@amodalai/runtime 0.1.26 → 0.2.1

package/dist/src/tools/web-search-tool.test.js

@@ -0,0 +1,153 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { createWebSearchTool } from './web-search-tool.js';
+import { ProviderError } from '../errors.js';
+function makeCtx(overrides) {
+    return {
+        request: vi.fn(),
+        store: vi.fn(),
+        env: vi.fn(),
+        log: vi.fn(),
+        user: { roles: [] },
+        signal: AbortSignal.timeout(5000),
+        sessionId: 'test-session',
+        ...overrides,
+    };
+}
+function makeProvider(result) {
+    return {
+        model: 'gemini-2.5-flash',
+        search: vi.fn().mockResolvedValue(result),
+        fetchUrl: vi.fn(),
+    };
+}
+// Helper to execute the tool and get a typed result.
+async function runTool(ctx, params) {
+    const tool = createWebSearchTool();
+    const raw = await tool.execute(params, ctx);
+    return raw;
+}
+describe('web_search tool', () => {
+    it('returns a friendly error when no searchProvider is configured', async () => {
+        const ctx = makeCtx();
+        const result = await runTool(ctx, { query: 'anything' });
+        expect(result.status).toBe('error');
+        expect(result.content).toContain('not configured');
+        expect(result.content).toContain('webTools');
+    });
+    it('formats synthesized answer with numbered source citations', async () => {
+        const provider = makeProvider({
+            text: 'Node.js 22 is the current LTS.',
+            sources: [
+                { uri: 'https://nodejs.org/en/blog/release/v22.0.0', title: 'Node.js 22 Release' },
+                { uri: 'https://en.wikipedia.org/wiki/Node.js' },
+            ],
+        });
+        const ctx = makeCtx({ searchProvider: provider });
+        const result = await runTool(ctx, { query: 'latest node version' });
+        expect(result.status).toBe('ok');
+        expect(result.content).toContain('Node.js 22 is the current LTS.');
+        expect(result.content).toContain('[1] https://nodejs.org/en/blog/release/v22.0.0 — Node.js 22 Release');
+        expect(result.content).toContain('[2] https://en.wikipedia.org/wiki/Node.js');
+        expect(result.source_count).toBe(2);
+    });
+    it('notes when no sources were returned', async () => {
+        const provider = makeProvider({ text: 'Answer without sources.', sources: [] });
+        const ctx = makeCtx({ searchProvider: provider });
+        const result = await runTool(ctx, { query: 'something' });
+        expect(result.status).toBe('ok');
+        expect(result.content).toContain('(no sources cited)');
+        expect(result.source_count).toBe(0);
+    });
+    it('caps source list at max_results', async () => {
+        const sources = Array.from({ length: 8 }, (_, i) => ({ uri: `https://example.com/${String(i)}` }));
+        const provider = makeProvider({ text: 'answer', sources });
+        const ctx = makeCtx({ searchProvider: provider });
+        const result = await runTool(ctx, { query: 'q', max_results: 3 });
+        expect(result.source_count).toBe(3);
+        expect(result.content).toContain('[1]');
+        expect(result.content).toContain('[3]');
+        expect(result.content).not.toContain('[4]');
+    });
+    it('passes ctx.signal through to the provider', async () => {
+        const searchMock = vi.fn().mockResolvedValue({ text: 'x', sources: [] });
+        const provider = {
+            model: 'test',
+            search: searchMock,
+            fetchUrl: vi.fn(),
+        };
+        const signal = AbortSignal.timeout(1000);
+        const ctx = makeCtx({ searchProvider: provider, signal });
+        await runTool(ctx, { query: 'q' });
+        expect(searchMock).toHaveBeenCalledWith('q', { signal });
+    });
+    it('truncates very long output with a marker', async () => {
+        const huge = 'a'.repeat(50_000);
+        const provider = makeProvider({ text: huge, sources: [] });
+        const ctx = makeCtx({ searchProvider: provider });
+        const result = await runTool(ctx, { query: 'q' });
+        expect(result.status).toBe('ok');
+        expect(result.content.length).toBeLessThan(9_000); // 2000 tokens × 4 chars/token = 8000
+        expect(result.content).toContain('(truncated)');
+    });
+    describe('provider error classification (retry guidance)', () => {
+        function makeProviderErrorProvider(status) {
+            const err = new ProviderError('Grounded search failed', {
+                provider: 'google',
+                statusCode: status,
+                retryable: status >= 500,
+            });
+            return {
+                model: 'test',
+                search: vi.fn().mockRejectedValue(err),
+                fetchUrl: vi.fn(),
+            };
+        }
+        it('tells the agent NOT to retry on 401 (auth)', async () => {
+            const ctx = makeCtx({ searchProvider: makeProviderErrorProvider(401) });
+            const result = await runTool(ctx, { query: 'q' });
+            expect(result.status).toBe('error');
+            expect(result.content).toContain('DO NOT retry');
+            expect(result.content).toContain('GOOGLE_API_KEY');
+            expect(result.retryable).toBe(false);
+        });
+        it('tells the agent NOT to retry on 400 (bad key)', async () => {
+            const ctx = makeCtx({ searchProvider: makeProviderErrorProvider(400) });
+            const result = await runTool(ctx, { query: 'q' });
+            expect(result.content).toContain('DO NOT retry');
+            expect(result.retryable).toBe(false);
+        });
+        it('tells the agent NOT to retry on 429 (quota)', async () => {
+            const ctx = makeCtx({ searchProvider: makeProviderErrorProvider(429) });
+            const result = await runTool(ctx, { query: 'q' });
+            expect(result.content).toContain('rate-limited');
+            expect(result.content).toContain('DO NOT retry');
+            expect(result.retryable).toBe(false);
+        });
+        it('says retry is OK on 5xx (transient)', async () => {
+            const ctx = makeCtx({ searchProvider: makeProviderErrorProvider(503) });
+            const result = await runTool(ctx, { query: 'q' });
+            expect(result.content).toContain('transient');
+            expect(result.content).toContain('may retry');
+            expect(result.retryable).toBe(true);
+        });
+    });
+    it('wraps unexpected (non-ProviderError) errors in ToolExecutionError', async () => {
+        const provider = {
+            model: 'test',
+            search: vi.fn().mockRejectedValue(new Error('boom')),
+            fetchUrl: vi.fn(),
+        };
+        const ctx = makeCtx({ searchProvider: provider });
+        const tool = createWebSearchTool();
+        await expect(tool.execute({ query: 'q' }, ctx)).rejects.toMatchObject({
+            name: 'ToolExecutionError',
+            toolName: 'web_search',
+        });
+    });
+});
+//# sourceMappingURL=web-search-tool.test.js.map

package/dist/src/tools/web-search-tool.test.js.map

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

package/dist/src/tools/web-tools-shared.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Shared helpers for the `web_search` and `fetch_url` tools.
+ *
+ * - `MAX_WEB_TOOL_RESULT_TOKENS` — uniform 2000-token cap on tool output.
+ * - `truncateToTokens()` — token-estimate truncation using the 4 chars/token
+ *   heuristic (matches `packages/runtime/src/agent/token-estimate.ts`).
+ */
+/** Max token budget for any single web-tool result, before truncation. */
+export declare const MAX_WEB_TOOL_RESULT_TOKENS = 2000;
+/**
+ * Truncate a string to fit within `maxTokens` tokens, using the same
+ * 4-chars-per-token heuristic the rest of the runtime uses. When the
+ * input fits, it is returned unchanged; otherwise it is trimmed and a
+ * truncation marker is appended so the model sees that content was cut.
+ */
+export declare function truncateToTokens(text: string, maxTokens: number): string;

package/dist/src/tools/web-tools-shared.js

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Shared helpers for the `web_search` and `fetch_url` tools.
+ *
+ * - `MAX_WEB_TOOL_RESULT_TOKENS` — uniform 2000-token cap on tool output.
+ * - `truncateToTokens()` — token-estimate truncation using the 4 chars/token
+ *   heuristic (matches `packages/runtime/src/agent/token-estimate.ts`).
+ */
+/** Max token budget for any single web-tool result, before truncation. */
+export const MAX_WEB_TOOL_RESULT_TOKENS = 2000;
+/** Chars-per-token approximation — matches `estimateTokenCount()`. */
+const CHARS_PER_TOKEN = 4;
+/** Suffix appended when content is truncated, so the model knows it is clipped. */
+const TRUNCATION_SUFFIX = '\n\n…(truncated)';
+/**
+ * Truncate a string to fit within `maxTokens` tokens, using the same
+ * 4-chars-per-token heuristic the rest of the runtime uses. When the
+ * input fits, it is returned unchanged; otherwise it is trimmed and a
+ * truncation marker is appended so the model sees that content was cut.
+ */
+export function truncateToTokens(text, maxTokens) {
+    const maxChars = maxTokens * CHARS_PER_TOKEN;
+    if (text.length <= maxChars)
+        return text;
+    const roomForSuffix = Math.max(0, maxChars - TRUNCATION_SUFFIX.length);
+    return text.slice(0, roomForSuffix) + TRUNCATION_SUFFIX;
+}
+//# sourceMappingURL=web-tools-shared.js.map

package/dist/src/tools/web-tools-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-tools-shared.js","sourceRoot":"","sources":["../../../src/tools/web-tools-shared.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAE/C,sEAAsE;AACtE,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B,mFAAmF;AACnF,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,SAAiB;IAC9D,MAAM,QAAQ,GAAG,SAAS,GAAG,eAAe,CAAC;IAC7C,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACvE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,GAAG,iBAAiB,CAAC;AAC1D,CAAC"}

package/dist/src/types.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { z } from 'zod';
-import type { AutomationDefinition, Question } from '@amodalai/core';
+import type { AutomationDefinition } from '@amodalai/core';
 export declare const ChatRequestSchema: z.ZodObject<{
     /** The user message to send to the agent */
     message: z.ZodString;
@@ -13,21 +13,36 @@ export declare const ChatRequestSchema: z.ZodObject<{
     /** Optional role override for this session */
     role: z.ZodOptional<z.ZodString>;
     /** Optional session type — controls which skills, tools, KB docs load */
-    session_type: z.ZodOptional<z.ZodString>;
+    session_type: z.ZodOptional<z.ZodEnum<["chat", "admin", "automation"]>>;
     /** Optional deployment ID — load a specific snapshot instead of the active one */
     deploy_id: z.ZodOptional<z.ZodString>;
+    /**
+     * Optional session-wide **token** budget cap (not dollars; cost varies
+     * by model). When cumulative usage reaches this value the loop
+     * terminates with `reason: 'budget_exceeded'`. Absent = no cap.
+     *
+     * This is a **soft ceiling** — the check runs after each turn, so a
+     * single in-flight turn can overshoot by up to `maxOutputTokens` +
+     * tool result sizes. Size the cap ~20% below your hard limit.
+     *
+     * Distinct from the LLM-API `max_tokens` (per-call output cap) —
+     * this is a session-wide cumulative total across all turns.
+     */
+    max_session_tokens: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     message: string;
     session_id?: string | undefined;
     role?: string | undefined;
-    session_type?: string | undefined;
+    session_type?: "chat" | "admin" | "automation" | undefined;
     deploy_id?: string | undefined;
+    max_session_tokens?: number | undefined;
 }, {
     message: string;
     session_id?: string | undefined;
     role?: string | undefined;
-    session_type?: string | undefined;
+    session_type?: "chat" | "admin" | "automation" | undefined;
     deploy_id?: string | undefined;
+    max_session_tokens?: number | undefined;
 }>;
 export type ChatRequest = z.infer<typeof ChatRequestSchema>;
 export declare const WebhookPayloadSchema: z.ZodObject<{
@@ -75,12 +90,13 @@ export declare enum SSEEventType {
     KBProposal = "kb_proposal",
     CredentialSaved = "credential_saved",
     Approved = "approved",
-    AskUser = "ask_user",
     ExploreStart = "explore_start",
     ExploreEnd = "explore_end",
     PlanMode = "plan_mode",
     FieldScrub = "field_scrub",
     ConfirmationRequired = "confirmation_required",
+    CompactionStart = "compaction_start",
+    CompactionEnd = "compaction_end",
     ToolLog = "tool_log",
     Error = "error",
     Done = "done"
@@ -160,15 +176,14 @@ export interface SSEApprovedEvent {
     preview_id: string;
     timestamp: string;
 }
-export interface SSEAskUserEvent {
-    type: SSEEventType.AskUser;
-    ask_id: string;
-    questions: Question[];
-    timestamp: string;
-}
 export interface SSEDoneEvent {
     type: SSEEventType.Done;
     timestamp: string;
+    /**
+     * Why the loop stopped. Consumers use this to distinguish normal
+     * termination from enforced caps (budget, turns, loop detection).
+     */
+    reason?: 'model_stop' | 'max_turns' | 'user_abort' | 'error' | 'budget_exceeded' | 'loop_detected';
     usage?: {
         input_tokens: number;
         output_tokens: number;
@@ -209,7 +224,20 @@ export interface SSEConfirmationRequiredEvent {
     escalated: boolean;
     timestamp: string;
 }
-export type SSEEvent = SSEInitEvent | SSETextDeltaEvent | SSEToolCallStartEvent | SSEToolCallResultEvent | SSESubagentEvent | SSESkillActivatedEvent | SSEWidgetEvent | SSEKBProposalEvent | SSECredentialSavedEvent | SSEApprovedEvent | SSEAskUserEvent | SSEExploreStartEvent | SSEExploreEndEvent | SSEPlanModeEvent | SSEFieldScrubEvent | SSEConfirmationRequiredEvent | SSEToolLogEvent | SSEErrorEvent | SSEDoneEvent;
+export interface SSECompactionStartEvent {
+    type: SSEEventType.CompactionStart;
+    estimated_tokens: number;
+    threshold: number;
+    timestamp: string;
+}
+export interface SSECompactionEndEvent {
+    type: SSEEventType.CompactionEnd;
+    tokens_before: number;
+    tokens_after: number;
+    compaction_tokens: number;
+    timestamp: string;
+}
+export type SSEEvent = SSEInitEvent | SSETextDeltaEvent | SSEToolCallStartEvent | SSEToolCallResultEvent | SSESubagentEvent | SSESkillActivatedEvent | SSEWidgetEvent | SSEKBProposalEvent | SSECredentialSavedEvent | SSEApprovedEvent | SSEExploreStartEvent | SSEExploreEndEvent | SSEPlanModeEvent | SSEFieldScrubEvent | SSEConfirmationRequiredEvent | SSECompactionStartEvent | SSECompactionEndEvent | SSEToolLogEvent | SSEErrorEvent | SSEDoneEvent;
 export interface SSEToolLogEvent {
     type: SSEEventType.ToolLog;
     tool_name: string;

package/dist/src/types.js

@@ -15,9 +15,22 @@ export const ChatRequestSchema = z.object({
     /** Optional role override for this session */
     role: z.string().optional(),
     /** Optional session type — controls which skills, tools, KB docs load */
-    session_type: z.string().optional(),
+    session_type: z.enum(['chat', 'admin', 'automation']).optional(),
     /** Optional deployment ID — load a specific snapshot instead of the active one */
     deploy_id: z.string().optional(),
+    /**
+     * Optional session-wide **token** budget cap (not dollars; cost varies
+     * by model). When cumulative usage reaches this value the loop
+     * terminates with `reason: 'budget_exceeded'`. Absent = no cap.
+     *
+     * This is a **soft ceiling** — the check runs after each turn, so a
+     * single in-flight turn can overshoot by up to `maxOutputTokens` +
+     * tool result sizes. Size the cap ~20% below your hard limit.
+     *
+     * Distinct from the LLM-API `max_tokens` (per-call output cap) —
+     * this is a session-wide cumulative total across all turns.
+     */
+    max_session_tokens: z.number().int().positive().optional(),
 });
 export const WebhookPayloadSchema = z.object({
     /** Optional event data passed to the automation prompt */
@@ -38,12 +51,13 @@ export var SSEEventType;
     SSEEventType["KBProposal"] = "kb_proposal";
     SSEEventType["CredentialSaved"] = "credential_saved";
     SSEEventType["Approved"] = "approved";
-    SSEEventType["AskUser"] = "ask_user";
     SSEEventType["ExploreStart"] = "explore_start";
     SSEEventType["ExploreEnd"] = "explore_end";
     SSEEventType["PlanMode"] = "plan_mode";
     SSEEventType["FieldScrub"] = "field_scrub";
     SSEEventType["ConfirmationRequired"] = "confirmation_required";
+    SSEEventType["CompactionStart"] = "compaction_start";
+    SSEEventType["CompactionEnd"] = "compaction_end";
     SSEEventType["ToolLog"] = "tool_log";
     SSEEventType["Error"] = "error";
     SSEEventType["Done"] = "done";

package/dist/src/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,4CAA4C;IAC5C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,qDAAqD;IACrD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,8CAA8C;IAC9C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,yEAAyE;IACzE,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACnC,kFAAkF;IAClF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,0DAA0D;IAC1D,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC;AAoCH,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,MAAM,CAAN,IAAY,YAoBX;AApBD,WAAY,YAAY;IACtB,6BAAa,CAAA;IACb,wCAAwB,CAAA;IACxB,iDAAiC,CAAA;IACjC,mDAAmC,CAAA;IACnC,gDAAgC,CAAA;IAChC,kDAAkC,CAAA;IAClC,iCAAiB,CAAA;IACjB,0CAA0B,CAAA;IAC1B,oDAAoC,CAAA;IACpC,qCAAqB,CAAA;IACrB,oCAAoB,CAAA;IACpB,8CAA8B,CAAA;IAC9B,0CAA0B,CAAA;IAC1B,sCAAsB,CAAA;IACtB,0CAA0B,CAAA;IAC1B,8DAA8C,CAAA;IAC9C,oCAAoB,CAAA;IACpB,+BAAe,CAAA;IACf,6BAAa,CAAA;AACf,CAAC,EApBW,YAAY,KAAZ,YAAY,QAoBvB"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,4CAA4C;IAC5C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,qDAAqD;IACrD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,8CAA8C;IAC9C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,yEAAyE;IACzE,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChE,kFAAkF;IAClF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC;;;;;;;;;;;OAWG;IACH,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC3D,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,0DAA0D;IAC1D,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC;AAoCH,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,MAAM,CAAN,IAAY,YAqBX;AArBD,WAAY,YAAY;IACtB,6BAAa,CAAA;IACb,wCAAwB,CAAA;IACxB,iDAAiC,CAAA;IACjC,mDAAmC,CAAA;IACnC,gDAAgC,CAAA;IAChC,kDAAkC,CAAA;IAClC,iCAAiB,CAAA;IACjB,0CAA0B,CAAA;IAC1B,oDAAoC,CAAA;IACpC,qCAAqB,CAAA;IACrB,8CAA8B,CAAA;IAC9B,0CAA0B,CAAA;IAC1B,sCAAsB,CAAA;IACtB,0CAA0B,CAAA;IAC1B,8DAA8C,CAAA;IAC9C,oDAAoC,CAAA;IACpC,gDAAgC,CAAA;IAChC,oCAAoB,CAAA;IACpB,+BAAe,CAAA;IACf,6BAAa,CAAA;AACf,CAAC,EArBW,YAAY,KAAZ,YAAY,QAqBvB"}