--- 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.