kontextual-engine/workplans/KONT-WP-0009-service-api-agent-safe-operation.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
KONT-WP-0009	workplan	Service API And Agent-Safe Operation	markitect	kontextual-engine	completed	codex	markitect	high	9	2026-05-05	2026-05-06	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

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

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

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

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

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

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

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.