From 2590b0cf8a1383a002eb277eb01c4764ed90b446 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 3 Aug 2026 10:54:53 +0000 Subject: [PATCH] feat: bring FuzeAgent to the platform's 4-pod standard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FuzeAgent already deployed a backend (orchestrator), a frontend (ui) and the family's A2A server. What it had NO contract for was the API that dispatches autonomous agents — which is exactly the API where an unclassified tool surface is dangerous. This adds that contract, serves it, and adds the config-driven MCP gateway pod configured from it. contracts/openapi.yaml — NEW 123 paths / 142 operations, extracted statically (ast, no imports) from every @app. decorator in services/orchestrator/main.py. Summaries are the handlers' own docstrings. Nothing invented. FINDING — seven duplicate (path, method) registrations. FastAPI keeps the FIRST and the later handler never runs. Two of them are not redundant definitions but DIFFERENT implementations that are dead code: register_agent_capabilities (shadowed by register_agent) and get_agent_tasks_list (shadowed by get_agent_tasks). All seven are tabulated in contracts/README.md. FINDING — the contract covers ONE of FuzeAgent's two backends. services/ hierarchy_API is a second FastAPI app on its own Service (port 8006) with ~40 routes. One OpenAPI document maps to one upstream base URL, so it needs its own contract and its own gateway pod; until then those operations are not on the MCP surface. Said plainly rather than reported as four green pods. The contract is SERVED, not just committed GET /openapi.yaml is new in main.py, reading the copy baked into the image. This is NOT /openapi.json: FastAPI generates that from the code and it says nothing about which operations dispatch an agent that cannot be recalled. Both are served; the curated one is the contract. A missing document is DEGRADED, not fatal — /health keeps returning 200 and gains `"openapi": "loaded" | "unavailable"`, and the endpoint answers 503. MCP pod — and why it is NOT the same as the mcpServer already deployed The chart already runs mcp-servers/fuzeagent-server: a hand-written MCP SSE server with ~15 curated tools and, per .fuze/manifest.json's own note, NO mutates classification at all. The new pod runs @fuzefront/mcp-gateway over contracts/openapi.yaml, which derives the classification mechanically and refuses to boot on a contradictory one. Both are left in place; whether to retire the hand-written one is an owner call, flagged not silently resolved. VERIFIED, not asserted: the real gateway was booted from the exact ConfigMap bytes `helm template` renders. 142 tools enumerate, 74 reads / 68 writes, 16 irreversible, no tool is both a read and irreversible, and startTaskExecution reaches the model prefixed "[WRITE — IRREVERSIBLE]". IRREVERSIBLE (16) — classified on EFFECT, never on verb: dispatch / execute (POST, defaults to reversible — overridden): startTaskExecution, initiateTaskCoordination, executeCommandInSandbox, executeContainerCommand, sendClaudeSessionInput, sendAgentCommunication, sendMessageToAgent, submitHumanResponse, deployMemoryEnabledAgent creates something this API cannot remove: createAgent, createAgentFromTemplate, assignTask, storeProviderCredentials (there is NO DELETE /agents/{id} and NO DELETE /tasks/{id} in the contract) DELETE default, left as-is: deleteAgentDocument, deleteOrganizationDocument, deleteTeamDocument Deliberately NOT irreversible, with reasons in the overrides: approveFileOperations writes files, but the contract contains the exact compensating operation (.../rollback) plus a preview stopMemoryEnabledAgent a DELETE that stops an agent which can be redeployed removeAgentContainer / destroySandbox re-creatable runtime artefacts cancelTaskExecution pinned reversible ONLY so nobody reads it as the undo for startTaskExecution. IT IS NOT. POST /rag/search is already a read via the gateway's suffix allowlist (verified: mutates=false), so it needs no entry. POST /mcp/call-tool keeps the default and is flagged: it is a passthrough whose reversibility belongs to the downstream tool and is not derivable from this contract. Slug: fuzeagent -> agent, FuzeAgent -> Agent. DECLARATION ONLY; `slug` is immutable and the live migration is owned elsewhere. No A2A pod is added: A2A is one shared multi-tenant server and this repo IS its home. deploy/argocd/README.md records the evidence that a2a-shared is wired for deployment (Application on main, enabled:true, pinned image, Service named a2a-shared:8080 matching the card's hardcoded URL, three tenants enabled) and is explicit that a running healthy pod could NOT be verified without cluster access. No Argo Application added, edited or removed — FuzeInfra owns those. No auth wiring touched (services/orchestrator/fuze_security.py, auth.py and the whole a2a-shared chart are untouched, leaving claude/fuze-security-migration clean). Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01GaPa3JgrVNtWrGvqQEAEqv --- contracts/README.md | 94 + contracts/openapi.yaml | 5649 +++++++++++++++++ deploy/argocd/README.md | 104 + deploy/helm/fuzeagent/files/openapi.yaml | 5649 +++++++++++++++++ .../helm/fuzeagent/files/tools.overrides.yaml | 258 + .../helm/fuzeagent/templates/mcp-gateway.yaml | 123 + .../fuzeagent/templates/orchestrator.yaml | 8 + deploy/helm/fuzeagent/values.yaml | 50 + mcp/tools.overrides.yaml | 258 + registration/manifest.json | 4 +- scripts/check-rendered-chart.py | 67 + scripts/sync-chart-files.sh | 59 + services/orchestrator/contracts/openapi.yaml | 5649 +++++++++++++++++ services/orchestrator/main.py | 73 +- 14 files changed, 18042 insertions(+), 3 deletions(-) create mode 100644 contracts/README.md create mode 100644 contracts/openapi.yaml create mode 100644 deploy/argocd/README.md create mode 100644 deploy/helm/fuzeagent/files/openapi.yaml create mode 100644 deploy/helm/fuzeagent/files/tools.overrides.yaml create mode 100644 deploy/helm/fuzeagent/templates/mcp-gateway.yaml create mode 100644 mcp/tools.overrides.yaml create mode 100755 scripts/check-rendered-chart.py create mode 100755 scripts/sync-chart-files.sh create mode 100644 services/orchestrator/contracts/openapi.yaml diff --git a/contracts/README.md b/contracts/README.md new file mode 100644 index 0000000..9e06799 --- /dev/null +++ b/contracts/README.md @@ -0,0 +1,94 @@ +# FuzeAgent contracts + +## `openapi.yaml` — the orchestrator API, as deployed + +`contracts/openapi.yaml` describes the HTTP surface of +`services/orchestrator/main.py`: the FastAPI application the Helm chart deploys +as the `orchestrator` pod on port 8000, reachable in-cluster at +`http://orchestrator:8000`. 123 paths / 142 operations, every one extracted +statically from an `@app.` decorator; summaries are the handlers' own +docstrings. + +It is served live at `GET /openapi.yaml`, and it is what the MCP gateway pod is +configured with. + +### `/openapi.yaml` is not `/openapi.json` + +FastAPI already serves `/openapi.json`, generated from the code at import time. +That document is accurate about shapes and **says nothing about which operations +dispatch an agent that cannot be recalled**. Both are served. The curated one — +this file, plus the classification `mcp/tools.overrides.yaml` narrows — is the +contract. + +## Read this before calling anything + +FuzeAgent is not a CRUD API with a dangerous corner. Its purpose is to +**dispatch agents that take real actions**: they write files, run shell commands +in containers, call third-party APIs and spend money on model inference. +`POST /tasks/{task_id}/execute` returns in milliseconds, and by then an agent is +running. `POST /tasks/{task_id}/cancel` stops *future* work; it undoes nothing. + +Two structural facts follow from reading the whole contract: + +1. There is **no `DELETE /agents/{agent_id}`** and **no `DELETE /tasks/{task_id}`**. + A created agent and a created task are permanent as far as this API goes. +2. The **only genuine undo** anywhere in the contract is + `POST /tasks/{task_id}/file-operations/{batch_id}/rollback`, and it undoes an + approved *file batch* and nothing else. + +`mcp/tools.overrides.yaml` marks 16 operations irreversible on that basis — +classified on effect, never on verb. Notably `approveFileOperations` is marked +**reversible** despite writing files, because the rollback above is a real +compensating operation; and `stopMemoryEnabledAgent` is marked **reversible** +despite being a `DELETE`, because it stops an agent that can be deployed again. + +## Known gaps + +1. **The `hierarchy-api` backend is not covered.** `services/hierarchy_API` + (the `hierarchy-api` pod, port 8006) is a second FastAPI application with + roughly forty of its own routes for organizations, teams and agent hierarchy. + One OpenAPI document maps to one upstream base URL, so covering it needs its + own contract and its own gateway pod. Until then those operations are not on + the MCP surface. + +2. **Seven duplicate route registrations.** FastAPI keeps the FIRST handler for + a `(path, method)` pair; the later one is dead code. The contract mirrors + that, and the shadowed handlers are: + + | Route | Serving | Dead | + |---|---|---| + | `POST /agents/{agent_id}/register` | `register_agent` | `register_agent_capabilities` | + | `POST /agents/{agent_id}/error` | `report_agent_error` | `report_agent_error` (defined twice) | + | `GET /knowledge/search` | `search_knowledge` | `search_knowledge` (defined twice) | + | `GET /teams` | `list_teams` | `get_teams` | + | `GET /organizations/{organization_id}/goals` | `list_organization_goals` | `get_organization_goals` | + | `GET /goals/{goal_id}` | `get_goal` | `get_goal_details` | + | `GET /agents/{agent_id}/tasks` | `get_agent_tasks` | `get_agent_tasks_list` | + + `register_agent_capabilities` and `get_agent_tasks_list` are the ones worth a + look: they are not duplicate definitions of the same thing, they are + *different implementations* that never run. + +3. **`POST /mcp/call-tool` is a passthrough of unknowable reversibility.** It + invokes a tool on whatever MCP server an agent has configured, so whether the + effect can be undone is a property of the downstream tool and is not + derivable from this contract. It keeps the default reversible-write + classification, which is the least-wrong available claim. + +## Keeping the copies honest + +The contract exists three times, for reasons Docker and Helm force: + +| Copy | Why | +|---|---| +| `contracts/openapi.yaml` | the source of truth | +| `services/orchestrator/contracts/openapi.yaml` | the image is built with `context: services/orchestrator`, so the repo-root tree is not in the build context; this copy ships in the image and is what `GET /openapi.yaml` serves | +| `deploy/helm/fuzeagent/files/openapi.yaml` | Helm can only read files inside the chart directory; this is what the MCP gateway pod mounts | + +```bash +scripts/sync-chart-files.sh # refresh the copies +scripts/sync-chart-files.sh --check # fail if they drifted (for CI) +``` + +A stale overrides copy is the dangerous one here: it would present +`startTaskExecution` to a model as an ordinary reversible write. diff --git a/contracts/openapi.yaml b/contracts/openapi.yaml new file mode 100644 index 0000000..7881015 --- /dev/null +++ b/contracts/openapi.yaml @@ -0,0 +1,5649 @@ +openapi: 3.1.0 +info: + title: FuzeAgent Orchestrator API + version: 0.1.0 + summary: The HTTP surface the deployed FuzeAgent orchestrator actually serves. + description: >- + FuzeAgent orchestrates autonomous AI agents: it creates agents, assigns them tasks, + EXECUTES those tasks in containers and sandboxes, brokers agent-to-agent + communication, and manages the knowledge and goal state behind all of it. + + + WHAT THIS DOCUMENT IS. It describes the routes served by + `services/orchestrator/main.py` — the FastAPI application the Helm chart deploys as + the `orchestrator` pod on port 8000, reachable in-cluster at + http://orchestrator:8000. Every path was read off an `@app.` decorator by + static analysis; the summaries are the handlers' own docstrings. Nothing here is + aspirational. + + + THE ONE THING TO UNDERSTAND BEFORE CALLING ANYTHING. FuzeAgent is not a CRUD API + with a dangerous corner. Its core purpose is to DISPATCH AGENTS THAT TAKE REAL + ACTIONS — they write files, run shell commands in containers, call third-party + APIs and spend money on model inference. `POST /tasks/{task_id}/execute` is the + canonical case: it returns quickly, and by the time it has, an agent is running. + Cancelling it stops future work; it does not undo work already done. Operations of + that shape are marked irreversible in `mcp/tools.overrides.yaml` regardless of + their HTTP verb, because the verb says nothing about whether the effect can be + taken back. + + + WHAT IT IS NOT. FuzeAgent deploys a SECOND backend, `services/hierarchy_API` + (the `hierarchy-api` pod, port 8006), with roughly forty of its own routes for + organizations, teams and agent hierarchy. It is a separate FastAPI application on + a separate Service and is NOT covered by this document; a single OpenAPI document + maps to a single upstream base URL, so it would need its own contract and its own + gateway pod. See `contracts/README.md`. + + + AUTHENTICATION. Bearer token, resolved through the FuzeFront Security API when + `SECURITY_BASE_URL` is configured (`services/orchestrator/fuze_security.py`), with + a local JWT fallback otherwise. `main:app` fails closed at boot without either. + contact: + name: FuzeAgent + url: https://github.com/izzywdev/FuzeAgent + license: + name: UNLICENSED +servers: + - url: / + description: >- + The orchestrator serves absolute paths with no common prefix, so the base URL + carries no path segment. In-cluster: http://orchestrator:8000. +tags: + - name: Platform + description: Health, websocket stats and system dashboards. + - name: Agents + description: Creating, inspecting and configuring agents. + - name: Tasks + description: >- + Assigning and EXECUTING work. The operations here are the ones that make an + agent act on the world. + - name: Containers + description: Per-agent container lifecycle and in-container command execution. + - name: Sandboxes + description: Sandbox lifecycle and arbitrary command execution inside one. + - name: Coordination + description: Multi-agent coordination sessions and agent-to-agent messaging. + - name: Conversations + description: Agent conversations and the derived artefacts (milestones, action items). + - name: Goals + description: Organizational goals, milestones and progress tracking. + - name: Knowledge + description: Documents, RAG index and knowledge analytics. + - name: Context + description: Agent interaction context. + - name: MCP passthrough + description: >- + The orchestrator's own MCP client surface — listing and calling tools of MCP + servers the AGENTS use. Not to be confused with FuzeAgent's MCP gateway pod, + which exposes THIS API as MCP tools. + - name: Organizations + description: Organization-scoped model, provider and dashboard configuration. +paths: + "/health": + get: + operationId: healthCheck + tags: ["Platform"] + summary: "Health Check" + description: + |- + Health check endpoint that returns the current status of the orchestrator service. + + Returns: + dict: Service health status and basic information + security: [] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents": + post: + operationId: createAgent + tags: ["Agents"] + summary: "Create AI Agent" + description: + |- + Create a new AI agent with repository and sandbox settings + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "AgentCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listAgents + tags: ["Agents"] + summary: "List All Agents" + description: + |- + List all agents and their status + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/tasks": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: assignTask + tags: ["Tasks"] + summary: "Assign Task to Agent" + description: + |- + Assign a task to an agent + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "TaskCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: getAgentTasks + tags: ["Tasks"] + summary: "Get tasks assigned to an agent" + description: + |- + Get tasks assigned to an agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/status": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentStatus + tags: ["Agents"] + summary: "Get detailed agent status" + description: + |- + Get detailed agent status + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/teams": + get: + operationId: listTeams + tags: ["Platform"] + summary: "List all teams" + description: + |- + List all teams + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agent-templates": + get: + operationId: listAgentTemplates + tags: ["Agents"] + summary: "List available agent templates" + description: + |- + List available agent templates + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks": + get: + operationId: listTasks + tags: ["Tasks"] + summary: "List all tasks" + description: + |- + List all tasks + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTask + tags: ["Tasks"] + summary: "Get task details" + description: + |- + Get task details + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateTask + tags: ["Tasks"] + summary: "Update task status and result" + description: + |- + Update task status and result + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/from-template": + post: + operationId: createAgentFromTemplate + tags: ["Agents"] + summary: "Create agent from template with repository settings" + description: + |- + Create agent from template with repository settings + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/templates": + get: + operationId: getAgentTemplates + tags: ["Agents"] + summary: "Get available agent templates" + description: + |- + Get available agent templates + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/execute": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: startTaskExecution + tags: ["Tasks"] + summary: "Start Autonomous Task Execution" + description: + |- + Start autonomous execution of a task + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/status": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskExecutionStatus + tags: ["Tasks"] + summary: "Get detailed task execution status" + description: + |- + Get detailed task execution status + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateTaskStatus + tags: ["Tasks"] + summary: "Update Task Status" + description: + |- + Update task status - used by memory-enabled agents to report progress + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/iterations": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskIterations + tags: ["Tasks"] + summary: "Get task iteration history" + description: + |- + Get task iteration history + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/sandbox": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentSandbox + tags: ["Agents"] + summary: "Get agent sandbox information" + description: + |- + Get agent sandbox information + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/context/interactions": + post: + operationId: storeInteraction + tags: ["Context"] + summary: "Store agent interaction" + description: + |- + Store agent interaction + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/context": + get: + operationId: getContext + tags: ["Context"] + summary: "Get relevant context for a query" + description: + |- + Get relevant context for a query + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/memory": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentMemory + tags: ["Agents"] + summary: "Get agent memory" + description: + |- + Get agent memory + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + delete: + operationId: stopMemoryEnabledAgent + tags: ["Agents"] + summary: "Stop Memory-Enabled Agent" + description: + |- + Stop and clean up a memory-enabled agent container + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/conversations": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentConversations + tags: ["Conversations"] + summary: "Get Agent Conversations" + description: + |- + Get all conversations for a specific agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + post: + operationId: createAgentConversation + tags: ["Conversations"] + summary: "Create New Agent Conversation" + description: + |- + Create a new conversation with an agent + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ConversationCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/conversations/{conversation_id}/messages": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + get: + operationId: getConversationMessages + tags: ["Conversations"] + summary: "Get Conversation Messages" + description: + |- + Get all messages in a conversation + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + post: + operationId: sendMessageToAgent + tags: ["Conversations"] + summary: "Send Message to Agent" + description: + |- + Send a message to an agent in a conversation + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ChatMessageRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/search": + get: + operationId: searchKnowledge + tags: ["Knowledge"] + summary: "Search knowledge base" + description: + |- + Search knowledge base + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/human-response": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: submitHumanResponse + tags: ["Tasks"] + summary: "Submit Human Response" + description: + |- + Submit human response to a task question + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "HumanResponseRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/cancel": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: cancelTaskExecution + tags: ["Tasks"] + summary: "Cancel autonomous execution of a task" + description: + |- + Cancel autonomous execution of a task + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/messages": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskMessages + tags: ["Tasks"] + summary: "Get task messages and chat history" + description: + |- + Get task messages and chat history + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/sandboxes": + get: + operationId: listSandboxes + tags: ["Sandboxes"] + summary: "List active sandboxes" + description: + |- + List active sandboxes + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/sandboxes/{sandbox_id}/execute": + parameters: + - name: sandbox_id + in: path + required: true + description: "Sandbox id." + schema: { type: string } + post: + operationId: executeCommandInSandbox + tags: ["Sandboxes"] + summary: "Execute a command in a sandbox" + description: + |- + Execute a command in a sandbox + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/sandboxes/{sandbox_id}": + parameters: + - name: sandbox_id + in: path + required: true + description: "Sandbox id." + schema: { type: string } + delete: + operationId: destroySandbox + tags: ["Sandboxes"] + summary: "Destroy a sandbox" + description: + |- + Destroy a sandbox + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/register": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: registerAgent + tags: ["Agents"] + summary: "Register an agent running in a sandbox container" + description: + |- + Register an agent running in a sandbox container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/next-task": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getNextTaskForAgent + tags: ["Agents"] + summary: "Get the next task for an agent to execute" + description: + |- + Get the next task for an agent to execute + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/error": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: reportAgentError + tags: ["Agents"] + summary: "Report an error from an agent" + description: + |- + Report an error from an agent + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/conversation": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskConversation + tags: ["Tasks"] + summary: "Get conversation history for a task" + description: + |- + Get conversation history for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/conversation/summary": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getConversationSummary + tags: ["Tasks"] + summary: "Get conversation summary with statistics" + description: + |- + Get conversation summary with statistics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/code-generations": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskCodeGenerations + tags: ["Tasks"] + summary: "Get code generations for a task" + description: + |- + Get code generations for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/performance": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentPerformance + tags: ["Agents"] + summary: "Get agent performance metrics" + description: + |- + Get agent performance metrics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/file-operations": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskFileOperations + tags: ["Tasks"] + summary: "Get File Operations" + description: + |- + Get file operations for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/file-operations/{batch_id}/preview": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + - name: batch_id + in: path + required: true + description: "Batch id." + schema: { type: string } + get: + operationId: getFileOperationsPreview + tags: ["Tasks"] + summary: "Get preview of file changes for a batch" + description: + |- + Get preview of file changes for a batch + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/file-operations/{batch_id}/approve": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + - name: batch_id + in: path + required: true + description: "Batch id." + schema: { type: string } + post: + operationId: approveFileOperations + tags: ["Tasks"] + summary: "Approve File Operations" + description: + |- + Approve or reject file operations + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "FileOperationApprovalRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/file-operations/{batch_id}/rollback": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + - name: batch_id + in: path + required: true + description: "Batch id." + schema: { type: string } + post: + operationId: rollbackFileOperations + tags: ["Tasks"] + summary: "Rollback applied file operations" + description: + |- + Rollback applied file operations + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/claude-session": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getClaudeSessionStatus + tags: ["Tasks"] + summary: "Get Claude SDK session status for a task" + description: + |- + Get Claude SDK session status for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/claude-session/input": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: sendClaudeSessionInput + tags: ["Tasks"] + summary: "Send input to Claude SDK session" + description: + |- + Send input to Claude SDK session + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/mcp/tools": + get: + operationId: getMcpTools + tags: ["MCP passthrough"] + summary: "Get available MCP tools" + description: + |- + Get available MCP tools + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/mcp/call-tool": + post: + operationId: callMcpTool + tags: ["MCP passthrough"] + summary: "Call MCP Tool" + description: + |- + Call an MCP tool + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "MCPToolRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/mcp/resources": + get: + operationId: getMcpResources + tags: ["MCP passthrough"] + summary: "Get available MCP resources" + description: + |- + Get available MCP resources + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/mcp/resource": + get: + operationId: getMcpResource + tags: ["MCP passthrough"] + summary: "Get an MCP resource by URI" + description: + |- + Get an MCP resource by URI + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/mcp-context": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskMcpContext + tags: ["Tasks"] + summary: "Get MCP context for a task" + description: + |- + Get MCP context for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/mcp-setup": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: setupAgentMcp + tags: ["Agents"] + summary: "Setup Agent MCP Integration" + description: + |- + Set up MCP integration for an agent + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "AgentMCPSetupRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/coordinate": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: initiateTaskCoordination + tags: ["Tasks"] + summary: "Initiate Multi-Agent Coordination" + description: + |- + Initiate multi-agent coordination for a complex task + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "CoordinationRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/coordination/{session_id}": + parameters: + - name: session_id + in: path + required: true + description: "Session id." + schema: { type: string } + get: + operationId: getCoordinationStatus + tags: ["Coordination"] + summary: "Get status of a coordination session" + description: + |- + Get status of a coordination session + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/coordination/{session_id}/cancel": + parameters: + - name: session_id + in: path + required: true + description: "Session id." + schema: { type: string } + post: + operationId: cancelCoordination + tags: ["Coordination"] + summary: "Cancel a coordination session" + description: + |- + Cancel a coordination session + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{from_agent_id}/communicate/{to_agent_id}": + parameters: + - name: from_agent_id + in: path + required: true + description: "From agent id." + schema: { type: string } + - name: to_agent_id + in: path + required: true + description: "To agent id." + schema: { type: string } + post: + operationId: sendAgentCommunication + tags: ["Agents"] + summary: "Send communication between agents" + description: + |- + Send communication between agents + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/coordination/active": + get: + operationId: getActiveCoordinations + tags: ["Coordination"] + summary: "Get all active coordination sessions" + description: + |- + Get all active coordination sessions + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/providers/{provider}/credentials": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + - name: provider + in: path + required: true + description: "Provider." + schema: { type: string } + post: + operationId: storeProviderCredentials + tags: ["Organizations"] + summary: "Store Provider API Credentials" + description: + |- + Store encrypted API credentials for a model provider at organization level + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ProviderCredentialsRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/models": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getAvailableModels + tags: ["Organizations"] + summary: "Get Available Models" + description: + |- + Get available AI models with provider credential validation + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/model-configuration": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: configureAgentModel + tags: ["Agents"] + summary: "Configure Agent Model Settings" + description: + |- + Configure model settings for an AI agent + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "AgentModelConfigRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: getAgentModelConfiguration + tags: ["Agents"] + summary: "Get Agent Model Configuration" + description: + |- + Get model configuration for an AI agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/tasks/cost-estimate": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: estimateTaskCost + tags: ["Tasks"] + summary: "Estimate Task Cost" + description: + |- + Estimate cost for task execution based on agent's model configuration + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "TaskCostEstimateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/model-usage": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getOrganizationModelUsage + tags: ["Organizations"] + summary: "Get Model Usage Statistics" + description: + |- + Get model usage statistics and costs for an organization + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/model-recommendations": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getModelRecommendations + tags: ["Agents"] + summary: "Get Model Recommendations" + description: + |- + Get model recommendations based on task capabilities and cost constraints + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/notifications/{recipient_type}/{recipient_id}": + parameters: + - name: recipient_type + in: path + required: true + description: "Recipient type." + schema: { type: string } + - name: recipient_id + in: path + required: true + description: "Recipient id." + schema: { type: string } + get: + operationId: getKnowledgeNotifications + tags: ["Knowledge"] + summary: "Get Knowledge Notifications" + description: + |- + Get knowledge notifications for a recipient + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/notifications/{notification_id}/status": + parameters: + - name: notification_id + in: path + required: true + description: "Notification id." + schema: { type: string } + put: + operationId: updateNotificationStatus + tags: ["Knowledge"] + summary: "Update Notification Status" + description: + |- + Update notification status and optional action taken + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/notifications/statistics": + get: + operationId: getNotificationStatistics + tags: ["Knowledge"] + summary: "Get Notification Statistics" + description: + |- + Get notification statistics and analytics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/add": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + post: + operationId: addOrganizationalKnowledge + tags: ["Knowledge"] + summary: "Add Organizational Knowledge" + description: + |- + Add knowledge to organization-level knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/search": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: searchOrganizationalKnowledge + tags: ["Knowledge"] + summary: "Search Organizational Knowledge" + description: + |- + Search organization-level knowledge base + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/context-enhancement/{agent_id}": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getEnhancedContextForAgent + tags: ["Knowledge"] + summary: "Get Enhanced Context for Agent" + description: + |- + Get enhanced context with relevant knowledge for agent task execution + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/organizations/{organization_id}/insights": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getOrganizationalKnowledgeInsights + tags: ["Knowledge"] + summary: "Get Organizational Knowledge Insights" + description: + |- + Get comprehensive organizational knowledge insights and analytics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/organizations/{organization_id}/effectiveness": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: analyzeKnowledgeEffectiveness + tags: ["Knowledge"] + summary: "Analyze Knowledge Effectiveness" + description: + |- + Analyze effectiveness of knowledge items in the organization + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/agents/{agent_id}/profile": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentKnowledgeProfile + tags: ["Knowledge"] + summary: "Get Agent Knowledge Profile" + description: + |- + Get detailed knowledge profile for an agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/organizations/{organization_id}/optimization": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getKnowledgeOptimizationRecommendations + tags: ["Knowledge"] + summary: "Get Knowledge Optimization Recommendations" + description: + |- + Generate comprehensive knowledge optimization recommendations + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/organizations/{organization_id}/trends": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getKnowledgeTrendsAnalysis + tags: ["Knowledge"] + summary: "Get Knowledge Trends Analysis" + description: + |- + Get comprehensive knowledge trends analysis + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/deploy-memory": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: deployMemoryEnabledAgent + tags: ["Agents"] + summary: "Deploy Memory-Enabled Agent" + description: + |- + Deploy a memory-enabled autonomous agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/memory-status": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentMemoryStatus + tags: ["Agents"] + summary: "Get Agent Memory Status" + description: + |- + Get agent memory status, expertise metrics, and insights + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/memory-tasks": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: assignTaskToMemoryAgent + tags: ["Agents"] + summary: "Assign Task to Memory Agent" + description: + |- + Assign a task to a memory-enabled agent for autonomous execution + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/system/expertise-dashboard": + get: + operationId: getSystemExpertiseDashboard + tags: ["Platform"] + summary: "Get System Expertise Dashboard" + description: + |- + Get comprehensive dashboard of system expertise and memory analytics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/tasks/pending": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getPendingTasksForAgent + tags: ["Tasks"] + summary: "Get Pending Tasks for Agent" + description: + |- + Get pending tasks that a memory-enabled agent can pick up + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/statistics": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: updateAgentStatistics + tags: ["Agents"] + summary: "Agent Statistics Update" + description: + |- + Update agent statistics - used by memory-enabled agents for performance tracking + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/goals": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + post: + operationId: createGoal + tags: ["Goals"] + summary: "Create organizational goal" + description: + |- + Create a new organizational goal + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "GoalCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listOrganizationGoals + tags: ["Goals"] + summary: "List organization goals" + description: + |- + List goals for an organization + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + get: + operationId: getGoal + tags: ["Goals"] + summary: "Get goal details" + description: + |- + Get goal details + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/overview": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + get: + operationId: getGoalOverview + tags: ["Goals"] + summary: "Get goal overview" + description: + |- + Get comprehensive goal overview + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/progress": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + put: + operationId: updateGoalProgress + tags: ["Goals"] + summary: "Update goal progress" + description: + |- + Update goal progress + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "GoalUpdateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/milestones": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: createMilestone + tags: ["Goals"] + summary: "Create milestone" + description: + |- + Create milestone for goal + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "MilestoneCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/milestones/{milestone_id}/tasks": + parameters: + - name: milestone_id + in: path + required: true + description: "Milestone id." + schema: { type: string } + post: + operationId: createTaskFromMilestone + tags: ["Goals"] + summary: "Create task from milestone" + description: + |- + Create task from milestone + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "TaskFromMilestoneRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/generate-execution-plan": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: generateExecutionPlan + tags: ["Goals"] + summary: "Generate execution plan" + description: + |- + Generate execution plan with milestones and tasks + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/generate-monthly-milestones": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: generateMonthlyMilestones + tags: ["Goals"] + summary: "Generate monthly milestones" + description: + |- + Generate monthly milestones for goal + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/milestones/{milestone_id}/generate-weekly-tasks": + parameters: + - name: milestone_id + in: path + required: true + description: "Milestone id." + schema: { type: string } + post: + operationId: generateWeeklyTasks + tags: ["Goals"] + summary: "Generate weekly tasks" + description: + |- + Generate weekly tasks for milestone + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/generate-cross-functional-tasks": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: generateCrossFunctionalTasks + tags: ["Goals"] + summary: "Generate cross-functional tasks" + description: + |- + Generate cross-functional tasks for goal + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/conversations": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: createGoalConversation + tags: ["Goals"] + summary: "Create goal conversation" + description: + |- + Create goal conversation + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "GoalConversationCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: getGoalConversations + tags: ["Goals"] + summary: "Get goal conversations" + description: + |- + Get conversations for a goal + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + get: + operationId: getGoalConversation + tags: ["Conversations"] + summary: "Get goal conversation" + description: + |- + Get goal conversation + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}/messages": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + post: + operationId: addMessageToConversation + tags: ["Conversations"] + summary: "Add message to conversation" + description: + |- + Add message to conversation + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ConversationMessageRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}/generate-milestones": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + post: + operationId: generatePlanningMilestones + tags: ["Conversations"] + summary: "Generate milestones from conversation" + description: + |- + Generate planning milestones from conversation + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}/conduct-progress-review": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + post: + operationId: conductProgressReview + tags: ["Conversations"] + summary: "Conduct progress review" + description: + |- + Conduct progress review + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}/extract-action-items": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + post: + operationId: extractActionItems + tags: ["Conversations"] + summary: "Extract action items" + description: + |- + Extract action items from conversation + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/track-progress": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: recordProgressTracking + tags: ["Goals"] + summary: "Record progress tracking update" + description: + |- + Record progress tracking update + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ProgressUpdateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/deadline-risk": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + get: + operationId: assessDeadlineRisk + tags: ["Goals"] + summary: "Assess deadline risk" + description: + |- + Assess deadline risk for goal + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/progress-report": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + get: + operationId: generateProgressReport + tags: ["Goals"] + summary: "Generate progress report" + description: + |- + Generate progress report for goal + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/goals-dashboard": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getOrganizationGoalsDashboard + tags: ["Goals"] + summary: "Get organization goals dashboard" + description: + |- + Get organization goals dashboard + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/tracking-dashboard": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getTrackingDashboard + tags: ["Organizations"] + summary: "Get tracking dashboard" + description: + |- + Get organization tracking dashboard + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/documents": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + post: + operationId: uploadOrganizationDocument + tags: ["Knowledge"] + summary: "Upload Organizational Document" + description: + |- + Upload a document to organizational knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "UploadFile (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listOrganizationDocuments + tags: ["Knowledge"] + summary: "List Organizational Documents" + description: + |- + Get list of organizational documents + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/url": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + post: + operationId: addOrganizationUrl + tags: ["Knowledge"] + summary: "Add URL to Organizational Knowledge" + description: + |- + Add URL content to organizational knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/documents/{doc_id}": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getOrganizationDocument + tags: ["Knowledge"] + summary: "Get Organizational Document" + description: + |- + Get organizational document metadata + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateOrganizationDocument + tags: ["Knowledge"] + summary: "Update Organizational Document" + description: + |- + Update organizational document metadata + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + delete: + operationId: deleteOrganizationDocument + tags: ["Knowledge"] + summary: "Delete Organizational Document" + description: + |- + Delete organizational document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/documents/{doc_id}/content": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getOrganizationDocumentContent + tags: ["Knowledge"] + summary: "Get Organizational Document Content" + description: + |- + Get full content of organizational document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/teams/{team_id}/documents": + parameters: + - name: team_id + in: path + required: true + description: "Team id." + schema: { type: string } + post: + operationId: uploadTeamDocument + tags: ["Knowledge"] + summary: "Upload Team Document" + description: + |- + Upload a document to team knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "UploadFile (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listTeamDocuments + tags: ["Knowledge"] + summary: "List Team Documents" + description: + |- + Get list of team documents + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/teams/{team_id}/url": + parameters: + - name: team_id + in: path + required: true + description: "Team id." + schema: { type: string } + post: + operationId: addTeamUrl + tags: ["Knowledge"] + summary: "Add URL to Team Knowledge" + description: + |- + Add URL content to team knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/teams/{team_id}/documents/{doc_id}": + parameters: + - name: team_id + in: path + required: true + description: "Team id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getTeamDocument + tags: ["Knowledge"] + summary: "Get Team Document" + description: + |- + Get team document metadata + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateTeamDocument + tags: ["Knowledge"] + summary: "Update Team Document" + description: + |- + Update team document metadata + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + delete: + operationId: deleteTeamDocument + tags: ["Knowledge"] + summary: "Delete Team Document" + description: + |- + Delete team document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/teams/{team_id}/documents/{doc_id}/content": + parameters: + - name: team_id + in: path + required: true + description: "Team id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getTeamDocumentContent + tags: ["Knowledge"] + summary: "Get Team Document Content" + description: + |- + Get full content of team document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/agents/{agent_id}/documents": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: uploadAgentDocument + tags: ["Knowledge"] + summary: "Upload Agent Document" + description: + |- + Upload a document to agent knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "UploadFile (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listAgentDocuments + tags: ["Knowledge"] + summary: "List Agent Documents" + description: + |- + Get list of agent documents + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/agents/{agent_id}/url": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: addAgentUrl + tags: ["Knowledge"] + summary: "Add URL to Agent Knowledge" + description: + |- + Add URL content to agent knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/agents/{agent_id}/documents/{doc_id}": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getAgentDocument + tags: ["Knowledge"] + summary: "Get Agent Document" + description: + |- + Get agent document metadata + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateAgentDocument + tags: ["Knowledge"] + summary: "Update Agent Document" + description: + |- + Update agent document metadata + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + delete: + operationId: deleteAgentDocument + tags: ["Knowledge"] + summary: "Delete Agent Document" + description: + |- + Delete agent document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/agents/{agent_id}/documents/{doc_id}/content": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getAgentDocumentContent + tags: ["Knowledge"] + summary: "Get Agent Document Content" + description: + |- + Get full content of agent document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/create": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: createAgentContainer + tags: ["Containers"] + summary: "Create Agent Container" + description: + |- + Create a new container for an AI agent + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/start": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: startAgentContainer + tags: ["Containers"] + summary: "Start Agent Container" + description: + |- + Start an agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/stop": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: stopAgentContainer + tags: ["Containers"] + summary: "Stop Agent Container" + description: + |- + Stop an agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/restart": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: restartAgentContainer + tags: ["Containers"] + summary: "Restart Agent Container" + description: + |- + Restart an agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + delete: + operationId: removeAgentContainer + tags: ["Containers"] + summary: "Remove Agent Container" + description: + |- + Remove an agent container + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/status": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentContainerStatus + tags: ["Containers"] + summary: "Get Agent Container Status" + description: + |- + Get container status for an agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/containers/agents": + get: + operationId: listAgentContainers + tags: ["Containers"] + summary: "List Agent Containers" + description: + |- + List all agent containers + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/logs": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentContainerLogs + tags: ["Containers"] + summary: "Get Agent Container Logs" + description: + |- + Get container logs for an agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/execute": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: executeContainerCommand + tags: ["Containers"] + summary: "Execute Command in Container" + description: + |- + Execute a command in the agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/search": + post: + operationId: searchKnowledgeContext + tags: ["Knowledge"] + summary: "Search for relevant knowledge context using RAG" + description: + |- + Search for relevant knowledge context using RAG + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/enhance-prompt": + post: + operationId: enhancePromptWithContext + tags: ["Knowledge"] + summary: "Enhance a prompt with relevant context using RAG" + description: + |- + Enhance a prompt with relevant context using RAG + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/reindex": + post: + operationId: reindexKnowledgeBase + tags: ["Knowledge"] + summary: "Reindex all documents in a scope for RAG" + description: + |- + Reindex all documents in a scope for RAG + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/stats": + get: + operationId: getRagIndexStats + tags: ["Knowledge"] + summary: "Get statistics about the RAG index" + description: + |- + Get statistics about the RAG index + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/documents/{doc_id}/reindex": + parameters: + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + post: + operationId: reindexDocument + tags: ["Knowledge"] + summary: "Reindex a specific document for RAG" + description: + |- + Reindex a specific document for RAG + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/ws/stats": + get: + operationId: getWebsocketStats + tags: ["Platform"] + summary: "Get WebSocket connection statistics" + description: + |- + Get WebSocket connection statistics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/ws/test/agent/{agent_id}/status": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: testAgentStatusNotification + tags: ["Platform"] + summary: "Test endpoint to send agent status notifications" + description: + |- + Test endpoint to send agent status notifications + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/openapi.yaml": + get: + operationId: getOpenapiDocument + tags: ["Platform"] + summary: "This OpenAPI document" + description: + |- + Unauthenticated. Serves contracts/openapi.yaml — the document you are reading — from the copy baked into the image, so what the API publishes is always the contract this build was compiled against. + + This is NOT /openapi.json. That endpoint is FastAPI's auto-generated schema: it is derived from the code at import time and carries no curated descriptions, no tags beyond the decorators, and — critically — none of the irreversibility guidance in mcp/tools.overrides.yaml. Both are served; this one is the contract. + + Answers 503 if the image was built without its contract. A missing document is degraded, not fatal — no restart can conjure a file the image lacks. + security: [] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + description: >- + Bearer token. Resolved through the FuzeFront Security API when + SECURITY_BASE_URL is set; local JWT verification otherwise. + schemas: + Error: + type: object + description: FastAPI's error shape. + properties: + detail: + description: Human-readable error, or a validation-error array. +security: + - bearerAuth: [] diff --git a/deploy/argocd/README.md b/deploy/argocd/README.md new file mode 100644 index 0000000..66dcd41 --- /dev/null +++ b/deploy/argocd/README.md @@ -0,0 +1,104 @@ +# Argo CD wiring for FuzeAgent — a FuzeInfra delegation + +**FuzeInfra owns Argo `Application` and `AppProject` resources.** A product repo +does not author them; two repos independently declaring an Application for the +same workload is the competing-unrestricted-app failure FuzeMarket PR #61 +removed. This file is the **handoff spec**, not a manifest. + +> **The manifests already in this directory are live wiring. This change +> neither adds, edits nor removes any of them.** + +| Existing manifest | Deploys | +|---|---| +| `app-of-apps.yaml` | recursive discovery of `applications/` | +| `applications/fuzeagent.yaml` | `deploy/helm/fuzeagent` — the product chart this change extends | +| `applications/fuzeagent-sealed.yaml` | the sealed-secret bundle | +| `applications/a2a-shared.yaml` | `deploy/helm/a2a-shared` — **the family's only A2A server** | + +## The A2A finding — read this first + +**`a2a-shared` is wired for deployment, not merely implemented.** This was the +open question for the whole family, so here is the evidence rather than a claim: + +- `deploy/argocd/applications/a2a-shared.yaml` exists **on `main`**, targeting + `path: deploy/helm/a2a-shared`, `targetRevision: main`, + `valueFiles: [values-prod.yaml]`, `destination.namespace: fuzeagent`, with + `automated: {prune: true, selfHeal: true}`. +- `deploy/helm/a2a-shared/values-prod.yaml` **on `main`** has `a2a.enabled: true` + and a pinned image `ghcr.io/izzywdev/fuzeagent-a2a:e2d7d1c2b55a`. +- `helm template` against those prod values renders a **Deployment and a Service + both named `a2a-shared`, port 8080**, whose selector matches exactly one + workload — i.e. precisely the address the image hardcodes on every Agent Card + (`agent-templates/a2a/card_generator.py:29`, + `http://a2a-shared.fuzeagent.svc.cluster.local:8080/rpc`). The chart's + `_helpers.tpl` pins that name deliberately and says why. +- Three tenants are enabled in those values: `FuzeAgent` + (entryRole `agent-orchestrator`), `FuzeFront` (`app-shell-platform`, ref + `master`), `FuzePlan` (`product-manager`). +- The four SealedSecrets it needs (`a2a-provider-anthropic`, `a2a-mtls-ca`, + `a2a-card-signing`, `a2a-repos-git`) are rendered by the chart itself. + +**What could NOT be verified from here:** whether the pod is actually *running +and healthy* in the cluster. There is no cluster access in this session, by +constraint. Everything above is GitOps declaration, which is the source of +truth for what Argo will apply — but "declared" is not "up". + +Two things to check on the cluster before relying on the surface: + +1. `kubectl -n fuzeagent get deploy,svc a2a-shared` and the pod's `/healthz`. +2. The repo-sync init container clones each tenant at its `ref`. **FuzePlan is a + private repo**, so the `a2a-repos-git` SealedSecret must carry a token that + can read it, or that tenant's card projection fails. + +One dead value, noted while reading: `deploy.stateConfigMap: a2a-state` is set +in `values-prod.yaml` but `templates/deployment.yaml` mounts an `emptyDir` for +`/state` and never references it. Nothing creates a ConfigMap called +`a2a-state`. Harmless today (the mount works), but the value is a no-op. + +## What FuzeAgent needs for the product chart + +| Field | Value | +|---|---| +| `repoURL` | `https://github.com/izzywdev/FuzeAgent.git` | +| `path` | `deploy/helm/fuzeagent` | +| `targetRevision` | `main` | +| `helm.valueFiles` | `values-prod.yaml` | +| `destination.namespace` | `fuzeagent` | +| `syncOptions` | `CreateNamespace=true` | + +## What this change adds to the render + +One new workload, behind its own gate, **shipping OFF**: + +| Pod | Gate | Ships as | To flip it | +|---|---|---|---| +| backend (`orchestrator`) | `orchestrator.enabled` | **on** (unchanged) | — now also serves `GET /openapi.yaml` | +| frontend (`ui`) | `ui.enabled` | **on** (unchanged) | — | +| MCP SSE gateway (`fuzeagent-mcp`) | `mcp.enabled` | **off** | needs `ghcr.io/izzywdev/fuze-mcp-gateway:0.1.0` in GHCR | +| A2A (`a2a-shared`) | separate chart | **on** | already deployed — see above | + +With `mcp.enabled: false` the rendered set is identical to today's apart from +one added env var on the orchestrator (`OPENAPI_SPEC_PATH`). + +**Note the namespace ResourceQuota.** `resourceGovernance.quota` allows 20 pods +and `limitsCpu: 6`. The MCP pod requests 50m/64Mi and limits 500m/256Mi, which +fits, but the quota is already sized deliberately for `a2a-shared` plus its +rolling-update surge — worth re-checking before enabling. + +## Infrastructure assumptions to confirm + +None was verified against a live cluster: + +- **Ingress class `traefik`** behind the Cloudflare tunnel; only `/` is routed, + to the `ui` Service, whose nginx reverse-proxies `/api/orchestrator` and + `/api/hierarchy` same-origin. +- **`ghcr.io/izzywdev/fuze-mcp-gateway:0.1.0` exists in GHCR.** It is FuzeFront's + image and **no workflow in this repo builds it**. If absent, flipping + `mcp.enabled` gives `ImagePullBackOff`, not a working pod. +- **`ghcr-pull` image pull secret** and `fuzeagent-secrets` exist in the + namespace — existing workloads already depend on both. +- **`release.yml` builds the orchestrator image on push to `main`** matching + `services/orchestrator/**`, so the new `GET /openapi.yaml` route and the + contract copy inside the image ship on the next release. That path filter does + **not** include `contracts/**`, which is why the contract is synced into + `services/orchestrator/contracts/` rather than referenced across the tree. diff --git a/deploy/helm/fuzeagent/files/openapi.yaml b/deploy/helm/fuzeagent/files/openapi.yaml new file mode 100644 index 0000000..7881015 --- /dev/null +++ b/deploy/helm/fuzeagent/files/openapi.yaml @@ -0,0 +1,5649 @@ +openapi: 3.1.0 +info: + title: FuzeAgent Orchestrator API + version: 0.1.0 + summary: The HTTP surface the deployed FuzeAgent orchestrator actually serves. + description: >- + FuzeAgent orchestrates autonomous AI agents: it creates agents, assigns them tasks, + EXECUTES those tasks in containers and sandboxes, brokers agent-to-agent + communication, and manages the knowledge and goal state behind all of it. + + + WHAT THIS DOCUMENT IS. It describes the routes served by + `services/orchestrator/main.py` — the FastAPI application the Helm chart deploys as + the `orchestrator` pod on port 8000, reachable in-cluster at + http://orchestrator:8000. Every path was read off an `@app.` decorator by + static analysis; the summaries are the handlers' own docstrings. Nothing here is + aspirational. + + + THE ONE THING TO UNDERSTAND BEFORE CALLING ANYTHING. FuzeAgent is not a CRUD API + with a dangerous corner. Its core purpose is to DISPATCH AGENTS THAT TAKE REAL + ACTIONS — they write files, run shell commands in containers, call third-party + APIs and spend money on model inference. `POST /tasks/{task_id}/execute` is the + canonical case: it returns quickly, and by the time it has, an agent is running. + Cancelling it stops future work; it does not undo work already done. Operations of + that shape are marked irreversible in `mcp/tools.overrides.yaml` regardless of + their HTTP verb, because the verb says nothing about whether the effect can be + taken back. + + + WHAT IT IS NOT. FuzeAgent deploys a SECOND backend, `services/hierarchy_API` + (the `hierarchy-api` pod, port 8006), with roughly forty of its own routes for + organizations, teams and agent hierarchy. It is a separate FastAPI application on + a separate Service and is NOT covered by this document; a single OpenAPI document + maps to a single upstream base URL, so it would need its own contract and its own + gateway pod. See `contracts/README.md`. + + + AUTHENTICATION. Bearer token, resolved through the FuzeFront Security API when + `SECURITY_BASE_URL` is configured (`services/orchestrator/fuze_security.py`), with + a local JWT fallback otherwise. `main:app` fails closed at boot without either. + contact: + name: FuzeAgent + url: https://github.com/izzywdev/FuzeAgent + license: + name: UNLICENSED +servers: + - url: / + description: >- + The orchestrator serves absolute paths with no common prefix, so the base URL + carries no path segment. In-cluster: http://orchestrator:8000. +tags: + - name: Platform + description: Health, websocket stats and system dashboards. + - name: Agents + description: Creating, inspecting and configuring agents. + - name: Tasks + description: >- + Assigning and EXECUTING work. The operations here are the ones that make an + agent act on the world. + - name: Containers + description: Per-agent container lifecycle and in-container command execution. + - name: Sandboxes + description: Sandbox lifecycle and arbitrary command execution inside one. + - name: Coordination + description: Multi-agent coordination sessions and agent-to-agent messaging. + - name: Conversations + description: Agent conversations and the derived artefacts (milestones, action items). + - name: Goals + description: Organizational goals, milestones and progress tracking. + - name: Knowledge + description: Documents, RAG index and knowledge analytics. + - name: Context + description: Agent interaction context. + - name: MCP passthrough + description: >- + The orchestrator's own MCP client surface — listing and calling tools of MCP + servers the AGENTS use. Not to be confused with FuzeAgent's MCP gateway pod, + which exposes THIS API as MCP tools. + - name: Organizations + description: Organization-scoped model, provider and dashboard configuration. +paths: + "/health": + get: + operationId: healthCheck + tags: ["Platform"] + summary: "Health Check" + description: + |- + Health check endpoint that returns the current status of the orchestrator service. + + Returns: + dict: Service health status and basic information + security: [] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents": + post: + operationId: createAgent + tags: ["Agents"] + summary: "Create AI Agent" + description: + |- + Create a new AI agent with repository and sandbox settings + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "AgentCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listAgents + tags: ["Agents"] + summary: "List All Agents" + description: + |- + List all agents and their status + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/tasks": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: assignTask + tags: ["Tasks"] + summary: "Assign Task to Agent" + description: + |- + Assign a task to an agent + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "TaskCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: getAgentTasks + tags: ["Tasks"] + summary: "Get tasks assigned to an agent" + description: + |- + Get tasks assigned to an agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/status": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentStatus + tags: ["Agents"] + summary: "Get detailed agent status" + description: + |- + Get detailed agent status + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/teams": + get: + operationId: listTeams + tags: ["Platform"] + summary: "List all teams" + description: + |- + List all teams + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agent-templates": + get: + operationId: listAgentTemplates + tags: ["Agents"] + summary: "List available agent templates" + description: + |- + List available agent templates + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks": + get: + operationId: listTasks + tags: ["Tasks"] + summary: "List all tasks" + description: + |- + List all tasks + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTask + tags: ["Tasks"] + summary: "Get task details" + description: + |- + Get task details + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateTask + tags: ["Tasks"] + summary: "Update task status and result" + description: + |- + Update task status and result + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/from-template": + post: + operationId: createAgentFromTemplate + tags: ["Agents"] + summary: "Create agent from template with repository settings" + description: + |- + Create agent from template with repository settings + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/templates": + get: + operationId: getAgentTemplates + tags: ["Agents"] + summary: "Get available agent templates" + description: + |- + Get available agent templates + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/execute": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: startTaskExecution + tags: ["Tasks"] + summary: "Start Autonomous Task Execution" + description: + |- + Start autonomous execution of a task + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/status": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskExecutionStatus + tags: ["Tasks"] + summary: "Get detailed task execution status" + description: + |- + Get detailed task execution status + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateTaskStatus + tags: ["Tasks"] + summary: "Update Task Status" + description: + |- + Update task status - used by memory-enabled agents to report progress + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/iterations": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskIterations + tags: ["Tasks"] + summary: "Get task iteration history" + description: + |- + Get task iteration history + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/sandbox": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentSandbox + tags: ["Agents"] + summary: "Get agent sandbox information" + description: + |- + Get agent sandbox information + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/context/interactions": + post: + operationId: storeInteraction + tags: ["Context"] + summary: "Store agent interaction" + description: + |- + Store agent interaction + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/context": + get: + operationId: getContext + tags: ["Context"] + summary: "Get relevant context for a query" + description: + |- + Get relevant context for a query + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/memory": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentMemory + tags: ["Agents"] + summary: "Get agent memory" + description: + |- + Get agent memory + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + delete: + operationId: stopMemoryEnabledAgent + tags: ["Agents"] + summary: "Stop Memory-Enabled Agent" + description: + |- + Stop and clean up a memory-enabled agent container + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/conversations": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentConversations + tags: ["Conversations"] + summary: "Get Agent Conversations" + description: + |- + Get all conversations for a specific agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + post: + operationId: createAgentConversation + tags: ["Conversations"] + summary: "Create New Agent Conversation" + description: + |- + Create a new conversation with an agent + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ConversationCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/conversations/{conversation_id}/messages": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + get: + operationId: getConversationMessages + tags: ["Conversations"] + summary: "Get Conversation Messages" + description: + |- + Get all messages in a conversation + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + post: + operationId: sendMessageToAgent + tags: ["Conversations"] + summary: "Send Message to Agent" + description: + |- + Send a message to an agent in a conversation + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ChatMessageRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/search": + get: + operationId: searchKnowledge + tags: ["Knowledge"] + summary: "Search knowledge base" + description: + |- + Search knowledge base + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/human-response": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: submitHumanResponse + tags: ["Tasks"] + summary: "Submit Human Response" + description: + |- + Submit human response to a task question + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "HumanResponseRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/cancel": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: cancelTaskExecution + tags: ["Tasks"] + summary: "Cancel autonomous execution of a task" + description: + |- + Cancel autonomous execution of a task + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/messages": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskMessages + tags: ["Tasks"] + summary: "Get task messages and chat history" + description: + |- + Get task messages and chat history + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/sandboxes": + get: + operationId: listSandboxes + tags: ["Sandboxes"] + summary: "List active sandboxes" + description: + |- + List active sandboxes + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/sandboxes/{sandbox_id}/execute": + parameters: + - name: sandbox_id + in: path + required: true + description: "Sandbox id." + schema: { type: string } + post: + operationId: executeCommandInSandbox + tags: ["Sandboxes"] + summary: "Execute a command in a sandbox" + description: + |- + Execute a command in a sandbox + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/sandboxes/{sandbox_id}": + parameters: + - name: sandbox_id + in: path + required: true + description: "Sandbox id." + schema: { type: string } + delete: + operationId: destroySandbox + tags: ["Sandboxes"] + summary: "Destroy a sandbox" + description: + |- + Destroy a sandbox + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/register": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: registerAgent + tags: ["Agents"] + summary: "Register an agent running in a sandbox container" + description: + |- + Register an agent running in a sandbox container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/next-task": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getNextTaskForAgent + tags: ["Agents"] + summary: "Get the next task for an agent to execute" + description: + |- + Get the next task for an agent to execute + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/error": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: reportAgentError + tags: ["Agents"] + summary: "Report an error from an agent" + description: + |- + Report an error from an agent + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/conversation": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskConversation + tags: ["Tasks"] + summary: "Get conversation history for a task" + description: + |- + Get conversation history for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/conversation/summary": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getConversationSummary + tags: ["Tasks"] + summary: "Get conversation summary with statistics" + description: + |- + Get conversation summary with statistics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/code-generations": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskCodeGenerations + tags: ["Tasks"] + summary: "Get code generations for a task" + description: + |- + Get code generations for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/performance": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentPerformance + tags: ["Agents"] + summary: "Get agent performance metrics" + description: + |- + Get agent performance metrics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/file-operations": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskFileOperations + tags: ["Tasks"] + summary: "Get File Operations" + description: + |- + Get file operations for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/file-operations/{batch_id}/preview": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + - name: batch_id + in: path + required: true + description: "Batch id." + schema: { type: string } + get: + operationId: getFileOperationsPreview + tags: ["Tasks"] + summary: "Get preview of file changes for a batch" + description: + |- + Get preview of file changes for a batch + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/file-operations/{batch_id}/approve": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + - name: batch_id + in: path + required: true + description: "Batch id." + schema: { type: string } + post: + operationId: approveFileOperations + tags: ["Tasks"] + summary: "Approve File Operations" + description: + |- + Approve or reject file operations + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "FileOperationApprovalRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/file-operations/{batch_id}/rollback": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + - name: batch_id + in: path + required: true + description: "Batch id." + schema: { type: string } + post: + operationId: rollbackFileOperations + tags: ["Tasks"] + summary: "Rollback applied file operations" + description: + |- + Rollback applied file operations + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/claude-session": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getClaudeSessionStatus + tags: ["Tasks"] + summary: "Get Claude SDK session status for a task" + description: + |- + Get Claude SDK session status for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/claude-session/input": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: sendClaudeSessionInput + tags: ["Tasks"] + summary: "Send input to Claude SDK session" + description: + |- + Send input to Claude SDK session + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/mcp/tools": + get: + operationId: getMcpTools + tags: ["MCP passthrough"] + summary: "Get available MCP tools" + description: + |- + Get available MCP tools + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/mcp/call-tool": + post: + operationId: callMcpTool + tags: ["MCP passthrough"] + summary: "Call MCP Tool" + description: + |- + Call an MCP tool + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "MCPToolRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/mcp/resources": + get: + operationId: getMcpResources + tags: ["MCP passthrough"] + summary: "Get available MCP resources" + description: + |- + Get available MCP resources + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/mcp/resource": + get: + operationId: getMcpResource + tags: ["MCP passthrough"] + summary: "Get an MCP resource by URI" + description: + |- + Get an MCP resource by URI + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/mcp-context": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskMcpContext + tags: ["Tasks"] + summary: "Get MCP context for a task" + description: + |- + Get MCP context for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/mcp-setup": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: setupAgentMcp + tags: ["Agents"] + summary: "Setup Agent MCP Integration" + description: + |- + Set up MCP integration for an agent + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "AgentMCPSetupRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/coordinate": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: initiateTaskCoordination + tags: ["Tasks"] + summary: "Initiate Multi-Agent Coordination" + description: + |- + Initiate multi-agent coordination for a complex task + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "CoordinationRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/coordination/{session_id}": + parameters: + - name: session_id + in: path + required: true + description: "Session id." + schema: { type: string } + get: + operationId: getCoordinationStatus + tags: ["Coordination"] + summary: "Get status of a coordination session" + description: + |- + Get status of a coordination session + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/coordination/{session_id}/cancel": + parameters: + - name: session_id + in: path + required: true + description: "Session id." + schema: { type: string } + post: + operationId: cancelCoordination + tags: ["Coordination"] + summary: "Cancel a coordination session" + description: + |- + Cancel a coordination session + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{from_agent_id}/communicate/{to_agent_id}": + parameters: + - name: from_agent_id + in: path + required: true + description: "From agent id." + schema: { type: string } + - name: to_agent_id + in: path + required: true + description: "To agent id." + schema: { type: string } + post: + operationId: sendAgentCommunication + tags: ["Agents"] + summary: "Send communication between agents" + description: + |- + Send communication between agents + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/coordination/active": + get: + operationId: getActiveCoordinations + tags: ["Coordination"] + summary: "Get all active coordination sessions" + description: + |- + Get all active coordination sessions + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/providers/{provider}/credentials": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + - name: provider + in: path + required: true + description: "Provider." + schema: { type: string } + post: + operationId: storeProviderCredentials + tags: ["Organizations"] + summary: "Store Provider API Credentials" + description: + |- + Store encrypted API credentials for a model provider at organization level + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ProviderCredentialsRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/models": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getAvailableModels + tags: ["Organizations"] + summary: "Get Available Models" + description: + |- + Get available AI models with provider credential validation + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/model-configuration": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: configureAgentModel + tags: ["Agents"] + summary: "Configure Agent Model Settings" + description: + |- + Configure model settings for an AI agent + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "AgentModelConfigRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: getAgentModelConfiguration + tags: ["Agents"] + summary: "Get Agent Model Configuration" + description: + |- + Get model configuration for an AI agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/tasks/cost-estimate": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: estimateTaskCost + tags: ["Tasks"] + summary: "Estimate Task Cost" + description: + |- + Estimate cost for task execution based on agent's model configuration + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "TaskCostEstimateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/model-usage": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getOrganizationModelUsage + tags: ["Organizations"] + summary: "Get Model Usage Statistics" + description: + |- + Get model usage statistics and costs for an organization + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/model-recommendations": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getModelRecommendations + tags: ["Agents"] + summary: "Get Model Recommendations" + description: + |- + Get model recommendations based on task capabilities and cost constraints + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/notifications/{recipient_type}/{recipient_id}": + parameters: + - name: recipient_type + in: path + required: true + description: "Recipient type." + schema: { type: string } + - name: recipient_id + in: path + required: true + description: "Recipient id." + schema: { type: string } + get: + operationId: getKnowledgeNotifications + tags: ["Knowledge"] + summary: "Get Knowledge Notifications" + description: + |- + Get knowledge notifications for a recipient + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/notifications/{notification_id}/status": + parameters: + - name: notification_id + in: path + required: true + description: "Notification id." + schema: { type: string } + put: + operationId: updateNotificationStatus + tags: ["Knowledge"] + summary: "Update Notification Status" + description: + |- + Update notification status and optional action taken + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/notifications/statistics": + get: + operationId: getNotificationStatistics + tags: ["Knowledge"] + summary: "Get Notification Statistics" + description: + |- + Get notification statistics and analytics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/add": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + post: + operationId: addOrganizationalKnowledge + tags: ["Knowledge"] + summary: "Add Organizational Knowledge" + description: + |- + Add knowledge to organization-level knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/search": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: searchOrganizationalKnowledge + tags: ["Knowledge"] + summary: "Search Organizational Knowledge" + description: + |- + Search organization-level knowledge base + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/context-enhancement/{agent_id}": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getEnhancedContextForAgent + tags: ["Knowledge"] + summary: "Get Enhanced Context for Agent" + description: + |- + Get enhanced context with relevant knowledge for agent task execution + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/organizations/{organization_id}/insights": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getOrganizationalKnowledgeInsights + tags: ["Knowledge"] + summary: "Get Organizational Knowledge Insights" + description: + |- + Get comprehensive organizational knowledge insights and analytics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/organizations/{organization_id}/effectiveness": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: analyzeKnowledgeEffectiveness + tags: ["Knowledge"] + summary: "Analyze Knowledge Effectiveness" + description: + |- + Analyze effectiveness of knowledge items in the organization + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/agents/{agent_id}/profile": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentKnowledgeProfile + tags: ["Knowledge"] + summary: "Get Agent Knowledge Profile" + description: + |- + Get detailed knowledge profile for an agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/organizations/{organization_id}/optimization": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getKnowledgeOptimizationRecommendations + tags: ["Knowledge"] + summary: "Get Knowledge Optimization Recommendations" + description: + |- + Generate comprehensive knowledge optimization recommendations + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/organizations/{organization_id}/trends": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getKnowledgeTrendsAnalysis + tags: ["Knowledge"] + summary: "Get Knowledge Trends Analysis" + description: + |- + Get comprehensive knowledge trends analysis + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/deploy-memory": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: deployMemoryEnabledAgent + tags: ["Agents"] + summary: "Deploy Memory-Enabled Agent" + description: + |- + Deploy a memory-enabled autonomous agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/memory-status": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentMemoryStatus + tags: ["Agents"] + summary: "Get Agent Memory Status" + description: + |- + Get agent memory status, expertise metrics, and insights + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/memory-tasks": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: assignTaskToMemoryAgent + tags: ["Agents"] + summary: "Assign Task to Memory Agent" + description: + |- + Assign a task to a memory-enabled agent for autonomous execution + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/system/expertise-dashboard": + get: + operationId: getSystemExpertiseDashboard + tags: ["Platform"] + summary: "Get System Expertise Dashboard" + description: + |- + Get comprehensive dashboard of system expertise and memory analytics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/tasks/pending": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getPendingTasksForAgent + tags: ["Tasks"] + summary: "Get Pending Tasks for Agent" + description: + |- + Get pending tasks that a memory-enabled agent can pick up + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/statistics": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: updateAgentStatistics + tags: ["Agents"] + summary: "Agent Statistics Update" + description: + |- + Update agent statistics - used by memory-enabled agents for performance tracking + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/goals": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + post: + operationId: createGoal + tags: ["Goals"] + summary: "Create organizational goal" + description: + |- + Create a new organizational goal + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "GoalCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listOrganizationGoals + tags: ["Goals"] + summary: "List organization goals" + description: + |- + List goals for an organization + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + get: + operationId: getGoal + tags: ["Goals"] + summary: "Get goal details" + description: + |- + Get goal details + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/overview": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + get: + operationId: getGoalOverview + tags: ["Goals"] + summary: "Get goal overview" + description: + |- + Get comprehensive goal overview + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/progress": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + put: + operationId: updateGoalProgress + tags: ["Goals"] + summary: "Update goal progress" + description: + |- + Update goal progress + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "GoalUpdateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/milestones": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: createMilestone + tags: ["Goals"] + summary: "Create milestone" + description: + |- + Create milestone for goal + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "MilestoneCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/milestones/{milestone_id}/tasks": + parameters: + - name: milestone_id + in: path + required: true + description: "Milestone id." + schema: { type: string } + post: + operationId: createTaskFromMilestone + tags: ["Goals"] + summary: "Create task from milestone" + description: + |- + Create task from milestone + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "TaskFromMilestoneRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/generate-execution-plan": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: generateExecutionPlan + tags: ["Goals"] + summary: "Generate execution plan" + description: + |- + Generate execution plan with milestones and tasks + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/generate-monthly-milestones": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: generateMonthlyMilestones + tags: ["Goals"] + summary: "Generate monthly milestones" + description: + |- + Generate monthly milestones for goal + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/milestones/{milestone_id}/generate-weekly-tasks": + parameters: + - name: milestone_id + in: path + required: true + description: "Milestone id." + schema: { type: string } + post: + operationId: generateWeeklyTasks + tags: ["Goals"] + summary: "Generate weekly tasks" + description: + |- + Generate weekly tasks for milestone + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/generate-cross-functional-tasks": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: generateCrossFunctionalTasks + tags: ["Goals"] + summary: "Generate cross-functional tasks" + description: + |- + Generate cross-functional tasks for goal + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/conversations": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: createGoalConversation + tags: ["Goals"] + summary: "Create goal conversation" + description: + |- + Create goal conversation + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "GoalConversationCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: getGoalConversations + tags: ["Goals"] + summary: "Get goal conversations" + description: + |- + Get conversations for a goal + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + get: + operationId: getGoalConversation + tags: ["Conversations"] + summary: "Get goal conversation" + description: + |- + Get goal conversation + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}/messages": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + post: + operationId: addMessageToConversation + tags: ["Conversations"] + summary: "Add message to conversation" + description: + |- + Add message to conversation + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ConversationMessageRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}/generate-milestones": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + post: + operationId: generatePlanningMilestones + tags: ["Conversations"] + summary: "Generate milestones from conversation" + description: + |- + Generate planning milestones from conversation + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}/conduct-progress-review": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + post: + operationId: conductProgressReview + tags: ["Conversations"] + summary: "Conduct progress review" + description: + |- + Conduct progress review + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}/extract-action-items": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + post: + operationId: extractActionItems + tags: ["Conversations"] + summary: "Extract action items" + description: + |- + Extract action items from conversation + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/track-progress": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: recordProgressTracking + tags: ["Goals"] + summary: "Record progress tracking update" + description: + |- + Record progress tracking update + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ProgressUpdateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/deadline-risk": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + get: + operationId: assessDeadlineRisk + tags: ["Goals"] + summary: "Assess deadline risk" + description: + |- + Assess deadline risk for goal + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/progress-report": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + get: + operationId: generateProgressReport + tags: ["Goals"] + summary: "Generate progress report" + description: + |- + Generate progress report for goal + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/goals-dashboard": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getOrganizationGoalsDashboard + tags: ["Goals"] + summary: "Get organization goals dashboard" + description: + |- + Get organization goals dashboard + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/tracking-dashboard": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getTrackingDashboard + tags: ["Organizations"] + summary: "Get tracking dashboard" + description: + |- + Get organization tracking dashboard + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/documents": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + post: + operationId: uploadOrganizationDocument + tags: ["Knowledge"] + summary: "Upload Organizational Document" + description: + |- + Upload a document to organizational knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "UploadFile (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listOrganizationDocuments + tags: ["Knowledge"] + summary: "List Organizational Documents" + description: + |- + Get list of organizational documents + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/url": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + post: + operationId: addOrganizationUrl + tags: ["Knowledge"] + summary: "Add URL to Organizational Knowledge" + description: + |- + Add URL content to organizational knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/documents/{doc_id}": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getOrganizationDocument + tags: ["Knowledge"] + summary: "Get Organizational Document" + description: + |- + Get organizational document metadata + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateOrganizationDocument + tags: ["Knowledge"] + summary: "Update Organizational Document" + description: + |- + Update organizational document metadata + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + delete: + operationId: deleteOrganizationDocument + tags: ["Knowledge"] + summary: "Delete Organizational Document" + description: + |- + Delete organizational document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/documents/{doc_id}/content": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getOrganizationDocumentContent + tags: ["Knowledge"] + summary: "Get Organizational Document Content" + description: + |- + Get full content of organizational document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/teams/{team_id}/documents": + parameters: + - name: team_id + in: path + required: true + description: "Team id." + schema: { type: string } + post: + operationId: uploadTeamDocument + tags: ["Knowledge"] + summary: "Upload Team Document" + description: + |- + Upload a document to team knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "UploadFile (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listTeamDocuments + tags: ["Knowledge"] + summary: "List Team Documents" + description: + |- + Get list of team documents + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/teams/{team_id}/url": + parameters: + - name: team_id + in: path + required: true + description: "Team id." + schema: { type: string } + post: + operationId: addTeamUrl + tags: ["Knowledge"] + summary: "Add URL to Team Knowledge" + description: + |- + Add URL content to team knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/teams/{team_id}/documents/{doc_id}": + parameters: + - name: team_id + in: path + required: true + description: "Team id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getTeamDocument + tags: ["Knowledge"] + summary: "Get Team Document" + description: + |- + Get team document metadata + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateTeamDocument + tags: ["Knowledge"] + summary: "Update Team Document" + description: + |- + Update team document metadata + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + delete: + operationId: deleteTeamDocument + tags: ["Knowledge"] + summary: "Delete Team Document" + description: + |- + Delete team document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/teams/{team_id}/documents/{doc_id}/content": + parameters: + - name: team_id + in: path + required: true + description: "Team id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getTeamDocumentContent + tags: ["Knowledge"] + summary: "Get Team Document Content" + description: + |- + Get full content of team document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/agents/{agent_id}/documents": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: uploadAgentDocument + tags: ["Knowledge"] + summary: "Upload Agent Document" + description: + |- + Upload a document to agent knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "UploadFile (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listAgentDocuments + tags: ["Knowledge"] + summary: "List Agent Documents" + description: + |- + Get list of agent documents + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/agents/{agent_id}/url": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: addAgentUrl + tags: ["Knowledge"] + summary: "Add URL to Agent Knowledge" + description: + |- + Add URL content to agent knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/agents/{agent_id}/documents/{doc_id}": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getAgentDocument + tags: ["Knowledge"] + summary: "Get Agent Document" + description: + |- + Get agent document metadata + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateAgentDocument + tags: ["Knowledge"] + summary: "Update Agent Document" + description: + |- + Update agent document metadata + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + delete: + operationId: deleteAgentDocument + tags: ["Knowledge"] + summary: "Delete Agent Document" + description: + |- + Delete agent document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/agents/{agent_id}/documents/{doc_id}/content": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getAgentDocumentContent + tags: ["Knowledge"] + summary: "Get Agent Document Content" + description: + |- + Get full content of agent document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/create": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: createAgentContainer + tags: ["Containers"] + summary: "Create Agent Container" + description: + |- + Create a new container for an AI agent + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/start": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: startAgentContainer + tags: ["Containers"] + summary: "Start Agent Container" + description: + |- + Start an agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/stop": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: stopAgentContainer + tags: ["Containers"] + summary: "Stop Agent Container" + description: + |- + Stop an agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/restart": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: restartAgentContainer + tags: ["Containers"] + summary: "Restart Agent Container" + description: + |- + Restart an agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + delete: + operationId: removeAgentContainer + tags: ["Containers"] + summary: "Remove Agent Container" + description: + |- + Remove an agent container + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/status": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentContainerStatus + tags: ["Containers"] + summary: "Get Agent Container Status" + description: + |- + Get container status for an agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/containers/agents": + get: + operationId: listAgentContainers + tags: ["Containers"] + summary: "List Agent Containers" + description: + |- + List all agent containers + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/logs": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentContainerLogs + tags: ["Containers"] + summary: "Get Agent Container Logs" + description: + |- + Get container logs for an agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/execute": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: executeContainerCommand + tags: ["Containers"] + summary: "Execute Command in Container" + description: + |- + Execute a command in the agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/search": + post: + operationId: searchKnowledgeContext + tags: ["Knowledge"] + summary: "Search for relevant knowledge context using RAG" + description: + |- + Search for relevant knowledge context using RAG + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/enhance-prompt": + post: + operationId: enhancePromptWithContext + tags: ["Knowledge"] + summary: "Enhance a prompt with relevant context using RAG" + description: + |- + Enhance a prompt with relevant context using RAG + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/reindex": + post: + operationId: reindexKnowledgeBase + tags: ["Knowledge"] + summary: "Reindex all documents in a scope for RAG" + description: + |- + Reindex all documents in a scope for RAG + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/stats": + get: + operationId: getRagIndexStats + tags: ["Knowledge"] + summary: "Get statistics about the RAG index" + description: + |- + Get statistics about the RAG index + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/documents/{doc_id}/reindex": + parameters: + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + post: + operationId: reindexDocument + tags: ["Knowledge"] + summary: "Reindex a specific document for RAG" + description: + |- + Reindex a specific document for RAG + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/ws/stats": + get: + operationId: getWebsocketStats + tags: ["Platform"] + summary: "Get WebSocket connection statistics" + description: + |- + Get WebSocket connection statistics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/ws/test/agent/{agent_id}/status": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: testAgentStatusNotification + tags: ["Platform"] + summary: "Test endpoint to send agent status notifications" + description: + |- + Test endpoint to send agent status notifications + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/openapi.yaml": + get: + operationId: getOpenapiDocument + tags: ["Platform"] + summary: "This OpenAPI document" + description: + |- + Unauthenticated. Serves contracts/openapi.yaml — the document you are reading — from the copy baked into the image, so what the API publishes is always the contract this build was compiled against. + + This is NOT /openapi.json. That endpoint is FastAPI's auto-generated schema: it is derived from the code at import time and carries no curated descriptions, no tags beyond the decorators, and — critically — none of the irreversibility guidance in mcp/tools.overrides.yaml. Both are served; this one is the contract. + + Answers 503 if the image was built without its contract. A missing document is degraded, not fatal — no restart can conjure a file the image lacks. + security: [] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + description: >- + Bearer token. Resolved through the FuzeFront Security API when + SECURITY_BASE_URL is set; local JWT verification otherwise. + schemas: + Error: + type: object + description: FastAPI's error shape. + properties: + detail: + description: Human-readable error, or a validation-error array. +security: + - bearerAuth: [] diff --git a/deploy/helm/fuzeagent/files/tools.overrides.yaml b/deploy/helm/fuzeagent/files/tools.overrides.yaml new file mode 100644 index 0000000..b8e1f19 --- /dev/null +++ b/deploy/helm/fuzeagent/files/tools.overrides.yaml @@ -0,0 +1,258 @@ +# ============================================================================= +# FuzeAgent — MCP tool mutation overrides. +# +# Consumed by @fuzefront/mcp-gateway. The gateway derives `mutates` from the HTTP +# method (GET/HEAD/OPTIONS = read; POST to a path ending /search, /query or +# /preview = read; DELETE = irreversible write; everything else = reversible +# write) and only needs this file where the method alone gets it WRONG. +# +# ON THIS API THE METHOD GETS IT WRONG A LOT, and the reason is the whole point +# of FuzeAgent: it DISPATCHES AGENTS THAT TAKE REAL ACTIONS. An agent writes +# files, runs shell commands in a container, calls third-party APIs and spends +# money on model inference. The HTTP response to "execute this task" arrives in +# milliseconds; the consequences do not stop there. +# +# So the classification here is on EFFECT, never on verb: +# +# * a POST that starts an agent is IRREVERSIBLE, even though POST defaults to +# reversible — cancelling stops FUTURE work, it does not undo work done; +# * a POST ending /search is a read, and the gateway already knows that; +# * a DELETE of a container is REVERSIBLE, because the container is +# re-creatable from the same agent definition. +# +# `reversibility` means, precisely: is there an operation IN THIS CONTRACT that +# the caller can invoke to undo the effect? Not "could a human repair it". +# +# The gateway REFUSES TO START if an entry declares something irreversible while +# also declaring it a read, or relabels a non-query-shaped POST as a read. +# +# VERIFIED, not asserted: this file was loaded by the real @fuzefront/mcp-gateway +# from the exact ConfigMap bytes `helm template` renders. 142 tools enumerate, +# 74 reads / 68 writes, 16 irreversible, no tool is both a read and +# irreversible, and startTaskExecution's description reaches the model prefixed +# "[WRITE — IRREVERSIBLE]". +# +# STANDING FACTS about this API that shape the list below: +# 1. There is NO `DELETE /agents/{agent_id}` and NO `DELETE /tasks/{task_id}`. +# A created agent and a created task are permanent as far as this API is +# concerned. +# 2. The only genuine undo operation anywhere in the contract is +# POST /tasks/{task_id}/file-operations/{batch_id}/rollback. It undoes an +# approved FILE batch and nothing else. +# ============================================================================= + +tools: + # ========================================================================= + # IRREVERSIBLE — dispatches an agent, or executes a command + # ========================================================================= + + # THE canonical case, and the reason this file is written the way it is. + # Starting execution hands the task to an agent that writes files, runs + # commands and calls external APIs. POST /tasks/{task_id}/cancel exists and is + # NOT an undo: it stops further work. Everything already done stays done, and + # the model spend is already spent. + startTaskExecution: + reversibility: irreversible + reason: >- + Dispatches an autonomous agent that writes files, runs commands and calls + external APIs; cancel stops future work but undoes nothing already done + + # Arbitrary command execution in a sandbox. Whatever the command did — wrote, + # deleted, pushed, called — is done. Destroying the sandbox afterwards does not + # reach anything the command touched outside it. + executeCommandInSandbox: + reversibility: irreversible + reason: >- + Runs an arbitrary command; its effects are not confined to the sandbox and + nothing in this API undoes them + + # Same thing, in an agent's own container. + executeContainerCommand: + reversibility: irreversible + reason: >- + Runs an arbitrary command inside the agent container; no operation in this + API undoes what the command did + + # Feeds input into a LIVE Claude Code session that is acting on a repository. + # There is no un-send, and the session acts on the input immediately. + sendClaudeSessionInput: + reversibility: irreversible + reason: >- + Injects input into a live agent session that acts on it immediately; there + is no recall + + # Starts a multi-agent coordination session — i.e. dispatches SEVERAL agents. + # POST /coordination/{session_id}/cancel is the same non-undo as task cancel. + initiateTaskCoordination: + reversibility: irreversible + reason: >- + Dispatches multiple coordinating agents; cancelling the session does not + undo what they already did + + # Delivers a message from one agent to another, which the receiving agent acts + # on. No unsend, and the recipient may already have started work. + sendAgentCommunication: + reversibility: irreversible + reason: >- + Delivers a message another agent acts on; there is no unsend and the + recipient may already have acted + + # Posting to an agent conversation is how a human or another system TASKS that + # agent conversationally. Same shape as the above. + sendMessageToAgent: + reversibility: irreversible + reason: >- + A message to an agent is a request it acts on; nothing in this API recalls + it or undoes the resulting work + + # Answering an agent's blocked question unblocks it and it resumes acting. + submitHumanResponse: + reversibility: irreversible + reason: >- + Unblocks a waiting agent, which resumes acting immediately; the response + cannot be withdrawn + + # Provisions and starts a memory-enabled agent — a deployment, not a record. + deployMemoryEnabledAgent: + reversibility: irreversible + reason: >- + Provisions and starts a running agent; this API has no delete-agent + operation to reverse it + + # ========================================================================= + # IRREVERSIBLE — creates something the API cannot remove + # ========================================================================= + + # There is no DELETE /agents/{agent_id} anywhere in the contract. An agent, + # once created, is permanent from a caller's point of view. + createAgent: + reversibility: irreversible + reason: >- + This API has no delete-agent operation, so a created agent cannot be + removed by the caller + createAgentFromTemplate: + reversibility: irreversible + reason: >- + This API has no delete-agent operation, so a created agent cannot be + removed by the caller + + # There is no DELETE /tasks/{task_id}. Assigning a task also puts it in the + # agent's queue, so it can begin executing without a further call. + assignTask: + reversibility: irreversible + reason: >- + This API has no delete-task operation, and an assigned task enters the + agent's queue where it may begin executing + + # Stores a provider credential for an organization. There is no + # delete-credential operation, and the secret has left the caller's hands. + storeProviderCredentials: + reversibility: irreversible + reason: >- + Stores a provider secret with no corresponding delete operation in this + API + + # ========================================================================= + # EXPLICITLY REVERSIBLE — documented, not left to the default + # ========================================================================= + + # The one true undo in the contract. It restores a file batch that + # approveFileOperations applied. Marked reversible so it is not confused with + # the dispatch operations above. + rollbackFileOperations: + reversibility: reversible + reason: >- + This is the undo operation — it restores the files an approved batch + changed + + # The interesting one. Approving a file batch WRITES FILES, which sounds + # irreversible — but this contract contains the exact compensating operation, + # POST /tasks/{task_id}/file-operations/{batch_id}/rollback, and + # /file-operations/{batch_id}/preview lets the caller see the diff first. + # A compensating operation that actually exists is what "reversible" means, so + # this stays reversible rather than being marked dangerous by association. + approveFileOperations: + reversibility: reversible + reason: >- + The contract contains an explicit rollback for exactly this batch, plus a + preview to inspect it beforehand + + # DELETE defaults to irreversible; downgraded deliberately. A container is a + # runtime artefact re-created from the same agent definition by + # POST /agents/{agent_id}/container/create, so nothing is lost. + removeAgentContainer: + reversibility: reversible + reason: >- + A container is re-creatable from the same agent definition via + container/create; no durable state is destroyed + stopAgentContainer: + reversibility: reversible + reason: >- + container/start restarts it from the same definition + + # DELETE defaults to irreversible; downgraded. A sandbox is ephemeral by + # definition and a new one is provisioned on demand. (Note the CONTENTS are + # not recoverable — but a sandbox is scratch space, and the operation that + # matters, executeCommandInSandbox, is already marked irreversible above.) + destroySandbox: + reversibility: reversible + reason: >- + A sandbox is ephemeral scratch space and a fresh one is provisioned on + demand + + # DELETE defaults to irreversible; downgraded. Despite the DELETE verb and the + # /memory path, the handler STOPS the memory-enabled agent — it is the inverse + # of deployMemoryEnabledAgent, and that agent can be deployed again. Classified + # on what it does, not on the method or the path noun. + stopMemoryEnabledAgent: + reversibility: reversible + reason: >- + Despite the DELETE verb this stops a memory-enabled agent; it is the exact + inverse of deployMemoryEnabledAgent and the agent can be deployed again + + # Cancelling stops future work. It is reversible in the narrow sense that the + # task can be executed again — but it is pinned here mainly so nobody reads + # "cancel" as the undo for startTaskExecution. IT IS NOT. + cancelTaskExecution: + reversibility: reversible + reason: >- + Stops future work and the task can be re-executed. NOTE this is not an + undo for startTaskExecution — work already performed by the agent stands + cancelCoordination: + reversibility: reversible + reason: >- + Stops the coordination session; it can be initiated again. Not an undo for + work the agents already performed + + # ========================================================================= + # NOT overridden, and why (recorded so the absences are deliberate) + # ========================================================================= + # + # POST /rag/search (operationId searchKnowledgeContext) — already a read: the + # gateway's query-shaped-POST allowlist is a SUFFIX match and this path ends + # in /search. Confirmed by booting the gateway: mutates=false. No entry + # needed, and adding one would be noise. + # + # DELETE /knowledge/**/documents/{doc_id} (three of them) — left at the DELETE + # default, irreversible. Correct: there is no undelete, and a document's + # content is not re-derivable from anything else in this API. + # + # POST /rag/reindex, /rag/documents/{doc_id}/reindex — reversible writes by + # default, which is right: reindexing is idempotent and recomputable. + # + # POST /goals/**/generate-*, /conversations/**/extract-*, /milestones/**/ + # generate-* — reversible writes by default. They consume model spend and + # persist generated artefacts, so they are NOT reads; but the artefacts are + # product-internal records with no external effect, so not irreversible. + # + # POST /agents/{agent_id}/register, /agents/{agent_id}/error — reversible + # writes by default. Both are agent-lifecycle callbacks, idempotent by + # design. + # + # POST /mcp/call-tool — deliberately NOT downgraded and deliberately NOT + # marked irreversible. It is a PASSTHROUGH to whatever MCP server an agent + # has configured, so its reversibility is a property of the downstream tool + # and is unknowable from this contract. It keeps the reversible-write + # default, which is the least-wrong claim available; treating a passthrough + # as safe would be worse, and asserting irreversible for every call would + # dilute the label. Flagged in the PR body as a genuine gap. diff --git a/deploy/helm/fuzeagent/templates/mcp-gateway.yaml b/deploy/helm/fuzeagent/templates/mcp-gateway.yaml new file mode 100644 index 0000000..326a333 --- /dev/null +++ b/deploy/helm/fuzeagent/templates/mcp-gateway.yaml @@ -0,0 +1,123 @@ +{{- if .Values.mcp.enabled }} +{{/* +FuzeAgent MCP SSE gateway — the product's THIRD pod (backend, frontend, MCP). + +It runs the shared @fuzefront/mcp-gateway image, which contains no FuzeAgent +logic: everything that makes this pod "the FuzeAgent gateway" is the spec and +the upstream URL below. Other products deploy the same image with their own. + +The spec and the mutation overrides are mounted from a ConfigMap rendered out of +deploy/helm/fuzeagent/files/, which are COPIES of contracts/openapi.yaml and +mcp/tools.overrides.yaml. Helm cannot read files outside the chart directory, so +the copies are unavoidable — run scripts/sync-chart-files.sh --check to prove they +have not drifted (it exits non-zero if they have). +*/}} +apiVersion: v1 +kind: ConfigMap +metadata: + name: fuzeagent-mcp-spec + labels: + app.kubernetes.io/name: fuzeagent + app.kubernetes.io/component: mcp-gateway +data: + openapi.yaml: |- +{{ .Files.Get "files/openapi.yaml" | indent 4 }} + tools.overrides.yaml: |- +{{ .Files.Get "files/tools.overrides.yaml" | indent 4 }} +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: fuzeagent-mcp + labels: + app.kubernetes.io/name: fuzeagent + app.kubernetes.io/component: mcp-gateway +spec: + replicas: {{ .Values.mcp.replicaCount }} + selector: + matchLabels: + app: fuzeagent-mcp + template: + metadata: + labels: + app: fuzeagent-mcp + app.kubernetes.io/component: mcp-gateway + annotations: + # Roll the pod when the spec or the overrides change, otherwise a + # contract change would leave a stale tool surface serving indefinitely. + checksum/spec: {{ .Files.Get "files/openapi.yaml" | sha256sum }} + checksum/overrides: {{ .Files.Get "files/tools.overrides.yaml" | sha256sum }} + spec: + {{- with .Values.imagePullSecrets }} + imagePullSecrets: + {{- toYaml . | nindent 8 }} + {{- end }} + containers: + - name: mcp-gateway + image: "{{ .Values.mcp.image.repository }}:{{ .Values.mcp.image.tag }}" + imagePullPolicy: {{ .Values.mcp.image.pullPolicy }} + ports: + - name: http + containerPort: {{ .Values.mcp.port }} + env: + - name: MCP_PRODUCT + value: agent + # In-cluster base URL of the FuzeAgent REST API. The gateway makes + # every upstream call here, carrying the CALLER'S bearer token. + - name: MCP_UPSTREAM_BASE_URL + value: {{ .Values.mcp.upstreamBaseUrl | quote }} + - name: MCP_OPENAPI_SPEC + value: /spec/openapi.yaml + - name: MCP_TOOL_OVERRIDES + value: /spec/tools.overrides.yaml + - name: PORT + value: {{ .Values.mcp.port | quote }} + # DELIBERATELY no credential env var. The gateway forwards the caller's + # identity and holds none of its own; it refuses to start if a service + # token is present, because a shared token would bypass every per-user + # Permit check on the FuzeAgent API. + readinessProbe: + httpGet: + path: /healthz + port: http + initialDelaySeconds: 5 + periodSeconds: 10 + failureThreshold: 6 + livenessProbe: + httpGet: + path: /healthz + port: http + initialDelaySeconds: 15 + periodSeconds: 15 + resources: + {{- toYaml .Values.mcp.resources | nindent 12 }} + securityContext: + allowPrivilegeEscalation: false + readOnlyRootFilesystem: true + capabilities: + drop: ["ALL"] + volumeMounts: + - name: spec + mountPath: /spec + readOnly: true + volumes: + - name: spec + configMap: + name: fuzeagent-mcp-spec +--- +apiVersion: v1 +kind: Service +metadata: + name: fuzeagent-mcp + labels: + app.kubernetes.io/name: fuzeagent + app.kubernetes.io/component: mcp-gateway +spec: + type: ClusterIP + selector: + app: fuzeagent-mcp + ports: + - name: http + port: {{ .Values.mcp.port }} + targetPort: http +{{- end }} diff --git a/deploy/helm/fuzeagent/templates/orchestrator.yaml b/deploy/helm/fuzeagent/templates/orchestrator.yaml index 7941cc8..09b7af3 100644 --- a/deploy/helm/fuzeagent/templates/orchestrator.yaml +++ b/deploy/helm/fuzeagent/templates/orchestrator.yaml @@ -33,6 +33,14 @@ spec: containerPort: {{ .Values.orchestrator.port }} env: {{- include "fuzeagent.backendEnv" . | nindent 12 }} + # The contract GET /openapi.yaml serves. Baked into the IMAGE + # (services/orchestrator/contracts/openapi.yaml — a drift-checked + # copy, because the image is built with `context: + # services/orchestrator`, so the repo-root contracts/ tree is not in + # the build context) rather than mounted, so what the API publishes + # is always the spec this build was compiled against. + - name: OPENAPI_SPEC_PATH + value: /app/contracts/openapi.yaml - name: RUN_MIGRATIONS value: {{ .Values.orchestrator.runMigrations | quote }} - name: ENABLE_AUTONOMOUS_EXECUTION diff --git a/deploy/helm/fuzeagent/values.yaml b/deploy/helm/fuzeagent/values.yaml index 9a5792f..e0ce3f9 100644 --- a/deploy/helm/fuzeagent/values.yaml +++ b/deploy/helm/fuzeagent/values.yaml @@ -136,3 +136,53 @@ resourceGovernance: defaultMemory: 512Mi defaultRequestCpu: 100m defaultRequestMemory: 128Mi + +# --------------------------------------------------------------------------- +# MCP SSE gateway — the config-driven @fuzefront/mcp-gateway pod. +# +# NOTE the distinction from `mcpServer` above. They are NOT the same thing and +# both are real: +# +# mcpServer mcp-servers/fuzeagent-server — a HAND-WRITTEN MCP SSE server with +# ~15 curated tools over the hierarchy API. It ships today, and it +# carries NO mutates/reversibility classification at all +# (.fuze/manifest.json says so explicitly: "Outstanding: a +# tools.json declaring `mutates` per tool"). +# mcp THIS one — the shared gateway image, configured with +# contracts/openapi.yaml + mcp/tools.overrides.yaml, which derives +# the classification mechanically and REFUSES TO BOOT on a +# self-contradictory one. +# +# That difference matters more on FuzeAgent than anywhere else in the family: +# this API dispatches agents that take real actions. A tool surface that +# presents `startTaskExecution` without saying it cannot be recalled is the +# specific failure the classification exists to prevent. +# +# Whether the hand-written server should be retired in favour of this pod is an +# owner decision, not a deployment one — both are left as they are, and the +# overlap is flagged in the PR body rather than resolved silently. +# +# Disabled by default: flipping it needs ghcr.io/izzywdev/fuze-mcp-gateway in +# GHCR, which NO workflow in this repo builds (it is FuzeFront's image). +# --------------------------------------------------------------------------- +mcp: + enabled: false + replicaCount: 1 + port: 8081 + image: + repository: ghcr.io/izzywdev/fuze-mcp-gateway + tag: "0.1.0" + pullPolicy: IfNotPresent + # In-cluster base URL of the ORCHESTRATOR. No path segment: the app serves + # absolute paths with no common prefix, which is what + # `servers: [{url: /}]` in contracts/openapi.yaml declares. `orchestrator` is + # the Service created by templates/orchestrator.yaml. + # + # NOT the hierarchy API. services/hierarchy_API is a SECOND backend on a + # second Service (port 8006) with its own ~40 routes, and one gateway pod + # maps to exactly one spec and one upstream. Covering it needs its own + # contract and its own pod — see contracts/README.md. + upstreamBaseUrl: "http://orchestrator:8000" + resources: + requests: { cpu: 50m, memory: 64Mi } + limits: { cpu: 500m, memory: 256Mi } diff --git a/mcp/tools.overrides.yaml b/mcp/tools.overrides.yaml new file mode 100644 index 0000000..b8e1f19 --- /dev/null +++ b/mcp/tools.overrides.yaml @@ -0,0 +1,258 @@ +# ============================================================================= +# FuzeAgent — MCP tool mutation overrides. +# +# Consumed by @fuzefront/mcp-gateway. The gateway derives `mutates` from the HTTP +# method (GET/HEAD/OPTIONS = read; POST to a path ending /search, /query or +# /preview = read; DELETE = irreversible write; everything else = reversible +# write) and only needs this file where the method alone gets it WRONG. +# +# ON THIS API THE METHOD GETS IT WRONG A LOT, and the reason is the whole point +# of FuzeAgent: it DISPATCHES AGENTS THAT TAKE REAL ACTIONS. An agent writes +# files, runs shell commands in a container, calls third-party APIs and spends +# money on model inference. The HTTP response to "execute this task" arrives in +# milliseconds; the consequences do not stop there. +# +# So the classification here is on EFFECT, never on verb: +# +# * a POST that starts an agent is IRREVERSIBLE, even though POST defaults to +# reversible — cancelling stops FUTURE work, it does not undo work done; +# * a POST ending /search is a read, and the gateway already knows that; +# * a DELETE of a container is REVERSIBLE, because the container is +# re-creatable from the same agent definition. +# +# `reversibility` means, precisely: is there an operation IN THIS CONTRACT that +# the caller can invoke to undo the effect? Not "could a human repair it". +# +# The gateway REFUSES TO START if an entry declares something irreversible while +# also declaring it a read, or relabels a non-query-shaped POST as a read. +# +# VERIFIED, not asserted: this file was loaded by the real @fuzefront/mcp-gateway +# from the exact ConfigMap bytes `helm template` renders. 142 tools enumerate, +# 74 reads / 68 writes, 16 irreversible, no tool is both a read and +# irreversible, and startTaskExecution's description reaches the model prefixed +# "[WRITE — IRREVERSIBLE]". +# +# STANDING FACTS about this API that shape the list below: +# 1. There is NO `DELETE /agents/{agent_id}` and NO `DELETE /tasks/{task_id}`. +# A created agent and a created task are permanent as far as this API is +# concerned. +# 2. The only genuine undo operation anywhere in the contract is +# POST /tasks/{task_id}/file-operations/{batch_id}/rollback. It undoes an +# approved FILE batch and nothing else. +# ============================================================================= + +tools: + # ========================================================================= + # IRREVERSIBLE — dispatches an agent, or executes a command + # ========================================================================= + + # THE canonical case, and the reason this file is written the way it is. + # Starting execution hands the task to an agent that writes files, runs + # commands and calls external APIs. POST /tasks/{task_id}/cancel exists and is + # NOT an undo: it stops further work. Everything already done stays done, and + # the model spend is already spent. + startTaskExecution: + reversibility: irreversible + reason: >- + Dispatches an autonomous agent that writes files, runs commands and calls + external APIs; cancel stops future work but undoes nothing already done + + # Arbitrary command execution in a sandbox. Whatever the command did — wrote, + # deleted, pushed, called — is done. Destroying the sandbox afterwards does not + # reach anything the command touched outside it. + executeCommandInSandbox: + reversibility: irreversible + reason: >- + Runs an arbitrary command; its effects are not confined to the sandbox and + nothing in this API undoes them + + # Same thing, in an agent's own container. + executeContainerCommand: + reversibility: irreversible + reason: >- + Runs an arbitrary command inside the agent container; no operation in this + API undoes what the command did + + # Feeds input into a LIVE Claude Code session that is acting on a repository. + # There is no un-send, and the session acts on the input immediately. + sendClaudeSessionInput: + reversibility: irreversible + reason: >- + Injects input into a live agent session that acts on it immediately; there + is no recall + + # Starts a multi-agent coordination session — i.e. dispatches SEVERAL agents. + # POST /coordination/{session_id}/cancel is the same non-undo as task cancel. + initiateTaskCoordination: + reversibility: irreversible + reason: >- + Dispatches multiple coordinating agents; cancelling the session does not + undo what they already did + + # Delivers a message from one agent to another, which the receiving agent acts + # on. No unsend, and the recipient may already have started work. + sendAgentCommunication: + reversibility: irreversible + reason: >- + Delivers a message another agent acts on; there is no unsend and the + recipient may already have acted + + # Posting to an agent conversation is how a human or another system TASKS that + # agent conversationally. Same shape as the above. + sendMessageToAgent: + reversibility: irreversible + reason: >- + A message to an agent is a request it acts on; nothing in this API recalls + it or undoes the resulting work + + # Answering an agent's blocked question unblocks it and it resumes acting. + submitHumanResponse: + reversibility: irreversible + reason: >- + Unblocks a waiting agent, which resumes acting immediately; the response + cannot be withdrawn + + # Provisions and starts a memory-enabled agent — a deployment, not a record. + deployMemoryEnabledAgent: + reversibility: irreversible + reason: >- + Provisions and starts a running agent; this API has no delete-agent + operation to reverse it + + # ========================================================================= + # IRREVERSIBLE — creates something the API cannot remove + # ========================================================================= + + # There is no DELETE /agents/{agent_id} anywhere in the contract. An agent, + # once created, is permanent from a caller's point of view. + createAgent: + reversibility: irreversible + reason: >- + This API has no delete-agent operation, so a created agent cannot be + removed by the caller + createAgentFromTemplate: + reversibility: irreversible + reason: >- + This API has no delete-agent operation, so a created agent cannot be + removed by the caller + + # There is no DELETE /tasks/{task_id}. Assigning a task also puts it in the + # agent's queue, so it can begin executing without a further call. + assignTask: + reversibility: irreversible + reason: >- + This API has no delete-task operation, and an assigned task enters the + agent's queue where it may begin executing + + # Stores a provider credential for an organization. There is no + # delete-credential operation, and the secret has left the caller's hands. + storeProviderCredentials: + reversibility: irreversible + reason: >- + Stores a provider secret with no corresponding delete operation in this + API + + # ========================================================================= + # EXPLICITLY REVERSIBLE — documented, not left to the default + # ========================================================================= + + # The one true undo in the contract. It restores a file batch that + # approveFileOperations applied. Marked reversible so it is not confused with + # the dispatch operations above. + rollbackFileOperations: + reversibility: reversible + reason: >- + This is the undo operation — it restores the files an approved batch + changed + + # The interesting one. Approving a file batch WRITES FILES, which sounds + # irreversible — but this contract contains the exact compensating operation, + # POST /tasks/{task_id}/file-operations/{batch_id}/rollback, and + # /file-operations/{batch_id}/preview lets the caller see the diff first. + # A compensating operation that actually exists is what "reversible" means, so + # this stays reversible rather than being marked dangerous by association. + approveFileOperations: + reversibility: reversible + reason: >- + The contract contains an explicit rollback for exactly this batch, plus a + preview to inspect it beforehand + + # DELETE defaults to irreversible; downgraded deliberately. A container is a + # runtime artefact re-created from the same agent definition by + # POST /agents/{agent_id}/container/create, so nothing is lost. + removeAgentContainer: + reversibility: reversible + reason: >- + A container is re-creatable from the same agent definition via + container/create; no durable state is destroyed + stopAgentContainer: + reversibility: reversible + reason: >- + container/start restarts it from the same definition + + # DELETE defaults to irreversible; downgraded. A sandbox is ephemeral by + # definition and a new one is provisioned on demand. (Note the CONTENTS are + # not recoverable — but a sandbox is scratch space, and the operation that + # matters, executeCommandInSandbox, is already marked irreversible above.) + destroySandbox: + reversibility: reversible + reason: >- + A sandbox is ephemeral scratch space and a fresh one is provisioned on + demand + + # DELETE defaults to irreversible; downgraded. Despite the DELETE verb and the + # /memory path, the handler STOPS the memory-enabled agent — it is the inverse + # of deployMemoryEnabledAgent, and that agent can be deployed again. Classified + # on what it does, not on the method or the path noun. + stopMemoryEnabledAgent: + reversibility: reversible + reason: >- + Despite the DELETE verb this stops a memory-enabled agent; it is the exact + inverse of deployMemoryEnabledAgent and the agent can be deployed again + + # Cancelling stops future work. It is reversible in the narrow sense that the + # task can be executed again — but it is pinned here mainly so nobody reads + # "cancel" as the undo for startTaskExecution. IT IS NOT. + cancelTaskExecution: + reversibility: reversible + reason: >- + Stops future work and the task can be re-executed. NOTE this is not an + undo for startTaskExecution — work already performed by the agent stands + cancelCoordination: + reversibility: reversible + reason: >- + Stops the coordination session; it can be initiated again. Not an undo for + work the agents already performed + + # ========================================================================= + # NOT overridden, and why (recorded so the absences are deliberate) + # ========================================================================= + # + # POST /rag/search (operationId searchKnowledgeContext) — already a read: the + # gateway's query-shaped-POST allowlist is a SUFFIX match and this path ends + # in /search. Confirmed by booting the gateway: mutates=false. No entry + # needed, and adding one would be noise. + # + # DELETE /knowledge/**/documents/{doc_id} (three of them) — left at the DELETE + # default, irreversible. Correct: there is no undelete, and a document's + # content is not re-derivable from anything else in this API. + # + # POST /rag/reindex, /rag/documents/{doc_id}/reindex — reversible writes by + # default, which is right: reindexing is idempotent and recomputable. + # + # POST /goals/**/generate-*, /conversations/**/extract-*, /milestones/**/ + # generate-* — reversible writes by default. They consume model spend and + # persist generated artefacts, so they are NOT reads; but the artefacts are + # product-internal records with no external effect, so not irreversible. + # + # POST /agents/{agent_id}/register, /agents/{agent_id}/error — reversible + # writes by default. Both are agent-lifecycle callbacks, idempotent by + # design. + # + # POST /mcp/call-tool — deliberately NOT downgraded and deliberately NOT + # marked irreversible. It is a PASSTHROUGH to whatever MCP server an agent + # has configured, so its reversibility is a property of the downstream tool + # and is unknowable from this contract. It keeps the reversible-write + # default, which is the least-wrong claim available; treating a passthrough + # as safe would be worse, and asserting irreversible for every call would + # dilute the label. Flagged in the PR body as a genuine gap. diff --git a/registration/manifest.json b/registration/manifest.json index 7474c5b..8ca773d 100644 --- a/registration/manifest.json +++ b/registration/manifest.json @@ -1,7 +1,7 @@ { "manifestVersion": "1", - "slug": "fuzeagent", - "name": "FuzeAgent", + "slug": "agent", + "name": "Agent", "menuLabel": "Agents", "description": "AI team orchestration — autonomous agents (Claude Code SDK + CrewAI) organised into teams and coordinated by a digital CEO.", "icon": { "kind": "emoji", "value": "🤖" }, diff --git a/scripts/check-rendered-chart.py b/scripts/check-rendered-chart.py new file mode 100755 index 0000000..647b74e --- /dev/null +++ b/scripts/check-rendered-chart.py @@ -0,0 +1,67 @@ +#!/usr/bin/env python3 +"""Assert properties of a rendered Helm chart that a lint cannot see. + + 1. Every Service selects EXACTLY ONE workload. A selector that matches two + Deployments silently round-robins API traffic into the wrong container + (e.g. into nginx and back); a selector that matches zero is a Service with + no endpoints, which looks fine until a call times out. + 2. No container image resolves to an empty repository or tag. + 3. Every probe targets a port the container actually declares. +""" +import sys, yaml + +def labels_match(selector, labels): + return all(labels.get(k) == v for k, v in (selector or {}).items()) + +def main(path): + docs = [d for d in yaml.safe_load_all(open(path)) if d] + workloads = [] # (kind, name, podLabels) + services = [] + problems = [] + for d in docs: + k = d.get('kind') + if k in ('Deployment', 'StatefulSet', 'DaemonSet'): + workloads.append((k, d['metadata']['name'], + (d['spec']['template']['metadata'].get('labels') or {}), + d)) + elif k == 'Service': + services.append(d) + + for svc in services: + sel = svc['spec'].get('selector') + name = svc['metadata']['name'] + if not sel: + problems.append(f"Service {name}: no selector at all") + continue + hits = [w[1] for w in workloads if labels_match(sel, w[2])] + if len(hits) != 1: + problems.append( + f"Service {name}: selector {sel} matches {len(hits)} workloads {hits} (expected exactly 1)") + else: + print(f" OK Service {name:34} -> {hits[0]}") + + for kind, name, _lab, d in workloads: + for c in d['spec']['template']['spec'].get('containers', []): + img = c.get('image', '') + if not img or img.endswith(':') or img.startswith(':'): + problems.append(f"{kind} {name}/{c['name']}: bad image {img!r}") + declared = {p.get('name') for p in (c.get('ports') or [])} | { + p.get('containerPort') for p in (c.get('ports') or [])} + for probe in ('readinessProbe', 'livenessProbe', 'startupProbe'): + hp = (c.get(probe) or {}).get('httpGet') + if hp and hp.get('port') not in declared: + problems.append( + f"{kind} {name}/{c['name']}: {probe} targets port {hp.get('port')!r}, " + f"container declares {sorted(x for x in declared if x is not None)}") + + print(f" {len(workloads)} workload(s), {len(services)} service(s)") + if problems: + print("\nPROBLEMS:") + for p in problems: + print(" ✗", p) + return 1 + print(" all assertions passed") + return 0 + +if __name__ == '__main__': + sys.exit(main(sys.argv[1])) diff --git a/scripts/sync-chart-files.sh b/scripts/sync-chart-files.sh new file mode 100755 index 0000000..4952929 --- /dev/null +++ b/scripts/sync-chart-files.sh @@ -0,0 +1,59 @@ +#!/usr/bin/env bash +# ============================================================================= +# Keep the mechanical copies of contracts/openapi.yaml in sync with the source. +# +# Two forced copies, for two different reasons, both silent failures if stale: +# +# services/orchestrator/contracts/openapi.yaml +# The orchestrator image is built with `context: services/orchestrator` +# (.github/workflows/release.yml), so the repo-root contracts/ tree is not +# in the build context at all. This copy ships in the image and is what +# GET /openapi.yaml serves. A stale copy makes the deployed API publish a +# contract for a different build. +# +# deploy/helm/fuzeagent/files/{openapi.yaml,tools.overrides.yaml} +# Helm can only read files inside the chart directory. These are what the +# MCP gateway pod mounts. A stale OVERRIDES copy is the dangerous one on +# this repo: it would serve `startTaskExecution` to a model as an ordinary +# reversible write, when it dispatches an agent that cannot be recalled. +# +# scripts/sync-chart-files.sh copy source -> copies +# scripts/sync-chart-files.sh --check fail if they differ (for CI) +# ============================================================================= +set -euo pipefail + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" + +SPEC="$ROOT/contracts/openapi.yaml" +OVERRIDES="$ROOT/mcp/tools.overrides.yaml" +DESTS=( + "$ROOT/services/orchestrator/contracts/openapi.yaml:$SPEC" + "$ROOT/deploy/helm/fuzeagent/files/openapi.yaml:$SPEC" + "$ROOT/deploy/helm/fuzeagent/files/tools.overrides.yaml:$OVERRIDES" +) + +if [[ "${1:-}" == "--check" ]]; then + status=0 + for pair in "${DESTS[@]}"; do + dst="${pair%%:*}"; src="${pair#*:}" + if ! diff -q "$src" "$dst" >/dev/null 2>&1; then + echo "DRIFT: ${dst#"$ROOT"/} differs from ${src#"$ROOT"/}" + diff -u "$dst" "$src" | head -40 || true + status=1 + fi + done + if [[ $status -eq 0 ]]; then + echo "Chart/image file copies are in sync." + else + echo + echo "Run scripts/sync-chart-files.sh to update the copies, then commit them." + fi + exit $status +fi + +for pair in "${DESTS[@]}"; do + dst="${pair%%:*}"; src="${pair#*:}" + mkdir -p "$(dirname "$dst")" + cp "$src" "$dst" + echo "synced ${dst#"$ROOT"/}" +done diff --git a/services/orchestrator/contracts/openapi.yaml b/services/orchestrator/contracts/openapi.yaml new file mode 100644 index 0000000..7881015 --- /dev/null +++ b/services/orchestrator/contracts/openapi.yaml @@ -0,0 +1,5649 @@ +openapi: 3.1.0 +info: + title: FuzeAgent Orchestrator API + version: 0.1.0 + summary: The HTTP surface the deployed FuzeAgent orchestrator actually serves. + description: >- + FuzeAgent orchestrates autonomous AI agents: it creates agents, assigns them tasks, + EXECUTES those tasks in containers and sandboxes, brokers agent-to-agent + communication, and manages the knowledge and goal state behind all of it. + + + WHAT THIS DOCUMENT IS. It describes the routes served by + `services/orchestrator/main.py` — the FastAPI application the Helm chart deploys as + the `orchestrator` pod on port 8000, reachable in-cluster at + http://orchestrator:8000. Every path was read off an `@app.` decorator by + static analysis; the summaries are the handlers' own docstrings. Nothing here is + aspirational. + + + THE ONE THING TO UNDERSTAND BEFORE CALLING ANYTHING. FuzeAgent is not a CRUD API + with a dangerous corner. Its core purpose is to DISPATCH AGENTS THAT TAKE REAL + ACTIONS — they write files, run shell commands in containers, call third-party + APIs and spend money on model inference. `POST /tasks/{task_id}/execute` is the + canonical case: it returns quickly, and by the time it has, an agent is running. + Cancelling it stops future work; it does not undo work already done. Operations of + that shape are marked irreversible in `mcp/tools.overrides.yaml` regardless of + their HTTP verb, because the verb says nothing about whether the effect can be + taken back. + + + WHAT IT IS NOT. FuzeAgent deploys a SECOND backend, `services/hierarchy_API` + (the `hierarchy-api` pod, port 8006), with roughly forty of its own routes for + organizations, teams and agent hierarchy. It is a separate FastAPI application on + a separate Service and is NOT covered by this document; a single OpenAPI document + maps to a single upstream base URL, so it would need its own contract and its own + gateway pod. See `contracts/README.md`. + + + AUTHENTICATION. Bearer token, resolved through the FuzeFront Security API when + `SECURITY_BASE_URL` is configured (`services/orchestrator/fuze_security.py`), with + a local JWT fallback otherwise. `main:app` fails closed at boot without either. + contact: + name: FuzeAgent + url: https://github.com/izzywdev/FuzeAgent + license: + name: UNLICENSED +servers: + - url: / + description: >- + The orchestrator serves absolute paths with no common prefix, so the base URL + carries no path segment. In-cluster: http://orchestrator:8000. +tags: + - name: Platform + description: Health, websocket stats and system dashboards. + - name: Agents + description: Creating, inspecting and configuring agents. + - name: Tasks + description: >- + Assigning and EXECUTING work. The operations here are the ones that make an + agent act on the world. + - name: Containers + description: Per-agent container lifecycle and in-container command execution. + - name: Sandboxes + description: Sandbox lifecycle and arbitrary command execution inside one. + - name: Coordination + description: Multi-agent coordination sessions and agent-to-agent messaging. + - name: Conversations + description: Agent conversations and the derived artefacts (milestones, action items). + - name: Goals + description: Organizational goals, milestones and progress tracking. + - name: Knowledge + description: Documents, RAG index and knowledge analytics. + - name: Context + description: Agent interaction context. + - name: MCP passthrough + description: >- + The orchestrator's own MCP client surface — listing and calling tools of MCP + servers the AGENTS use. Not to be confused with FuzeAgent's MCP gateway pod, + which exposes THIS API as MCP tools. + - name: Organizations + description: Organization-scoped model, provider and dashboard configuration. +paths: + "/health": + get: + operationId: healthCheck + tags: ["Platform"] + summary: "Health Check" + description: + |- + Health check endpoint that returns the current status of the orchestrator service. + + Returns: + dict: Service health status and basic information + security: [] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents": + post: + operationId: createAgent + tags: ["Agents"] + summary: "Create AI Agent" + description: + |- + Create a new AI agent with repository and sandbox settings + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "AgentCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listAgents + tags: ["Agents"] + summary: "List All Agents" + description: + |- + List all agents and their status + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/tasks": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: assignTask + tags: ["Tasks"] + summary: "Assign Task to Agent" + description: + |- + Assign a task to an agent + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "TaskCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: getAgentTasks + tags: ["Tasks"] + summary: "Get tasks assigned to an agent" + description: + |- + Get tasks assigned to an agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/status": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentStatus + tags: ["Agents"] + summary: "Get detailed agent status" + description: + |- + Get detailed agent status + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/teams": + get: + operationId: listTeams + tags: ["Platform"] + summary: "List all teams" + description: + |- + List all teams + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agent-templates": + get: + operationId: listAgentTemplates + tags: ["Agents"] + summary: "List available agent templates" + description: + |- + List available agent templates + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks": + get: + operationId: listTasks + tags: ["Tasks"] + summary: "List all tasks" + description: + |- + List all tasks + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTask + tags: ["Tasks"] + summary: "Get task details" + description: + |- + Get task details + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateTask + tags: ["Tasks"] + summary: "Update task status and result" + description: + |- + Update task status and result + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/from-template": + post: + operationId: createAgentFromTemplate + tags: ["Agents"] + summary: "Create agent from template with repository settings" + description: + |- + Create agent from template with repository settings + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/templates": + get: + operationId: getAgentTemplates + tags: ["Agents"] + summary: "Get available agent templates" + description: + |- + Get available agent templates + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/execute": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: startTaskExecution + tags: ["Tasks"] + summary: "Start Autonomous Task Execution" + description: + |- + Start autonomous execution of a task + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/status": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskExecutionStatus + tags: ["Tasks"] + summary: "Get detailed task execution status" + description: + |- + Get detailed task execution status + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateTaskStatus + tags: ["Tasks"] + summary: "Update Task Status" + description: + |- + Update task status - used by memory-enabled agents to report progress + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/iterations": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskIterations + tags: ["Tasks"] + summary: "Get task iteration history" + description: + |- + Get task iteration history + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/sandbox": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentSandbox + tags: ["Agents"] + summary: "Get agent sandbox information" + description: + |- + Get agent sandbox information + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/context/interactions": + post: + operationId: storeInteraction + tags: ["Context"] + summary: "Store agent interaction" + description: + |- + Store agent interaction + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/context": + get: + operationId: getContext + tags: ["Context"] + summary: "Get relevant context for a query" + description: + |- + Get relevant context for a query + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/memory": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentMemory + tags: ["Agents"] + summary: "Get agent memory" + description: + |- + Get agent memory + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + delete: + operationId: stopMemoryEnabledAgent + tags: ["Agents"] + summary: "Stop Memory-Enabled Agent" + description: + |- + Stop and clean up a memory-enabled agent container + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/conversations": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentConversations + tags: ["Conversations"] + summary: "Get Agent Conversations" + description: + |- + Get all conversations for a specific agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + post: + operationId: createAgentConversation + tags: ["Conversations"] + summary: "Create New Agent Conversation" + description: + |- + Create a new conversation with an agent + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ConversationCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/conversations/{conversation_id}/messages": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + get: + operationId: getConversationMessages + tags: ["Conversations"] + summary: "Get Conversation Messages" + description: + |- + Get all messages in a conversation + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + post: + operationId: sendMessageToAgent + tags: ["Conversations"] + summary: "Send Message to Agent" + description: + |- + Send a message to an agent in a conversation + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ChatMessageRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/search": + get: + operationId: searchKnowledge + tags: ["Knowledge"] + summary: "Search knowledge base" + description: + |- + Search knowledge base + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/human-response": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: submitHumanResponse + tags: ["Tasks"] + summary: "Submit Human Response" + description: + |- + Submit human response to a task question + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "HumanResponseRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/cancel": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: cancelTaskExecution + tags: ["Tasks"] + summary: "Cancel autonomous execution of a task" + description: + |- + Cancel autonomous execution of a task + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/messages": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskMessages + tags: ["Tasks"] + summary: "Get task messages and chat history" + description: + |- + Get task messages and chat history + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/sandboxes": + get: + operationId: listSandboxes + tags: ["Sandboxes"] + summary: "List active sandboxes" + description: + |- + List active sandboxes + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/sandboxes/{sandbox_id}/execute": + parameters: + - name: sandbox_id + in: path + required: true + description: "Sandbox id." + schema: { type: string } + post: + operationId: executeCommandInSandbox + tags: ["Sandboxes"] + summary: "Execute a command in a sandbox" + description: + |- + Execute a command in a sandbox + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/sandboxes/{sandbox_id}": + parameters: + - name: sandbox_id + in: path + required: true + description: "Sandbox id." + schema: { type: string } + delete: + operationId: destroySandbox + tags: ["Sandboxes"] + summary: "Destroy a sandbox" + description: + |- + Destroy a sandbox + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/register": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: registerAgent + tags: ["Agents"] + summary: "Register an agent running in a sandbox container" + description: + |- + Register an agent running in a sandbox container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/next-task": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getNextTaskForAgent + tags: ["Agents"] + summary: "Get the next task for an agent to execute" + description: + |- + Get the next task for an agent to execute + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/error": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: reportAgentError + tags: ["Agents"] + summary: "Report an error from an agent" + description: + |- + Report an error from an agent + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/conversation": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskConversation + tags: ["Tasks"] + summary: "Get conversation history for a task" + description: + |- + Get conversation history for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/conversation/summary": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getConversationSummary + tags: ["Tasks"] + summary: "Get conversation summary with statistics" + description: + |- + Get conversation summary with statistics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/code-generations": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskCodeGenerations + tags: ["Tasks"] + summary: "Get code generations for a task" + description: + |- + Get code generations for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/performance": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentPerformance + tags: ["Agents"] + summary: "Get agent performance metrics" + description: + |- + Get agent performance metrics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/file-operations": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskFileOperations + tags: ["Tasks"] + summary: "Get File Operations" + description: + |- + Get file operations for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/file-operations/{batch_id}/preview": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + - name: batch_id + in: path + required: true + description: "Batch id." + schema: { type: string } + get: + operationId: getFileOperationsPreview + tags: ["Tasks"] + summary: "Get preview of file changes for a batch" + description: + |- + Get preview of file changes for a batch + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/file-operations/{batch_id}/approve": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + - name: batch_id + in: path + required: true + description: "Batch id." + schema: { type: string } + post: + operationId: approveFileOperations + tags: ["Tasks"] + summary: "Approve File Operations" + description: + |- + Approve or reject file operations + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "FileOperationApprovalRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/file-operations/{batch_id}/rollback": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + - name: batch_id + in: path + required: true + description: "Batch id." + schema: { type: string } + post: + operationId: rollbackFileOperations + tags: ["Tasks"] + summary: "Rollback applied file operations" + description: + |- + Rollback applied file operations + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/claude-session": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getClaudeSessionStatus + tags: ["Tasks"] + summary: "Get Claude SDK session status for a task" + description: + |- + Get Claude SDK session status for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/claude-session/input": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: sendClaudeSessionInput + tags: ["Tasks"] + summary: "Send input to Claude SDK session" + description: + |- + Send input to Claude SDK session + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/mcp/tools": + get: + operationId: getMcpTools + tags: ["MCP passthrough"] + summary: "Get available MCP tools" + description: + |- + Get available MCP tools + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/mcp/call-tool": + post: + operationId: callMcpTool + tags: ["MCP passthrough"] + summary: "Call MCP Tool" + description: + |- + Call an MCP tool + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "MCPToolRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/mcp/resources": + get: + operationId: getMcpResources + tags: ["MCP passthrough"] + summary: "Get available MCP resources" + description: + |- + Get available MCP resources + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/mcp/resource": + get: + operationId: getMcpResource + tags: ["MCP passthrough"] + summary: "Get an MCP resource by URI" + description: + |- + Get an MCP resource by URI + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/mcp-context": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + get: + operationId: getTaskMcpContext + tags: ["Tasks"] + summary: "Get MCP context for a task" + description: + |- + Get MCP context for a task + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/mcp-setup": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: setupAgentMcp + tags: ["Agents"] + summary: "Setup Agent MCP Integration" + description: + |- + Set up MCP integration for an agent + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "AgentMCPSetupRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/tasks/{task_id}/coordinate": + parameters: + - name: task_id + in: path + required: true + description: "Task id." + schema: { type: string } + post: + operationId: initiateTaskCoordination + tags: ["Tasks"] + summary: "Initiate Multi-Agent Coordination" + description: + |- + Initiate multi-agent coordination for a complex task + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "CoordinationRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/coordination/{session_id}": + parameters: + - name: session_id + in: path + required: true + description: "Session id." + schema: { type: string } + get: + operationId: getCoordinationStatus + tags: ["Coordination"] + summary: "Get status of a coordination session" + description: + |- + Get status of a coordination session + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/coordination/{session_id}/cancel": + parameters: + - name: session_id + in: path + required: true + description: "Session id." + schema: { type: string } + post: + operationId: cancelCoordination + tags: ["Coordination"] + summary: "Cancel a coordination session" + description: + |- + Cancel a coordination session + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{from_agent_id}/communicate/{to_agent_id}": + parameters: + - name: from_agent_id + in: path + required: true + description: "From agent id." + schema: { type: string } + - name: to_agent_id + in: path + required: true + description: "To agent id." + schema: { type: string } + post: + operationId: sendAgentCommunication + tags: ["Agents"] + summary: "Send communication between agents" + description: + |- + Send communication between agents + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/coordination/active": + get: + operationId: getActiveCoordinations + tags: ["Coordination"] + summary: "Get all active coordination sessions" + description: + |- + Get all active coordination sessions + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/providers/{provider}/credentials": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + - name: provider + in: path + required: true + description: "Provider." + schema: { type: string } + post: + operationId: storeProviderCredentials + tags: ["Organizations"] + summary: "Store Provider API Credentials" + description: + |- + Store encrypted API credentials for a model provider at organization level + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ProviderCredentialsRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/models": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getAvailableModels + tags: ["Organizations"] + summary: "Get Available Models" + description: + |- + Get available AI models with provider credential validation + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/model-configuration": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: configureAgentModel + tags: ["Agents"] + summary: "Configure Agent Model Settings" + description: + |- + Configure model settings for an AI agent + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "AgentModelConfigRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: getAgentModelConfiguration + tags: ["Agents"] + summary: "Get Agent Model Configuration" + description: + |- + Get model configuration for an AI agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/tasks/cost-estimate": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: estimateTaskCost + tags: ["Tasks"] + summary: "Estimate Task Cost" + description: + |- + Estimate cost for task execution based on agent's model configuration + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "TaskCostEstimateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/model-usage": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getOrganizationModelUsage + tags: ["Organizations"] + summary: "Get Model Usage Statistics" + description: + |- + Get model usage statistics and costs for an organization + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/model-recommendations": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getModelRecommendations + tags: ["Agents"] + summary: "Get Model Recommendations" + description: + |- + Get model recommendations based on task capabilities and cost constraints + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/notifications/{recipient_type}/{recipient_id}": + parameters: + - name: recipient_type + in: path + required: true + description: "Recipient type." + schema: { type: string } + - name: recipient_id + in: path + required: true + description: "Recipient id." + schema: { type: string } + get: + operationId: getKnowledgeNotifications + tags: ["Knowledge"] + summary: "Get Knowledge Notifications" + description: + |- + Get knowledge notifications for a recipient + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/notifications/{notification_id}/status": + parameters: + - name: notification_id + in: path + required: true + description: "Notification id." + schema: { type: string } + put: + operationId: updateNotificationStatus + tags: ["Knowledge"] + summary: "Update Notification Status" + description: + |- + Update notification status and optional action taken + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/notifications/statistics": + get: + operationId: getNotificationStatistics + tags: ["Knowledge"] + summary: "Get Notification Statistics" + description: + |- + Get notification statistics and analytics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/add": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + post: + operationId: addOrganizationalKnowledge + tags: ["Knowledge"] + summary: "Add Organizational Knowledge" + description: + |- + Add knowledge to organization-level knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/search": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: searchOrganizationalKnowledge + tags: ["Knowledge"] + summary: "Search Organizational Knowledge" + description: + |- + Search organization-level knowledge base + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/context-enhancement/{agent_id}": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getEnhancedContextForAgent + tags: ["Knowledge"] + summary: "Get Enhanced Context for Agent" + description: + |- + Get enhanced context with relevant knowledge for agent task execution + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/organizations/{organization_id}/insights": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getOrganizationalKnowledgeInsights + tags: ["Knowledge"] + summary: "Get Organizational Knowledge Insights" + description: + |- + Get comprehensive organizational knowledge insights and analytics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/organizations/{organization_id}/effectiveness": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: analyzeKnowledgeEffectiveness + tags: ["Knowledge"] + summary: "Analyze Knowledge Effectiveness" + description: + |- + Analyze effectiveness of knowledge items in the organization + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/agents/{agent_id}/profile": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentKnowledgeProfile + tags: ["Knowledge"] + summary: "Get Agent Knowledge Profile" + description: + |- + Get detailed knowledge profile for an agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/organizations/{organization_id}/optimization": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getKnowledgeOptimizationRecommendations + tags: ["Knowledge"] + summary: "Get Knowledge Optimization Recommendations" + description: + |- + Generate comprehensive knowledge optimization recommendations + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/analytics/organizations/{organization_id}/trends": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getKnowledgeTrendsAnalysis + tags: ["Knowledge"] + summary: "Get Knowledge Trends Analysis" + description: + |- + Get comprehensive knowledge trends analysis + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/deploy-memory": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: deployMemoryEnabledAgent + tags: ["Agents"] + summary: "Deploy Memory-Enabled Agent" + description: + |- + Deploy a memory-enabled autonomous agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/memory-status": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentMemoryStatus + tags: ["Agents"] + summary: "Get Agent Memory Status" + description: + |- + Get agent memory status, expertise metrics, and insights + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/memory-tasks": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: assignTaskToMemoryAgent + tags: ["Agents"] + summary: "Assign Task to Memory Agent" + description: + |- + Assign a task to a memory-enabled agent for autonomous execution + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/system/expertise-dashboard": + get: + operationId: getSystemExpertiseDashboard + tags: ["Platform"] + summary: "Get System Expertise Dashboard" + description: + |- + Get comprehensive dashboard of system expertise and memory analytics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/tasks/pending": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getPendingTasksForAgent + tags: ["Tasks"] + summary: "Get Pending Tasks for Agent" + description: + |- + Get pending tasks that a memory-enabled agent can pick up + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/statistics": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: updateAgentStatistics + tags: ["Agents"] + summary: "Agent Statistics Update" + description: + |- + Update agent statistics - used by memory-enabled agents for performance tracking + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/goals": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + post: + operationId: createGoal + tags: ["Goals"] + summary: "Create organizational goal" + description: + |- + Create a new organizational goal + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "GoalCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listOrganizationGoals + tags: ["Goals"] + summary: "List organization goals" + description: + |- + List goals for an organization + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + get: + operationId: getGoal + tags: ["Goals"] + summary: "Get goal details" + description: + |- + Get goal details + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/overview": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + get: + operationId: getGoalOverview + tags: ["Goals"] + summary: "Get goal overview" + description: + |- + Get comprehensive goal overview + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/progress": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + put: + operationId: updateGoalProgress + tags: ["Goals"] + summary: "Update goal progress" + description: + |- + Update goal progress + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "GoalUpdateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/milestones": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: createMilestone + tags: ["Goals"] + summary: "Create milestone" + description: + |- + Create milestone for goal + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "MilestoneCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/milestones/{milestone_id}/tasks": + parameters: + - name: milestone_id + in: path + required: true + description: "Milestone id." + schema: { type: string } + post: + operationId: createTaskFromMilestone + tags: ["Goals"] + summary: "Create task from milestone" + description: + |- + Create task from milestone + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "TaskFromMilestoneRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/generate-execution-plan": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: generateExecutionPlan + tags: ["Goals"] + summary: "Generate execution plan" + description: + |- + Generate execution plan with milestones and tasks + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/generate-monthly-milestones": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: generateMonthlyMilestones + tags: ["Goals"] + summary: "Generate monthly milestones" + description: + |- + Generate monthly milestones for goal + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/milestones/{milestone_id}/generate-weekly-tasks": + parameters: + - name: milestone_id + in: path + required: true + description: "Milestone id." + schema: { type: string } + post: + operationId: generateWeeklyTasks + tags: ["Goals"] + summary: "Generate weekly tasks" + description: + |- + Generate weekly tasks for milestone + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/generate-cross-functional-tasks": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: generateCrossFunctionalTasks + tags: ["Goals"] + summary: "Generate cross-functional tasks" + description: + |- + Generate cross-functional tasks for goal + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/conversations": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: createGoalConversation + tags: ["Goals"] + summary: "Create goal conversation" + description: + |- + Create goal conversation + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "GoalConversationCreateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: getGoalConversations + tags: ["Goals"] + summary: "Get goal conversations" + description: + |- + Get conversations for a goal + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + get: + operationId: getGoalConversation + tags: ["Conversations"] + summary: "Get goal conversation" + description: + |- + Get goal conversation + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}/messages": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + post: + operationId: addMessageToConversation + tags: ["Conversations"] + summary: "Add message to conversation" + description: + |- + Add message to conversation + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ConversationMessageRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}/generate-milestones": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + post: + operationId: generatePlanningMilestones + tags: ["Conversations"] + summary: "Generate milestones from conversation" + description: + |- + Generate planning milestones from conversation + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}/conduct-progress-review": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + post: + operationId: conductProgressReview + tags: ["Conversations"] + summary: "Conduct progress review" + description: + |- + Conduct progress review + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/conversations/{conversation_id}/extract-action-items": + parameters: + - name: conversation_id + in: path + required: true + description: "Conversation id." + schema: { type: string } + post: + operationId: extractActionItems + tags: ["Conversations"] + summary: "Extract action items" + description: + |- + Extract action items from conversation + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/track-progress": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + post: + operationId: recordProgressTracking + tags: ["Goals"] + summary: "Record progress tracking update" + description: + |- + Record progress tracking update + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "ProgressUpdateRequest (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/deadline-risk": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + get: + operationId: assessDeadlineRisk + tags: ["Goals"] + summary: "Assess deadline risk" + description: + |- + Assess deadline risk for goal + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/goals/{goal_id}/progress-report": + parameters: + - name: goal_id + in: path + required: true + description: "Goal id." + schema: { type: string } + get: + operationId: generateProgressReport + tags: ["Goals"] + summary: "Generate progress report" + description: + |- + Generate progress report for goal + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/goals-dashboard": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getOrganizationGoalsDashboard + tags: ["Goals"] + summary: "Get organization goals dashboard" + description: + |- + Get organization goals dashboard + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/organizations/{organization_id}/tracking-dashboard": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + get: + operationId: getTrackingDashboard + tags: ["Organizations"] + summary: "Get tracking dashboard" + description: + |- + Get organization tracking dashboard + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/documents": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + post: + operationId: uploadOrganizationDocument + tags: ["Knowledge"] + summary: "Upload Organizational Document" + description: + |- + Upload a document to organizational knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "UploadFile (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listOrganizationDocuments + tags: ["Knowledge"] + summary: "List Organizational Documents" + description: + |- + Get list of organizational documents + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/url": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + post: + operationId: addOrganizationUrl + tags: ["Knowledge"] + summary: "Add URL to Organizational Knowledge" + description: + |- + Add URL content to organizational knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/documents/{doc_id}": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getOrganizationDocument + tags: ["Knowledge"] + summary: "Get Organizational Document" + description: + |- + Get organizational document metadata + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateOrganizationDocument + tags: ["Knowledge"] + summary: "Update Organizational Document" + description: + |- + Update organizational document metadata + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + delete: + operationId: deleteOrganizationDocument + tags: ["Knowledge"] + summary: "Delete Organizational Document" + description: + |- + Delete organizational document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/organizations/{organization_id}/documents/{doc_id}/content": + parameters: + - name: organization_id + in: path + required: true + description: "Organization id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getOrganizationDocumentContent + tags: ["Knowledge"] + summary: "Get Organizational Document Content" + description: + |- + Get full content of organizational document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/teams/{team_id}/documents": + parameters: + - name: team_id + in: path + required: true + description: "Team id." + schema: { type: string } + post: + operationId: uploadTeamDocument + tags: ["Knowledge"] + summary: "Upload Team Document" + description: + |- + Upload a document to team knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "UploadFile (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listTeamDocuments + tags: ["Knowledge"] + summary: "List Team Documents" + description: + |- + Get list of team documents + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/teams/{team_id}/url": + parameters: + - name: team_id + in: path + required: true + description: "Team id." + schema: { type: string } + post: + operationId: addTeamUrl + tags: ["Knowledge"] + summary: "Add URL to Team Knowledge" + description: + |- + Add URL content to team knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/teams/{team_id}/documents/{doc_id}": + parameters: + - name: team_id + in: path + required: true + description: "Team id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getTeamDocument + tags: ["Knowledge"] + summary: "Get Team Document" + description: + |- + Get team document metadata + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateTeamDocument + tags: ["Knowledge"] + summary: "Update Team Document" + description: + |- + Update team document metadata + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + delete: + operationId: deleteTeamDocument + tags: ["Knowledge"] + summary: "Delete Team Document" + description: + |- + Delete team document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/teams/{team_id}/documents/{doc_id}/content": + parameters: + - name: team_id + in: path + required: true + description: "Team id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getTeamDocumentContent + tags: ["Knowledge"] + summary: "Get Team Document Content" + description: + |- + Get full content of team document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/agents/{agent_id}/documents": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: uploadAgentDocument + tags: ["Knowledge"] + summary: "Upload Agent Document" + description: + |- + Upload a document to agent knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: true + content: + application/json: + schema: + type: object + description: "UploadFile (see services/orchestrator/main.py; the model is Pydantic and not reproduced here)." + additionalProperties: true + responses: + "201": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + get: + operationId: listAgentDocuments + tags: ["Knowledge"] + summary: "List Agent Documents" + description: + |- + Get list of agent documents + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/agents/{agent_id}/url": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: addAgentUrl + tags: ["Knowledge"] + summary: "Add URL to Agent Knowledge" + description: + |- + Add URL content to agent knowledge base + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/agents/{agent_id}/documents/{doc_id}": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getAgentDocument + tags: ["Knowledge"] + summary: "Get Agent Document" + description: + |- + Get agent document metadata + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + put: + operationId: updateAgentDocument + tags: ["Knowledge"] + summary: "Update Agent Document" + description: + |- + Update agent document metadata + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + delete: + operationId: deleteAgentDocument + tags: ["Knowledge"] + summary: "Delete Agent Document" + description: + |- + Delete agent document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/knowledge/agents/{agent_id}/documents/{doc_id}/content": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + get: + operationId: getAgentDocumentContent + tags: ["Knowledge"] + summary: "Get Agent Document Content" + description: + |- + Get full content of agent document + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/create": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: createAgentContainer + tags: ["Containers"] + summary: "Create Agent Container" + description: + |- + Create a new container for an AI agent + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/start": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: startAgentContainer + tags: ["Containers"] + summary: "Start Agent Container" + description: + |- + Start an agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/stop": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: stopAgentContainer + tags: ["Containers"] + summary: "Stop Agent Container" + description: + |- + Stop an agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/restart": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: restartAgentContainer + tags: ["Containers"] + summary: "Restart Agent Container" + description: + |- + Restart an agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + delete: + operationId: removeAgentContainer + tags: ["Containers"] + summary: "Remove Agent Container" + description: + |- + Remove an agent container + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/status": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentContainerStatus + tags: ["Containers"] + summary: "Get Agent Container Status" + description: + |- + Get container status for an agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/containers/agents": + get: + operationId: listAgentContainers + tags: ["Containers"] + summary: "List Agent Containers" + description: + |- + List all agent containers + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/logs": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + get: + operationId: getAgentContainerLogs + tags: ["Containers"] + summary: "Get Agent Container Logs" + description: + |- + Get container logs for an agent + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/agents/{agent_id}/container/execute": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: executeContainerCommand + tags: ["Containers"] + summary: "Execute Command in Container" + description: + |- + Execute a command in the agent container + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/search": + post: + operationId: searchKnowledgeContext + tags: ["Knowledge"] + summary: "Search for relevant knowledge context using RAG" + description: + |- + Search for relevant knowledge context using RAG + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/enhance-prompt": + post: + operationId: enhancePromptWithContext + tags: ["Knowledge"] + summary: "Enhance a prompt with relevant context using RAG" + description: + |- + Enhance a prompt with relevant context using RAG + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/reindex": + post: + operationId: reindexKnowledgeBase + tags: ["Knowledge"] + summary: "Reindex all documents in a scope for RAG" + description: + |- + Reindex all documents in a scope for RAG + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/stats": + get: + operationId: getRagIndexStats + tags: ["Knowledge"] + summary: "Get statistics about the RAG index" + description: + |- + Get statistics about the RAG index + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/rag/documents/{doc_id}/reindex": + parameters: + - name: doc_id + in: path + required: true + description: "Doc id." + schema: { type: string } + post: + operationId: reindexDocument + tags: ["Knowledge"] + summary: "Reindex a specific document for RAG" + description: + |- + Reindex a specific document for RAG + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/ws/stats": + get: + operationId: getWebsocketStats + tags: ["Platform"] + summary: "Get WebSocket connection statistics" + description: + |- + Get WebSocket connection statistics + security: [{ bearerAuth: [] }] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/ws/test/agent/{agent_id}/status": + parameters: + - name: agent_id + in: path + required: true + description: "Agent id." + schema: { type: string } + post: + operationId: testAgentStatusNotification + tags: ["Platform"] + summary: "Test endpoint to send agent status notifications" + description: + |- + Test endpoint to send agent status notifications + security: [{ bearerAuth: [] }] + requestBody: + required: false + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "404": + description: Not found. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "422": + description: Validation error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "/openapi.yaml": + get: + operationId: getOpenapiDocument + tags: ["Platform"] + summary: "This OpenAPI document" + description: + |- + Unauthenticated. Serves contracts/openapi.yaml — the document you are reading — from the copy baked into the image, so what the API publishes is always the contract this build was compiled against. + + This is NOT /openapi.json. That endpoint is FastAPI's auto-generated schema: it is derived from the code at import time and carries no curated descriptions, no tags beyond the decorators, and — critically — none of the irreversibility guidance in mcp/tools.overrides.yaml. Both are served; this one is the contract. + + Answers 503 if the image was built without its contract. A missing document is degraded, not fatal — no restart can conjure a file the image lacks. + security: [] + responses: + "200": + description: Success. + content: + application/json: + schema: { type: object } + "401": + description: Not authenticated. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } + "500": + description: Internal server error. + content: + application/json: + schema: { $ref: "#/components/schemas/Error" } +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + description: >- + Bearer token. Resolved through the FuzeFront Security API when + SECURITY_BASE_URL is set; local JWT verification otherwise. + schemas: + Error: + type: object + description: FastAPI's error shape. + properties: + detail: + description: Human-readable error, or a validation-error array. +security: + - bearerAuth: [] diff --git a/services/orchestrator/main.py b/services/orchestrator/main.py index 3d8752a..ce26700 100644 --- a/services/orchestrator/main.py +++ b/services/orchestrator/main.py @@ -24,7 +24,7 @@ status, ) from fastapi.middleware.cors import CORSMiddleware -from fastapi.responses import HTMLResponse +from fastapi.responses import HTMLResponse, Response from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer from pydantic import BaseModel, Field @@ -673,9 +673,80 @@ async def health_check(): "mcp_integration": True, "real_time_streaming": True, }, + # Whether GET /openapi.yaml can answer. An image built without its + # contract is DEGRADED, not dead — the probe still passes (no restart + # can conjure a file the image lacks) but the condition is visible to + # anything that looks, instead of surfacing only as a 503 later. + "openapi": "loaded" if _openapi_document() is not None else "unavailable", } +# --------------------------------------------------------------------------- +# The contract, SERVED. +# +# contracts/openapi.yaml describes this orchestrator's real HTTP surface, with +# the curated descriptions and the irreversibility guidance that +# mcp/tools.overrides.yaml narrows. Committing it is not the same as publishing +# it: consumers — the MCP gateway among them — discover the surface over HTTP. +# +# This is NOT /openapi.json. FastAPI generates that from the code at import +# time; it is accurate about shapes and says nothing about which operations +# dispatch an agent that cannot be recalled. Both are served. This one is the +# contract. +# +# The document is read from the IMAGE, never from a mount, so what this endpoint +# publishes is always the contract this build was compiled against. +# --------------------------------------------------------------------------- +_ORCH_DIR = os.path.dirname(os.path.abspath(__file__)) +_OPENAPI_CANDIDATES = [ + p + for p in [ + os.getenv("OPENAPI_SPEC_PATH"), + os.path.join(_ORCH_DIR, "contracts", "openapi.yaml"), + os.path.join(_ORCH_DIR, "..", "..", "contracts", "openapi.yaml"), + ] + if p +] + + +def _openapi_document(): + """Return the OpenAPI document text, or None when the image lacks it.""" + for path in _OPENAPI_CANDIDATES: + try: + with open(path, "r", encoding="utf-8") as fh: + return fh.read() + except OSError: + continue + return None + + +@app.get( + "/openapi.yaml", + tags=["health"], + summary="This OpenAPI Document", + description=( + "Serve contracts/openapi.yaml — the curated contract, as distinct from " + "FastAPI's auto-generated /openapi.json." + ), + include_in_schema=False, +) +async def get_openapi_document(): + doc = _openapi_document() + if doc is None: + logger.error("OpenAPI document not found; tried %s", _OPENAPI_CANDIDATES) + # 503, not 500 and not a crash: the service is otherwise functional and + # no restart can produce a spec the image does not contain. + raise HTTPException( + status_code=503, + detail=( + "openapi_document_unavailable: this image was built without " + "contracts/openapi.yaml. Rebuild with the repo root as the Docker " + "context so the contract is copied in." + ), + ) + return Response(content=doc, media_type="application/yaml") + + # WebSocket for real-time updates @app.websocket("/ws") async def websocket_endpoint(websocket: WebSocket):