@robota-sdk/agent-transport 3.0.0-beta.76 → 3.0.0-beta.78

package/dist/node/testing/index.d.ts

@@ -1,21 +1,2 @@
-import { IAIProvider, TUniversalMessage } from "@robota-sdk/agent-core";
-
-//#region src/testing/scripted-provider.d.ts
-/** One scripted assistant turn: plain text or tool invocations. */
-type TScriptedTurn = {
-  text: string;
-} | {
-  toolCalls: ReadonlyArray<{
-    name: string;
-    args: Record<string, unknown>;
-  }>;
-};
-interface IScriptedProvider {
-  provider: IAIProvider;
-  /** Message arrays of every chat() call, in order, for request assertions. */
-  requests: TUniversalMessage[][];
-}
-declare function createScriptedProvider(turns: readonly TScriptedTurn[]): IScriptedProvider;
-//#endregion
-export { type IScriptedProvider, type TScriptedTurn, createScriptedProvider };
-//# sourceMappingURL=index.d.ts.map
+import { IScriptedProvider, TScriptedTurn, createScriptedProvider } from "@robota-sdk/agent-core/testing";
+export { type IScriptedProvider, type TScriptedTurn, createScriptedProvider };

package/dist/node/testing/index.js

@@ -1,2 +1 @@
-function e(e){let t=[],n=0;return{provider:{name:`scripted-test-provider`,version:`test`,async chat(r){t.push([...r]);let i=e[n];if(i===void 0)throw Error(`Scripted provider: script exhausted at call ${n+1} (script declares ${e.length} turn(s)) — extend the script instead of relying on improvised responses`);return n+=1,`text`in i?{id:`scripted-${n}`,role:`assistant`,content:i.text,state:`complete`,timestamp:new Date}:{id:`scripted-${n}`,role:`assistant`,content:null,state:`complete`,timestamp:new Date,toolCalls:i.toolCalls.map((e,t)=>({id:`scripted-call-${n}-${t}`,type:`function`,function:{name:e.name,arguments:JSON.stringify(e.args)}}))}},async generateResponse(){return{content:`scripted provider does not implement raw responses`}},supportsTools(){return!0},validateConfig(){return!0}},requests:t}}export{e as createScriptedProvider};
-//# sourceMappingURL=index.js.map
+import{createScriptedProvider as e}from"@robota-sdk/agent-core/testing";export{e as createScriptedProvider};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robota-sdk/agent-transport",
-  "version": "3.0.0-beta.76",
+  "version": "3.0.0-beta.78",
   "description": "Core transport package for Robota SDK — headless adapter, scripted-provider testing fixtures, and the transport registry",
   "type": "module",
   "main": "dist/node/index.js",
@@ -41,6 +41,18 @@
         "import": "./dist/node/testing/index.js",
         "require": "./dist/node/testing/index.cjs"
       }
+    },
+    "./programmatic": {
+      "types": "./dist/node/programmatic/index.d.ts",
+      "source": "./src/programmatic/index.ts",
+      "node": {
+        "import": "./dist/node/programmatic/index.js",
+        "require": "./dist/node/programmatic/index.cjs"
+      },
+      "default": {
+        "import": "./dist/node/programmatic/index.js",
+        "require": "./dist/node/programmatic/index.cjs"
+      }
     }
   },
   "repository": {
@@ -59,9 +71,9 @@
     "src"
   ],
   "dependencies": {
-    "@robota-sdk/agent-framework": "3.0.0-beta.76",
-    "@robota-sdk/agent-core": "3.0.0-beta.76",
-    "@robota-sdk/agent-interface-transport": "3.0.0-beta.76"
+    "@robota-sdk/agent-core": "3.0.0-beta.78",
+    "@robota-sdk/agent-interface-transport": "3.0.0-beta.78",
+    "@robota-sdk/agent-framework": "3.0.0-beta.78"
   },
   "devDependencies": {
     "rimraf": "^5.0.10",
@@ -69,9 +81,9 @@
     "tsx": "^4.22.4",
     "typescript": "^5.9.3",
     "vitest": "^3.2.6",
-    "@robota-sdk/agent-command": "3.0.0-beta.76"
+    "@robota-sdk/agent-command": "3.0.0-beta.78"
   },
-  "license": "MIT",
+  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "publishConfig": {
     "access": "public"
   },

package/src/__tests__/programmatic/programmatic-ask-user.test.ts

@@ -0,0 +1,32 @@
+/**
+ * CMD-004 PR-E: ProgrammaticInteractionChannel.askUser() — the unified ask path on the programmatic
+ * channel. FIFO from the pre-supplied queue; empty queue → cancelled (never blocks a headless run).
+ */
+import { describe, expect, it } from 'vitest';
+
+import { ProgrammaticInteractionChannel } from '../../programmatic/ProgrammaticInteractionChannel.js';
+
+import type { IActionRequest } from '@robota-sdk/agent-core';
+
+const REQUEST: IActionRequest = {
+  id: 'q',
+  title: 'Pick',
+  options: [{ value: 'a', label: 'A' }],
+  maxSelect: 1,
+};
+
+describe('ProgrammaticInteractionChannel.askUser', () => {
+  it('resolves cancelled when no answer is queued', async () => {
+    const channel = new ProgrammaticInteractionChannel();
+    expect(await channel.askUser(REQUEST)).toEqual({ type: 'cancelled' });
+  });
+
+  it('resolves queued answers FIFO, then cancelled once drained', async () => {
+    const channel = new ProgrammaticInteractionChannel();
+    channel.queueUserAction({ type: 'answer', values: ['a'] });
+    channel.queueUserAction({ type: 'cancelled' });
+    expect(await channel.askUser(REQUEST)).toEqual({ type: 'answer', values: ['a'] });
+    expect(await channel.askUser(REQUEST)).toEqual({ type: 'cancelled' });
+    expect(await channel.askUser(REQUEST)).toEqual({ type: 'cancelled' });
+  });
+});

package/src/__tests__/programmatic/programmatic-driver.test.ts

@@ -0,0 +1,107 @@
+/**
+ * INFRA-019: in-process programmatic driving of the REAL agent.
+ *
+ * Drives `createProgrammaticAgent` (→ `createInteractiveRuntime` → a real `InteractiveSession`) with
+ * the deterministic scripted provider. No terminal, no PTY, no mocks of the framework loop: a message
+ * is pushed in-process and the structured `InteractionEvent` stream is asserted as data. This is the
+ * in-process form of "drive the agent at will" (TEST-008 north star).
+ */
+
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createScriptedProvider } from '@robota-sdk/agent-core/testing';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  createProgrammaticAgent,
+  ProgrammaticInteractionChannel,
+} from '../../programmatic/index.js';
+
+import type { IAgentDriver } from '@robota-sdk/agent-interface-transport';
+
+describe('programmatic in-process agent driver (INFRA-019)', () => {
+  let cwd: string;
+  let driver: IAgentDriver | undefined;
+
+  beforeEach(() => {
+    cwd = mkdtempSync(join(tmpdir(), 'robota-programmatic-'));
+  });
+
+  afterEach(async () => {
+    await driver?.stop();
+    driver = undefined;
+    rmSync(cwd, { recursive: true, force: true });
+  });
+
+  it('TC-01/02: send() drives a real turn and the scripted assistant reply is captured as data', async () => {
+    const scripted = createScriptedProvider([{ text: 'DRIVEN_ANSWER_42' }]);
+    driver = createProgrammaticAgent({ provider: scripted.provider, cwd });
+
+    await driver.start();
+    await driver.send('hello');
+
+    // TC-02: the reply is captured structurally — no terminal involved.
+    expect(driver.lastAssistantText()).toBe('DRIVEN_ANSWER_42');
+    expect(driver.assistantReplies()).toEqual(['DRIVEN_ANSWER_42']);
+
+    // Event order: the user message is recorded before the assistant completion.
+    const types = driver.events.map((e) => e.type);
+    expect(types).toContain('user-message');
+    expect(types).toContain('assistant-done');
+    expect(types.indexOf('user-message')).toBeLessThan(types.indexOf('assistant-done'));
+    expect(driver.errors()).toEqual([]);
+
+    // The scripted provider saw exactly the driven message.
+    const firstRequest = scripted.requests[0] ?? [];
+    const contents = firstRequest.map((m) => String(m.content));
+    expect(contents.some((c) => c.includes('hello'))).toBe(true);
+  });
+
+  it('TC-03: a scripted tool-call turn runs the real tool loop and is captured in toolCalls()', async () => {
+    const target = join(cwd, 'greet.txt');
+    writeFileSync(target, 'Hello, world\n', 'utf8');
+
+    const scripted = createScriptedProvider([
+      {
+        toolCalls: [
+          { name: 'Edit', args: { filePath: target, oldString: 'Hello', newString: 'Goodbye' } },
+        ],
+      },
+      { text: 'edit done' },
+    ]);
+    driver = createProgrammaticAgent({
+      provider: scripted.provider,
+      cwd,
+      permissionMode: 'bypassPermissions',
+    });
+
+    await driver.start();
+    await driver.send('change the greeting');
+
+    // The real tool loop executed: the file on disk was mutated.
+    expect(readFileSync(target, 'utf8')).toBe('Goodbye, world\n');
+    // The tool call surfaced as structured data.
+    const calls = driver.toolCalls();
+    expect(calls.some((c) => c.name === 'Edit')).toBe(true);
+    expect(driver.lastAssistantText()).toBe('edit done');
+  });
+
+  it('TC-04: queueUserAction pre-answers an askUser; empty queue resolves to cancelled', async () => {
+    const scripted = createScriptedProvider([{ text: 'noop' }]);
+    driver = createProgrammaticAgent({ provider: scripted.provider, cwd });
+    await driver.start();
+
+    // Exercise the unified ask contract in isolation (the FIFO queue the driver's queueUserAction feeds).
+    const channel = new ProgrammaticInteractionChannel();
+    const request = { id: 'x', title: 'ok?', options: [{ value: 'a', label: 'A' }], maxSelect: 1 };
+
+    channel.queueUserAction({ type: 'answer', values: ['a'] });
+    const answered = await channel.askUser(request);
+    expect(answered).toEqual({ type: 'answer', values: ['a'] });
+
+    const defaulted = await channel.askUser(request);
+    expect(defaulted).toEqual({ type: 'cancelled' });
+  });
+});

package/src/__tests__/programmatic/programmatic-flows.test.ts

@@ -0,0 +1,140 @@
+/**
+ * TEST-009 Phase 2: conversation + slash-command flows driven through `IAgentDriver`.
+ *
+ * Exercises the in-process driver (`createProgrammaticAgent`) against the REAL framework loop with the
+ * scripted provider: multi-turn context, a slash command producing a `command-result`, and the CMD-004
+ * ask seam (a command self-asks via `getUserInteraction()`, pre-answered through `queueUserAction`).
+ * All assertions read the shared `InteractionEvent` stream the contract exposes.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { confirmAction, isConfirmed } from '@robota-sdk/agent-core';
+import { createScriptedProvider } from '@robota-sdk/agent-core/testing';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { createProgrammaticAgent } from '../../programmatic/index.js';
+
+import type { ICommandModule } from '@robota-sdk/agent-framework';
+import type { IAgentDriver, InteractionEvent } from '@robota-sdk/agent-interface-transport';
+
+function commandResults(
+  events: readonly InteractionEvent[],
+): Array<{ name: string; output: string }> {
+  return events
+    .filter(
+      (e): e is Extract<InteractionEvent, { type: 'command-result' }> =>
+        e.type === 'command-result',
+    )
+    .map((e) => ({ name: e.name, output: e.output }));
+}
+
+/** A read-only `/ping` command that returns a fixed result — no host adapters needed. */
+const PING_MODULE: ICommandModule = {
+  name: 'ping',
+  systemCommands: [
+    {
+      name: 'ping',
+      description: 'test ping',
+      userInvocable: true,
+      safety: 'read-only',
+      requiresPermission: false,
+      execute: () => ({ message: 'PONG', success: true }),
+    },
+  ],
+};
+
+/** A `/danger` command that self-asks for confirmation via the CMD-004 ask seam. */
+const CONFIRM_MODULE: ICommandModule = {
+  name: 'danger',
+  systemCommands: [
+    {
+      name: 'danger',
+      description: 'requires confirmation',
+      userInvocable: true,
+      safety: 'read-only',
+      requiresPermission: false,
+      lifecycle: 'inline',
+      execute: async (context) => {
+        const ui = context.getUserInteraction?.();
+        const response = ui ? await ui.ask(confirmAction('danger', 'Are you sure?')) : undefined;
+        if (!response || !isConfirmed(response)) {
+          return { message: 'DANGER_CANCELLED', success: true };
+        }
+        return { message: 'DANGER_RAN', success: true };
+      },
+    },
+  ],
+};
+
+describe('IAgentDriver conversation + slash flows (TEST-009 Phase 2)', () => {
+  let cwd: string;
+  let driver: IAgentDriver | undefined;
+
+  beforeEach(() => {
+    cwd = mkdtempSync(join(tmpdir(), 'robota-flows-'));
+  });
+  afterEach(async () => {
+    await driver?.stop();
+    driver = undefined;
+    rmSync(cwd, { recursive: true, force: true });
+  });
+
+  it('carries multi-turn conversation context across sends', async () => {
+    const scripted = createScriptedProvider([{ text: 'NOTED_42' }, { text: 'IT_WAS_42' }]);
+    driver = createProgrammaticAgent({ provider: scripted.provider, cwd });
+    await driver.start();
+
+    await driver.send('Remember the number 42');
+    expect(driver.lastAssistantText()).toBe('NOTED_42');
+
+    await driver.send('What number?');
+    expect(driver.lastAssistantText()).toBe('IT_WAS_42');
+    expect(driver.assistantReplies()).toEqual(['NOTED_42', 'IT_WAS_42']);
+
+    // The second request must carry the prior turn (real session context).
+    const second = (scripted.requests[1] ?? []).map((m) => String(m.content)).join('\n');
+    expect(second).toContain('Remember the number 42');
+    expect(second).toContain('NOTED_42');
+  });
+
+  it('runs a slash command and surfaces a command-result event', async () => {
+    const scripted = createScriptedProvider([{ text: 'unused' }]);
+    driver = createProgrammaticAgent({
+      provider: scripted.provider,
+      cwd,
+      commandModules: [PING_MODULE],
+    });
+    await driver.start();
+
+    await driver.send('/ping');
+    expect(commandResults(driver.events)).toEqual([{ name: 'ping', output: 'PONG' }]);
+  });
+
+  it('drives the ask seam: queueUserAction confirms a self-asking command; empty queue cancels it', async () => {
+    const scripted = createScriptedProvider([{ text: 'unused' }, { text: 'unused' }]);
+    driver = createProgrammaticAgent({
+      provider: scripted.provider,
+      cwd,
+      commandModules: [CONFIRM_MODULE],
+    });
+    await driver.start();
+
+    // Confirmed → the command runs (askUser resolved from the pre-supplied queue).
+    driver.queueUserAction({ type: 'answer', values: ['yes'] });
+    await driver.send('/danger');
+    const ranAfterConfirm = commandResults(driver.events).filter(
+      (c) => c.output === 'DANGER_RAN',
+    ).length;
+    expect(ranAfterConfirm).toBe(1);
+
+    // Empty queue → askUser resolves `cancelled` → the command takes its cancel path (does NOT run).
+    await driver.send('/danger');
+    expect(commandResults(driver.events).filter((c) => c.output === 'DANGER_RAN').length).toBe(
+      ranAfterConfirm,
+    );
+    expect(commandResults(driver.events).some((c) => c.output === 'DANGER_CANCELLED')).toBe(true);
+  });
+});

package/src/__tests__/transport-registry.stop-all.test.ts

@@ -0,0 +1,53 @@
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { TransportRegistry } from '../transport-registry';
+
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
+import type { IConfigurableTransport } from '@robota-sdk/agent-interface-transport';
+
+function makeTransport(
+  name: string,
+  stop: () => Promise<void>,
+): IConfigurableTransport<IInteractiveSession> {
+  return {
+    name,
+    defaultEnabled: true,
+    attach: vi.fn(),
+    start: vi.fn().mockResolvedValue(undefined),
+    stop,
+  } as unknown as IConfigurableTransport<IInteractiveSession>;
+}
+
+describe('TransportRegistry.stopAll (best-effort, CORE-013)', () => {
+  it('stops every transport even when one stop fails, and collects the error', async () => {
+    const registry = new TransportRegistry(
+      path.join(mkdtempSync(path.join(tmpdir(), 'registry-')), 'settings.json'),
+    );
+    const stoppedSecond = vi.fn().mockResolvedValue(undefined);
+    registry.register(
+      makeTransport('failing', async () => {
+        throw new Error('stop boom');
+      }),
+    );
+    registry.register(makeTransport('healthy', stoppedSecond));
+
+    const result = await registry.stopAll();
+
+    expect(stoppedSecond).toHaveBeenCalledTimes(1);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].message).toBe('stop boom');
+  });
+
+  it('returns an empty error list when all stops succeed', async () => {
+    const registry = new TransportRegistry(
+      path.join(mkdtempSync(path.join(tmpdir(), 'registry-')), 'settings.json'),
+    );
+    registry.register(makeTransport('a', vi.fn().mockResolvedValue(undefined)));
+
+    await expect(registry.stopAll()).resolves.toEqual({ errors: [] });
+  });
+});

package/src/headless/HeadlessInteractionChannel.ts

@@ -64,15 +64,36 @@ export class HeadlessInteractionChannel {
   }
 
   async run(prompt: string): Promise<void> {
+    const session = this.createSession();
+    const runner = createHeadlessRunner({ session, outputFormat: this.opts.outputFormat });
+    this.exitCode = await runner.run(prompt);
+    await session.shutdown({ reason: 'prompt_input_exit', message: 'Headless transport complete' });
+  }
+
+  /**
+   * GOAL-001: run an autonomous goal to completion (or a stop condition) in headless mode.
+   * Mirrors {@link run} but drives the framework goal loop instead of a single prompt.
+   */
+  async runGoal(objective: string, options: { maxIterations?: number } = {}): Promise<void> {
+    const session = this.createSession();
+    const runner = createHeadlessRunner({ session, outputFormat: this.opts.outputFormat });
+    this.exitCode = await runner.runGoal(objective, options);
+    await session.shutdown({ reason: 'prompt_input_exit', message: 'Headless goal complete' });
+  }
+
+  private createSession(): InteractiveSession {
     const shellExec: TShellExecFn =
       this.opts.shellExec ??
       ((command: string) =>
         execSync(command, { timeout: 5000, encoding: 'utf-8', stdio: 'pipe' }).trimEnd());
 
-    const session = new InteractiveSession({
+    return new InteractiveSession({
       cwd: this.opts.cwd,
       provider: this.opts.provider,
       permissionMode: this.opts.permissionMode ?? 'bypassPermissions',
+      // CMD-004: headless has no interactive renderer, so it injects no askHandler — the session's
+      // getUserInteraction() returns undefined and each command applies its explicit no-human path
+      // (e.g. /mode reports current, /exit and /clear proceed — never a silent guess).
       maxTurns: this.opts.maxTurns,
       sessionStore: this.opts.sessionStore,
       resumeSessionId: this.opts.resumeSessionId,
@@ -100,10 +121,6 @@ export class HeadlessInteractionChannel {
         ? { selfVerification: this.opts.selfVerification }
         : {}),
     });
-
-    const runner = createHeadlessRunner({ session, outputFormat: this.opts.outputFormat });
-    this.exitCode = await runner.run(prompt);
-    await session.shutdown({ reason: 'prompt_input_exit', message: 'Headless transport complete' });
   }
 
   getExitCode(): number {

package/src/headless/__tests__/headless-goal-runner.test.ts

@@ -0,0 +1,108 @@
+/**
+ * GOAL-001: headless autonomous goal runner. A fake session emits goal lifecycle events; the
+ * runner resolves to exit 0 when satisfied, GOAL_NOT_SATISFIED_EXIT_CODE at a bound, and 1 on error.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+import { createHeadlessRunner, GOAL_NOT_SATISFIED_EXIT_CODE } from '../headless-runner.js';
+
+import type {
+  IGoalEvent,
+  IGoalState,
+  IInteractiveSession,
+} from '@robota-sdk/agent-interface-transport';
+
+type TListener = (...args: unknown[]) => void;
+
+function goalState(overrides: Partial<IGoalState> = {}): IGoalState {
+  return {
+    id: 'g1',
+    objective: 'do it',
+    status: 'satisfied',
+    iterations: 2,
+    maxIterations: 25,
+    startedAt: '2026-06-27T00:00:00.000Z',
+    progress: [],
+    ...overrides,
+  };
+}
+
+/** Minimal fake session whose setGoal drives a scripted sequence of events. */
+function createFakeSession(
+  script: (emit: (e: string, ...a: unknown[]) => void) => void,
+): IInteractiveSession {
+  const listeners = new Map<string, Set<TListener>>();
+  const emit = (event: string, ...args: unknown[]): void => {
+    for (const fn of listeners.get(event) ?? []) fn(...args);
+  };
+  return {
+    on: (event: string, handler: TListener) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(handler);
+    },
+    off: (event: string, handler: TListener) => listeners.get(event)?.delete(handler),
+    setGoal: async () => {
+      queueMicrotask(() => script(emit));
+      return goalState();
+    },
+    getSession: () => ({ getSessionId: () => 'sess' }),
+  } as unknown as IInteractiveSession;
+}
+
+const stdoutChunks: string[] = [];
+const stderrChunks: string[] = [];
+
+beforeEach(() => {
+  stdoutChunks.length = 0;
+  stderrChunks.length = 0;
+  vi.spyOn(process.stdout, 'write').mockImplementation(((chunk: unknown) => {
+    stdoutChunks.push(String(chunk));
+    return true;
+  }) as never);
+  vi.spyOn(process.stderr, 'write').mockImplementation(((chunk: unknown) => {
+    stderrChunks.push(String(chunk));
+    return true;
+  }) as never);
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('headless runGoal', () => {
+  it('exits 0 and prints turn responses when the goal is satisfied', async () => {
+    const session = createFakeSession((emit) => {
+      emit('complete', { response: 'did step 1' });
+      emit('goal_event', {
+        type: 'goal_started',
+        goal: goalState({ status: 'active' }),
+      } as IGoalEvent);
+      emit('goal_event', {
+        type: 'goal_stopped',
+        goal: goalState({ stopReason: 'satisfied' }),
+      } as IGoalEvent);
+    });
+    const code = await createHeadlessRunner({ session, outputFormat: 'text' }).runGoal('do it');
+    expect(code).toBe(0);
+    expect(stdoutChunks).toContain('did step 1\n');
+    expect(stdoutChunks.join('')).toContain('Goal satisfied');
+  });
+
+  it('exits GOAL_NOT_SATISFIED_EXIT_CODE when stopped at a bound', async () => {
+    const session = createFakeSession((emit) => {
+      emit('goal_event', {
+        type: 'goal_stopped',
+        goal: goalState({ status: 'stopped', stopReason: 'max-iterations' }),
+      } as IGoalEvent);
+    });
+    const code = await createHeadlessRunner({ session, outputFormat: 'text' }).runGoal('do it');
+    expect(code).toBe(GOAL_NOT_SATISFIED_EXIT_CODE);
+  });
+
+  it('exits 1 on a turn error', async () => {
+    const session = createFakeSession((emit) => {
+      emit('error', new Error('provider exploded'));
+    });
+    const code = await createHeadlessRunner({ session, outputFormat: 'text' }).runGoal('do it');
+    expect(code).toBe(1);
+  });
+});

package/src/headless/__tests__/headless-runner.test.ts

@@ -4,8 +4,9 @@ import type {
   IInteractiveSession,
   TBackgroundJobGroupEvent,
 } from '@robota-sdk/agent-interface-transport';
-import type { TBackgroundTaskEvent } from '@robota-sdk/agent-framework';
+
 import { createHeadlessRunner } from '../headless-runner.js';
+import type { TBackgroundTaskEvent } from '@robota-sdk/agent-interface-transport';
 
 function createMockSession(behavior: 'complete' | 'interrupted' | 'error', response = '') {
   const listeners = new Map<string, Array<(...args: unknown[]) => void>>();

package/src/headless/headless-runner.ts

@@ -1,16 +1,29 @@
 import { executeSlashCommandIfPresent, subscribeStreamJsonEvents } from './headless-stream-json.js';
 
-import type { IExecutionResult, IInteractiveSession } from '@robota-sdk/agent-interface-transport';
+import type {
+  IExecutionResult,
+  IGoalEvent,
+  IInteractiveSession,
+} from '@robota-sdk/agent-interface-transport';
 
 export type TOutputFormat = 'text' | 'json' | 'stream-json';
 
+/** GOAL-001: options for an autonomous headless goal run. */
+export interface IHeadlessGoalOptions {
+  maxIterations?: number;
+}
+
 export interface IHeadlessRunnerOptions {
   session: IInteractiveSession;
   outputFormat: TOutputFormat;
 }
 
+/** Exit code for a goal that stopped cleanly without being satisfied (bound/convergence/cancel). */
+export const GOAL_NOT_SATISFIED_EXIT_CODE = 2;
+
 export function createHeadlessRunner(options: IHeadlessRunnerOptions): {
   run: (prompt: string) => Promise<number>;
+  runGoal: (objective: string, goalOptions?: IHeadlessGoalOptions) => Promise<number>;
 } {
   const { session, outputFormat } = options;
   return {
@@ -19,9 +32,62 @@ export function createHeadlessRunner(options: IHeadlessRunnerOptions): {
       if (outputFormat === 'json') return runJsonFormat(session, prompt);
       return runStreamJsonFormat(session, prompt);
     },
+    runGoal: (objective: string, goalOptions: IHeadlessGoalOptions = {}): Promise<number> =>
+      runGoalFormat(session, objective, goalOptions, outputFormat),
   };
 }
 
+/**
+ * GOAL-001: drive an autonomous goal to completion in headless mode. Streams each turn's response
+ * for progress, then resolves when the goal stops: exit 0 if satisfied, {@link GOAL_NOT_SATISFIED_EXIT_CODE}
+ * if it stopped at a bound (max-iterations / no-progress / cancelled), or 1 on a turn error.
+ */
+function runGoalFormat(
+  session: IInteractiveSession,
+  objective: string,
+  goalOptions: IHeadlessGoalOptions,
+  outputFormat: TOutputFormat,
+): Promise<number> {
+  return new Promise<number>((resolve) => {
+    const cleanup = (): void => {
+      session.off('complete', onComplete);
+      session.off('error', onError);
+      session.off('goal_event', onGoal);
+    };
+    const onComplete = (result: IExecutionResult): void => {
+      if (result.response) process.stdout.write(result.response + '\n');
+    };
+    const onError = (error: Error): void => {
+      cleanup();
+      if (outputFormat === 'text') process.stderr.write(error.message + '\n');
+      else writeJsonResult(getSessionId(session), '', 'error', error);
+      resolve(1);
+    };
+    const onGoal = (event: IGoalEvent): void => {
+      if (event.type !== 'goal_stopped') return;
+      cleanup();
+      const goal = event.goal;
+      const satisfied = goal.stopReason === 'satisfied';
+      const summary = satisfied
+        ? `Goal satisfied after ${goal.iterations} iteration(s).`
+        : `Goal stopped: ${goal.stopReason} (after ${goal.iterations} iteration(s)).`;
+      if (outputFormat === 'text')
+        (satisfied ? process.stdout : process.stderr).write(summary + '\n');
+      else writeJsonResult(getSessionId(session), summary, satisfied ? 'success' : 'error');
+      resolve(satisfied ? 0 : GOAL_NOT_SATISFIED_EXIT_CODE);
+    };
+
+    session.on('complete', onComplete);
+    session.on('error', onError);
+    session.on('goal_event', onGoal);
+
+    void session.setGoal(
+      objective,
+      goalOptions.maxIterations ? { maxIterations: goalOptions.maxIterations } : {},
+    );
+  });
+}
+
 export function resolveErrorCode(error: Error): string {
   const msg = error.message.toLowerCase();
   if (msg.includes('api key') || msg.includes('no provider') || msg.includes('provider')) {