anantham-v2 2.0.0-alpha.1

package/dist/agents/subagent-manager.js

@@ -0,0 +1,222 @@
+import { randomUUID } from "node:crypto";
+import { AgentStartupPlanSchema } from "../domain/agent.js";
+import { EventTypes } from "../domain/event.js";
+import { DelegationGuard } from "./delegation-guard.js";
+/**
+ * Subagent Manager coordinating bounded hierarchical delegation,
+ * parent/child lifecycles, and cancellation propagation.
+ * PRD Part 2 Section 38, Section 40.
+ */
+export class SubagentManager {
+    agentManager;
+    agentRegistry;
+    delegationGuard;
+    eventStore;
+    leaseRepo;
+    // parentInstanceId -> Set of childInstanceIds
+    parentToChildren = new Map();
+    // childInstanceId -> parentInstanceId
+    childToParent = new Map();
+    constructor(options) {
+        this.agentManager = options.agentManager;
+        this.agentRegistry = options.agentRegistry;
+        this.delegationGuard = options.delegationGuard ?? new DelegationGuard();
+        this.eventStore = options.eventStore;
+        this.leaseRepo = options.leaseRepo;
+    }
+    getRegistry() {
+        return this.agentRegistry;
+    }
+    getLeaseRepo() {
+        return this.leaseRepo;
+    }
+    /**
+     * Delegate task/objective to a bounded subagent.
+     * PRD Part 2 Section 38.
+     */
+    delegate(request) {
+        // 1. Fetch parent instance
+        const parentInstance = this.agentManager.getInstance(request.parentInstanceId);
+        if (!parentInstance) {
+            return {
+                success: false,
+                errorCode: "PARENT_INSTANCE_NOT_FOUND",
+                errorMessage: `Parent agent instance "${request.parentInstanceId}" not found`,
+            };
+        }
+        // 2. Fetch parent startup plan
+        const parentPlan = parentInstance.startupPlan;
+        if (!parentPlan) {
+            return {
+                success: false,
+                errorCode: "PARENT_PLAN_NOT_FOUND",
+                errorMessage: `Parent startup plan not found on instance "${request.parentInstanceId}"`,
+            };
+        }
+        // 3. Count active children
+        const activeChildren = this.getActiveChildCount(request.parentInstanceId);
+        // 4. Guard check (depth, fan-out, permissions, budget)
+        const guardRes = this.delegationGuard.validateDelegation(parentInstance, parentPlan, request, activeChildren);
+        if (!guardRes.valid) {
+            return {
+                success: false,
+                errorCode: guardRes.errorCode,
+                errorMessage: guardRes.errorMessage,
+            };
+        }
+        // 5. Construct bounded child startup plan
+        const parentDepth = parentPlan.metadata?.delegationDepth ?? 0;
+        const childDepth = parentDepth + 1;
+        const childPlanId = `plan_sub_${randomUUID()}`;
+        const childBudget = {
+            maxTokens: request.allocatedBudget.maxTokens ?? parentPlan.budget.maxTokens,
+            maxCostUsd: request.allocatedBudget.maxCostUsd ?? parentPlan.budget.maxCostUsd,
+            maxToolCalls: request.allocatedBudget.maxToolCalls ?? parentPlan.budget.maxToolCalls,
+            maxDurationSeconds: request.allocatedBudget.maxDurationSeconds ?? parentPlan.budget.maxDurationSeconds,
+        };
+        const childPlan = {
+            planId: childPlanId,
+            agentId: request.childAgentId,
+            version: "1.0.0",
+            role: request.childRole,
+            objective: request.childObjective,
+            resolvedModel: parentPlan.resolvedModel,
+            resolvedCapabilities: request.requestedCapabilities.length > 0
+                ? request.requestedCapabilities
+                : parentPlan.resolvedCapabilities,
+            resolvedTools: request.requestedTools.length > 0
+                ? request.requestedTools
+                : parentPlan.resolvedTools,
+            resolvedSkills: request.requestedSkills.length > 0
+                ? request.requestedSkills
+                : parentPlan.resolvedSkills,
+            grantedPermissions: request.requestedPermissions.filter((p) => parentPlan.grantedPermissions.includes(p)),
+            executor: parentPlan.executor,
+            contextScope: {
+                ...parentPlan.contextScope,
+                ...request.contextScope,
+            },
+            memoryScope: {
+                ...parentPlan.memoryScope,
+                namespace: `agent:${request.childAgentId}`,
+                ...request.memoryScope,
+            },
+            budget: childBudget,
+            projectId: parentPlan.projectId, // Strictly locked to parent project
+            sessionId: parentPlan.sessionId,
+            resolvedAt: new Date().toISOString(),
+            metadata: {
+                parentAgentId: request.parentAgentId,
+                parentInstanceId: request.parentInstanceId,
+                delegationDepth: childDepth,
+                taskId: request.taskId,
+            },
+        };
+        AgentStartupPlanSchema.parse(childPlan);
+        // 6. Spawn child instance
+        const childInstance = this.agentManager.createInstance(childPlan);
+        // 7. Track hierarchy
+        if (!this.parentToChildren.has(request.parentInstanceId)) {
+            this.parentToChildren.set(request.parentInstanceId, new Set());
+        }
+        this.parentToChildren.get(request.parentInstanceId).add(childInstance.instanceId);
+        this.childToParent.set(childInstance.instanceId, request.parentInstanceId);
+        // 8. Emit durable events
+        this.emitEvent(EventTypes.SUBAGENT_SPAWNED, {
+            parentAgentId: request.parentAgentId,
+            parentInstanceId: request.parentInstanceId,
+            childAgentId: request.childAgentId,
+            childInstanceId: childInstance.instanceId,
+            delegationDepth: childDepth,
+            projectId: parentPlan.projectId,
+            sessionId: parentPlan.sessionId,
+            taskId: request.taskId,
+        });
+        this.emitEvent(EventTypes.SUBAGENT_DELEGATED, {
+            parentInstanceId: request.parentInstanceId,
+            childInstanceId: childInstance.instanceId,
+            role: request.childRole,
+            objective: request.childObjective,
+            projectId: parentPlan.projectId,
+            sessionId: parentPlan.sessionId,
+            taskId: request.taskId,
+        });
+        return {
+            success: true,
+            childPlan,
+            childInstanceId: childInstance.instanceId,
+        };
+    }
+    /**
+     * Recursively cancel an agent instance and all its active descendant subagents.
+     * PRD Part 2 Section 40.
+     */
+    propagateCancellation(parentInstanceId) {
+        const cancelledInstanceIds = [];
+        const queue = [parentInstanceId];
+        while (queue.length > 0) {
+            const currentId = queue.shift();
+            cancelledInstanceIds.push(currentId);
+            // Stop instance
+            this.agentManager.stopInstance(currentId);
+            // Find children
+            const children = this.parentToChildren.get(currentId);
+            if (children) {
+                for (const childId of children) {
+                    queue.push(childId);
+                }
+            }
+        }
+        return cancelledInstanceIds;
+    }
+    /**
+     * Get all direct child instances for a parent.
+     */
+    getChildInstances(parentInstanceId) {
+        const childIds = this.parentToChildren.get(parentInstanceId);
+        if (!childIds)
+            return [];
+        const instances = [];
+        for (const childId of childIds) {
+            const instance = this.agentManager.getInstance(childId);
+            if (instance)
+                instances.push(instance);
+        }
+        return instances;
+    }
+    getActiveChildCount(parentInstanceId) {
+        const childIds = this.parentToChildren.get(parentInstanceId);
+        if (!childIds)
+            return 0;
+        let activeCount = 0;
+        for (const childId of childIds) {
+            const instance = this.agentManager.getInstance(childId);
+            if (instance && (instance.status === "running" || instance.status === "ready")) {
+                activeCount++;
+            }
+        }
+        return activeCount;
+    }
+    emitEvent(type, payload) {
+        if (!this.eventStore)
+            return;
+        try {
+            this.eventStore.append({
+                id: `evt_${randomUUID()}`,
+                schemaVersion: 1,
+                type,
+                actor: "agent",
+                projectId: payload.projectId || "system",
+                sessionId: payload.sessionId ? payload.sessionId : undefined,
+                taskId: payload.taskId ? payload.taskId : undefined,
+                agentId: payload.childAgentId ? payload.childAgentId : payload.parentAgentId,
+                payload,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        catch {
+            // EventStore failure must not crash execution
+        }
+    }
+}
+//# sourceMappingURL=subagent-manager.js.map

package/dist/agents/subagent-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-manager.js","sourceRoot":"","sources":["../../src/agents/subagent-manager.ts"],"names":[],"mappings":"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"}

package/dist/api/api-authenticator.d.ts

@@ -0,0 +1,24 @@
+import { type IncomingMessage } from "node:http";
+import { type ApiAuthContext } from "../domain/api.js";
+export interface ApiAuthenticatorOptions {
+    apiKeys?: Map<string, {
+        actorId: string;
+        role: string;
+        allowedProjects: string[];
+    }>;
+    allowAnonymous?: boolean;
+}
+/**
+ * API Authenticator validating Bearer tokens and API keys.
+ * PRD Part 1 Section 32 & PRD Part 2 Section 200.
+ */
+export declare class ApiAuthenticator {
+    private readonly apiKeys;
+    private readonly allowAnonymous;
+    constructor(options?: ApiAuthenticatorOptions);
+    /**
+     * Authenticate incoming HTTP request.
+     */
+    authenticate(req: IncomingMessage): ApiAuthContext;
+}
+//# sourceMappingURL=api-authenticator.d.ts.map

package/dist/api/api-authenticator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-authenticator.d.ts","sourceRoot":"","sources":["../../src/api/api-authenticator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,KAAK,cAAc,EAAwB,MAAM,kBAAkB,CAAC;AAE7E,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACpF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4E;IACpG,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;gBAE7B,OAAO,GAAE,uBAA4B;IAcjD;;OAEG;IACI,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,cAAc;CAuC1D"}

package/dist/api/api-authenticator.js

@@ -0,0 +1,61 @@
+import { ApiAuthContextSchema } from "../domain/api.js";
+/**
+ * API Authenticator validating Bearer tokens and API keys.
+ * PRD Part 1 Section 32 & PRD Part 2 Section 200.
+ */
+export class ApiAuthenticator {
+    apiKeys;
+    allowAnonymous;
+    constructor(options = {}) {
+        this.apiKeys = options.apiKeys ?? new Map();
+        this.allowAnonymous = options.allowAnonymous ?? false;
+        // Default development operator key if none configured
+        if (this.apiKeys.size === 0) {
+            this.apiKeys.set("anantham-dev-key", {
+                actorId: "dev_operator",
+                role: "admin",
+                allowedProjects: ["*"],
+            });
+        }
+    }
+    /**
+     * Authenticate incoming HTTP request.
+     */
+    authenticate(req) {
+        const authHeader = req.headers["authorization"];
+        const apiKeyHeader = req.headers["x-api-key"];
+        let token = "";
+        if (authHeader && authHeader.startsWith("Bearer ")) {
+            token = authHeader.slice(7).trim();
+        }
+        else if (typeof apiKeyHeader === "string") {
+            token = apiKeyHeader.trim();
+        }
+        if (token) {
+            const keyInfo = this.apiKeys.get(token);
+            if (keyInfo) {
+                return ApiAuthContextSchema.parse({
+                    authenticated: true,
+                    actorId: keyInfo.actorId,
+                    role: keyInfo.role,
+                    allowedProjects: keyInfo.allowedProjects,
+                });
+            }
+        }
+        if (this.allowAnonymous) {
+            return ApiAuthContextSchema.parse({
+                authenticated: true,
+                actorId: "anonymous_user",
+                role: "viewer",
+                allowedProjects: ["*"],
+            });
+        }
+        return ApiAuthContextSchema.parse({
+            authenticated: false,
+            actorId: "unauthenticated",
+            role: "none",
+            allowedProjects: [],
+        });
+    }
+}
+//# sourceMappingURL=api-authenticator.js.map

package/dist/api/api-authenticator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-authenticator.js","sourceRoot":"","sources":["../../src/api/api-authenticator.ts"],"names":[],"mappings":"AACA,OAAO,EAAuB,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAO7E;;;GAGG;AACH,MAAM,OAAO,gBAAgB;IACV,OAAO,CAA4E;IACnF,cAAc,CAAU;IAEzC,YAAY,UAAmC,EAAE;QAC/C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,GAAG,EAAE,CAAC;QAC5C,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,KAAK,CAAC;QAEtD,sDAAsD;QACtD,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE;gBACnC,OAAO,EAAE,cAAc;gBACvB,IAAI,EAAE,OAAO;gBACb,eAAe,EAAE,CAAC,GAAG,CAAC;aACvB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;OAEG;IACI,YAAY,CAAC,GAAoB;QACtC,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QAChD,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAE9C,IAAI,KAAK,GAAG,EAAE,CAAC;QACf,IAAI,UAAU,IAAI,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACnD,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,CAAC;aAAM,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;YAC5C,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC;QAC9B,CAAC;QAED,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACxC,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,oBAAoB,CAAC,KAAK,CAAC;oBAChC,aAAa,EAAE,IAAI;oBACnB,OAAO,EAAE,OAAO,CAAC,OAAO;oBACxB,IAAI,EAAE,OAAO,CAAC,IAAI;oBAClB,eAAe,EAAE,OAAO,CAAC,eAAe;iBACzC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,OAAO,oBAAoB,CAAC,KAAK,CAAC;gBAChC,aAAa,EAAE,IAAI;gBACnB,OAAO,EAAE,gBAAgB;gBACzB,IAAI,EAAE,QAAQ;gBACd,eAAe,EAAE,CAAC,GAAG,CAAC;aACvB,CAAC,CAAC;QACL,CAAC;QAED,OAAO,oBAAoB,CAAC,KAAK,CAAC;YAChC,aAAa,EAAE,KAAK;YACpB,OAAO,EAAE,iBAAiB;YAC1B,IAAI,EAAE,MAAM;YACZ,eAAe,EAAE,EAAE;SACpB,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/api/api-authorizer.d.ts

@@ -0,0 +1,16 @@
+import { type ApiAuthContext } from "../domain/api.js";
+/**
+ * API Authorizer enforcing project tenant containment and role permissions.
+ * PRD Part 1 Section 34 & PRD Part 2 Section 200.
+ */
+export declare class ApiAuthorizer {
+    /**
+     * Enforce project containment for request context.
+     */
+    static authorizeProject(auth: ApiAuthContext, projectId: string): boolean;
+    /**
+     * Enforce role-based access for privileged operations.
+     */
+    static authorizeRole(auth: ApiAuthContext, requiredRole: "viewer" | "operator" | "admin"): boolean;
+}
+//# sourceMappingURL=api-authorizer.d.ts.map

package/dist/api/api-authorizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-authorizer.d.ts","sourceRoot":"","sources":["../../src/api/api-authorizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;GAGG;AACH,qBAAa,aAAa;IACxB;;OAEG;WACW,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAMhF;;OAEG;WACW,aAAa,CAAC,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO;CAO1G"}

package/dist/api/api-authorizer.js

@@ -0,0 +1,31 @@
+/**
+ * API Authorizer enforcing project tenant containment and role permissions.
+ * PRD Part 1 Section 34 & PRD Part 2 Section 200.
+ */
+export class ApiAuthorizer {
+    /**
+     * Enforce project containment for request context.
+     */
+    static authorizeProject(auth, projectId) {
+        if (!auth.authenticated)
+            return false;
+        if (auth.allowedProjects.includes("*"))
+            return true;
+        return auth.allowedProjects.includes(projectId);
+    }
+    /**
+     * Enforce role-based access for privileged operations.
+     */
+    static authorizeRole(auth, requiredRole) {
+        if (!auth.authenticated)
+            return false;
+        if (auth.role === "admin")
+            return true;
+        if (auth.role === "operator" && requiredRole !== "admin")
+            return true;
+        if (auth.role === "viewer" && requiredRole === "viewer")
+            return true;
+        return false;
+    }
+}
+//# sourceMappingURL=api-authorizer.js.map

package/dist/api/api-authorizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-authorizer.js","sourceRoot":"","sources":["../../src/api/api-authorizer.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,aAAa;IACxB;;OAEG;IACI,MAAM,CAAC,gBAAgB,CAAC,IAAoB,EAAE,SAAiB;QACpE,IAAI,CAAC,IAAI,CAAC,aAAa;YAAE,OAAO,KAAK,CAAC;QACtC,IAAI,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QACpD,OAAO,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,aAAa,CAAC,IAAoB,EAAE,YAA6C;QAC7F,IAAI,CAAC,IAAI,CAAC,aAAa;YAAE,OAAO,KAAK,CAAC;QACtC,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC;QACvC,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,YAAY,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC;QACtE,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,YAAY,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACrE,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/api/api-error-mapper.d.ts

@@ -0,0 +1,15 @@
+import { type ApiErrorResponse } from "../domain/api.js";
+/**
+ * Standardized HTTP Error Mapper preserving runtime classifications.
+ * PRD Part 1 Section 60 & PRD Part 2 Section 200.
+ */
+export declare class ApiErrorMapper {
+    /**
+     * Map any caught error to HTTP status code and structured response envelope.
+     */
+    static mapError(error: unknown): {
+        statusCode: number;
+        response: ApiErrorResponse;
+    };
+}
+//# sourceMappingURL=api-error-mapper.d.ts.map

package/dist/api/api-error-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-error-mapper.d.ts","sourceRoot":"","sources":["../../src/api/api-error-mapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAA0B,MAAM,kBAAkB,CAAC;AAEjF;;;GAGG;AACH,qBAAa,cAAc;IACzB;;OAEG;WACW,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,gBAAgB,CAAA;KAAE;CAyD3F"}

package/dist/api/api-error-mapper.js

@@ -0,0 +1,68 @@
+import { ApiErrorResponseSchema } from "../domain/api.js";
+/**
+ * Standardized HTTP Error Mapper preserving runtime classifications.
+ * PRD Part 1 Section 60 & PRD Part 2 Section 200.
+ */
+export class ApiErrorMapper {
+    /**
+     * Map any caught error to HTTP status code and structured response envelope.
+     */
+    static mapError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const lower = message.toLowerCase();
+        let statusCode = 500;
+        let classification = "INTERNAL_ERROR";
+        let code = "internal_server_error";
+        if (lower.includes("unauthorized") || lower.includes("unauthenticated") || lower.includes("missing token")) {
+            statusCode = 401;
+            classification = "UNAUTHORIZED";
+            code = "unauthorized";
+        }
+        else if (lower.includes("forbidden") || lower.includes("boundary violation") || lower.includes("policy denial")) {
+            statusCode = 403;
+            classification = "FORBIDDEN";
+            code = "forbidden";
+        }
+        else if (lower.includes("not found") || lower.includes("does not exist") || lower.includes("no active")) {
+            statusCode = 404;
+            classification = "NOT_FOUND";
+            code = "not_found";
+        }
+        else if (lower.includes("idempotency")) {
+            statusCode = 409;
+            classification = "IDEMPOTENCY_CONFLICT";
+            code = "conflict";
+        }
+        else if (lower.includes("fencing") || lower.includes("stale") || lower.includes("conflict")) {
+            statusCode = 409;
+            classification = "LEASE_FENCING_ERROR";
+            code = "conflict";
+        }
+        else if (lower.includes("validation") ||
+            lower.includes("invalid") ||
+            lower.includes("schema") ||
+            lower.includes("required") ||
+            lower.includes("too_small") ||
+            lower.includes("too_big") ||
+            lower.includes("invalid_type")) {
+            statusCode = 400;
+            classification = "VALIDATION_ERROR";
+            code = "bad_request";
+        }
+        else if (lower.includes("rate limit") || lower.includes("too many requests")) {
+            statusCode = 429;
+            classification = "RATE_LIMITED";
+            code = "too_many_requests";
+        }
+        const response = ApiErrorResponseSchema.parse({
+            success: false,
+            error: {
+                code,
+                message,
+                classification,
+            },
+        });
+        return { statusCode, response };
+    }
+}
+//# sourceMappingURL=api-error-mapper.js.map

package/dist/api/api-error-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-error-mapper.js","sourceRoot":"","sources":["../../src/api/api-error-mapper.ts"],"names":[],"mappings":"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"}

package/dist/api/api-idempotency-manager.d.ts

@@ -0,0 +1,31 @@
+/**
+ * In-memory / durable Idempotency Manager for mutating REST operations.
+ * PRD Part 2 Section 205.
+ */
+export interface CachedResponse {
+    statusCode: number;
+    responseBody: unknown;
+    timestamp: string;
+    method?: string;
+    pathname?: string;
+    bodyHash?: string;
+}
+export interface RequestIdempotencyContext {
+    method: string;
+    pathname: string;
+    bodyHash?: string;
+}
+export declare class IdempotencyConflictError extends Error {
+    constructor(message: string);
+}
+export declare class ApiIdempotencyManager {
+    private readonly cache;
+    private readonly ttlMs;
+    constructor(options?: {
+        ttlMs?: number;
+    });
+    get(key: string, context?: RequestIdempotencyContext): CachedResponse | undefined;
+    set(key: string, statusCode: number, responseBody: unknown, context?: RequestIdempotencyContext): void;
+    clear(): void;
+}
+//# sourceMappingURL=api-idempotency-manager.d.ts.map

package/dist/api/api-idempotency-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-idempotency-manager.d.ts","sourceRoot":"","sources":["../../src/api/api-idempotency-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO;IAIrC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,cAAc,GAAG,SAAS;IAyBjF,GAAG,CACR,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,OAAO,EACrB,OAAO,CAAC,EAAE,yBAAyB,GAClC,IAAI;IAWA,KAAK,IAAI,IAAI;CAGrB"}

package/dist/api/api-idempotency-manager.js

@@ -0,0 +1,46 @@
+export class IdempotencyConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IdempotencyConflictError";
+    }
+}
+export class ApiIdempotencyManager {
+    cache = new Map();
+    ttlMs;
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? 300_000; // 5 minutes default
+    }
+    get(key, context) {
+        const cached = this.cache.get(key);
+        if (!cached)
+            return undefined;
+        const age = Date.now() - new Date(cached.timestamp).getTime();
+        if (age > this.ttlMs) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        if (context && cached.method && cached.pathname) {
+            const methodMatch = cached.method === context.method;
+            const pathMatch = cached.pathname === context.pathname;
+            const bodyMatch = !cached.bodyHash || !context.bodyHash || cached.bodyHash === context.bodyHash;
+            if (!methodMatch || !pathMatch || !bodyMatch) {
+                throw new IdempotencyConflictError(`Idempotency-Key '${key}' is already bound to a different request (${cached.method} ${cached.pathname}).`);
+            }
+        }
+        return cached;
+    }
+    set(key, statusCode, responseBody, context) {
+        this.cache.set(key, {
+            statusCode,
+            responseBody,
+            timestamp: new Date().toISOString(),
+            method: context?.method,
+            pathname: context?.pathname,
+            bodyHash: context?.bodyHash,
+        });
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+//# sourceMappingURL=api-idempotency-manager.js.map

package/dist/api/api-idempotency-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-idempotency-manager.js","sourceRoot":"","sources":["../../src/api/api-idempotency-manager.ts"],"names":[],"mappings":"AAmBA,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,MAAM,OAAO,qBAAqB;IACf,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC1C,KAAK,CAAS;IAE/B,YAAY,UAA8B,EAAE;QAC1C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,oBAAoB;IAC7D,CAAC;IAEM,GAAG,CAAC,GAAW,EAAE,OAAmC;QACzD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,MAAM;YAAE,OAAO,SAAS,CAAC;QAE9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;QAC9D,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;YACrB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,OAAO,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YAChD,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC;YACrD,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC;YACvD,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC;YAEhG,IAAI,CAAC,WAAW,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,EAAE,CAAC;gBAC7C,MAAM,IAAI,wBAAwB,CAChC,oBAAoB,GAAG,8CAA8C,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,IAAI,CAC1G,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAEM,GAAG,CACR,GAAW,EACX,UAAkB,EAClB,YAAqB,EACrB,OAAmC;QAEnC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,UAAU;YACV,YAAY;YACZ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,MAAM,EAAE,OAAO,EAAE,MAAM;YACvB,QAAQ,EAAE,OAAO,EAAE,QAAQ;YAC3B,QAAQ,EAAE,OAAO,EAAE,QAAQ;SAC5B,CAAC,CAAC;IACL,CAAC;IAEM,KAAK;QACV,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/api/api-router.d.ts

@@ -0,0 +1,54 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { type SqliteEngine } from "../persistence/sqlite-engine.js";
+import { type ProjectRepository } from "../persistence/repositories/project-repository.js";
+import { type SessionRepository } from "../persistence/repositories/session-repository.js";
+import { type TaskRepository } from "../persistence/repositories/task-repository.js";
+import { type JobRepository } from "../persistence/repositories/job-repository.js";
+import { type NodeRepository } from "../persistence/repositories/node-repository.js";
+import { type ArtifactRepository } from "../persistence/repositories/artifact-repository.js";
+import { type EventStore } from "../event-state/event-store.js";
+import { type TaskClaimManager } from "../tasks/task-claim-manager.js";
+import { type CrashRecoveryEngine } from "../recovery/crash-recovery-engine.js";
+import { ApiAuthenticator } from "./api-authenticator.js";
+import { ApiIdempotencyManager } from "./api-idempotency-manager.js";
+export interface ApiRouterOptions {
+    engine: SqliteEngine;
+    projectRepo: ProjectRepository;
+    sessionRepo: SessionRepository;
+    taskRepo: TaskRepository;
+    jobRepo: JobRepository;
+    nodeRepo: NodeRepository;
+    artifactRepo: ArtifactRepository;
+    eventStore: EventStore;
+    claimManager?: TaskClaimManager;
+    recoveryEngine?: CrashRecoveryEngine;
+    authenticator?: ApiAuthenticator;
+    idempotencyManager?: ApiIdempotencyManager;
+}
+/**
+ * REST API Router & Request Dispatcher.
+ * PRD Part 2 Section 200–215.
+ */
+export declare class ApiRouter {
+    readonly engine: SqliteEngine;
+    readonly projectRepo: ProjectRepository;
+    readonly sessionRepo: SessionRepository;
+    readonly taskRepo: TaskRepository;
+    readonly jobRepo: JobRepository;
+    readonly nodeRepo: NodeRepository;
+    readonly artifactRepo: ArtifactRepository;
+    readonly eventStore: EventStore;
+    readonly claimManager?: TaskClaimManager;
+    readonly recoveryEngine?: CrashRecoveryEngine;
+    readonly authenticator: ApiAuthenticator;
+    readonly idempotencyManager: ApiIdempotencyManager;
+    constructor(options: ApiRouterOptions);
+    /**
+     * Handle incoming HTTP request and route to appropriate controller.
+     */
+    handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    private sendJson;
+    private sendError;
+    private readRequestBody;
+}
+//# sourceMappingURL=api-router.d.ts.map

package/dist/api/api-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-router.d.ts","sourceRoot":"","sources":["../../src/api/api-router.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAWtE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,mDAAmD,CAAC;AAC3F,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,mDAAmD,CAAC;AAC3F,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,gDAAgD,CAAC;AACrF,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,+CAA+C,CAAC;AACnF,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,gDAAgD,CAAC;AACrF,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,oDAAoD,CAAC;AAC7F,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAEhF,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,cAAc,CAAC;IACzB,YAAY,EAAE,kBAAkB,CAAC;IACjC,UAAU,EAAE,UAAU,CAAC;IACvB,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,aAAa,CAAC,EAAE,gBAAgB,CAAC;IACjC,kBAAkB,CAAC,EAAE,qBAAqB,CAAC;CAC5C;AAED;;;GAGG;AACH,qBAAa,SAAS;IACpB,SAAgB,MAAM,EAAE,YAAY,CAAC;IACrC,SAAgB,WAAW,EAAE,iBAAiB,CAAC;IAC/C,SAAgB,WAAW,EAAE,iBAAiB,CAAC;IAC/C,SAAgB,QAAQ,EAAE,cAAc,CAAC;IACzC,SAAgB,OAAO,EAAE,aAAa,CAAC;IACvC,SAAgB,QAAQ,EAAE,cAAc,CAAC;IACzC,SAAgB,YAAY,EAAE,kBAAkB,CAAC;IACjD,SAAgB,UAAU,EAAE,UAAU,CAAC;IACvC,SAAgB,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChD,SAAgB,cAAc,CAAC,EAAE,mBAAmB,CAAC;IAErD,SAAgB,aAAa,EAAE,gBAAgB,CAAC;IAChD,SAAgB,kBAAkB,EAAE,qBAAqB,CAAC;gBAE9C,OAAO,EAAE,gBAAgB;IAgBrC;;OAEG;IACU,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAydpF,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,SAAS;YAKH,eAAe;CAyB9B"}