salmon-loop 0.2.3

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

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { text } from '../../../locales/index.js';
+import { GitAdapter } from '../../adapters/git/git-adapter.js';
+import { LIMITS } from '../../config/limits.js';
+import { Phase } from '../../types/runtime.js';
+import { repoResource } from '../parallel/resource-helpers.js';
+export const gitCatSpec = {
+    name: 'git.cat',
+    source: 'builtin',
+    intent: 'READ',
+    description: `${text.tools.gitCatDescription} IMPORTANT: The file parameter must be a relative path (e.g., "src/main.ts"). Do NOT use absolute paths or paths with "..".`,
+    riskLevel: 'low',
+    sideEffects: ['git_read'],
+    concurrency: 'parallel_ok',
+    computeResources: (_input, ctx) => [repoResource(ctx)],
+    inputSchema: z.object({
+        file: z.string().describe('Path to the file relative to repo root'),
+        ref: z.string().default('HEAD').describe('Git reference (branch, hash, or HEAD)'),
+    }),
+    outputSchema: z.object({
+        content: z.string(),
+        file: z.string(),
+        ref: z.string(),
+    }),
+    allowedPhases: [Phase.SLASH, Phase.CONTEXT],
+    examples: [
+        {
+            description: 'Read a file from HEAD revision',
+            input: { file: 'src/main.ts', ref: 'HEAD' },
+            output: { content: '<file content>', file: 'src/main.ts', ref: 'HEAD' },
+        },
+        {
+            description: 'Read a file from a specific tag',
+            input: { file: 'README.md', ref: 'v1.0.0' },
+            output: { content: '<file content>', file: 'README.md', ref: 'v1.0.0' },
+        },
+        {
+            description: 'Read a file using default ref (HEAD)',
+            input: { file: 'package.json' },
+            output: { content: '<file content>', file: 'package.json', ref: 'HEAD' },
+        },
+    ],
+};
+/**
+ * Builtin tool to read file content from a specific git revision
+ */
+export async function executeGitCat(input, ctx) {
+    const { file, ref } = input;
+    // Safety check: ensure file path doesn't try to escape
+    if (file.includes('..') || file.startsWith('/') || /^[a-zA-Z]:/.test(file)) {
+        throw new Error(text.tools.invalidRelativePath(file));
+    }
+    const repoRoot = ctx.worktreeRoot || ctx.repoRoot;
+    const git = new GitAdapter(repoRoot);
+    const res = await git.execMeta(['show', `${ref}:${file}`], {
+        cwd: repoRoot,
+        env: ctx.env,
+        limits: { maxStdoutBytes: LIMITS.maxToolOutputBytes, maxStderrChars: 16_384 },
+        timeoutMs: LIMITS.gitTimeoutMs,
+    });
+    if (!res.ok) {
+        if (res.error?.message)
+            throw new Error(text.git.processError(res.error.message));
+        throw new Error(text.git.showFailed(`code=${res.code ?? 'null'} ${res.stderr.trim()}`.trim()));
+    }
+    if (res.stdoutTruncated)
+        throw new Error(text.git.outputTruncated(LIMITS.maxToolOutputBytes));
+    return {
+        content: res.stdout.toString('utf8'),
+        file,
+        ref,
+    };
+}
+export const gitStatusSpec = {
+    name: 'git.status',
+    source: 'builtin',
+    intent: 'LIST',
+    description: text.tools.gitStatusDescription,
+    riskLevel: 'low',
+    sideEffects: ['git_read'],
+    concurrency: 'parallel_ok',
+    computeResources: (_input, ctx) => [repoResource(ctx)],
+    inputSchema: z.object({
+        porcelain: z.boolean().default(true).describe('Give the output in an easy-to-parse format'),
+    }),
+    outputSchema: z.object({
+        status: z.string(),
+    }),
+    allowedPhases: [Phase.SLASH, Phase.CONTEXT, Phase.PLAN, Phase.VERIFY],
+};
+/**
+ * Builtin tool to check git status
+ */
+export async function executeGitStatus(input, ctx) {
+    const { porcelain } = input;
+    const args = ['status'];
+    if (porcelain)
+        args.push('--porcelain');
+    const repoRoot = ctx.worktreeRoot || ctx.repoRoot;
+    const git = new GitAdapter(repoRoot);
+    const res = await git.execMeta(args, {
+        cwd: repoRoot,
+        env: ctx.env,
+        limits: { maxStdoutBytes: LIMITS.maxToolOutputBytes, maxStderrChars: 16_384 },
+        timeoutMs: LIMITS.gitTimeoutMs,
+    });
+    if (!res.ok) {
+        if (res.error?.message)
+            throw new Error(text.git.processError(res.error.message));
+        throw new Error(text.git.commandFailedDetailed(res.code, res.stderr.trim()));
+    }
+    if (res.stdoutTruncated)
+        throw new Error(text.git.outputTruncated(LIMITS.maxToolOutputBytes));
+    return {
+        status: res.stdout.toString('utf8'),
+    };
+}
+//# sourceMappingURL=git.js.map

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

@@ -0,0 +1,80 @@
+import { subAgentTaskSpec } from '../../sub-agent/tools/task-spawn.js';
+import { artifactReadSpec, executeArtifactRead } from './artifact.js';
+import { astGrepSpec, executeAstGrep } from './ast-grep.js';
+import { astDefsRefsSpec, executeAstDefsRefs } from './ast.js';
+import { codeSearchExecutor } from './code-search/executor.js';
+import { CodeSearchSpec } from './code-search/spec.js';
+import { codeReadSpec, executeFsList, executeFsReadFile, fsListSpec, fsReadFileSpec, } from './fs.js';
+import { gitCatSpec, executeGitCat, gitStatusSpec, executeGitStatus } from './git.js';
+import { askUserSpec } from './interaction.js';
+import { updateKnowledgeSpec, executeUpdateKnowledge } from './knowledge.js';
+import { planInitSpec, planReadSpec, planUpdateSpec } from './plan.js';
+import { proposalApplySpec, executeProposalApply } from './proposal.js';
+import { shellExecSpec, executeShellExec } from './shell.js';
+import { verifyRunSpec, executeVerifyRun } from './verify.js';
+/**
+ * Registers all builtin tools into the provided registry
+ */
+export function registerAllBuiltins(registry) {
+    // Register sub-agent tool
+    registry.register(subAgentTaskSpec);
+    registry.register({
+        ...artifactReadSpec,
+        executor: executeArtifactRead,
+    });
+    registry.register({
+        ...updateKnowledgeSpec,
+        executor: executeUpdateKnowledge,
+    });
+    registry.register({
+        ...proposalApplySpec,
+        executor: executeProposalApply,
+    });
+    // Register unified code.search with its specific executor
+    registry.register({
+        ...CodeSearchSpec,
+        executor: codeSearchExecutor,
+    });
+    registry.register({
+        ...astDefsRefsSpec,
+        executor: executeAstDefsRefs,
+    });
+    registry.register({
+        ...gitCatSpec,
+        executor: executeGitCat,
+    });
+    registry.register({
+        ...gitStatusSpec,
+        executor: executeGitStatus,
+    });
+    registry.register({
+        ...fsReadFileSpec,
+        executor: executeFsReadFile,
+    });
+    registry.register({
+        ...codeReadSpec,
+        executor: executeFsReadFile,
+    });
+    registry.register({
+        ...fsListSpec,
+        executor: executeFsList,
+    });
+    registry.register({
+        ...astGrepSpec,
+        executor: executeAstGrep,
+    });
+    registry.register({
+        ...verifyRunSpec,
+        executor: executeVerifyRun,
+    });
+    registry.register({
+        ...shellExecSpec,
+        executor: executeShellExec,
+    });
+    registry.register(planInitSpec);
+    registry.register(planReadSpec);
+    registry.register(planUpdateSpec);
+    registry.register(askUserSpec);
+}
+export { CodeSearchSpec, codeSearchExecutor, astDefsRefsSpec as codeAstSpec, executeAstDefsRefs as executeCodeAst, gitCatSpec, executeGitCat, gitStatusSpec, executeGitStatus, codeReadSpec, fsListSpec, executeFsList, fsReadFileSpec as fsReadSpec, executeFsReadFile as executeFsRead, updateKnowledgeSpec, executeUpdateKnowledge, astGrepSpec as codeSearchAstSpec, executeAstGrep as executeCodeSearchAst, verifyRunSpec as testRunSpec, executeVerifyRun as executeTestRun, };
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import { text } from '../../../locales/index.js';
+import { Phase } from '../../types/runtime.js';
+const optionSchema = z.object({
+    label: z.string().min(1),
+    description: z.string().min(1),
+});
+const questionSchema = z.object({
+    question: z.string().min(1),
+    header: z.string().min(1),
+    options: z.array(optionSchema).min(2).max(4),
+    multiSelect: z.boolean(),
+});
+const askUserInputSchema = z
+    .object({
+    questions: z.array(questionSchema).min(1).max(4),
+})
+    .superRefine((value, ctx) => {
+    const seen = new Set();
+    for (const q of value.questions) {
+        if (seen.has(q.question)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Duplicate question: ${q.question}`,
+            });
+            return;
+        }
+        seen.add(q.question);
+    }
+});
+const askUserOutputSchema = z.object({
+    questions: z.array(questionSchema),
+    answers: z.record(z.string(), z.string()),
+});
+function buildPrompt(questions) {
+    if (questions.length === 0)
+        return text.tools.askUserPromptDefault;
+    const first = questions[0];
+    const header = first.header?.trim();
+    const question = first.question?.trim();
+    if (header && question)
+        return `${header}: ${question}`;
+    if (header)
+        return header;
+    if (question)
+        return question;
+    return text.tools.askUserPromptDefault;
+}
+function buildInputRequired(input) {
+    return {
+        type: 'question',
+        reason: 'clarification',
+        prompt: buildPrompt(input.questions),
+        questions: input.questions,
+        responseFormat: 'json',
+    };
+}
+export const askUserSpec = {
+    name: 'interaction.ask_user',
+    source: 'builtin',
+    intent: 'AGENT',
+    description: text.tools.askUserDescription,
+    riskLevel: 'low',
+    sideEffects: ['none'],
+    concurrency: 'serial_only',
+    allowedPhases: [Phase.EXPLORE, Phase.PLAN, Phase.PATCH, Phase.VALIDATE, Phase.AST_VALIDATE],
+    inputSchema: askUserInputSchema,
+    outputSchema: askUserOutputSchema,
+    executor: async (input, ctx) => {
+        if (ctx.agentKind === 'subagent') {
+            const err = new Error(text.tools.askUserSubagentBlocked);
+            err.code = 'ASK_USER_SUBAGENT_BLOCKED';
+            throw err;
+        }
+        if (!ctx.userInputProvider) {
+            const err = new Error(text.tools.askUserRequired);
+            const inputRequired = buildInputRequired(input);
+            err.code = 'INTERRUPT_REQUIRED';
+            err.interrupt = {
+                type: 'awaiting_input',
+                reason: inputRequired.reason ?? 'clarification',
+                prompt: inputRequired.prompt,
+                data: { inputRequired },
+            };
+            throw err;
+        }
+        const output = await ctx.userInputProvider.askUser(input, { signal: ctx.signal });
+        const validationError = validateAnswers(input, output.answers);
+        if (validationError) {
+            const err = new Error(validationError);
+            err.code = 'INVALID_OUTPUT';
+            throw err;
+        }
+        return { questions: input.questions, answers: output.answers };
+    },
+};
+function validateAnswers(input, answers) {
+    const questionMap = new Map(input.questions.map((q) => [q.question, new Set(q.options.map((o) => o.label))]));
+    for (const key of Object.keys(answers)) {
+        const allowed = questionMap.get(key);
+        if (!allowed) {
+            return `Unknown question answer key: ${key}`;
+        }
+        const raw = answers[key] ?? '';
+        const parts = raw
+            .split(',')
+            .map((part) => part.trim())
+            .filter(Boolean);
+        if (parts.length === 0) {
+            return `Empty answer for question: ${key}`;
+        }
+        for (const answer of parts) {
+            if (!allowed.has(answer)) {
+                return `Invalid answer "${answer}" for question: ${key}`;
+            }
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=interaction.js.map

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

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+import { writeFile, mkdir } from '../../adapters/fs/node-fs.js';
+import { getDefaultIndexPath } from '../../config/paths.js';
+import { Phase } from '../../types/runtime.js';
+import { safeJoin } from '../../utils/path.js';
+let lastEventTimestampMs = 0;
+let eventSequence = 0;
+function nextEventFilePrefix() {
+    const nowMs = Date.now();
+    if (nowMs === lastEventTimestampMs) {
+        eventSequence += 1;
+    }
+    else {
+        lastEventTimestampMs = nowMs;
+        eventSequence = 0;
+    }
+    // Keep lexical sort order aligned with chronological order.
+    // KnowledgeGatherer sorts filenames as strings (ascending).
+    return `${nowMs}-${String(eventSequence).padStart(6, '0')}`;
+}
+const updateKnowledgeInputSchema = z.discriminatedUnion('category', [
+    z.object({
+        category: z.literal('project_rules'),
+        rules: z.array(z.string()).describe('Full list of active project rules and coding standards'),
+        deprecated_rules: z
+            .array(z.string())
+            .optional()
+            .describe('List of previously recorded rules that are no longer valid or have been replaced'),
+    }),
+    z.object({
+        category: z.literal('architectural_decisions'),
+        decision: z.string().describe('The new architectural decision to record'),
+        related_files: z.array(z.string()).optional().describe('Files affected by this decision'),
+    }),
+    z.object({
+        category: z.literal('user_preferences'),
+        preferences: z.string().describe('Updated description of user personal preferences'),
+    }),
+]);
+export const updateKnowledgeSpec = {
+    name: 'update_knowledge',
+    source: 'builtin',
+    intent: 'WRITE',
+    description: 'Persist project-specific knowledge, rules, and decisions for cross-session memory.',
+    riskLevel: 'low',
+    sideEffects: ['fs_write'],
+    concurrency: 'parallel_ok',
+    inputSchema: updateKnowledgeInputSchema,
+    outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+    }),
+    allowedPhases: [Phase.EXPLORE, Phase.PLAN, Phase.PATCH],
+};
+export async function executeUpdateKnowledge(input, ctx) {
+    const { repoRoot } = ctx;
+    const indexPath = getDefaultIndexPath(repoRoot);
+    const knowledgeDir = safeJoin(indexPath, 'knowledge');
+    // Use timestamp + per-process sequence to ensure unique append-only filenames
+    // even when multiple events occur within the same millisecond.
+    const fileName = `${nextEventFilePrefix()}-${input.category}.json`;
+    const filePath = safeJoin(knowledgeDir, fileName);
+    let dataToSave = {};
+    switch (input.category) {
+        case 'project_rules':
+            dataToSave = {
+                project_rules: input.rules,
+                deprecated_rules: input.deprecated_rules,
+            };
+            break;
+        case 'architectural_decisions':
+            dataToSave = {
+                architectural_decisions: [
+                    {
+                        date: new Date().toISOString().split('T')[0],
+                        decision: input.decision,
+                        related_files: input.related_files,
+                    },
+                ],
+            };
+            break;
+        case 'user_preferences':
+            dataToSave = { user_preferences: input.preferences };
+            break;
+    }
+    try {
+        await mkdir(knowledgeDir, { recursive: true });
+        await writeFile(filePath, JSON.stringify(dataToSave, null, 2));
+        return {
+            success: true,
+            message: `Successfully recorded knowledge event: ${fileName}`,
+        };
+    }
+    catch (e) {
+        throw new Error(`Failed to record knowledge event: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+//# sourceMappingURL=knowledge.js.map

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

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+import { text } from '../../../locales/index.js';
+import { initPlan, readPlan, updatePlan } from '../../plan/index.js';
+import { Phase } from '../../types/runtime.js';
+const sessionIdSchema = z
+    .string()
+    .min(6)
+    .max(64)
+    .regex(/^[a-zA-Z0-9_-]+$/)
+    .describe('Plan session ID (opaque).');
+const stepIdSchema = z
+    .string()
+    .min(3)
+    .max(128)
+    .regex(/^[a-zA-Z0-9_.:-]+$/)
+    .describe('Stable step ID (from <!-- sl:id=... -->).');
+function planResource(ctx, sessionId) {
+    const repoId = ctx.persistenceRoot ?? ctx.repoRoot;
+    if (!sessionId)
+        return [{ kind: 'repo', id: repoId }];
+    return [{ kind: 'pathPrefix', repoId, prefix: `.salmonloop/plans/${sessionId}/` }];
+}
+export const planInitSpec = {
+    name: 'plan.init',
+    source: 'builtin',
+    intent: 'WRITE',
+    description: text.tools.planInitDescription,
+    riskLevel: 'low',
+    sideEffects: ['runtime_write'],
+    concurrency: 'mutex_by_resource',
+    computeResources: (_args, ctx) => planResource(ctx),
+    allowedPhases: [Phase.EXPLORE, Phase.PLAN, Phase.PATCH, Phase.VERIFY, Phase.SHRINK],
+    inputSchema: z.object({
+        mission: z.string().min(1),
+        objective: z.string().min(1),
+        context: z.string().optional(),
+    }),
+    outputSchema: z.object({
+        sessionId: z.string(),
+        planPathHint: z.string(),
+        baseHash: z.string(),
+    }),
+    executor: async (input, ctx) => {
+        const persistenceRoot = ctx.persistenceRoot ?? ctx.repoRoot;
+        return initPlan({
+            persistenceRoot,
+            mission: input.mission,
+            objective: input.objective,
+            context: input.context,
+        });
+    },
+};
+export const planReadSpec = {
+    name: 'plan.read',
+    source: 'builtin',
+    intent: 'READ',
+    description: text.tools.planReadDescription,
+    riskLevel: 'low',
+    sideEffects: ['fs_read'],
+    concurrency: 'parallel_ok',
+    computeResources: (args, ctx) => planResource(ctx, args.sessionId),
+    allowedPhases: [Phase.EXPLORE, Phase.PLAN, Phase.PATCH, Phase.VERIFY, Phase.SHRINK],
+    inputSchema: z.object({
+        sessionId: sessionIdSchema,
+    }),
+    outputSchema: z.object({
+        sessionId: z.string(),
+        baseHash: z.string(),
+        active: z.array(z.object({
+            stepId: z.string(),
+            text: z.string(),
+            checkbox: z.enum(['checked', 'unchecked']),
+            status: z.enum(['todo', 'active', 'done', 'failed', 'skipped', 'conflict']),
+        })),
+        pending: z.array(z.object({
+            stepId: z.string(),
+            text: z.string(),
+            checkbox: z.enum(['checked', 'unchecked']),
+            status: z.enum(['todo', 'active', 'done', 'failed', 'skipped', 'conflict']),
+        })),
+        recentDone: z.array(z.object({
+            stepId: z.string(),
+            text: z.string(),
+            checkbox: z.enum(['checked', 'unchecked']),
+            status: z.enum(['todo', 'active', 'done', 'failed', 'skipped', 'conflict']),
+        })),
+        conflicts: z.object({ present: z.boolean(), summary: z.string().optional() }),
+    }),
+    executor: async (input, ctx) => {
+        const persistenceRoot = ctx.persistenceRoot ?? ctx.repoRoot;
+        return readPlan({ persistenceRoot, sessionId: input.sessionId });
+    },
+};
+export const planUpdateSpec = {
+    name: 'plan.update',
+    source: 'builtin',
+    intent: 'WRITE',
+    description: text.tools.planUpdateDescription,
+    riskLevel: 'low',
+    sideEffects: ['runtime_write'],
+    concurrency: 'mutex_by_resource',
+    computeResources: (args, ctx) => planResource(ctx, args.sessionId),
+    allowedPhases: [Phase.EXPLORE, Phase.PLAN, Phase.PATCH, Phase.VERIFY, Phase.SHRINK],
+    inputSchema: z.object({
+        sessionId: sessionIdSchema,
+        baseHash: z.string().min(8),
+        stepId: stepIdSchema,
+        patch: z.object({
+            status: z.enum(['todo', 'active', 'done', 'failed', 'skipped', 'conflict']).optional(),
+            checkbox: z.enum(['checked', 'unchecked']).optional(),
+            appendSubtasks: z.array(z.string().min(1)).optional(),
+            note: z.string().optional(),
+        }),
+    }),
+    outputSchema: z.union([
+        z.object({
+            ok: z.literal(true),
+            sessionId: z.string(),
+            baseHash: z.string(),
+            updatedStepId: z.string(),
+        }),
+        z.object({
+            ok: z.literal(false),
+            sessionId: z.string(),
+            baseHash: z.string(),
+            conflict: z.object({
+                code: z.enum([
+                    'BASE_HASH_MISMATCH',
+                    'STEP_NOT_FOUND',
+                    'MALFORMED_METADATA',
+                    'WRITE_DENIED',
+                ]),
+                message: z.string(),
+            }),
+        }),
+    ]),
+    executor: async (input, ctx) => {
+        const persistenceRoot = ctx.persistenceRoot ?? ctx.repoRoot;
+        return updatePlan({
+            persistenceRoot,
+            sessionId: input.sessionId,
+            baseHash: input.baseHash,
+            stepId: input.stepId,
+            patch: input.patch,
+        });
+    },
+};
+//# sourceMappingURL=plan.js.map