@m6d/cortex-cli 0.12.1 → 0.13.0

package/src/contracts/runtime/grammar.ts

@@ -1,169 +0,0 @@
-import { z } from "zod";
-import {
-    LOCALES,
-    MEDIA_FORMS,
-    TOOL_SURFACES,
-    type Greeting,
-    type Suggestions,
-} from "../wire/index";
-
-/*
- * The grammar both sides of the runtime API share: identifier patterns, the
- * closed sets, and the small schemas every request and response is built from.
- */
-
-/** The agent slug path param, validated on both sides of the wire. */
-export const AGENT_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
-export const agentSlugSchema = z.string().regex(AGENT_SLUG_PATTERN);
-
-/**
- * An ASCII JavaScript identifier: what a tool name (a `tools.<name>()` sandbox
- * binding on the server) and a variable name must be, and what a rendered
- * signature prints bare rather than quoted.
- */
-export const IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
-
-/** Consumer-facing slugs: service keys, skill names, and trigger names share it. */
-export const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-export const slugSchema = z.string().regex(SLUG_PATTERN).max(64);
-
-export const localeSchema = z.enum(LOCALES);
-export const toolSurfaceSchema = z.enum(TOOL_SURFACES);
-export const mediaFormSchema = z.enum(MEDIA_FORMS);
-export const catalogVersionSchema = z.string().regex(/^[0-9a-f]{16}$/);
-export const sha256HexSchema = z.string().regex(/^[0-9a-f]{64}$/);
-
-/**
- * A variable the server fills per request: a session value, a request-context
- * value, or one the SDK computes. Declared once per server so the console
- * offers exactly what that server provides to the agents created on it, in
- * prompts and as tool input sources alike.
- */
-export const variableDeclarationSchema = z.object({
-    name: z.string().regex(IDENTIFIER_PATTERN).max(64),
-    description: z.string().max(500),
-    example: z.string().max(200),
-    /** Computed by the SDK per request (`utcTime`, `locale`); no session value can set it. */
-    computed: z.boolean(),
-});
-export type VariableDeclaration = z.infer<typeof variableDeclarationSchema>;
-
-/** Variable names a tool input or prompt reads. */
-export const boundVariablesSchema = z.array(variableDeclarationSchema.shape.name);
-
-/** A sandbox binding a piece of rich text mentions, so the turn can register it before the model reads the text. */
-export const mentionedToolSchema = z.object({
-    toolId: z.uuid(),
-    name: z.string().regex(IDENTIFIER_PATTERN),
-    readOnly: z.boolean(),
-    /** A tool that parks for approval is never a sandbox binding, mentioned or not. */
-    requiresApproval: z.boolean(),
-    variables: boundVariablesSchema,
-});
-
-/**
- * Variables the SDK itself fills for every agent, listed first in a server's
- * declaration so the console offers them like any consumer-declared one.
- */
-export const SDK_VARIABLES = [
-    {
-        name: "utcTime",
-        description: "Current time in UTC (ISO 8601)",
-        example: "2026-09-12T08:30:00Z",
-        computed: true,
-    },
-    {
-        name: "locale",
-        description: "Resolved locale of the session",
-        example: "ar",
-        computed: true,
-    },
-    {
-        name: "timezone",
-        description: "The user's IANA time zone, as the widget reports it",
-        example: "Asia/Riyadh",
-        computed: true,
-    },
-] as const satisfies ReadonlyArray<VariableDeclaration>;
-
-/**
- * The widget's landing-page prompt chips, per locale: a short title the chip
- * shows and the prompt it sends when clicked. Every source of them
- * (the Control Center agent row, a server-code override, the capabilities
- * handshake) stores this exact shape, so the widget never sees a blank or
- * unbounded chip whichever source won. Pure validation, no transforms: a
- * value that passes is served verbatim, so each source trims before it
- * stores.
- */
-export const SUGGESTION_LIMITS = { perLocale: 6, titleLength: 120, promptLength: 2000 } as const;
-const trimmedText = (max: number) =>
-    z
-        .string()
-        .min(1)
-        .max(max)
-        .refine((text) => text === text.trim(), "text has surrounding whitespace");
-export const suggestionsSchema = z.record(
-    localeSchema,
-    z
-        .array(
-            z.object({
-                title: trimmedText(SUGGESTION_LIMITS.titleLength),
-                prompt: trimmedText(SUGGESTION_LIMITS.promptLength),
-            }),
-        )
-        .max(SUGGESTION_LIMITS.perLocale),
-) satisfies z.ZodType<Suggestions>;
-
-/** One string per locale, at most 500 characters each; author copy the widget shows as is. */
-export const localizedTextSchema = z.record(localeSchema, z.string().max(500));
-
-export const GREETING_MAX_LENGTH = 200;
-/**
- * The blank-chat landing's headline per locale. Empty means the widget's
- * built-in default for that locale; like suggestions, served verbatim.
- */
-export const greetingSchema = z.record(
-    localeSchema,
-    z
-        .string()
-        .max(GREETING_MAX_LENGTH)
-        .refine((text) => text === text.trim(), "greeting has surrounding whitespace"),
-) satisfies z.ZodType<Greeting>;
-
-/**
- * The Control Center's id for a resolved agent. Servers echo it on reports
- * about that agent so they attach to it even if the slug or alias they used
- * later moves.
- */
-export const agentRefSchema = z.uuid();
-
-/**
- * Response header carrying the resolved agent's ref on every agent-scoped
- * runtime answer, errors included, so a server can attribute a request even
- * when the body is an error envelope. Absent only when no agent resolved.
- */
-export const AGENT_REF_HEADER = "X-CC-Agent-Ref";
-
-/**
- * The playground operator's stand-in for a test thread's session: a
- * URI-encoded JSON object of declared variable values, sent by cc's
- * playground beside `X-Cortex-Playground` and honoured only when that header
- * verifies. The server stores it as the thread's session on creation, so the
- * customer's `loadSessionData` (which never sees cc-minted tokens) is not
- * needed for prompts and tool sources to have values.
- */
-export const PLAYGROUND_SESSION_HEADER = "X-Cortex-Playground-Session";
-
-/** Sent by cc's playground; a server verifies it against cc's JWKS before honouring it. */
-export const PLAYGROUND_HEADER = "X-Cortex-Playground";
-
-/** The end user's bearer, forwarded verbatim by the server to cc and by cc to the tool's backend. */
-export const END_USER_TOKEN_HEADER = "X-End-User-Token";
-
-/** Execute idempotency: a server-minted key the runtime replays within its window. */
-export const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
-export const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,200}$/;
-
-/** Correlation id echoed on every runtime response. */
-export const REQUEST_ID_HEADER = "X-Request-Id";
-export const REQUEST_ID_MAX_LENGTH = 128;

package/src/contracts/runtime/index.ts

@@ -1,15 +0,0 @@
-/*
- * The contract between the cortex-cc console and `@m6d/cortex-server`:
- * the grammar they share, the runtime API cc serves, triggers in both
- * directions, and the fleet sync the server pushes.
- */
-export * from "./grammar";
-export * from "./auth";
-export * from "./api";
-export * from "./triggers";
-export * from "./models";
-export * from "./datasets";
-export * from "./dataset-sql";
-export * from "./dataset-sql-guide";
-export * from "./sync";
-export * from "./signature";

package/src/contracts/runtime/models.ts

@@ -1,50 +0,0 @@
-import { z } from "zod";
-
-/**
- * One level's pick of what a run talks to: a model a Control Center
- * provider lists, the reasoning effort sent with it, both, or neither. An
- * unset part inherits from the level above (trigger, then agent, then
- * server, then the server's code config). An effort carries down only as
- * far as the level that picked the model, and is sent only when that
- * model's provider lists it.
- */
-export const modelChoiceSchema = z
-    .object({
-        provider: z.string().min(1).nullable(),
-        model: z.string().min(1).nullable(),
-        effort: z.string().min(1).nullable(),
-    })
-    .refine((choice) => (choice.provider === null) === (choice.model === null), {
-        error: "A provider and its model are picked together.",
-    });
-export type ModelChoice = z.infer<typeof modelChoiceSchema>;
-
-/** A pick that inherits everything. */
-export const INHERIT_MODEL = {
-    provider: null,
-    model: null,
-    effort: null,
-} satisfies ModelChoice;
-
-/**
- * An OpenAI-compatible endpoint as a server calls it: cc resolves the key
- * from the provider's secret, and `efforts` are the values it accepts as
- * `reasoning_effort`.
- */
-export const modelProviderEndpointSchema = z.object({
-    baseURL: z.url(),
-    apiKey: z.string().min(1),
-    efforts: z.array(z.string().min(1)),
-});
-
-/**
- * The model picks a server needs to run one agent: its server's and the
- * agent's own (each trigger carries its own on its declaration), plus every
- * provider any of them names.
- */
-export const runtimeModelsSchema = z.object({
-    providers: z.record(z.string(), modelProviderEndpointSchema),
-    server: modelChoiceSchema,
-    agent: modelChoiceSchema,
-});
-export type RuntimeModels = z.infer<typeof runtimeModelsSchema>;

package/src/contracts/runtime/signature.ts

@@ -1,255 +0,0 @@
-import { isRecord } from "../json";
-import { IDENTIFIER_PATTERN } from "./grammar";
-
-/*
- * The one rendering of a dynamic tool the model sees, whichever side
- * produced it: Control Center renders its registry tools at resolve time,
- * `@m6d/cortex-server` renders an MCP server's tools at turn time, and both
- * land in the same "Dynamic Tools" prompt section. A TypeScript-like
- * signature over the tool's JSON Schema: the input typed field by field with
- * its description as a trailing comment, the response as the names of the
- * fields it carries (what a script reads off the result), never their types.
- */
-
-/** Past this nesting an object prints as `object`: deeper detail costs more prompt than it earns. */
-const MAX_DEPTH = 3;
-
-function propertyName(name: string) {
-    return IDENTIFIER_PATTERN.test(name) ? name : JSON.stringify(name);
-}
-
-function compactLine(value: string) {
-    return value.replace(/\s+/g, " ").trim();
-}
-
-function fieldComment(value: unknown) {
-    if (typeof value !== "string") return "";
-    return Array.from(compactLine(value)).slice(0, 80).join("");
-}
-
-/** The `required` names of an object schema, or none when it declares none. */
-export function requiredProperties(schema: unknown) {
-    return isRecord(schema) && Array.isArray(schema.required)
-        ? schema.required.filter((name): name is string => typeof name === "string")
-        : [];
-}
-
-/** Property names in the schema's `x-order` first, then the rest as declared. */
-export function orderedPropertyNames(schema: Record<string, unknown>) {
-    const properties = isRecord(schema.properties) ? schema.properties : {};
-    const order = Array.isArray(schema["x-order"])
-        ? schema["x-order"].filter(
-              (name): name is string => typeof name === "string" && name in properties,
-          )
-        : [];
-    return [...order, ...Object.keys(properties).filter((name) => !order.includes(name))];
-}
-
-const SCALAR_TYPES = new Set(["boolean", "number", "string"]);
-
-/**
- * Follows a local `$ref` (`#`, `#/$defs/x`, or `#/definitions/x`) to its
- * definition in the root document, keeping the keywords beside the ref (a
- * description, say), so a shared shape a converter hoisted (a tool's schema
- * rows) renders as its fields rather than `unknown`. A described ref comes out
- * of zod as a one-entry `allOf`, which reads the same. A recursive shape ends
- * where `MAX_DEPTH` ends it.
- */
-function resolver(root: unknown) {
-    function definition(pointer: string) {
-        if (pointer === "#") return root;
-        const parts = pointer.split("/");
-        const [, section, name] = parts;
-        const definitions =
-            isRecord(root) && (section === "$defs" || section === "definitions")
-                ? root[section]
-                : undefined;
-        return parts.length === 3 && isRecord(definitions) && name !== undefined
-            ? definitions[name]
-            : undefined;
-    }
-    return function resolve(schema: unknown): unknown {
-        if (!isRecord(schema)) return schema;
-        const { $ref, allOf, ...rest } = schema;
-        if (typeof $ref === "string") {
-            const target = definition($ref);
-            return isRecord(target) ? { ...target, ...rest } : target;
-        }
-        if (Array.isArray(allOf) && allOf.length === 1) {
-            const target = resolve(allOf[0]);
-            return isRecord(target) ? { ...target, ...rest } : target;
-        }
-        return schema;
-    };
-}
-
-type Resolve = ReturnType<typeof resolver>;
-
-function literalUnion(values: unknown[]) {
-    return values
-        .filter((value) => value === null || SCALAR_TYPES.has(typeof value))
-        .map((value) => JSON.stringify(value))
-        .join(" | ");
-}
-
-/** An object's fields one per line, each typed, marked optional, and commented from its description. */
-function inputObject(
-    schema: Record<string, unknown>,
-    resolve: Resolve,
-    depth: number,
-    indent: number,
-) {
-    if (depth >= MAX_DEPTH) return "object";
-    const properties = isRecord(schema.properties) ? schema.properties : {};
-    const required = new Set(requiredProperties(schema));
-    const fields = orderedPropertyNames(schema).map((name) => {
-        const child = resolve(properties[name]);
-        const comment = isRecord(child) ? fieldComment(child.description) : "";
-        return `${" ".repeat(indent + 2)}${propertyName(name)}${required.has(name) ? "" : "?"}: ${inputType(child, resolve, depth + 1, indent + 2)},${comment ? ` // ${comment}` : ""}`;
-    });
-    return fields.length > 0 ? `{\n${fields.join("\n")}\n${" ".repeat(indent)}}` : "{}";
-}
-
-function inputType(schema: unknown, resolve: Resolve, depth = 0, indent = 0): string {
-    schema = resolve(schema);
-    if (!isRecord(schema)) return "unknown";
-    if ("const" in schema && SCALAR_TYPES.has(typeof schema.const)) {
-        return JSON.stringify(schema.const);
-    }
-    if (Array.isArray(schema.enum) && schema.enum.length > 0) return literalUnion(schema.enum);
-    const variants = variantsOf(schema);
-    if (variants) {
-        const rendered = variants.map((variant) => inputType(variant, resolve, depth, indent));
-        return [...new Set(rendered)].join(" | ");
-    }
-    const type = primaryType(schema.type);
-    const nullable = allowsNull(schema.type) ? " | null" : "";
-    if (type === "null") return "null";
-    if (type === "array") {
-        const item = inputType(schema.items, resolve, depth + 1, indent);
-        // A union item type binds looser than `[]`, so it is parenthesized.
-        return `${item.includes(" | ") ? `(${item})` : item}[]${nullable}`;
-    }
-    if (type === "object" || isRecord(schema.properties)) {
-        return inputObject(schema, resolve, depth, indent) + nullable;
-    }
-    if (type === "integer") return `number${nullable}`;
-    return SCALAR_TYPES.has(String(type)) ? `${String(type)}${nullable}` : "unknown";
-}
-
-/** The non-null member of a JSON Schema `type`, so `["string", "null"]` reads as `string`. */
-function primaryType(type: unknown) {
-    if (!Array.isArray(type)) return type;
-    const members: unknown[] = type;
-    return members.find((member) => member !== "null");
-}
-
-function allowsNull(type: unknown) {
-    if (!Array.isArray(type)) return false;
-    const members: unknown[] = type;
-    return members.includes("null");
-}
-
-/** The branches of a union schema, under whichever keyword carries them. */
-function variantsOf(schema: Record<string, unknown>) {
-    const variants = [schema.oneOf, schema.anyOf].find(Array.isArray);
-    return variants && variants.length > 0 ? variants : undefined;
-}
-
-function isObjectSchema(schema: unknown): schema is Record<string, unknown> {
-    return (
-        isRecord(schema) && (primaryType(schema.type) === "object" || isRecord(schema.properties))
-    );
-}
-
-/**
- * A response schema as one shape: a union's object branches merged into the
- * fields any of them may carry, a `null` branch dropped. A script reads a
- * field off whichever branch came back, so the names are what matter.
- */
-function responseUnion(schema: unknown, resolve: Resolve): unknown {
-    const resolved = resolve(schema);
-    if (!isRecord(resolved)) return resolved;
-    const variants = variantsOf(resolved);
-    if (!variants) return resolved;
-    const branches = variants
-        .map((variant) => responseUnion(variant, resolve))
-        .filter(
-            (variant): variant is Record<string, unknown> =>
-                isRecord(variant) && variant.type !== "null",
-        );
-    const objects = branches.filter(isObjectSchema);
-    if (objects.length === 0) return branches[0];
-    const properties: Record<string, unknown> = {};
-    for (const object of objects) {
-        if (isRecord(object.properties)) Object.assign(properties, object.properties);
-    }
-    return { type: "object", properties };
-}
-
-function responseObject(schema: Record<string, unknown>, resolve: Resolve, depth = 0): string {
-    const properties = isRecord(schema.properties) ? schema.properties : {};
-    const fields = orderedPropertyNames(schema).map((name) => {
-        const child = responseUnion(properties[name], resolve);
-        if (!isRecord(child) || depth >= MAX_DEPTH) return propertyName(name);
-        if (primaryType(child.type) === "array") {
-            const items = responseUnion(child.items, resolve);
-            return isObjectSchema(items)
-                ? `${propertyName(name)}[].${responseObject(items, resolve, depth + 1)}`
-                : propertyName(name);
-        }
-        return isObjectSchema(child)
-            ? `${propertyName(name)}.${responseObject(child, resolve, depth + 1)}`
-            : propertyName(name);
-    });
-    return fields.length > 0 ? `{ ${fields.join(", ")} }` : "{}";
-}
-
-/**
- * The names a result carries, as a script would read them: `{ id, items[].{ name } }`.
- * A schema that describes no fields is `{}`, which is also what a tool that
- * declares no response gets; a caller that knows nothing passes `undefined`
- * and gets `unknown`, so the model does not mistake silence for emptiness.
- */
-export function responseShape(schema: unknown) {
-    if (schema === undefined) return "unknown";
-    const resolve = resolver(schema);
-    const root = responseUnion(schema, resolve);
-    if (!isRecord(root)) return "{}";
-    if (primaryType(root.type) === "array") {
-        const items = responseUnion(root.items, resolve);
-        return isObjectSchema(items) ? `[]${responseObject(items, resolve)}` : "[]";
-    }
-    return responseObject(root, resolve);
-}
-
-/** One line, no comment terminator, and always a sentence, so it can sit in the doc comment. */
-function summarize(description: string) {
-    const text = compactLine(description).replaceAll("*/", "* /");
-    if (!text) return "";
-    return /[.!?]$/.test(text) ? text : `${text}.`;
-}
-
-export type ToolSignatureInput = {
-    /** As the script calls it: a name dot access cannot reach renders as the index call `tools["a-b"]`. */
-    name: string;
-    description: string;
-    /** JSON Schema of the input object as the model should see it. */
-    inputSchema: unknown;
-    /** Already rendered (a shared-shape ref like `$R1`), or the JSON Schema to render, or undefined for "unknown". */
-    returns: string | { schema: unknown };
-    /** Appended to the summary; the caller knows what else the model should be told (idempotency, embedded flows). */
-    notes?: ReadonlyArray<string>;
-};
-
-/** `/** summary *\/\nname(input: {...}): { fields }`. */
-export function renderToolSignature(tool: ToolSignatureInput) {
-    const summary = [summarize(tool.description), ...(tool.notes ?? [])].filter(Boolean).join(" ");
-    const callee = IDENTIFIER_PATTERN.test(tool.name)
-        ? tool.name
-        : `tools[${JSON.stringify(tool.name)}]`;
-    const returns =
-        typeof tool.returns === "string" ? tool.returns : responseShape(tool.returns.schema);
-    const input = inputType(tool.inputSchema, resolver(tool.inputSchema));
-    return `${summary ? `/** ${summary} */\n` : ""}${callee}(input: ${input}): ${returns}`;
-}

package/src/contracts/runtime/sync.ts

@@ -1,196 +0,0 @@
-import { z } from "zod";
-import { MESSAGE_ROLES, type TokenUsage } from "../wire/index";
-import { agentRefSchema, agentSlugSchema, variableDeclarationSchema } from "./grammar";
-import { approvalRequestedEventSchema, TRIGGER_OUTCOMES, TRIGGER_SOURCES } from "./triggers";
-import { DATASET_ERROR_KINDS } from "./datasets";
-
-/*
- * Fleet sync: `@m6d/cortex-server` mirrors thread/message/usage activity into
- * cc via `POST /api/runtime/sync` batches. Upserts are idempotent on
- * (serverId, id); an empty batch is the heartbeat.
- */
-
-const tokenCountSchema = z.number().int().nonnegative();
-
-export const tokenUsageSchema = z.object({
-    input: z.object({
-        noCache: tokenCountSchema,
-        cacheRead: tokenCountSchema,
-        cacheWrite: tokenCountSchema,
-        total: tokenCountSchema,
-    }),
-    output: z.object({
-        reasoning: tokenCountSchema,
-        text: tokenCountSchema,
-        total: tokenCountSchema,
-    }),
-    total: tokenCountSchema,
-}) satisfies z.ZodType<TokenUsage>;
-
-const componentNamesSchema = z.array(z.string().min(1).max(128)).max(1_000);
-
-/**
- * What a server offers every agent the Control Center creates for it, sent
- * whole at boot in `server.declare`: the `{{variables}}` its session loader
- * and request context fill, SDK ones included, and the names of the
- * components its code declares at server level, which reach those agents
- * too and which the Control Center therefore refuses on its own components.
- * Agents in the server's own code never appear here; the Control Center is
- * blind to them.
- */
-export const serverDeclarationSchema = z.object({
-    variables: z.array(variableDeclarationSchema),
-    components: z.object({
-        tool: componentNamesSchema,
-        skill: componentNamesSchema,
-        trigger: componentNamesSchema,
-        dataset_host: componentNamesSchema,
-    }),
-});
-export type ServerDeclaration = z.infer<typeof serverDeclarationSchema>;
-
-export const syncEventSchema = z.discriminatedUnion("type", [
-    z.object({
-        type: z.literal("thread.upsert"),
-        id: z.uuid(),
-        agentSlug: agentSlugSchema,
-        userId: z.string().max(255),
-        title: z.string().max(256).nullable(),
-        isTest: z.boolean(),
-        /** Set on headless threads a trigger owns; `userId` is then a sentinel. */
-        triggerName: z.string().max(64).nullable(),
-        triggerKey: z.string().max(256).nullable(),
-        createdAt: z.iso.datetime(),
-        updatedAt: z.iso.datetime(),
-    }),
-    z.object({
-        type: z.literal("thread.delete"),
-        id: z.uuid(),
-    }),
-    z.object({
-        type: z.literal("message.upsert"),
-        id: z.string().max(128),
-        threadId: z.uuid(),
-        role: z.enum(MESSAGE_ROLES),
-        text: z.string().nullable(),
-        ordinal: z.number().int(),
-        content: z.looseObject({}),
-        createdAt: z.iso.datetime(),
-    }),
-    z.object({
-        type: z.literal("usage.record"),
-        id: z.uuid(),
-        messageId: z.string().max(128),
-        threadId: z.uuid(),
-        stepNumber: z.number().int(),
-        tokenUsage: tokenUsageSchema,
-        /** Stamped by the event constructor: llm_requests has no timestamp column, but time-bucketed usage stats need one. */
-        createdAt: z.iso.datetime(),
-    }),
-    /** One loadSkill call, hit or miss, from either skill source. Bounded by construction (no body travels). */
-    z.object({
-        type: z.literal("skill.load"),
-        id: z.uuid(),
-        threadId: z.uuid(),
-        agentSlug: agentSlugSchema,
-        /** The ref cc issued for the agent that answered; a code-only agent or a miss has none. */
-        agentRef: agentRefSchema.optional(),
-        /** As the model asked for it, even when nothing answered. */
-        skillName: z.string().max(64),
-        source: z.enum(TRIGGER_SOURCES).nullable(),
-        hit: z.boolean(),
-        /** The user message this turn answers; the mirror joins it for the drill-down. */
-        messageId: z.string().max(128),
-        createdAt: z.iso.datetime(),
-    }),
-    /** One dataset read, refused or answered; never the rows. */
-    z.object({
-        type: z.literal("dataset.read"),
-        id: z.uuid(),
-        threadId: z.uuid(),
-        agentSlug: agentSlugSchema,
-        agentRef: agentRefSchema.optional(),
-        host: z.string().max(64),
-        /** Empty when the statement was refused before it named one. */
-        dataset: z.string().max(64),
-        rowCount: z.number().int().nonnegative(),
-        truncated: z.boolean(),
-        durationMs: z.number().int().nonnegative(),
-        status: z.enum(["ok", ...DATASET_ERROR_KINDS]),
-        /** The SQL the model wrote, when the read came from a statement. */
-        sql: z.string().max(4000).optional(),
-        /** Why a read did not answer: the parser's refusal, the validator's issues or the host's detail. */
-        detail: z.string().max(1000).optional(),
-        /** The user or trigger message this turn answers; the mirror joins it for the drill-down. */
-        messageId: z.string().max(128),
-        createdAt: z.iso.datetime(),
-    }),
-    /** One firing, upserted on start and again on its terminal outcome; the firing id is the event id so both land on one mirror row. */
-    z.object({
-        type: z.literal("trigger.firing"),
-        id: z.uuid(),
-        agentSlug: agentSlugSchema,
-        agentRef: agentRefSchema.optional(),
-        triggerName: z.string().max(64),
-        source: z.enum(TRIGGER_SOURCES),
-        threadId: z.uuid().nullable(),
-        runId: z.string().max(64).nullable(),
-        outcome: z.enum(TRIGGER_OUTCOMES),
-        reason: z.string().max(64).nullable(),
-        output: z.unknown(),
-        createdAt: z.iso.datetime(),
-        finishedAt: z.iso.datetime().nullable(),
-    }),
-    /**
-     * A run on a cc-backed agent parked on approval. cc delivers it to the
-     * published webhooks in the agent's audience; a code agent reacts in
-     * code and sends none.
-     */
-    z.object({
-        type: z.literal("approval.requested"),
-        id: z.uuid(),
-        agentSlug: agentSlugSchema,
-        agentRef: agentRefSchema,
-        payload: approvalRequestedEventSchema,
-        createdAt: z.iso.datetime(),
-    }),
-    /** What the server offers console-created agents, sent whole at boot and replacing the previous declaration. */
-    z.object({
-        type: z.literal("server.declare"),
-        id: z.uuid(),
-        ...serverDeclarationSchema.shape,
-        createdAt: z.iso.datetime(),
-    }),
-]);
-export type SyncEvent = z.infer<typeof syncEventSchema>;
-
-/*
- * `epoch` identifies the sending database's generation (a UUIDv7 minted into
- * the server DB's `sync_meta` row): a recreated database gets a new epoch, so
- * cc can tell a legitimately restarted outbox sequence from a stale batch.
- * v7 uuids are time-ordered, so cc also rejects batches from a superseded
- * (lexicographically lower) epoch outright.
- * `seq` is the batch's highest outbox row id; batches are contiguous
- * id-ordered outbox prefixes, so within one epoch cc keeps a per-server
- * high-water mark and discards batches at or below it. A stale in-flight
- * batch (an expired flusher lease, a replay after a lost ack) can never
- * overwrite newer mirrored state. Heartbeats carry no events and nothing to
- * fence, so `seq` exists only on the non-empty branch.
- */
-export const syncRequestSchema = z.union([
-    z.object({
-        events: z.array(syncEventSchema).min(1).max(500),
-        epoch: z.uuid(),
-        seq: z.number().int().positive(),
-    }),
-    z.object({
-        events: z.array(syncEventSchema).length(0),
-        epoch: z.uuid(),
-    }),
-]);
-export type SyncRequest = z.input<typeof syncRequestSchema>;
-
-export const syncResponseSchema = z.object({
-    accepted: z.number().int(),
-});
-export type SyncResponse = z.infer<typeof syncResponseSchema>;