generated from coulomb/repo-seed
285 lines
10 KiB
Markdown
285 lines
10 KiB
Markdown
---
|
|
id: KONT-WP-0009
|
|
type: workplan
|
|
title: "Service API And Agent-Safe Operation"
|
|
domain: markitect
|
|
repo: kontextual-engine
|
|
status: completed
|
|
owner: codex
|
|
topic_slug: markitect
|
|
planning_priority: high
|
|
planning_order: 9
|
|
created: "2026-05-05"
|
|
updated: "2026-05-06"
|
|
state_hub_workstream_id: "6e672b1a-2e57-489e-8516-cb75611d4354"
|
|
---
|
|
|
|
# KONT-WP-0009: Service API And Agent-Safe Operation
|
|
|
|
## Purpose
|
|
|
|
Expose the engine through versioned service APIs and explicit agent-safe
|
|
operations. This workplan turns the programmatic contracts into a headless
|
|
service surface for assets, metadata, relationships, ingestion, retrieval,
|
|
transformations, workflows, permissions, audit, context packages, and bounded
|
|
agent actions.
|
|
|
|
## Requirement Coverage
|
|
|
|
Primary: FR-160 to FR-169 and FR-180 to FR-188.
|
|
|
|
Supporting: FR-060 to FR-066, FR-080 to FR-085, FR-100 to FR-106,
|
|
FR-120 to FR-126, FR-200 to FR-202, FR-240 to FR-245.
|
|
|
|
## Architecture Constraint
|
|
|
|
Implement the service API as an adapter over application services, following
|
|
`docs/architecture-blueprint.md`. HTTP routes must not own domain behavior.
|
|
Agent operations must use the bounded operation catalog, policy checks, audit
|
|
events, dry-run behavior, and review gates described in the blueprint.
|
|
|
|
## markitect-tool Boundary Remark
|
|
|
|
Service and agent APIs may expose engine operations that internally use
|
|
Markitect for markdown-backed context packages, selectors, validation, and
|
|
deterministic markdown operations. They must not expose the `mkt` CLI as the
|
|
engine control plane or let agents bypass engine policy, audit, lifecycle, and
|
|
review gates through Markitect APIs.
|
|
|
|
## Implementation Status
|
|
|
|
The optional FastAPI service skeleton is implemented for health, readiness,
|
|
version, OpenAPI contracts, asset/metadata/relationship/audit/policy resources,
|
|
ingestion jobs, governed retrieval, transformations, and workflow resources.
|
|
See
|
|
`docs/service-api-implementation.md`.
|
|
|
|
All MVP tasks in this workplan are implemented.
|
|
|
|
## S9.1 - Implement versioned FastAPI service skeleton and health contracts
|
|
|
|
```task
|
|
id: KONT-WP-0009-T001
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "bdb2380e-4ea1-4b8c-a6c9-fc8da2122813"
|
|
```
|
|
|
|
Add the first optional FastAPI service layer while keeping core behavior in
|
|
programmatic contracts.
|
|
|
|
Acceptance:
|
|
|
|
- Service startup, health, readiness, version, and OpenAPI output are tested.
|
|
- Service code wraps core contracts rather than becoming the architecture.
|
|
- API versioning policy is documented for MVP.
|
|
|
|
Implemented:
|
|
|
|
- `kontextual_engine.api.create_app()` creates an optional FastAPI adapter.
|
|
- `ServiceRuntime` provides health, readiness, and version payloads without
|
|
requiring FastAPI at import time.
|
|
- Operational probes are exposed at `/health`, `/ready`, and `/version`; MVP
|
|
versioned aliases are exposed under `/api/v1`.
|
|
- API versioning policy is documented in `docs/service-api-boundary.md`.
|
|
|
|
## S9.2 - Expose asset metadata relationship audit and policy APIs
|
|
|
|
```task
|
|
id: KONT-WP-0009-T002
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "a37e5ba3-e128-4100-b22c-c85cca3f8db3"
|
|
```
|
|
|
|
Expose service APIs for asset lifecycle, metadata, classifications,
|
|
relationships, policies, permissions, lifecycle state, and audit events.
|
|
|
|
Acceptance:
|
|
|
|
- Core asset operations are available without a CLI or UI.
|
|
- Permission and policy checks run before protected operations.
|
|
- Audit history can be queried by authorized callers.
|
|
|
|
Implemented:
|
|
|
|
- `ServiceRuntime` exposes asset create/list/get, metadata add/list,
|
|
lifecycle transition, relationship create/list, audit query, and policy
|
|
evaluation operations over existing service contracts.
|
|
- FastAPI routes under `/api/v1` wrap those runtime operations without owning
|
|
domain behavior.
|
|
- Policy denial blocks protected asset mutations and denied attempts remain
|
|
auditable.
|
|
|
|
## S9.3 - Expose ingestion retrieval transformation and workflow APIs
|
|
|
|
```task
|
|
id: KONT-WP-0009-T003
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "7271b26d-0dbb-4eca-9140-a7729ad296e4"
|
|
```
|
|
|
|
Expose APIs for ingestion jobs, query/retrieval, transformations, derived
|
|
artifacts, workflow templates, workflow runs, and job recovery actions.
|
|
|
|
Acceptance:
|
|
|
|
- Jobs return IDs, state, outputs, failures, retry options, and correlation
|
|
IDs.
|
|
- Retrieval results are permission-aware and source-grounded.
|
|
- Transformations and workflows expose lineage and audit references.
|
|
|
|
Implemented:
|
|
|
|
- `ServiceRuntime` exposes ingestion capabilities and ingestion job start/list/get
|
|
over `AssetIngestionService`.
|
|
- Governed retrieval endpoints wrap `AssetRetrievalService` for asset, context
|
|
entity, relationship, feedback, index refresh, and quality metric contracts.
|
|
- Transformation operations and runs are exposed with retry/cancel hints,
|
|
lineage, output assets, audit references, and policy decisions.
|
|
- Workflow templates, queued/invoked runs, run recovery, review decisions,
|
|
review queues, exception queues, and reconstruction are exposed over
|
|
`WorkflowService`.
|
|
- Runtime tests cover completed and failed ingestion jobs, source-grounded
|
|
retrieval, transformation lineage/audit, and workflow reconstruction.
|
|
|
|
## S9.4 - Implement actor context delegation and authorization middleware
|
|
|
|
```task
|
|
id: KONT-WP-0009-T004
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "7becdec7-ddbb-497f-b762-77043e16046e"
|
|
```
|
|
|
|
Implement request-level actor context for human users, applications,
|
|
automation, service accounts, delegated users, and AI agents.
|
|
|
|
Acceptance:
|
|
|
|
- Every material service operation has actor context.
|
|
- Delegation and agent identity are represented explicitly.
|
|
- Authorization failures do not leak protected content in errors or result
|
|
shapes.
|
|
|
|
Implemented:
|
|
|
|
- `ServiceRuntime.operation_context()` now supports actor external refs,
|
|
groups, delegated actors, request scope, policy scope, and AI-agent metadata.
|
|
- FastAPI request context parsing accepts actor, delegated actor, agent, group,
|
|
request-scope, and policy-scope headers.
|
|
- `GET /api/v1/context` exposes the resolved operation context for integration
|
|
checks and client diagnostics.
|
|
- FastAPI exception handlers preserve structured errors from dependencies.
|
|
- HTTP authorization error payloads redact protected resource metadata from
|
|
policy-decision context.
|
|
|
|
## S9.5 - Implement bounded agent operation catalog
|
|
|
|
```task
|
|
id: KONT-WP-0009-T005
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "fc9e1def-229c-4224-8fd3-6fd4f9785c27"
|
|
```
|
|
|
|
Define and expose explicit agent operations for inspect, search, retrieve,
|
|
assemble context, enrich metadata, classify, transform, invoke workflow, submit
|
|
review, and report result.
|
|
|
|
Acceptance:
|
|
|
|
- Agents can only act through documented operations.
|
|
- Each operation declares inputs, outputs, permission requirements, audit
|
|
behavior, and failure modes.
|
|
- Agent operations are auditable separately from human and deterministic
|
|
automation actions.
|
|
|
|
Implemented:
|
|
|
|
- Added a bounded agent operation catalog for inspect, retrieve, search,
|
|
assemble-context preview, metadata enrichment, classification request,
|
|
transformation, workflow invocation, review submission, and result reporting.
|
|
- Added `GET /api/v1/agents/operations`, `GET /api/v1/agents/operations/{id}`,
|
|
and `POST /api/v1/agents/operations/{id}`.
|
|
- Agent operation execution authorizes `agent.operation.*`, emits separate
|
|
agent-operation audit events, supports generic dry-run envelopes, and
|
|
dispatches through existing runtime methods.
|
|
- Unsupported operation IDs fail with structured validation errors rather than
|
|
opening arbitrary command or internal-service access.
|
|
|
|
## S9.6 - Implement context package API with policy constraints
|
|
|
|
```task
|
|
id: KONT-WP-0009-T006
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "9ff1d345-d0a1-46eb-ae9a-f6beba2fa5e9"
|
|
```
|
|
|
|
Provide bounded context packages containing selected assets, snippets,
|
|
metadata, relationships, provenance, task instructions, and policy constraints.
|
|
|
|
Acceptance:
|
|
|
|
- Context packages do not require unrestricted repository access.
|
|
- Package contents are source-grounded and permission filtered.
|
|
- External memory references remain opaque and respect
|
|
`docs/phase-memory-boundary.md`.
|
|
- Markdown-backed packages can interoperate with Markitect context-package
|
|
payloads while remaining wrapped in engine permission and audit contracts.
|
|
|
|
Implemented:
|
|
|
|
- Added `GET /api/v1/context-packages/schema` and
|
|
`POST /api/v1/context-packages`.
|
|
- Context packages are assembled from permission-filtered retrieval results and
|
|
include source refs, snippets, metadata, relationships, representation
|
|
provenance, policy constraints, audit references, and policy decisions.
|
|
- External memory refs are represented as opaque pointers and do not embed
|
|
memory graph content.
|
|
- The `markitect` format emits a Markitect-compatible envelope while keeping
|
|
markdown rendering, selector semantics, and validation delegated to
|
|
`markitect-tool`.
|
|
|
|
## S9.7 - Implement dry-run review-gate and contract-test coverage
|
|
|
|
```task
|
|
id: KONT-WP-0009-T007
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "bbbdec75-d3c0-4367-b073-ef9c5dffa2b7"
|
|
```
|
|
|
|
Add dry-run and review-gate behavior for destructive, sensitive, externally
|
|
published, or high-impact service and agent operations.
|
|
|
|
Acceptance:
|
|
|
|
- Risky actions can be denied, dry-run, or routed to review.
|
|
- Contract tests cover API errors, authorization failures, review-required
|
|
responses, and partial failures.
|
|
- OpenAPI output remains stable for implemented endpoints.
|
|
|
|
Implemented:
|
|
|
|
- Agent operation policy decisions with `require_review` now return structured
|
|
`review_required` envelopes and audit `review_required` outcomes.
|
|
- Agent operation policy decisions with `dry_run_only` now return
|
|
`dry_run_required` envelopes unless the request is already a dry run.
|
|
- Generic agent dry-run requests audit with `dry_run` outcomes and avoid domain
|
|
mutation.
|
|
- Contract tests cover redacted authorization failures, review-required
|
|
responses, dry-run-required responses, partial ingestion failures, and OpenAPI
|
|
stability for implemented endpoint groups.
|
|
|
|
## Definition Of Done
|
|
|
|
- The service API exposes the MVP operation surface without requiring UI.
|
|
- Agent-safe operations are explicit, bounded, permissioned, auditable, and
|
|
reviewable.
|
|
- API routes remain adapters over the core contracts described in
|
|
`docs/architecture-blueprint.md`.
|
|
- `python3 -m pytest` passes.
|