@m6d/cortex-cli 1.1.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "1.1.0",
+    "version": "1.3.0",
     "description": "Scaffold and operate Cortex servers",
     "license": "MIT",
     "type": "module",
@@ -16,7 +16,7 @@
     ],
     "scripts": {
         "check": "tsc --noEmit",
-        "prepack": "cp -R ../../internal/contracts src/contracts && rm src/contracts/package.json src/contracts/tsconfig.json",
+        "prepack": "rm -rf src/contracts && cp -R ../../internal/contracts/src src/contracts",
         "postpack": "rm -rf src/contracts",
         "test": "bun test"
     },

package/src/contracts/client-tools/index.ts

@@ -0,0 +1,56 @@
+/**
+ * The embed ↔ widget handshake for client tools.
+ *
+ * A page embedded by the chat widget (a hosted checkout, signing page, …)
+ * reports its outcome with:
+ *
+ *     window.parent.postMessage(
+ *         { type: "cortex:client-tool", status: "completed", reference: "session_123" },
+ *         "*",
+ *     );
+ *
+ * The widget accepts the message only when the event's origin matches the
+ * tool's configured `embedOrigin`. The payload is the page's claim, relayed to
+ * the agent as-is: cortex does not verify it, and anything that must actually
+ * be true lives in the integrating backend's own records.
+ *
+ * Like the wire seam, 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 CLIENT_TOOL_MESSAGE_TYPE = "cortex:client-tool";
+
+export const CLIENT_TOOL_STATUSES = ["completed", "cancelled", "failed"] as const;
+
+export type ClientToolStatus = (typeof CLIENT_TOOL_STATUSES)[number];
+
+export type ClientToolHandshake = {
+    type: typeof CLIENT_TOOL_MESSAGE_TYPE;
+    status: ClientToolStatus;
+    /** Opaque id for the integrating backend's own bookkeeping (session id, envelope id, …). */
+    reference?: string;
+    /** Optional payload passed through to the agent as part of the tool result. */
+    result?: unknown;
+};
+
+/**
+ * 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 parseClientToolHandshake(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"] !== CLIENT_TOOL_MESSAGE_TYPE) return null;
+    const status = CLIENT_TOOL_STATUSES.find((known) => known === message["status"]);
+    if (!status) return null;
+    const reference = message["reference"];
+    return {
+        type: CLIENT_TOOL_MESSAGE_TYPE,
+        status,
+        ...(typeof reference === "string" ? { reference } : {}),
+        ...(message["result"] !== undefined ? { result: message["result"] } : {}),
+    } satisfies ClientToolHandshake;
+}

package/src/contracts/graph/index.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 "./schema";
+export { GRAPH_SCHEMA, GRAPH_SCHEMA_VERSION } from "./schema";
+
+export type {
+    EndpointScalarType,
+    EndpointProperty,
+    ResponseKind,
+    AutoGenerated,
+    ConceptDef,
+    EndpointDef,
+    EndpointInput,
+    ServiceDef,
+    RuleDef,
+    DomainDef,
+} from "./types";
+
+export { defineConcept, defineRule, defineService, defineDomain, defineEndpoint } from "./helpers";
+
+export type { Neo4jConfig, Neo4jClient } from "./clients/neo4j";
+export { createNeo4jClient } from "./clients/neo4j";
+
+export type { EmbedFn, EmbeddingProviderConfig } from "./clients/embed";
+export { createEmbedder } from "./clients/embed";

package/src/contracts/{runtime.ts → runtime/index.ts}

@@ -89,6 +89,18 @@ export const knowledgeChunkSchema = z.object({
     }),
 });
 
+/**
+ * Runtime contract §5.4: present on signatures of `embedded` tools — flows
+ * the end user completes in an embedded surface inside the chat widget. The
+ * tool's endpoint fields act as the *initiate* call (returns the embed URL);
+ * the result the page reports back is relayed as-is — verifying it is the
+ * integrating backend's job.
+ */
+export const toolEmbedSchema = z.object({
+    surface: z.enum(["inline", "modal"]),
+    embedOrigin: z.url(),
+});
+
 export const toolSignatureSchema = z.object({
     toolId: z.uuid(),
     name: z.string().regex(TOOL_NAME_PATTERN),
@@ -98,6 +110,11 @@ export const toolSignatureSchema = z.object({
     signature: z.string(),
     score: z.number().nullable(),
     pinned: z.boolean(),
+    embed: toolEmbedSchema.optional(),
+    /** Client tools only: the published input JSON Schema, verbatim.
+     * Client-executed declarations need a real schema — the rendered
+     * `signature` text alone is not enough for function calling. */
+    inputSchema: z.record(z.string(), z.unknown()).optional(),
 });
 
 export const serviceCardSchema = z.object({
@@ -236,6 +253,7 @@ export const runtimeErrorSchema = z.object({
     }),
 });
 
+export type ToolEmbed = z.infer<typeof toolEmbedSchema>;
 export type RuntimeAgentConfig = z.infer<typeof runtimeAgentConfigSchema>;
 export type ResolveRequest = z.input<typeof resolveRequestSchema>;
 export type ResolveResponse = z.infer<typeof resolveResponseSchema>;

package/src/contracts/{wire.ts → wire/index.ts}

@@ -70,12 +70,24 @@ export type TokenUsage = {
     total: number;
 };
 
+/**
+ * How to launch one client tool: stamped by the server, per tool name, on
+ * the metadata of an assistant message that may carry its pending call. Kept in
+ * the message so the binding survives server restarts while a run is parked.
+ */
+export type ClientToolBinding = {
+    toolId: string;
+    surface: "inline" | "modal";
+    embedOrigin: string;
+};
+
 export type MessageMetadata = {
     modelId?: string;
     providerMetadata?: unknown;
     isAborted?: boolean;
     tokenUsage?: TokenUsage;
     attachments?: AttachmentSummary[];
+    clientTools?: Record<string, ClientToolBinding>;
 };
 
 /**
@@ -93,6 +105,38 @@ export type CortexMessage<TPart = unknown> = {
     metadata?: MessageMetadata;
 };
 
+/**
+ * Key under the AG-UI request's `forwardedProps` carrying the answers to
+ * parked client tool calls on a continuation request. The server owns the
+ * transcript (a continuation sends `messages: []`), so the answered assistant
+ * message itself never crosses the wire — the SDK's park-boundary snapshot
+ * does not preserve its id, and round-tripping it duplicated the stored
+ * message.
+ */
+export const CLIENT_TOOL_ANSWERS_KEY = "clientToolAnswers";
+
+/** One answered client tool call, applied to the stored transcript server-side. */
+export type ClientToolAnswer = {
+    toolCallId: string;
+    output: unknown;
+    state: "complete" | "error";
+};
+
+/**
+ * Response of `POST /chat/:chatId/tools/:toolCallId/initiate`. `embed:
+ * false` means the pending call is not a CC client tool — the widget
+ * falls back to its default rendering for the call. The payload is for the
+ * widget only; it never reaches the LLM.
+ */
+export type ClientToolInitiateResult =
+    | { embed: false }
+    | {
+          embed: true;
+          embedUrl: string;
+          surface: "inline" | "modal";
+          embedOrigin: string;
+      };
+
 export type ThreadCreatedEvent = {
     type: "thread:created";
     payload: { thread: ThreadSummary };

package/tsconfig.json

@@ -22,7 +22,7 @@
             // vendors it into src/contracts, where the first candidate finds it in
             // the published tarball. Inside the repo that copy doesn't exist and
             // resolution falls through to the workspace source.
-            "@cortex/contracts/*": ["./src/contracts/*", "../../internal/contracts/*"],
+            "@cortex/contracts/*": ["./src/contracts/*", "../../internal/contracts/src/*"],
             // Internal-only, and the reason this file ships in package.json `files`:
             // the CLI runs as raw TypeScript from inside node_modules, so Bun has to
             // read this config to resolve `@/`.

package/src/contracts/README.md

@@ -1,23 +0,0 @@
-# @cortex/contracts
-
-The shapes both sides of a cortex boundary must agree on. Private on purpose —
-it never publishes; each publishable package carries its own copy:
-
-- `@m6d/cortex-server` and `@m6d/cortex-cli` publish raw source, so their
-  `prepack` vendors a copy of this directory into the tarball (`contracts/` and
-  `src/contracts/` respectively), resolved there by their shipped tsconfig paths.
-- `@m6d/cortex-angular` and `@m6d/cortex-react` compile the parts they import
-  into their build artifacts.
-
-Three boundaries, one subpath each:
-
-| import                      | boundary                                                      |
-| --------------------------- | ------------------------------------------------------------- |
-| `@cortex/contracts/wire`    | chat client ↔ server (HTTP/WebSocket types)                   |
-| `@cortex/contracts/runtime` | cortex-cc console ↔ server runtime API (zod schemas)          |
-| `@cortex/contracts/graph`   | graph authoring (cli) ↔ server (vocabulary, helpers, clients) |
-
-Everything is consumed as TypeScript source — no build, no dist. Nothing here
-has a runtime dependency beyond zod (for `/runtime`), and nothing here may grow
-one: these files are compiled into an Angular library, a React library, a CLI
-and a Bun server alike.

package/src/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";