@matterailab/orbcode 0.1.10 → 0.1.14

package/dist/config/settings.js

@@ -1,7 +1,9 @@
+import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { DEFAULT_MODEL_ID, isValidAxonModel, registerCustomModels } from "../api/models.js";
+import { isHookEvent } from "../core/hooks.js";
 const DEFAULTS = {
     model: DEFAULT_MODEL_ID,
     autoApproveEdits: false,
@@ -27,6 +29,19 @@ function getConfigPath() {
 export function getSettingsPaths(cwd = process.cwd()) {
     return [path.join(getConfigDir(), "settings.json"), path.join(cwd, ".orbcode", "settings.json")];
 }
+/** Concatenate a settings file's `hooks` block into the accumulator, keeping
+ *  only known events and well-formed matcher arrays. */
+function mergeHooksInto(target, raw) {
+    if (!raw || typeof raw !== "object")
+        return;
+    for (const [event, matchers] of Object.entries(raw)) {
+        if (!isHookEvent(event))
+            continue;
+        if (!Array.isArray(matchers))
+            continue;
+        (target[event] ??= []).push(...matchers);
+    }
+}
 function readJson(filePath) {
     try {
         return JSON.parse(fs.readFileSync(filePath, "utf8"));
@@ -35,6 +50,74 @@ function readJson(filePath) {
         return undefined;
     }
 }
+// --- Project-hook trust ---------------------------------------------------
+// User-level hooks (~/.orbcode/settings.json) are written by the user and are
+// always trusted. Project-level hooks (<cwd>/.orbcode/settings.json) ship
+// inside a repo and could come from anyone, so they run arbitrary shell
+// commands only after the user explicitly trusts them. Trust is keyed by
+// project path + a hash of the hooks, so changing the hooks re-prompts.
+function getProjectSettingsPath(cwd) {
+    return path.join(cwd, ".orbcode", "settings.json");
+}
+function getTrustStorePath() {
+    return path.join(getConfigDir(), "hook-trust.json");
+}
+/** Normalized project hooks (known events only), or undefined if none. */
+function readProjectHooks(cwd) {
+    const merged = {};
+    mergeHooksInto(merged, readJson(getProjectSettingsPath(cwd))?.hooks);
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+function hashHooks(hooks) {
+    return crypto.createHash("sha256").update(JSON.stringify(hooks)).digest("hex").slice(0, 16);
+}
+function isProjectHooksTrusted(cwd, hash) {
+    // Escape hatch for CI / non-interactive automation. Only honored when
+    // stdin is not a TTY (so a stray export in a shell rc file can't silently
+    // disable the trust gate for interactive sessions). A non-TTY check keeps
+    // the gate meaningful in the TUI while still letting CI opt in.
+    if (process.env.ORBCODE_TRUST_PROJECT_HOOKS === "1" && !process.stdin.isTTY)
+        return true;
+    const store = readJson(getTrustStorePath());
+    return Boolean(store && store[cwd] === hash);
+}
+/** Persist trust for the current project's hooks (call after the user agrees). */
+export function trustProjectHooks(cwd = process.cwd()) {
+    const hooks = readProjectHooks(cwd);
+    if (!hooks)
+        return;
+    const store = readJson(getTrustStorePath()) ?? {};
+    store[cwd] = hashHooks(hooks);
+    try {
+        fs.mkdirSync(getConfigDir(), { recursive: true });
+        fs.writeFileSync(getTrustStorePath(), JSON.stringify(store, null, "\t") + "\n", { mode: 0o600 });
+    }
+    catch {
+        // best-effort; if it can't be persisted the user will simply be re-prompted
+    }
+}
+/**
+ * If this project defines hooks that are not yet trusted, return the list of
+ * shell commands awaiting approval; otherwise null (no project hooks, or already
+ * trusted). The TUI uses this to gate project hooks behind a trust prompt.
+ */
+export function getPendingProjectHooks(cwd = process.cwd()) {
+    const hooks = readProjectHooks(cwd);
+    if (!hooks)
+        return null;
+    if (isProjectHooksTrusted(cwd, hashHooks(hooks)))
+        return null;
+    const commands = [];
+    for (const matchers of Object.values(hooks)) {
+        for (const matcher of matchers ?? []) {
+            for (const hook of matcher.hooks ?? []) {
+                if (hook?.command)
+                    commands.push(hook.command);
+            }
+        }
+    }
+    return { commands };
+}
 /** Make sure ~/.orbcode/settings.json exists (empty JSON) so users can find it. */
 function ensureUserSettingsFile() {
     try {
@@ -52,8 +135,9 @@ export function loadSettings() {
     ensureUserSettingsFile();
     const settings = { ...DEFAULTS, ...readJson(getConfigPath()) };
     // Layer settings.json files on top (user config dir, then project).
+    const cwd = process.cwd();
     const customModels = [];
-    for (const settingsPath of getSettingsPaths()) {
+    for (const settingsPath of getSettingsPaths(cwd)) {
         const fileSettings = readJson(settingsPath);
         if (!fileSettings)
             continue;
@@ -71,6 +155,22 @@ export function loadSettings() {
         settings.customModels = customModels;
         registerCustomModels(customModels);
     }
+    // Hooks: user-level hooks always apply; project-level hooks run alongside
+    // them but only once trusted (they execute arbitrary shell commands). The
+    // two sets concatenate, so a trusted project adds to — never clobbers — your
+    // global hooks.
+    const mergedHooks = {};
+    mergeHooksInto(mergedHooks, readJson(path.join(getConfigDir(), "settings.json"))?.hooks);
+    const projectHooks = readProjectHooks(cwd);
+    if (projectHooks && isProjectHooksTrusted(cwd, hashHooks(projectHooks))) {
+        for (const [event, matchers] of Object.entries(projectHooks)) {
+            ;
+            (mergedHooks[event] ??= []).push(...matchers);
+        }
+    }
+    if (Object.keys(mergedHooks).length > 0) {
+        settings.hooks = mergedHooks;
+    }
     // env block from settings.json applies to this process.
     if (settings.env && typeof settings.env === "object") {
         for (const [key, value] of Object.entries(settings.env)) {

package/dist/core/agent.js

@@ -1,12 +1,14 @@
 import { execSync } from "node:child_process";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
-import { AxonClient } from "../api/client.js";
+import { REASONING_DETAILS_FIELD } from "../api/llmClient.js";
+import { createLLMClient } from "../api/provider.js";
 import { buildSystemPrompt } from "../prompts/system.js";
 import { describeToolCall, executeTool, getActiveTools, getApprovalKind, } from "../tools/index.js";
 import { walkFiles } from "../tools/executors/listFiles.js";
 import { previewFileChange } from "../tools/executors/files.js";
-import { saveSession } from "./sessions.js";
+import { getSessionFilePath, saveSession } from "./sessions.js";
+import { HookRunner } from "./hooks.js";
 const MAX_STEPS_PER_TURN = 50;
 const RESULT_PREVIEW_LINES = 6;
 function detectRepo(cwd) {
@@ -50,6 +52,11 @@ function getGitSummary(cwd) {
 function stripUserQueryTags(text) {
     return text.replace(/<user_query>\n?/g, "").replace(/\n?<\/user_query>/g, "");
 }
+/** Wrap hook-injected context in clearly delimited tags so the model can
+ *  distinguish it from user/system content (prompt-injection defense). */
+function wrapHookContext(source, text) {
+    return `<hook_context source="${source}">\n${text}\n</hook_context>`;
+}
 export class Agent {
     options;
     client;
@@ -69,10 +76,27 @@ export class Agent {
     contextTokens = 0;
     title = "";
     createdAt = new Date().toISOString();
+    hooks;
+    /** SessionStart fires once, lazily, before the first turn of this instance. */
+    sessionStarted = false;
+    /** carries SessionStart additionalContext into the first user message */
+    pendingStartContext = "";
+    /** guards Stop-hook forced continuation against infinite loops */
+    stopHookActive = false;
+    /** in-flight fire-and-forget hook promises (Notification), awaited on exit */
+    pendingBackground = new Set();
     taskId;
     constructor(options) {
         this.options = options;
         this.taskId = options.resume?.id ?? randomUUID();
+        this.hooks = new HookRunner({
+            cwd: options.cwd,
+            sessionId: this.taskId,
+            transcriptPath: getSessionFilePath(this.taskId),
+            config: options.hooks,
+            onSystemMessage: (message, isError) => options.callbacks.onEvent({ type: "system", message, isError }),
+            getSignal: () => this.abortController?.signal,
+        });
         if (options.resume) {
             this.messages = options.resume.messages;
             this.todos = options.resume.todos;
@@ -84,7 +108,7 @@ export class Agent {
         }
         this.sessionApproveEdits = options.autoApproveEdits;
         this.systemPrompt = buildSystemPrompt(options.cwd);
-        this.client = new AxonClient({
+        this.client = createLLMClient({
             token: options.token,
             modelId: options.modelId,
             taskId: this.taskId,
@@ -95,7 +119,7 @@ export class Agent {
     }
     setModel(modelId) {
         this.options.modelId = modelId;
-        this.client = new AxonClient({
+        this.client = createLLMClient({
             token: this.options.token,
             modelId,
             taskId: this.taskId,
@@ -121,6 +145,11 @@ export class Agent {
         this.title = title;
         this.persist();
     }
+    /** Swap the hook config mid-session (e.g. after the user trusts project hooks). */
+    setHooks(hooks) {
+        this.options.hooks = hooks;
+        this.hooks.setConfig(hooks);
+    }
     /** Update auto-approval behavior mid-session (shift+tab cycling in the TUI). */
     setApprovalMode(autoApproveEdits, autoApproveSafeCommands) {
         this.sessionApproveEdits = autoApproveEdits;
@@ -136,6 +165,9 @@ export class Agent {
         this.totalCost = 0;
         this.contextTokens = 0;
         this.title = "";
+        this.pendingStartContext = "";
+        this.sessionStarted = false;
+        this.stopHookActive = false;
     }
     /** Write the current conversation to the sessions directory. */
     persist() {
@@ -206,6 +238,21 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
     async runTurn(userText) {
         const { onEvent } = this.options.callbacks;
         this.abortController = new AbortController();
+        await this.maybeFireSessionStart();
+        // UserPromptSubmit may block the prompt outright or attach extra context.
+        let promptContext = "";
+        if (this.hooks.hasHooks("UserPromptSubmit")) {
+            const result = await this.hooks.run("UserPromptSubmit", { prompt: userText });
+            if (result.blocked || result.stopAll) {
+                const reason = result.blockReason || result.stopReason || "Prompt blocked by a hook.";
+                onEvent({ type: "system", message: reason, isError: true });
+                this.abortController = undefined;
+                onEvent({ type: "turn-end" });
+                return;
+            }
+            if (result.additionalContext)
+                promptContext = result.additionalContext;
+        }
         if (!this.title) {
             this.title = userText.replace(/\s+/g, " ").trim().slice(0, 80);
         }
@@ -214,12 +261,27 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             userContent = `${this.buildEnvironmentDetails()}\n\n${userContent}`;
             this.firstMessageSent = true;
         }
+        // SessionStart context sits above the prompt; UserPromptSubmit context
+        // is appended after it. Both reach the model but neither is shown as
+        // user-typed text (they live outside the <user_query> markers).
+        if (this.pendingStartContext) {
+            userContent = `${wrapHookContext("SessionStart", this.pendingStartContext)}\n\n${userContent}`;
+            this.pendingStartContext = "";
+        }
+        if (promptContext) {
+            userContent = `${userContent}\n\n${wrapHookContext("UserPromptSubmit", promptContext)}`;
+        }
         this.messages.push({ role: "user", content: userContent });
         try {
+            this.stopHookActive = false;
             for (let step = 0; step < MAX_STEPS_PER_TURN; step++) {
                 const done = await this.runStep();
-                if (done)
-                    break;
+                if (!done)
+                    continue;
+                // The model is ready to stop; Stop hooks may force it to continue.
+                if (await this.shouldContinueAfterStop())
+                    continue;
+                break;
             }
         }
         catch (error) {
@@ -241,6 +303,65 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             onEvent({ type: "turn-end" });
         }
     }
+    /** Fire SessionStart once per instance, stashing any injected context for
+     *  the first user message. */
+    async maybeFireSessionStart() {
+        if (this.sessionStarted)
+            return;
+        this.sessionStarted = true;
+        if (!this.hooks.hasHooks("SessionStart"))
+            return;
+        const result = await this.hooks.run("SessionStart", {
+            source: this.options.resume ? "resume" : "startup",
+        });
+        if (result.additionalContext)
+            this.pendingStartContext = result.additionalContext;
+    }
+    /** Ask Stop hooks whether the turn should keep going. Forces at most one
+     *  continuation per turn (stop_hook_active) so a hook can't loop forever. */
+    async shouldContinueAfterStop() {
+        if (!this.hooks.hasHooks("Stop"))
+            return false;
+        const result = await this.hooks.run("Stop", { stop_hook_active: this.stopHookActive });
+        if (result.stopAll)
+            return false;
+        if (result.blocked && !this.stopHookActive) {
+            this.stopHookActive = true;
+            const reason = result.blockReason || "A Stop hook asked you to keep going.";
+            this.messages.push({ role: "user", content: `System reminder (Stop hook): ${reason}` });
+            return true;
+        }
+        return false;
+    }
+    /** Track a fire-and-forget hook promise so it can be awaited on exit. */
+    trackBackground(p) {
+        this.pendingBackground.add(p);
+        p.finally(() => this.pendingBackground.delete(p));
+    }
+    /** Wait (up to `timeoutMs`) for in-flight background hooks to settle. */
+    async awaitBackground(timeoutMs) {
+        if (this.pendingBackground.size === 0)
+            return;
+        const all = Promise.allSettled([...this.pendingBackground]);
+        const cap = new Promise((resolve) => {
+            const t = setTimeout(resolve, timeoutMs);
+            t.unref?.();
+        });
+        await Promise.race([all, cap]);
+    }
+    /** Fire SessionEnd hooks. Best-effort; never blocks shutdown. */
+    async endSession(reason) {
+        // Let in-flight Notification hooks settle before the final SessionEnd.
+        await this.awaitBackground(3000);
+        if (!this.hooks.hasHooks("SessionEnd"))
+            return;
+        try {
+            await this.hooks.run("SessionEnd", { reason });
+        }
+        catch {
+            // a SessionEnd hook must never prevent the app from exiting
+        }
+    }
     /** Summarize the conversation so far and replace history with the summary. */
     async compact() {
         const { onEvent } = this.options.callbacks;
@@ -249,6 +370,20 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             onEvent({ type: "turn-end" });
             return;
         }
+        // Covers the resume-then-immediately-/compact path, so SessionStart
+        // always fires before any SessionEnd.
+        await this.maybeFireSessionStart();
+        // If SessionStart produced context, fold it into the compaction request
+        // rather than letting it linger for the next turn.
+        let startContext = "";
+        if (this.pendingStartContext) {
+            startContext = wrapHookContext("SessionStart", this.pendingStartContext) + "\n\n";
+            this.pendingStartContext = "";
+        }
+        // PreCompact runs before summarizing (it cannot cancel compaction).
+        if (this.hooks.hasHooks("PreCompact")) {
+            await this.hooks.run("PreCompact", { trigger: "manual", custom_instructions: "" });
+        }
         this.abortController = new AbortController();
         const signal = this.abortController.signal;
         try {
@@ -256,7 +391,8 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
                 ...this.outgoingMessages(),
                 {
                     role: "user",
-                    content: "Summarize this conversation so it can replace the full history. Capture the user's goals, decisions made, files created or modified (with paths), important code details, and any remaining next steps. Be thorough but concise. Respond with only the summary.",
+                    content: startContext +
+                        "Summarize this conversation so it can replace the full history. Capture the user's goals, decisions made, files created or modified (with paths), important code details, and any remaining next steps. Be thorough but concise. Respond with only the summary.",
                 },
             ];
             let summary = "";
@@ -313,6 +449,7 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
         let assistantText = "";
         let hadReasoning = false;
         let reasoningStart = 0;
+        let reasoningDetails;
         const toolCallsByIndex = new Map();
         let nextSyntheticIndex = 10000;
         const stream = this.client.createMessage(this.systemPrompt, this.outgoingMessages(), getActiveTools(), signal);
@@ -331,6 +468,10 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
                     }
                     onEvent({ type: "reasoning-delta", text: chunk.text });
                     break;
+                case "reasoning_details":
+                    // Opaque thinking blocks (with signatures) for next-turn replay.
+                    reasoningDetails = chunk.details;
+                    break;
                 case "native_tool_calls":
                     for (const tc of chunk.toolCalls) {
                         const index = tc.index ?? nextSyntheticIndex++;
@@ -378,6 +519,12 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
                 function: { name: tc.name, arguments: tc.arguments || "{}" },
             }));
         }
+        // Stash reasoning blocks (opaque) so the next turn can replay them. The
+        // field is persisted with the session and stripped on the OpenAI path.
+        if (reasoningDetails !== undefined) {
+            ;
+            assistantMessage[REASONING_DETAILS_FIELD] = reasoningDetails;
+        }
         this.messages.push(assistantMessage);
         if (toolCalls.length === 0) {
             return true;
@@ -410,7 +557,6 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             });
             return message;
         }
-        const summary = describeToolCall(toolCall.name, args);
         if (toolCall.name === "attempt_completion") {
             onEvent({ type: "completion", result: String(args.result ?? "") });
             return "The user has been shown the completion result.";
@@ -420,9 +566,54 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             const suggestions = (Array.isArray(args.follow_up) ? args.follow_up : [])
                 .map((s) => ({ text: String(s?.text ?? "") }))
                 .filter((s) => s.text);
+            // Notification fires whenever OrbCode pauses to wait on the user.
+            if (this.hooks.hasHooks("Notification")) {
+                this.trackBackground(this.hooks.run("Notification", {
+                    message: question || "OrbCode is asking a follow-up question.",
+                }));
+            }
             const answer = await requestFollowup(question, suggestions);
             return `<answer>\n${answer}\n</answer>`;
         }
+        // PreToolUse runs before approval/execution. It can block the call,
+        // override the approval decision, rewrite the tool input, or add context.
+        let preContext = "";
+        let bypassApproval = false;
+        let forceApproval = false;
+        if (this.hooks.hasHooks("PreToolUse")) {
+            const pre = await this.hooks.run("PreToolUse", { tool_name: toolCall.name, tool_input: args });
+            if (pre.stopAll || pre.blocked || pre.permissionDecision === "deny") {
+                const reason = pre.blockReason || pre.stopReason || pre.permissionReason || "Blocked by a PreToolUse hook.";
+                const blockedSummary = describeToolCall(toolCall.name, args);
+                onEvent({ type: "tool-start", id: toolCall.id, name: toolCall.name, summary: blockedSummary });
+                onEvent({
+                    type: "tool-end",
+                    id: toolCall.id,
+                    name: toolCall.name,
+                    summary: blockedSummary,
+                    resultPreview: reason,
+                    isError: true,
+                });
+                if (pre.stopAll)
+                    this.abortController?.abort();
+                return reason;
+            }
+            if (pre.updatedInput) {
+                args = pre.updatedInput;
+                onEvent({
+                    type: "system",
+                    message: `PreToolUse hook rewrote the input for ${toolCall.name}.`,
+                    isError: false,
+                });
+            }
+            if (pre.permissionDecision === "allow")
+                bypassApproval = true;
+            if (pre.permissionDecision === "ask")
+                forceApproval = true;
+            if (pre.additionalContext)
+                preContext = pre.additionalContext;
+        }
+        const summary = describeToolCall(toolCall.name, args);
         onEvent({ type: "tool-start", id: toolCall.id, name: toolCall.name, summary });
         const approvalKind = getApprovalKind(toolCall.name, args);
         const diff = approvalKind === "edit" ? previewFileChange(toolCall.name, args, this.options.cwd) : undefined;
@@ -433,7 +624,18 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
         if (approvalKind === "command") {
             needsApproval = isDangerous || !(this.sessionApproveCommands || this.options.autoApproveSafeCommands);
         }
+        // A PreToolUse hook can force the approval prompt ("ask") or skip it ("allow").
+        if (forceApproval)
+            needsApproval = true;
+        else if (bypassApproval)
+            needsApproval = false;
         if (needsApproval) {
+            // Notification fires when OrbCode needs the user to grant permission.
+            if (this.hooks.hasHooks("Notification")) {
+                this.trackBackground(this.hooks.run("Notification", {
+                    message: `OrbCode needs your permission to use ${toolCall.name}`,
+                }));
+            }
             const decision = await requestApproval({
                 kind: approvalKind,
                 toolName: toolCall.name,
@@ -462,7 +664,30 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             }
         }
         const result = await executeTool(toolCall.name, args, this.toolContext());
-        const previewLines = result.text.split("\n");
+        // PostToolUse can feed extra context (or a block reason) back to the
+        // model. PreToolUse additionalContext is delivered here too.
+        let resultText = result.text;
+        const extras = [];
+        if (preContext)
+            extras.push(wrapHookContext("PreToolUse", preContext));
+        if (this.hooks.hasHooks("PostToolUse")) {
+            const post = await this.hooks.run("PostToolUse", {
+                tool_name: toolCall.name,
+                tool_input: args,
+                tool_response: result.text,
+            });
+            if (post.additionalContext)
+                extras.push(wrapHookContext("PostToolUse", post.additionalContext));
+            if (post.blocked && post.blockReason)
+                extras.push(`[PostToolUse hook]: ${post.blockReason}`);
+            if (post.stopAll) {
+                this.abortController?.abort();
+                onEvent({ type: "system", message: "A PostToolUse hook stopped the turn.", isError: false });
+            }
+        }
+        if (extras.length)
+            resultText += `\n\n${extras.join("\n\n")}`;
+        const previewLines = resultText.split("\n");
         const resultPreview = previewLines.slice(0, RESULT_PREVIEW_LINES).join("\n") +
             (previewLines.length > RESULT_PREVIEW_LINES ? `\n… (${previewLines.length} lines)` : "");
         onEvent({
@@ -474,6 +699,6 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             isError: Boolean(result.isError),
             diff: result.isError ? undefined : diff,
         });
-        return result.text;
+        return resultText;
     }
 }