Skip to content
Closed
204 changes: 204 additions & 0 deletions packages/core/src/agents/runtime/workflow-orchestrator.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@
// T7 (PR #4732 R1): the `vi as vitest` alias diverges from every other
// test file in the repo. Use `vi` directly.
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import * as fsSync from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {
WorkflowOrchestrator,
WorkflowExecutionError,
Expand Down Expand Up @@ -1710,6 +1712,208 @@ describe('createProductionDispatch', () => {
expect(created[0]!.agentId).toMatch(/^workflow-agent-[0-9a-f]{16}$/);
});

// --- per-dispatch transcript ------------------------------------------
//
// Workflow subagents were the only agents in the product that left no
// record on disk. These cases pin the SHAPE, not just the existence of a
// file: a consumer of `<projectDir>/subagents/<sessionId>/` answers "what
// did this agent actually do" by reading the launch prompt out of the
// first record and pairing functionCall/functionResponse by callId. A file
// that exists but carries neither answers nothing.
describe('dispatch transcript', () => {
let projectDir: string;

beforeEach(() => {
projectDir = fsSync.mkdtempSync(path.join(os.tmpdir(), 'wf-tx-'));
});

afterEach(() => {
fsSync.rmSync(projectDir, { recursive: true, force: true });
});

const SESSION = 'sess-transcript-test';

function transcriptConfig(): Config {
return {
storage: { getProjectDir: () => projectDir },
getSessionId: () => SESSION,
getProjectRoot: () => projectDir,
getCliVersion: () => '0.0.0-test',
} as unknown as Config;
}

function transcriptFiles(): string[] {
const dir = path.join(projectDir, 'subagents', SESSION);
if (!fsSync.existsSync(dir)) return [];
return fsSync
.readdirSync(dir)
.filter((f) => f.endsWith('.jsonl'))
.map((f) => path.join(dir, f));
}

function recordsOf(file: string): Array<Record<string, unknown>> {
return fsSync
.readFileSync(file, 'utf8')
.split('\n')
.filter((l) => l.trim())
.map((l) => JSON.parse(l) as Record<string, unknown>);
}

it('writes one transcript per dispatch, opening with the launch prompt', async () => {
const dispatch = createProductionDispatch(transcriptConfig());
await dispatch('review the diff', { label: 'reviewer' });

const files = transcriptFiles();
expect(files).toHaveLength(1);
// Named for the same id the dispatch reports in its terminal error, so
// a failure message leads straight to the record.
expect(path.basename(files[0])).toMatch(
/^agent-workflow-agent-[0-9a-f]{16}\.jsonl$/,
);

const records = recordsOf(files[0]);
const first = records[0];
expect(first['type']).toBe('user');
expect(first['agentId']).toBe(created[0]!.agentId);
expect(first['agentName']).toBe('reviewer');
expect(first['sessionId']).toBe(SESSION);
// The prompt is written at attach time, before the model has produced
// anything — which is what makes it evidence the agent cannot revise.
expect(
(first['message'] as { parts: Array<{ text?: string }> }).parts[0].text,
).toBe('review the diff');
});

it("records the agent's tool calls, pairable by callId", async () => {
nextExecuteHook.value = async (emitter) => {
emitter.emit(AgentEventType.TOOL_CALL, {
subagentId: 'workflow-agent',
round: 1,
callId: 'call-1',
name: 'read_file',
args: { absolute_path: '/repo/diff.txt', offset: 0, limit: 40 },
description: 'read the diff',
timestamp: Date.now(),
});
emitter.emit(AgentEventType.TOOL_RESPONSES_FINALIZED, {
subagentId: 'workflow-agent',
round: 1,
responses: [
{
callId: 'call-1',
responseParts: [
{
functionResponse: {
id: 'call-1',
name: 'read_file',
response: { output: 'diff text' },
},
},
],
},
],
timestamp: Date.now(),
});
};

const dispatch = createProductionDispatch(transcriptConfig());
await dispatch('read it', { label: 'reader' });

const records = recordsOf(transcriptFiles()[0]);
const call = records.find((r) =>
(
r['message'] as { parts?: Array<{ functionCall?: unknown }> }
)?.parts?.some((p) => p.functionCall !== undefined),
);
const result = records.find((r) => r['type'] === 'tool_result');
expect(call).toBeDefined();
expect(result).toBeDefined();

const fc = (
call!['message'] as {
parts: Array<{
functionCall?: { id: string; name: string; args: unknown };
}>;
}
).parts[0].functionCall!;
expect(fc.id).toBe('call-1');
expect(fc.name).toBe('read_file');
// The args are what let a reader ask "which file, which lines" rather
// than only "it called something".
expect(fc.args).toEqual({
absolute_path: '/repo/diff.txt',
offset: 0,
limit: 40,
});
expect((result!['toolCallResult'] as { callId: string }).callId).toBe(
'call-1',
);
});

// A retried dispatch is two agent runs, and a reader that saw one merged
// record could not tell a stall from an agent that behaved oddly. The id
// is minted per attempt precisely so each leaves its own file.
it('writes a separate transcript for each stall retry attempt', async () => {
let attempt = 0;
nextExecuteHook.value = async (emitter, signal) => {
attempt += 1;
if (attempt > 1) {
nextTerminateMode.value = 'GOAL';
return;
}
nextTerminateMode.value = 'CANCELLED';
emitter.emit(AgentEventType.ROUND_START, {
subagentId: 'workflow-agent',
round: 1,
promptId: 'prompt-1',
timestamp: Date.now(),
});
await new Promise<void>((resolve) => {
if (signal?.aborted) {
resolve();
return;
}
signal?.addEventListener('abort', () => resolve(), { once: true });
});
};

const dispatch = createProductionDispatch(transcriptConfig());
await dispatch('stall once', { label: 'staller', stallMs: 20 });

expect(attempt).toBe(2);
const files = transcriptFiles();
expect(files).toHaveLength(2);
// Each is self-describing: both carry the launch prompt, so neither is
// a fragment that only makes sense beside the other.
for (const file of files) {
expect(recordsOf(file)[0]['type']).toBe('user');
}
});

// The transcript is audit metadata. A dispatch that would have succeeded
// must not fail because the record could not be written — which is also
// why every other test in this file, whose fakeConfig() has none of the
// methods used above, still passes.
it('does not fail the dispatch when the transcript cannot be written', async () => {
const broken = {
storage: {
getProjectDir: () => {
throw new Error('no project dir');
},
},
getSessionId: () => SESSION,
getProjectRoot: () => projectDir,
getCliVersion: () => '0.0.0-test',
} as unknown as Config;

const dispatch = createProductionDispatch(broken);
await expect(dispatch('still works', { label: 'x' })).resolves.toBe(
'headless-said:still works',
);
expect(transcriptFiles()).toHaveLength(0);
});
});

it('does not suppress env bootstrap with an empty initial history', async () => {
const dispatch = createProductionDispatch(fakeConfig());
await dispatch('hello', { label: 'h1' });
Expand Down
116 changes: 114 additions & 2 deletions packages/core/src/agents/runtime/workflow-orchestrator.ts
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,14 @@ import {
import { FileDiscoveryService } from '../../services/fileDiscoveryService.js';
import { WorkspaceContext } from '../../utils/workspaceContext.js';
import { SyntheticOutputTool } from '../../tools/syntheticOutput.js';
import { rebuildToolRegistryOnOverride } from '../../tools/agent/agent.js';
import {
getCachedGitBranch,
rebuildToolRegistryOnOverride,
} from '../../tools/agent/agent.js';
import {
attachJsonlTranscriptWriter,
getAgentJsonlPath,
} from '../agent-transcript.js';
import { toModelVisibleSubagentResult } from '../subagent-result.js';
import { SUBAGENT_PLAN_LIFECYCLE_TOOLS } from './subagent-plan-tool-policy.js';
import { runWithAgentContext } from './agent-context.js';
Expand Down Expand Up @@ -394,17 +401,31 @@ export function createProductionDispatch(
);
return runStallResilient(
async (attemptSignal, emitter) => {
// Minted here rather than inside the dispatch so this attempt's
// transcript is named for the same id the dispatch reports in its
// terminal error — and so the writer is attached to the emitter
// BEFORE any agent event can fire on it.
const workflowAgentId = `workflow-agent-${randomBytes(8).toString('hex')}`;
const cleanupApprovalBridge = bridgeApprovalEvents?.(emitter);
const detachTranscript = attachDispatchTranscript(
config,
workflowAgentId,
prompt,
opts,
emitter,
);
try {
return await runSingleDispatch(
config,
prompt,
opts,
attemptSignal,
emitter,
workflowAgentId,
onTokens,
);
} finally {
detachTranscript();
cleanupApprovalBridge?.();
}
},
Expand All @@ -417,6 +438,92 @@ export function createProductionDispatch(
};
}

/**
* Attach the harness's own per-subagent transcript to one dispatch.
*
* Workflow subagents were the only agents in the product that left no record.
* `attachJsonlTranscriptWriter` has exactly one other caller — the Agent tool
* (foreground and background) — while workflow dispatch goes straight to
* `AgentHeadless.create` / `createAgentHeadless`, so nothing landed in
* `<projectDir>/subagents/<sessionId>/`. Everything that reads that directory
* to answer "what did this agent actually do" was blind on the workflow path:
* post-mortem of a failed run, cost accounting, and any gate built on tool
* calls rather than on the agent's own prose (which is precisely the evidence
* an agent cannot forge — a whiffing agent still writes plausible text, but it
* makes no tool call).
*
* One attach point covers both dispatch paths because `runStallResilient`
* builds one `AgentEventEmitter` per attempt and hands the same instance to
* the fast path and the override path alike.
*
* Per ATTEMPT, not per `agent()` call: the caller mints one id per attempt,
* so a stall retry writes its own transcript rather than appending to the
* abandoned one. Three attempts leave three records, each self-describing —
* which is what makes a retry legible after the fact instead of looking like
* one agent that behaved strangely.
*
* Best-effort by construction. A transcript is audit metadata; an unwritable
* or full disk must not fail a dispatch that would otherwise have succeeded,
* so both the attach and the returned cleanup swallow their errors. The
* writer itself opens its fd lazily, so a dispatch that produces no record
* materializes no file.
*/
function attachDispatchTranscript(
config: Config,
workflowAgentId: string,
prompt: string,
opts: WorkflowAgentOpts,
emitter: AgentEventEmitter,
): () => void {
let cleanup: (() => void) | undefined;
try {
const sessionId = config.getSessionId();
const projectRoot = config.getProjectRoot();
// `label` first: it is the identity the script chose and the one the run
// shows in progress output, so a reader matching a transcript to a line
// of the script has the same name in both places. `agentType` is the
// fallback that still says something; the constant is the last resort.
const label = typeof opts.label === 'string' ? opts.label.trim() : '';
const agentType =
typeof opts.agentType === 'string' ? opts.agentType.trim() : '';
({ cleanup } = attachJsonlTranscriptWriter(
emitter,
getAgentJsonlPath(
config.storage.getProjectDir(),
sessionId,
workflowAgentId,
),
{
agentId: workflowAgentId,
agentName: label || agentType || 'workflow-agent',
sessionId,
cwd: projectRoot,
version: config.getCliVersion() || 'unknown',
gitBranch: getCachedGitBranch(projectRoot),
// Seeds the first `user` record, written before the model has said
// anything — so the transcript states what the agent was asked to do
// without a reader needing the script that asked it.
initialUserPrompt: prompt,
},
));
} catch (error) {
debugLogger.warn(
`[workflow] transcript attach failed for ${workflowAgentId}: ${error}`,
);
return () => {};
}
const detach = cleanup;
return () => {
try {
detach();
} catch (error) {
debugLogger.warn(
`[workflow] transcript cleanup failed for ${workflowAgentId}: ${error}`,
);
}
};
}

/**
* One single-attempt production dispatch. Receives the per-attempt abort
* signal (the stall wrapper chains the parent signal into it + the watchdog
Expand All @@ -431,12 +538,17 @@ async function runSingleDispatch(
opts: WorkflowAgentOpts,
attemptSignal: AbortSignal,
emitter: AgentEventEmitter,
/**
* This attempt's agent id, minted by the caller so the transcript writer
* could be attached to `emitter` before the agent exists. Also the id this
* function names in its non-GOAL terminal error.
*/
workflowAgentId: string,
onTokens?: (outputTokens: number, opts: WorkflowAgentOpts) => void,
): Promise<WorkflowAgentResult> {
const { AgentHeadless, ContextState } = await import('./agent-headless.js');
const ctx = new ContextState();
ctx.set('task_prompt', prompt);
const workflowAgentId = `workflow-agent-${randomBytes(8).toString('hex')}`;
debugLogger.debug(`[workflow] Dispatch ${workflowAgentId}`);

if (
Expand Down
8 changes: 7 additions & 1 deletion packages/core/src/tools/agent/agent.ts
Original file line number Diff line number Diff line change
Expand Up @@ -139,8 +139,14 @@ import type { AuthOverrides } from '../../models/content-generator-config.js';
// background) starts. Branches don't change within a process under normal
// use; the transcript annotation is best-effort audit metadata, so a stale
// value after a user `git checkout` mid-session is acceptable.
//
// Exported so the workflow dispatch path (workflow-orchestrator.ts) annotates
// its transcripts from the SAME cache instead of opening a second one — the
// whole point of the memo is one `git rev-parse` per cwd per process, and a
// private copy per launch path would quietly restore the per-launch execSync
// for workflow subagents.
const gitBranchCache = new Map<string, string | undefined>();
function getCachedGitBranch(cwd: string): string | undefined {
export function getCachedGitBranch(cwd: string): string | undefined {
if (gitBranchCache.has(cwd)) return gitBranchCache.get(cwd);
const branch = getGitBranch(cwd);
gitBranchCache.set(cwd, branch);
Expand Down
Loading