salmon-loop 0.3.2 → 0.5.0

package/dist/core/sub-agent/summary.js

@@ -0,0 +1,96 @@
+/**
+ * Sub-agent result synthesis.
+ *
+ * Detects file-level conflicts between sub-agent patches
+ * and generates structured summaries for parent injection.
+ */
+/**
+ * Extract file paths touched by a unified diff.
+ * Parses diff headers (lines starting with "--- a/" and "+++ b/").
+ */
+export function extractDiffFiles(patch) {
+    const files = new Set();
+    const lines = patch.split('\n');
+    for (const line of lines) {
+        if (line.startsWith('+++ b/')) {
+            files.add(line.slice(6));
+        }
+    }
+    return Array.from(files);
+}
+/**
+ * Detect file-level conflicts across multiple sub-agent results.
+ * Two agents conflict if they both modify the same file.
+ */
+export function detectConflicts(results) {
+    const fileToAgents = new Map();
+    for (const { agentId, result } of results) {
+        if (!result.finalPatch || typeof result.finalPatch !== 'string')
+            continue;
+        const files = extractDiffFiles(result.finalPatch);
+        for (const file of files) {
+            const agents = fileToAgents.get(file) ?? [];
+            agents.push(agentId);
+            fileToAgents.set(file, agents);
+        }
+    }
+    const conflicts = [];
+    for (const [file, agents] of fileToAgents) {
+        if (agents.length > 1) {
+            conflicts.push({ file, agents });
+        }
+    }
+    return conflicts;
+}
+/**
+ * Generate a structured summary of all sub-agent results.
+ */
+export function generateSubAgentSummary(results) {
+    const conflicts = detectConflicts(results);
+    const changedFiles = new Set();
+    let succeeded = 0;
+    let failed = 0;
+    let totalTokens = 0;
+    for (const { result } of results) {
+        if (result.success)
+            succeeded++;
+        else
+            failed++;
+        totalTokens += result.tokenUsage ?? 0;
+        if (result.finalPatch && typeof result.finalPatch === 'string') {
+            for (const file of extractDiffFiles(result.finalPatch)) {
+                changedFiles.add(file);
+            }
+        }
+    }
+    return {
+        totalAgents: results.length,
+        succeeded,
+        failed,
+        conflicts,
+        totalTokens,
+        changedFiles: Array.from(changedFiles),
+    };
+}
+/**
+ * Format a sub-agent summary as a human-readable string for LLM context injection.
+ */
+export function formatSubAgentSummary(summary) {
+    const lines = [
+        `## Sub-Agent Summary`,
+        `- Total: ${summary.totalAgents} | Succeeded: ${summary.succeeded} | Failed: ${summary.failed}`,
+        `- Total tokens: ${summary.totalTokens.toLocaleString()}`,
+        `- Changed files: ${summary.changedFiles.length}`,
+    ];
+    if (summary.changedFiles.length > 0) {
+        lines.push(`- Files: ${summary.changedFiles.join(', ')}`);
+    }
+    if (summary.conflicts.length > 0) {
+        lines.push(`\n### Conflicts Detected`);
+        for (const conflict of summary.conflicts) {
+            lines.push(`- \`${conflict.file}\`: modified by ${conflict.agents.join(', ')}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=summary.js.map

package/dist/core/sub-agent/team.js

@@ -0,0 +1,98 @@
+/**
+ * SubAgentTeam — lightweight task board for parallel sub-agent coordination.
+ *
+ * Multiple sub-agents can claim tasks/files to avoid duplicate work.
+ * Claims are advisory (not enforced) — the team board is a shared
+ * declaration board, not a mutex.
+ */
+export class SubAgentTeam {
+    board = new Map();
+    /**
+     * Attempt to claim a task key. Returns true if the claim succeeded
+     * (key was unclaimed), false if already claimed by another agent.
+     * Re-claiming by the same agent is idempotent (returns true).
+     */
+    claim(taskKey, agentId) {
+        const existing = this.board.get(taskKey);
+        if (existing && existing.claimedBy !== agentId) {
+            return false;
+        }
+        this.board.set(taskKey, { claimedBy: agentId, claimedAt: Date.now() });
+        return true;
+    }
+    /**
+     * Release a claim (e.g., on completion or failure).
+     */
+    release(taskKey, agentId) {
+        const existing = this.board.get(taskKey);
+        if (!existing || existing.claimedBy !== agentId) {
+            return false;
+        }
+        this.board.delete(taskKey);
+        return true;
+    }
+    /**
+     * Check if a task key is already claimed by someone else.
+     */
+    isClaimed(taskKey, excludeAgent) {
+        const existing = this.board.get(taskKey);
+        if (!existing)
+            return false;
+        return existing.claimedBy !== excludeAgent;
+    }
+    /**
+     * List all current claims.
+     */
+    listClaims() {
+        return Array.from(this.board.entries()).map(([taskKey, entry]) => ({
+            taskKey,
+            claimedBy: entry.claimedBy,
+            claimedAt: entry.claimedAt,
+        }));
+    }
+    /**
+     * Get all claims for a specific agent.
+     */
+    getAgentClaims(agentId) {
+        const claims = [];
+        for (const [taskKey, entry] of this.board) {
+            if (entry.claimedBy === agentId) {
+                claims.push({ taskKey, claimedBy: entry.claimedBy, claimedAt: entry.claimedAt });
+            }
+        }
+        return claims;
+    }
+    /**
+     * Clear all claims for a specific agent (e.g., on termination).
+     */
+    releaseAll(agentId) {
+        let released = 0;
+        for (const [key, entry] of this.board) {
+            if (entry.claimedBy === agentId) {
+                this.board.delete(key);
+                released++;
+            }
+        }
+        return released;
+    }
+}
+// Global team registry — teams live for the duration of the parent session
+const teams = new Map();
+/** Get an existing team or create a new one. Teams are keyed by teamId. */
+export function getOrCreateTeam(teamId) {
+    let team = teams.get(teamId);
+    if (!team) {
+        team = new SubAgentTeam();
+        teams.set(teamId, team);
+    }
+    return team;
+}
+/** Remove a team from the global registry. Returns false if not found. */
+export function removeTeam(teamId) {
+    return teams.delete(teamId);
+}
+/** Remove all teams from the global registry. */
+export function clearAllTeams() {
+    teams.clear();
+}
+//# sourceMappingURL=team.js.map

package/dist/core/sub-agent/tools/task-await.js

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { text } from '../../../locales/index.js';
+import { Phase } from '../../types/runtime.js';
+import { createSubAgentController } from '../controller.js';
+const AgentAwaitInputSchema = z.object({
+    agentId: z.string().min(1).describe('The agent ID returned by agent_dispatch in async mode.'),
+    timeout_seconds: z
+        .number()
+        .positive()
+        .optional()
+        .describe('Maximum time to wait for the result. Defaults to the agent profile timeout.'),
+});
+/**
+ * agent_await (Internal: Smallfry Result Collector)
+ * Waits for an asynchronously dispatched sub-agent to complete and returns its result.
+ * Polls the shared controller (same instance used by agent_dispatch) for agent status.
+ */
+export const agentAwaitTaskSpec = {
+    name: 'agent_await',
+    source: 'builtin',
+    intent: 'AGENT',
+    description: text.smallfry.ui.awaitToolDescription,
+    riskLevel: 'low',
+    defaultTimeoutMs: 300_000,
+    sideEffects: ['none'],
+    concurrency: 'parallel_ok',
+    allowedPhases: [Phase.PLAN, Phase.CONTEXT, Phase.AUTOPILOT],
+    inputSchema: AgentAwaitInputSchema,
+    outputSchema: z.any(), // Maps to SubAgentResult
+    examples: [
+        {
+            description: 'Await the result of an async sub-agent',
+            input: {
+                agentId: 'smallfry-a1b2c3d4',
+            },
+            output: {
+                success: true,
+                agent_ref: 'explorer',
+                summary: '<diagnosis and findings>',
+            },
+        },
+    ],
+    executor: async (input, ctx) => {
+        const parsed = AgentAwaitInputSchema.parse(input);
+        const controller = ctx.subAgentController ?? createSubAgentController();
+        const timeoutMs = parsed.timeout_seconds ? parsed.timeout_seconds * 1000 : 300_000;
+        try {
+            // Try awaiting the specific agent ID first (short timeout — if the ID is a
+            // placeholder like '{{handle}}' that no one will resolve, we must fall through
+            // to the scanning fallback quickly).
+            let result = await controller.awaitResult(parsed.agentId, Math.min(timeoutMs, 200));
+            // If not found (e.g., LLM used a placeholder), wait for any pending agent.
+            if (!result) {
+                const agents = controller.listAgents();
+                for (const agent of agents) {
+                    if (agent.status === 'terminated') {
+                        // Already completed — try to get the stored result
+                        result = await controller.awaitResult(agent.id, 0);
+                        if (result)
+                            break;
+                    }
+                }
+            }
+            // If still no result, wait for the first agent to complete
+            if (!result) {
+                const deadline = Date.now() + timeoutMs;
+                while (Date.now() < deadline) {
+                    const agents = controller.listAgents();
+                    for (const agent of agents) {
+                        if (agent.status === 'terminated') {
+                            result = await controller.awaitResult(agent.id, 0);
+                            if (result)
+                                break;
+                        }
+                    }
+                    if (result)
+                        break;
+                    await new Promise((resolve) => setTimeout(resolve, 50));
+                }
+            }
+            if (result)
+                return result;
+            // Timeout
+            return {
+                success: false,
+                agent_ref: parsed.agentId,
+                summary: `Timed out waiting for agent ${parsed.agentId}`,
+                reason: `Timed out after ${timeoutMs}ms`,
+                reasonCode: 'AWAIT_FAILED',
+                tokenUsage: 0,
+                attempts: 1,
+                logs: [],
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                agent_ref: parsed.agentId,
+                summary: error instanceof Error ? error.message : String(error),
+                reason: error instanceof Error ? error.message : String(error),
+                reasonCode: 'AWAIT_FAILED',
+                tokenUsage: 0,
+                attempts: 1,
+                logs: [],
+            };
+        }
+    },
+};
+//# sourceMappingURL=task-await.js.map

package/dist/core/sub-agent/tools/task-spawn.js

@@ -6,8 +6,8 @@ import { mergeSubAgentContextSnapshot } from '../context-snapshot.js';
 import { createSubAgentController } from '../controller.js';
 import { SubAgentManager } from '../core/manager.js';
 import { validateSharedPrefixConsistency } from '../prefix-consistency.js';
-import { SubAgentRequestSchema } from '../types.js';
-function normalizeDispatchRequest(input, ctx) {
+import { SubAgentRequestSchema, } from '../types.js';
+export function normalizeDispatchRequest(input, ctx) {
     const requested = {
         ...input,
         session_target: input.session_target ?? 'isolated',
@@ -18,6 +18,17 @@ function normalizeDispatchRequest(input, ctx) {
                     ? 'review'
                     : 'diagnosis'),
     };
+    if (requested.session_target === 'fork') {
+        // Fork mode: inherit parent's conversation context with cache sharing
+        return {
+            ...requested,
+            contextSnapshot: {
+                ...requested.contextSnapshot,
+                conversationContext: ctx.contextSnapshot?.conversationContext,
+                cacheSharing: ctx.contextSnapshot?.cacheSharing,
+            },
+        };
+    }
     if (requested.session_target !== 'shared') {
         return requested;
     }
@@ -52,6 +63,7 @@ function normalizeDispatchRequest(input, ctx) {
 /**
  * agent_dispatch (Internal: Smallfry Dispatcher)
  * The primary tool for spawning autonomous sub-agents to handle specialized sub-tasks.
+ * Supports async mode: set async=true to get a handle immediately, then use agent_await.
  */
 export const subAgentTaskSpec = {
     name: 'agent_dispatch',
@@ -66,7 +78,7 @@ export const subAgentTaskSpec = {
     concurrency: 'parallel_ok', // Smallfrys handle their own isolation
     allowedPhases: [Phase.PLAN, Phase.CONTEXT, Phase.AUTOPILOT],
     inputSchema: SubAgentRequestSchema,
-    outputSchema: z.any(), // Maps to SubAgentResult
+    outputSchema: z.any(), // Maps to SubAgentResult | SubAgentHandle
     examples: [
         {
             description: 'Ask a read-only explorer to inspect failing tests before editing',
@@ -95,12 +107,45 @@ export const subAgentTaskSpec = {
                 summary: '<review findings>',
             },
         },
+        {
+            description: 'Async dispatch: spawn an explorer and continue working',
+            input: {
+                agent_ref: 'explorer',
+                task: 'Scan src/utils/ for unused exports.',
+                async: true,
+            },
+            output: {
+                agentId: 'smallfry-a1b2c3d4',
+                status: 'working',
+                taskId: 'smallfry-a1b2c3d4',
+            },
+        },
     ],
     executor: async (input, ctx) => {
-        const manager = new SubAgentManager(ctx, ctx.subAgentController ?? createSubAgentController());
-        const request = normalizeDispatchRequest(input, ctx);
-        // Launch the Smallfry via the manager
-        return await manager.execute(request);
+        const parsed = SubAgentRequestSchema.parse(input);
+        const controller = ctx.subAgentController ?? createSubAgentController();
+        const manager = ctx.subAgentManagerFactory
+            ? ctx.subAgentManagerFactory(ctx, controller)
+            : new SubAgentManager(ctx, controller, {
+                llmFactory: ctx.llmFactory,
+                onSubAgentComplete: ctx.onSubAgentComplete,
+            });
+        const request = normalizeDispatchRequest(parsed, ctx);
+        try {
+            return await manager.execute(request);
+        }
+        catch (error) {
+            return {
+                success: false,
+                agent_ref: request.agent_ref,
+                summary: error instanceof Error ? error.message : String(error),
+                reason: error instanceof Error ? error.message : String(error),
+                reasonCode: 'DISPATCH_FAILED',
+                tokenUsage: 0,
+                attempts: 1,
+                logs: [],
+            };
+        }
     },
 };
 //# sourceMappingURL=task-spawn.js.map

package/dist/core/sub-agent/tools/team.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { Phase } from '../../types/runtime.js';
+import { getOrCreateTeam } from '../team.js';
+const AgentTeamInputSchema = z.object({
+    action: z
+        .enum(['claim', 'release', 'list', 'is_claimed'])
+        .describe('Action: claim a task key, release a claim, list all claims, or check if claimed.'),
+    taskKey: z
+        .string()
+        .optional()
+        .describe('The task/file key to claim, release, or check. Required for claim/release/is_claimed.'),
+    teamId: z.string().min(1).describe('The team ID to operate on.'),
+});
+/**
+ * agent_team — Coordination tool for parallel sub-agents.
+ * Allows sub-agents to claim tasks/files and query the team board
+ * to avoid duplicate work.
+ */
+export const agentTeamSpec = {
+    name: 'agent_team',
+    source: 'builtin',
+    intent: 'AGENT',
+    description: 'Coordinate with parallel sub-agents. Use "claim" to declare you are working on a task/file, "list" to see current claims, "is_claimed" to check availability, "release" to free a claim.',
+    riskLevel: 'low',
+    defaultTimeoutMs: 5_000,
+    sideEffects: ['none'],
+    concurrency: 'parallel_ok',
+    allowedPhases: [Phase.PLAN, Phase.CONTEXT, Phase.AUTOPILOT],
+    inputSchema: AgentTeamInputSchema,
+    outputSchema: z.any(),
+    examples: [
+        {
+            description: 'Claim a file for editing',
+            input: { action: 'claim', taskKey: 'src/utils/parser.ts', teamId: 'team-alpha' },
+            output: { success: true, claimed: true },
+        },
+        {
+            description: 'Check if a file is already claimed',
+            input: { action: 'is_claimed', taskKey: 'src/utils/parser.ts', teamId: 'team-alpha' },
+            output: { claimed: true, claimedBy: 'smallfry-a1b2c3d4' },
+        },
+        {
+            description: 'List all current claims',
+            input: { action: 'list', teamId: 'team-alpha' },
+            output: {
+                claims: [
+                    {
+                        taskKey: 'src/utils/parser.ts',
+                        claimedBy: 'smallfry-a1b2c3d4',
+                        claimedAt: 1717800000000,
+                    },
+                ],
+            },
+        },
+    ],
+    executor: async (input, ctx) => {
+        const parsed = AgentTeamInputSchema.parse(input);
+        const agentId = ctx.agentId ?? 'unknown';
+        const team = getOrCreateTeam(parsed.teamId);
+        switch (parsed.action) {
+            case 'claim': {
+                if (!parsed.taskKey)
+                    return { success: false, error: 'taskKey required for claim' };
+                const claimed = team.claim(parsed.taskKey, agentId);
+                return { success: true, claimed };
+            }
+            case 'release': {
+                if (!parsed.taskKey)
+                    return { success: false, error: 'taskKey required for release' };
+                const released = team.release(parsed.taskKey, agentId);
+                return { success: true, released };
+            }
+            case 'is_claimed': {
+                if (!parsed.taskKey)
+                    return { success: false, error: 'taskKey required for is_claimed' };
+                const existing = team.listClaims().find((c) => c.taskKey === parsed.taskKey);
+                return {
+                    success: true,
+                    claimed: team.isClaimed(parsed.taskKey),
+                    claimedBy: existing?.claimedBy,
+                };
+            }
+            case 'list': {
+                const claims = team.listClaims();
+                return { success: true, claims };
+            }
+            default:
+                return { success: false, error: `Unknown action: ${parsed.action}` };
+        }
+    },
+};
+//# sourceMappingURL=team.js.map

package/dist/core/sub-agent/types.js

@@ -40,9 +40,9 @@ export const SubAgentRequestSchema = z.object({
         .describe('Optional repo-relative files the sub-agent should inspect first.'),
     recursionDepth: z.number().optional().default(0),
     session_target: z
-        .enum(['isolated', 'shared'])
+        .enum(['isolated', 'shared', 'fork'])
         .default('isolated')
-        .describe('Optional runtime strategy. Omit unless shared context is explicitly needed.'),
+        .describe('Optional runtime strategy. "fork" inherits parent conversation context with cache sharing. "shared" merges context snapshots. "isolated" (default) uses a clean environment.'),
     timeout_seconds: z
         .preprocess((value) => {
         if (typeof value !== 'string')
@@ -58,6 +58,15 @@ export const SubAgentRequestSchema = z.object({
         .enum(['diagnosis', 'patch', 'review'])
         .optional()
         .describe('Expected deliverable. Use patch for coder-style implementation proposals.'),
+    async: z
+        .boolean()
+        .default(false)
+        .optional()
+        .describe('If true, return a handle immediately and let the caller await the result.'),
+    teamId: z
+        .string()
+        .optional()
+        .describe('Join a coordination team. Sub-agents sharing a teamId can avoid duplicate work via claim/list.'),
     contextSnapshot: z
         .object({
         version: z.literal(SUB_AGENT_CONTEXT_SNAPSHOT_VERSION).optional().default(1),

package/dist/core/target-runtime/profile.js

@@ -1,5 +1,6 @@
 import { existsSync } from '../adapters/fs/node-fs.js';
 import { readFile } from '../adapters/fs/node-fs.js';
+import { getLogger } from '../observability/logger.js';
 import { ensureInSandbox, safeJoin } from '../utils/path.js';
 const LOCKFILE_HINTS = [
     { file: 'bun.lock', manager: 'bun' },
@@ -59,7 +60,8 @@ export async function detectNodeRuntimeProfile(repoPath) {
     try {
         parsed = JSON.parse(await readFile(packageJsonPath, 'utf-8'));
     }
-    catch {
+    catch (error) {
+        getLogger().debug(`[TargetRuntime] Failed to parse package.json: ${error instanceof Error ? error.message : String(error)}`);
         return undefined;
     }
     const { packageManager, source } = detectPackageManager(repoPath, parsed);

package/dist/core/tools/audit.js

@@ -1,5 +1,5 @@
 import { text } from '../../locales/index.js';
-import { tryGetLogger } from '../observability/logger.js';
+import { getLogger, tryGetLogger } from '../observability/logger.js';
 import { Phase } from '../types/runtime.js';
 import { sanitizeErrorMessage } from '../utils/sanitizer.js';
 export class ToolAuditLogger {
@@ -112,7 +112,8 @@ export class ToolAuditLogger {
             const str = JSON.stringify(data);
             return str.length > 200 ? str.substring(0, 200) + '...' : str;
         }
-        catch {
+        catch (error) {
+            getLogger().debug(`[ToolAudit] Failed to summarize data: ${error instanceof Error ? error.message : String(error)}`);
             return '[Circular/Unserializable]';
         }
     }

package/dist/core/tools/budget.js

@@ -1,3 +1,4 @@
+import { getLogger } from '../observability/logger.js';
 /**
  * Default budget limits to ensure system stability.
  */
@@ -50,18 +51,14 @@ export class BudgetGuard {
         const currentRiskActive = this.activeCallsByRisk[params.riskLevel];
         const maxRiskAllowed = this.config.maxConcurrentByRisk[params.riskLevel];
         if (currentRiskActive >= maxRiskAllowed) {
-            throw {
-                code: 'BUDGET_CONCURRENCY',
-                message: `Too many concurrent ${params.riskLevel}-risk tool calls (limit: ${maxRiskAllowed})`,
-            };
+            throw Object.assign(new Error(`Too many concurrent ${params.riskLevel}-risk tool calls (limit: ${maxRiskAllowed})`), { code: 'BUDGET_CONCURRENCY' });
         }
         // 2. Rate Limit / Count Check per Phase
         const currentCount = this.callCounts.get(params.phase) || 0;
         if (currentCount >= this.config.maxCallsPerPhase) {
-            throw {
+            throw Object.assign(new Error(`Too many tool calls in phase ${params.phase}`), {
                 code: 'BUDGET_RATE_LIMIT',
-                message: `Too many tool calls in phase ${params.phase}`,
-            };
+            });
         }
         this.activeCallsByRisk[params.riskLevel]++;
         this.callCounts.set(params.phase, currentCount + 1);
@@ -71,10 +68,7 @@ export class BudgetGuard {
             // 4. Output Size Check (Preliminary)
             const size = this.estimateSize(result);
             if (size > params.maxOutputBytes) {
-                throw {
-                    code: 'OUTPUT_TOO_LARGE',
-                    message: `Output size ${size} bytes exceeds limit of ${params.maxOutputBytes}`,
-                };
+                throw Object.assign(new Error(`Output size ${size} bytes exceeds limit of ${params.maxOutputBytes}`), { code: 'OUTPUT_TOO_LARGE' });
             }
             return result;
         }
@@ -110,7 +104,8 @@ export class BudgetGuard {
             // This is expensive for large objects, but safe for checking limits
             return JSON.stringify(obj).length;
         }
-        catch {
+        catch (error) {
+            getLogger().debug(`[Budget] Failed to estimate size: ${error instanceof Error ? error.message : String(error)}`);
             return 0; // Circular structure or otherwise un-stringifiable
         }
     }