@kuralle-agents/core 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -94,6 +94,9 @@ export { defineTool } from './types/effectTool.js';
 export { fsErrorCode } from './types/filesystem.js';
 export { createFsTool } from './tools/fs/createFsTool.js';
 export type { CreateFsToolOptions, GrepHit } from './tools/fs/createFsTool.js';
+export { createShellTool } from './tools/fs/createShellTool.js';
+export type { CreateShellToolOptions } from './tools/fs/createShellTool.js';
+export type { Shell, ShellResult, ShellExecOptions } from './types/shell.js';
 export { SkillsCapability, wireAgentSkills, collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, InlineSkillStore, } from './skills/index.js';
 export type { WiredAgentSkills, SkillWireAgent } from './skills/index.js';
 export { buildToolSet, toolToAiSdk, wrapAiSdkTool, ToolApprovalDeniedError, ToolTimeoutError, } from './tools/effect/index.js';

package/dist/index.js

@@ -53,6 +53,7 @@ export { defineAgent, defineFlow, reply, collect, action, decide, confirmGate, }
 export { defineTool } from './types/effectTool.js';
 export { fsErrorCode } from './types/filesystem.js';
 export { createFsTool } from './tools/fs/createFsTool.js';
+export { createShellTool } from './tools/fs/createShellTool.js';
 export { SkillsCapability, wireAgentSkills, collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, InlineSkillStore, } from './skills/index.js';
 export { buildToolSet, toolToAiSdk, wrapAiSdkTool, ToolApprovalDeniedError, ToolTimeoutError, } from './tools/effect/index.js';
 export { parseConfirmation } from './flow/confirmParse.js';

package/dist/runtime/buildAgentToolSurface.js

@@ -1,4 +1,5 @@
 import { createFsTool } from '../tools/fs/createFsTool.js';
+import { createShellTool } from '../tools/fs/createShellTool.js';
 import { wireAgentSkills } from '../skills/wireAgentSkills.js';
 import { buildKnowledgeTool, wireWorkingMemory } from './grounding/index.js';
 import { resolveAgentWorkspace, } from './resolveAgentWorkspace.js';
@@ -17,6 +18,9 @@ export async function buildAgentToolSurface(agent, session, deps) {
         });
         executorTools.workspace = workspaceTool;
     }
+    if (resolvedWorkspace?.shell) {
+        executorTools.bash = createShellTool({ shell: resolvedWorkspace.shell });
+    }
     const wiredWorkingMemory = await wireWorkingMemory(agent, session, deps.defaultWorkingMemoryStore);
     if (wiredWorkingMemory) {
         executorTools.memory_block = wiredWorkingMemory.memoryBlockTool;

package/dist/runtime/ctx.js

@@ -140,7 +140,7 @@ function makeCtx(deps) {
             }
             const callsite = consumeCallsite();
             const key = toolEffectKey(deps.runState.runId, callsite, name, args);
-            return replayOrExecute(key, 'tool', name, () => deps.toolExecutor.execute({
+            const executeTool = () => deps.toolExecutor.execute({
                 name,
                 args,
                 session: deps.session,
@@ -148,7 +148,32 @@ function makeCtx(deps) {
                 abortSignal: deps.bargeIn ?? deps.abortSignal,
                 def: options?.def,
                 toolCtx: options?.toolCtx,
-            }));
+            });
+            if (def?.replay === false) {
+                const auditKey = `${key}:${steps.length}`;
+                try {
+                    const result = await executeTool();
+                    await appendLiveStep(auditKey, 'tool', name, result);
+                    return result;
+                }
+                catch (error) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    const startedAt = Date.now();
+                    const record = {
+                        index: steps.length,
+                        key: auditKey,
+                        kind: 'tool',
+                        name,
+                        error: { name: err.name, message: err.message },
+                        startedAt,
+                        finishedAt: startedAt,
+                    };
+                    await deps.runStore.appendStep(deps.runState.runId, record);
+                    steps.push(record);
+                    throw err;
+                }
+            }
+            return replayOrExecute(key, 'tool', name, executeTool);
         },
         approve: async (req) => {
             return pauseEffect(APPROVAL_SIGNAL, { approval: req });

package/dist/runtime/resolveAgentWorkspace.d.ts

@@ -1,10 +1,13 @@
 import type { FileSystem } from '../types/filesystem.js';
+import type { Shell } from '../types/shell.js';
 export type AgentWorkspaceConfig = FileSystem | {
     fs: FileSystem;
+    shell?: Shell;
     readOnly?: boolean;
 };
 export interface ResolvedAgentWorkspace {
     fs: FileSystem;
+    shell?: Shell;
     readOnly: boolean;
 }
 export declare function resolveAgentWorkspace(workspace: AgentWorkspaceConfig | undefined): ResolvedAgentWorkspace | undefined;

package/dist/runtime/resolveAgentWorkspace.js

@@ -3,7 +3,11 @@ export function resolveAgentWorkspace(workspace) {
         return undefined;
     }
     if (typeof workspace === 'object' && workspace !== null && 'fs' in workspace) {
-        return { fs: workspace.fs, readOnly: workspace.readOnly !== false };
+        return {
+            fs: workspace.fs,
+            shell: workspace.shell,
+            readOnly: workspace.readOnly !== false,
+        };
     }
-    return { fs: workspace, readOnly: true };
+    return { fs: workspace, readOnly: true, shell: undefined };
 }

package/dist/tools/effect/ToolExecutor.js

@@ -114,7 +114,12 @@ export class CoreToolExecutor {
                     interimTimer.unref();
                 }
             }
-            const executePromise = Promise.resolve(def.execute(sanitizedArgs, toolCtx)).then(async (result) => {
+            const executeCtx = toolCtx
+                ? { ...toolCtx, abortSignal }
+                : abortSignal
+                    ? { abortSignal }
+                    : undefined;
+            const executePromise = Promise.resolve(def.execute(sanitizedArgs, executeCtx)).then(async (result) => {
                 if (result && typeof result[Symbol.asyncIterator] === 'function') {
                     const chunks = [];
                     for await (const chunk of result) {

package/dist/tools/effect/defineTool.d.ts

@@ -18,6 +18,7 @@ export declare function defineTool<S extends z.ZodTypeAny | StandardSchemaV1 | u
     /** @deprecated Use `interimAfterMs`. */
     estimatedDurationMs?: number;
     timeoutMs?: number;
+    replay?: boolean;
     execute: (args: InferToolInput<S>, ctx?: ToolContext) => Promise<R> | AsyncIterable<R>;
 }): Tool<InferToolInput<S>, R>;
 export declare function toolToAiSdk<TInput = unknown, TOutput = unknown>(def: Tool<TInput, TOutput>): AiTool<TInput, TOutput>;

package/dist/tools/effect/defineTool.js

@@ -10,6 +10,7 @@ export function defineTool(config) {
         interim: config.interim ?? config.filler,
         interimAfterMs: config.interimAfterMs ?? config.estimatedDurationMs,
         timeoutMs: config.timeoutMs,
+        replay: config.replay,
         execute: config.execute,
     };
 }

package/dist/tools/fs/caps.d.ts

@@ -0,0 +1,21 @@
+export declare const MAX_READ_LINES = 2000;
+export declare const MAX_READ_BYTES: number;
+export declare const MAX_GREP_HITS = 200;
+export declare const MAX_GREP_LINE_LEN = 500;
+export declare const MAX_LIST_ENTRIES = 1000;
+export declare const MAX_SHELL_OUTPUT_BYTES: number;
+export declare function applyReadWindow(content: string, offset?: number, limit?: number): {
+    content: string;
+    truncated: boolean;
+    note?: string;
+};
+export declare function capGrepHits<T extends {
+    text: string;
+}>(hits: T[]): {
+    hits: T[];
+    truncated: boolean;
+};
+export declare function capList<T>(entries: T[]): {
+    entries: T[];
+    truncated: boolean;
+};

package/dist/tools/fs/caps.js

@@ -0,0 +1,59 @@
+export const MAX_READ_LINES = 2000;
+export const MAX_READ_BYTES = 50 * 1024;
+export const MAX_GREP_HITS = 200;
+export const MAX_GREP_LINE_LEN = 500;
+export const MAX_LIST_ENTRIES = 1000;
+export const MAX_SHELL_OUTPUT_BYTES = 50 * 1024;
+export function applyReadWindow(content, offset, limit) {
+    const allLines = content.split('\n');
+    let lines = allLines;
+    let truncated = false;
+    const notes = [];
+    // `offset` is a 1-indexed start line. 0, 1, and undefined all mean "from the
+    // start" — models routinely fill an optional numeric arg with 0, and that must
+    // not silently empty the read.
+    if (offset !== undefined && offset > 1) {
+        lines = lines.slice(offset - 1);
+        truncated = true;
+    }
+    // `limit` caps the returned line count only when positive. 0 and undefined
+    // both mean "no explicit limit" (still bounded by MAX_READ_LINES below).
+    if (limit !== undefined && limit > 0 && lines.length > limit) {
+        lines = lines.slice(0, limit);
+        truncated = true;
+    }
+    if (lines.length > MAX_READ_LINES) {
+        lines = lines.slice(0, MAX_READ_LINES);
+        truncated = true;
+        notes.push(`truncated at ${MAX_READ_LINES} lines; use offset/limit`);
+    }
+    let result = lines.join('\n');
+    if (result.length > MAX_READ_BYTES) {
+        result = result.slice(0, MAX_READ_BYTES);
+        truncated = true;
+        if (!notes.some((n) => n.includes('bytes'))) {
+            notes.push(`truncated at ${MAX_READ_BYTES} bytes; use offset/limit`);
+        }
+    }
+    if (!truncated) {
+        return { content: result, truncated: false };
+    }
+    const note = notes.length > 0 ? notes.join('; ') : 'truncated; use offset/limit';
+    return { content: result, truncated: true, note };
+}
+export function capGrepHits(hits) {
+    const truncated = hits.length > MAX_GREP_HITS;
+    const capped = hits.slice(0, MAX_GREP_HITS).map((hit) => {
+        if (hit.text.length <= MAX_GREP_LINE_LEN)
+            return hit;
+        return {
+            ...hit,
+            text: `${hit.text.slice(0, MAX_GREP_LINE_LEN)}…`,
+        };
+    });
+    return { hits: capped, truncated };
+}
+export function capList(entries) {
+    const truncated = entries.length > MAX_LIST_ENTRIES;
+    return { entries: entries.slice(0, MAX_LIST_ENTRIES), truncated };
+}

package/dist/tools/fs/createFsTool.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { defineTool } from '../effect/defineTool.js';
 import { fsErrorCode } from '../../types/filesystem.js';
+import { applyReadWindow, capGrepHits, capList } from './caps.js';
 const DEFAULT_READ_ONLY = true;
 const workspaceInput = z.object({
     op: z.enum(['ls', 'cat', 'grep', 'find', 'read', 'write', 'edit']),
@@ -12,6 +13,9 @@ const workspaceInput = z.object({
     content: z.string().optional(),
     find: z.string().optional(),
     replace: z.string().optional(),
+    offset: z.number().optional(),
+    limit: z.number().optional(),
+    replaceAll: z.boolean().optional(),
 });
 function normalizeFsPath(path, fallback = '/') {
     if (!path || path.trim() === '')
@@ -32,6 +36,32 @@ function assertWritable(readOnly, path) {
     if (readOnly)
         throw eroFs(path);
 }
+const GREP_FLAG_ORDER = ['g', 'i', 'm', 's'];
+function parseGrepFlags(flags) {
+    if (!flags)
+        return undefined;
+    const allowed = new Set(GREP_FLAG_ORDER);
+    const seen = new Set();
+    const out = [];
+    for (const ch of flags) {
+        if (allowed.has(ch) && !seen.has(ch)) {
+            seen.add(ch);
+            out.push(ch);
+        }
+    }
+    return out.length > 0 ? out.join('') : undefined;
+}
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let pos = 0;
+    while ((pos = haystack.indexOf(needle, pos)) !== -1) {
+        count++;
+        pos += needle.length;
+    }
+    return count;
+}
 async function listFiles(fs, root) {
     const normalized = root === '' ? '/' : root;
     const out = [];
@@ -62,7 +92,7 @@ async function listFiles(fs, root) {
 async function grepFiles(fs, pattern, root, flags) {
     let re;
     try {
-        re = new RegExp(pattern, flags?.includes('i') ? 'i' : undefined);
+        re = new RegExp(pattern, parseGrepFlags(flags));
     }
     catch {
         throw new Error(`EINVAL: invalid grep pattern '${pattern}'`);
@@ -84,6 +114,7 @@ async function grepFiles(fs, pattern, root, flags) {
             }
             const lines = content.split('\n');
             for (let i = 0; i < lines.length; i++) {
+                re.lastIndex = 0;
                 if (re.test(lines[i])) {
                     hits.push({ path: filePath, line: i + 1, text: lines[i] });
                 }
@@ -105,6 +136,7 @@ async function grepFiles(fs, pattern, root, flags) {
         }
         const lines = content.split('\n');
         for (let i = 0; i < lines.length; i++) {
+            re.lastIndex = 0;
             if (re.test(lines[i])) {
                 hits.push({ path: filePath, line: i + 1, text: lines[i] });
             }
@@ -133,19 +165,30 @@ export function createFsTool(opts) {
             switch (args.op) {
                 case 'ls': {
                     const path = normalizeFsPath(args.path);
-                    const entries = await fs.readdirWithFileTypes(path);
+                    const rawEntries = await fs.readdirWithFileTypes(path);
+                    const { entries, truncated } = capList(rawEntries);
                     return {
                         op: args.op,
                         ok: true,
                         path,
                         entries,
+                        ...(truncated ? { truncated: true } : {}),
                     };
                 }
                 case 'cat':
                 case 'read': {
                     const path = requireField(args, 'path', args.op);
-                    const content = await fs.readFile(path);
-                    return { op: args.op, ok: true, path, content };
+                    const raw = await fs.readFile(path);
+                    const windowed = applyReadWindow(raw, args.offset, args.limit);
+                    return {
+                        op: args.op,
+                        ok: true,
+                        path,
+                        content: windowed.content,
+                        ...(windowed.truncated
+                            ? { truncated: true, note: windowed.note }
+                            : {}),
+                    };
                 }
                 case 'find': {
                     const root = normalizeFsPath(args.root);
@@ -155,24 +198,28 @@ export function createFsTool(opts) {
                         const normalizedRoot = root === '/' ? '/' : root.replace(/\/$/, '');
                         return p === normalizedRoot || p.startsWith(`${normalizedRoot}/`);
                     });
+                    const { entries: cappedPaths, truncated } = capList(rooted);
                     return {
                         op: args.op,
                         ok: true,
                         root,
                         glob,
-                        paths: rooted,
+                        paths: cappedPaths,
+                        ...(truncated ? { truncated: true } : {}),
                     };
                 }
                 case 'grep': {
                     const pattern = requireField(args, 'pattern', args.op);
                     const path = normalizeFsPath(args.path);
-                    const hits = await grepFiles(fs, pattern, path, args.flags);
+                    const rawHits = await grepFiles(fs, pattern, path, args.flags);
+                    const { hits, truncated } = capGrepHits(rawHits);
                     return {
                         op: args.op,
                         ok: true,
                         pattern,
                         path,
                         hits,
+                        ...(truncated ? { truncated: true } : {}),
                     };
                 }
                 case 'write': {
@@ -188,9 +235,23 @@ export function createFsTool(opts) {
                     const replace = requireField(args, 'replace', args.op);
                     assertWritable(readOnly, path);
                     const current = await fs.readFile(path);
-                    if (!current.includes(find)) {
+                    const occurrences = countOccurrences(current, find);
+                    if (occurrences === 0) {
                         throw new Error(`ENOENT: find string not found in file, edit '${path}'`);
                     }
+                    if (args.replaceAll) {
+                        const next = current.replaceAll(find, replace);
+                        await fs.writeFile(path, next);
+                        return {
+                            op: args.op,
+                            ok: true,
+                            path,
+                            replacements: occurrences,
+                        };
+                    }
+                    if (occurrences > 1) {
+                        throw new Error(`EAMBIG: ${occurrences} occurrences of find string in '${path}'; add surrounding context or use replaceAll`);
+                    }
                     const next = current.replace(find, replace);
                     await fs.writeFile(path, next);
                     return { op: args.op, ok: true, path };

package/dist/tools/fs/createShellTool.d.ts

@@ -0,0 +1,7 @@
+import type { AnyTool } from '../../types/effectTool.js';
+import type { Shell } from '../../types/shell.js';
+export interface CreateShellToolOptions {
+    shell: Shell;
+    timeoutMs?: number;
+}
+export declare function createShellTool(opts: CreateShellToolOptions): AnyTool;

package/dist/tools/fs/createShellTool.js

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { defineTool } from '../effect/defineTool.js';
+import { MAX_SHELL_OUTPUT_BYTES } from './caps.js';
+const bashInput = z.object({
+    command: z.string(),
+    timeout: z.number().optional(),
+});
+const TIMEOUT_EXIT_CODE = 124;
+function isTimeoutError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const msg = error.message.toLowerCase();
+    return msg.includes('timeout') || msg.includes('timed out');
+}
+function capShellOutput(stdout, stderr) {
+    const combined = stdout.length + stderr.length;
+    if (combined <= MAX_SHELL_OUTPUT_BYTES) {
+        return { stdout, stderr };
+    }
+    const note = `\n[kuralle] output truncated at ${MAX_SHELL_OUTPUT_BYTES} bytes`;
+    const budget = MAX_SHELL_OUTPUT_BYTES - note.length;
+    if (budget <= 0) {
+        return { stdout: '', stderr: note.trim() };
+    }
+    if (stdout.length >= budget) {
+        return { stdout: stdout.slice(0, budget), stderr: note.trim() };
+    }
+    const stderrBudget = budget - stdout.length;
+    return {
+        stdout,
+        stderr: `${stderr.slice(0, stderrBudget)}${note}`,
+    };
+}
+export function createShellTool(opts) {
+    const defaultTimeoutMs = opts.timeoutMs;
+    return defineTool({
+        name: 'bash',
+        description: 'Run a shell command in the agent workspace. Returns stdout, stderr, exitCode. Output is truncated when large.',
+        replay: false,
+        input: bashInput,
+        execute: async (args, ctx) => {
+            const timeoutMs = args.timeout !== undefined ? args.timeout * 1000 : defaultTimeoutMs;
+            if (ctx?.abortSignal?.aborted) {
+                throw new DOMException('Aborted', 'AbortError');
+            }
+            let result;
+            try {
+                result = await opts.shell.exec(args.command, {
+                    timeoutMs,
+                    signal: ctx?.abortSignal,
+                });
+            }
+            catch (error) {
+                if (ctx?.abortSignal?.aborted) {
+                    throw error;
+                }
+                if (isTimeoutError(error)) {
+                    const seconds = timeoutMs !== undefined ? Math.round(timeoutMs / 1000) : args.timeout ?? 0;
+                    return {
+                        op: 'bash',
+                        ok: false,
+                        stdout: '',
+                        stderr: `[kuralle] command timed out after ${seconds}s`,
+                        exitCode: TIMEOUT_EXIT_CODE,
+                    };
+                }
+                throw error;
+            }
+            if (result.exitCode === TIMEOUT_EXIT_CODE) {
+                const seconds = timeoutMs !== undefined ? Math.round(timeoutMs / 1000) : args.timeout ?? 0;
+                return {
+                    op: 'bash',
+                    ok: false,
+                    stdout: result.stdout,
+                    stderr: result.stderr ||
+                        `[kuralle] command timed out after ${seconds}s`,
+                    exitCode: TIMEOUT_EXIT_CODE,
+                };
+            }
+            const capped = capShellOutput(result.stdout, result.stderr);
+            return {
+                op: 'bash',
+                ok: result.exitCode === 0,
+                stdout: capped.stdout,
+                stderr: capped.stderr,
+                exitCode: result.exitCode,
+            };
+        },
+    });
+}

package/dist/types/agentConfig.d.ts

@@ -8,9 +8,11 @@ import type { RefinementCapability } from '../capabilities/RefinementCapability.
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { AnyTool } from './effectTool.js';
 import type { FileSystem } from './filesystem.js';
+import type { Shell } from './shell.js';
 import type { SkillSource } from './skills.js';
 export type AgentWorkspaceConfig = FileSystem | {
     fs: FileSystem;
+    shell?: Shell;
     readOnly?: boolean;
 };
 export type Instructions = string | AgentPrompt | ((ctx: {

package/dist/types/effectTool.d.ts

@@ -10,6 +10,8 @@ export interface Tool<TInput = unknown, TOutput = unknown> {
     interim?: string;
     interimAfterMs?: number;
     timeoutMs?: number;
+    /** When false, the durable journal always re-executes this tool instead of returning a cached step result — for observation/mutation tools (fs, shell) whose result must be fresh. Default true. */
+    replay?: boolean;
     execute: (args: TInput, ctx?: ToolContext) => Promise<TOutput> | AsyncIterable<TOutput>;
 }
 export type AnyTool = Tool<any, any>;

package/dist/types/run-context.d.ts

@@ -118,5 +118,5 @@ export interface RunContext {
     resetCallsites(): void;
 }
 export type ActionContext = Pick<RunContext, 'tool' | 'approve' | 'signal' | 'now' | 'uuid' | 'emit' | 'fs'>;
-export type ToolContext = Pick<RunContext, 'session' | 'runState' | 'tool' | 'now' | 'uuid' | 'emit' | 'fs'>;
+export type ToolContext = Pick<RunContext, 'session' | 'runState' | 'tool' | 'now' | 'uuid' | 'emit' | 'fs' | 'abortSignal'>;
 export type { ModelMessage };

package/dist/types/shell.d.ts

@@ -0,0 +1,15 @@
+export interface ShellResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface ShellExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface Shell {
+    exec(command: string, options?: ShellExecOptions): Promise<ShellResult>;
+    cwd?: string;
+}

package/dist/types/shell.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-core"
   },
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A framework for structured conversational AI agents",
   "publishConfig": {
     "access": "public"
@@ -103,7 +103,7 @@
     "typescript": "^5.3.0",
     "vitest": "^3.2.4",
     "zod": "^4.0.0",
-    "@kuralle-agents/realtime-audio": "0.11.0"
+    "@kuralle-agents/realtime-audio": "0.12.0"
   },
   "dependencies": {
     "chrono-node": "^2.6.0"
@@ -111,6 +111,7 @@
   "scripts": {
     "prebuild": "rm -rf dist",
     "build": "tsc -p tsconfig.json",
+    "typecheck:audit": "tsc --noEmit -p tsconfig.audit.json",
     "typecheck:examples": "tsc --noEmit -p tsconfig.examples.json",
     "clean": "rm -rf dist",
     "test": "bun test ./test && vitest run --config vitest.config.ts",