agent-relay 12.2.3 → 12.2.4

package/dist/cli/commands/product-surfaces.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Mount the Relay product CLIs as `agent-relay` command groups.
+ *
+ * `file` -> relayfile, `flows` -> relayflows, `sessions` -> relayhistory.
+ * Each product ships its own {@link RelayCliSurface}; this module only says
+ * which package backs which group. Command behaviour lives in the product
+ * repos, and `mountRelayCliSurface` does the generic wiring.
+ */
+import type { Command } from 'commander';
+import { type RelayCliSurface } from '@agent-relay/cli-surface';
+import { type RelayCliSurfaceDependencies } from '../lib/relay-cli-surface.js';
+/** How one product group is mounted. */
+export interface ProductSurfaceDefinition {
+    /** Group name under `agent-relay`. */
+    as: string;
+    /** One-line description for `agent-relay --help`. */
+    description: string;
+    /**
+     * Package subpath exporting `createRelayCliSurface`.
+     *
+     * Imported lazily, so an `agent-relay` invocation that never touches this
+     * group never pays to load the product SDK.
+     */
+    specifier: string;
+    /** Additional group names reaching the same surface, hidden from help. */
+    hiddenAliases?: readonly string[];
+    /**
+     * Options handed to the product's `createRelayCliSurface`.
+     *
+     * `sessions` uses this to pass a Relayhistory cloud client, which makes the
+     * product's `cloud …` commands appear. Resolved lazily alongside the import,
+     * so building a client costs nothing until the group is used.
+     */
+    createOptions?: () => unknown | Promise<unknown>;
+    /**
+     * Optionally widen the product surface before mounting.
+     *
+     * `sessions` uses this to compose relayhistory's local commands with its
+     * cloud client, so the user sees one tree rather than our package split.
+     */
+    extend?: (base: RelayCliSurface) => Promise<RelayCliSurface> | RelayCliSurface;
+}
+/** Injectable import hook, so tests can mount fakes without publishing packages. */
+export interface ProductSurfaceDependencies extends RelayCliSurfaceDependencies {
+    importModule: (specifier: string) => Promise<unknown>;
+}
+/** The product groups `agent-relay` mounts. */
+export declare const PRODUCT_SURFACES: readonly ProductSurfaceDefinition[];
+/**
+ * Import a product's surface and prepare it for mounting.
+ *
+ * @param definition - The group being loaded.
+ * @param deps - Import hook and output sink.
+ * @returns The surface, extended when the definition asks for it.
+ * @throws With an actionable message when the package is missing, too old, or
+ *   does not export the expected factory.
+ */
+export declare function loadProductSurface(definition: ProductSurfaceDefinition, deps: ProductSurfaceDependencies): Promise<RelayCliSurface>;
+/**
+ * Register every product group on the root program.
+ *
+ * @param program - The root commander program.
+ * @param overrides - Test seams for import, io, and exit.
+ * @param definitions - Groups to mount; defaults to {@link PRODUCT_SURFACES}.
+ */
+export declare function registerProductSurfaceCommands(program: Command, overrides?: Partial<ProductSurfaceDependencies>, definitions?: readonly ProductSurfaceDefinition[]): void;
+//# sourceMappingURL=product-surfaces.d.ts.map

package/dist/cli/commands/product-surfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-surfaces.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/product-surfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAoC,KAAK,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAMlG,OAAO,EAAwB,KAAK,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAErG,wCAAwC;AACxC,MAAM,WAAW,wBAAwB;IACvC,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;CAChF;AAOD,oFAAoF;AACpF,MAAM,WAAW,0BAA2B,SAAQ,2BAA2B;IAC7E,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAqBD,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,EAAE,SAAS,wBAAwB,EAqB/D,CAAC;AA+EF;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,wBAAwB,EACpC,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,eAAe,CAAC,CAkB1B;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,OAAO,EAChB,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,EACnD,WAAW,GAAE,SAAS,wBAAwB,EAAqB,GAClE,IAAI,CAmBN"}

package/dist/cli/commands/product-surfaces.js

@@ -0,0 +1,165 @@
+/**
+ * Mount the Relay product CLIs as `agent-relay` command groups.
+ *
+ * `file` -> relayfile, `flows` -> relayflows, `sessions` -> relayhistory.
+ * Each product ships its own {@link RelayCliSurface}; this module only says
+ * which package backs which group. Command behaviour lives in the product
+ * repos, and `mountRelayCliSurface` does the generic wiring.
+ */
+import { composeSurfaces } from '@agent-relay/cli-surface';
+import { describeError } from '../lib/describe-error.js';
+import { redactCredentialValues } from '@agent-relay/cloud/redact';
+import { defaultExit } from '../lib/exit.js';
+import { mountRelayCliSurface } from '../lib/relay-cli-surface.js';
+/**
+ * The real process streams, with credentials masked on stderr.
+ *
+ * Commander's own parse errors are already redacted, but a mounted product
+ * writes through the injected sink, so its diagnostics would bypass that and
+ * echo a credential a user put in argv. Only stderr is masked: stdout is the
+ * data the caller asked for, it can be binary (`file export --format tar
+ * --output -`), and rewriting it would corrupt the payload.
+ */
+function processIo() {
+    return {
+        stdout: (chunk) => process.stdout.write(chunk),
+        // Bytes pass through untouched — there is nothing to mask in a binary
+        // chunk, and decoding one to scan it would corrupt what gets written.
+        stderr: (chunk) => process.stderr.write(typeof chunk === 'string' ? redactCredentialValues(chunk) : chunk),
+    };
+}
+/** The product groups `agent-relay` mounts. */
+export const PRODUCT_SURFACES = [
+    {
+        as: 'file',
+        description: 'relayfile — read and write provider files through a local mount',
+        specifier: '@relayfile/sdk/relay-cli',
+    },
+    {
+        as: 'flows',
+        description: 'relayflows — author, check, run, and deploy agent workflows',
+        specifier: '@relayflows/sdk/relay-cli',
+    },
+    {
+        as: 'sessions',
+        description: 'Relay session history — search, replay, and export past sessions',
+        specifier: 'ai-hist/relay-cli',
+        // `agent-relay session replay` predates this group and still works; it is
+        // hidden so help shows one name for one thing.
+        hiddenAliases: ['session'],
+        createOptions: createSessionsSurfaceOptions,
+        extend: composeSessionReplay,
+    },
+];
+/**
+ * Specifier for the optional cloud client.
+ *
+ * Indirected through a variable on purpose. `@relayhistory/cloud-client` is an
+ * `optionalDependency`, but TypeScript still resolves a literal specifier
+ * inside `await import(...)` and fails the build with TS2307 wherever the
+ * package is absent — which is every CI runner until it is published. The
+ * try/catch already covers its runtime absence; this covers compile time.
+ */
+const RELAYHISTORY_CLOUD_CLIENT = '@relayhistory/cloud-client';
+/**
+ * Build the Relayhistory cloud client that unlocks `sessions cloud …`.
+ *
+ * Returns no client when Relayhistory is not configured: ai-hist then drops
+ * those commands from its declared tree, so help never advertises something
+ * that cannot run.
+ */
+async function createSessionsSurfaceOptions() {
+    const { readStoredRelayhistoryAuth, resolveRelayhistoryConfig } = await import('./session.js');
+    const { baseUrl, token } = resolveRelayhistoryConfig(readStoredRelayhistoryAuth());
+    if (!baseUrl || !token)
+        return {};
+    try {
+        const module = (await import(RELAYHISTORY_CLOUD_CLIENT));
+        return { cloud: module.createRelayhistoryCloudClient({ baseUrl, token }) };
+    }
+    catch {
+        // The cloud client is optional: without it the local half still mounts,
+        // which is strictly better than failing the whole group.
+        return {};
+    }
+}
+/** Compose Relay's own `replay` into the session history tree. */
+async function composeSessionReplay(base) {
+    const { createSessionReplaySurface } = await import('./session.js');
+    return composeSurfaces({
+        id: base.id,
+        version: base.version,
+        parts: [base, createSessionReplaySurface(base.version)],
+    });
+}
+/**
+ * Explain an import failure in terms the operator can act on.
+ *
+ * A missing subpath export is the common case while a product is mid-upgrade,
+ * and the raw `ERR_PACKAGE_PATH_NOT_EXPORTED` text does not say which package
+ * to update.
+ */
+function describeLoadFailure(definition, error) {
+    const code = error?.code;
+    const packageName = definition.specifier
+        .split('/')
+        .slice(0, definition.specifier.startsWith('@') ? 2 : 1)
+        .join('/');
+    if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') {
+        return (`\`agent-relay ${definition.as}\` needs ${packageName}, which is not installed.\n` +
+            `Reinstall agent-relay, or install ${packageName} alongside it.`);
+    }
+    if (code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+        return (`The installed ${packageName} is too old for \`agent-relay ${definition.as}\`: ` +
+            `it does not export ${definition.specifier}.\nUpgrade ${packageName} and retry.`);
+    }
+    return `Could not load \`agent-relay ${definition.as}\` from ${definition.specifier}: ${describeError(error)}`;
+}
+/**
+ * Import a product's surface and prepare it for mounting.
+ *
+ * @param definition - The group being loaded.
+ * @param deps - Import hook and output sink.
+ * @returns The surface, extended when the definition asks for it.
+ * @throws With an actionable message when the package is missing, too old, or
+ *   does not export the expected factory.
+ */
+export async function loadProductSurface(definition, deps) {
+    let module;
+    try {
+        module = (await deps.importModule(definition.specifier));
+    }
+    catch (error) {
+        throw new Error(describeLoadFailure(definition, error));
+    }
+    if (typeof module.createRelayCliSurface !== 'function') {
+        throw new Error(`${definition.specifier} does not export createRelayCliSurface(). ` +
+            `\`agent-relay ${definition.as}\` cannot be mounted.`);
+    }
+    const options = definition.createOptions ? await definition.createOptions() : undefined;
+    const base = module.createRelayCliSurface(options);
+    return definition.extend ? await definition.extend(base) : base;
+}
+/**
+ * Register every product group on the root program.
+ *
+ * @param program - The root commander program.
+ * @param overrides - Test seams for import, io, and exit.
+ * @param definitions - Groups to mount; defaults to {@link PRODUCT_SURFACES}.
+ */
+export function registerProductSurfaceCommands(program, overrides = {}, definitions = PRODUCT_SURFACES) {
+    const deps = {
+        importModule: overrides.importModule ?? ((specifier) => import(specifier)),
+        io: overrides.io ?? processIo(),
+        exit: overrides.exit ?? defaultExit,
+    };
+    for (const definition of definitions) {
+        mountRelayCliSurface(program, {
+            as: definition.as,
+            description: definition.description,
+            ...(definition.hiddenAliases ? { hiddenAliases: definition.hiddenAliases } : {}),
+            load: () => loadProductSurface(definition, deps),
+        }, deps);
+    }
+}
+//# sourceMappingURL=product-surfaces.js.map

package/dist/cli/commands/product-surfaces.js.map

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

package/dist/cli/commands/session.d.ts

@@ -1,3 +1,4 @@
+import type { RelayCliSurface } from '@agent-relay/cli-surface';
 import { type ReplaySessionResult } from '@agent-relay/session';
 import { Command } from 'commander';
 export interface SessionReplayClient {
@@ -15,6 +16,8 @@ export interface SessionCommandDependencies {
     error: (...args: unknown[]) => void;
     exit: (code: number) => never;
 }
+/** Exported so the mounted `sessions` group can build a cloud client from the same credentials. */
+export declare function readStoredRelayhistoryAuth(): StoredRelayhistoryAuth | null;
 /** Exported for direct unit coverage of the local-vs-production host allowlist. */
 export declare function trustedStoredBaseUrl(value: string): string | undefined;
 /**
@@ -37,4 +40,18 @@ export declare function resolveRelaycastConfig(persistedWorkspaceKey?: string):
 };
 /** Register durable completed-session replay joined across Relayhistory and Relaycast. */
 export declare function registerSessionCommands(program: Command, overrides?: Partial<SessionCommandDependencies>): void;
+/**
+ * Session replay as a mountable surface part.
+ *
+ * `agent-relay sessions` is one tree spanning three owners: ai-hist's local
+ * history, its cloud client, and this — replay, which joins Relayhistory turns
+ * with Relaycast conversation. Replay stays in this repo because Relaycast is
+ * Relay's own surface, not something ai-hist should learn about; composing it
+ * keeps the package boundary out of the user's command line.
+ *
+ * @param version - Version to report, normally the surface it composes with.
+ * @param overrides - Same dependency seams as the commander registration.
+ * @returns A single-command surface providing `replay`.
+ */
+export declare function createSessionReplaySurface(version: string, overrides?: Partial<SessionCommandDependencies>): RelayCliSurface;
 //# sourceMappingURL=session.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/session.ts"],"names":[],"mappings":"AAIA,OAAO,EAAiB,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAwB,MAAM,WAAW,CAAC;AAW1D,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,CAAC,UAAU,EAAE,sBAAsB,GAAG,IAAI,KAAK,mBAAmB,CAAC;IACjF,cAAc,EAAE,MAAM,sBAAsB,GAAG,IAAI,CAAC;IACpD,mBAAmB,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAC9C,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAClC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC;CAC/B;AAoBD,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CActE;AAUD;;;;;;;GAOG;AACH,yFAAyF;AACzF,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,sBAAsB,GAAG,IAAI,GAAG;IACpF,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B,CAKA;AAED,iGAAiG;AACjG,wBAAgB,sBAAsB,CAAC,qBAAqB,CAAC,EAAE,MAAM,GAAG;IACtE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAOA;AAiCD,0FAA0F;AAC1F,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,IAAI,CA+BN"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/session.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAc,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAiB,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAwB,MAAM,WAAW,CAAC;AAW1D,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,CAAC,UAAU,EAAE,sBAAsB,GAAG,IAAI,KAAK,mBAAmB,CAAC;IACjF,cAAc,EAAE,MAAM,sBAAsB,GAAG,IAAI,CAAC;IACpD,mBAAmB,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAC9C,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAClC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC;CAC/B;AAED,mGAAmG;AACnG,wBAAgB,0BAA0B,IAAI,sBAAsB,GAAG,IAAI,CAgB1E;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CActE;AAUD;;;;;;;GAOG;AACH,yFAAyF;AACzF,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,sBAAsB,GAAG,IAAI,GAAG;IACpF,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B,CAKA;AAED,iGAAiG;AACjG,wBAAgB,sBAAsB,CAAC,qBAAqB,CAAC,EAAE,MAAM,GAAG;IACtE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAOA;AAiCD,0FAA0F;AAC1F,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,IAAI,CA+BN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,eAAe,CAwDjB"}

package/dist/cli/commands/session.js

@@ -10,7 +10,8 @@ const SESSION_REF_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-
 const ALLOWED_RELAYHISTORY_HOST = 'history.agentrelay.com';
 /** Same fallback chain `@agent-relay/session`'s `SessionClient` resolves a token from. */
 const RELAYHISTORY_TOKEN_ENV_VARS = ['RELAYHISTORY_TOKEN', 'RELAYHISTORY_ACCESS_TOKEN', 'RELAY_AGENT_TOKEN'];
-function readStoredRelayhistoryAuth() {
+/** Exported so the mounted `sessions` group can build a cloud client from the same credentials. */
+export function readStoredRelayhistoryAuth() {
     try {
         const authDir = process.env.RELAYHISTORY_HOME ?? path.join(os.homedir(), '.agentworkforce', 'relayhistory');
         const parsed = JSON.parse(fs.readFileSync(path.join(authDir, 'auth.json'), 'utf8'));
@@ -129,4 +130,67 @@ export function registerSessionCommands(program, overrides = {}) {
         deps.log(replay.contextPrompt);
     });
 }
+/**
+ * Session replay as a mountable surface part.
+ *
+ * `agent-relay sessions` is one tree spanning three owners: ai-hist's local
+ * history, its cloud client, and this — replay, which joins Relayhistory turns
+ * with Relaycast conversation. Replay stays in this repo because Relaycast is
+ * Relay's own surface, not something ai-hist should learn about; composing it
+ * keeps the package boundary out of the user's command line.
+ *
+ * @param version - Version to report, normally the surface it composes with.
+ * @param overrides - Same dependency seams as the commander registration.
+ * @returns A single-command surface providing `replay`.
+ */
+export function createSessionReplaySurface(version, overrides = {}) {
+    const deps = withDefaults(overrides);
+    return {
+        id: 'relay-session-replay',
+        version,
+        contract: 1,
+        commands: [
+            {
+                name: 'replay',
+                description: 'Reconstruct a completed Relay session from Relayhistory and Relaycast',
+                args: [{ name: 'id', description: 'Relay-emitted session UUID', required: true }],
+            },
+        ],
+        async run(argv, io) {
+            const [, rawId, ...rest] = ['replay', ...argv.slice(1)];
+            if (rest.length > 0) {
+                io.stderr(`error: unexpected argument '${rest[0]}'\n`);
+                return 2;
+            }
+            if (!rawId) {
+                io.stderr("error: missing required argument 'id'\n");
+                return 2;
+            }
+            let sessionId;
+            try {
+                sessionId = parseSessionRef(rawId);
+            }
+            catch (error) {
+                io.stderr(`error: ${error instanceof Error ? error.message : String(error)}\n`);
+                return 2;
+            }
+            const storedAuth = deps.readStoredAuth();
+            const config = resolveRelayhistoryConfig(storedAuth);
+            if (!config.baseUrl) {
+                io.stderr('No Relayhistory endpoint is configured. Set RELAYHISTORY_URL, or sign in so ' +
+                    '~/.agentworkforce/relayhistory/auth.json has a base_url.\n');
+                return 1;
+            }
+            if (!config.token) {
+                io.stderr('No Relayhistory credential is configured. Set RELAYHISTORY_TOKEN ' +
+                    '(or RELAYHISTORY_ACCESS_TOKEN/RELAY_AGENT_TOKEN), or sign in so ' +
+                    '~/.agentworkforce/relayhistory/auth.json has an access_token.\n');
+                return 1;
+            }
+            const replay = await deps.createClient(storedAuth).replaySession(sessionId);
+            io.stdout(`${replay.contextPrompt}\n`);
+            return 0;
+        },
+    };
+}
 //# sourceMappingURL=session.js.map

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

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

package/dist/cli/lib/deprecate-command.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Mark existing commander commands as deprecated without changing what they do.
+ *
+ * Used for the v1 relayflows commands under `agent-relay cloud`, which are
+ * superseded by the v2 `agent-relay flows` surface. The agreed behaviour is
+ * "keep working, warn, hide": scripts that call them today keep passing, the
+ * operator is told what to move to, and new users never discover v1 from
+ * `--help`.
+ *
+ * Hiding goes through commander's public `configureHelp({ visibleCommands })`
+ * rather than the private `_hidden` field, so a commander upgrade cannot
+ * silently un-hide the v1 surface.
+ */
+import { type Command } from 'commander';
+/** Where a deprecated command's callers should go instead. */
+export interface DeprecationNotice {
+    /**
+     * Replacement invocation, e.g. `agent-relay flows run`.
+     *
+     * Omit when nothing replaces the command yet. Several v1 relayflows commands
+     * (schedule, logs, cancel) have no v2 equivalent, and inventing a pointer to
+     * a command that does not exist is worse than admitting the gap.
+     */
+    replacement?: string;
+    /** Version the deprecation took effect. */
+    since: string;
+    /**
+     * Extra guidance appended to the warning.
+     *
+     * Set this when the replacement is not a drop-in — a v1 command whose v2
+     * equivalent takes different arguments needs to say so, or the pointer is
+     * worse than no pointer.
+     */
+    note?: string;
+    /**
+     * Keep the command listed in `--help` (default: hide it).
+     *
+     * Hiding is right for a command with a replacement. A command that is still
+     * the only way to do its job must stay discoverable even while deprecated,
+     * or we strand the people relying on it.
+     */
+    keepVisible?: boolean;
+}
+/** Injectable warning sink; defaults to the real stderr. */
+export interface DeprecationDependencies {
+    warn: (message: string) => void;
+}
+/**
+ * Render the stderr notice for a deprecated command.
+ *
+ * @param invocation - How the user reached the command, e.g. `agent-relay cloud run`.
+ * @param notice - Replacement and guidance.
+ * @returns The warning text, newline-terminated.
+ */
+export declare function formatDeprecationWarning(invocation: string, notice: DeprecationNotice): string;
+/**
+ * Attach a deprecation warning to one command and hide it from its parent's help.
+ *
+ * The command's action is untouched: it still runs, and still returns whatever
+ * it returned before.
+ *
+ * @param command - The command to deprecate. Must already be attached to a parent.
+ * @param notice - Replacement and guidance.
+ * @param overrides - Test seam for the warning sink.
+ * @throws When the command has no parent, since there is then no help to hide it from.
+ */
+export declare function deprecateCommand(command: Command, notice: DeprecationNotice, overrides?: Partial<DeprecationDependencies>): void;
+/**
+ * Read back the names hidden from a parent's help.
+ *
+ * Exported for tests; production code has no reason to ask.
+ */
+export declare function hiddenCommandNames(parent: Command): readonly string[];
+//# sourceMappingURL=deprecate-command.d.ts.map

package/dist/cli/lib/deprecate-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecate-command.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/deprecate-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAQ,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAE/C,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,4DAA4D;AAC5D,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAe9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,iBAAiB,EACzB,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,IAAI,CAoBN;AAwCD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAErE"}

package/dist/cli/lib/deprecate-command.js

@@ -0,0 +1,107 @@
+/**
+ * Mark existing commander commands as deprecated without changing what they do.
+ *
+ * Used for the v1 relayflows commands under `agent-relay cloud`, which are
+ * superseded by the v2 `agent-relay flows` surface. The agreed behaviour is
+ * "keep working, warn, hide": scripts that call them today keep passing, the
+ * operator is told what to move to, and new users never discover v1 from
+ * `--help`.
+ *
+ * Hiding goes through commander's public `configureHelp({ visibleCommands })`
+ * rather than the private `_hidden` field, so a commander upgrade cannot
+ * silently un-hide the v1 surface.
+ */
+import { Help } from 'commander';
+/**
+ * Render the stderr notice for a deprecated command.
+ *
+ * @param invocation - How the user reached the command, e.g. `agent-relay cloud run`.
+ * @param notice - Replacement and guidance.
+ * @returns The warning text, newline-terminated.
+ */
+export function formatDeprecationWarning(invocation, notice) {
+    const lines = [
+        `warning: \`${invocation}\` is deprecated since ${notice.since} and will be removed in a future release.`,
+    ];
+    if (notice.replacement) {
+        lines.push(`         Use \`${notice.replacement}\` instead.`);
+        if (notice.note)
+            lines.push(`         ${notice.note}`);
+    }
+    else {
+        // A specific note about why there is no replacement beats the generic
+        // line; printing both just says the same thing twice.
+        lines.push(`         ${notice.note ?? 'No replacement is available yet; it remains supported until one ships.'}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Attach a deprecation warning to one command and hide it from its parent's help.
+ *
+ * The command's action is untouched: it still runs, and still returns whatever
+ * it returned before.
+ *
+ * @param command - The command to deprecate. Must already be attached to a parent.
+ * @param notice - Replacement and guidance.
+ * @param overrides - Test seam for the warning sink.
+ * @throws When the command has no parent, since there is then no help to hide it from.
+ */
+export function deprecateCommand(command, notice, overrides = {}) {
+    const warn = overrides.warn ?? ((message) => process.stderr.write(message));
+    const parent = command.parent;
+    if (!parent) {
+        throw new Error(`cannot deprecate '${command.name()}': it is not attached to a parent command`);
+    }
+    // Keep the text accurate for anyone who reaches help another way (`--help`
+    // on the command itself still prints its own description).
+    command.description(notice.replacement
+        ? `${command.description()} (deprecated — use \`${notice.replacement}\`)`
+        : `${command.description()} (deprecated)`);
+    command.hook('preAction', () => {
+        warn(formatDeprecationWarning(invocationPath(command), notice));
+    });
+    if (!notice.keepVisible)
+        hideFromParentHelp(parent, command.name());
+}
+/** Build the full invocation path for a command, e.g. `agent-relay cloud run`. */
+function invocationPath(command) {
+    const names = [];
+    let cursor = command;
+    while (cursor) {
+        names.unshift(cursor.name());
+        cursor = cursor.parent;
+    }
+    return names.join(' ');
+}
+/** Command names hidden from each parent's help, keyed by the parent command. */
+const hiddenByParent = new WeakMap();
+/**
+ * Hide one subcommand name from a parent's help listing.
+ *
+ * Idempotent, and safe to call for several children of the same parent: the
+ * help override is installed once and consults a growing name set.
+ */
+function hideFromParentHelp(parent, name) {
+    const existing = hiddenByParent.get(parent);
+    if (existing) {
+        existing.add(name);
+        return;
+    }
+    const hidden = new Set([name]);
+    hiddenByParent.set(parent, hidden);
+    // Delegate to commander's own visibility rules, then subtract. Reimplementing
+    // the filter would drop its handling of the built-in help command.
+    const base = new Help();
+    parent.configureHelp({
+        visibleCommands: (cmd) => base.visibleCommands(cmd).filter((child) => !hidden.has(child.name())),
+    });
+}
+/**
+ * Read back the names hidden from a parent's help.
+ *
+ * Exported for tests; production code has no reason to ask.
+ */
+export function hiddenCommandNames(parent) {
+    return [...(hiddenByParent.get(parent) ?? [])];
+}
+//# sourceMappingURL=deprecate-command.js.map

package/dist/cli/lib/deprecate-command.js.map

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