@zhixuan92/multi-model-agent 3.0.0

package/dist/openapi.js

@@ -0,0 +1,314 @@
+// packages/server/src/openapi.ts
+//
+// Builds the OpenAPI 3.0 document that describes all endpoints of the
+// multi-model-agent HTTP server.
+//
+// Uses @asteasolutions/zod-to-openapi to convert each tool's Zod inputSchema
+// directly into OpenAPI request body schemas.
+import { z } from 'zod';
+import { extendZodWithOpenApi, OpenAPIRegistry, OpenApiGeneratorV3, } from '@asteasolutions/zod-to-openapi';
+import * as delegate from '@zhixuan92/multi-model-agent-core/tool-schemas/delegate';
+import * as audit from '@zhixuan92/multi-model-agent-core/tool-schemas/audit';
+import * as review from '@zhixuan92/multi-model-agent-core/tool-schemas/review';
+import * as verify from '@zhixuan92/multi-model-agent-core/tool-schemas/verify';
+import * as debug from '@zhixuan92/multi-model-agent-core/tool-schemas/debug';
+import * as executePlan from '@zhixuan92/multi-model-agent-core/tool-schemas/execute-plan';
+import * as retry from '@zhixuan92/multi-model-agent-core/tool-schemas/retry';
+// Extend Zod once with openapi support.
+extendZodWithOpenApi(z);
+/** Sort an object's keys recursively for deterministic JSON serialization. */
+function sortKeys(obj) {
+    if (obj === null || typeof obj !== 'object')
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(sortKeys);
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+        sorted[key] = sortKeys(obj[key]);
+    }
+    return sorted;
+}
+/** Shared 202 response for async tool endpoints. */
+const asyncResponse202 = {
+    description: 'Accepted — batch created',
+    content: {
+        'application/json': {
+            schema: z.object({
+                batchId: z.string().describe('Unique batch identifier for polling via GET /batch/:batchId'),
+                statusUrl: z.string().describe('Full URL to poll for this batch'),
+            }),
+        },
+    },
+};
+/** Shared `cwd` query parameter (required by all tool endpoints). */
+const cwdQueryParam = {
+    name: 'cwd',
+    in: 'query',
+    required: true,
+    description: 'Absolute path to the project working directory',
+    schema: { type: 'string' },
+};
+/** Standard 401 error response. */
+const response401 = { description: 'Missing or invalid Bearer token' };
+/** Standard 403 error response. */
+const response403 = { description: 'Forbidden (loopback-only or path traversal)' };
+/** Standard 404 error response. */
+const response404 = { description: 'Resource not found' };
+export function buildOpenApiDoc() {
+    const registry = new OpenAPIRegistry();
+    // ── Tool endpoints (POST, require cwd + auth) ───────────────────────────────
+    registry.registerPath({
+        method: 'post',
+        path: '/delegate',
+        summary: 'Dispatch tasks to sub-agents',
+        tags: ['Tools'],
+        request: {
+            query: z.object({ cwd: z.string().describe('Project working directory') }),
+            body: {
+                required: true,
+                content: { 'application/json': { schema: delegate.inputSchema } },
+            },
+        },
+        responses: {
+            202: asyncResponse202,
+            400: { description: 'Request validation error' },
+            401: response401,
+        },
+    });
+    registry.registerPath({
+        method: 'post',
+        path: '/audit',
+        summary: 'Audit documents or files',
+        tags: ['Tools'],
+        request: {
+            query: z.object({ cwd: z.string().describe('Project working directory') }),
+            body: {
+                required: true,
+                content: { 'application/json': { schema: audit.inputSchema } },
+            },
+        },
+        responses: {
+            202: asyncResponse202,
+            400: { description: 'Request validation error' },
+            401: response401,
+        },
+    });
+    registry.registerPath({
+        method: 'post',
+        path: '/review',
+        summary: 'Review code for quality and security',
+        tags: ['Tools'],
+        request: {
+            query: z.object({ cwd: z.string().describe('Project working directory') }),
+            body: {
+                required: true,
+                content: { 'application/json': { schema: review.inputSchema } },
+            },
+        },
+        responses: {
+            202: asyncResponse202,
+            400: { description: 'Request validation error' },
+            401: response401,
+        },
+    });
+    registry.registerPath({
+        method: 'post',
+        path: '/verify',
+        summary: 'Verify work against a checklist',
+        tags: ['Tools'],
+        request: {
+            query: z.object({ cwd: z.string().describe('Project working directory') }),
+            body: {
+                required: true,
+                content: { 'application/json': { schema: verify.inputSchema } },
+            },
+        },
+        responses: {
+            202: asyncResponse202,
+            400: { description: 'Request validation error' },
+            401: response401,
+        },
+    });
+    registry.registerPath({
+        method: 'post',
+        path: '/debug',
+        summary: 'Debug a problem with sub-agent assistance',
+        tags: ['Tools'],
+        request: {
+            query: z.object({ cwd: z.string().describe('Project working directory') }),
+            body: {
+                required: true,
+                content: { 'application/json': { schema: debug.inputSchema } },
+            },
+        },
+        responses: {
+            202: asyncResponse202,
+            400: { description: 'Request validation error' },
+            401: response401,
+        },
+    });
+    registry.registerPath({
+        method: 'post',
+        path: '/execute-plan',
+        summary: 'Execute tasks from a plan file',
+        tags: ['Tools'],
+        request: {
+            query: z.object({ cwd: z.string().describe('Project working directory') }),
+            body: {
+                required: true,
+                content: { 'application/json': { schema: executePlan.inputSchema } },
+            },
+        },
+        responses: {
+            202: asyncResponse202,
+            400: { description: 'Request validation error' },
+            401: response401,
+        },
+    });
+    registry.registerPath({
+        method: 'post',
+        path: '/retry',
+        summary: 'Retry failed tasks from a previous batch',
+        tags: ['Tools'],
+        request: {
+            query: z.object({ cwd: z.string().describe('Project working directory') }),
+            body: {
+                required: true,
+                content: { 'application/json': { schema: retry.inputSchema } },
+            },
+        },
+        responses: {
+            202: asyncResponse202,
+            400: { description: 'Request validation error' },
+            401: response401,
+        },
+    });
+    // ── Control endpoints ───────────────────────────────────────────────────────
+    registry.registerPath({
+        method: 'get',
+        path: '/batch/{batchId}',
+        summary: 'Poll batch status',
+        tags: ['Control'],
+        request: {
+            params: z.object({ batchId: z.string().describe('Batch identifier') }),
+            query: z.object({
+                taskIndex: z.string().optional().describe('Zero-based task index for result slicing'),
+            }),
+        },
+        responses: {
+            200: { description: 'Batch state (pending | awaiting_clarification | complete | failed | expired)' },
+            401: response401,
+            404: response404,
+        },
+    });
+    registry.registerPath({
+        method: 'post',
+        path: '/context-blocks',
+        summary: 'Register a context block',
+        tags: ['Control'],
+        request: {
+            query: z.object({ cwd: z.string().describe('Project working directory') }),
+            body: {
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: z.object({
+                            content: z.string().describe('Block content (plain text or markdown)'),
+                            label: z.string().optional().describe('Human-readable label'),
+                        }),
+                    },
+                },
+            },
+        },
+        responses: {
+            201: { description: 'Block created' },
+            400: { description: 'Validation error or content too large' },
+            401: response401,
+        },
+    });
+    registry.registerPath({
+        method: 'delete',
+        path: '/context-blocks/{blockId}',
+        summary: 'Delete a context block',
+        tags: ['Control'],
+        request: {
+            params: z.object({ blockId: z.string().describe('Context block identifier') }),
+            query: z.object({ cwd: z.string().describe('Project working directory') }),
+        },
+        responses: {
+            200: { description: 'Block deleted (or was already absent)' },
+            401: response401,
+        },
+    });
+    registry.registerPath({
+        method: 'post',
+        path: '/clarifications/confirm',
+        summary: 'Confirm a proposed interpretation to unblock an awaiting_clarification batch',
+        tags: ['Control'],
+        request: {
+            body: {
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: z.object({
+                            batchId: z.string(),
+                            interpretation: z.string(),
+                        }),
+                    },
+                },
+            },
+        },
+        responses: {
+            200: { description: 'Clarification accepted' },
+            400: { description: 'Invalid batch state' },
+            401: response401,
+            404: response404,
+        },
+    });
+    // ── Introspection endpoints ─────────────────────────────────────────────────
+    registry.registerPath({
+        method: 'get',
+        path: '/health',
+        summary: 'Liveness probe — no auth required',
+        tags: ['Introspection'],
+        responses: {
+            200: {
+                description: 'Server is alive',
+                content: {
+                    'application/json': {
+                        schema: z.object({ ok: z.literal(true) }),
+                    },
+                },
+            },
+        },
+    });
+    registry.registerPath({
+        method: 'get',
+        path: '/status',
+        summary: 'Operator status — loopback + auth required',
+        tags: ['Introspection'],
+        responses: {
+            200: { description: 'Server status object (§5.10)' },
+            401: response401,
+            403: response403,
+        },
+    });
+    // ── Generate ────────────────────────────────────────────────────────────────
+    const generator = new OpenApiGeneratorV3(registry.definitions);
+    const doc = generator.generateDocument({
+        openapi: '3.0.3',
+        info: {
+            title: 'multi-model-agent',
+            version: '3.0.0',
+        },
+    });
+    // Return a key-sorted version for deterministic golden comparisons
+    return sortKeys(doc);
+}
+/** Utility: serialize the OpenAPI doc with sorted keys for golden snapshots. */
+export function serializeOpenApiDoc(doc) {
+    return JSON.stringify(doc, null, 2);
+}
+// Re-export cwdQueryParam for tests / external use
+export { cwdQueryParam };
+//# sourceMappingURL=openapi.js.map

package/dist/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,EAAE;AACF,sEAAsE;AACtE,iCAAiC;AACjC,EAAE;AACF,6EAA6E;AAC7E,8CAA8C;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,kBAAkB,GACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,QAAQ,MAAM,yDAAyD,CAAC;AACpF,OAAO,KAAK,KAAK,MAAM,sDAAsD,CAAC;AAC9E,OAAO,KAAK,MAAM,MAAM,uDAAuD,CAAC;AAChF,OAAO,KAAK,MAAM,MAAM,uDAAuD,CAAC;AAChF,OAAO,KAAK,KAAK,MAAM,sDAAsD,CAAC;AAC9E,OAAO,KAAK,WAAW,MAAM,6DAA6D,CAAC;AAC3F,OAAO,KAAK,KAAK,MAAM,sDAAsD,CAAC;AAE9E,wCAAwC;AACxC,oBAAoB,CAAC,CAAC,CAAC,CAAC;AAExB,8EAA8E;AAC9E,SAAS,QAAQ,CAAC,GAAY;IAC5B,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IACxD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACjD,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAA8B,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACrE,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAE,GAA+B,CAAC,GAAG,CAAC,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,oDAAoD;AACpD,MAAM,gBAAgB,GAAG;IACvB,WAAW,EAAE,0BAA0B;IACvC,OAAO,EAAE;QACP,kBAAkB,EAAE;YAClB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;gBACf,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6DAA6D,CAAC;gBAC3F,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;aAClE,CAAC;SACH;KACF;CACF,CAAC;AAEF,qEAAqE;AACrE,MAAM,aAAa,GAAG;IACpB,IAAI,EAAE,KAAK;IACX,EAAE,EAAE,OAAgB;IACpB,QAAQ,EAAE,IAAI;IACd,WAAW,EAAE,gDAAgD;IAC7D,MAAM,EAAE,EAAE,IAAI,EAAE,QAAiB,EAAE;CACpC,CAAC;AAEF,mCAAmC;AACnC,MAAM,WAAW,GAAG,EAAE,WAAW,EAAE,iCAAiC,EAAE,CAAC;AAEvE,mCAAmC;AACnC,MAAM,WAAW,GAAG,EAAE,WAAW,EAAE,6CAA6C,EAAE,CAAC;AAEnF,mCAAmC;AACnC,MAAM,WAAW,GAAG,EAAE,WAAW,EAAE,oBAAoB,EAAE,CAAC;AAE1D,MAAM,UAAU,eAAe;IAC7B,MAAM,QAAQ,GAAG,IAAI,eAAe,EAAE,CAAC;IAEvC,+EAA+E;IAE/E,QAAQ,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,8BAA8B;QACvC,IAAI,EAAE,CAAC,OAAO,CAAC;QACf,OAAO,EAAE;YACP,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CAAC;YAC1E,IAAI,EAAE;gBACJ,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,WAAW,EAAE,EAAE;aAClE;SACF;QACD,SAAS,EAAE;YACT,GAAG,EAAE,gBAAgB;YACrB,GAAG,EAAE,EAAE,WAAW,EAAE,0BAA0B,EAAE;YAChD,GAAG,EAAE,WAAW;SACjB;KACF,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,0BAA0B;QACnC,IAAI,EAAE,CAAC,OAAO,CAAC;QACf,OAAO,EAAE;YACP,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CAAC;YAC1E,IAAI,EAAE;gBACJ,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,WAAW,EAAE,EAAE;aAC/D;SACF;QACD,SAAS,EAAE;YACT,GAAG,EAAE,gBAAgB;YACrB,GAAG,EAAE,EAAE,WAAW,EAAE,0BAA0B,EAAE;YAChD,GAAG,EAAE,WAAW;SACjB;KACF,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,sCAAsC;QAC/C,IAAI,EAAE,CAAC,OAAO,CAAC;QACf,OAAO,EAAE;YACP,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CAAC;YAC1E,IAAI,EAAE;gBACJ,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,EAAE;aAChE;SACF;QACD,SAAS,EAAE;YACT,GAAG,EAAE,gBAAgB;YACrB,GAAG,EAAE,EAAE,WAAW,EAAE,0BAA0B,EAAE;YAChD,GAAG,EAAE,WAAW;SACjB;KACF,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,iCAAiC;QAC1C,IAAI,EAAE,CAAC,OAAO,CAAC;QACf,OAAO,EAAE;YACP,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CAAC;YAC1E,IAAI,EAAE;gBACJ,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,EAAE;aAChE;SACF;QACD,SAAS,EAAE;YACT,GAAG,EAAE,gBAAgB;YACrB,GAAG,EAAE,EAAE,WAAW,EAAE,0BAA0B,EAAE;YAChD,GAAG,EAAE,WAAW;SACjB;KACF,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,2CAA2C;QACpD,IAAI,EAAE,CAAC,OAAO,CAAC;QACf,OAAO,EAAE;YACP,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CAAC;YAC1E,IAAI,EAAE;gBACJ,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,WAAW,EAAE,EAAE;aAC/D;SACF;QACD,SAAS,EAAE;YACT,GAAG,EAAE,gBAAgB;YACrB,GAAG,EAAE,EAAE,WAAW,EAAE,0BAA0B,EAAE;YAChD,GAAG,EAAE,WAAW;SACjB;KACF,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,gCAAgC;QACzC,IAAI,EAAE,CAAC,OAAO,CAAC;QACf,OAAO,EAAE;YACP,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CAAC;YAC1E,IAAI,EAAE;gBACJ,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,WAAW,EAAE,EAAE;aACrE;SACF;QACD,SAAS,EAAE;YACT,GAAG,EAAE,gBAAgB;YACrB,GAAG,EAAE,EAAE,WAAW,EAAE,0BAA0B,EAAE;YAChD,GAAG,EAAE,WAAW;SACjB;KACF,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,0CAA0C;QACnD,IAAI,EAAE,CAAC,OAAO,CAAC;QACf,OAAO,EAAE;YACP,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CAAC;YAC1E,IAAI,EAAE;gBACJ,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,WAAW,EAAE,EAAE;aAC/D;SACF;QACD,SAAS,EAAE;YACT,GAAG,EAAE,gBAAgB;YACrB,GAAG,EAAE,EAAE,WAAW,EAAE,0BAA0B,EAAE;YAChD,GAAG,EAAE,WAAW;SACjB;KACF,CAAC,CAAC;IAEH,+EAA+E;IAE/E,QAAQ,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,mBAAmB;QAC5B,IAAI,EAAE,CAAC,SAAS,CAAC;QACjB,OAAO,EAAE;YACP,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;YACtE,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;gBACd,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;aACtF,CAAC;SACH;QACD,SAAS,EAAE;YACT,GAAG,EAAE,EAAE,WAAW,EAAE,8EAA8E,EAAE;YACpG,GAAG,EAAE,WAAW;YAChB,GAAG,EAAE,WAAW;SACjB;KACF,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE,0BAA0B;QACnC,IAAI,EAAE,CAAC,SAAS,CAAC;QACjB,OAAO,EAAE;YACP,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CAAC;YAC1E,IAAI,EAAE;gBACJ,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE;oBACP,kBAAkB,EAAE;wBAClB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;4BACf,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;4BACtE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;yBAC9D,CAAC;qBACH;iBACF;aACF;SACF;QACD,SAAS,EAAE;YACT,GAAG,EAAE,EAAE,WAAW,EAAE,eAAe,EAAE;YACrC,GAAG,EAAE,EAAE,WAAW,EAAE,uCAAuC,EAAE;YAC7D,GAAG,EAAE,WAAW;SACjB;KACF,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,QAAQ;QAChB,IAAI,EAAE,2BAA2B;QACjC,OAAO,EAAE,wBAAwB;QACjC,IAAI,EAAE,CAAC,SAAS,CAAC;QACjB,OAAO,EAAE;YACP,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC,EAAE,CAAC;YAC9E,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CAAC;SAC3E;QACD,SAAS,EAAE;YACT,GAAG,EAAE,EAAE,WAAW,EAAE,uCAAuC,EAAE;YAC7D,GAAG,EAAE,WAAW;SACjB;KACF,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,yBAAyB;QAC/B,OAAO,EAAE,8EAA8E;QACvF,IAAI,EAAE,CAAC,SAAS,CAAC;QACjB,OAAO,EAAE;YACP,IAAI,EAAE;gBACJ,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE;oBACP,kBAAkB,EAAE;wBAClB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;4BACf,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;4BACnB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;yBAC3B,CAAC;qBACH;iBACF;aACF;SACF;QACD,SAAS,EAAE;YACT,GAAG,EAAE,EAAE,WAAW,EAAE,wBAAwB,EAAE;YAC9C,GAAG,EAAE,EAAE,WAAW,EAAE,qBAAqB,EAAE;YAC3C,GAAG,EAAE,WAAW;YAChB,GAAG,EAAE,WAAW;SACjB;KACF,CAAC,CAAC;IAEH,+EAA+E;IAE/E,QAAQ,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,mCAAmC;QAC5C,IAAI,EAAE,CAAC,eAAe,CAAC;QACvB,SAAS,EAAE;YACT,GAAG,EAAE;gBACH,WAAW,EAAE,iBAAiB;gBAC9B,OAAO,EAAE;oBACP,kBAAkB,EAAE;wBAClB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;qBAC1C;iBACF;aACF;SACF;KACF,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,4CAA4C;QACrD,IAAI,EAAE,CAAC,eAAe,CAAC;QACvB,SAAS,EAAE;YACT,GAAG,EAAE,EAAE,WAAW,EAAE,8BAA8B,EAAE;YACpD,GAAG,EAAE,WAAW;YAChB,GAAG,EAAE,WAAW;SACjB;KACF,CAAC,CAAC;IAEH,+EAA+E;IAE/E,MAAM,SAAS,GAAG,IAAI,kBAAkB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC/D,MAAM,GAAG,GAAG,SAAS,CAAC,gBAAgB,CAAC;QACrC,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE;YACJ,KAAK,EAAE,mBAAmB;YAC1B,OAAO,EAAE,OAAO;SACjB;KACF,CAAC,CAAC;IAEH,mEAAmE;IACnE,OAAO,QAAQ,CAAC,GAAG,CAA4B,CAAC;AAClD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,mBAAmB,CAAC,GAA4B;IAC9D,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACtC,CAAC;AAED,mDAAmD;AACnD,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/skills/_shared/auth.md

@@ -0,0 +1,32 @@
+## Authentication
+
+Every request to the multi-model-agent server requires a Bearer token.
+
+### Obtain the token
+
+**From environment variable** (preferred):
+```
+MMAGENT_AUTH_TOKEN=<token>
+```
+
+**From CLI**:
+```bash
+mmagent print-token
+```
+
+### Use the token
+
+Add to every request as an HTTP header:
+```
+Authorization: Bearer <token>
+```
+
+### Shell helper
+
+```bash
+TOKEN="${MMAGENT_AUTH_TOKEN:-$(mmagent print-token)}"
+curl -H "Authorization: Bearer $TOKEN" ...
+```
+
+If the server returns `401 unauthorized`, re-run `mmagent print-token` —
+the token may have changed after a server restart.

package/dist/skills/_shared/error-handling.md

@@ -0,0 +1,31 @@
+## Error handling
+
+### HTTP status decision table
+
+| Status | Code | Action |
+|---|---|---|
+| `400` | `invalid_request` | Fix the request body or query params |
+| `401` | `unauthorized` | Re-fetch token; check `MMAGENT_AUTH_TOKEN` |
+| `403` | `forbidden` | `cwd` query param missing or out of scope |
+| `404` | `not_found` | Wrong `batchId` or resource does not exist |
+| `409` | `invalid_batch_state` / `pinned` | Batch in wrong state; check current state first |
+| `413` | `payload_too_large` | Reduce content size (context block or body) |
+| `429` | `rate_limited` | Wait `Retry-After` seconds, then retry |
+| `503` | `project_cap_exceeded` | Too many concurrent projects; wait and retry |
+| `5xx` | server error | Retry once after 2 s; escalate if it persists |
+
+### Network failures
+
+Retry up to 3 times with exponential backoff (1 s → 2 s → 4 s).
+If the server is unreachable, check that `mmagent serve` is running:
+```bash
+curl -s http://localhost:$PORT/health   # expects { ok: true }
+```
+
+### Auth errors (401)
+
+```bash
+export MMAGENT_AUTH_TOKEN=$(mmagent print-token)
+```
+
+The token changes on every server restart. Re-export before retrying.

package/dist/skills/_shared/polling.md

@@ -0,0 +1,40 @@
+## Polling for batch completion
+
+After a tool call returns a `batchId`, poll `GET /batch/:id` until the batch
+reaches a terminal state.
+
+### Terminal states
+
+| State | Meaning |
+|---|---|
+| `complete` | All tasks finished — read results |
+| `failed` | Batch failed — read error details |
+| `expired` | Batch TTL exceeded — retry if needed |
+
+### Awaiting clarification
+
+If `GET /batch/:id` returns `state: 'awaiting_clarification'`, the service
+needs your confirmation before it can continue. Read `proposedInterpretation`
+from the response, then call `POST /clarifications/confirm` with your chosen
+`interpretation` (accept or correct the proposal).
+
+### Poll loop (shell)
+
+```bash
+DELAY=1
+while true; do
+  RESP=$(curl -sf -H "Authorization: Bearer $TOKEN" \
+    "http://localhost:$PORT/batch/$BATCH_ID")
+  STATE=$(echo "$RESP" | jq -r '.state')
+  case "$STATE" in
+    complete|failed|expired) echo "$RESP"; break ;;
+    awaiting_clarification)
+      # Invoke mma-clarifications to confirm interpretation, then continue
+      break ;;
+    *) sleep $DELAY; DELAY=$(( DELAY < 5 ? DELAY * 2 : 5 )) ;;
+  esac
+done
+```
+
+Start at 1 s, double each iteration, cap at 5 s. Most batches complete in
+under 60 s; long tasks may take several minutes.

package/dist/skills/_shared/response-shape.md

@@ -0,0 +1,46 @@
+## Response shapes
+
+### POST /<tool>?cwd=<abs> — dispatch response (202)
+
+```json
+{
+  "batchId": "<uuid>",
+  "state": "pending"
+}
+```
+
+### GET /batch/:id — polling response
+
+```json
+{
+  "batchId": "<uuid>",
+  "state": "pending | running | awaiting_clarification | complete | failed | expired",
+  "proposedInterpretation": "<string>",
+  "results": [ ... ],
+  "headline": "<string>",
+  "batchTimings": { ... },
+  "costSummary": { ... }
+}
+```
+
+`proposedInterpretation` is only present when `state` is `awaiting_clarification`.
+
+`results`, `headline`, `batchTimings`, and `costSummary` are only present
+when `state` is `complete` or `failed`.
+
+### GET /batch/:id?taskIndex=N — single task slice
+
+Returns the same shape but `results` contains only the task at index `N`.
+
+### Error response (4xx / 5xx)
+
+```json
+{
+  "error": "<code>",
+  "message": "<human-readable>",
+  "details": { ... }
+}
+```
+
+`details` is optional and present only when the server has structured
+additional context (e.g. `fieldErrors` for validation failures).

package/dist/skills/mma-audit/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: mma-audit
+description: Audit a document for security, performance, correctness, or style issues. Sub-agents run in parallel per file.
+when_to_use: When you need to audit a spec, design doc, or configuration file for correctness, security, style, or performance issues.
+---
+
+## mma-audit
+
+Send a document or set of files to sub-agents for structured auditing. Each
+file is audited independently in parallel; results are indexed by file.
+
+### Endpoint
+
+`POST /audit?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+### Request body
+
+```json
+{
+  "document": "inline content to audit (optional if filePaths given)",
+  "auditType": "correctness",
+  "filePaths": ["/project/docs/spec.md"],
+  "contextBlockIds": []
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `document` | string | no | Inline document content |
+| `auditType` | string \| string[] | yes | `security`, `performance`, `correctness`, `style`, or `general`; or an array of the first four |
+| `filePaths` | string[] | no | Files to audit (parallel) |
+| `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` |
+
+Either `document` or `filePaths` (or both) must be provided.
+
+### Full example
+
+```bash
+BATCH=$(curl -sf -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"auditType":"correctness","filePaths":["/project/docs/api-spec.md"]}' \
+  "http://localhost:$PORT/audit?cwd=/project")
+BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+```
+
+Then poll until complete:
+
+@include _shared/polling.md
+
+@include _shared/response-shape.md
+
+@include _shared/error-handling.md

package/dist/skills/mma-clarifications/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: mma-clarifications
+description: Confirm or correct the service's proposed interpretation when a batch is awaiting clarification before it can proceed.
+when_to_use: When polling GET /batch/:id returns state 'awaiting_clarification'. Read proposedInterpretation, then call this skill to confirm or correct it.
+---
+
+## mma-clarifications
+
+When a batch pauses with `state: 'awaiting_clarification'`, the service has
+proposed an interpretation of the task and is waiting for your decision.
+Read the proposal, then call `POST /clarifications/confirm` to either accept
+or correct it. The batch resumes immediately after confirmation.
+
+### Endpoint
+
+`POST /clarifications/confirm`
+
+Auth required. Not cwd-gated (operates on a `batchId`).
+
+@include _shared/auth.md
+
+### Request body
+
+```json
+{
+  "batchId": "550e8400-e29b-41d4-a716-446655440000",
+  "interpretation": "Refactor only the auth module, leaving the user module unchanged"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `batchId` | string (UUID) | yes | Batch in `awaiting_clarification` state |
+| `interpretation` | string | yes | Accept proposal verbatim or provide a corrected version |
+
+### Response (200)
+
+```json
+{ "batchId": "...", "state": "pending" }
+```
+
+`state` is usually `pending` (batch resumes). It may be `complete` if the
+executor was already waiting and finishes immediately.
+
+### Full flow
+
+```bash
+# 1. Poll until awaiting_clarification
+STATE=$(curl -sf -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:$PORT/batch/$BATCH_ID" | jq -r '.state')
+
+# 2. Read the proposal
+PROPOSAL=$(curl -sf -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:$PORT/batch/$BATCH_ID" | jq -r '.proposedInterpretation')
+
+# 3. Confirm (accept proposal or supply corrected text)
+curl -sf -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{\"batchId\":\"$BATCH_ID\",\"interpretation\":\"$PROPOSAL\"}" \
+  "http://localhost:$PORT/clarifications/confirm"
+
+# 4. Resume polling
+```
+
+@include _shared/polling.md
+
+@include _shared/error-handling.md

package/dist/skills/mma-context-blocks/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: mma-context-blocks
+description: Register large reused documents as context blocks and reference them by ID across multiple tool calls. Avoids re-sending the same content repeatedly.
+when_to_use: When the same large document (spec, plan, codebase summary) needs to be referenced by multiple mma-* calls. Register once, reference by ID.
+---
+
+## mma-context-blocks
+
+Store large documents once; reference them by ID in subsequent `mma-*` calls
+via `contextBlockIds`. The service prepends the block content to each task
+prompt that references it.
+
+### Register a context block
+
+`POST /context-blocks?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+#### Request body
+
+```json
+{
+  "content": "# Project spec\n...",
+  "ttlMs": 3600000
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `content` | string | yes | Document content (min 1 char) |
+| `ttlMs` | number | no | Time-to-live in ms; omit for session-scoped |
+
+#### Response (201)
+
+```json
+{ "id": "cb_abc123" }
+```
+
+Use this `id` as a `contextBlockIds` entry in `mma-delegate`, `mma-audit`,
+`mma-review`, `mma-verify`, `mma-debug`, or `mma-execute-plan`.
+
+### Delete a context block
+
+`DELETE /context-blocks/:id?cwd=<abs-path>`
+
+Returns `200 { ok: true }` on success.
+
+Returns `409 pinned` if the block is held by one or more active batches —
+wait for those batches to complete before deleting.
+
+### Example
+
+```bash
+# Register spec document
+ID=$(curl -sf -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{\"content\":$(jq -Rs . < /project/docs/spec.md)}" \
+  "http://localhost:$PORT/context-blocks?cwd=/project" | jq -r '.id')
+
+# Use in a delegate call
+curl -sf -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{\"tasks\":[{\"prompt\":\"Implement per spec\",\"contextBlockIds\":[\"$ID\"]}]}" \
+  "http://localhost:$PORT/delegate?cwd=/project"
+```
+
+@include _shared/error-handling.md