Wrap launcher programs in a workflow run for top-level phase/log

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Author: Copilot

skills/rig/SKILL.md

@@ -62,6 +62,7 @@ Defaults: `name: "agent"`, `model: "small"`, `maxTurns: 4`, string input/output,
 | Deterministic TypeScript fan-out | `workflow({ meta, input?, body })` + `export default`; use `call`, `pipeline`, `parallel`, `until` inside `body` |
 | One-off prompt inside a workflow | `call.text(prompt)` for a string, `call.json(prompt, schema)` for structured output |
 | Reusable workflow step | Define an `agent({ input, output })` and `call(worker, input, { label, phase })` |
+| Phase or log from an agent program | Import `phase` / `log` from `rig` and call them at top level; the launcher runs every program inside a workflow |
 | Custom model-callable operation | `defineTool(name, { description, parameters, handler })` |
 | Structured-output retries | `maxTurns` on the agent plus `addons: [repair()]` |
 | Retry with final-turn warning | `addons: [steering(), repair()]` in that order |

skills/rig/references/claude-workflow-conversion.md

@@ -34,6 +34,11 @@ primitives from its context instead of from globals.
 | top-level `return value` | `return value` from `body` | Same |
 | `Workflow({ scriptPath, args })` from a session | `cat args.json \| node skills/rig/rig.ts program.ts` | See [runtime](runtime.md) |
 
+Globals such as `phase` and `log` also exist as module-level imports from `rig`.
+The launcher runs every program — including one whose root export is an `agent` —
+inside a workflow run, so a partially ported script can call `phase()` and `log()`
+at top level before the orchestration itself moves into `workflow({ body })`.
+
 ## Schema conversion
 
 Dynamic workflows pass OpenAI-strict JSON Schema literals. rig schemas are

skills/rig/references/dynamic-workflows.md

@@ -77,6 +77,28 @@ export default linter;
 - Omit `input` for a no-input program (inline mode) or add `input: s.object({ ... })` for file-mode programs that read stdin JSON.
 - Use `agent()` with `agents:` when an LLM should improvise the coordination order. Use `workflow()` when TypeScript owns the orchestration (fan-out, branching, convergence).
 
+## Top-level constructs in agent programs
+
+The launcher runs every program inside a workflow run, including programs whose
+root export is an `agent`, a string, or a prompt builder. Module evaluation
+happens inside that run, so `phase()` and `log()` imported from `rig` work at the
+program's top level without declaring a `workflow()`:
+
+```ts
+import { agent, log, phase } from "rig";
+
+phase("Review");
+log("reviewing the staged diff");
+
+export default agent({ instructions: "Review the staged diff." });
+```
+
+`currentWorkflow()` returns the active run context (`call`, `budget`, `signal`,
+`phase`, `log`) or `undefined` outside a run; `phase()` and `log()` are no-ops
+outside a run. A `workflow()` default export is nested into the same run, so it
+shares the launcher's limiter, budget, and event stream instead of starting a
+second run.
+
 ## Context
 
 | Member | Behavior |

skills/rig/references/runtime.md

@@ -39,6 +39,12 @@ Stdin coercion follows the root schema:
 
 The launcher writes string results, or the string `text` field of an object result, directly to stdout. It JSON-serializes other results.
 
+Both modes evaluate the program and run its root inside a workflow run, so
+top-level `phase()` and `log()` work in any program and `currentWorkflow()` is
+defined from module scope. A `workflow` default export nests into that run
+instead of starting a second one. Run events are emitted under the
+`workflow:event` debug category.
+
 Add `--server` in either mode to start the Copilot server over stdio and force the Copilot engine. Without it, `copilotEngine()` connects over HTTP using `COPILOT_SDK_URI`, then `localhost:7777`.
 
 Use `--help`, `-h`, `help`, `/help`, or `/?` to print launcher usage.

skills/rig/rig.ts

@@ -98,6 +98,7 @@ import { writeSync } from "node:fs";
 import { access, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { CopilotClient, RuntimeConnection, approveAll } from "@github/copilot-sdk";
 import type { CopilotClientOptions } from "@github/copilot-sdk";
 
@@ -694,6 +695,7 @@ const debugAgentComplete = debug("agent:complete");
 const debugAgentRetry = debug("agent:retry");
 const debugAgentFailure = debug("agent:failure");
 const debugAgentClose = debug("agent:close");
+const debugWorkflowEvent = debug("workflow:event");
 
 export type AgentAddonContext = {
   spec: NormalizedAgentSpec<any, any>;
@@ -1454,7 +1456,9 @@ export async function launchRigProgram(programPath: string, options: LaunchOptio
   const resolvedPath = isAbsolute(programPath) ? programPath : resolve(cwd, programPath);
 
   configureAgent(defaultAgentFactory({ cwd, ...(options.startServer ? { startServer: true } : {}) }));
-  await import(pathToFileURL(resolvedPath).href);
+  await runInRootWorkflow("launcher-program", async () => {
+    await import(pathToFileURL(resolvedPath).href);
+  });
 }
 
 async function readStdin(stream: NodeJS.ReadableStream): Promise<string> {
@@ -1506,7 +1510,12 @@ function asRootProgram(value: unknown, name: string): AgentFn | undefined {
     const hasInput = "inputSchema" in w;
     const inputSchema: Schema = hasInput ? (w.inputSchema as Schema) : defaultStringSchema;
     const fn = Object.assign(
-      async (input: unknown) => runWorkflow(w, hasInput ? { args: input } : {}),
+      async (input: unknown) => {
+        const args = hasInput ? input : undefined;
+        const ambient = currentWorkflow();
+        // Nest into the launcher's root run so limits, budget, and events are shared.
+        return ambient ? ambient.call.workflow(w, args) : runWorkflow(w, { args });
+      },
       {
         inputSchema,
         outputSchema: defaultStringSchema as Schema,
@@ -1521,6 +1530,19 @@ function asRootProgram(value: unknown, name: string): AgentFn | undefined {
   return undefined;
 }
 
+/**
+ * Runs a launcher program inside a workflow run so a program that exports an
+ * agent (or a plain prompt) can still use top-level workflow constructs such as
+ * `phase()` and `log()`.  Module evaluation happens inside `body`, so top-level
+ * program statements observe the ambient run too.
+ */
+async function runInRootWorkflow<Output>(name: string, body: () => Promise<Output>): Promise<Output> {
+  return runWorkflow<undefined, Output>(
+    { meta: { name, description: "Rig program root" }, body },
+    { onEvent: (event) => debugWorkflowEvent(event) },
+  );
+}
+
 function noInputInvocation(agentFn: AgentFn): unknown | undefined {
   const schema = agentFn.inputSchema;
   if ("type" in schema && schema.type === "string") {
@@ -1720,13 +1742,14 @@ async function runRootAgentFromStdin(
   }
 
   configureAgent(defaultAgentFactory({ cwd, ...(options.startServer ? { startServer: true } : {}) }));
-  const mod = await import(pathToFileURL(resolvedPath).href);
-  const rootAgent = asRootProgram(mod.default, "launcher-root");
-  if (!rootAgent) {
-    throw new Error("Expected program to export a root value (agent, workflow, string, or prompt builder) as default export.");
-  }
-
-  const result = await rootAgent(coerceStdinInput(rootAgent, prompt));
+  const result = await runInRootWorkflow("launcher-root", async () => {
+    const mod = await import(pathToFileURL(resolvedPath).href);
+    const rootAgent = asRootProgram(mod.default, "launcher-root");
+    if (!rootAgent) {
+      throw new Error("Expected program to export a root value (agent, workflow, string, or prompt builder) as default export.");
+    }
+    return rootAgent(coerceStdinInput(rootAgent, prompt));
+  });
   io.stdout.write(renderStdout(result));
 }
 
@@ -1754,16 +1777,18 @@ async function runProgramCodeFromStdin(
       return;
     }
     configureAgent(defaultAgentFactory({ cwd, ...(options.startServer ? { startServer: true } : {}) }));
-    const mod = await import(pathToFileURL(tempProgramPath).href);
-    const rootAgent = asRootProgram(mod.default, "launcher-inline-root");
-    if (!rootAgent) {
-      throw new Error("Expected program to export a root value (agent, workflow, string, or prompt builder) as default export.");
-    }
-    const input = noInputInvocation(rootAgent);
-    if (input === undefined) {
-      throw new Error("Expected stdin program root agent to have no input (omit input or use input: s.object({})).");
-    }
-    const result = await rootAgent(input);
+    const result = await runInRootWorkflow("launcher-inline-root", async () => {
+      const mod = await import(pathToFileURL(tempProgramPath).href);
+      const rootAgent = asRootProgram(mod.default, "launcher-inline-root");
+      if (!rootAgent) {
+        throw new Error("Expected program to export a root value (agent, workflow, string, or prompt builder) as default export.");
+      }
+      const input = noInputInvocation(rootAgent);
+      if (input === undefined) {
+        throw new Error("Expected stdin program root agent to have no input (omit input or use input: s.object({})).");
+      }
+      return rootAgent(input);
+    });
     io.stdout.write(renderStdout(result));
   } finally {
     await rm(tempDir, { recursive: true, force: true });
@@ -2116,6 +2141,27 @@ export function workflow(
   };
 }
 
+const workflowStore = new AsyncLocalStorage<WorkflowContext<unknown>>();
+
+/**
+ * Returns the context of the innermost active workflow run, or `undefined`
+ * outside a run.  Launcher programs always run inside a workflow, so a rig
+ * program can reach `call`, `budget`, and `signal` from module scope.
+ */
+export function currentWorkflow(): WorkflowContext<unknown> | undefined {
+  return workflowStore.getStore();
+}
+
+/** Sets the ambient phase of the active workflow run.  No-op outside a run. */
+export function phase(name: string): void {
+  currentWorkflow()?.phase(name);
+}
+
+/** Emits a structured log event on the active workflow run.  No-op outside a run. */
+export function log(message: string): void {
+  currentWorkflow()?.log(message);
+}
+
 export type WorkflowLimits = {
   concurrency?: number;
   maxAgents?: number;
@@ -2424,9 +2470,13 @@ export async function runWorkflow<Input, Output>(
   ): Promise<ChildOutput> => {
     const name = nestedOptions.label ?? child.meta.name;
     const outerPhase = currentPhase;
+    const childContext = makeContext(args as ChildInput);
     writeLog(`workflow ${name} started`);
     try {
-      return await child.body(makeContext(args as ChildInput));
+      return await workflowStore.run(
+        childContext as WorkflowContext<unknown>,
+        () => child.body(childContext),
+      );
     } finally {
       currentPhase = outerPhase;
       writeLog(`workflow ${name} finished`);
@@ -2436,7 +2486,9 @@ export async function runWorkflow<Input, Output>(
   const context = makeContext(options.args as Input);
 
   try {
-    const body = Promise.resolve(definition.body(context));
+    const body = Promise.resolve(
+      workflowStore.run(context as WorkflowContext<unknown>, () => definition.body(context)),
+    );
     const output = await (wallLimit === undefined ? body : Promise.race([body, wallLimit]));
     emit({
       type: "run_done",

src/launcher.stdin-ambient.fixture.ts

@@ -0,0 +1,12 @@
+import { agent, currentWorkflow, log, phase } from "rig";
+
+phase("Prepare");
+log("program loaded");
+
+(globalThis as { __launcherAmbientRun?: boolean }).__launcherAmbientRun = currentWorkflow() !== undefined;
+
+const root = agent({
+  name: "launcher-stdin-ambient-root",
+});
+
+export default root;

src/launcher.test.ts

@@ -114,6 +114,24 @@ it("supports stdin mode for string input/output root agents", async () => {
   expect(output.join("")).toBe("done");
 });
 
+it("wraps an agent program in a workflow so top-level constructs work", async () => {
+  const fixturePath = resolve(dirname(fileURLToPath(import.meta.url)), "./launcher.stdin-ambient.fixture.ts");
+  const stdin = Readable.from(["Review this patch"]);
+  const output: string[] = [];
+  const stdout = new Writable({
+    write(chunk, _encoding, callback) {
+      output.push(chunk.toString());
+      callback();
+    },
+  });
+
+  mocks.setSendAndWaitImpl(async () => JSON.stringify("done"));
+  await runLauncherCli([fixturePath], {}, { stdin, stdout });
+
+  expect((globalThis as { __launcherAmbientRun?: boolean }).__launcherAmbientRun).toBe(true);
+  expect(output.join("")).toBe("done");
+});
+
 it("supports stdin mode when root default export is a string", async () => {
   const fixturePath = resolve(dirname(fileURLToPath(import.meta.url)), "./launcher.stdin-default-string.fixture.ts");
   const stdin = Readable.from(["Review this patch"]);

src/workflow.test.ts

@@ -2,6 +2,9 @@ import { describe, expect, it, vi } from "vitest";
 import type { AgentFn, CallOptions } from "rig";
 import {
   configureAgent,
+  currentWorkflow,
+  log,
+  phase,
   WorkflowLimitError,
   parallel,
   runWorkflow,
@@ -290,3 +293,43 @@ describe("workflow one-off agents", () => {
     expect(prompts).toHaveLength(2);
   });
 });
+
+describe("ambient workflow context", () => {
+  it("routes top-level phase and log to the active run", async () => {
+    const worker = fakeAgent<number, number>("worker", (value) => value);
+    const events: WorkflowEvent[] = [];
+    const definition = workflow({
+      meta: { name: "ambient", description: "ambient helpers" },
+      body: async ({ call }) => {
+        phase("Work");
+        log("started");
+        return call(worker, 1);
+      },
+    });
+
+    await expect(runWorkflow(definition, { onEvent: (event) => events.push(event) })).resolves.toBe(1);
+    expect(events.find((event) => event.type === "phase_start")).toMatchObject({ phase: "Work" });
+    expect(events.find((event) => event.type === "log")).toMatchObject({ message: "started", phase: "Work" });
+    expect(events.find((event) => event.type === "agent_start")).toMatchObject({ phase: "Work" });
+  });
+
+  it("exposes the run context through currentWorkflow and clears it afterwards", async () => {
+    const definition = workflow({
+      meta: { name: "context", description: "context lookup" },
+      body: async () => {
+        await Promise.resolve();
+        return currentWorkflow()?.budget.total;
+      },
+    });
+
+    await expect(runWorkflow(definition, { limits: { maxAgents: 7 } })).resolves.toBe(7);
+    expect(currentWorkflow()).toBeUndefined();
+  });
+
+  it("ignores top-level phase and log outside a run", () => {
+    expect(() => {
+      phase("Work");
+      log("no run");
+    }).not.toThrow();
+  });
+});