rivet-design 0.12.4 → 0.13.0

package/dist/cli/commands/wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AA+E3E;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAU,MAAM,MAAM,EAAE,KAAG,OAAO,CAAC,gBAAgB,CAqEzE,CAAC"}

package/dist/cli/commands/wait.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleWait = void 0;
+const envelope_1 = require("../envelope");
+const flags_1 = require("../flags");
+const client_1 = require("../client");
+const shared_1 = require("./shared");
+const COMMAND = 'wait';
+const DEFAULT_WAIT_TIMEOUT_SECONDS = 120;
+const WAIT_POLL_INTERVAL_MS = 500;
+const WAIT_FLAG_SPEC = {
+    timeout: { takesValue: true },
+};
+const workStateOf = (status, workId) => {
+    const activeRun = status.activeRun;
+    if (activeRun &&
+        (activeRun.agentRunId === workId || activeRun.traceId === workId)) {
+        return 'running';
+    }
+    const leases = status.queue?.leases ?? [];
+    if (leases.some((lease) => lease.requestId === workId ||
+        (lease.mergedRequestIds ?? []).includes(workId))) {
+        return 'running';
+    }
+    const queued = status.queue?.queued ?? [];
+    if (queued.some((item) => item.requestId === workId)) {
+        return 'pending';
+    }
+    if ((status.settledRequestIds ?? []).includes(workId)) {
+        return 'settled';
+    }
+    return 'unknown';
+};
+const waitTimeoutMessage = (workId, state, timeoutSeconds) => state === 'pending'
+    ? `Work ${workId} is still pending after ${timeoutSeconds}s. Check \`rivet status\`.`
+    : `Work ${workId} is still running after ${timeoutSeconds}s. Re-issue \`rivet wait\` or check \`rivet status\`.`;
+const unknownWorkMessage = (workId) => `Unknown work id ${workId}. Check \`rivet status\` for queued, running, or recently settled work.`;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Block — boundedly — until a work id settles. Exits `0` when the work is no
+ * longer queued, leased, or running; exits `5` on timeout with the work
+ * still live (not a failure: re-issue `rivet wait` or check `rivet status`).
+ * The timeout envelope reports the honest state: `running` for leased or
+ * active work, `pending` for work merely staged in the queue.
+ */
+const handleWait = async (args) => {
+    const context = (0, shared_1.parseCommandContext)(COMMAND, args, WAIT_FLAG_SPEC);
+    if ((0, shared_1.isCommandResult)(context)) {
+        return context;
+    }
+    const workId = context.flags.positionals[0];
+    if (!workId) {
+        return (0, envelope_1.errorResult)(COMMAND, 'USAGE_ERROR', 'Usage: rivet wait <workId> [--timeout <seconds>]');
+    }
+    const timeoutSeconds = (0, flags_1.integerFlag)(context.flags, 'timeout') ?? DEFAULT_WAIT_TIMEOUT_SECONDS;
+    if (context.flags.errors.length > 0) {
+        return (0, envelope_1.errorResult)(COMMAND, 'USAGE_ERROR', context.flags.errors.join('; '));
+    }
+    const attached = await (0, shared_1.attachOrUnavailable)(COMMAND, context.projectPath);
+    if (!(0, shared_1.isAttached)(attached)) {
+        return attached;
+    }
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let wasObservedRunning = false;
+    for (;;) {
+        let status;
+        try {
+            const response = await (0, client_1.requestServer)(attached, '/api/cli/status');
+            if (response.status !== 200) {
+                return (0, shared_1.serverErrorResult)(COMMAND, response.status, response.body);
+            }
+            status = response.body;
+        }
+        catch (error) {
+            return (0, shared_1.transportErrorResult)(COMMAND, error);
+        }
+        const workState = workStateOf(status, workId);
+        if (workState === 'settled') {
+            return (0, envelope_1.okResult)(COMMAND, {
+                workId,
+                state: 'settled',
+                wasObservedRunning,
+            });
+        }
+        if (workState === 'unknown') {
+            return (0, envelope_1.errorResult)(COMMAND, 'OPERATION_FAILED', unknownWorkMessage(workId), {
+                workId,
+                state: 'unknown',
+            });
+        }
+        if (workState === 'running') {
+            wasObservedRunning = true;
+        }
+        if (Date.now() >= deadline) {
+            return (0, envelope_1.errorResult)(COMMAND, 'WAIT_TIMEOUT', waitTimeoutMessage(workId, workState, timeoutSeconds), { workId, state: workState });
+        }
+        await sleep(WAIT_POLL_INTERVAL_MS);
+    }
+};
+exports.handleWait = handleWait;
+//# sourceMappingURL=wait.js.map

package/dist/cli/commands/wait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.js","sourceRoot":"","sources":["../../../src/cli/commands/wait.ts"],"names":[],"mappings":"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"}

package/dist/cli/entry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lean entry point for control-plane subcommands. `bin/rivet.js` routes here
+ * (instead of `dist/index.js`) when argv names a control command, skipping
+ * the full CLI's static import graph — the dominant fixed cost of an
+ * invocation. Everything heavier than the router loads lazily per command.
+ *
+ * Behavior must stay identical to the control-plane branch in
+ * `src/index.ts` `main()`: run the command, flush stdout so piped envelopes
+ * are never truncated, exit with the documented code.
+ */
+export declare const runControlPlane: (args?: string[]) => Promise<void>;
+//# sourceMappingURL=entry.d.ts.map

package/dist/cli/entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../src/cli/entry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAM,MAAM,EAA0B,KACrC,OAAO,CAAC,IAAI,CAWd,CAAC"}

package/dist/cli/entry.js

@@ -0,0 +1,61 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runControlPlane = void 0;
+const commandNames_1 = require("./commandNames");
+/**
+ * Lean entry point for control-plane subcommands. `bin/rivet.js` routes here
+ * (instead of `dist/index.js`) when argv names a control command, skipping
+ * the full CLI's static import graph — the dominant fixed cost of an
+ * invocation. Everything heavier than the router loads lazily per command.
+ *
+ * Behavior must stay identical to the control-plane branch in
+ * `src/index.ts` `main()`: run the command, flush stdout so piped envelopes
+ * are never truncated, exit with the documented code.
+ */
+const runControlPlane = async (args = process.argv.slice(2)) => {
+    if (!(0, commandNames_1.isCliControlCommand)(args[0])) {
+        // Defensive: the bin only routes control commands here, but a direct
+        // caller could pass anything. Fall back to the full CLI.
+        const { main } = await Promise.resolve().then(() => __importStar(require('../index')));
+        return main(args);
+    }
+    const { runCliControlCommand } = await Promise.resolve().then(() => __importStar(require('./router')));
+    const exitCode = await runCliControlCommand(args);
+    // Flush stdout before exiting so piped envelopes are never truncated.
+    process.stdout.write('', () => process.exit(exitCode));
+};
+exports.runControlPlane = runControlPlane;
+//# sourceMappingURL=entry.js.map

package/dist/cli/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/cli/entry.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,iDAAqD;AAErD;;;;;;;;;GASG;AACI,MAAM,eAAe,GAAG,KAAK,EAClC,OAAiB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EACvB,EAAE;IACjB,IAAI,CAAC,IAAA,kCAAmB,EAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,qEAAqE;QACrE,yDAAyD;QACzD,MAAM,EAAE,IAAI,EAAE,GAAG,wDAAa,UAAU,GAAC,CAAC;QAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IACD,MAAM,EAAE,oBAAoB,EAAE,GAAG,wDAAa,UAAU,GAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,IAAI,CAAC,CAAC;IAClD,sEAAsE;IACtE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;AACzD,CAAC,CAAC;AAbW,QAAA,eAAe,mBAa1B"}

package/dist/cli/envelope.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Machine-readable output contract for `rivet` subcommands.
+ *
+ * Every invocation prints exactly one schema-versioned JSON envelope on
+ * stdout (or one envelope per line for NDJSON streaming surfaces) and routes
+ * all human-readable progress to stderr. Exit codes are documented and
+ * stable so agents can branch on them without parsing prose.
+ *
+ * Contract: `docs/cli-first-architecture-design.md` (Invocation model) and
+ * `openspec/changes/cli-first-control-plane/specs/cli-control-plane/spec.md`.
+ */
+export declare const CLI_SCHEMA_VERSION = 1;
+/** Documented exit codes for the CLI contract. */
+export declare const CLI_EXIT_CODES: {
+    /** Operation completed. */
+    readonly ok: 0;
+    /** Operation failed — see `error.code` in the envelope. */
+    readonly operationFailed: 1;
+    /** Usage error: unknown command, missing argument, invalid flag value. */
+    readonly usageError: 2;
+    /** Authentication required — run `rivet login`. */
+    readonly authRequired: 3;
+    /** No server for the project and one could not be started. */
+    readonly serverUnavailable: 4;
+    /** `rivet wait` timed out with the work still pending or running (not a failure). */
+    readonly waitTimeout: 5;
+};
+export type CliExitCode = (typeof CLI_EXIT_CODES)[keyof typeof CLI_EXIT_CODES];
+/** Stable machine-readable error codes carried in `error.code`. */
+export type CliErrorCode = 'OPERATION_FAILED' | 'USAGE_ERROR' | 'AUTH_REQUIRED' | 'SERVER_UNAVAILABLE' | 'WAIT_TIMEOUT'
+/** `rivet mcp` from a stale host registration: the MCP server is removed. */
+ | 'MCP_REMOVED';
+export type CliErrorEnvelope = {
+    schemaVersion: typeof CLI_SCHEMA_VERSION;
+    ok: false;
+    command: string;
+    error: {
+        code: CliErrorCode;
+        message: string;
+        /** Optional structured detail (e.g. server error payloads). */
+        details?: unknown;
+    };
+};
+export type CliOkEnvelope<TData = unknown> = {
+    schemaVersion: typeof CLI_SCHEMA_VERSION;
+    ok: true;
+    command: string;
+    data: TData;
+};
+export type CliEnvelope<TData = unknown> = CliOkEnvelope<TData> | CliErrorEnvelope;
+/** Result of one subcommand run: the envelope to print plus its exit code. */
+export type CliCommandResult = {
+    envelope: CliEnvelope;
+    exitCode: CliExitCode;
+};
+export declare const okResult: (command: string, data: unknown) => CliCommandResult;
+export declare const errorResult: (command: string, code: CliErrorCode, message: string, details?: unknown) => CliCommandResult;
+/** Serialize one envelope as a single stdout line (NDJSON-compatible). */
+export declare const serializeEnvelope: (envelope: CliEnvelope) => string;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/cli/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/cli/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,kDAAkD;AAClD,eAAO,MAAM,cAAc;IACzB,2BAA2B;;IAE3B,2DAA2D;;IAE3D,0EAA0E;;IAE1E,mDAAmD;;IAEnD,8DAA8D;;IAE9D,qFAAqF;;CAE7E,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAE/E,mEAAmE;AACnE,MAAM,MAAM,YAAY,GACpB,kBAAkB,GAClB,aAAa,GACb,eAAe,GACf,oBAAoB,GACpB,cAAc;AAChB,6EAA6E;GAC3E,aAAa,CAAC;AAElB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,aAAa,EAAE,OAAO,kBAAkB,CAAC;IACzC,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,IAAI,EAAE,YAAY,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,+DAA+D;QAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,aAAa,CAAC,KAAK,GAAG,OAAO,IAAI;IAC3C,aAAa,EAAE,OAAO,kBAAkB,CAAC;IACzC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,WAAW,CAAC,KAAK,GAAG,OAAO,IACrC,aAAa,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAAC;AAE1C,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,WAAW,CAAC;CACvB,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,SAAS,MAAM,EAAE,MAAM,OAAO,KAAG,gBAGxD,CAAC;AAWH,eAAO,MAAM,WAAW,GACtB,SAAS,MAAM,EACf,MAAM,YAAY,EAClB,SAAS,MAAM,EACf,UAAU,OAAO,KAChB,gBAQD,CAAC;AAEH,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,GAAI,UAAU,WAAW,KAAG,MAChC,CAAC"}

package/dist/cli/envelope.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Machine-readable output contract for `rivet` subcommands.
+ *
+ * Every invocation prints exactly one schema-versioned JSON envelope on
+ * stdout (or one envelope per line for NDJSON streaming surfaces) and routes
+ * all human-readable progress to stderr. Exit codes are documented and
+ * stable so agents can branch on them without parsing prose.
+ *
+ * Contract: `docs/cli-first-architecture-design.md` (Invocation model) and
+ * `openspec/changes/cli-first-control-plane/specs/cli-control-plane/spec.md`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeEnvelope = exports.errorResult = exports.okResult = exports.CLI_EXIT_CODES = exports.CLI_SCHEMA_VERSION = void 0;
+exports.CLI_SCHEMA_VERSION = 1;
+/** Documented exit codes for the CLI contract. */
+exports.CLI_EXIT_CODES = {
+    /** Operation completed. */
+    ok: 0,
+    /** Operation failed — see `error.code` in the envelope. */
+    operationFailed: 1,
+    /** Usage error: unknown command, missing argument, invalid flag value. */
+    usageError: 2,
+    /** Authentication required — run `rivet login`. */
+    authRequired: 3,
+    /** No server for the project and one could not be started. */
+    serverUnavailable: 4,
+    /** `rivet wait` timed out with the work still pending or running (not a failure). */
+    waitTimeout: 5,
+};
+const okResult = (command, data) => ({
+    envelope: { schemaVersion: exports.CLI_SCHEMA_VERSION, ok: true, command, data },
+    exitCode: exports.CLI_EXIT_CODES.ok,
+});
+exports.okResult = okResult;
+const ERROR_EXIT_CODES = {
+    OPERATION_FAILED: exports.CLI_EXIT_CODES.operationFailed,
+    USAGE_ERROR: exports.CLI_EXIT_CODES.usageError,
+    AUTH_REQUIRED: exports.CLI_EXIT_CODES.authRequired,
+    SERVER_UNAVAILABLE: exports.CLI_EXIT_CODES.serverUnavailable,
+    WAIT_TIMEOUT: exports.CLI_EXIT_CODES.waitTimeout,
+    MCP_REMOVED: exports.CLI_EXIT_CODES.usageError,
+};
+const errorResult = (command, code, message, details) => ({
+    envelope: {
+        schemaVersion: exports.CLI_SCHEMA_VERSION,
+        ok: false,
+        command,
+        error: { code, message, ...(details === undefined ? {} : { details }) },
+    },
+    exitCode: ERROR_EXIT_CODES[code],
+});
+exports.errorResult = errorResult;
+/** Serialize one envelope as a single stdout line (NDJSON-compatible). */
+const serializeEnvelope = (envelope) => JSON.stringify(envelope);
+exports.serializeEnvelope = serializeEnvelope;
+//# sourceMappingURL=envelope.js.map

package/dist/cli/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/cli/envelope.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEU,QAAA,kBAAkB,GAAG,CAAC,CAAC;AAEpC,kDAAkD;AACrC,QAAA,cAAc,GAAG;IAC5B,2BAA2B;IAC3B,EAAE,EAAE,CAAC;IACL,2DAA2D;IAC3D,eAAe,EAAE,CAAC;IAClB,0EAA0E;IAC1E,UAAU,EAAE,CAAC;IACb,mDAAmD;IACnD,YAAY,EAAE,CAAC;IACf,8DAA8D;IAC9D,iBAAiB,EAAE,CAAC;IACpB,qFAAqF;IACrF,WAAW,EAAE,CAAC;CACN,CAAC;AA0CJ,MAAM,QAAQ,GAAG,CAAC,OAAe,EAAE,IAAa,EAAoB,EAAE,CAAC,CAAC;IAC7E,QAAQ,EAAE,EAAE,aAAa,EAAE,0BAAkB,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE;IACxE,QAAQ,EAAE,sBAAc,CAAC,EAAE;CAC5B,CAAC,CAAC;AAHU,QAAA,QAAQ,YAGlB;AAEH,MAAM,gBAAgB,GAAsC;IAC1D,gBAAgB,EAAE,sBAAc,CAAC,eAAe;IAChD,WAAW,EAAE,sBAAc,CAAC,UAAU;IACtC,aAAa,EAAE,sBAAc,CAAC,YAAY;IAC1C,kBAAkB,EAAE,sBAAc,CAAC,iBAAiB;IACpD,YAAY,EAAE,sBAAc,CAAC,WAAW;IACxC,WAAW,EAAE,sBAAc,CAAC,UAAU;CACvC,CAAC;AAEK,MAAM,WAAW,GAAG,CACzB,OAAe,EACf,IAAkB,EAClB,OAAe,EACf,OAAiB,EACC,EAAE,CAAC,CAAC;IACtB,QAAQ,EAAE;QACR,aAAa,EAAE,0BAAkB;QACjC,EAAE,EAAE,KAAK;QACT,OAAO;QACP,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;KACxE;IACD,QAAQ,EAAE,gBAAgB,CAAC,IAAI,CAAC;CACjC,CAAC,CAAC;AAbU,QAAA,WAAW,eAarB;AAEH,0EAA0E;AACnE,MAAM,iBAAiB,GAAG,CAAC,QAAqB,EAAU,EAAE,CACjE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;AADd,QAAA,iBAAiB,qBACH"}

package/dist/cli/flags.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Minimal flag parser for `rivet` control-plane subcommands. Supports
+ * `--flag value`, `--flag=value`, and boolean flags; collects positionals;
+ * reports unknown flags so commands can fail with a usage error instead of
+ * silently ignoring typos.
+ */
+export type FlagSpec = Record<string, {
+    takesValue: boolean;
+}>;
+export type ParsedFlags = {
+    values: Record<string, string | boolean>;
+    positionals: string[];
+    errors: string[];
+};
+export declare const parseFlags: (args: string[], spec: FlagSpec) => ParsedFlags;
+export declare const stringFlag: (parsed: ParsedFlags, name: string) => string | undefined;
+export declare const booleanFlag: (parsed: ParsedFlags, name: string) => boolean;
+/** Parse a positive integer flag; pushes a usage error when malformed. */
+export declare const integerFlag: (parsed: ParsedFlags, name: string) => number | undefined;
+//# sourceMappingURL=flags.d.ts.map

package/dist/cli/flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../../src/cli/flags.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAE/D,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACzC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,EAAE,EAAE,MAAM,QAAQ,KAAG,WA+C3D,CAAC;AAEF,eAAO,MAAM,UAAU,GACrB,QAAQ,WAAW,EACnB,MAAM,MAAM,KACX,MAAM,GAAG,SAGX,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,QAAQ,WAAW,EAAE,MAAM,MAAM,KAAG,OAClC,CAAC;AAE/B,0EAA0E;AAC1E,eAAO,MAAM,WAAW,GACtB,QAAQ,WAAW,EACnB,MAAM,MAAM,KACX,MAAM,GAAG,SAWX,CAAC"}

package/dist/cli/flags.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Minimal flag parser for `rivet` control-plane subcommands. Supports
+ * `--flag value`, `--flag=value`, and boolean flags; collects positionals;
+ * reports unknown flags so commands can fail with a usage error instead of
+ * silently ignoring typos.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.integerFlag = exports.booleanFlag = exports.stringFlag = exports.parseFlags = void 0;
+const parseFlags = (args, spec) => {
+    const values = {};
+    const positionals = [];
+    const errors = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const equalsIndex = arg.indexOf('=');
+        const name = equalsIndex === -1 ? arg.slice(2) : arg.slice(2, equalsIndex);
+        const inlineValue = equalsIndex === -1 ? undefined : arg.slice(equalsIndex + 1);
+        const definition = spec[name];
+        if (!definition) {
+            errors.push(`Unknown flag --${name}`);
+            continue;
+        }
+        if (!definition.takesValue) {
+            if (inlineValue !== undefined) {
+                errors.push(`Flag --${name} does not take a value`);
+                continue;
+            }
+            values[name] = true;
+            continue;
+        }
+        if (inlineValue !== undefined) {
+            values[name] = inlineValue;
+            continue;
+        }
+        const next = args[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+            errors.push(`Flag --${name} requires a value`);
+            continue;
+        }
+        values[name] = next;
+        i++;
+    }
+    return { values, positionals, errors };
+};
+exports.parseFlags = parseFlags;
+const stringFlag = (parsed, name) => {
+    const value = parsed.values[name];
+    return typeof value === 'string' ? value : undefined;
+};
+exports.stringFlag = stringFlag;
+const booleanFlag = (parsed, name) => parsed.values[name] === true;
+exports.booleanFlag = booleanFlag;
+/** Parse a positive integer flag; pushes a usage error when malformed. */
+const integerFlag = (parsed, name) => {
+    const raw = (0, exports.stringFlag)(parsed, name);
+    if (raw === undefined) {
+        return undefined;
+    }
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isInteger(value) || value <= 0) {
+        parsed.errors.push(`Flag --${name} must be a positive integer`);
+        return undefined;
+    }
+    return value;
+};
+exports.integerFlag = integerFlag;
+//# sourceMappingURL=flags.js.map

package/dist/cli/flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../../src/cli/flags.ts"],"names":[],"mappings":"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"}

package/dist/cli/handoff.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Optional caller handoff for agent invocations of the `rivet` CLI.
+ *
+ * Agent invocations identify themselves with `--caller-agent` /
+ * `--caller-model` / `--caller-session` (or env equivalents, or a single
+ * `--handoff <json>` blob). Human-direct invocations omit all of it and are
+ * first-class: they are recorded with initiator `human` and contribute
+ * nothing to runner selection.
+ *
+ * The handoff is a validated hint, never an authority: `caller-agent` is
+ * checked against an allowlist (anything else records as `unknown`), and it
+ * is accepted ONLY from invocation flags and environment — never from
+ * project-local files, because the runner it selects executes with bypassed
+ * permissions and a cloned repo must not influence which binary that is or
+ * which chat session it resumes.
+ */
+import type { CallerAgentKind, WorkItemInitiator } from '../types/change-request-types';
+export declare const CALLER_AGENT_ALLOWLIST: readonly ["claude", "codex", "cursor"];
+export type CallerHandoff = {
+    agent: CallerAgentKind;
+    model?: string;
+    /** Live AI-chat session id. Never logged and never sent to telemetry. */
+    session?: string;
+};
+export type { CallerAgentKind, WorkItemInitiator };
+export declare const HANDOFF_ENV_VARS: {
+    readonly agent: "RIVET_CALLER_AGENT";
+    readonly model: "RIVET_CALLER_MODEL";
+    readonly session: "RIVET_CALLER_SESSION";
+};
+export type HandoffFlagValues = {
+    callerAgent?: string;
+    callerModel?: string;
+    callerSession?: string;
+    /** Raw `--handoff <json>` value, when supplied. */
+    handoffJson?: string;
+};
+export type ParseHandoffResult = {
+    ok: true;
+    handoff: CallerHandoff | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve the caller handoff from invocation flags and environment only.
+ * Precedence per field: explicit `--caller-*` flag > `--handoff` JSON >
+ * environment variable. No handoff sources present → `handoff: null`
+ * (the human-direct path).
+ */
+export declare const parseHandoff: (flags: HandoffFlagValues, env?: NodeJS.ProcessEnv) => ParseHandoffResult;
+/** Initiator attribution for a parsed handoff (`human` when absent). */
+export declare const initiatorFor: (handoff: CallerHandoff | null) => WorkItemInitiator;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/cli/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../src/cli/handoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,+BAA+B,CAAC;AAEvC,eAAO,MAAM,sBAAsB,wCAAyC,CAAC;AAE7E,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,eAAe,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,CAAC;AAEnD,eAAO,MAAM,gBAAgB;;;;CAInB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AA2CF,MAAM,MAAM,kBAAkB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7E;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GACvB,OAAO,iBAAiB,EACxB,MAAK,MAAM,CAAC,UAAwB,KACnC,kBAuCF,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,YAAY,GACvB,SAAS,aAAa,GAAG,IAAI,KAC5B,iBAOoB,CAAC"}

package/dist/cli/handoff.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Optional caller handoff for agent invocations of the `rivet` CLI.
+ *
+ * Agent invocations identify themselves with `--caller-agent` /
+ * `--caller-model` / `--caller-session` (or env equivalents, or a single
+ * `--handoff <json>` blob). Human-direct invocations omit all of it and are
+ * first-class: they are recorded with initiator `human` and contribute
+ * nothing to runner selection.
+ *
+ * The handoff is a validated hint, never an authority: `caller-agent` is
+ * checked against an allowlist (anything else records as `unknown`), and it
+ * is accepted ONLY from invocation flags and environment — never from
+ * project-local files, because the runner it selects executes with bypassed
+ * permissions and a cloned repo must not influence which binary that is or
+ * which chat session it resumes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initiatorFor = exports.parseHandoff = exports.HANDOFF_ENV_VARS = exports.CALLER_AGENT_ALLOWLIST = void 0;
+exports.CALLER_AGENT_ALLOWLIST = ['claude', 'codex', 'cursor'];
+exports.HANDOFF_ENV_VARS = {
+    agent: 'RIVET_CALLER_AGENT',
+    model: 'RIVET_CALLER_MODEL',
+    session: 'RIVET_CALLER_SESSION',
+};
+const normalizeAgentKind = (raw) => {
+    const candidate = raw.trim().toLowerCase();
+    return exports.CALLER_AGENT_ALLOWLIST.includes(candidate)
+        ? candidate
+        : 'unknown';
+};
+const nonEmpty = (value) => {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+};
+/**
+ * Parse the `--handoff` JSON blob. The shape is schema-versioned alongside
+ * the output envelope; unknown fields are ignored so agent guidance can
+ * template one opaque blob.
+ */
+const parseHandoffJson = (raw) => {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null) {
+            return null;
+        }
+        return {
+            agent: typeof parsed.agent === 'string' ? parsed.agent : undefined,
+            model: typeof parsed.model === 'string' ? parsed.model : undefined,
+            session: typeof parsed.session === 'string' ? parsed.session : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Resolve the caller handoff from invocation flags and environment only.
+ * Precedence per field: explicit `--caller-*` flag > `--handoff` JSON >
+ * environment variable. No handoff sources present → `handoff: null`
+ * (the human-direct path).
+ */
+const parseHandoff = (flags, env = process.env) => {
+    let fromJson = {};
+    if (flags.handoffJson !== undefined) {
+        const parsed = parseHandoffJson(flags.handoffJson);
+        if (!parsed) {
+            return {
+                ok: false,
+                error: '--handoff must be a JSON object like {"agent":"claude","model":"...","session":"..."}',
+            };
+        }
+        fromJson = parsed;
+    }
+    const agentRaw = nonEmpty(flags.callerAgent) ??
+        nonEmpty(fromJson.agent) ??
+        nonEmpty(env[exports.HANDOFF_ENV_VARS.agent]);
+    const model = nonEmpty(flags.callerModel) ??
+        nonEmpty(fromJson.model) ??
+        nonEmpty(env[exports.HANDOFF_ENV_VARS.model]);
+    const session = nonEmpty(flags.callerSession) ??
+        nonEmpty(fromJson.session) ??
+        nonEmpty(env[exports.HANDOFF_ENV_VARS.session]);
+    if (!agentRaw && !model && !session) {
+        return { ok: true, handoff: null };
+    }
+    return {
+        ok: true,
+        handoff: {
+            agent: agentRaw ? normalizeAgentKind(agentRaw) : 'unknown',
+            ...(model ? { model } : {}),
+            ...(session ? { session } : {}),
+        },
+    };
+};
+exports.parseHandoff = parseHandoff;
+/** Initiator attribution for a parsed handoff (`human` when absent). */
+const initiatorFor = (handoff) => handoff
+    ? {
+        kind: 'agent',
+        agent: handoff.agent,
+        ...(handoff.model ? { model: handoff.model } : {}),
+    }
+    : { kind: 'human' };
+exports.initiatorFor = initiatorFor;
+//# sourceMappingURL=handoff.js.map

package/dist/cli/handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.js","sourceRoot":"","sources":["../../src/cli/handoff.ts"],"names":[],"mappings":"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"}

package/dist/cli/handoffStore.d.ts

@@ -0,0 +1,24 @@
+import type { CallerHandoff, WorkItemInitiator } from './handoff';
+/**
+ * Durable, owner-only record of the handoff that started a session — the
+ * on-disk counterpart of the in-memory session attribution. Written under
+ * `<projectPath>/.rivet/cli/handoff.json` with `0600` permissions (the same
+ * discipline as the daemon token) because it can carry the caller's chat
+ * session id. That id never leaves this file: work items are stamped with
+ * agent kind and model only, and telemetry never receives it.
+ */
+export declare const SESSION_HANDOFF_VERSION = 1;
+export type SessionHandoffRecord = {
+    version: typeof SESSION_HANDOFF_VERSION;
+    sessionId: string | null;
+    recordedAt: string;
+    initiator: WorkItemInitiator;
+    /** Full handoff, including the chat session id. Null for human starts. */
+    handoff: CallerHandoff | null;
+};
+export declare const sessionHandoffPath: (projectPath: string) => string;
+/** Atomically persist the session-starting handoff, owner-only. */
+export declare const writeSessionHandoff: (projectPath: string, record: Omit<SessionHandoffRecord, "version" | "recordedAt">) => void;
+/** Read the persisted session handoff, or null when missing/corrupt. */
+export declare const readSessionHandoff: (projectPath: string) => SessionHandoffRecord | null;
+//# sourceMappingURL=handoffStore.d.ts.map

package/dist/cli/handoffStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoffStore.d.ts","sourceRoot":"","sources":["../../src/cli/handoffStore.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAElE;;;;;;;GAOG;AAEH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,OAAO,uBAAuB,CAAC;IACxC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,0EAA0E;IAC1E,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;CAC/B,CAAC;AAIF,eAAO,MAAM,kBAAkB,GAAI,aAAa,MAAM,KAAG,MACL,CAAC;AAErD,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,GAC9B,aAAa,MAAM,EACnB,QAAQ,IAAI,CAAC,oBAAoB,EAAE,SAAS,GAAG,YAAY,CAAC,KAC3D,IAmBF,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,GAC7B,aAAa,MAAM,KAClB,oBAAoB,GAAG,IASzB,CAAC"}