@m6d/cortex-cli 0.12.1 → 0.14.0

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>;

package/src/contracts/runtime/triggers.ts

@@ -1,267 +0,0 @@
-import { z } from "zod";
-import { datasetIdentifierSchema } from "./datasets";
-import { modelChoiceSchema } from "./models";
-import {
-    agentRefSchema,
-    agentSlugSchema,
-    localizedTextSchema,
-    mentionedToolSchema,
-    sha256HexSchema,
-    slugSchema,
-} from "./grammar";
-
-/*
- * Triggers: named entry points on an agent. A firing is one invocation with a
- * payload and starts at most one run. The end user's message is the built-in
- * `message` trigger; every other trigger is fired by an external caller over
- * `POST /agents/:agentSlug/triggers/:name` on the server with the trigger's
- * own secret. Two directions live here: what cc publishes to the server
- * (declarations, secret checks) and what the server answers a caller.
- */
-
-export const MESSAGE_TRIGGER_NAME = "message";
-
-/** The tool a trigger run with an output schema answers through; no other tool may take its name. */
-export const TRIGGER_ANSWER_TOOL_NAME = "submitAnswer";
-
-/**
- * The first characters of a fire bearer say what it is: the secret callers
- * hold, or a one-shot test token the console minted. A test token is a JWT
- * the Control Center signed, so a server verifies it against the Control
- * Center's JWKS before saying a word to it, and the Control Center then
- * consumes it so it fires once.
- */
-export const TRIGGER_SECRET_PREFIXES = { live: "tr_live_", test: "tr_test_" } as const;
-export const TRIGGER_TEST_TOKEN_AUDIENCE = "cortex:trigger-test";
-
-/** The claims a test token carries beside the standard ones; the server checks them against the route it arrived on. */
-export const triggerTestTokenClaimsSchema = z.object({
-    agent: agentSlugSchema,
-    trigger: slugSchema,
-});
-
-export const TRIGGER_OUTCOMES = [
-    "started",
-    /** The run parked on a tool that needs approval; `POST .../firings/:id/answer` resumes it. */
-    "awaiting_approval",
-    "completed",
-    "failed",
-    "rejected",
-    "dropped",
-    "disabled",
-] as const;
-export type TriggerOutcome = (typeof TRIGGER_OUTCOMES)[number];
-
-/** Why a firing was dropped: the thread was busy, or the daily budget was spent. */
-export const TRIGGER_DROP_REASONS = ["busy", "budget"] as const;
-export type TriggerDropReason = (typeof TRIGGER_DROP_REASONS)[number];
-
-export const TRIGGER_SOURCES = ["code", "cc"] as const;
-export type TriggerSource = (typeof TRIGGER_SOURCES)[number];
-
-/**
- * Which thread a firing lands in. `single`: one thread for the trigger.
- * `per-firing`: a fresh thread every time. `ephemeral`: a fresh thread that
- * is deleted once the run completes, for one-shot calls: the answer reaches
- * the caller as the firing's output or through the live stream, and nothing
- * else outlives the run; a failed run keeps its thread for inspection. `keyed`:
- * one thread per distinct value at a JSON pointer into the payload (e.g.
- * `/pull_request/number`).
- */
-export const triggerThreadPolicySchema = z.discriminatedUnion("policy", [
-    z.object({ policy: z.literal("single") }),
-    z.object({ policy: z.literal("per-firing") }),
-    z.object({ policy: z.literal("ephemeral") }),
-    z.object({ policy: z.literal("keyed"), key: z.string().regex(/^\//).max(256) }),
-]);
-export type TriggerThreadPolicy = z.infer<typeof triggerThreadPolicySchema>;
-
-/* cc publishes to the server. */
-
-/**
- * A tool a trigger's instructions mention. Most are sandbox bindings; one
- * that parks for approval is declared to the model as a function call
- * instead, so it carries what that takes, as a /resolve signature does: a run
- * started by a trigger has no other way to learn it.
- */
-const triggerMentionedToolSchema = z.discriminatedUnion("requiresApproval", [
-    mentionedToolSchema.extend({ requiresApproval: z.literal(false) }),
-    mentionedToolSchema.extend({
-        requiresApproval: z.literal(true),
-        signature: z.string(),
-        inputSchema: z.record(z.string(), z.unknown()),
-        approvalMessage: localizedTextSchema.optional(),
-    }),
-]);
-
-/** A trigger as both sides describe it. Secrets and credentials never cross this contract. */
-export const triggerDeclarationSchema = z.object({
-    name: slugSchema,
-    description: z.string().max(500),
-    /** JSON Schema for the payload; cc triggers are validated from it on the server. */
-    input: z.record(z.string(), z.unknown()),
-    /**
-     * JSON Schema the run's answer must match, or null for a free-text run.
-     * The run submits it through an answer tool whose input is this schema,
-     * and the server stores it as the firing's `output`; a run that never
-     * submits fails with `no_output`, one whose answers the schema refused
-     * with `invalid_output`.
-     */
-    output: z.record(z.string(), z.unknown()).nullable(),
-    /**
-     * The prompt the run starts from, mentions already rendered to names by
-     * the console; `{{variables}}` and `{{/json/pointer}}` payload fields
-     * are the server's to fill per firing.
-     */
-    instructions: z.string().max(20_000),
-    /** Tools the instructions mention: sandbox bindings for the run, or declared to the model when they park for approval. */
-    mentionedTools: z.array(triggerMentionedToolSchema),
-    /** Datasets the instructions mention, listed in the run's context whatever the question. */
-    mentionedDatasets: z.array(datasetIdentifierSchema),
-    threadPolicy: triggerThreadPolicySchema,
-    budgetPerDay: z.number().int().positive().nullable(),
-    /** Consecutive failed or rejected firings before the trigger disables itself. */
-    disableAfterFailures: z.number().int().positive(),
-    hasCredential: z.boolean(),
-    /** What runs of this trigger talk to, over the agent's pick; read live like the credential. */
-    modelChoice: modelChoiceSchema,
-    /**
-     * sha256 of the fire secret, so a server checks a presented bearer in
-     * process; the Control Center hears only about console test secrets,
-     * which it alone can consume.
-     */
-    secretHash: sha256HexSchema,
-});
-export type TriggerDeclaration = z.infer<typeof triggerDeclarationSchema>;
-
-/**
- * `POST /api/runtime/agents/:agentSlug/triggers/:name/auth`: a server holding a
- * bearer for a cc trigger asks cc whether it is the trigger's secret. Only the
- * hash travels; a positive answer carries the bearer the run acts with, if
- * the trigger has a credential, resolved by cc (acquired, for an OAuth2 one).
- */
-export const triggerAuthRequestSchema = z.object({
-    secretHash: sha256HexSchema,
-});
-export type TriggerAuthRequest = z.infer<typeof triggerAuthRequestSchema>;
-
-export const triggerAuthResponseSchema = z.discriminatedUnion("ok", [
-    z.object({
-        ok: z.literal(true),
-        credential: z.string().nullable(),
-        /** When the bearer stops working, ISO 8601; null for one that does not expire or has no credential. */
-        expiresAt: z.iso.datetime().nullable(),
-        /** The bearer was a single-use test secret, now spent: the server must not cache this verdict. */
-        oneShot: z.boolean(),
-    }),
-    z.object({ ok: z.literal(false) }),
-]);
-export type TriggerAuthResponse = z.infer<typeof triggerAuthResponseSchema>;
-
-/* The server answers a caller firing `POST /agents/:agentSlug/triggers/:name`. */
-
-/** One server tool call a parked run waits on; `POST .../firings/:id/answer` decides it. */
-const triggerApprovalSchema = z.object({
-    toolCallId: z.string(),
-    toolName: z.string(),
-    input: z.unknown(),
-});
-
-/** The host-reaction events a run reports. One so far; the shape is generic. */
-export const HOST_EVENTS = ["approval_requested"] as const;
-
-/**
- * A run parked on server tools that need the user's approval, as every host
- * hears of it: the code hook's argument and a webhook's body are this one
- * object. `agentId` is the slug; `agentRef` is cc's id when cc backs the
- * agent. `firingId` and `triggerName` are set when a trigger started the run,
- * which is what a host answering through the firing route needs.
- */
-export const approvalRequestedEventSchema = z.object({
-    event: z.literal("approval_requested"),
-    agentId: z.string(),
-    agentRef: agentRefSchema.optional(),
-    threadId: z.string(),
-    runId: z.string(),
-    userId: z.string(),
-    firingId: z.uuid().optional(),
-    triggerName: z.string().optional(),
-    /** The hook always gets each call's `input`; a webhook body leaves it out when the whole would be too large for the wire. */
-    approvals: z.array(triggerApprovalSchema.extend({ input: z.unknown().optional() })),
-    occurredAt: z.iso.datetime(),
-});
-export type ApprovalRequestedEvent = z.infer<typeof approvalRequestedEventSchema>;
-
-export const triggerFiringResponseSchema = z.discriminatedUnion("outcome", [
-    z.object({
-        firingId: z.uuid(),
-        outcome: z.literal("started"),
-        threadId: z.uuid(),
-        runId: z.string(),
-    }),
-    /* The shapes a caller that waited (`?wait=`) gets instead of `started`: the run ended, or it parked for a decision. */
-    z.object({
-        firingId: z.uuid(),
-        outcome: z.literal("awaiting_approval"),
-        threadId: z.uuid(),
-        runId: z.string(),
-        approvals: z.array(triggerApprovalSchema),
-    }),
-    z.object({
-        firingId: z.uuid(),
-        outcome: z.literal("completed"),
-        threadId: z.uuid(),
-        runId: z.string(),
-        /** The validated answer when the trigger declares an output schema, else null. */
-        output: z.unknown(),
-    }),
-    z.object({
-        firingId: z.uuid(),
-        outcome: z.literal("failed"),
-        threadId: z.uuid(),
-        runId: z.string(),
-        reason: z.string().nullable(),
-    }),
-    z.object({
-        firingId: z.uuid(),
-        outcome: z.literal("dropped"),
-        reason: z.enum(TRIGGER_DROP_REASONS),
-        threadId: z.uuid().nullable(),
-    }),
-    z.object({ firingId: z.uuid(), outcome: z.literal("disabled") }),
-    z.object({
-        firingId: z.uuid(),
-        outcome: z.literal("rejected"),
-        issues: z.array(z.object({ path: z.string(), message: z.string() })),
-    }),
-]);
-export type TriggerFiringResponse = z.infer<typeof triggerFiringResponseSchema>;
-
-/** `POST /agents/:agentSlug/triggers/:name/firings/:id/answer`: the decision on one parked call. */
-export const triggerFiringAnswerSchema = z.object({
-    toolCallId: z.string().min(1).max(256),
-    approved: z.boolean(),
-});
-export type TriggerFiringAnswer = z.infer<typeof triggerFiringAnswerSchema>;
-
-/** One row of `GET /agents/:agentSlug/triggers/:name/firings`, and the answer of `.../firings/:id`. */
-export const triggerFiringRecordSchema = z.object({
-    id: z.uuid(),
-    triggerName: z.string(),
-    threadId: z.uuid().nullable(),
-    runId: z.string().nullable(),
-    outcome: z.enum(TRIGGER_OUTCOMES),
-    reason: z.string().nullable(),
-    /** Set once a run with an output schema completed; null otherwise. */
-    output: z.unknown(),
-    /** The calls an `awaiting_approval` firing waits on; filled by the single-firing read, empty in the list and for every other outcome. */
-    approvals: z.array(triggerApprovalSchema),
-    createdAt: z.iso.datetime(),
-    finishedAt: z.iso.datetime().nullable(),
-});
-export type TriggerFiringRecord = z.infer<typeof triggerFiringRecordSchema>;
-
-export const triggerFiringListResponseSchema = z.object({
-    firings: z.array(triggerFiringRecordSchema),
-});
-export type TriggerFiringListResponse = z.infer<typeof triggerFiringListResponseSchema>;