@m6d/cortex-server 2.1.0 → 2.3.0

package/contracts/graph.ts

@@ -1,36 +0,0 @@
-/**
- * The graph contract — the knowledge-graph vocabulary, authoring types and
- * clients that `@m6d/cortex-cli` writes with and `@m6d/cortex-server` reads
- * with. `@m6d/cortex-server` re-exports all of it, so a project authoring
- * domains still has exactly one import path.
- */
-
-export type { GraphSchema } from "./graph/schema";
-export { GRAPH_SCHEMA, GRAPH_SCHEMA_VERSION } from "./graph/schema";
-
-export type {
-    EndpointScalarType,
-    EndpointProperty,
-    ResponseKind,
-    AutoGenerated,
-    ConceptDef,
-    EndpointDef,
-    EndpointInput,
-    ServiceDef,
-    RuleDef,
-    DomainDef,
-} from "./graph/types";
-
-export {
-    defineConcept,
-    defineRule,
-    defineService,
-    defineDomain,
-    defineEndpoint,
-} from "./graph/helpers";
-
-export type { Neo4jConfig, Neo4jClient } from "./graph/neo4j";
-export { createNeo4jClient } from "./graph/neo4j";
-
-export type { EmbedFn, EmbeddingProviderConfig } from "./graph/embed";
-export { createEmbedder } from "./graph/embed";

package/contracts/interactive.ts

@@ -1,53 +0,0 @@
-/**
- * The embed ↔ widget handshake for interactive tools.
- *
- * A page embedded by the chat widget (a hosted checkout, signing page, …)
- * reports its outcome with:
- *
- *     window.parent.postMessage(
- *         { type: "cortex:interactive", status: "completed", reference: "session_123" },
- *         "*",
- *     );
- *
- * The widget accepts the message only when the event's origin matches the
- * tool's configured `embedOrigin`, and treats the payload as untrusted — for
- * tools with a verify endpoint the server re-checks the reference before the
- * agent sees a result.
- *
- * Like `wire.ts`, this file is compiled into the client SDKs and must stay
- * free of runtime dependencies. It is also the spec any future SDK (Flutter)
- * reimplements against.
- */
-
-export const INTERACTIVE_MESSAGE_TYPE = "cortex:interactive";
-
-export const INTERACTIVE_STATUSES = ["completed", "cancelled", "failed"] as const;
-
-export type InteractiveStatus = (typeof INTERACTIVE_STATUSES)[number];
-
-export type InteractiveHandshake = {
-    type: typeof INTERACTIVE_MESSAGE_TYPE;
-    status: InteractiveStatus;
-    /** Opaque id the tool's verify endpoint resolves (session id, envelope id, …). */
-    reference?: string;
-};
-
-/**
- * Parse a `message` event into a handshake, or null when the origin doesn't
- * match the tool's `embedOrigin` or the payload isn't a well-formed handshake.
- * Call from the widget's `message` listener with `event.data` / `event.origin`.
- */
-export function parseInteractiveHandshake(data: unknown, origin: string, embedOrigin: string) {
-    if (origin !== embedOrigin) return null;
-    if (typeof data !== "object" || data === null) return null;
-    const message = data as Record<string, unknown>;
-    if (message["type"] !== INTERACTIVE_MESSAGE_TYPE) return null;
-    const status = INTERACTIVE_STATUSES.find((known) => known === message["status"]);
-    if (!status) return null;
-    const reference = message["reference"];
-    return {
-        type: INTERACTIVE_MESSAGE_TYPE,
-        status,
-        ...(typeof reference === "string" ? { reference } : {}),
-    } satisfies InteractiveHandshake;
-}

package/dist/contracts/interactive.d.ts

@@ -1,39 +0,0 @@
-/**
- * The embed ↔ widget handshake for interactive tools.
- *
- * A page embedded by the chat widget (a hosted checkout, signing page, …)
- * reports its outcome with:
- *
- *     window.parent.postMessage(
- *         { type: "cortex:interactive", status: "completed", reference: "session_123" },
- *         "*",
- *     );
- *
- * The widget accepts the message only when the event's origin matches the
- * tool's configured `embedOrigin`, and treats the payload as untrusted — for
- * tools with a verify endpoint the server re-checks the reference before the
- * agent sees a result.
- *
- * Like `wire.ts`, this file is compiled into the client SDKs and must stay
- * free of runtime dependencies. It is also the spec any future SDK (Flutter)
- * reimplements against.
- */
-export declare const INTERACTIVE_MESSAGE_TYPE = "cortex:interactive";
-export declare const INTERACTIVE_STATUSES: readonly ["completed", "cancelled", "failed"];
-export type InteractiveStatus = (typeof INTERACTIVE_STATUSES)[number];
-export type InteractiveHandshake = {
-    type: typeof INTERACTIVE_MESSAGE_TYPE;
-    status: InteractiveStatus;
-    /** Opaque id the tool's verify endpoint resolves (session id, envelope id, …). */
-    reference?: string;
-};
-/**
- * Parse a `message` event into a handshake, or null when the origin doesn't
- * match the tool's `embedOrigin` or the payload isn't a well-formed handshake.
- * Call from the widget's `message` listener with `event.data` / `event.origin`.
- */
-export declare function parseInteractiveHandshake(data: unknown, origin: string, embedOrigin: string): {
-    reference?: string | undefined;
-    type: "cortex:interactive";
-    status: "failed" | "completed" | "cancelled";
-} | null;

package/dist/src/lib/ai/interactive.d.ts

@@ -1,62 +0,0 @@
-import type { ResolvedCortexAgentConfig } from "../config";
-import type { ChatMessage, Thread } from "../types";
-import { ControlCenterClient } from "../cc/client";
-import type { CcRuntime } from "../cc/registry";
-/**
- * The wire-shape bindings stamped on the turn's final assistant message, so a
- * parked interactive call can be initiated and verified after any restart.
- * Only names that actually won declaration merging are stamped — a call to a
- * colliding consumer-owned tool must never be treated as interactive. Undefined
- * when nothing qualifies, keeping metadata lean.
- */
-export declare function interactiveToolBindings(cc: CcRuntime | undefined, takenNames: ReadonlySet<string>): {
-    [k: string]: {
-        surface: "inline" | "modal";
-        embedOrigin: string;
-        hasVerify: boolean;
-        resultDelivery: "agent" | "endpoint" | "both";
-        toolId: string;
-    };
-} | undefined;
-/** Null when the agent has no Control Center — every caller treats that as "skip". */
-export declare function createCcClient(config: ResolvedCortexAgentConfig): ControlCenterClient | null;
-/**
- * `POST /chat/:chatId/tools/:toolCallId/initiate` — runs the interactive
- * tool's initiate call (the tool's own endpoint) and hands the widget its
- * embed payload. The model never sees this payload. The idempotency key is
- * pinned to the tool call, so a reload mid-flow reuses the created session
- * instead of opening a second one.
- */
-export declare function initiateInteractiveTool(options: {
-    config: ResolvedCortexAgentConfig;
-    thread: Thread;
-    userId: string;
-    token: string;
-    toolCallId: string;
-}): Promise<{
-    interactive: false;
-    embedUrl?: undefined;
-    surface?: undefined;
-    embedOrigin?: undefined;
-} | {
-    interactive: true;
-    embedUrl: string;
-    surface: "inline" | "modal";
-    embedOrigin: string;
-}>;
-/**
- * The trust boundary for interactive results: whatever the client submitted
- * for a bound tool call is replaced wholesale — cancelled/failed pass through
- * normalized, completed is re-established by the tool's verify call when it
- * has one, and result delivery masking is applied before the model reads it.
- * Runs before the answering turn is persisted, so both the stored transcript
- * and the model context carry only settled results.
- */
-export declare function settleInteractiveToolResults(options: {
-    messages: ChatMessage[];
-    thread: Thread;
-    userId: string;
-    token: string;
-    config: ResolvedCortexAgentConfig;
-    ccClient: ControlCenterClient | null;
-}): Promise<void>;

package/src/lib/ai/interactive.ts

@@ -1,364 +0,0 @@
-import { HTTPException } from "hono/http-exception";
-import type { InteractiveInitiateResult, MessageMetadata } from "@cortex/contracts/wire";
-import { INTERACTIVE_STATUSES } from "@cortex/contracts/interactive";
-import type { ResolvedCortexAgentConfig } from "@/config";
-import type { ChatMessage, Thread } from "@/types";
-import { ControlCenterClient } from "@/cc/client";
-import type { CcRuntime } from "@/cc/registry";
-import { recordRecentCcTool } from "@/cc/registry";
-
-type InteractiveBinding = NonNullable<MessageMetadata["interactiveTools"]>[string];
-
-/**
- * The wire-shape bindings stamped on the turn's final assistant message, so a
- * parked interactive call can be initiated and verified after any restart.
- * Only names that actually won declaration merging are stamped — a call to a
- * colliding consumer-owned tool must never be treated as interactive. Undefined
- * when nothing qualifies, keeping metadata lean.
- */
-export function interactiveToolBindings(
-    cc: CcRuntime | undefined,
-    takenNames: ReadonlySet<string>,
-) {
-    if (!cc) return undefined;
-    const entries = [...cc.interactiveTools]
-        .filter(([name]) => !takenNames.has(name))
-        .map(
-            ([name, tool]) =>
-                [
-                    name,
-                    { toolId: tool.toolId, ...tool.interaction } satisfies InteractiveBinding,
-                ] as const,
-        );
-    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
-}
-
-/** Null when the agent has no Control Center — every caller treats that as "skip". */
-export function createCcClient(config: ResolvedCortexAgentConfig) {
-    return config.controlCenter ? new ControlCenterClient(config.controlCenter) : null;
-}
-
-/** How long initiate waits out the turn-commit race before giving up. */
-const PENDING_CALL_RETRIES = 6;
-const PENDING_CALL_RETRY_MS = 700;
-
-/**
- * The widget initiates the moment its stream goes idle, which can beat the
- * turn's commit to the database — so a missing call is retried briefly before
- * it becomes a 404. An *answered* call 404s immediately: it was settled
- * elsewhere (another tab) and the widget should fall back to its pill.
- */
-async function findPendingInteractiveCall(
-    config: ResolvedCortexAgentConfig,
-    userId: string,
-    threadId: string,
-    toolCallId: string,
-) {
-    for (let attempt = 0; ; attempt += 1) {
-        const stored = await config.db.messages.list(userId, threadId);
-        const messages = stored.map((row) => row.content);
-        const answered = messages.some((candidate) =>
-            candidate.parts.some(
-                (part) => part.type === "tool-result" && part.toolCallId === toolCallId,
-            ),
-        );
-        if (answered) return null;
-
-        for (const message of messages) {
-            const call = message.parts.find(
-                (part) => part.type === "tool-call" && part.id === toolCallId,
-            );
-            if (call?.type === "tool-call") return { message, call };
-        }
-
-        if (attempt >= PENDING_CALL_RETRIES) return null;
-        await new Promise((resolve) => setTimeout(resolve, PENDING_CALL_RETRY_MS));
-    }
-}
-
-/**
- * `POST /chat/:chatId/tools/:toolCallId/initiate` — runs the interactive
- * tool's initiate call (the tool's own endpoint) and hands the widget its
- * embed payload. The model never sees this payload. The idempotency key is
- * pinned to the tool call, so a reload mid-flow reuses the created session
- * instead of opening a second one.
- */
-export async function initiateInteractiveTool(options: {
-    config: ResolvedCortexAgentConfig;
-    thread: Thread;
-    userId: string;
-    token: string;
-    toolCallId: string;
-}) {
-    const { config, thread, userId, token, toolCallId } = options;
-    const pending = await findPendingInteractiveCall(config, userId, thread.id, toolCallId);
-    if (!pending) {
-        throw new HTTPException(404, { message: "No pending tool call with this id" });
-    }
-    const { message, call } = pending;
-
-    const binding = message.metadata?.interactiveTools?.[call.name];
-    const ccClient = createCcClient(config);
-    if (!binding || !ccClient) {
-        return { interactive: false } satisfies InteractiveInitiateResult;
-    }
-
-    const result = await ccClient.execute(
-        config.agentId,
-        binding.toolId,
-        {
-            input: asRecord(call.input) ?? asRecord(parseJson(call.arguments)) ?? {},
-            context: { threadId: thread.id, userId },
-        },
-        {
-            readOnly: false,
-            endUserToken: token,
-            threadId: thread.id,
-            turnKey: toolCallId,
-            stepIndex: 0,
-            callIndex: 0,
-            idempotencyKey: `${thread.id}:${toolCallId}:initiate`,
-        },
-    );
-    if (!result) {
-        throw new HTTPException(502, { message: "The tool is temporarily unavailable" });
-    }
-    if ("error" in result) {
-        throw new HTTPException(502, { message: `initiate failed: ${result.error.kind}` });
-    }
-
-    const embedUrl = asRecord(result.output)?.embedUrl;
-    if (typeof embedUrl !== "string" || !isOnOrigin(embedUrl, binding.embedOrigin)) {
-        throw new HTTPException(502, {
-            message: "initiate did not return an embedUrl on the configured origin",
-        });
-    }
-
-    // Anchor the trusted reference to this call: a verified completion may
-    // only settle against the session this initiate created, never against
-    // whichever reference the browser chooses to report.
-    if (binding.hasVerify) {
-        const reference = asRecord(result.output)?.reference;
-        if (typeof reference !== "string" || !reference) {
-            throw new HTTPException(502, {
-                message: "initiate did not return the reference its verify endpoint needs",
-            });
-        }
-        await config.db.messages.mergeInteractiveReference(
-            thread.id,
-            message.id,
-            toolCallId,
-            reference,
-        );
-    }
-
-    return {
-        interactive: true,
-        embedUrl,
-        surface: binding.surface,
-        embedOrigin: binding.embedOrigin,
-    } satisfies InteractiveInitiateResult;
-}
-
-/**
- * The trust boundary for interactive results: whatever the client submitted
- * for a bound tool call is replaced wholesale — cancelled/failed pass through
- * normalized, completed is re-established by the tool's verify call when it
- * has one, and result delivery masking is applied before the model reads it.
- * Runs before the answering turn is persisted, so both the stored transcript
- * and the model context carry only settled results.
- */
-export async function settleInteractiveToolResults(options: {
-    messages: ChatMessage[];
-    thread: Thread;
-    userId: string;
-    token: string;
-    config: ResolvedCortexAgentConfig;
-    ccClient: ControlCenterClient | null;
-}) {
-    // Deliberately no early-out on a missing CC client: normalization must run
-    // for every bound result regardless — only the verify call needs CC, and
-    // without it a claimed completion fails rather than passing through.
-    const { messages, thread, userId, token, config, ccClient } = options;
-    const answering = messages.filter(
-        (message) =>
-            message.role === "assistant" &&
-            message.parts.some((part) => part.type === "tool-result"),
-    );
-    if (answering.length === 0) return;
-
-    const stored = await config.db.messages.list(userId, thread.id);
-    const storedMessages = stored.map((row) => row.content);
-    const pendingCalls = collectPendingCalls(storedMessages);
-    if (pendingCalls.size === 0) return;
-
-    const context = {
-        ccClient,
-        agentId: config.agentId,
-        threadId: thread.id,
-        userId,
-        token,
-        references: collectReferences(storedMessages),
-    };
-    for (const message of answering) {
-        await settleMessage(message, pendingCalls, context);
-    }
-}
-
-async function settleMessage(
-    message: ChatMessage,
-    pendingCalls: Map<string, PendingInteractiveCall>,
-    context: SettleContext,
-) {
-    for (const part of message.parts) {
-        if (part.type !== "tool-result") continue;
-        const pending = pendingCalls.get(part.toolCallId);
-        if (!pending) continue;
-
-        recordRecentCcTool(context.threadId, pending.name);
-        const settled = await settleOne(pending.binding, part.content, part.toolCallId, context);
-        part.content = JSON.stringify(settled);
-    }
-}
-
-type PendingInteractiveCall = { name: string; binding: InteractiveBinding };
-
-/**
- * The authoritative view of what may settle: stored, unanswered tool calls
- * whose own message carries a binding for their name, keyed by call id. The
- * incoming message's tool-call parts are client-authored and never consulted —
- * a fabricated call/result pair matches nothing here.
- */
-function collectPendingCalls(messages: ChatMessage[]) {
-    const answered = answeredCallIds(messages);
-    const pending = new Map<string, PendingInteractiveCall>();
-    for (const message of messages) {
-        const bindings = message.metadata?.interactiveTools;
-        if (!bindings) continue;
-        for (const part of message.parts) {
-            if (part.type !== "tool-call" || answered.has(part.id)) continue;
-            const binding = bindings[part.name];
-            if (binding) pending.set(part.id, { name: part.name, binding });
-        }
-    }
-    return pending;
-}
-
-function answeredCallIds(messages: ChatMessage[]) {
-    const answered = new Set<string>();
-    for (const message of messages) {
-        for (const part of message.parts) {
-            if (part.type === "tool-result") answered.add(part.toolCallId);
-        }
-    }
-    return answered;
-}
-
-/** The references initiate anchored, keyed by tool call id. */
-function collectReferences(messages: ChatMessage[]) {
-    const references = new Map<string, string>();
-    for (const message of messages) {
-        for (const [toolCallId, reference] of Object.entries(
-            message.metadata?.interactiveReferences ?? {},
-        )) {
-            references.set(toolCallId, reference);
-        }
-    }
-    return references;
-}
-
-type SettleContext = {
-    ccClient: ControlCenterClient | null;
-    agentId: string;
-    threadId: string;
-    userId: string;
-    token: string;
-    references: Map<string, string>;
-};
-
-async function settleOne(
-    binding: InteractiveBinding,
-    content: string | unknown[],
-    toolCallId: string,
-    context: SettleContext,
-) {
-    const reported = parseReported(content);
-    if (reported.status === "cancelled") return { status: "cancelled" };
-    if (reported.status !== "completed") return { status: "failed" };
-
-    if (!binding.hasVerify) {
-        // A completion the server cannot re-establish is just the browser's
-        // word. Current Control Centers always configure verification, so this
-        // only fires against a foreign runtime — refuse rather than trust.
-        return { status: "failed", detail: "verification required" };
-    }
-    const anchored = context.references.get(toolCallId);
-    if (!anchored || reported.reference !== anchored) {
-        return { status: "failed", detail: "completion does not match the initiated session" };
-    }
-    if (!context.ccClient) {
-        return { status: "failed", detail: "verification unavailable" };
-    }
-
-    const result = await context.ccClient.execute(
-        context.agentId,
-        binding.toolId,
-        {
-            input: { reference: anchored },
-            phase: "verify",
-            context: { threadId: context.threadId, userId: context.userId },
-        },
-        {
-            readOnly: true,
-            endUserToken: context.token,
-            threadId: context.threadId,
-            turnKey: "verify",
-            stepIndex: 0,
-            callIndex: 0,
-        },
-    );
-    if (!result) return { status: "failed", detail: "verification unavailable" };
-    if ("error" in result) return { status: "failed", detail: result.error.kind };
-    return deliver(binding, reported.reference, result.output);
-}
-
-function deliver(binding: InteractiveBinding, reference: string | undefined, output: unknown) {
-    return binding.resultDelivery === "endpoint"
-        ? { status: "completed", reference }
-        : { status: "completed", reference, result: output };
-}
-
-function parseReported(content: string | unknown[]) {
-    const record = asRecord(typeof content === "string" ? parseJson(content) : content);
-    const status = INTERACTIVE_STATUSES.find((known) => known === record?.status);
-    return {
-        status,
-        reference: typeof record?.reference === "string" ? record.reference : undefined,
-    };
-}
-
-function parseJson(value: string | undefined) {
-    if (value === undefined) return undefined;
-    try {
-        return JSON.parse(value) as unknown;
-    } catch {
-        return undefined;
-    }
-}
-
-function asRecord(value: unknown) {
-    return typeof value === "object" && value !== null && !Array.isArray(value)
-        ? (value as Record<string, unknown>)
-        : undefined;
-}
-
-function isOnOrigin(url: string, origin: string) {
-    try {
-        const parsed = new URL(url);
-        // http(s) only: javascript:/data: URLs normalize to origin "null",
-        // which a bare equality check could otherwise be tricked into passing.
-        return ["http:", "https:"].includes(parsed.protocol) && parsed.origin === origin;
-    } catch {
-        return false;
-    }
-}