feat(cli): runs export + invoke --scaffold + envelope contract test vs cloud (#189)

README.md

@@ -95,6 +95,33 @@ Useful flags: `--input KEY=value` overrides declared persona inputs;
 filesystem with provider data the handler reads. Exit code is 0 when every
 envelope succeeded, 1 when any handler invocation failed.
 
+### Where fixtures come from
+
+The primary path is exporting a **real fire** — the fixture is then cloud's
+exact normalized output, so replay cannot drift from production:
+
+```bash
+agentworkforce runs export <runId> --fixture event.json
+agentworkforce invoke ./persona.json --fixture event.json
+```
+
+(`runs export` reads the captured envelope from the run's
+`/runs/:runId/envelope` endpoint; pass `--agent <deployedName>` to skip the
+workspace-wide run lookup. Runs that predate envelope capture, or whose
+envelope was too large to store, are reported with next steps — oversized
+envelopes are omitted, never truncated.)
+
+Before any real fire exists, scaffold a skeleton:
+
+```bash
+agentworkforce invoke --scaffold github.pull_request.opened --output event.json
+```
+
+The frame is filled in; for provider events the `resource` payload is an
+explicit TODO hole (its shape is decided by adapter normalization + cloud's
+buildEnvelope and shouldn't be guessed). `<type>` is validated against the
+trigger catalog with a warn-don't-block stance.
+
 ## Persona vs agent
 
 A deployable agent is two files. The **persona** says *what the agent is*

packages/cli/src/cli.ts

@@ -72,6 +72,7 @@ import {
 import ora, { type Ora } from 'ora';
 import { runDeploy, runLogin, runLogout } from './deploy-command.js';
 import { runInvoke } from './invoke-command.js';
+import { runRuns } from './runs-command.js';
 import { runDestroy } from './destroy-command.js';
 import { runDeploymentList, runDeploymentLogs } from './list-command.js';
 import {
@@ -258,6 +259,15 @@ Commands:
                         --input KEY=value   override a declared persona input
                         --seed PATH=file    seed the simulated filesystem
                         --workspace <id>    workspace id for the simulated ctx
+                        --scaffold <type>   emit a fixture skeleton for an
+                                            event type instead of running
+                                            (no persona needed)
+  runs export <runId> [flags]
+                      Export the gateway envelope cloud delivered to a run
+                      as a replayable invoke fixture. Flags:
+                        --agent <selector>  agentId/deployedName owning the
+                                            run (otherwise all are checked)
+                        --fixture <file>    write the fixture to a file
   deployments list    List deployed cloud agents in the active workspace.
   deployments logs    Show structured logs for a deployed cloud agent.
   destroy <persona-or-agent-id> [flags]
@@ -4388,6 +4398,11 @@ export async function main(): Promise<void> {
     return;
   }
 
+  if (subcommand === 'runs') {
+    await runRuns(rest);
+    return;
+  }
+
   if (subcommand === 'deployments') {
     const [action, ...extra] = rest;
     if (!action || action === '-h' || action === '--help') {

packages/cli/src/invoke-command.test.ts

@@ -8,6 +8,7 @@ import {
   parseInvokeArgs,
   renderHumanSummary,
   runInvoke,
+  scaffoldFixture,
   type RunInvokeIO
 } from './invoke-command.js';
 import type { SimulationResult } from '@agentworkforce/runtime';
@@ -30,8 +31,8 @@ test('parseInvokeArgs: persona + fixture + repeatable flags', () => {
     '--output',
     './run.json'
   ]);
-  assert.ok(!('help' in parsed));
-  if ('help' in parsed) return;
+  assert.ok(!('help' in parsed) && !('scaffold' in parsed));
+  if ('help' in parsed || 'scaffold' in parsed) return;
   assert.equal(path.basename(parsed.personaPath), 'persona.json');
   assert.equal(path.basename(parsed.fixturePath), 'event.json');
   assert.equal(path.basename(parsed.outputPath ?? ''), 'run.json');
@@ -326,3 +327,81 @@ test('renderHumanSummary: lists runs with status, side-effect count, skips', ()
   assert.match(summary, /error: kaboom/);
   assert.match(summary, /\[skip\] unsupported envelope e9 \(mystery\.event\)/);
 });
+
+// ---------------------------------------------------------------------------
+// --scaffold (workforce#189)
+
+test('parseInvokeArgs: --scaffold needs no persona or fixture', () => {
+  const parsed = parseInvokeArgs(['--scaffold', 'cron.tick', '--output', './event.json']);
+  assert.ok('scaffold' in parsed);
+  if (!('scaffold' in parsed)) return;
+  assert.equal(parsed.scaffold, 'cron.tick');
+  assert.equal(path.basename(parsed.outputPath ?? ''), 'event.json');
+});
+
+test('parseInvokeArgs: --scaffold rejects invoke-only args instead of ignoring them', () => {
+  assert.throws(
+    () => parseInvokeArgs(['./persona.json', '--scaffold', 'cron.tick']),
+    /only accepts --output.*<persona-path>/
+  );
+  assert.throws(
+    () => parseInvokeArgs(['--scaffold', 'cron.tick', '--fixture', './event.json']),
+    /only accepts --output.*--fixture/
+  );
+  assert.throws(
+    () => parseInvokeArgs(['--scaffold', 'cron.tick', '--input', 'FOO=bar', '--seed', '/x=./x.json']),
+    /only accepts --output.*--input, --seed/
+  );
+});
+
+test('scaffoldFixture: cron.tick emits a complete frame with name/cron and no warnings', () => {
+  const { fixture, warnings } = scaffoldFixture('cron.tick');
+  assert.deepEqual(warnings, []);
+  assert.equal(fixture.type, 'cron.tick');
+  assert.ok(typeof fixture.occurredAt === 'string');
+  assert.ok(String(fixture.name).includes('TODO'));
+  assert.ok(typeof fixture.cron === 'string');
+  assert.ok(!('resource' in fixture));
+
+  const named = scaffoldFixture('cron.daily-report');
+  assert.equal(named.fixture.type, 'cron.daily-report');
+});
+
+test('scaffoldFixture: known provider event emits frame + explicit resource TODO hole', () => {
+  const { fixture, warnings } = scaffoldFixture('github.pull_request.opened');
+  assert.deepEqual(warnings, []);
+  assert.equal(fixture.type, 'github.pull_request.opened');
+  const resource = fixture.resource as Record<string, unknown>;
+  assert.ok(String(resource.TODO).includes('runs export'));
+});
+
+test('scaffoldFixture: unknown provider/event warns but never blocks (lintTriggers stance)', () => {
+  const unknownProvider = scaffoldFixture('notaprovider.something');
+  assert.equal(unknownProvider.warnings.length, 1);
+  assert.match(unknownProvider.warnings[0], /not in KNOWN_TRIGGER_CATALOG/);
+  assert.equal(unknownProvider.fixture.type, 'notaprovider.something');
+
+  const unknownEvent = scaffoldFixture('github.not_a_real_event');
+  assert.equal(unknownEvent.warnings.length, 1);
+  assert.match(unknownEvent.warnings[0], /not a known github trigger/);
+});
+
+test('runInvoke --scaffold writes the skeleton and exits clean', async () => {
+  const io = collectingIO();
+  const previousExitCode = process.exitCode;
+  const result = await runInvoke(['--scaffold', 'cron.tick'], io);
+  const exitCode = process.exitCode;
+  process.exitCode = previousExitCode;
+
+  assert.equal(result, undefined);
+  assert.notEqual(exitCode, 1);
+  const skeleton = JSON.parse(io.out.join(''));
+  assert.equal(skeleton.type, 'cron.tick');
+});
+
+test('scaffoldFixture: non-tick cron types are PRESERVED with a warning, never rewritten', () => {
+  const { fixture, warnings } = scaffoldFixture('cron.daily');
+  assert.equal(fixture.type, 'cron.daily');
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0], /preserving requested type "cron.daily"/);
+});

packages/cli/src/invoke-command.ts

@@ -3,6 +3,7 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { bundleStager, preflightPersona } from '@agentworkforce/deploy';
+import { KNOWN_TRIGGER_CATALOG } from '@agentworkforce/persona-kit';
 import {
   simulateInvocation,
   type RawGatewayEnvelope,
@@ -11,6 +12,7 @@ import {
 } from '@agentworkforce/runtime';
 
 export const INVOKE_USAGE = `usage: agentworkforce invoke <persona-path> --fixture <file> [flags]
+       agentworkforce invoke --scaffold <type> [--output <file>]
 
 Simulate an invocation: execute the persona's handler against fixture event
 envelope(s) with every external side effect recorded, NOT executed, and emit
@@ -35,6 +37,10 @@ Flags:
                            /slack/channels/_index.json).
   --workspace <id>         Workspace id for the simulated ctx; defaults to
                            the first envelope's workspace.
+  --scaffold <type>        Emit a fixture skeleton for an event type instead
+                           of running a persona. Provider payloads are left
+                           as explicit TODO holes; prefer runs export after
+                           a real fire exists.
   -h, --help               Print this message.
 
 Exit code: 0 when every dispatched envelope succeeded, 1 when any handler
@@ -51,14 +57,19 @@ export interface InvokeOptions {
   workspaceId?: string;
 }
 
-export type ParsedInvokeArgs = InvokeOptions | { help: true };
+export type ParsedInvokeArgs =
+  | InvokeOptions
+  | { help: true }
+  | { scaffold: string; outputPath?: string };
 
 /** Parse `invoke` args. Throws on usage errors (caller maps to exit 1). */
 export function parseInvokeArgs(args: readonly string[]): ParsedInvokeArgs {
   let personaPath: string | undefined;
   let fixturePath: string | undefined;
   let outputPath: string | undefined;
   let workspaceId: string | undefined;
+  let scaffoldType: string | undefined;
+  let sawFixture = false;
   const inputs: Record<string, string> = {};
   const seeds: Record<string, string> = {};
 
@@ -67,13 +78,19 @@ export function parseInvokeArgs(args: readonly string[]): ParsedInvokeArgs {
     if (a === '-h' || a === '--help') {
       return { help: true };
     } else if (a === '--fixture') {
+      sawFixture = true;
       fixturePath = expectValue('--fixture', args[++i]);
     } else if (a.startsWith('--fixture=')) {
+      sawFixture = true;
       fixturePath = expectInline('--fixture', a.slice('--fixture='.length));
     } else if (a === '--output') {
       outputPath = expectValue('--output', args[++i]);
     } else if (a.startsWith('--output=')) {
       outputPath = expectInline('--output', a.slice('--output='.length));
+    } else if (a === '--scaffold') {
+      scaffoldType = expectValue('--scaffold', args[++i]);
+    } else if (a.startsWith('--scaffold=')) {
+      scaffoldType = expectInline('--scaffold', a.slice('--scaffold='.length));
     } else if (a === '--workspace') {
       workspaceId = expectValue('--workspace', args[++i]);
     } else if (a.startsWith('--workspace=')) {
@@ -95,6 +112,22 @@ export function parseInvokeArgs(args: readonly string[]): ParsedInvokeArgs {
     }
   }
 
+  if (scaffoldType) {
+    const invalidScaffoldFlags = [
+      sawFixture ? '--fixture' : '',
+      workspaceId ? '--workspace' : '',
+      Object.keys(inputs).length > 0 ? '--input' : '',
+      Object.keys(seeds).length > 0 ? '--seed' : '',
+      personaPath ? '<persona-path>' : ''
+    ].filter(Boolean);
+    if (invalidScaffoldFlags.length > 0) {
+      throw new Error(
+        `invoke: --scaffold only accepts --output; remove ${invalidScaffoldFlags.join(', ')}`
+      );
+    }
+    // Scaffold mode authors a fixture skeleton; no persona/fixture needed.
+    return { scaffold: scaffoldType, ...(outputPath ? { outputPath: path.resolve(outputPath) } : {}) };
+  }
   if (!personaPath) {
     throw new Error('invoke: missing persona path. Usage: agentworkforce invoke <persona-path> --fixture <file>');
   }
@@ -261,6 +294,18 @@ export async function runInvoke(
     io.stdout(INVOKE_USAGE);
     return undefined;
   }
+  if ('scaffold' in opts) {
+    const { fixture, warnings } = scaffoldFixture(opts.scaffold);
+    for (const warning of warnings) io.stderr(`warn: ${warning}\n`);
+    const text = `${JSON.stringify(fixture, null, 2)}\n`;
+    if (opts.outputPath) {
+      await writeFile(opts.outputPath, text, 'utf8');
+      io.stderr(`fixture skeleton written to ${opts.outputPath}\n`);
+    } else {
+      io.stdout(text);
+    }
+    return undefined;
+  }
 
   try {
     return await runInvokeWithOptions(opts, io);
@@ -369,3 +414,86 @@ export function renderHumanSummary(result: SimulationResult): string {
   }
   return `${lines.join('\n')}\n`;
 }
+
+/**
+ * Cold-start fixture authoring (workforce#189): emit a RawGatewayEnvelope
+ * skeleton for an event type before any real fire exists. The frame is
+ * filled in; for provider events the `resource` payload shape is decided by
+ * adapter normalization + cloud's buildEnvelope and CANNOT be guessed here,
+ * so it is left as an explicit TODO hole — prefer
+ * `agentworkforce runs export <runId> --fixture …` once a real fire exists.
+ *
+ * `<type>` is validated against KNOWN_TRIGGER_CATALOG with the same
+ * warn-don't-block stance as lintTriggers.
+ */
+export function scaffoldFixture(type: string): {
+  fixture: Record<string, unknown>;
+  warnings: string[];
+} {
+  const warnings: string[] = [];
+  const occurredAt = new Date().toISOString();
+
+  if (type === 'cron.tick' || type.startsWith('cron.')) {
+    if (type !== 'cron.tick') {
+      // Preserve what was asked for (a silent rewrite would scaffold a
+      // DIFFERENT event type than requested) but warn: the gateway
+      // delivers schedule fires as `cron.tick`, and the runner shim
+      // treats any `cron.*` as a cron event.
+      warnings.push(
+        `the gateway delivers schedule fires as "cron.tick"; preserving requested type "${type}" (the runner shim still dispatches any cron.* as a cron event)`
+      );
+    }
+    return {
+      fixture: {
+        id: 'evt_local_1',
+        workspace: 'ws-local',
+        type,
+        occurredAt,
+        name: 'TODO: your schedule name (persona schedules[].name)',
+        cron: '0 9 * * 1'
+      },
+      warnings
+    };
+  }
+
+  const firstDot = type.indexOf('.');
+  const provider = firstDot > 0 ? type.slice(0, firstDot) : '';
+  const eventName = firstDot > 0 ? type.slice(firstDot + 1) : '';
+  if (!provider || !eventName) {
+    warnings.push(
+      `"${type}" is not a recognized envelope type shape (expected "cron.tick" or "<provider>.<event>"); emitting a provider-style skeleton anyway`
+    );
+  } else {
+    const catalog = KNOWN_TRIGGER_CATALOG as Record<string, unknown>;
+    const events = catalog[provider];
+    if (events === undefined) {
+      warnings.push(
+        `provider "${provider}" is not in KNOWN_TRIGGER_CATALOG (known: ${Object.keys(catalog).join(', ')}); scaffolding anyway`
+      );
+    } else {
+      const known = Array.isArray(events)
+        ? events.includes(eventName)
+        : typeof events === 'object' && events !== null && eventName in (events as Record<string, unknown>);
+      if (!known) {
+        warnings.push(
+          `event "${eventName}" is not a known ${provider} trigger in KNOWN_TRIGGER_CATALOG; scaffolding anyway`
+        );
+      }
+    }
+  }
+
+  return {
+    fixture: {
+      id: 'evt_local_1',
+      workspace: 'ws-local',
+      type,
+      occurredAt,
+      resource: {
+        TODO:
+          'the provider payload shape is decided by adapter normalization + cloud buildEnvelope; ' +
+          'export a real fire with `agentworkforce runs export <runId> --fixture event.json` to get the exact shape'
+      }
+    },
+    warnings
+  };
+}