@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/oauth/storage.js

@@ -0,0 +1,357 @@
+/**
+ * OAuth credential storage in <bubble home>/auth.json.
+ *
+ * The path is resolved at CONSTRUCTION time through getBubbleHome(), never at
+ * module load: a module-level constant froze the real ~/.bubble at import,
+ * which no test could isolate (known-defects #7) and which ignored
+ * BUBBLE_HOME / dev mode while every other config file honored them
+ * (config.json, sessions, memory all derive from getBubbleHome).
+ *
+ * The file is shared by every Bubble process on the machine (several TUIs, the
+ * desktop app, the Feishu host), and OAuth refresh tokens are single-use, so a
+ * stale copy is not harmless — presenting an already-rotated refresh token is
+ * rejected (`refresh_token_reused`) and forces a new login. Hence:
+ *   - writes are read-merge-write of ONE key plus an atomic rename, never a
+ *     dump of this process's whole in-memory map over the file;
+ *   - reads follow the file (mtime/size check) so a token rotated by another
+ *     process is picked up instead of the stale in-memory one;
+ *   - withRefreshLock() serializes refreshes across processes.
+ *
+ * Node has no flock, so both locks are O_EXCL lock files carrying an owner
+ * token: a holder only ever deletes a lock whose content is its own token,
+ * and stale locks are broken one breaker at a time (see breakLockIfStale), so
+ * a breaker cannot remove a successor's live lock. What remains is a holder
+ * suspended past the stale threshold that resumes and releases in the same
+ * microseconds a breaker acts. The refresh path tolerates even that: results
+ * are stored by compare-and-set, and a rejected token triggers a second look
+ * at the file (ProviderRegistry).
+ */
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { getBubbleHome } from "../bubble-home.js";
+/**
+ * The refresh holder heartbeats its lock, so "stale" means the holder is gone,
+ * not merely slow. Waiters outlast the stale threshold: a crashed holder is
+ * always recovered from, and only a live, stuck one makes a waiter give up.
+ */
+const REFRESH_LOCK_STALE_MS = 30_000;
+const REFRESH_LOCK_HEARTBEAT_MS = 5_000;
+const REFRESH_LOCK_WAIT_MS = 90_000;
+const REFRESH_LOCK_POLL_MS = 50;
+/** The write lock spans a few ms of synchronous file I/O. */
+const WRITE_LOCK_STALE_MS = 5_000;
+const WRITE_LOCK_WAIT_MS = 15_000;
+const WRITE_LOCK_POLL_MS = 5;
+const BREAKER_STALE_MS = 10_000;
+const sleepCell = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+    Atomics.wait(sleepCell, 0, 0, ms);
+}
+/**
+ * One acquisition attempt. Returns the owner token, or undefined on contention
+ * (after breaking the lock if it was stale, so the caller's retry can win).
+ * Anything but EEXIST is a real error — an unwritable home must surface, not
+ * be mistaken for contention and retried forever.
+ */
+function tryAcquireLock(lockPath, staleMs) {
+    const token = `${process.pid}:${randomUUID()}`;
+    let fd;
+    try {
+        const dir = dirname(lockPath);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        fd = openSync(lockPath, "wx", 0o600);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        breakLockIfStale(lockPath, staleMs);
+        return undefined;
+    }
+    try {
+        writeSync(fd, token);
+    }
+    finally {
+        closeSync(fd);
+    }
+    return token;
+}
+function observeLock(lockPath) {
+    try {
+        return { mtimeMs: statSync(lockPath).mtimeMs, token: readFileSync(lockPath, "utf-8") };
+    }
+    catch {
+        return undefined; // released meanwhile
+    }
+}
+function isStale(lockPath, staleMs) {
+    const observed = observeLock(lockPath);
+    return !!observed && Date.now() - observed.mtimeMs > staleMs;
+}
+/**
+ * Breakers are serialized by their own O_EXCL lock, held for the few
+ * microseconds of the re-check and unlink below. Without it, two waiters that
+ * both judged the lock stale could interleave: one unlinks it, a successor
+ * acquires the path, and the other then unlinks the successor's live lock.
+ * Under the breaker lock the second one re-checks and finds a fresh lock.
+ */
+function breakLockIfStale(lockPath, staleMs) {
+    if (!isStale(lockPath, staleMs))
+        return;
+    const breakerPath = `${lockPath}.breaker`;
+    let fd;
+    try {
+        fd = openSync(breakerPath, "wx", 0o600);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        // Someone else is breaking it right now; only a crash inside that tiny
+        // section leaves the file behind, so clear an old one for the next retry.
+        if (isStale(breakerPath, BREAKER_STALE_MS)) {
+            try {
+                unlinkSync(breakerPath);
+            }
+            catch {
+                // Already gone.
+            }
+        }
+        return;
+    }
+    try {
+        closeSync(fd);
+        if (isStale(lockPath, staleMs))
+            unlinkSync(lockPath);
+    }
+    catch {
+        // Already gone.
+    }
+    finally {
+        try {
+            unlinkSync(breakerPath);
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
+/** Never delete a lock that is not ours (ours may have been broken as stale). */
+function releaseLock(lockPath, token) {
+    try {
+        if (readFileSync(lockPath, "utf-8") === token)
+            unlinkSync(lockPath);
+    }
+    catch {
+        // Already gone.
+    }
+}
+export class AuthStorage {
+    data = {};
+    /** Identity of the file as last read/written, to detect foreign writes. */
+    diskStamp;
+    mutationListeners = [];
+    authPath;
+    constructor(authPath = join(getBubbleHome(), "auth.json")) {
+        this.authPath = authPath;
+        this.load();
+    }
+    /**
+     * Observe credential writes/removals. Callers across the codebase mutate
+     * this storage directly (login/logout flows), so consumers that must react
+     * to credential-identity changes (ProviderRegistry's routing revision)
+     * subscribe here instead of wrapping every call site.
+     */
+    onMutation(listener) {
+        this.mutationListeners.push(listener);
+        return () => {
+            this.mutationListeners = this.mutationListeners.filter((item) => item !== listener);
+        };
+    }
+    notifyMutation(providerId) {
+        for (const listener of this.mutationListeners) {
+            try {
+                listener(providerId);
+            }
+            catch {
+                // Listeners must never break credential writes.
+            }
+        }
+    }
+    stampOf() {
+        try {
+            const stat = statSync(this.authPath);
+            // ino + ctime: every write replaces the file by rename, so they change
+            // even when a same-size rotation lands within one coarse mtime tick.
+            return `${stat.ino}:${stat.mtimeMs}:${stat.ctimeMs}:${stat.size}`;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    readDisk() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.authPath, "utf-8"));
+            return parsed && typeof parsed === "object" ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    load() {
+        this.diskStamp = this.stampOf();
+        this.data = this.diskStamp === undefined ? {} : this.readDisk();
+    }
+    /**
+     * Adopt writes made by other processes; notifies for the keys that changed.
+     * `force` skips the stamp shortcut: a token rotation keeps the file size, so
+     * on a coarse-mtime filesystem the stamp alone can miss it. The refresh and
+     * write paths cannot afford that.
+     */
+    sync(force = false) {
+        const stamp = this.stampOf();
+        if (!force && stamp === this.diskStamp)
+            return;
+        const previous = this.data;
+        this.diskStamp = stamp;
+        this.data = stamp === undefined ? {} : this.readDisk();
+        for (const key of new Set([...Object.keys(previous), ...Object.keys(this.data)])) {
+            if (JSON.stringify(previous[key]) !== JSON.stringify(this.data[key]))
+                this.notifyMutation(key);
+        }
+    }
+    /**
+     * Read-merge-write of a single key: entries owned by other processes survive.
+     * The whole sequence runs under the cross-process write lock — without it a
+     * process could read, lose the CPU while another persists a rotated token,
+     * then rename its older snapshot over it.
+     */
+    commit(providerId, creds, 
+    /** Compare-and-set guard, checked under the lock against the re-read file. */
+    guard) {
+        const lockPath = `${this.authPath}.wlock`;
+        const deadline = Date.now() + WRITE_LOCK_WAIT_MS;
+        let token = tryAcquireLock(lockPath, WRITE_LOCK_STALE_MS);
+        while (token === undefined) {
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for the credential write lock (${lockPath}).`);
+            }
+            sleepSync(WRITE_LOCK_POLL_MS);
+            token = tryAcquireLock(lockPath, WRITE_LOCK_STALE_MS);
+        }
+        try {
+            this.sync(true);
+            if (guard && !guard(this.data[providerId]))
+                return false;
+            const next = { ...this.data };
+            if (creds)
+                next[providerId] = creds;
+            else
+                delete next[providerId];
+            const tmpPath = `${this.authPath}.${process.pid}.tmp`;
+            writeFileSync(tmpPath, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+            // Fencing: if this process was suspended past the stale threshold, the
+            // lock was broken and someone else may have committed since the re-read
+            // above. Publishing the snapshot now would roll their write back.
+            if (observeLock(lockPath)?.token !== token) {
+                unlinkSync(tmpPath);
+                throw new Error("Lost the credential write lock before publishing; the write was not applied.");
+            }
+            renameSync(tmpPath, this.authPath);
+            this.data = next;
+            this.diskStamp = this.stampOf();
+            return true;
+        }
+        finally {
+            releaseLock(lockPath, token);
+        }
+    }
+    /** Force a re-read of the file (see sync). */
+    reload() {
+        this.sync(true);
+    }
+    /**
+     * Serialize token refreshes across processes. Callers must re-read the
+     * credentials inside `fn`: whoever held the lock before may already have
+     * rotated them. `fn` never runs without the lock — presenting a single-use
+     * refresh token concurrently can void the login, while a timeout only costs
+     * one retryable request.
+     */
+    async withRefreshLock(fn) {
+        const lockPath = `${this.authPath}.lock`;
+        const deadline = Date.now() + REFRESH_LOCK_WAIT_MS;
+        let token = tryAcquireLock(lockPath, REFRESH_LOCK_STALE_MS);
+        while (token === undefined) {
+            if (Date.now() >= deadline) {
+                throw new Error("Timed out waiting for another Bubble process to finish refreshing credentials. Try again.");
+            }
+            await new Promise((resolve) => setTimeout(resolve, REFRESH_LOCK_POLL_MS));
+            token = tryAcquireLock(lockPath, REFRESH_LOCK_STALE_MS);
+        }
+        const owned = token;
+        const heartbeat = setInterval(() => {
+            try {
+                if (readFileSync(lockPath, "utf-8") === owned)
+                    utimesSync(lockPath, new Date(), new Date());
+            }
+            catch {
+                // Lock gone: nothing to keep alive.
+            }
+        }, REFRESH_LOCK_HEARTBEAT_MS);
+        heartbeat.unref?.();
+        try {
+            return await fn();
+        }
+        finally {
+            clearInterval(heartbeat);
+            releaseLock(lockPath, owned);
+        }
+    }
+    getPath() {
+        return this.authPath;
+    }
+    get(providerId) {
+        this.sync();
+        return this.data[providerId];
+    }
+    set(providerId, creds) {
+        this.commit(providerId, creds);
+        this.notifyMutation(providerId);
+    }
+    /**
+     * Store the result of a refresh only if the entry is still the one that was
+     * refreshed (`fromRefreshToken`; null = the key must still be absent). A
+     * /login or /logout in another process only takes the write lock, so it can
+     * land while a refresh request is in flight; its outcome must win over a
+     * result derived from the credentials it replaced.
+     */
+    replaceIfUnchanged(providerId, creds, fromRefreshToken) {
+        const written = this.commit(providerId, creds, (onDisk) => fromRefreshToken === null ? onDisk === undefined : onDisk?.refreshToken === fromRefreshToken);
+        if (written)
+            this.notifyMutation(providerId);
+        return written;
+    }
+    remove(providerId) {
+        this.commit(providerId, undefined);
+        this.notifyMutation(providerId);
+    }
+    has(providerId) {
+        this.sync();
+        return !!this.data[providerId];
+    }
+    isExpired(providerId, graceMs = 5 * 60 * 1000) {
+        this.sync();
+        const creds = this.data[providerId];
+        if (!creds)
+            return true;
+        return Date.now() >= creds.expiresAt - graceMs;
+    }
+    getAccessToken(providerId) {
+        this.sync();
+        return this.data[providerId]?.accessToken;
+    }
+    list() {
+        this.sync();
+        return Object.keys(this.data);
+    }
+}

package/dist/oauth/types.d.ts

@@ -0,0 +1,15 @@
+export interface OAuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    idToken?: string;
+    accountId?: string;
+}
+export interface OAuthCredentials {
+    type: "oauth";
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    idToken?: string;
+    accountId?: string;
+}

package/dist/oauth/types.js

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

package/dist/orchestrator/default-hooks.d.ts

@@ -0,0 +1,22 @@
+import type { TurnHooks } from "./hooks.js";
+/**
+ * Default hooks: infrastructure and information only.
+ *
+ * The cognitive-governance layer that used to live here (task classifier,
+ * step-budget governor, discovery barrier, evidence tracker, bash-search
+ * arbitration, delegation nudge, completion self-check) was removed — see
+ * docs/harness-thinning.md. The TurnHooks mechanism itself stays, pi-style:
+ * hosts may install their own policies, the core ships none.
+ *
+ * What remains, and why it passes the ruler in that document:
+ * - resident-history compaction calls (infrastructure)
+ * - background-task and subagent-lifecycle reminders (facts the model
+ *   cannot otherwise see)
+ * - orchestrationRequestReminder (deliberately retained policy: amplifies
+ *   the user's EXPLICIT orchestration request at the decision turn)
+ * - userNamedModelReminder (deterministic catalog resolution of a model the
+ *   user named — information the model would otherwise retype from priors)
+ * - modified-existing-tests disclosure (git ground truth: bash writes and
+ *   subagent worktree merges do not appear in the model's own tool memory)
+ */
+export declare function createDefaultHooks(): TurnHooks[];

package/dist/orchestrator/default-hooks.js

@@ -0,0 +1,127 @@
+import { buildModifiedTestsDisclosure } from "../prompt/reminders.js";
+import { orchestrationRequestReminder, userNamedModelReminder } from "../prompt/task-reminders.js";
+import { captureGitBaseline, detectRunChanges } from "../agent/change-tracker.js";
+import { buildSubagentLifecycleReminder } from "../agent/subagent-lifecycle-reminder.js";
+/**
+ * Default hooks: infrastructure and information only.
+ *
+ * The cognitive-governance layer that used to live here (task classifier,
+ * step-budget governor, discovery barrier, evidence tracker, bash-search
+ * arbitration, delegation nudge, completion self-check) was removed — see
+ * docs/harness-thinning.md. The TurnHooks mechanism itself stays, pi-style:
+ * hosts may install their own policies, the core ships none.
+ *
+ * What remains, and why it passes the ruler in that document:
+ * - resident-history compaction calls (infrastructure)
+ * - background-task and subagent-lifecycle reminders (facts the model
+ *   cannot otherwise see)
+ * - orchestrationRequestReminder (deliberately retained policy: amplifies
+ *   the user's EXPLICIT orchestration request at the decision turn)
+ * - userNamedModelReminder (deterministic catalog resolution of a model the
+ *   user named — information the model would otherwise retype from priors)
+ * - modified-existing-tests disclosure (git ground truth: bash writes and
+ *   subagent worktree merges do not appear in the model's own tool memory)
+ */
+export function createDefaultHooks() {
+    return [
+        {
+            async beforeTurn(ctx) {
+                // Git ground truth for the tests-touched disclosure: tool-metadata
+                // bookkeeping misses bash-written files and subagent worktree merges;
+                // a dirty-state baseline at run start makes the run's real footprint
+                // observable.
+                if (ctx.state.gitBaseline === undefined) {
+                    ctx.state.gitBaseline = await captureGitBaseline(ctx.cwd);
+                }
+                // User named the mechanism ("agent team" / workflow / 编排): remind at
+                // the decision turn, where it outweighs the parallel-spawns prior.
+                const orchestrationReminder = orchestrationRequestReminder(ctx.input, ctx.agent.hasToolAvailable("run_workflow"));
+                if (orchestrationReminder) {
+                    ctx.queueReminder(orchestrationReminder);
+                }
+                // User named a configured model ("gpt 5.6 sol"): resolve it against
+                // the routable catalog and hand over the exact id at the decision
+                // point — never let the parent retype ids from priors (v3.6).
+                const namedModelReminder = userNamedModelReminder(ctx.input, ctx.agent.listRoutableModels?.(), ctx.agent.hasToolAvailable("spawn_agent"));
+                if (namedModelReminder) {
+                    ctx.queueReminder(namedModelReminder);
+                }
+                // Background-task truth at turn start: completions that landed while
+                // the agent was idle (or during another session's turn) reach the
+                // model here; the same state-change gate prevents duplicates with the
+                // beforeContinuation emission (background-tasks design §2.3a).
+                const backgroundTaskReminder = ctx.agent.consumeBackgroundTaskReminder?.();
+                if (backgroundTaskReminder) {
+                    ctx.queueReminder(backgroundTaskReminder);
+                }
+                ctx.agent.compactResidentHistory();
+            },
+            beforeModelCall(ctx) {
+                ctx.agent.compactResidentHistory();
+            },
+            afterTurn(ctx) {
+                ctx.agent.compactResidentHistory();
+            },
+        },
+        {
+            beforeToolCall(ctx) {
+                ctx.state.toolUsed = true;
+            },
+            beforeContinuation(ctx) {
+                if (hasSubagentLifecycleActivity(ctx.toolCalls, ctx.toolResults)) {
+                    const reminder = buildSubagentLifecycleReminder(ctx.agent.listSubAgents(), ctx.toolResults);
+                    if (reminder) {
+                        ctx.queueReminder(reminder);
+                    }
+                }
+                // Background-task truth: state-change gated inside the agent (a task
+                // started/finished/killed since the last emission), so a mid-turn
+                // completion reaches the model without stacking per-call duplicates
+                // (background-tasks design §2.3a).
+                const taskReminder = ctx.agent.consumeBackgroundTaskReminder?.();
+                if (taskReminder) {
+                    ctx.queueReminder(taskReminder);
+                }
+            },
+            async afterTurn(ctx) {
+                // Modified-existing-tests disclosure: pure information, delivered at
+                // most once, only when this run touched test files that already
+                // existed at run start. Forcing one continuation turn is the only way
+                // a final-turn fact can reach the model at all. The old completion
+                // self-check ("re-read the request...") was removed with the
+                // governance layer; this survives it because the underlying fact
+                // comes from git, not from the model's own tool history.
+                if (ctx.state.testsTouchedDisclosed)
+                    return;
+                // Tools are frozen: the model could not act on the disclosure, so
+                // another turn is pure token burn.
+                if (ctx.state.forceTextOnlyReason)
+                    return;
+                // Subagents hand off to a parent whose own disclosure covers their
+                // merged changes via the git baseline.
+                if (ctx.agent.role === "subagent")
+                    return;
+                // Only attribute git changes to runs that actually used tools, so
+                // external repo churn cannot hijack a pure Q&A turn.
+                if (!ctx.state.toolUsed || !ctx.state.gitBaseline)
+                    return;
+                const changes = await detectRunChanges(ctx.cwd, ctx.state.gitBaseline);
+                if (!changes || changes.modifiedExistingTests.length === 0)
+                    return;
+                ctx.state.testsTouchedDisclosed = true;
+                ctx.state.forceContinuationReason = "tests_touched_disclosure";
+                ctx.queueReminder(buildModifiedTestsDisclosure(changes.modifiedExistingTests));
+            },
+        },
+    ];
+}
+function hasSubagentLifecycleActivity(toolCalls, toolResults) {
+    return toolCalls.some((toolCall) => isSubagentLifecycleTool(toolCall.name))
+        || toolResults.some((result) => result.metadata?.kind === "subagent");
+}
+function isSubagentLifecycleTool(name) {
+    return name === "spawn_agent"
+        || name === "wait_agent"
+        || name === "send_input"
+        || name === "close_agent";
+}

package/dist/orchestrator/hooks.d.ts

@@ -0,0 +1,69 @@
+import type { Agent } from "../agent.js";
+import type { ContentPart, ParsedToolCall, ToolRegistryEntry, ToolResult } from "../types.js";
+import type { GitChangeBaseline } from "../agent/change-tracker.js";
+export interface TurnHookState {
+    turnCount?: number;
+    forceTextOnlyReason?: string;
+    forceContinuationReason?: string;
+    /** Modified-existing-tests disclosure already delivered this run (at most once). */
+    testsTouchedDisclosed?: boolean;
+    /** Git dirty-state snapshot at run start (null = not a git repo / git failed). */
+    gitBaseline?: GitChangeBaseline | null;
+    /** Any tool executed this run — guards git-change attribution for pure Q&A turns. */
+    toolUsed?: boolean;
+    taskBudget?: {
+        total: number;
+        spent: number;
+    };
+}
+export interface TurnHookContext {
+    agent: Agent;
+    cwd: string;
+    input: string | ContentPart[];
+    state: TurnHookState;
+    queueReminder: (reminder: string) => void;
+    flushReminders: () => void;
+}
+export interface BeforeModelCallHookContext extends TurnHookContext {
+    toolEntries: ToolRegistryEntry[];
+    disableTools: (reason: string) => void;
+}
+export interface BeforeToolCallHookContext extends TurnHookContext {
+    toolCall: ParsedToolCall;
+    blockedResult?: ToolResult;
+    replaceToolCall: (toolCall: ParsedToolCall) => void;
+    blockToolCall: (result: ToolResult) => void;
+}
+export interface AfterToolCallHookContext extends TurnHookContext {
+    toolCall: ParsedToolCall;
+    result: ToolResult;
+    replaceResult: (result: ToolResult) => void;
+}
+export interface BeforeContinuationHookContext extends TurnHookContext {
+    toolCalls: ParsedToolCall[];
+    toolResults: ToolResult[];
+    requestTextOnlyTurn: (reason: string) => void;
+}
+export interface TurnHooks {
+    beforeTurn?: (ctx: TurnHookContext) => void | Promise<void>;
+    beforeModelCall?: (ctx: BeforeModelCallHookContext) => void | Promise<void>;
+    beforeToolCall?: (ctx: BeforeToolCallHookContext) => void | Promise<void>;
+    afterToolCall?: (ctx: AfterToolCallHookContext) => void | Promise<void>;
+    beforeContinuation?: (ctx: BeforeContinuationHookContext) => void | Promise<void>;
+    afterTurn?: (ctx: TurnHookContext) => void | Promise<void>;
+}
+export declare class HookBus {
+    private beforeTurnHooks;
+    private beforeModelCallHooks;
+    private beforeToolCallHooks;
+    private afterToolCallHooks;
+    private beforeContinuationHooks;
+    private afterTurnHooks;
+    register(hooks: TurnHooks): void;
+    runBeforeTurn(ctx: TurnHookContext): Promise<void>;
+    runBeforeModelCall(ctx: BeforeModelCallHookContext): Promise<void>;
+    runBeforeToolCall(ctx: BeforeToolCallHookContext): Promise<void>;
+    runAfterToolCall(ctx: AfterToolCallHookContext): Promise<void>;
+    runBeforeContinuation(ctx: BeforeContinuationHookContext): Promise<void>;
+    runAfterTurn(ctx: TurnHookContext): Promise<void>;
+}

package/dist/orchestrator/hooks.js

@@ -0,0 +1,52 @@
+export class HookBus {
+    beforeTurnHooks = [];
+    beforeModelCallHooks = [];
+    beforeToolCallHooks = [];
+    afterToolCallHooks = [];
+    beforeContinuationHooks = [];
+    afterTurnHooks = [];
+    register(hooks) {
+        if (hooks.beforeTurn)
+            this.beforeTurnHooks.push(hooks.beforeTurn);
+        if (hooks.beforeModelCall)
+            this.beforeModelCallHooks.push(hooks.beforeModelCall);
+        if (hooks.beforeToolCall)
+            this.beforeToolCallHooks.push(hooks.beforeToolCall);
+        if (hooks.afterToolCall)
+            this.afterToolCallHooks.push(hooks.afterToolCall);
+        if (hooks.beforeContinuation)
+            this.beforeContinuationHooks.push(hooks.beforeContinuation);
+        if (hooks.afterTurn)
+            this.afterTurnHooks.push(hooks.afterTurn);
+    }
+    async runBeforeTurn(ctx) {
+        for (const hook of this.beforeTurnHooks) {
+            await hook(ctx);
+        }
+    }
+    async runBeforeModelCall(ctx) {
+        for (const hook of this.beforeModelCallHooks) {
+            await hook(ctx);
+        }
+    }
+    async runBeforeToolCall(ctx) {
+        for (const hook of this.beforeToolCallHooks) {
+            await hook(ctx);
+        }
+    }
+    async runAfterToolCall(ctx) {
+        for (const hook of this.afterToolCallHooks) {
+            await hook(ctx);
+        }
+    }
+    async runBeforeContinuation(ctx) {
+        for (const hook of this.beforeContinuationHooks) {
+            await hook(ctx);
+        }
+    }
+    async runAfterTurn(ctx) {
+        for (const hook of this.afterTurnHooks) {
+            await hook(ctx);
+        }
+    }
+}

package/dist/permission/mode.d.ts

@@ -0,0 +1,19 @@
+import type { PermissionMode } from "../types.js";
+/**
+ * Display metadata for each permission mode. Mirrors Claude Code's
+ * PERMISSION_MODE_CONFIG — kept narrow to what the TUI needs today.
+ */
+export interface PermissionModeInfo {
+    title: string;
+    shortTitle: string;
+    /** Single/double-char prefix shown in the footer badge. Empty = no badge. */
+    symbol: string;
+    /** Theme colour key. */
+    color: "muted" | "accent" | "success" | "warning" | "error";
+}
+export declare const PERMISSION_MODE_INFO: Record<PermissionMode, PermissionModeInfo>;
+/**
+ * Cycle order for the interactive mode keybind. The visible TUI loop keeps the
+ * mental model simple: Build -> Plan -> Bypass -> Build.
+ */
+export declare function getNextPermissionMode(current: PermissionMode): PermissionMode;

package/dist/permission/mode.js

@@ -0,0 +1,16 @@
+export const PERMISSION_MODE_INFO = {
+    default: { title: "Default", shortTitle: "default", symbol: "", color: "muted" },
+    plan: { title: "Plan", shortTitle: "plan", symbol: "⏸", color: "accent" },
+    bypassPermissions: { title: "Bypass permissions", shortTitle: "bypass permission", symbol: "⏵⏵", color: "error" },
+};
+/**
+ * Cycle order for the interactive mode keybind. The visible TUI loop keeps the
+ * mental model simple: Build -> Plan -> Bypass -> Build.
+ */
+export function getNextPermissionMode(current) {
+    if (current === "default")
+        return "plan";
+    if (current === "plan")
+        return "bypassPermissions";
+    return "default";
+}