klyro 1.0.5 → 1.0.7

package/README.md

@@ -55,6 +55,19 @@ node dist/index.js chat
 | `KLYRO_WORKER=0` | Disable subprocess isolation for subagents |
 | `KLYRO_SESSIONS_DIR`, `KLYRO_UPDATE_CACHE`, `KLYRO_CREDENTIALS_FILE` | Relocatable state (tests + power users) |
 
+## New in recent releases
+
+- `klyro run --bare` — deterministic runs: skips MCP, hooks, memory/KLYRO.md/context, persistence
+- `klyro mcp trust <name>` / `mcp prompts [server]` / `mcp add <name> <https-url>` — remote MCP + prompt trust
+- `klyro agents lint` — validate `.klyro/agents/*.md` (ids, tool names)
+- `klyro init` — scan-seeded `KLYRO.md` + `.mcp.json` (never overwrites)
+- `klyro update --apply` — opt-in self-apply of the verified update
+- `klyro eval --judge-model <id>` — model-graded rubric scoring
+- Hooks: `matcher` scoping, stdin JSON, `sessionStart`/`sessionEnd`/`stop` events, JSON verdicts
+- Custom agents (`.klyro/agents/*.md`), custom commands (`.klyro/commands/*.md`), vim mode (`/vim`), `@`-file completion
+- Credentials prefer the OS keychain (macOS Keychain, Linux libsecret), 0600 file fallback
+- Headless JSON ends with exactly one stable `kind:result` envelope (parse the LAST line)
+
 ## Documentation
 
 | Doc | Purpose |

package/dist/agent/custom-agents.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition } from './orchestrator.js';
+/** Load custom agents: global first, project wins on id clash. Never throws. */
+export declare function loadCustomAgents(cwd: string): AgentDefinition[];

package/dist/agent/custom-agents.js

@@ -0,0 +1,96 @@
+/**
+ * Custom subagents from markdown files:
+ *   `<cwd>/.klyro/agents/*.md` (project) + `~/.klyro/agents/*.md` (global).
+ * Project wins on id clash (including overriding a builtin).
+ *
+ * Frontmatter fields: name (default: filename), description, tools
+ * (comma/list — omitted inherits parent tools), model, readonly,
+ * canSpawn, maxSteps, maxTokens, maxCost, maxTimeMs, allowedPaths.
+ * The markdown body becomes specialist instructions (`prompt`) prepended
+ * to the delegated task. Unknown tool names are NOT rejected here —
+ * `resolveCapabilities` drops them with reasons at spawn time.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { parseFrontmatter, parseList, parseBool, parseInt_ } from '../cli/slash/custom.js';
+const AGENT_ID_RE = /^[A-Za-z0-9_-]{1,32}$/;
+function readAgentFile(file, source) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const { data, body } = parseFrontmatter(raw);
+    const fallback = path.basename(file, path.extname(file));
+    const id = (data['name'] || fallback).toLowerCase();
+    if (!AGENT_ID_RE.test(id))
+        return null;
+    const description = data['description'] || `Custom agent ${id}`;
+    const def = { id, description };
+    const tools = parseList(data['tools']);
+    if (tools.length > 0)
+        def.allowedTools = tools;
+    if (data['model'])
+        def.model = data['model'];
+    if (data['readonly'] !== undefined && data['readonly'] !== '')
+        def.readonly = parseBool(data['readonly'], false);
+    if (data['canSpawn'] !== undefined && data['canSpawn'] !== '')
+        def.canSpawn = parseBool(data['canSpawn'], false);
+    const maxSteps = parseInt_(data['maxsteps']);
+    if (maxSteps !== undefined)
+        def.maxSteps = maxSteps;
+    const maxTokens = parseInt_(data['maxtokens']);
+    if (maxTokens !== undefined)
+        def.maxTokens = maxTokens;
+    const maxCost = data['maxcost'] !== undefined && data['maxcost'] !== '' ? Number(data['maxcost']) : undefined;
+    if (maxCost !== undefined && Number.isFinite(maxCost) && maxCost > 0)
+        def.maxCost = maxCost;
+    const maxTimeMs = parseInt_(data['maxtimems']);
+    if (maxTimeMs !== undefined)
+        def.maxTimeMs = maxTimeMs;
+    const paths = parseList(data['allowedpaths']);
+    if (paths.length > 0)
+        def.allowedPaths = paths;
+    const prompt = body.trim();
+    if (prompt)
+        def.prompt = prompt;
+    def.source = source;
+    return def;
+}
+function listAgentFiles(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md'))
+        .map((e) => path.join(dir, e.name))
+        .sort();
+}
+/** Load custom agents: global first, project wins on id clash. Never throws. */
+export function loadCustomAgents(cwd) {
+    const byId = new Map();
+    try {
+        const home = os.homedir() || process.cwd();
+        for (const f of listAgentFiles(path.join(home, '.klyro', 'agents'))) {
+            const d = readAgentFile(f, 'global');
+            if (d)
+                byId.set(d.id, d);
+        }
+        for (const f of listAgentFiles(path.join(cwd, '.klyro', 'agents'))) {
+            const d = readAgentFile(f, 'project');
+            if (d)
+                byId.set(d.id, d);
+        }
+    }
+    catch {
+        return [...byId.values()];
+    }
+    return [...byId.values()];
+}

package/dist/agent/orchestrator.d.ts

@@ -43,9 +43,21 @@ export interface AgentDefinition {
      * spawn time (`undefined` = no additional constraint).
      */
     allowedPaths?: string[];
+    /**
+     * Specialist instructions (from `.klyro/agents/*.md` body or programmatic
+     * defs). Prepended to the delegated task at spawn time.
+     */
+    prompt?: string;
+    /** Where the definition came from (builtins omit this = 'builtin'). */
+    source?: 'builtin' | 'project' | 'global';
 }
 /** Default agents a model can delegate to. */
 export declare const BUILTIN_AGENTS: readonly AgentDefinition[];
+/**
+ * Layer specialist instructions into a child's system prompt (not the user
+ * task). Pure — unit-tested directly. No-op when the def has no prompt.
+ */
+export declare function layerSpecialistPrompt(base: RuntimeDeps['systemPrompt'], def: Pick<AgentDefinition, 'id' | 'prompt'>): RuntimeDeps['systemPrompt'];
 /** Compact summary returned to the parent — the child's transcript stays separate. */
 export interface ChildSummary {
     taskId: string;
@@ -158,7 +170,20 @@ export interface OrchestratorOpts {
      * always isolate. Defaults to false.
      */
     isTui?: boolean;
+    /**
+     * Working directory used to discover custom agents
+     * (`.klyro/agents/*.md`). Defaults to `process.cwd()`.
+     */
+    cwd?: string;
 }
+/**
+ * All agents: builtins plus custom `.klyro/agents/*.md` definitions.
+ * Custom ids win on clash (including overriding a builtin) — the override
+ * is surfaced via `source`. No instance needed; used by CLI + spawn paths.
+ */
+export declare function listAllAgents(cwd?: string): AgentDefinition[];
+/** Find one agent by id across builtins + custom files. */
+export declare function findAgent(id: string, cwd?: string): AgentDefinition | undefined;
 /**
  * Build a `subtask.progress` note for one finished tool call.
  * Pure — unit-tested directly (see agent-tools.test.ts).
@@ -182,6 +207,7 @@ export declare class AgentOrchestrator {
     readonly taskManager: TaskManager;
     readonly workerSpawner: WorkerSpawner;
     readonly isTui: boolean;
+    private readonly customCwd;
     /** Per-task spawn metadata: capability drops + worktree placement. */
     private readonly taskMeta;
     /** Finished summaries not yet drained via `drainCompletions`. */

package/dist/agent/orchestrator.js

@@ -19,6 +19,7 @@ import { TaskManager } from './task-manager.js';
 import { WorkerSpawner } from './worker-spawner.js';
 import { resolveCapabilities, DEFAULT_WRITE_TOOLS, DEFAULT_SPAWN_TOOLS, DEFAULT_DENIED_TOOLS, } from './capabilities.js';
 import { forkChild, workerEntryPath } from './child-worker.js';
+import { loadCustomAgents } from './custom-agents.js';
 import { resolveAndFollowSymlinks } from '../policy/path-guard.js';
 import { ensureGitRepo, createWorktree, mergeWorktree, removeWorktree, deleteBranch, } from './worktree-manager.js';
 /** Concurrency budgets enforced in `spawnAgent` (CONCURRENCY_LIMIT on exceed). */
@@ -70,6 +71,39 @@ export const BUILTIN_AGENTS = [
         allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'repo_map', 'recent_files'],
     },
 ];
+/**
+ * Layer specialist instructions into a child's system prompt (not the user
+ * task). Pure — unit-tested directly. No-op when the def has no prompt.
+ */
+export function layerSpecialistPrompt(base, def) {
+    if (!def.prompt)
+        return base;
+    return (ctx) => {
+        const r = base(ctx);
+        const block = `\n\n<specialist id="${def.id}">\n${def.prompt}\n</specialist>`;
+        return typeof r === 'string' ? r + block : { ...r, system: r.system + block };
+    };
+}
+/**
+ * All agents: builtins plus custom `.klyro/agents/*.md` definitions.
+ * Custom ids win on clash (including overriding a builtin) — the override
+ * is surfaced via `source`. No instance needed; used by CLI + spawn paths.
+ */
+export function listAllAgents(cwd) {
+    const byId = new Map();
+    for (const d of BUILTIN_AGENTS)
+        byId.set(d.id, { ...d, source: 'builtin' });
+    try {
+        for (const d of loadCustomAgents(cwd ?? process.cwd()))
+            byId.set(d.id, d);
+    }
+    catch { /* custom agents are best-effort */ }
+    return [...byId.values()];
+}
+/** Find one agent by id across builtins + custom files. */
+export function findAgent(id, cwd) {
+    return listAllAgents(cwd).find((a) => a.id === id);
+}
 /** Map a runtime `RunResult.status` to a task status. */
 function mapResultStatus(status) {
     switch (status) {
@@ -132,6 +166,7 @@ export class AgentOrchestrator {
     taskManager;
     workerSpawner;
     isTui;
+    customCwd;
     /** Per-task spawn metadata: capability drops + worktree placement. */
     taskMeta = new Map();
     /** Finished summaries not yet drained via `drainCompletions`. */
@@ -142,12 +177,13 @@ export class AgentOrchestrator {
         this.taskManager = opts.taskManager ?? new TaskManager({ sessionId: opts.sessionId });
         this.workerSpawner = opts.workerSpawner ?? new WorkerSpawner();
         this.isTui = opts.isTui ?? false;
+        this.customCwd = opts.cwd;
     }
     listAgents() {
-        return [...BUILTIN_AGENTS];
+        return listAllAgents(this.customCwd);
     }
     getAgent(id) {
-        return BUILTIN_AGENTS.find((a) => a.id === id);
+        return listAllAgents(this.customCwd).find((a) => a.id === id);
     }
     /** Build the bridge the parent's runtime hands to tools. */
     bridgeFor(parent) {
@@ -345,7 +381,8 @@ export class AgentOrchestrator {
         }
         this.taskMeta.set(record.id, worktree ? { def, dropped: resolved.dropped, worktree, repoCwd } : { def, dropped: resolved.dropped });
         const childRegistry = new ScopedRegistry(this.deps.registry, resolved.allowed);
-        const childDeps = { ...this.deps, registry: childRegistry };
+        const childPromptFn = layerSpecialistPrompt(this.deps.systemPrompt, def);
+        const childDeps = { ...this.deps, registry: childRegistry, systemPrompt: childPromptFn };
         const childRef = {
             taskId: record.id,
             ...(parent.taskId !== undefined ? { parentTaskId: parent.taskId } : {}),
@@ -405,7 +442,7 @@ export class AgentOrchestrator {
             let childOutcome;
             try {
                 if (useProcessIsolation) {
-                    const sysPrompt = resolveSystemPrompt(this.deps.systemPrompt, { cwd: childCwd });
+                    const sysPrompt = resolveSystemPrompt(childPromptFn, { cwd: childCwd });
                     // Splice the volatile telemetry suffix into the stable prefix so the
                     // child's provider sees one system string. Telemetry is best-effort
                     // inside the child (it re-emits); the goal here is parity, not

package/dist/agent/runtime.d.ts

@@ -85,6 +85,11 @@ export interface RunOptions {
     temperature?: number;
     signal?: AbortSignal;
     nonInteractive: boolean;
+    /**
+     * Bare mode: skip all hooks (load + sessionStart/stop). The caller is
+     * responsible for skipping MCP/persistence/context (see runOnce `bare`).
+     */
+    bare?: boolean;
     /**
      * Optional pre-existing transcript to seed the conversation. When set,
      * the runtime skips the initial `[{role:'user', content:[text(task)]}]`
@@ -126,6 +131,16 @@ export interface RunOptions {
         store?: import('../persistence/store.js').SessionStore;
         sessionId?: string;
     };
+    /**
+     * Level 10 — tamper-evident audit. When an AuditLog is provided, the
+     * runtime writes policy decisions and tool completions into the chained
+     * audit stream (complements, does not replace, persistence). Defaults off
+     * so callers opt in; `klyro` CLI enables it when a sessions dir exists.
+     */
+    audit?: {
+        log?: import('../persistence/audit.js').AuditLog;
+        sessionId?: string;
+    };
     /**
      * Orchestration context (P0). Present for any agent that is itself managed
      * by an AgentOrchestrator — so a child knows who its parent is, how deep the