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	todo	codex	markitect	high	9	2026-05-05	2026-05-05	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.

S9.1 - Implement versioned FastAPI service skeleton and health contracts

id: KONT-WP-0009-T001
status: todo
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.

S9.2 - Expose asset metadata relationship audit and policy APIs

id: KONT-WP-0009-T002
status: todo
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.

S9.3 - Expose ingestion retrieval transformation and workflow APIs

id: KONT-WP-0009-T003
status: todo
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.

S9.4 - Implement actor context delegation and authorization middleware

id: KONT-WP-0009-T004
status: todo
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.

S9.5 - Implement bounded agent operation catalog

id: KONT-WP-0009-T005
status: todo
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.

S9.6 - Implement context package API with policy constraints

id: KONT-WP-0009-T006
status: todo
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.

S9.7 - Implement dry-run review-gate and contract-test coverage

id: KONT-WP-0009-T007
status: todo
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.

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.