salmon-loop 0.2.13 → 0.3.0

package/dist/core/sub-agent/prefix-consistency.js

@@ -0,0 +1,48 @@
+import { createHash } from 'crypto';
+function digest(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+export function buildSystemPrefixDigest(parts) {
+    return digest([parts.phase, parts.namespace ?? 'default', parts.contextHash ?? 'missing'].join('\u001f'));
+}
+export function buildToolSchemaHash(parts) {
+    const names = [...(parts.allowedToolNames ?? [])].sort();
+    return digest([parts.phase, ...names].join('\u001f'));
+}
+export function validateSharedPrefixConsistency(args) {
+    const requestSharing = args.requestSnapshot?.cacheSharing;
+    const runtimeSharing = args.runtimeSnapshot?.cacheSharing;
+    if (!runtimeSharing || !requestSharing) {
+        return { compatible: false, reason: 'missing_cache_sharing_snapshot' };
+    }
+    if (!runtimeSharing.contextHash ||
+        !runtimeSharing.toolSchemaHash ||
+        !runtimeSharing.systemPrefixDigest) {
+        return { compatible: false, reason: 'runtime_missing_cache_digest_fields' };
+    }
+    if (!requestSharing.contextHash ||
+        !requestSharing.toolSchemaHash ||
+        !requestSharing.systemPrefixDigest) {
+        return { compatible: false, reason: 'request_missing_cache_digest_fields' };
+    }
+    const expected = {
+        contextHash: runtimeSharing.contextHash,
+        toolSchemaHash: runtimeSharing.toolSchemaHash,
+        systemPrefixDigest: runtimeSharing.systemPrefixDigest,
+    };
+    const actual = {
+        contextHash: requestSharing.contextHash,
+        toolSchemaHash: requestSharing.toolSchemaHash,
+        systemPrefixDigest: requestSharing.systemPrefixDigest,
+    };
+    const compatible = expected.contextHash === actual.contextHash &&
+        expected.toolSchemaHash === actual.toolSchemaHash &&
+        expected.systemPrefixDigest === actual.systemPrefixDigest;
+    return {
+        compatible,
+        reason: compatible ? undefined : 'cache_critical_prefix_mismatch',
+        expected,
+        actual,
+    };
+}
+//# sourceMappingURL=prefix-consistency.js.map

package/dist/core/sub-agent/registry-defaults.js

@@ -9,6 +9,7 @@ const DEFAULT_SUB_AGENT_PROFILES = [
         stratagem: 'investigator',
         maxTokens: 50000,
         maxAttempts: 3,
+        timeoutMs: 60_000,
     },
     {
         id: 'surgeon',
@@ -20,6 +21,7 @@ const DEFAULT_SUB_AGENT_PROFILES = [
         stratagem: 'surgeon',
         maxTokens: 100000,
         maxAttempts: 5,
+        timeoutMs: 180_000,
     },
     {
         id: 'reviewer',
@@ -31,6 +33,7 @@ const DEFAULT_SUB_AGENT_PROFILES = [
         stratagem: 'investigator',
         maxTokens: 30000,
         maxAttempts: 2,
+        timeoutMs: 60_000,
     },
     {
         id: 'cleaner',
@@ -42,6 +45,7 @@ const DEFAULT_SUB_AGENT_PROFILES = [
         stratagem: 'surgeon',
         maxTokens: 50000,
         maxAttempts: 3,
+        timeoutMs: 120_000,
     },
 ];
 export function registerDefaultSubAgentProfiles(registry) {

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

@@ -1,8 +1,54 @@
 import { z } from 'zod';
 import { text } from '../../../locales/index.js';
+import { recordAuditEvent } from '../../observability/audit-trail.js';
+import { Phase } from '../../types/runtime.js';
+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) {
+    const requested = {
+        ...input,
+        session_target: input.session_target ?? 'isolated',
+        expected_output: input.expected_output ??
+            (input.agent_ref === 'surgeon' || input.agent_ref === 'cleaner'
+                ? 'patch'
+                : input.agent_ref === 'reviewer'
+                    ? 'review'
+                    : 'diagnosis'),
+    };
+    if (requested.session_target !== 'shared') {
+        return requested;
+    }
+    const consistency = validateSharedPrefixConsistency({
+        requestSnapshot: requested.contextSnapshot,
+        runtimeSnapshot: ctx.contextSnapshot,
+    });
+    if (!consistency.compatible) {
+        recordAuditEvent('sub_agent.shared.prefix_consistency_failed', {
+            metric: 'shared_fallback_rate',
+            fallbackMode: 'isolated',
+            reason: consistency.reason,
+            expected: consistency.expected,
+            actual: consistency.actual,
+        }, {
+            source: 'smallfry',
+            severity: 'medium',
+            scope: 'session',
+            phase: ctx.phase,
+        });
+        return {
+            ...requested,
+            session_target: 'isolated',
+            contextSnapshot: undefined,
+        };
+    }
+    return {
+        ...requested,
+        contextSnapshot: mergeSubAgentContextSnapshot(requested.contextSnapshot, ctx.contextSnapshot),
+    };
+}
 /**
  * agent_dispatch (Internal: Smallfry Dispatcher)
  * The primary tool for spawning autonomous sub-agents to handle specialized sub-tasks.
@@ -13,17 +59,48 @@ export const subAgentTaskSpec = {
     intent: 'AGENT',
     description: text.smallfry.ui.spawnToolDescription,
     riskLevel: 'medium',
+    defaultTimeoutMs: 180_000,
     // This tool is proposal-only: it may read the repo and produce structured proposals,
     // but it MUST NOT mutate the user's workspace from within the calling phase.
     sideEffects: ['none', 'fs_read', 'git_read'],
     concurrency: 'parallel_ok', // Smallfrys handle their own isolation
-    allowedPhases: ['PLAN', 'CONTEXT'],
+    allowedPhases: [Phase.PLAN, Phase.CONTEXT, Phase.AUTOPILOT],
     inputSchema: SubAgentRequestSchema,
     outputSchema: z.any(), // Maps to SubAgentResult
+    examples: [
+        {
+            description: 'Ask a read-only explorer to inspect failing tests before editing',
+            input: {
+                agent_ref: 'explorer',
+                task: 'Inspect src/order.js, src/inventory.js, and test/order.test.js. Identify why the order pricing tests fail and return a concise diagnosis with recommended files to edit.',
+                contextFiles: ['src/order.js', 'src/inventory.js', 'test/order.test.js'],
+                expected_output: 'diagnosis',
+            },
+            output: {
+                success: true,
+                agent_ref: 'explorer',
+                summary: '<diagnosis and recommended next steps>',
+            },
+        },
+        {
+            description: 'Ask a reviewer to audit a proposed implementation',
+            input: {
+                agent_ref: 'reviewer',
+                task: 'Review the current changes for correctness, missing edge cases, and behavior covered by tests. Return findings only.',
+                expected_output: 'review',
+            },
+            output: {
+                success: true,
+                agent_ref: 'reviewer',
+                summary: '<review findings>',
+            },
+        },
+    ],
     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(input);
+        return await manager.execute(request);
     },
 };
 //# sourceMappingURL=task-spawn.js.map

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

@@ -1,19 +1,148 @@
 import { z } from 'zod';
+export const SUB_AGENT_CONTEXT_SNAPSHOT_VERSION = 1;
+/**
+ * Versioned protocol contract for sub-agent context snapshot fields.
+ *
+ * - `clone`: mutable request/runtime data must be deep-cloned before dispatch.
+ * - `share`: session-scoped coordination metadata is intentionally shared.
+ */
+export const SUB_AGENT_CONTEXT_SNAPSHOT_FIELD_SEMANTICS = {
+    conversationContext: 'clone',
+    artifactHints: 'clone',
+    toolCallingAudit: 'clone',
+    replacementState: 'clone',
+    planRuntime: 'share',
+    cacheSharing: 'share',
+};
+const SubAgentContextMessageSchema = z.object({
+    role: z.enum(['system', 'user', 'assistant', 'tool']),
+    content: z.string(),
+    name: z.string().optional(),
+    reasoning_content: z.string().optional(),
+    tool_calls: z.array(z.unknown()).optional(),
+    tool_call_id: z.string().optional(),
+});
 /**
  * Zod Schema for validation
  */
 export const SubAgentRequestSchema = z.object({
     agent_ref: z
         .string()
-        .describe('The specialized agent role to dispatch (e.g., explorer, surgeon)'),
-    task: z.string().describe('The specific task or instruction for the sub-agent'),
-    contextFiles: z.array(z.string()).optional(),
+        .min(1)
+        .describe('Required specialized agent role: explorer for read-only investigation, reviewer for audit, surgeon for implementation proposals, cleaner for lint/format cleanup.'),
+    task: z
+        .string()
+        .min(1)
+        .describe('Required concrete delegated mission. Include relevant files, failure symptoms, and the exact desired deliverable. Never leave this empty.'),
+    contextFiles: z
+        .array(z.string().describe('Repo-relative file path relevant to the delegated mission.'))
+        .optional()
+        .describe('Optional repo-relative files the sub-agent should inspect first.'),
     recursionDepth: z.number().optional().default(0),
     session_target: z
         .enum(['isolated', 'shared'])
         .default('isolated')
-        .describe('Whether the session should be isolated (shadow worktree) or shared'),
-    timeout_seconds: z.number().optional().describe('Maximum execution time in seconds'),
+        .describe('Optional runtime strategy. Omit unless shared context is explicitly needed.'),
+    timeout_seconds: z
+        .preprocess((value) => {
+        if (typeof value !== 'string')
+            return value;
+        const trimmed = value.trim();
+        if (!/^\d+(?:\.\d+)?$/.test(trimmed))
+            return value;
+        return Number(trimmed);
+    }, z.number().positive())
+        .optional()
+        .describe('Maximum execution time in seconds'),
+    expected_output: z
+        .enum(['diagnosis', 'patch', 'review'])
+        .optional()
+        .describe('Expected deliverable. Use patch for coder-style implementation proposals.'),
+    contextSnapshot: z
+        .object({
+        version: z.literal(SUB_AGENT_CONTEXT_SNAPSHOT_VERSION).optional().default(1),
+        conversationContext: z.array(SubAgentContextMessageSchema).optional(),
+        artifactHints: z
+            .object({
+            verifyArtifact: z
+                .object({
+                handle: z.string(),
+                mimeType: z.string(),
+                sha256: z.string(),
+                size: z.number(),
+            })
+                .optional(),
+            subAgentPatchArtifacts: z
+                .array(z.object({
+                handle: z.string(),
+                mimeType: z.string(),
+                sha256: z.string(),
+                size: z.number(),
+            }))
+                .optional(),
+            subAgentAuditArtifacts: z
+                .array(z.object({
+                handle: z.string(),
+                mimeType: z.string(),
+                sha256: z.string(),
+                size: z.number(),
+            }))
+                .optional(),
+            recentReadArtifacts: z
+                .array(z.object({
+                path: z.string(),
+                artifact: z.object({
+                    handle: z.string(),
+                    mimeType: z.string(),
+                    sha256: z.string(),
+                    size: z.number(),
+                }),
+            }))
+                .optional(),
+            toolResultPreviewArtifacts: z
+                .array(z.object({
+                label: z.string(),
+                artifact: z.object({
+                    handle: z.string(),
+                    mimeType: z.string(),
+                    sha256: z.string(),
+                    size: z.number(),
+                }),
+            }))
+                .optional(),
+        })
+            .optional(),
+        toolCallingAudit: z.array(z.record(z.string(), z.unknown())).optional(),
+        replacementState: z
+            .object({
+            schemaVersion: z.number(),
+            entries: z.record(z.string(), z.object({
+                toolResultId: z.string(),
+                decision: z.enum(['kept', 'replaced']),
+                preview: z.string(),
+                frozenAt: z.number(),
+                sourceArtifactHandle: z.string().optional(),
+                identityVersion: z.string(),
+                hashAlgorithm: z.string(),
+            })),
+        })
+            .optional(),
+        planRuntime: z
+            .object({
+            sessionId: z.string(),
+            planPathHint: z.string(),
+        })
+            .optional(),
+        cacheSharing: z
+            .object({
+            namespace: z.string().optional(),
+            contextHash: z.string().optional(),
+            toolSchemaHash: z.string().optional(),
+            systemPrefixDigest: z.string().optional(),
+        })
+            .optional(),
+    })
+        .optional(),
     budgetOverride: z
         .object({
         maxTokens: z.number().optional(),

package/dist/core/tools/audit.js

@@ -1,5 +1,5 @@
 import { text } from '../../locales/index.js';
-import { getLogger } from '../observability/logger.js';
+import { tryGetLogger } from '../observability/logger.js';
 import { Phase } from '../types/runtime.js';
 import { sanitizeErrorMessage } from '../utils/sanitizer.js';
 export class ToolAuditLogger {
@@ -29,7 +29,10 @@ export class ToolAuditLogger {
             decision,
         };
         this.logs.push(entry);
-        getLogger().debug(text.audit.event('Start', spec.name, decision.allowed ? 'allowed' : 'denied'));
+        const logger = tryGetLogger();
+        if (logger) {
+            logger.debug(text.audit.event('Start', spec.name, decision.allowed ? 'allowed' : 'denied'));
+        }
     }
     onEnd(result) {
         const phase = (result.id && this.callPhaseIndex.get(result.id)) ||
@@ -48,7 +51,10 @@ export class ToolAuditLogger {
             errorMessage: result.error?.message ? sanitizeErrorMessage(result.error.message) : undefined,
         };
         this.logs.push(entry);
-        getLogger().debug(text.audit.event('End', result.toolName, result.status));
+        const logger = tryGetLogger();
+        if (logger) {
+            logger.debug(text.audit.event('End', result.toolName, result.status));
+        }
         if (result.id) {
             this.callPhaseIndex.delete(result.id);
         }
@@ -69,7 +75,10 @@ export class ToolAuditLogger {
             authPersist: event.persist,
         };
         this.logs.push(entry);
-        getLogger().debug(text.audit.event('Authorization', event.toolName, event.outcome));
+        const logger = tryGetLogger();
+        if (logger) {
+            logger.debug(text.audit.event('Authorization', event.toolName, event.outcome));
+        }
         this.options?.onAuthorizationDecision?.(event);
         const updated = this.updateAuthorizationSummary(event.source);
         if (updated && this.options?.onAuthorizationSummary) {

package/dist/core/tools/builtin/ast-grep.js

@@ -29,7 +29,7 @@ export const astGrepSpec = {
         })),
         error: z.string().optional(),
     }),
-    allowedPhases: [Phase.CONTEXT, Phase.EXPLORE, Phase.PLAN],
+    allowedPhases: [Phase.CONTEXT, Phase.EXPLORE, Phase.PLAN, Phase.AUTOPILOT],
 };
 /**
  * Executes the ast-grep search.

package/dist/core/tools/builtin/ast.js

@@ -29,7 +29,7 @@ export const astDefsRefsSpec = {
             location: z.any(),
         })),
     }),
-    allowedPhases: [Phase.CONTEXT, Phase.EXPLORE, Phase.PLAN],
+    allowedPhases: [Phase.CONTEXT, Phase.EXPLORE, Phase.PLAN, Phase.AUTOPILOT],
 };
 /**
  * Builtin tool to query AST definitions and references