@oharness/engine 0.1.0

package/dist/agent/agent.js

@@ -0,0 +1,758 @@
+import { errorMessage } from "../core/errors.js";
+import { estimateStringTokens } from "../core/tokens.js";
+import { assistantMessage, emptyUsage, messageText, userMessage } from "../core/types.js";
+import { createTaskTool } from "../tools/builtin/task.js";
+import { ARCHIVE_READER } from "../tools/builtin/recall.js";
+import { ARTIFACT_METADATA_KEY } from "../tools/builtin/artifact.js";
+import { previewJson } from "../util/json.js";
+import { AsyncQueue, mergeStreams } from "../util/queue.js";
+import { createLogger } from "../util/logger.js";
+import { compact, shouldCompact } from "./compaction.js";
+import { capToolResult } from "./overflow.js";
+import { checkWrite, resolveWithin } from "./workspace.js";
+import { SkillRegistry } from "./skills.js";
+import { MemoryStore } from "./memory.js";
+import { createMemoryTools } from "../tools/builtin/memory.js";
+import { createSkillTool } from "../tools/builtin/skill.js";
+import { createMcpResourceTools } from "../tools/builtin/mcp-resource.js";
+import { HookRegistry } from "./hooks.js";
+import { buildSystemPrompt } from "./prompt.js";
+import { SubagentRegistry } from "./subagent.js";
+const DEFAULT_MAX_TURNS = 60;
+/**
+ * The agentic loop: prompt the model, run whatever tools it asks for, feed the
+ * results back, repeat until it stops calling tools.
+ *
+ * Everything provider-specific lives behind `Provider`, so this loop is the
+ * same regardless of which model is selected — including when the model
+ * changes partway through a session.
+ */
+export class Agent {
+    session;
+    tools;
+    hooks;
+    subagents;
+    skills;
+    memory;
+    state;
+    opts;
+    logger;
+    agentId;
+    controller = new AbortController();
+    running = false;
+    sessionStarted = false;
+    /** Set when a hook asks the turn to end; read by the main loop. */
+    stopRequested;
+    /** Memory index for this run's system prompt. */
+    memoryIndex;
+    constructor(opts) {
+        this.opts = opts;
+        this.session = opts.session;
+        this.tools = opts.tools;
+        this.hooks = opts.hooks ?? new HookRegistry();
+        this.subagents = opts.subagents ?? new SubagentRegistry();
+        this.skills = opts.skills ?? new SkillRegistry();
+        this.memory = opts.memory;
+        this.state = opts.session.state;
+        this.agentId = opts.agentId ?? "main";
+        this.logger = (opts.logger ?? createLogger("agent")).child(this.agentId);
+        // Let `recall` reach this session's archive. Bound here rather than passed
+        // through ToolContext so subagents sharing the session see it too.
+        this.state.set(ARCHIVE_READER, () => this.session.archive());
+        // MCP resources and prompts are only reachable through tools, and only
+        // worth advertising when a server is actually connected.
+        if (this.opts.mcp && !this.tools.has("mcp_read_resource")) {
+            const connected = this.opts.mcp.status().some((server) => server.connected);
+            if (connected)
+                this.tools.registerAll(createMcpResourceTools(this.opts.mcp));
+        }
+        if (this.memory && !this.tools.has("memory")) {
+            this.tools.registerAll(createMemoryTools(this.memory));
+        }
+        // Same reasoning as the task tool: the description has to name the skills
+        // that exist, or the model has nothing to match a task against.
+        if (!this.tools.has("skill") && this.skills.size > 0) {
+            this.tools.register(createSkillTool(this.skills));
+        }
+        // The task tool has to be built here: its description enumerates the
+        // subagent types that actually exist in this configuration.
+        if (!this.tools.has("task") && this.subagents.list().length > 0) {
+            this.tools.register(createTaskTool(this));
+        }
+    }
+    /**
+     * Announce a model switch so a UI can render it and hooks can react.
+     * Called by whoever changes the session's model.
+     */
+    async *switchModel(ref) {
+        const { from, to } = this.session.setModel(ref);
+        yield { type: "model_changed", from: from.id, to: to.id };
+    }
+    /**
+     * The model used for compaction summaries. Falls back to the session model
+     * if `smallModel` is unset or unresolvable — a bad alias should degrade to a
+     * pricier summary, never break the turn.
+     */
+    summarizerModel() {
+        const ref = this.opts.smallModel;
+        if (!ref)
+            return this.session.model;
+        try {
+            return this.session.providers.resolve(ref);
+        }
+        catch {
+            this.logger.warn("smallModel could not be resolved; using the session model", { ref });
+            return this.session.model;
+        }
+    }
+    /** Run the SessionEnd hook. Call when the session is finished with. */
+    async end() {
+        if (!this.sessionStarted)
+            return;
+        this.sessionStarted = false;
+        await this.hooks.run({
+            event: "SessionEnd",
+            sessionId: this.session.id,
+            agentId: this.agentId,
+            cwd: this.session.cwd,
+            messages: this.session.messages,
+        });
+    }
+    /** Cancel the in-flight turn. The loop exits with `stopReason: "aborted"`. */
+    abort() {
+        this.controller.abort();
+    }
+    get isRunning() {
+        return this.running;
+    }
+    // --- ToolHost -----------------------------------------------------------
+    /**
+     * Where the file tools are allowed to look. The policy lives here, so the
+     * tools ask rather than each re-deriving a notion of "inside the project".
+     */
+    resolvePath(input, access) {
+        return resolveWithin(this.opts.workspace, this.session.cwd, input, access);
+    }
+    listSubagentTypes() {
+        return this.subagents.summaries();
+    }
+    async runSubagent(opts) {
+        const definition = this.subagents.get(opts.agentType);
+        if (!definition)
+            throw new Error(`unknown agent type: ${opts.agentType}`);
+        // A subagent gets its own transcript and a filtered tool set, but shares
+        // the parent's scratch state so file-read tracking stays coherent.
+        const { Session: SessionClass } = await import("./session.js");
+        const child = new SessionClass({
+            cwd: this.session.cwd,
+            model: opts.model ?? definition.model ?? this.session.model.id,
+            providers: this.session.providers,
+            permissionMode: this.session.permissions.getMode(),
+            store: false,
+        });
+        for (const [key, value] of this.session.state)
+            child.state.set(key, value);
+        const childAgent = new Agent({
+            ...this.opts,
+            session: child,
+            tools: definition.tools ? this.tools.filtered(definition.tools) : this.tools.clone(),
+            systemPrompt: definition.systemPrompt,
+            appendSystemPrompt: undefined,
+            maxTurns: definition.maxTurns ?? this.opts.maxTurns,
+            agentId: `${this.agentId}/${definition.name}`,
+            // One level of delegation: a subagent may not spawn further subagents.
+            subagents: new SubagentRegistry([]),
+        });
+        let text = "";
+        let turns = 0;
+        let usage = emptyUsage();
+        for await (const event of childAgent.run(opts.prompt, { signal: opts.signal })) {
+            if (event.type === "assistant_message") {
+                const messageBody = messageText(event.message);
+                if (messageBody.trim())
+                    text = messageBody;
+            }
+            else if (event.type === "done") {
+                turns = event.turns;
+                usage = event.usage;
+            }
+        }
+        // Propagate state the subagent built up (e.g. files it read).
+        for (const [key, value] of child.state)
+            this.session.state.set(key, value);
+        await this.hooks.run({
+            event: "SubagentStop",
+            sessionId: this.session.id,
+            agentId: `${this.agentId}/${definition.name}`,
+            cwd: this.session.cwd,
+        });
+        return {
+            text,
+            turns,
+            usage: { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens },
+        };
+    }
+    // --- Main loop ----------------------------------------------------------
+    async *run(input, runOpts = {}) {
+        this.running = true;
+        this.controller = new AbortController();
+        const external = runOpts.signal;
+        if (external) {
+            if (external.aborted)
+                this.controller.abort();
+            else
+                external.addEventListener("abort", () => this.controller.abort(), { once: true });
+        }
+        const signal = this.controller.signal;
+        // Fired once per session rather than per turn: hooks use it to seed
+        // context or announce the session, which should not repeat every prompt.
+        if (!this.sessionStarted) {
+            this.sessionStarted = true;
+            const start = await this.hooks.run({
+                event: "SessionStart",
+                sessionId: this.session.id,
+                agentId: this.agentId,
+                cwd: this.session.cwd,
+                messages: this.session.messages,
+            });
+            if (start.additionalContext) {
+                yield { type: "notice", message: start.additionalContext };
+            }
+        }
+        const maxTurns = this.opts.maxTurns ?? DEFAULT_MAX_TURNS;
+        let stopReason = "end_turn";
+        let turn = 0;
+        try {
+            await this.session.init();
+            // Read once per run: the index is only rebuilt when the agent writes a
+            // note, and re-reading the directory every turn would be wasteful.
+            this.memoryIndex = await this.memory?.promptSection();
+            yield* this.ingestInput(input);
+            while (turn < maxTurns) {
+                if (signal.aborted) {
+                    stopReason = "aborted";
+                    break;
+                }
+                turn++;
+                this.session.turns++;
+                yield { type: "turn_start", turn, model: this.session.model.id };
+                yield* this.maybeCompact();
+                const request = this.buildRequest(signal);
+                await this.hooks.run({
+                    event: "PreModelRequest",
+                    sessionId: this.session.id,
+                    agentId: this.agentId,
+                    cwd: this.session.cwd,
+                    messages: this.session.messages,
+                });
+                let assembled;
+                try {
+                    assembled = yield* this.streamAssistant(request);
+                }
+                catch (err) {
+                    const message = errorMessage(err);
+                    this.logger.error("provider request failed", { error: message });
+                    // Read off the error rather than narrowed to ProviderError: the
+                    // engine is imported through more than one specifier in this
+                    // workspace, and an instanceof against a class that may have been
+                    // loaded twice is a check that fails for reasons unrelated to what
+                    // it is asking.
+                    const status = err?.status;
+                    // And which vendor said it, read off the same way and for the same
+                    // reason the status is: a 401 is not a sentence to print but a
+                    // provider to reconnect, and the consumer cannot know which one that
+                    // is — a fallback may have moved off the model the session names.
+                    const provider = err?.provider;
+                    yield {
+                        type: "error",
+                        error: message,
+                        ...(typeof status === "number" ? { status } : {}),
+                        ...(typeof provider === "string" ? { provider } : {}),
+                        fatal: true,
+                    };
+                    stopReason = "error";
+                    break;
+                }
+                this.session.recordUsage(assembled.usage);
+                const message = assistantMessage(assembled.content, {
+                    model: this.session.model.model,
+                    provider: this.session.model.provider,
+                    usage: assembled.usage,
+                    stopReason: assembled.stopReason,
+                });
+                // An empty assistant turn would be rejected on the next request, so
+                // never persist one.
+                if (message.content.length > 0) {
+                    await this.session.addMessage(message);
+                    yield { type: "assistant_message", message };
+                }
+                const calls = message.content.filter((block) => block.type === "tool_call");
+                if (calls.length === 0) {
+                    stopReason = assembled.stopReason === "tool_use" ? "end_turn" : assembled.stopReason;
+                    break;
+                }
+                const results = [];
+                for await (const event of this.executeCalls(calls, signal, results)) {
+                    yield event;
+                }
+                // All tool results for a turn must go back in one user message —
+                // splitting them teaches the model to stop calling tools in parallel.
+                await this.session.addMessage({
+                    role: "user",
+                    content: results,
+                    meta: { timestamp: Date.now(), synthetic: true },
+                });
+                if (this.stopRequested) {
+                    yield { type: "notice", message: this.stopRequested };
+                    this.stopRequested = undefined;
+                    stopReason = "end_turn";
+                    break;
+                }
+                if (signal.aborted) {
+                    stopReason = "aborted";
+                    break;
+                }
+            }
+            if (turn >= maxTurns && stopReason === "end_turn") {
+                yield {
+                    type: "notice",
+                    message: `Stopped after ${maxTurns} turns without finishing. Send another message to continue.`,
+                };
+            }
+            await this.hooks.run({
+                event: "Stop",
+                sessionId: this.session.id,
+                agentId: this.agentId,
+                cwd: this.session.cwd,
+                messages: this.session.messages,
+            });
+        }
+        finally {
+            this.running = false;
+            await this.session.persist().catch(() => { });
+        }
+        yield {
+            type: "done",
+            stopReason,
+            usage: this.session.usage,
+            costUsd: this.session.costUsd,
+            turns: turn,
+        };
+    }
+    // --- Steps --------------------------------------------------------------
+    async *ingestInput(input) {
+        if (Array.isArray(input)) {
+            for (const message of input)
+                await this.session.addMessage(message);
+            return;
+        }
+        const outcome = await this.hooks.run({
+            event: "UserPromptSubmit",
+            sessionId: this.session.id,
+            agentId: this.agentId,
+            cwd: this.session.cwd,
+            prompt: input,
+        });
+        if (outcome.decision === "deny") {
+            yield { type: "error", error: outcome.message ?? "prompt rejected by hook", fatal: true };
+            return;
+        }
+        const text = outcome.additionalContext
+            ? `${input}\n\n<hook-context>\n${outcome.additionalContext}\n</hook-context>`
+            : input;
+        await this.session.addMessage(userMessage(text));
+    }
+    async *maybeCompact() {
+        if (this.opts.compaction === false)
+            return;
+        const systemTokens = estimateStringTokens(this.systemPrompt());
+        if (!shouldCompact(this.session.messages, this.session.model, systemTokens, this.opts.compaction)) {
+            return;
+        }
+        await this.hooks.run({
+            event: "PreCompact",
+            sessionId: this.session.id,
+            agentId: this.agentId,
+            cwd: this.session.cwd,
+            messages: this.session.messages,
+        });
+        try {
+            // Summarizing is a cheap, well-specified task — run it on the small
+            // model when one is configured rather than on whatever expensive model
+            // the session happens to be using.
+            const summarizer = this.summarizerModel();
+            const provider = this.session.providers.getProvider(summarizer.provider);
+            const result = await compact(this.session.messages, provider, summarizer, this.opts.compaction ?? {});
+            if (result.droppedMessages === 0)
+                return;
+            // compactTo archives what it drops, so nothing becomes unrecoverable.
+            await this.session.compactTo(result.messages, result.dropped);
+            yield {
+                type: "compacted",
+                tokensBefore: result.tokensBefore,
+                tokensAfter: result.tokensAfter,
+                droppedMessages: result.droppedMessages,
+            };
+        }
+        catch (err) {
+            // Failing to compact is not fatal — the request may still fit.
+            this.logger.warn("compaction failed", { error: errorMessage(err) });
+            yield { type: "notice", message: `Compaction failed: ${errorMessage(err)}` };
+        }
+    }
+    systemPrompt() {
+        return buildSystemPrompt({
+            systemPrompt: this.opts.systemPrompt,
+            appendSystemPrompt: this.opts.appendSystemPrompt,
+            cwd: this.session.cwd,
+            model: this.session.model,
+            permissionMode: this.session.permissions.getMode(),
+            projectInstructions: this.opts.projectInstructions,
+            mcpInstructions: this.opts.mcp?.serverInstructions(),
+            toolNames: this.tools.visible(this.opts.toolFilter).map((t) => t.name),
+            // Only the descriptions — loading every skill body up front would
+            // defeat the point of having them be loadable.
+            extraSections: [this.skills.promptSection(), this.memoryIndex].filter((section) => section !== undefined),
+        });
+    }
+    buildRequest(signal) {
+        const model = this.session.model;
+        return {
+            model,
+            system: this.systemPrompt(),
+            messages: this.session.messages,
+            tools: model.supportsTools ? this.tools.schemas(this.opts.toolFilter) : undefined,
+            toolChoice: { type: "auto" },
+            thinking: this.opts.thinking,
+            cache: this.opts.cache ?? true,
+            signal,
+        };
+    }
+    /** Consume the provider stream, emitting deltas and assembling the message. */
+    async *streamAssistant(request) {
+        const provider = this.session.providers.getProvider(request.model.provider);
+        let text = "";
+        let thinking = "";
+        let signature;
+        const toolCalls = [];
+        let usage = emptyUsage();
+        let stopReason = "end_turn";
+        for await (const event of provider.stream(request)) {
+            switch (event.type) {
+                case "text_delta":
+                    text += event.text;
+                    yield { type: "text_delta", text: event.text };
+                    break;
+                case "thinking_delta":
+                    thinking += event.text;
+                    yield { type: "thinking_delta", text: event.text };
+                    break;
+                case "thinking_signature":
+                    signature = event.signature;
+                    break;
+                case "tool_call_end":
+                    toolCalls.push({
+                        type: "tool_call",
+                        id: event.id,
+                        name: event.name,
+                        input: event.input,
+                    });
+                    break;
+                case "usage":
+                    usage = event.usage;
+                    break;
+                case "end":
+                    stopReason = event.stopReason;
+                    usage = event.usage;
+                    break;
+                default:
+                    break;
+            }
+        }
+        // Anthropic requires thinking blocks first; the others don't care, so a
+        // single canonical order works everywhere.
+        const content = [];
+        if (thinking) {
+            const block = { type: "thinking", thinking };
+            if (signature)
+                block.signature = signature;
+            content.push(block);
+        }
+        if (text)
+            content.push({ type: "text", text });
+        content.push(...toolCalls);
+        return { content, usage, stopReason };
+    }
+    async *executeCalls(calls, signal, results) {
+        // Parallelize only when every call in the turn is safe to run
+        // concurrently — one unsafe call forces the whole batch to serialize,
+        // because we cannot know how they interact.
+        const parallel = calls.length > 1 &&
+            calls.every((call) => this.tools.get(call.name)?.concurrencySafe === true);
+        if (!parallel) {
+            for (const call of calls) {
+                yield* this.executeOne(call, signal, results);
+            }
+            return;
+        }
+        // Merge the per-call event streams so the UI sees tools interleave as they
+        // actually run. Buffering until every call finished made parallel
+        // execution indistinguishable from serial.
+        const collected = new Map();
+        yield* mergeStreams(calls.map((call) => async function* () {
+            const local = [];
+            yield* this.executeOne(call, signal, local);
+            if (local[0])
+                collected.set(call.id, local[0]);
+        }.bind(this)));
+        // Results still go back in the model's original call order, independent of
+        // which finished first.
+        for (const call of calls) {
+            const result = collected.get(call.id);
+            if (result)
+                results.push(result);
+        }
+    }
+    async *executeOne(call, signal, results) {
+        const started = Date.now();
+        const tool = this.tools.get(call.name);
+        if (!tool) {
+            const available = this.tools.visible(this.opts.toolFilter).map((t) => t.name).join(", ");
+            results.push(errorResult(call, `No tool named "${call.name}". Available tools: ${available}`));
+            return;
+        }
+        // Validate before anything else so a malformed call costs nothing.
+        let input = call.input;
+        if (tool.validate) {
+            const parsed = tool.validate(input);
+            if (!parsed.ok) {
+                results.push(errorResult(call, `Invalid input for ${call.name}: ${parsed.error}`));
+                return;
+            }
+            input = parsed.value;
+        }
+        const title = tool.renderTitle?.(input) ?? `${call.name}(${previewJson(input, 60)})`;
+        yield { type: "tool_start", toolCallId: call.id, toolName: call.name, title, input };
+        const pre = await this.hooks.run({
+            event: "PreToolUse",
+            sessionId: this.session.id,
+            agentId: this.agentId,
+            cwd: this.session.cwd,
+            toolName: call.name,
+            toolInput: input,
+        });
+        if (pre.decision === "deny") {
+            const reason = pre.message ?? "blocked by a PreToolUse hook";
+            yield { type: "permission_result", toolCallId: call.id, allowed: false, reason };
+            results.push(errorResult(call, reason));
+            return;
+        }
+        if (pre.updatedInput !== undefined)
+            input = pre.updatedInput;
+        if (pre.stop) {
+            // A hook asking to stop is stronger than denying one tool: end the turn
+            // rather than handing the model an error it will try to work around.
+            const reason = pre.message ?? "stopped by a PreToolUse hook";
+            results.push(errorResult(call, reason));
+            this.stopRequested = reason;
+            return;
+        }
+        // The workspace policy runs before the approval prompt: a write the
+        // policy forbids should never be offered for approval at all.
+        if (this.opts.workspace && !tool.readOnly) {
+            const check = checkWrite(this.opts.workspace, call.name, input, this.session.cwd);
+            if (!check.allowed) {
+                const reason = check.reason ?? "blocked by the workspace policy";
+                yield { type: "permission_result", toolCallId: call.id, allowed: false, reason };
+                results.push(errorResult(call, reason));
+                return;
+            }
+        }
+        const allowed = yield* this.checkPermission(call, tool, input, title);
+        if (!allowed)
+            return void results.push(errorResult(call, permissionDenialText(title)));
+        const ctx = {
+            cwd: this.session.cwd,
+            sessionId: this.session.id,
+            agentId: this.agentId,
+            toolCallId: call.id,
+            signal,
+            logger: this.logger.child(call.name),
+            onProgress: () => { },
+            host: this,
+        };
+        // Progress has to reach the consumer while the tool is still running —
+        // buffering it until completion turns a long-running tool into a frozen
+        // dot on screen.
+        const progress = new AsyncQueue();
+        ctx.onProgress = (update) => progress.push({ type: "tool_progress", progress: update });
+        let result;
+        const execution = (async () => {
+            try {
+                result = await tool.execute(input, ctx);
+            }
+            catch (err) {
+                result = {
+                    content: [{ type: "text", text: `Tool threw: ${errorMessage(err)}` }],
+                    isError: true,
+                };
+            }
+            finally {
+                progress.close();
+            }
+        })();
+        yield* progress;
+        await execution;
+        // The finally block above always assigns, so this is defensive only.
+        result ??= { content: [{ type: "text", text: "Tool produced no result" }], isError: true };
+        const post = await this.hooks.run({
+            event: "PostToolUse",
+            sessionId: this.session.id,
+            agentId: this.agentId,
+            cwd: this.session.cwd,
+            toolName: call.name,
+            toolInput: input,
+            result,
+        });
+        if (post.updatedResult)
+            result = post.updatedResult;
+        // Cap the result last, after hooks have had their say. A tool result lands
+        // in the transcript after this turn's compaction check has already run, so
+        // an uncapped result is the one thing compaction cannot protect against.
+        const capped = capToolResult(result, {
+            toolName: call.name,
+            toolCallId: call.id,
+            limit: this.opts.toolResultLimit,
+        });
+        if (capped.archived) {
+            await this.session.archiveOverflow(capped.archived);
+            this.logger.debug("archived oversized tool output", {
+                tool: call.name,
+                chars: capped.originalChars,
+            });
+            yield {
+                type: "notice",
+                message: `${call.name} returned ${capped.originalChars.toLocaleString()} characters; truncated and archived (recall to search it).`,
+            };
+        }
+        result = capped.result;
+        // A write into a skills directory is the agent authoring a skill for
+        // itself. Re-registering here is what closes the loop — otherwise the
+        // skill sits on disk unusable until the process restarts.
+        if (!result.isError && this.opts.onSkillsChanged && touchesSkills(call.name, input)) {
+            await this.opts.onSkillsChanged();
+            if (this.skills.size > 0 && !this.tools.has("skill")) {
+                this.tools.register(createSkillTool(this.skills));
+            }
+        }
+        const durationMs = Date.now() - started;
+        yield { type: "tool_end", toolCallId: call.id, toolName: call.name, result, durationMs };
+        // Read off the final result rather than captured at execute time, so a
+        // PostToolUse hook that rewrites or suppresses the result suppresses the
+        // artifact with it. The descriptor survives `capToolResult`, which spreads
+        // the metadata it was given.
+        const produced = result.metadata?.[ARTIFACT_METADATA_KEY];
+        if (!result.isError && isArtifactDescriptor(produced)) {
+            yield { type: "artifact", artifact: produced };
+        }
+        results.push({
+            type: "tool_result",
+            toolCallId: call.id,
+            toolName: call.name,
+            content: result.content,
+            isError: result.isError,
+        });
+    }
+    async *checkPermission(call, tool, input, title) {
+        const decision = this.session.permissions.evaluate(tool, input);
+        if (decision.behavior === "allow")
+            return true;
+        if (decision.behavior === "deny") {
+            yield {
+                type: "permission_result",
+                toolCallId: call.id,
+                allowed: false,
+                reason: decision.message,
+            };
+            return false;
+        }
+        const request = {
+            toolName: call.name,
+            input,
+            title,
+            reason: decision.rule ? `matched rule ${decision.rule}` : undefined,
+        };
+        yield { type: "permission_request", request };
+        // With no way to ask, an `ask` decision has to fail closed. Recorded as
+        // its own outcome rather than as a refusal: nobody refused this, nobody
+        // ever saw it, and a trail that cannot tell those apart is misleading in
+        // exactly the case somebody is reading it to understand.
+        if (!this.opts.permissionPrompt) {
+            this.session.permissions.recordAnswer(decision.auditId, "unavailable");
+            yield {
+                type: "permission_result",
+                toolCallId: call.id,
+                allowed: false,
+                reason: "no approval handler is configured",
+            };
+            return false;
+        }
+        const answer = await this.opts.permissionPrompt(request);
+        const allowed = typeof answer === "boolean" ? answer : answer.allow;
+        let remembered;
+        if (allowed && typeof answer === "object" && answer.remember) {
+            // `true` keeps the old session-only behaviour; a scope name persists.
+            const scope = answer.remember === true ? "session" : answer.remember;
+            remembered = await this.session.permissions.rememberAllow(tool, input, scope);
+        }
+        this.session.permissions.recordAnswer(decision.auditId, allowed ? "allowed" : "denied", remembered);
+        yield {
+            type: "permission_result",
+            toolCallId: call.id,
+            allowed,
+            ...(remembered ? { remembered } : {}),
+        };
+        return allowed;
+    }
+}
+/**
+ * Metadata is `Record<string, unknown>` and reaches here through a hook that
+ * any user can write, so the descriptor is checked rather than asserted. A
+ * malformed one is dropped: a frontend that renders an artifact row from a
+ * half-built object is worse than one that never hears about it.
+ */
+function isArtifactDescriptor(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const d = value;
+    return (typeof d["id"] === "string" &&
+        typeof d["title"] === "string" &&
+        typeof d["mime"] === "string" &&
+        typeof d["kind"] === "string" &&
+        typeof d["version"] === "number" &&
+        typeof d["bytes"] === "number");
+}
+function errorResult(call, text) {
+    return {
+        type: "tool_result",
+        toolCallId: call.id,
+        toolName: call.name,
+        content: [{ type: "text", text }],
+        isError: true,
+    };
+}
+function permissionDenialText(title) {
+    return `The user did not approve ${title}. Do not retry it. Explain what you wanted to do and ask how to proceed, or continue with another approach.`;
+}
+/** Whether a tool call wrote something that looks like a skill definition. */
+function touchesSkills(toolName, input) {
+    if (toolName !== "write" && toolName !== "edit")
+        return false;
+    const target = input?.path;
+    if (typeof target !== "string")
+        return false;
+    // Only SKILL.md matters: the supporting scripts a skill ships do not change
+    // what is advertised, so re-scanning for those would be noise.
+    return target.includes("skills") && target.endsWith("SKILL.md");
+}
+//# sourceMappingURL=agent.js.map