@multiplayer-app/agent 0.1.8 → 0.1.10

package/README.md

@@ -0,0 +1,106 @@
+# Agent library
+
+This package runs inside the sandbox VM. Start with `src/runtime/index.ts`: it loads environment
+configuration, chooses a mode, and connects the agent to the gateway.
+
+## Where to make changes
+
+| Area | Files | Responsibility |
+| --- | --- | --- |
+| Startup | `src/runtime/cli.ts`, `src/runtime/index.ts`, `src/runtime/lambda-microvm.ts` | Process startup, shutdown, Lambda suspend/terminate hooks |
+| Configuration and wire contract | `src/runtime/config.ts`, `src/transport/protocol.ts` | Environment variables, commands, events, secret keys |
+| One-shot tasks | `src/task/loop.ts`, `src/transport/reporter.ts` | Run `AGENT_TASK`, report results, exit |
+| Agent definitions | `src/agent/definition.ts`, `src/agent/profiles/` | Coding/research prompts, model selection, workspace directories, tool composition |
+| Turn execution | `src/agent/turn-runner.ts` | Execute one model/tool loop, report events and usage, return a completed/aborted/failed outcome |
+| Chat sessions | `src/session/runtime.ts` | Own conversation, budget, queue, checkpoints, and shutdown |
+| Compatibility entry point | `src/session/index.ts` | Preserve `SessionAgent`, `runSessionAgent`, and `limitConversation` imports |
+| Conversation storage | `src/session/conversation.ts` | Context trimming and atomic conversation-file writes |
+| Session tools | `src/session/tools.ts`, `src/session/tool-context.ts` | Register tools, report progress, ask questions, publish artifacts |
+| Models and usage | `src/models/resolve-model.ts`, `src/models/usage.ts` | Resolve a definition's model and normalize token usage |
+| Workspace persistence | `src/persistence/workspace.ts`, `src/persistence/git-sync.ts`, `src/persistence/snapshot-sync.ts` | Common restore/checkpoint interface backed by project Git or standalone session snapshots |
+| Gateway connection | `src/transport/link.ts` | Send sequenced events and acknowledge commands |
+| Local and MCP tools | `src/tools/`, `src/mcp/` | Filesystem, shell, external tool discovery and execution |
+| Research tools | `src/research/filingramp-tools.ts`, `src/research/filingramp/` | Register FilingRamp tools and implement searches, filing details, downloads |
+| Research contracts | `src/research/filingramp-contract.ts`, `src/research/scope.ts` | Normalize API-specific filters and apply the session scope |
+| Research extraction | `src/research/extraction-tool.ts`, `src/research/prompt.ts` | Bulk model extraction and research instructions |
+
+The package exports in `src/index.ts`, `./protocol`, and `./attribution` are the
+public integration points. `SessionAgent` is an alias for `SessionRuntime`, so existing
+constructors and lifecycle calls still work. New consumers can use `AgentDefinition`,
+`TurnRunner`, and `WorkspacePersistence` directly.
+
+## Ownership boundaries
+
+`AgentDefinition` describes a profile: its model, instructions, workspace directories,
+step limit, and tool factory. The research definition retains its FilingRamp client and
+scope lookup cache across turns. It creates turn-specific progress, clarification, and
+extraction tools for each execution.
+
+`TurnRunner.run()` receives messages, instructions, an abort signal, an event sink, and
+budget callbacks. It returns a typed outcome and messages to append. It does not modify
+the supplied history, create timers, access the gateway connection, or checkpoint files.
+
+`SessionRuntime` owns mutable session state. It passes context to the runner, appends the
+returned messages, and decides when completion can be announced. Its constructor accepts
+optional definition, runner, and persistence dependencies so these boundaries can be tested
+without a model provider or storage server.
+
+`WorkspacePersistence` adapts the existing Git/snapshot sync classes. Its checkpoint result
+distinguishes a Git commit from a snapshot hash; neither leaks into the other's wire contract.
+A successful no-op is still durable. A failed restore or upload rejects the operation.
+
+## Session flow and invariants
+
+1. Restore the workspace, then load `.builder/conversation.json`, build tools, and
+   announce readiness. A failed restore must fail startup, not start an empty chat.
+2. Run one turn at a time. Incoming messages queue while a turn runs or checkpoints.
+   Tool callbacks capture their owning turn's identity and abort signal, so a delayed
+   callback cannot become an event for the next turn. `SessionRuntime` owns the token budget.
+3. Save the conversation before checkpointing the workspace. Completed turns checkpoint
+   before emitting `done`; interrupted turns also attempt a checkpoint.
+4. Serialize checkpoints. Periodic work runs five minutes after the last successful
+   durable checkpoint and schedules its next timer only after the current attempt
+   finishes. Failed storage writes must remain retryable.
+5. Confirm idle only after a durable checkpoint and a second activity check. Shutdown
+   aborts the active turn, clears queued work, waits for the turn, and checkpoints.
+   Lambda suspend/terminate hooks await startup and checkpoint completion before returning.
+
+A checkpoint recovers saved conversation, token budget, and workspace files. Queued commands
+and an in-flight model/tool step are process-local; this is not an execution journal that
+replays interrupted tool calls. Client event replay is a separate platform concern handled
+outside this runtime. The refactor does not change the persisted conversation format.
+
+Standalone sessions use the authenticated storage service to save workspace snapshots
+under `accounts/<accountId>/sessions/<sessionId>/`; they do not create `.git`.
+Project sessions use Git under `accounts/<accountId>/projects/<projectId>/`.
+`publish_results` separately sends selected text files to the platform for display;
+it does not replace workspace checkpoints.
+
+## Adding a research tool
+
+Register it in `filingramp-tools.ts` and implement it in the appropriate module under
+`research/filingramp/`. Keep model-facing names, descriptions, and schemas beside the
+implementation. Reuse the filter normalization in `filingramp-contract.ts` and scope
+handling in `scope.ts`; filings and document indexes accept different vocabularies.
+Return small projections and save large results or document text to workspace files.
+Propagate request failures instead of presenting them as zero results.
+
+Session tools receive an explicit `SessionToolContext` with workspace access, an abort signal,
+and callbacks for progress, clarification, files, and usage. They have no direct access to the
+session queue or gateway. Report extraction usage through `recordUsage` so the same session
+budget covers both the main model and extraction. Add a profile in `src/agent/profiles/` and select
+it in that directory's factory; the session runtime needs no profile-specific branches.
+
+## Local checks
+
+From the repository root:
+
+```sh
+pnpm --filter @multiplayer-app/agent test
+pnpm --filter @multiplayer-app/agent lint
+```
+
+The test command compiles the package and runs the Node test suite, including local
+Git recovery, snapshot recovery, checkpoint timing, queue/shutdown ordering, turn isolation,
+budget continuation, research contracts, and tool behavior.
+Tests use temporary workspaces and mocked service/model responses; they need no API keys.

package/dist/agent/definition.d.ts

@@ -0,0 +1,22 @@
+import type { Tool } from 'ai';
+import type { OpenRouterApp } from '../models/attribution';
+import type { AgentProfile, ModelProviderConfig } from '../runtime/config';
+import type { SessionToolContext } from '../session/tool-context';
+export interface AgentModel {
+    id: string;
+    provider: ModelProviderConfig;
+    attribution: OpenRouterApp;
+}
+/** Profile-specific behavior. Definitions have no queue, conversation, or checkpoint state. */
+export interface AgentDefinition {
+    profile: AgentProfile;
+    model: AgentModel;
+    maxSteps: number;
+    workspaceDirectories: readonly string[];
+    instructions(context: {
+        restored: boolean;
+        tokenBudget?: number;
+    }): string;
+    createTools(context: SessionToolContext): Record<string, Tool>;
+}
+//# sourceMappingURL=definition.d.ts.map

package/dist/agent/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/agent/definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAC1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,WAAW,EAAE,aAAa,CAAA;CAC3B;AAED,+FAA+F;AAC/F,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,YAAY,CAAA;IACrB,KAAK,EAAE,UAAU,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC,YAAY,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAA;IAC1E,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;CAC/D"}

package/dist/agent/definition.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=definition.js.map

package/dist/agent/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/agent/definition.ts"],"names":[],"mappings":""}

package/dist/agent/definition.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=definition.test.d.ts.map

package/dist/agent/definition.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.test.d.ts","sourceRoot":"","sources":["../../src/agent/definition.test.ts"],"names":[],"mappings":""}

package/dist/agent/definition.test.js

@@ -0,0 +1,40 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = require("node:test");
+const profiles_1 = require("./profiles");
+(0, node_test_1.it)('keeps profile instructions, workspace setup, models, and tools together', () => {
+    var _a;
+    const config = {
+        sessionId: 'test', mode: 'session', profile: 'coding', workspaceDir: '/unused',
+        model: 'main-model', extractionModel: 'extraction-model', provider: {}, mcpConnections: [],
+        filingRamp: { baseUrl: 'https://example.test', authToken: 'test', industryData: false },
+        researchScope: { states: ['TX'] },
+    };
+    const context = {
+        workspaceDir: '/unused', abortSignal: new AbortController().signal,
+        reportProgress() { }, requestClarification() { }, publishFiles() { }, recordUsage() { },
+    };
+    const coding = (0, profiles_1.createAgentDefinition)(config, context.workspaceDir);
+    strict_1.default.equal(coding.profile, 'coding');
+    strict_1.default.equal(coding.model.id, 'main-model');
+    strict_1.default.deepEqual(coding.workspaceDirectories, []);
+    strict_1.default.match(coding.instructions({ restored: false }), /coding agent/);
+    strict_1.default.equal(coding.createTools(context).search_filings, undefined);
+    strict_1.default.equal(coding.createTools(context).extract_from_texts, undefined);
+    const research = (0, profiles_1.createAgentDefinition)({ ...config, profile: 'research' }, context.workspaceDir);
+    strict_1.default.deepEqual(research.workspaceDirectories, ['research', 'data', 'data/text']);
+    strict_1.default.match(research.instructions({ restored: false }), /fresh session/);
+    strict_1.default.match(research.instructions({ restored: true, tokenBudget: 1000 }), /restored from a previous run/);
+    strict_1.default.match(research.instructions({ restored: true, tokenBudget: 1000 }), /1,000 tokens/);
+    strict_1.default.match(research.instructions({ restored: false }), /TX/);
+    const tools = research.createTools(context);
+    for (const name of ['search_filings', 'count_filings', 'summarize_filings', 'get_filing', 'search_documents', 'download_attachment', 'search_objections', 'read_text', 'extract_from_texts']) {
+        strict_1.default.equal(typeof ((_a = tools[name]) === null || _a === void 0 ? void 0 : _a.execute), 'function', name);
+    }
+    strict_1.default.equal(research.createTools(context).search_documents, tools.search_documents, 'scope lookup cache survives between turns');
+});
+//# sourceMappingURL=definition.test.js.map

package/dist/agent/definition.test.js.map

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

package/dist/agent/profiles/coding.d.ts

@@ -0,0 +1,4 @@
+import type { AgentDefinition } from '../definition';
+import type { AgentRuntimeConfig } from '../../runtime/config';
+export declare function createCodingAgent(config: AgentRuntimeConfig): AgentDefinition;
+//# sourceMappingURL=coding.d.ts.map

package/dist/agent/profiles/coding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coding.d.ts","sourceRoot":"","sources":["../../../src/agent/profiles/coding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAK9D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,eAAe,CAS7E"}

package/dist/agent/profiles/coding.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCodingAgent = createCodingAgent;
+const attribution_1 = require("../../models/attribution");
+const tools_1 = require("../../session/tools");
+const SYSTEM_PROMPT = `You are a coding agent running inside an isolated session workspace VM with a persistent disk. You have direct tools to read/write files and run shell commands in the workspace, plus (if any MCP servers are configured) search_tools/get_tool_details/call_mcp_tool to use them. Work efficiently, verify with cheap commands (build, lint), report progress with report_progress, publish deliverables with publish_results, and finish each turn with a concise summary.`;
+function createCodingAgent(config) {
+    return {
+        profile: 'coding',
+        model: { id: config.model, provider: config.provider, attribution: attribution_1.OPENROUTER_APPS.SESSION_AGENT },
+        maxSteps: 80,
+        workspaceDirectories: [],
+        instructions: () => SYSTEM_PROMPT,
+        createTools: (context) => (0, tools_1.createSessionTools)(context, config.mcpConnections),
+    };
+}
+//# sourceMappingURL=coding.js.map

package/dist/agent/profiles/coding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coding.js","sourceRoot":"","sources":["../../../src/agent/profiles/coding.ts"],"names":[],"mappings":";;AAOA,8CASC;AAfD,0DAA0D;AAE1D,+CAAwD;AAExD,MAAM,aAAa,GAAG,+cAA+c,CAAA;AAEre,SAAgB,iBAAiB,CAAC,MAA0B;IAC1D,OAAO;QACL,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,6BAAe,CAAC,aAAa,EAAE;QAClG,QAAQ,EAAE,EAAE;QACZ,oBAAoB,EAAE,EAAE;QACxB,YAAY,EAAE,GAAG,EAAE,CAAC,aAAa;QACjC,WAAW,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAA,0BAAkB,EAAC,OAAO,EAAE,MAAM,CAAC,cAAc,CAAC;KAC7E,CAAA;AACH,CAAC"}

package/dist/agent/profiles/index.d.ts

@@ -0,0 +1,4 @@
+import type { AgentDefinition } from '../definition';
+import type { AgentRuntimeConfig } from '../../runtime/config';
+export declare function createAgentDefinition(config: AgentRuntimeConfig, workspaceDir: string): AgentDefinition;
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/profiles/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agent/profiles/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAI9D,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,GAAG,eAAe,CAEvG"}

package/dist/agent/profiles/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentDefinition = createAgentDefinition;
+const coding_1 = require("./coding");
+const research_1 = require("./research");
+function createAgentDefinition(config, workspaceDir) {
+    return config.profile === 'research' ? (0, research_1.createResearchAgent)(config, workspaceDir) : (0, coding_1.createCodingAgent)(config);
+}
+//# sourceMappingURL=index.js.map

package/dist/agent/profiles/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/profiles/index.ts"],"names":[],"mappings":";;AAKA,sDAEC;AALD,qCAA4C;AAC5C,yCAAgD;AAEhD,SAAgB,qBAAqB,CAAC,MAA0B,EAAE,YAAoB;IACpF,OAAO,MAAM,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,IAAA,8BAAmB,EAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,IAAA,0BAAiB,EAAC,MAAM,CAAC,CAAA;AAC9G,CAAC"}

package/dist/agent/profiles/research.d.ts

@@ -0,0 +1,4 @@
+import type { AgentDefinition } from '../definition';
+import type { AgentRuntimeConfig } from '../../runtime/config';
+export declare function createResearchAgent(config: AgentRuntimeConfig, workspaceDir: string): AgentDefinition;
+//# sourceMappingURL=research.d.ts.map

package/dist/agent/profiles/research.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research.d.ts","sourceRoot":"","sources":["../../../src/agent/profiles/research.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAO9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,GAAG,eAAe,CA8BrG"}

package/dist/agent/profiles/research.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createResearchAgent = createResearchAgent;
+const attribution_1 = require("../../models/attribution");
+const extraction_tool_1 = require("../../research/extraction-tool");
+const filingramp_client_1 = require("../../research/filingramp-client");
+const filingramp_tools_1 = require("../../research/filingramp-tools");
+const prompt_1 = require("../../research/prompt");
+const tools_1 = require("../../session/tools");
+function createResearchAgent(config, workspaceDir) {
+    // Keep authentication and resolved scope labels across turns. These tools do not own turn state.
+    const filingTools = config.filingRamp
+        ? (0, filingramp_tools_1.createFilingRampTools)({ client: new filingramp_client_1.FilingRampClient(config.filingRamp), workspaceDir, scope: config.researchScope })
+        : {};
+    if (!config.filingRamp) {
+        console.warn('[session] research profile without FilingRamp credentials — filing tools disabled');
+    }
+    return {
+        profile: 'research',
+        model: { id: config.model, provider: config.provider, attribution: attribution_1.OPENROUTER_APPS.DEEP_RESEARCH },
+        maxSteps: 80,
+        workspaceDirectories: prompt_1.RESEARCH_WORKSPACE_DIRS,
+        instructions: ({ restored, tokenBudget }) => {
+            var _a;
+            return (0, prompt_1.buildResearchSystemPrompt)({
+                scope: config.researchScope,
+                industryData: Boolean((_a = config.filingRamp) === null || _a === void 0 ? void 0 : _a.industryData),
+                tokenBudget,
+                restored,
+            });
+        },
+        createTools: (context) => ({
+            ...(0, tools_1.createSessionTools)(context, config.mcpConnections),
+            ...filingTools,
+            extract_from_texts: (0, extraction_tool_1.createExtractionTool)(context, {
+                id: config.extractionModel,
+                provider: config.provider,
+                attribution: attribution_1.OPENROUTER_APPS.DEEP_RESEARCH,
+            }),
+        }),
+    };
+}
+//# sourceMappingURL=research.js.map

package/dist/agent/profiles/research.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"research.js","sourceRoot":"","sources":["../../../src/agent/profiles/research.ts"],"names":[],"mappings":";;AASA,kDA8BC;AAtCD,0DAA0D;AAE1D,oEAAqE;AACrE,wEAAmE;AACnE,sEAAuE;AACvE,kDAA0F;AAC1F,+CAAwD;AAExD,SAAgB,mBAAmB,CAAC,MAA0B,EAAE,YAAoB;IAClF,iGAAiG;IACjG,MAAM,WAAW,GAAG,MAAM,CAAC,UAAU;QACnC,CAAC,CAAC,IAAA,wCAAqB,EAAC,EAAE,MAAM,EAAE,IAAI,oCAAgB,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,CAAC,aAAa,EAAE,CAAC;QACvH,CAAC,CAAC,EAAE,CAAA;IACN,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,mFAAmF,CAAC,CAAA;IACnG,CAAC;IAED,OAAO;QACL,OAAO,EAAE,UAAU;QACnB,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,6BAAe,CAAC,aAAa,EAAE;QAClG,QAAQ,EAAE,EAAE;QACZ,oBAAoB,EAAE,gCAAuB;QAC7C,YAAY,EAAE,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,EAAE;;YAAC,OAAA,IAAA,kCAAyB,EAAC;gBACrE,KAAK,EAAE,MAAM,CAAC,aAAa;gBAC3B,YAAY,EAAE,OAAO,CAAC,MAAA,MAAM,CAAC,UAAU,0CAAE,YAAY,CAAC;gBACtD,WAAW;gBACX,QAAQ;aACT,CAAC,CAAA;SAAA;QACF,WAAW,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACzB,GAAG,IAAA,0BAAkB,EAAC,OAAO,EAAE,MAAM,CAAC,cAAc,CAAC;YACrD,GAAG,WAAW;YACd,kBAAkB,EAAE,IAAA,sCAAoB,EAAC,OAAO,EAAE;gBAChD,EAAE,EAAE,MAAM,CAAC,eAAe;gBAC1B,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,WAAW,EAAE,6BAAe,CAAC,aAAa;aAC3C,CAAC;SACH,CAAC;KACH,CAAA;AACH,CAAC"}

package/dist/agent/turn-runner.d.ts

@@ -0,0 +1,37 @@
+import { type ModelMessage } from 'ai';
+import type { AgentDefinition } from './definition';
+import type { OutboundEvent } from '../transport/link';
+import { type TokenUsage } from '../models/usage';
+export interface TurnInput {
+    messageId: string;
+    messages: ModelMessage[];
+    instructions: string;
+    workspaceDir: string;
+    abortSignal: AbortSignal;
+    budgetExceeded(): boolean;
+    recordUsage(usage: TokenUsage): void;
+    emit(event: OutboundEvent): void;
+}
+interface TurnOutput {
+    /** Messages to append to history, including a safe text-only fallback for an interrupted turn. */
+    messages: ModelMessage[];
+    partialText: string;
+    askedUser: boolean;
+}
+export type TurnResult = TurnOutput & ({
+    status: 'completed';
+    text: string;
+} | {
+    status: 'aborted';
+} | {
+    status: 'failed';
+    error: string;
+});
+/** Executes one turn. It neither mutates conversation history nor checkpoints or schedules work. */
+export declare class TurnRunner {
+    private readonly definition;
+    constructor(definition: AgentDefinition);
+    run(input: TurnInput): Promise<TurnResult>;
+}
+export {};
+//# sourceMappingURL=turn-runner.d.ts.map

package/dist/agent/turn-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-runner.d.ts","sourceRoot":"","sources":["../../src/agent/turn-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,IAAI,CAAA;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAGtD,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE1D,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,WAAW,CAAA;IACxB,cAAc,IAAI,OAAO,CAAA;IACzB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;IACpC,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAA;CACjC;AAED,UAAU,UAAU;IAClB,kGAAkG;IAClG,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,CAClC;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CACtC,CAAA;AAED,oGAAoG;AACpG,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,eAAe;IAElD,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;CAgFjD"}

package/dist/agent/turn-runner.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TurnRunner = void 0;
+const ai_1 = require("ai");
+const resolve_model_1 = require("../models/resolve-model");
+const usage_1 = require("../models/usage");
+/** Executes one turn. It neither mutates conversation history nor checkpoints or schedules work. */
+class TurnRunner {
+    constructor(definition) {
+        this.definition = definition;
+    }
+    async run(input) {
+        var _a, _b;
+        const { messageId, abortSignal, emit } = input;
+        let partialText = '';
+        let askedUser = false;
+        let responseMessages;
+        const recordUsage = (usage, model) => {
+            input.recordUsage(usage);
+            emit({ type: 'usage', messageId, usage: { ...usage, model } });
+        };
+        const context = {
+            workspaceDir: input.workspaceDir,
+            abortSignal,
+            recordUsage,
+            reportProgress: (steps, toolCallId) => emit({ type: 'progress', messageId, toolCallId, steps }),
+            publishFiles: (files) => emit({ type: 'files', messageId, files }),
+            requestClarification: (question, toolCallId) => {
+                askedUser = true;
+                emit({ type: 'question', messageId, toolCallId, question });
+            },
+        };
+        try {
+            abortSignal.throwIfAborted();
+            const { model, maxSteps } = this.definition;
+            const result = (0, ai_1.streamText)({
+                model: (0, resolve_model_1.resolveLanguageModel)(model.provider, model.id, model.attribution),
+                system: input.instructions,
+                messages: input.messages,
+                tools: this.definition.createTools(context),
+                abortSignal,
+                stopWhen: [(0, ai_1.stepCountIs)(maxSteps), () => askedUser || input.budgetExceeded()],
+            });
+            for await (const part of result.fullStream) {
+                switch (part.type) {
+                    case 'text-delta':
+                        partialText += part.text;
+                        emit({ type: 'text_delta', messageId, text: part.text });
+                        break;
+                    case 'reasoning-delta':
+                        emit({ type: 'reasoning_delta', messageId, text: part.text });
+                        break;
+                    case 'tool-call':
+                        emit({ type: 'tool_call_start', messageId, toolCallId: part.toolCallId, toolName: part.toolName, input: part.input });
+                        break;
+                    case 'tool-result':
+                        emit({ type: 'tool_call_result', messageId, toolCallId: part.toolCallId, output: part.output });
+                        break;
+                    case 'tool-error':
+                        emit({
+                            type: 'tool_call_result', messageId, toolCallId: part.toolCallId,
+                            error: part.error instanceof Error ? part.error.message : String(part.error),
+                        });
+                        break;
+                    case 'finish-step': {
+                        const usage = (0, usage_1.usageOf)(part);
+                        if (usage)
+                            recordUsage(usage, (_b = (_a = part.response) === null || _a === void 0 ? void 0 : _a.modelId) !== null && _b !== void 0 ? _b : model.id);
+                        break;
+                    }
+                    case 'error':
+                        throw part.error;
+                }
+            }
+            abortSignal.throwIfAborted();
+            responseMessages = (await result.response).messages;
+            const text = await result.text;
+            return { status: 'completed', messages: responseMessages, text, partialText, askedUser };
+        }
+        catch (error) {
+            const aborted = abortSignal.aborted;
+            // A partial stream may end between a tool call and its result. Persist text only in that case.
+            const messages = responseMessages !== null && responseMessages !== void 0 ? responseMessages : [{
+                    role: 'assistant', content: partialText || (aborted ? '(stopped by the user)' : '(turn failed)'),
+                }];
+            const output = { messages, partialText, askedUser };
+            return aborted
+                ? { ...output, status: 'aborted' }
+                : { ...output, status: 'failed', error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+}
+exports.TurnRunner = TurnRunner;
+//# sourceMappingURL=turn-runner.js.map

package/dist/agent/turn-runner.js.map

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

package/dist/agent/turn-runner.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=turn-runner.test.d.ts.map

package/dist/agent/turn-runner.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-runner.test.d.ts","sourceRoot":"","sources":["../../src/agent/turn-runner.test.ts"],"names":[],"mappings":""}