salmon-loop 0.3.1 → 0.4.1

package/dist/core/tools/session.js

@@ -8,7 +8,9 @@ import { CanonicalResponsesEventEmitter, } from '../streaming/canonical/canonica
 import { mapLlmStreamChunkToCanonicalStreamParts } from '../streaming/canonical/parts-from-llm-stream-chunk.js';
 import { ArtifactStore } from '../sub-agent/artifacts/store.js';
 import { Phase } from '../types/runtime.js';
+import { extractNetworkCode, extractProvider, extractStatusCode } from '../utils/error.js';
 import { isSafeRelativePath, normalizePath } from '../utils/path.js';
+import { isRecord } from '../utils/serialize.js';
 import { buildHeadlessToolInputPayload } from './headless-payload.js';
 import { toolToOpenAI } from './mapper.js';
 import { InMemoryLockManager } from './parallel/lock-manager.js';
@@ -17,6 +19,13 @@ import { ParallelScheduler } from './parallel/scheduler.js';
 import { isRecoverableToolInputErrorCode } from './recoverable-tool-errors.js';
 import { ToolCallAccumulator } from './streaming/ToolCallAccumulator.js';
 import { resolveVisibleToolSpecs } from './tool-visibility.js';
+function findLast(array, predicate) {
+    for (let i = array.length - 1; i >= 0; i--) {
+        if (predicate(array[i]))
+            return array[i];
+    }
+    return undefined;
+}
 function safeParseJson(argsText) {
     if (typeof argsText !== 'string') {
         return { ok: true, value: argsText };
@@ -126,7 +135,7 @@ function isArtifactHandleRecord(value) {
         typeof candidate.size === 'number');
 }
 function extractArtifactHandlesFromToolOutput(output) {
-    if (!isObjectRecord(output)) {
+    if (!isRecord(output)) {
         return {};
     }
     const patchArtifact = isArtifactHandleRecord(output.patchArtifact)
@@ -144,12 +153,12 @@ function extractRecentReadResult(params) {
     if (params.toolName !== 'fs.read' && params.toolName !== 'code.read') {
         return undefined;
     }
-    if (!isObjectRecord(params.output) || typeof params.output.content !== 'string') {
+    if (!isRecord(params.output) || typeof params.output.content !== 'string') {
         return undefined;
     }
     const args = safeParseJson(params.rawArgs);
     const argsValue = args.ok ? args.value : params.rawArgs;
-    if (!isObjectRecord(argsValue))
+    if (!isRecord(argsValue))
         return undefined;
     const file = argsValue.file ?? argsValue.file_path ?? argsValue.filePath ?? argsValue.path;
     if (typeof file !== 'string' || !file.trim())
@@ -703,7 +712,7 @@ export async function chatWithTools(initialMessages, chatOptions, session) {
             tool_calls: assistant.tool_calls,
         });
         const toolCalls = assistant.tool_calls || [];
-        if (!Array.isArray(toolCalls) || toolCalls.length === 0) {
+        if (toolCalls.length === 0) {
             if (session.llmOutput) {
                 emitLlmOutput({
                     emit: session.emit,
@@ -728,7 +737,7 @@ export async function chatWithTools(initialMessages, chatOptions, session) {
         message: `Tool calling exceeded maximum rounds (${maxRounds}); continuing without further tool execution`,
         timestamp: new Date(),
     });
-    const lastAssistant = [...messages].reverse().find((m) => m.role === 'assistant');
+    const lastAssistant = findLast(messages, (m) => m.role === 'assistant');
     if (session.llmOutput && lastAssistant?.content) {
         emitLlmOutput({
             emit: session.emit,
@@ -740,11 +749,8 @@ export async function chatWithTools(initialMessages, chatOptions, session) {
     }
     return lastAssistant || { role: 'assistant', content: '' };
 }
-function isObjectRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function isPlainObject(value) {
-    if (!isObjectRecord(value))
+    if (!isRecord(value))
         return false;
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
@@ -789,61 +795,6 @@ function coercePlanUpdatePatch(args) {
     }
     return { args, error: formatPlanUpdatePatchTypeError(describeValueType(patch)) };
 }
-function unwrapRetryError(err) {
-    if (!err || typeof err !== 'object')
-        return err;
-    const candidate = err;
-    if (candidate.lastError)
-        return candidate.lastError;
-    return err;
-}
-function extractStatusCode(err) {
-    const unwrapped = unwrapRetryError(err);
-    if (!unwrapped || typeof unwrapped !== 'object')
-        return undefined;
-    const meta = unwrapped?.meta;
-    if (meta && typeof meta === 'object' && typeof meta.statusCode === 'number') {
-        return meta.statusCode;
-    }
-    const statusCode = unwrapped?.statusCode;
-    if (typeof statusCode === 'number')
-        return statusCode;
-    const response = unwrapped?.response;
-    if (response && typeof response === 'object' && typeof response.status === 'number') {
-        return response.status;
-    }
-    return undefined;
-}
-function extractNetworkCode(err) {
-    const unwrapped = unwrapRetryError(err);
-    if (!unwrapped || typeof unwrapped !== 'object')
-        return undefined;
-    const code = unwrapped?.code;
-    if (typeof code === 'string')
-        return code;
-    const cause = unwrapped?.cause;
-    if (cause && typeof cause === 'object' && typeof cause.code === 'string') {
-        return cause.code;
-    }
-    const meta = unwrapped?.meta;
-    if (meta && typeof meta === 'object' && typeof meta.causeName === 'string') {
-        return meta.causeName;
-    }
-    return undefined;
-}
-function extractProvider(err) {
-    const unwrapped = unwrapRetryError(err);
-    if (!unwrapped || typeof unwrapped !== 'object')
-        return undefined;
-    const meta = unwrapped?.meta;
-    if (meta && typeof meta === 'object' && typeof meta.provider === 'string') {
-        return meta.provider;
-    }
-    const provider = unwrapped?.provider;
-    if (typeof provider === 'string')
-        return provider;
-    return undefined;
-}
 const ENABLE_TOOL_ARG_REPAIR = process.env.SALMONLOOP_ENABLE_TOOL_ARG_REPAIR === '1' ||
     process.env.SALMONLOOP_ENABLE_TOOL_ARG_REPAIR === 'true';
 const SAFE_INFERRED_EXTENSIONS = new Set([
@@ -901,7 +852,7 @@ function inferHighConfidenceFiles(instruction) {
     return Array.from(new Set(candidates));
 }
 function extractInstructionText(messages) {
-    const lastUser = [...messages].reverse().find((m) => m.role === 'user');
+    const lastUser = findLast(messages, (m) => m.role === 'user');
     const text = typeof lastUser?.content === 'string' ? lastUser.content : '';
     if (!text)
         return '';
@@ -921,7 +872,7 @@ function prepareToolCallRequests(calls) {
 async function runToolExecutionPlan(params) {
     const scheduler = new ParallelScheduler(params.session.toolstack.router, new InMemoryLockManager());
     const runSignal = params.signal ?? new AbortController().signal;
-    let result = (await scheduler.run(params.plan, { ...params.session.runtime, phase: params.phase }, runSignal));
+    let result = await scheduler.run(params.plan, { ...params.session.runtime, phase: params.phase }, runSignal);
     const persistEnabled = process.env.NODE_ENV !== 'test';
     const persistenceRoot = params.session.runtime.persistenceRoot || params.session.runtime.repoRoot;
     if (persistEnabled) {
@@ -943,10 +894,10 @@ async function runToolExecutionPlan(params) {
         await Promise.all(result.blockedApprovals.map(async (a) => {
             await waitForAuthorization?.(a.nodeId, runSignal);
         }));
-        result = (await scheduler.run(params.plan, { ...params.session.runtime, phase: params.phase }, runSignal, {
+        result = await scheduler.run(params.plan, { ...params.session.runtime, phase: params.phase }, runSignal, {
             initialResults: result.nodeResults,
             resumeBlockedApprovals: true,
-        }));
+        });
         if (persistEnabled) {
             await PlanPersistence.save(persistenceRoot, params.plan, result, {
                 repoRoot: params.session.runtime.repoRoot,
@@ -983,12 +934,14 @@ function applyStrictToolOutputSchemaValidation(params) {
 }
 async function executeToolCalls(session, phase, round, calls, messages, signal) {
     const prepared = prepareToolCallRequests(calls);
+    const specByName = new Map();
+    for (const spec of session.toolstack.registry.listAll()) {
+        specByName.set(spec.name, spec);
+    }
     const bucketByCallId = new Map();
     const preparedCounts = { regular: 0, agent: 0 };
     for (const item of prepared) {
-        const spec = typeof item.toolName === 'string'
-            ? session.toolstack.registry.listAll().find((s) => s.name === item.toolName)
-            : undefined;
+        const spec = typeof item.toolName === 'string' ? specByName.get(item.toolName) : undefined;
         const bucket = spec?.intent === 'AGENT' ? 'agent' : 'regular';
         bucketByCallId.set(item.callId, bucket);
         preparedCounts[bucket]++;
@@ -1031,7 +984,7 @@ async function executeToolCalls(session, phase, round, calls, messages, signal)
             ENABLE_TOOL_ARG_REPAIR &&
             phase === Phase.EXPLORE &&
             normalizedToolName === 'fs.read' &&
-            isObjectRecord(argsValue) &&
+            isRecord(argsValue) &&
             typeof argsValue.file !== 'string') {
             const instruction = extractInstructionText(messages);
             const inferred = inferHighConfidenceFiles(instruction);
@@ -1040,7 +993,7 @@ async function executeToolCalls(session, phase, round, calls, messages, signal)
             }
         }
         let planUpdatePatchError;
-        if (parsedArgsOk && normalizedToolName === 'plan.update' && isObjectRecord(argsValue)) {
+        if (parsedArgsOk && normalizedToolName === 'plan.update' && isRecord(argsValue)) {
             const patchGuard = coercePlanUpdatePatch(argsValue);
             argsValue = patchGuard.args;
             if (patchGuard.coercedPatchSource) {
@@ -1056,9 +1009,7 @@ async function executeToolCalls(session, phase, round, calls, messages, signal)
         const input = session.eventPayload?.includeToolInput && parsedArgsOk
             ? buildHeadlessToolInputPayload(argsValue)
             : undefined;
-        const spec = typeof toolName === 'string'
-            ? session.toolstack.registry.listAll().find((s) => s.name === toolName)
-            : undefined;
+        const spec = typeof toolName === 'string' ? specByName.get(toolName) : undefined;
         if (typeof toolName === 'string') {
             session.emit?.({
                 type: 'log',
@@ -1177,7 +1128,8 @@ async function executeToolCalls(session, phase, round, calls, messages, signal)
         };
         const patchCoercionSource = patchCoercionByCallId.get(callId);
         if (patchCoercionSource) {
-            parsedAuditEntry.coercedPatchSource = patchCoercionSource;
+            parsedAuditEntry.coercedPatchSource =
+                patchCoercionSource;
         }
         session.toolCallingAudit?.event(parsedAuditEntry);
         if (planUpdatePatchError) {
@@ -1269,9 +1221,10 @@ async function executeToolCalls(session, phase, round, calls, messages, signal)
         if (result.status !== 'ok' &&
             result.error?.code === 'INTERRUPT_REQUIRED' &&
             result.meta?.interrupt) {
-            const err = new Error(result.error.message || 'Interrupt required');
-            err.code = 'INTERRUPT_REQUIRED';
-            err.interrupt = result.meta.interrupt;
+            const err = Object.assign(new Error(result.error.message || 'Interrupt required'), {
+                code: 'INTERRUPT_REQUIRED',
+                interrupt: result.meta.interrupt,
+            });
             throw err;
         }
         if (result.status !== 'ok') {
@@ -1295,26 +1248,30 @@ async function executeToolCalls(session, phase, round, calls, messages, signal)
             };
             const patchCoercionSource = patchCoercionByCallId.get(callId);
             if (patchCoercionSource) {
-                errorAuditEntry.coercedPatchSource = patchCoercionSource;
+                errorAuditEntry.coercedPatchSource =
+                    patchCoercionSource;
             }
             session.toolCallingAudit?.event(errorAuditEntry);
         }
         else {
-            const toolResultOutputOk = isObjectRecord(result.output) && typeof result.output.ok === 'boolean'
+            const toolResultOutputOk = isRecord(result.output) && typeof result.output.ok === 'boolean'
                 ? result.output.ok
                 : undefined;
             const artifacts = extractArtifactHandlesFromToolOutput(result.output);
-            const recentReadArtifact = await persistRecentReadArtifact({
-                toolName: typeof toolName === 'string' ? toolName : 'unknown',
-                rawArgs,
-                output: result.output,
-            });
-            const toolResultPreviewArtifact = await persistToolResultPreviewArtifact({
-                toolName: typeof toolName === 'string' ? toolName : 'unknown',
-                output: result.output,
-                summary: result.summary,
-                outputSummary: result.outputSummary,
-            });
+            const resolvedToolName = typeof toolName === 'string' ? toolName : 'unknown';
+            const [recentReadArtifact, toolResultPreviewArtifact] = await Promise.all([
+                persistRecentReadArtifact({
+                    toolName: resolvedToolName,
+                    rawArgs,
+                    output: result.output,
+                }),
+                persistToolResultPreviewArtifact({
+                    toolName: resolvedToolName,
+                    output: result.output,
+                    summary: result.summary,
+                    outputSummary: result.outputSummary,
+                }),
+            ]);
             session.toolCallingAudit?.event({
                 timestamp: new Date().toISOString(),
                 phase,
@@ -1410,9 +1367,9 @@ export async function chatWithToolsStreaming(initialMessages, chatOptions, sessi
                         statusCode: extractStatusCode(e),
                         networkCode: extractNetworkCode(e),
                         errorName: e instanceof Error ? e.name : 'UnknownError',
-                        errorCode: typeof e?.llmCode === 'string'
+                        errorCode: isRecord(e) && typeof e.llmCode === 'string'
                             ? e.llmCode
-                            : typeof e?.code === 'string'
+                            : isRecord(e) && typeof e.code === 'string'
                                 ? e.code
                                 : undefined,
                     }, { source: 'llm', severity: 'low', scope: 'session', phase });
@@ -1470,7 +1427,7 @@ export async function chatWithToolsStreaming(initialMessages, chatOptions, sessi
                 }, { source: 'llm', severity: 'low', scope: 'session', phase });
                 messages.push(assistant);
                 const calls = assistant.tool_calls || [];
-                if (!Array.isArray(calls) || calls.length === 0) {
+                if (calls.length === 0) {
                     if (session.llmOutput) {
                         emitLlmStreamEnd({
                             emit: session.emit,
@@ -1509,7 +1466,7 @@ export async function chatWithToolsStreaming(initialMessages, chatOptions, sessi
         message: `Tool calling exceeded maximum rounds (${maxRounds}); continuing without further tool execution`,
         timestamp: new Date(),
     });
-    const lastAssistant = [...messages].reverse().find((m) => m.role === 'assistant');
+    const lastAssistant = findLast(messages, (m) => m.role === 'assistant');
     return lastAssistant || { role: 'assistant', content: '' };
 }
 //# sourceMappingURL=session.js.map

package/dist/core/tools/streaming/ToolCallAccumulator.js

@@ -1,6 +1,4 @@
-function isRecord(value) {
-    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
+import { isRecord } from '../../utils/serialize.js';
 function mergeToolCall(prev, next) {
     if (!isRecord(next))
         return prev ?? next;

package/dist/core/tools/tool-visibility.js

@@ -46,7 +46,8 @@ export function resolvePhaseVisibleTools(params) {
 export function resolveVisibleToolSpecs(params) {
     if (!params.toolstack)
         return [];
-    const allowedSpecs = params.toolstack.registry.listAll().filter((spec) => params.toolstack.policy.decide(params.phase, spec, {
+    const { toolstack } = params;
+    const allowedSpecs = toolstack.registry.listAll().filter((spec) => toolstack.policy.decide(params.phase, spec, {
         worktreeRoot: params.worktreeRoot,
         flowMode: params.flowMode,
     }).allowed);

package/dist/core/tools/types.js

@@ -7,4 +7,14 @@ export const TOOL_INTENTS = [
     'AGENT',
     'REPORT',
 ];
+/**
+ * Type-safe helper to create a fully-formed ToolSpec from a spec definition and executor.
+ * Eliminates the `{ ...spec, executor: exec as any }` boilerplate pattern.
+ *
+ * The executor parameter accepts a superset of ToolRuntimeCtx (e.g., with phase narrowed
+ * to non-optional) to support tools that require the router-injected phase field.
+ */
+export function defineTool(spec, executor) {
+    return { ...spec, executor: executor };
+}
 //# sourceMappingURL=types.js.map

package/dist/core/utils/error.js

@@ -0,0 +1,79 @@
+import { isRecord } from './serialize.js';
+/**
+ * Extract a human-readable error message from an unknown thrown value.
+ * Handles Error instances, strings, and falls back to String(value).
+ */
+export function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    return String(error);
+}
+/**
+ * Unwrap retry-style errors that wrap the real error in a `lastError` property.
+ */
+export function unwrapRetryError(err) {
+    if (!isRecord(err))
+        return err;
+    if (err.lastError)
+        return err.lastError;
+    return err;
+}
+/**
+ * Extract an HTTP-style status code from an error object.
+ * Checks: meta.statusCode, statusCode, response.status
+ */
+export function extractStatusCode(err) {
+    const unwrapped = unwrapRetryError(err);
+    if (!isRecord(unwrapped))
+        return undefined;
+    const meta = unwrapped.meta;
+    if (isRecord(meta) && typeof meta.statusCode === 'number') {
+        return meta.statusCode;
+    }
+    if (typeof unwrapped.statusCode === 'number')
+        return unwrapped.statusCode;
+    const response = unwrapped.response;
+    if (isRecord(response) && typeof response.status === 'number') {
+        return response.status;
+    }
+    return undefined;
+}
+/**
+ * Extract a network error code from an error object.
+ * Checks: code, cause.code, meta.causeName
+ */
+export function extractNetworkCode(err) {
+    const unwrapped = unwrapRetryError(err);
+    if (!isRecord(unwrapped))
+        return undefined;
+    if (typeof unwrapped.code === 'string')
+        return unwrapped.code;
+    const cause = unwrapped.cause;
+    if (isRecord(cause) && typeof cause.code === 'string') {
+        return cause.code;
+    }
+    const meta = unwrapped.meta;
+    if (isRecord(meta) && typeof meta.causeName === 'string') {
+        return meta.causeName;
+    }
+    return undefined;
+}
+/**
+ * Extract a provider name from an error object.
+ * Checks: meta.provider, provider
+ */
+export function extractProvider(err) {
+    const unwrapped = unwrapRetryError(err);
+    if (!isRecord(unwrapped))
+        return undefined;
+    const meta = unwrapped.meta;
+    if (isRecord(meta) && typeof meta.provider === 'string') {
+        return meta.provider;
+    }
+    if (typeof unwrapped.provider === 'string')
+        return unwrapped.provider;
+    return undefined;
+}
+//# sourceMappingURL=error.js.map

package/dist/core/utils/serialize.js

@@ -0,0 +1,63 @@
+/**
+ * Safely serialize a value to JSON string.
+ * Returns '[Unserializable]' if JSON.stringify throws and String() also fails.
+ */
+export function safeStringify(value, options) {
+    try {
+        const raw = JSON.stringify(value, null, options?.indent);
+        if (options?.maxLength && raw.length > options.maxLength) {
+            return `${raw.slice(0, options.maxLength)}...`;
+        }
+        return raw;
+    }
+    catch {
+        try {
+            return String(value);
+        }
+        catch {
+            return '[Unserializable]';
+        }
+    }
+}
+/**
+ * Type guard: narrow an unknown value to Record<string, unknown>.
+ * Returns false for arrays, primitives, null, and undefined.
+ */
+export function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+/**
+ * Narrow an unknown value to a Record<string, unknown>.
+ * Returns an empty object for non-object inputs (arrays, primitives, null, undefined).
+ */
+export function asRecord(value) {
+    return isRecord(value) ? value : {};
+}
+/**
+ * Extract a string value from a record by key.
+ * Returns null if the key doesn't exist or the value isn't a string.
+ */
+export function getString(record, key) {
+    const value = record[key];
+    return typeof value === 'string' ? value : null;
+}
+/**
+ * Extract a nested record from a record by key.
+ * Returns null if the key doesn't exist or the value isn't a record.
+ */
+export function getRecord(record, key) {
+    const value = record[key];
+    return isRecord(value) ? value : null;
+}
+/**
+ * Extract a human-readable error message from an unknown thrown value.
+ * Handles Error instances, strings, and falls back to String(value).
+ */
+export function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    return String(error);
+}
+//# sourceMappingURL=serialize.js.map

package/dist/core/utils/zod.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+/**
+ * Unwrap Zod wrapper types (ZodPipe, ZodOptional, ZodNullable, ZodDefault)
+ * to get the underlying schema. Useful for schema generation and hint building.
+ */
+export function unwrapZodSchema(schema) {
+    let current = schema;
+    for (let depth = 0; depth < 20; depth++) {
+        if (current instanceof z.ZodPipe) {
+            current = current.def.out;
+            continue;
+        }
+        if (current instanceof z.ZodOptional) {
+            current = current.def.innerType;
+            continue;
+        }
+        if (current instanceof z.ZodNullable) {
+            current = current.def.innerType;
+            continue;
+        }
+        if (current instanceof z.ZodDefault) {
+            current = current.def.innerType;
+            continue;
+        }
+        break;
+    }
+    return current;
+}
+//# sourceMappingURL=zod.js.map

package/dist/core/workspace/capabilities.js

@@ -1,6 +1,7 @@
 import { access, constants } from '../adapters/fs/node-fs.js';
 import { GitAdapter } from '../adapters/git/git-adapter.js';
 import { LIMITS } from '../config/limits.js';
+import { errorMessage } from '../utils/error.js';
 const PROBE_LIMITS = { maxStdoutBytes: 4_096, maxStderrChars: 4_096 };
 function gitFailureReason(result) {
     if (result.error?.code === 'ENOENT')
@@ -23,7 +24,7 @@ async function detectFileSystemCapability(workspacePath) {
         return {
             readable: false,
             writable: false,
-            reason: error instanceof Error ? error.message : String(error),
+            reason: errorMessage(error),
         };
     }
     try {
@@ -34,7 +35,7 @@ async function detectFileSystemCapability(workspacePath) {
         return {
             readable: true,
             writable: false,
-            reason: error instanceof Error ? error.message : String(error),
+            reason: errorMessage(error),
         };
     }
 }

package/dist/integrations/langfuse/litellm-langfuse-outcome-reporter.js

@@ -1,6 +1,7 @@
 import { readFile } from '../../core/adapters/fs/node-fs.js';
 import { recordAuditEvent } from '../../core/observability/audit-trail.js';
 import { getLogger } from '../../core/observability/logger.js';
+import { isRecord } from '../../core/utils/serialize.js';
 import { text } from '../../locales/index.js';
 function nowIso() {
     return new Date().toISOString();
@@ -43,7 +44,7 @@ function buildPhaseDurations(traces) {
         return undefined;
     const out = {};
     for (const t of traces) {
-        if (!t || typeof t !== 'object')
+        if (!isRecord(t))
             continue;
         const name = t.name;
         const duration = t.duration;
@@ -69,13 +70,13 @@ async function tryReadAuditJson(auditPath) {
 }
 function extractNetworkErrorCode(error) {
     const allow = (value) => typeof value === 'string' && /^[A-Z0-9_]{2,32}$/.test(value) ? value : undefined;
-    if (error && typeof error === 'object') {
-        const e = error;
-        return (allow(e.code) ||
-            allow(e.cause?.code) ||
-            allow(e.cause?.errno) ||
-            allow(e.errno) ||
-            allow(e.cause?.name));
+    if (isRecord(error)) {
+        const cause = isRecord(error.cause) ? error.cause : undefined;
+        return (allow(error.code) ||
+            allow(cause?.code) ||
+            allow(cause?.errno) ||
+            allow(error.errno) ||
+            allow(cause?.name));
     }
     return undefined;
 }

package/dist/locales/en.js

@@ -770,7 +770,8 @@ Please return the patch in PURE unified diff format:`;
             missionFailedWithReason: (reason) => `Smallfry mission failed: ${reason}`,
         },
         ui: {
-            spawnToolDescription: 'Delegate a concrete sub-task to a specialized sub-agent. This is not a no-argument action: always provide agent_ref and task. Use agent_ref="explorer" for read-only investigation, "reviewer" for audit, "surgeon" for implementation proposals, or "cleaner" for lint/format cleanup. Keep task self-contained with relevant files and the exact deliverable. Omit session_target unless shared context is explicitly required.',
+            spawnToolDescription: 'Delegate a concrete sub-task to a specialized sub-agent. This is not a no-argument action: always provide agent_ref and task. Use agent_ref="explorer" for read-only investigation, "reviewer" for audit, "surgeon" for implementation proposals, or "cleaner" for lint/format cleanup. Keep task self-contained with relevant files and the exact deliverable. Omit session_target unless shared context is explicitly required. Set async=true to get a handle immediately and use agent_await to collect the result later.',
+            awaitToolDescription: 'Wait for an async sub-agent (spawned with agent_dispatch async=true) to complete and return its result. Pass the agentId from the dispatch handle.',
             progressTitle: (id) => `[Smallfry: ${id}]`,
         },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "salmon-loop",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "A chat-first coding agent CLI for safe, reviewable repository changes",
   "type": "module",
   "bin": {