howtofixcli 0.7.13 → 0.7.15

package/dist/goal.js

@@ -1,222 +0,0 @@
-/**
- * A persistent goal for the session, with usage accounting and a continuation
- * loop.
- *
- * Why this exists: opencode's most-reacted session request (#27167) is a native
- * goal, and its own author states the reason it is not a command template — it
- * "needs persistence, runtime continuation, usage accounting, and client
- * sync/status surfaces". A slash command that prints a prompt can do none of
- * those. What a goal buys over a plain message is that the harness knows what
- * the run is *for*, so it can:
- *
- *   - keep the goal in the prompt every request (a long task survives a
- *     compaction that drops the original message),
- *   - continue working when the agent tries to stop with the goal still open,
- *   - account the cost against it and stop at a budget instead of running away,
- *   - refuse to let the model declare victory without evidence.
- *
- * State lives in the session branch (a `custom` entry), so it survives a resume
- * and stays correct across a fork — the same reason `todo.ts` keeps its list
- * there. A module-level mirror exists only so the HUD can paint the goal without
- * a session handle; it is reseeded from the branch on `session_start`.
- *
- * Pure where it matters: {@link applyGoalOp} and {@link shouldContinue} hold the
- * policy, so both are testable without a session or a model.
- */
-import { StringEnum } from "@netrodev/hxf-ai";
-import { defineTool } from "@netrodev/hxf-coding-agent";
-import { Type } from "typebox";
-/** Session entry type the goal is persisted under. */
-export const GOAL_ENTRY = "howtofix.goal";
-/** Custom message type used for the automatic continuation. */
-export const GOAL_CONTINUE = "howtofix.goal.continue";
-/** Longest goal text accepted. */
-export const MAX_GOAL = 400;
-/**
- * Continuations allowed when the goal sets no budget.
- *
- * A goal that can continue forever is the failure mode this whole feature is
- * meant to avoid, so the default is a cap rather than "unlimited": an unattended
- * run stops and says so, and the user can resume it.
- */
-export const DEFAULT_BUDGET = 25;
-const MARK = {
-    active: "●",
-    paused: "‖",
-    done: "✓",
-    cleared: "○",
-};
-/** One line for the tool result and the HUD. */
-export function formatGoal(goal) {
-    if (!goal || goal.status === "cleared")
-        return "No goal set.";
-    const cap = goal.budget ?? DEFAULT_BUDGET;
-    const parts = [`${MARK[goal.status]} ${goal.status}`, `${goal.used}/${cap} continuations`];
-    if (goal.note)
-        parts.push(goal.note);
-    return `${parts.join(" · ")}\n${goal.text}`;
-}
-/** The short form painted in the HUD. Empty when there is nothing worth showing. */
-export function goalSegment(goal) {
-    if (!goal || goal.status === "cleared" || goal.status === "done")
-        return "";
-    const cap = goal.budget ?? DEFAULT_BUDGET;
-    const text = goal.text.length > 48 ? `${goal.text.slice(0, 47)}…` : goal.text;
-    return `goal ${MARK[goal.status]} ${goal.used}/${cap} · ${text}`;
-}
-/**
- * The block injected into the prompt, so the goal survives compaction.
- *
- * Deliberately free of anything that changes between turns. This is appended to
- * the system message, which is the cacheable prefix of every request, so a
- * counter here would invalidate the prompt cache on every continuation — the
- * same class of mistake that cost Claude Code 10.2% of fleet-wide cache
- * creation tokens when a dynamic agent list sat in a tool schema. The spend is
- * reported where it belongs: in the continuation message and the tool result,
- * both of which are new content and cannot invalidate a cached prefix.
- */
-export function renderGoalBlock(goal) {
-    const lines = ["<goal>", goal.text, `Status: ${goal.status}.`];
-    if (goal.status === "active") {
-        lines.push("Work toward this goal until it is genuinely met. When it is, call the `goal` tool with", 'op="complete" and a note naming the evidence; a command you ran or a file you checked.', "If you are blocked and cannot proceed, say so plainly instead of repeating an attempt.");
-    }
-    lines.push("</goal>");
-    return lines.join("\n");
-}
-/** What the agent is told when the harness decides to keep going. */
-export function continuationPrompt(goal) {
-    return [
-        "[goal] The goal is still open and you stopped without closing it:",
-        `  ${goal.text}`,
-        "",
-        "Continue from where you left off. Do not repeat work you already did. If the goal is met,",
-        'call the `goal` tool with op="complete" and a note naming the evidence. Do not call it',
-        "complete to escape a hard problem: if you cannot make progress, state what is blocking you.",
-        `Continuations used: ${goal.used}/${goal.budget ?? DEFAULT_BUDGET}.`,
-    ].join("\n");
-}
-/** A stable in-memory mirror for surfaces with no session handle (the HUD). */
-let mirror;
-export function currentGoal() {
-    return mirror;
-}
-export function setMirror(goal) {
-    mirror = goal;
-}
-export function shouldContinue(goal) {
-    if (!goal)
-        return { action: "stop", reason: "no goal", close: false };
-    if (goal.status === "done")
-        return { action: "stop", reason: "goal complete", close: false };
-    if (goal.status === "cleared")
-        return { action: "stop", reason: "goal cleared", close: false };
-    if (goal.status === "paused")
-        return { action: "stop", reason: "goal paused", close: false };
-    const cap = goal.budget ?? DEFAULT_BUDGET;
-    if (goal.used >= cap)
-        return { action: "stop", reason: `budget exhausted (${cap} continuations)`, close: true };
-    return { action: "continue" };
-}
-/** Apply one op. Pure, so the policy is testable without a session. */
-export function applyGoalOp(goal, op, text, budget, note) {
-    switch (op) {
-        case "view":
-            return { goal };
-        case "set": {
-            if (!text?.trim())
-                return { goal, error: "set needs text" };
-            if (text.length > MAX_GOAL)
-                return { goal, error: `text longer than ${MAX_GOAL} characters` };
-            if (budget !== undefined && (!Number.isInteger(budget) || budget < 1)) {
-                return { goal, error: "budget must be a positive integer" };
-            }
-            // A new goal resets the accounting: the cap belongs to the goal, not to
-            // the session, so a fresh goal gets its full budget.
-            return { goal: { text: text.trim(), status: "active", used: 0, ...(budget === undefined ? {} : { budget }) } };
-        }
-        case "pause":
-        case "resume":
-        case "complete":
-        case "clear": {
-            if (!goal || goal.status === "cleared")
-                return { goal, error: "no goal to change" };
-            if (op === "resume") {
-                if (goal.status === "done")
-                    return { goal, error: "goal is complete; set a new one instead" };
-                return { goal: { ...goal, status: "active", note: undefined } };
-            }
-            if (op === "pause")
-                return { goal: { ...goal, status: "paused" } };
-            if (op === "clear")
-                return { goal: { ...goal, status: "cleared" } };
-            // `complete` requires evidence. The model may only declare victory with a
-            // note naming what it verified; a bare "done" is what lets a wrong answer
-            // ship as a finished task.
-            if (!note?.trim())
-                return { goal, error: "complete needs a note naming the evidence (a command you ran or a file you checked)" };
-            return { goal: { ...goal, status: "done", note: note.trim() } };
-        }
-        default:
-            return { goal, error: `unknown op ${JSON.stringify(op)}` };
-    }
-}
-/**
- * Rebuild the goal by replaying this branch in order.
- *
- * Two sources, because two things write it: the `goal` tool (whose result
- * `details` are persisted in the transcript, exactly like `todo.ts`) and the
- * continuation extension, which appends a `custom` entry to record a spend
- * before it continues. Whichever is later in the branch wins, so a resume sees
- * the true state and the accounting cannot be reset by a restart.
- */
-export function readGoal(ctx) {
-    let goal;
-    for (const entry of ctx.sessionManager.getBranch()) {
-        if (entry.type === "custom" && entry.customType === GOAL_ENTRY) {
-            goal = entry.data;
-            continue;
-        }
-        // The slash command persists through `sendCustomMessage`, which writes a
-        // `custom_message` carrying the goal in `details` rather than `data`.
-        if (entry.type === "custom_message" && entry.customType === GOAL_ENTRY) {
-            goal = entry.details ?? goal;
-            continue;
-        }
-        if (entry.type !== "message")
-            continue;
-        const message = entry.message;
-        if (message.role !== "toolResult" || message.toolName !== "goal")
-            continue;
-        const details = message.details;
-        if (details?.goal)
-            goal = details.goal;
-    }
-    return goal;
-}
-export const goalParams = Type.Object({
-    op: StringEnum(["set", "view", "pause", "resume", "complete", "clear"], {
-        description: "set starts a goal; complete closes it with evidence; pause/resume/clear manage it; view reads it",
-    }),
-    text: Type.Optional(Type.String({ description: "The goal, in one sentence, as the user would state it (for set)" })),
-    budget: Type.Optional(Type.Number({ description: "Optional cap on automatic continuations before the run stops" })),
-    note: Type.Optional(Type.String({ description: "Evidence that the goal is met (required for complete)" })),
-});
-export const goalTool = defineTool({
-    name: "goal",
-    label: "goal",
-    description: "Track the goal for this session. The goal is already shown in your context every request, so you rarely need `view`. Call `complete` only when the goal is genuinely met, and pass a note naming the evidence. When a goal is active the harness continues the run if you stop without closing it, so closing it is how you stop.",
-    promptSnippet: "goal: the session's objective, and how to close it",
-    parameters: goalParams,
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-        const before = readGoal(ctx);
-        const { goal, error } = applyGoalOp(before, params.op, params.text, params.budget, params.note);
-        setMirror(goal);
-        const body = formatGoal(goal);
-        const summary = error ? `Error: ${error}\n${body}` : body;
-        return {
-            content: [{ type: "text", text: summary }],
-            details: { op: params.op, goal },
-            ...(error ? { isError: true } : {}),
-        };
-    },
-});

package/dist/hooks-extension.js

@@ -1,176 +0,0 @@
-import { readMessageText, writeMessageText } from "./prompt-text.js";
-import { HOOKS_FILE, checkToolInput, loadHooks, resetOnceHooks, runHooksFor } from "./hooks.js";
-/** Read once per session; see the note above. */
-let config = { hooks: {} };
-/** Context a `SessionStart` hook contributed, kept for the session's prompts. */
-let sessionContext;
-export function createHooksExtension() {
-    return (hxf) => {
-        // Read the config HERE, in the factory, not in `session_start`.
-        //
-        // Measured: `session_start` does not fire in `-p` print mode — one-shot runs
-        // are exactly where a `PreToolUse` hook matters most (an unattended agent is
-        // the one you want policed), and loading in the lifecycle event left `config`
-        // empty there, so every hook silently did nothing. The factory runs in every
-        // mode. The read is one small synchronous file; it happens once per process.
-        const loaded = loadHooks(HOOKS_FILE);
-        config = loaded.config;
-        sessionContext = undefined;
-        // A resumed session re-arms its `once` hooks: the ledger is per process, and
-        // the session that just opened is a new one from the hook's point of view.
-        resetOnceHooks();
-        hxf.on("session_start", async (_event, ctx) => {
-            for (const diagnostic of loaded.diagnostics) {
-                ctx.ui.notify(`hooks.json: ${diagnostic.message}`, "warning");
-            }
-            const { outcome, ran } = await runHooksFor(config, "SessionStart", { hook_event_name: "SessionStart", cwd: ctx.cwd }, { cwd: ctx.cwd });
-            if (outcome.context)
-                sessionContext = outcome.context;
-            if (outcome.error)
-                ctx.ui.notify(`SessionStart hook: ${outcome.error}`, "warning");
-            if (ran && sessionContext) {
-                ctx.ui.notify(`SessionStart hooks added ${sessionContext.length} characters of context`, "info");
-            }
-        });
-        // `UserPromptSubmit` may block a prompt or add to it. The SDK's `input` event
-        // is the only place a prompt can be replaced before the run starts.
-        hxf.on("input", async (event, ctx) => {
-            if (!config.hooks.UserPromptSubmit)
-                return undefined;
-            const payload = {
-                hook_event_name: "UserPromptSubmit",
-                cwd: ctx.cwd,
-                prompt: event.text,
-            };
-            const { outcome } = await runHooksFor(config, "UserPromptSubmit", payload, { cwd: ctx.cwd });
-            if (outcome.error)
-                ctx.ui.notify(`UserPromptSubmit hook: ${outcome.error}`, "warning");
-            if (outcome.block) {
-                ctx.ui.notify(outcome.reason ?? "blocked by a hook", "warning");
-                return { action: "handled" };
-            }
-            if (!outcome.context)
-                return undefined;
-            return { action: "transform", text: `${event.text}\n\n${outcome.context}` };
-        });
-        // `PreToolUse` is the one that can refuse — or rewrite. It runs before the
-        // approval gate because a hook is the user's own policy and must not be
-        // overridable by an approval mode.
-        hxf.on("tool_call", async (event, ctx) => {
-            if (!config.hooks.PreToolUse)
-                return undefined;
-            const payload = {
-                hook_event_name: "PreToolUse",
-                cwd: ctx.cwd,
-                tool_name: event.toolName,
-                tool_input: event.input,
-            };
-            const { outcome } = await runHooksFor(config, "PreToolUse", payload, { cwd: ctx.cwd });
-            if (outcome.error)
-                ctx.ui.notify(`PreToolUse hook: ${outcome.error}`, "warning");
-            if (outcome.block) {
-                return { block: true, reason: outcome.reason ?? "blocked by a hook" };
-            }
-            // A rewrite replaces what the tool will actually do, so it is validated
-            // against the tool's own schema before it is used — the same schema the
-            // provider was given, read from the SDK's own registry. A rewrite that
-            // fails is dropped and the original arguments run: a guard must not be able
-            // to turn itself into a way to run something the model never asked for.
-            if (outcome.updatedInput) {
-                const tools = hxf.getAllTools();
-                const schema = tools.find((tool) => tool.name === event.toolName)?.parameters;
-                if (!schema) {
-                    ctx.ui.notify(`PreToolUse hook rewrote \`${event.toolName}\`, but no schema is known for that tool — the rewrite was ignored`, "warning");
-                }
-                else {
-                    const problem = checkToolInput(schema, outcome.updatedInput);
-                    if (problem) {
-                        ctx.ui.notify(`PreToolUse hook rewrite ignored — ${problem}`, "warning");
-                    }
-                    else {
-                        // The SDK's documented way to change arguments: mutate in place.
-                        Object.assign(event.input, outcome.updatedInput);
-                    }
-                }
-            }
-            return undefined;
-        });
-        // `PostToolUse` adds context to what the tool returned. The event is
-        // `tool_result`, and the result's `content` is replaced with the hook's text
-        // appended — `structuredContent` is returned alongside it so it is not
-        // dropped (the SDK drops it otherwise).
-        hxf.on("tool_result", async (event, ctx) => {
-            if (!config.hooks.PostToolUse)
-                return undefined;
-            const text = event.content.map((block) => (block.type === "text" ? block.text : "")).join("\n");
-            const payload = {
-                hook_event_name: "PostToolUse",
-                cwd: ctx.cwd,
-                tool_name: event.toolName,
-                tool_input: event.input,
-                tool_result: text,
-                tool_is_error: event.isError,
-            };
-            const { outcome } = await runHooksFor(config, "PostToolUse", payload, { cwd: ctx.cwd });
-            if (outcome.error)
-                ctx.ui.notify(`PostToolUse hook: ${outcome.error}`, "warning");
-            if (!outcome.context)
-                return undefined;
-            return {
-                content: [...event.content, { type: "text", text: `\n[hook] ${outcome.context}` }],
-                structuredContent: event.structuredContent,
-            };
-        });
-        // `SessionStart` context reaches the model through the same path the shared
-        // notes use: appended to the leading system message, which must stay at index
-        // 0 because that is where the provider reads the prompt from.
-        hxf.on("context_with_system", async (event) => {
-            if (!sessionContext)
-                return undefined;
-            const head = event.messages[0];
-            if (!head || head.role !== "system")
-                return undefined;
-            const combined = `${readMessageText(head.content)}\n\n${sessionContext}`;
-            const messages = event.messages.map((message) => (message === head ? { ...head, content: writeMessageText(head.content, combined) } : message));
-            return { messages };
-        });
-        // `PreCompact` observes a compaction before it happens — the moment context
-        // is about to be thrown away. Notification only: the SDK's compaction result
-        // is not something a shell command should be able to veto, and a hook that
-        // could would be a way to wedge a session at its most fragile point.
-        hxf.on("session_before_compact", async (event, ctx) => {
-            if (!config.hooks.PreCompact)
-                return;
-            const { outcome } = await runHooksFor(config, "PreCompact", {
-                hook_event_name: "PreCompact",
-                cwd: ctx.cwd,
-                compact_reason: event.reason,
-            }, { cwd: ctx.cwd });
-            if (outcome.error)
-                ctx.ui.notify(`PreCompact hook: ${outcome.error}`, "warning");
-        });
-        // `SessionEnd` for a session that is **replaced** (`/new`, `/resume`, a fork).
-        //
-        // Measured: this event does NOT fire when the process exits — `/quit` and
-        // double Ctrl+C produced zero events, even for a TypeScript extension writing
-        // synchronously. The quit path is therefore handled in `ui.ts`'s `shutdown()`,
-        // which runs the same hooks and awaits them. This handler covers the other
-        // moment the session ends: being swapped for another one.
-        hxf.on("session_shutdown", async (event, ctx) => {
-            if (!config.hooks.SessionEnd)
-                return;
-            const { outcome } = await runHooksFor(config, "SessionEnd", { hook_event_name: "SessionEnd", cwd: ctx.cwd, reason: event.reason }, { cwd: ctx.cwd });
-            if (outcome.error)
-                ctx.ui.notify(`SessionEnd hook: ${outcome.error}`, "warning");
-        });
-        // `Stop` is notification-only: it fires when the run will not continue on its
-        // own, which is the moment an integration wants to know about.
-        hxf.on("agent_settled", async (_event, ctx) => {
-            if (!config.hooks.Stop)
-                return;
-            const { outcome } = await runHooksFor(config, "Stop", { hook_event_name: "Stop", cwd: ctx.cwd }, { cwd: ctx.cwd });
-            if (outcome.error)
-                ctx.ui.notify(`Stop hook: ${outcome.error}`, "warning");
-        });
-    };
-}