comisai 1.0.4

package/node_modules/@comis/core/dist/domain/agent-response.d.ts

@@ -0,0 +1,55 @@
+import { type Result } from "@comis/shared";
+import { z } from "zod";
+/**
+ * A single tool invocation requested by the agent.
+ */
+export declare const ToolCallSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    input: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type ToolCall = z.infer<typeof ToolCallSchema>;
+/**
+ * Token usage breakdown for observability and budget tracking.
+ */
+export declare const TokenUsageSchema: z.ZodObject<{
+    prompt: z.ZodNumber;
+    completion: z.ZodNumber;
+    provider: z.ZodString;
+    model: z.ZodString;
+}, z.core.$strict>;
+export type TokenUsage = z.infer<typeof TokenUsageSchema>;
+/**
+ * AgentResponse: The structured output from an AI agent invocation.
+ *
+ * Captures content, tool calls, token usage (for budget guards), and
+ * finish reason to drive orchestration decisions.
+ */
+export declare const AgentResponseSchema: z.ZodObject<{
+    agentId: z.ZodString;
+    content: z.ZodString;
+    toolCalls: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        input: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>>;
+    tokensUsed: z.ZodOptional<z.ZodObject<{
+        prompt: z.ZodNumber;
+        completion: z.ZodNumber;
+        provider: z.ZodString;
+        model: z.ZodString;
+    }, z.core.$strict>>;
+    finishReason: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        budget_exceeded: "budget_exceeded";
+        stop: "stop";
+        max_tokens: "max_tokens";
+        tool_use: "tool_use";
+    }>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type AgentResponse = z.infer<typeof AgentResponseSchema>;
+/**
+ * Parse unknown input into an AgentResponse, returning Result<T, ZodError>.
+ */
+export declare function parseAgentResponse(raw: unknown): Result<AgentResponse, z.ZodError>;

package/node_modules/@comis/core/dist/domain/agent-response.js

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+import { ok, err } from "@comis/shared";
+import { z } from "zod";
+/**
+ * A single tool invocation requested by the agent.
+ */
+export const ToolCallSchema = z.strictObject({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    input: z.record(z.string(), z.unknown()).default({}),
+});
+/**
+ * Token usage breakdown for observability and budget tracking.
+ */
+export const TokenUsageSchema = z.strictObject({
+    prompt: z.number().int().nonnegative(),
+    completion: z.number().int().nonnegative(),
+    provider: z.string().min(1),
+    model: z.string().min(1),
+});
+/**
+ * AgentResponse: The structured output from an AI agent invocation.
+ *
+ * Captures content, tool calls, token usage (for budget guards), and
+ * finish reason to drive orchestration decisions.
+ */
+export const AgentResponseSchema = z.strictObject({
+    agentId: z.string().min(1),
+    content: z.string(),
+    toolCalls: z.array(ToolCallSchema).default([]),
+    tokensUsed: TokenUsageSchema.optional(),
+    finishReason: z
+        .enum(["stop", "max_tokens", "tool_use", "error", "budget_exceeded"])
+        .default("stop"),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+});
+/**
+ * Parse unknown input into an AgentResponse, returning Result<T, ZodError>.
+ */
+export function parseAgentResponse(raw) {
+    const result = AgentResponseSchema.safeParse(raw);
+    if (result.success) {
+        return ok(result.data);
+    }
+    return err(result.error);
+}

package/node_modules/@comis/core/dist/domain/agent-response.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@comis/core/dist/domain/agent-response.test.js

@@ -0,0 +1,159 @@
+import { describe, expect, it } from "vitest";
+import { parseAgentResponse } from "./agent-response.js";
+function validResponse(overrides = {}) {
+    return {
+        agentId: "main-agent",
+        content: "Here is my response.",
+        ...overrides,
+    };
+}
+describe("AgentResponse", () => {
+    describe("valid data", () => {
+        it("parses a minimal valid response", () => {
+            const result = parseAgentResponse(validResponse());
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value.agentId).toBe("main-agent");
+                expect(result.value.content).toBe("Here is my response.");
+            }
+        });
+        it("applies default values for toolCalls, finishReason, metadata", () => {
+            const result = parseAgentResponse(validResponse());
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value.toolCalls).toEqual([]);
+                expect(result.value.finishReason).toBe("stop");
+                expect(result.value.metadata).toEqual({});
+            }
+        });
+        it("accepts empty content (agent may return only tool calls)", () => {
+            const result = parseAgentResponse(validResponse({ content: "" }));
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value.content).toBe("");
+            }
+        });
+        it("accepts all finish reasons", () => {
+            const reasons = ["stop", "max_tokens", "tool_use", "error", "budget_exceeded"];
+            for (const finishReason of reasons) {
+                const result = parseAgentResponse(validResponse({ finishReason }));
+                expect(result.ok).toBe(true);
+            }
+        });
+        it("accepts tool calls array", () => {
+            const result = parseAgentResponse(validResponse({
+                toolCalls: [
+                    { id: "tc-1", name: "search", input: { query: "test" } },
+                    { id: "tc-2", name: "read_file", input: { path: "/tmp/a.txt" } },
+                ],
+            }));
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value.toolCalls).toHaveLength(2);
+                expect(result.value.toolCalls[0].name).toBe("search");
+            }
+        });
+        it("accepts tokensUsed when provided", () => {
+            const result = parseAgentResponse(validResponse({
+                tokensUsed: {
+                    prompt: 100,
+                    completion: 50,
+                    provider: "anthropic",
+                    model: "claude-opus-4-20250514",
+                },
+            }));
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value.tokensUsed?.prompt).toBe(100);
+                expect(result.value.tokensUsed?.provider).toBe("anthropic");
+            }
+        });
+        it("allows omitting optional tokensUsed", () => {
+            const result = parseAgentResponse(validResponse());
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value.tokensUsed).toBeUndefined();
+            }
+        });
+        it("accepts metadata with arbitrary values", () => {
+            const result = parseAgentResponse(validResponse({
+                metadata: { latencyMs: 234, cached: false },
+            }));
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value.metadata).toEqual({
+                    latencyMs: 234,
+                    cached: false,
+                });
+            }
+        });
+    });
+    describe("invalid data", () => {
+        it("rejects missing required fields", () => {
+            const result = parseAgentResponse({});
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                const paths = result.error.issues.map((i) => i.path[0]);
+                expect(paths).toContain("agentId");
+                expect(paths).toContain("content");
+            }
+        });
+        it("rejects empty agentId", () => {
+            const result = parseAgentResponse(validResponse({ agentId: "" }));
+            expect(result.ok).toBe(false);
+        });
+        it("rejects invalid finishReason", () => {
+            const result = parseAgentResponse(validResponse({ finishReason: "cancelled" }));
+            expect(result.ok).toBe(false);
+        });
+        it("rejects invalid tool call shape", () => {
+            const result = parseAgentResponse(validResponse({ toolCalls: [{ bad: "shape" }] }));
+            expect(result.ok).toBe(false);
+        });
+        it("rejects tool call with empty id", () => {
+            const result = parseAgentResponse(validResponse({
+                toolCalls: [{ id: "", name: "search", input: {} }],
+            }));
+            expect(result.ok).toBe(false);
+        });
+        it("rejects tool call with empty name", () => {
+            const result = parseAgentResponse(validResponse({
+                toolCalls: [{ id: "tc-1", name: "", input: {} }],
+            }));
+            expect(result.ok).toBe(false);
+        });
+        it("rejects invalid tokensUsed shape", () => {
+            const result = parseAgentResponse(validResponse({ tokensUsed: { prompt: "not a number" } }));
+            expect(result.ok).toBe(false);
+        });
+        it("rejects negative token counts", () => {
+            const result = parseAgentResponse(validResponse({
+                tokensUsed: {
+                    prompt: -1,
+                    completion: 50,
+                    provider: "openai",
+                    model: "gpt-4",
+                },
+            }));
+            expect(result.ok).toBe(false);
+        });
+        it("strips extra/unknown fields", () => {
+            const result = parseAgentResponse(validResponse({ unknownField: "surprise" }));
+            expect(result.ok).toBe(false);
+        });
+        it("rejects non-object input", () => {
+            const result = parseAgentResponse(42);
+            expect(result.ok).toBe(false);
+        });
+        it("returns descriptive ZodError issues", () => {
+            const result = parseAgentResponse({ agentId: 123 });
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.error.issues.length).toBeGreaterThan(0);
+                for (const issue of result.error.issues) {
+                    expect(issue.message).toBeTruthy();
+                }
+            }
+        });
+    });
+});

package/node_modules/@comis/core/dist/domain/approval-request.d.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+/**
+ * ApprovalRequest: A pending approval for a privileged agent action.
+ *
+ * When an agent invokes a tool classified as requiring human confirmation,
+ * the approval gate creates an ApprovalRequest and pauses execution until
+ * an operator approves, denies, or the request times out.
+ *
+ * Captures who, what, and why for audit.
+ *
+ * @module
+ */
+/**
+ * Schema for an approval request submitted by the approval gate.
+ *
+ * Fields capture the full context needed for an operator to make an
+ * informed approve/deny decision.
+ */
+export declare const ApprovalRequestSchema: z.ZodObject<{
+    /** Unique identifier for this approval request */
+    requestId: z.ZodString;
+    /** Name of the tool being invoked */
+    toolName: z.ZodString;
+    /** The classified action (e.g., "agents.delete") */
+    action: z.ZodString;
+    /** Tool parameters (sanitized, no secrets) */
+    params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    /** The agent that triggered the action */
+    agentId: z.ZodString;
+    /** Session context identifier */
+    sessionKey: z.ZodString;
+    /** Trust level of the requesting user */
+    trustLevel: z.ZodEnum<{
+        admin: "admin";
+        user: "user";
+        guest: "guest";
+    }>;
+    /** Timestamp when the request was created (epoch ms) */
+    createdAt: z.ZodNumber;
+    /** How long before auto-deny (ms) */
+    timeoutMs: z.ZodNumber;
+}, z.core.$strict>;
+/** An approval request awaiting operator decision. */
+export type ApprovalRequest = z.infer<typeof ApprovalRequestSchema>;
+/**
+ * Schema for the resolution of an approval request.
+ *
+ * Created when an operator approves/denies or the request times out.
+ */
+export declare const ApprovalResolutionSchema: z.ZodObject<{
+    /** The request being resolved */
+    requestId: z.ZodString;
+    /** Whether the action was approved */
+    approved: z.ZodBoolean;
+    /** Who approved/denied (operator ID or "system:timeout") */
+    approvedBy: z.ZodString;
+    /** Optional reason for the decision */
+    reason: z.ZodOptional<z.ZodString>;
+    /** Timestamp when the resolution was made (epoch ms) */
+    resolvedAt: z.ZodNumber;
+}, z.core.$strict>;
+/** The resolution outcome of an approval request. */
+export type ApprovalResolution = z.infer<typeof ApprovalResolutionSchema>;
+/** Schema for a serialized pending approval request (for restart persistence). */
+export declare const SerializedApprovalRequestSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    toolName: z.ZodString;
+    action: z.ZodString;
+    params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    agentId: z.ZodString;
+    sessionKey: z.ZodString;
+    trustLevel: z.ZodEnum<{
+        admin: "admin";
+        user: "user";
+        guest: "guest";
+    }>;
+    createdAt: z.ZodNumber;
+    timeoutMs: z.ZodNumber;
+}, z.core.$strict>;
+/** A serialized approval request for persistence across restarts. */
+export type SerializedApprovalRequest = z.infer<typeof SerializedApprovalRequestSchema>;
+/** Schema for a serialized approval cache entry (for restart persistence of cached approvals). */
+export declare const SerializedApprovalCacheEntrySchema: z.ZodObject<{
+    /** The cache key: "${sessionKey}::${action}" */
+    cacheKey: z.ZodString;
+    /** The cached approval resolution */
+    resolution: z.ZodObject<{
+        requestId: z.ZodString;
+        approved: z.ZodBoolean;
+        approvedBy: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+        resolvedAt: z.ZodNumber;
+    }, z.core.$strict>;
+    /** Absolute expiry timestamp (epoch ms) */
+    expiresAt: z.ZodNumber;
+}, z.core.$strict>;
+/** A serialized approval cache entry for persistence across restarts. */
+export type SerializedApprovalCacheEntry = z.infer<typeof SerializedApprovalCacheEntrySchema>;

package/node_modules/@comis/core/dist/domain/approval-request.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from "zod";
+/**
+ * ApprovalRequest: A pending approval for a privileged agent action.
+ *
+ * When an agent invokes a tool classified as requiring human confirmation,
+ * the approval gate creates an ApprovalRequest and pauses execution until
+ * an operator approves, denies, or the request times out.
+ *
+ * Captures who, what, and why for audit.
+ *
+ * @module
+ */
+/**
+ * Schema for an approval request submitted by the approval gate.
+ *
+ * Fields capture the full context needed for an operator to make an
+ * informed approve/deny decision.
+ */
+export const ApprovalRequestSchema = z.strictObject({
+    /** Unique identifier for this approval request */
+    requestId: z.string().uuid(),
+    /** Name of the tool being invoked */
+    toolName: z.string(),
+    /** The classified action (e.g., "agents.delete") */
+    action: z.string(),
+    /** Tool parameters (sanitized, no secrets) */
+    params: z.record(z.string(), z.unknown()),
+    /** The agent that triggered the action */
+    agentId: z.string(),
+    /** Session context identifier */
+    sessionKey: z.string(),
+    /** Trust level of the requesting user */
+    trustLevel: z.enum(["admin", "user", "guest"]),
+    /** Timestamp when the request was created (epoch ms) */
+    createdAt: z.number(),
+    /** How long before auto-deny (ms) */
+    timeoutMs: z.number().int().positive(),
+});
+/**
+ * Schema for the resolution of an approval request.
+ *
+ * Created when an operator approves/denies or the request times out.
+ */
+export const ApprovalResolutionSchema = z.strictObject({
+    /** The request being resolved */
+    requestId: z.string().uuid(),
+    /** Whether the action was approved */
+    approved: z.boolean(),
+    /** Who approved/denied (operator ID or "system:timeout") */
+    approvedBy: z.string(),
+    /** Optional reason for the decision */
+    reason: z.string().optional(),
+    /** Timestamp when the resolution was made (epoch ms) */
+    resolvedAt: z.number(),
+});
+/** Schema for a serialized pending approval request (for restart persistence). */
+export const SerializedApprovalRequestSchema = z.strictObject({
+    requestId: z.string().uuid(),
+    toolName: z.string(),
+    action: z.string(),
+    params: z.record(z.string(), z.unknown()),
+    agentId: z.string(),
+    sessionKey: z.string(),
+    trustLevel: z.enum(["admin", "user", "guest"]),
+    createdAt: z.number(),
+    timeoutMs: z.number().int().positive(),
+});
+/** Schema for a serialized approval cache entry (for restart persistence of cached approvals). */
+export const SerializedApprovalCacheEntrySchema = z.strictObject({
+    /** The cache key: "${sessionKey}::${action}" */
+    cacheKey: z.string(),
+    /** The cached approval resolution */
+    resolution: z.strictObject({
+        requestId: z.string().uuid(),
+        approved: z.boolean(),
+        approvedBy: z.string(),
+        reason: z.string().optional(),
+        resolvedAt: z.number(),
+    }),
+    /** Absolute expiry timestamp (epoch ms) */
+    expiresAt: z.number(),
+});

package/node_modules/@comis/core/dist/domain/credential-mapping.d.ts

@@ -0,0 +1,46 @@
+import { type Result } from "@comis/shared";
+import { z } from "zod";
+/**
+ * InjectionType: How a credential is injected into an outbound HTTP request.
+ *
+ * - `bearer_header` — Authorization: Bearer <secret>
+ * - `custom_header` — Arbitrary header (injectionKey = header name)
+ * - `query_param` — URL query parameter (injectionKey = param name)
+ * - `basic_auth` — Authorization: Basic base64(<secret>)
+ */
+export declare const InjectionTypeSchema: z.ZodEnum<{
+    bearer_header: "bearer_header";
+    custom_header: "custom_header";
+    query_param: "query_param";
+    basic_auth: "basic_auth";
+}>;
+export type InjectionType = z.infer<typeof InjectionTypeSchema>;
+/**
+ * CredentialMapping: Binds an encrypted secret to an injection strategy
+ * for a specific URL pattern and optional tool name.
+ *
+ * The CredentialInjector reads these mappings at request time to decide
+ * which secret to inject, how to inject it, and which URLs it applies to.
+ */
+export declare const CredentialMappingSchema: z.ZodObject<{
+    id: z.ZodString;
+    secretName: z.ZodString;
+    injectionType: z.ZodEnum<{
+        bearer_header: "bearer_header";
+        custom_header: "custom_header";
+        query_param: "query_param";
+        basic_auth: "basic_auth";
+    }>;
+    injectionKey: z.ZodOptional<z.ZodString>;
+    urlPattern: z.ZodString;
+    toolName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CredentialMapping = z.infer<typeof CredentialMappingSchema>;
+/**
+ * Parse unknown input into a CredentialMapping, returning Result<T, Error>.
+ *
+ * Uses Zod .safeParse() and wraps the result in the shared Result type.
+ * Refinement errors (missing injectionKey for custom_header/query_param)
+ * are included in the ZodError issues array.
+ */
+export declare function parseCredentialMapping(input: unknown): Result<CredentialMapping, z.ZodError>;

package/node_modules/@comis/core/dist/domain/credential-mapping.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+import { ok, err } from "@comis/shared";
+import { z } from "zod";
+/**
+ * InjectionType: How a credential is injected into an outbound HTTP request.
+ *
+ * - `bearer_header` — Authorization: Bearer <secret>
+ * - `custom_header` — Arbitrary header (injectionKey = header name)
+ * - `query_param` — URL query parameter (injectionKey = param name)
+ * - `basic_auth` — Authorization: Basic base64(<secret>)
+ */
+export const InjectionTypeSchema = z.enum([
+    "bearer_header",
+    "custom_header",
+    "query_param",
+    "basic_auth",
+]);
+/**
+ * CredentialMapping: Binds an encrypted secret to an injection strategy
+ * for a specific URL pattern and optional tool name.
+ *
+ * The CredentialInjector reads these mappings at request time to decide
+ * which secret to inject, how to inject it, and which URLs it applies to.
+ */
+export const CredentialMappingSchema = z
+    .object({
+    /** Unique identifier for this mapping */
+    id: z.string().min(1),
+    /** References secrets(name) — the encrypted secret to inject */
+    secretName: z.string().min(1),
+    /** How the credential is injected into the request */
+    injectionType: InjectionTypeSchema,
+    /** Header name or query param name (required for custom_header and query_param) */
+    injectionKey: z.string().optional(),
+    /** URL pattern this mapping applies to (glob or prefix match) */
+    urlPattern: z.string().min(1),
+    /** Optional tool name to restrict this mapping to a specific tool */
+    toolName: z.string().optional(),
+})
+    .refine((data) => {
+    if (data.injectionType === "custom_header" || data.injectionType === "query_param") {
+        return typeof data.injectionKey === "string" && data.injectionKey.length > 0;
+    }
+    return true;
+}, {
+    message: "injectionKey is required for custom_header and query_param injection types",
+    path: ["injectionKey"],
+});
+/**
+ * Parse unknown input into a CredentialMapping, returning Result<T, Error>.
+ *
+ * Uses Zod .safeParse() and wraps the result in the shared Result type.
+ * Refinement errors (missing injectionKey for custom_header/query_param)
+ * are included in the ZodError issues array.
+ */
+export function parseCredentialMapping(input) {
+    const result = CredentialMappingSchema.safeParse(input);
+    if (result.success) {
+        return ok(result.data);
+    }
+    return err(result.error);
+}

package/node_modules/@comis/core/dist/domain/credential-mapping.test.d.ts

@@ -0,0 +1 @@
+export {};