@m6d/cortex-cli 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "Scaffold and operate Cortex servers",
     "license": "MIT",
     "type": "module",

package/src/contracts/interactive.ts

@@ -0,0 +1,53 @@
+/**
+ * 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/src/contracts/runtime.ts

@@ -89,6 +89,19 @@ export const knowledgeChunkSchema = z.object({
     }),
 });
 
+/**
+ * Runtime contract §5.4: present on signatures of `interactive` 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);
+ * `hasVerify` marks a second, server-trusted call that settles the result.
+ */
+export const toolInteractionSchema = z.object({
+    surface: z.enum(["inline", "modal"]),
+    embedOrigin: z.url(),
+    hasVerify: z.boolean(),
+    resultDelivery: z.enum(["agent", "endpoint", "both"]),
+});
+
 export const toolSignatureSchema = z.object({
     toolId: z.uuid(),
     name: z.string().regex(TOOL_NAME_PATTERN),
@@ -98,6 +111,11 @@ export const toolSignatureSchema = z.object({
     signature: z.string(),
     score: z.number().nullable(),
     pinned: z.boolean(),
+    interaction: toolInteractionSchema.optional(),
+    /** Interactive 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({
@@ -194,6 +212,9 @@ export const searchKnowledgeResponseSchema = z.object({
 
 export const executeRequestSchema = z.object({
     input: z.record(z.string(), z.unknown()).default({}),
+    // Interactive tools only: absent | "initiate" targets the tool's endpoint
+    // fields, "verify" targets its verify endpoint config.
+    phase: z.enum(["initiate", "verify"]).optional(),
     context: z
         .object({
             threadId: z.string().max(128).optional(),
@@ -236,6 +257,7 @@ export const runtimeErrorSchema = z.object({
     }),
 });
 
+export type ToolInteraction = z.infer<typeof toolInteractionSchema>;
 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

@@ -70,12 +70,29 @@ export type TokenUsage = {
     total: number;
 };
 
+/**
+ * How to launch one interactive 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 InteractiveToolBinding = {
+    toolId: string;
+    surface: "inline" | "modal";
+    embedOrigin: string;
+    hasVerify: boolean;
+    resultDelivery: "agent" | "endpoint" | "both";
+};
+
 export type MessageMetadata = {
     modelId?: string;
     providerMetadata?: unknown;
     isAborted?: boolean;
     tokenUsage?: TokenUsage;
     attachments?: AttachmentSummary[];
+    interactiveTools?: Record<string, InteractiveToolBinding>;
+    /** Per tool call: the trusted reference its initiate call returned. A
+     * verified completion must match it — the browser's word is never enough. */
+    interactiveReferences?: Record<string, string>;
 };
 
 /**
@@ -93,6 +110,21 @@ export type CortexMessage<TPart = unknown> = {
     metadata?: MessageMetadata;
 };
 
+/**
+ * Response of `POST /chat/:chatId/tools/:toolCallId/initiate`. `interactive:
+ * false` means the pending call is not an interactive CC 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 InteractiveInitiateResult =
+    | { interactive: false }
+    | {
+          interactive: true;
+          embedUrl: string;
+          surface: "inline" | "modal";
+          embedOrigin: string;
+      };
+
 export type ThreadCreatedEvent = {
     type: "thread:created";
     payload: { thread: ThreadSummary };