@sunshinelife83/hearth 1.0.0

package/dist/tool-surfaces/codex.js

@@ -0,0 +1,255 @@
+import * as z from "zod/v4";
+import { logEvent } from "../logger.js";
+import { applyPatch } from "../apply-patch.js";
+import { EDIT_TOOL_ANNOTATIONS, SHELL_TOOL_ANNOTATIONS, toolNames, workspaceIdDescription, } from "./types.js";
+import { enforceShellPolicy, resultOutputSchema, runLoggedToolOperation, sandboxDecision, snapshotBeforeRiskyExecution, textBlock, } from "./shared.js";
+const CODEX_INSTRUCTIONS = `Use ${toolNames.read} for direct file reads, apply_patch for all file modifications, exec_command for inspection, tests, builds, and other commands, and write_stdin to poll or interact with running processes. Commands run with the local user's authority and are not sandboxed; workspace validation only selects their initial working directory. Command policy: inspection commands run freely; ordinary workspace work (builds, tests, local edits) runs freely; commands with effects outside the workspace (network fetches, package installs, recursive deletes, git push, permission changes) require explicit user approval in the conversation and the approvedByUser flag; privilege escalation, system management, and piping remote scripts into a shell are always blocked. Follow instructions returned by ${toolNames.openWorkspace}; read applicable instruction and skill files before working in their scope.`;
+export function codexInstructions() {
+    return CODEX_INSTRUCTIONS;
+}
+export function registerCodexTools(context) {
+    for (const register of CODEX_REGISTRATIONS) {
+        register(context);
+    }
+}
+const CODEX_REGISTRATIONS = [
+    registerApplyPatchTool,
+    registerCodexProcessTools,
+];
+function processResult(snapshot) {
+    const status = snapshot.running
+        ? `Process running with session ID ${snapshot.sessionId}.`
+        : snapshot.signal
+            ? `Process exited after signal ${snapshot.signal}.`
+            : `Process exited with code ${snapshot.exitCode ?? "unknown"}.`;
+    return snapshot.output
+        ? `${snapshot.output.replace(/\n$/, "")}\n${status}`
+        : status;
+}
+function processOutputSchema() {
+    return resultOutputSchema({
+        sessionId: z.number().optional(),
+        running: z.boolean(),
+        exitCode: z.number().int().optional(),
+        signal: z.string().optional(),
+        wallTimeMs: z.number().nonnegative(),
+        outputTruncated: z.boolean(),
+    });
+}
+function processToolResponse(snapshot) {
+    const result = processResult(snapshot);
+    const content = [textBlock(result)];
+    return {
+        content,
+        structuredContent: {
+            result,
+            sessionId: snapshot.sessionId,
+            running: snapshot.running,
+            exitCode: snapshot.exitCode,
+            signal: snapshot.signal,
+            wallTimeMs: snapshot.wallTimeMs,
+            outputTruncated: snapshot.outputTruncated,
+        },
+    };
+}
+function registerApplyPatchTool(context) {
+    const { server, config, workspaces } = context;
+    server.registerTool("apply_patch", {
+        title: "Apply patch",
+        description: "Apply one structured patch in a workspace. Supports adding, overwriting, updating, deleting, and moving files. Use this for all file modifications. Paths must be relative to the workspace.",
+        inputSchema: {
+            workspaceId: z.string().describe(workspaceIdDescription),
+            patch: z
+                .string()
+                .describe("Patch text enclosed by *** Begin Patch and *** End Patch markers."),
+        },
+        outputSchema: resultOutputSchema({
+            additions: z.number(),
+            removals: z.number(),
+            files: z.array(z.object({
+                path: z.string(),
+                previousPath: z.string().optional(),
+                operation: z.enum(["add", "update", "delete", "move"]),
+            })),
+        }),
+        annotations: EDIT_TOOL_ANNOTATIONS,
+    }, async ({ workspaceId, patch }) => {
+        const startedAt = performance.now();
+        const applied = await runLoggedToolOperation(config, { tool: "apply_patch", workspaceId }, startedAt, async () => {
+            const workspace = workspaces.getWorkspace(workspaceId);
+            return applyPatch(workspace.root, patch);
+        });
+        const paths = applied.files.map((file) => file.path).join(", ");
+        const result = `Applied patch to ${applied.files.length} file(s): ${paths}`;
+        const content = [textBlock(result)];
+        return {
+            content,
+            structuredContent: {
+                result,
+                additions: applied.additions,
+                removals: applied.removals,
+                files: applied.files,
+            },
+        };
+    });
+}
+function registerCodexProcessTools(context) {
+    const { server, config, workspaces, processSessions } = context;
+    server.registerTool("exec_command", {
+        title: "Execute command",
+        description: "Run a command with the local user's authority. Commands are not sandboxed; workspace validation only selects the initial working directory. Returns the result when it exits during the yield window, otherwise returns a sessionId for write_stdin. Use this for file inspection, tests, builds, package scripts, and long-running processes.",
+        inputSchema: {
+            workspaceId: z.string().describe(workspaceIdDescription),
+            cmd: z.string().min(1).describe("Shell command to execute."),
+            tty: z
+                .boolean()
+                .optional()
+                .describe("Allocate a pseudo-terminal for interactive commands. Defaults to false."),
+            columns: z
+                .number()
+                .int()
+                .min(1)
+                .max(1_000)
+                .optional()
+                .describe("Initial PTY width. Defaults to 80."),
+            rows: z
+                .number()
+                .int()
+                .min(1)
+                .max(1_000)
+                .optional()
+                .describe("Initial PTY height. Defaults to 24."),
+            workingDirectory: z
+                .string()
+                .optional()
+                .describe("Working directory relative to the workspace root. Defaults to the workspace root."),
+            yieldTimeMs: z
+                .number()
+                .int()
+                .min(0)
+                .max(30_000)
+                .optional()
+                .describe("Milliseconds to wait before returning a running session. Defaults to 10000."),
+            maxOutputTokens: z
+                .number()
+                .int()
+                .positive()
+                .max(100_000)
+                .optional()
+                .describe("Approximate output token budget. Defaults to 10000."),
+            approvedByUser: z
+                .boolean()
+                .optional()
+                .describe("Set to true only after the user explicitly approved this exact command in the conversation. Required for tier-2 commands (network, installs, recursive deletes, pushes) unless the workspace runs in autonomous mode."),
+        },
+        outputSchema: processOutputSchema(),
+        annotations: SHELL_TOOL_ANNOTATIONS,
+    }, async ({ workspaceId, cmd, tty, columns, rows, workingDirectory, yieldTimeMs, maxOutputTokens, approvedByUser, }) => {
+        const startedAt = performance.now();
+        const workspace = workspaces.getWorkspace(workspaceId);
+        const verdict = enforceShellPolicy(config, { tool: "exec_command", workspaceId, command: cmd, workspaceRoot: workspace.root }, approvedByUser);
+        if (verdict.denial) {
+            logEvent(config.logging, "info", "tool_call", {
+                tool: "exec_command",
+                workspaceId,
+                success: false,
+                durationMs: Math.round(performance.now() - startedAt),
+                error: "policy_denied",
+            });
+            return verdict.denial;
+        }
+        const sandbox = sandboxDecision(config, verdict.classification.tier, workspace.root);
+        if (sandbox.denialReason) {
+            return {
+                content: [textBlock(sandbox.denialReason)],
+                isError: true,
+                structuredContent: { result: sandbox.denialReason },
+            };
+        }
+        const snapshot = await runLoggedToolOperation(config, {
+            tool: "exec_command",
+            workspaceId,
+            workingDirectory: workingDirectory ?? ".",
+            command: cmd,
+            commandLength: cmd.length,
+        }, startedAt, async () => {
+            const workspace = workspaces.getWorkspace(workspaceId);
+            await snapshotBeforeRiskyExecution(config, workspace, cmd);
+            const cwd = workspaces.resolveWorkingDirectory(workspace, workingDirectory);
+            return processSessions.start({
+                workspaceId,
+                command: cmd,
+                cwd,
+                workspaceRoot: workspace.root,
+                sandbox: sandbox.enabled,
+                tty,
+                columns,
+                rows,
+                yieldTimeMs,
+                maxOutputTokens,
+            });
+        });
+        return processToolResponse(snapshot);
+    });
+    server.registerTool("write_stdin", {
+        title: "Write to process",
+        description: "Poll or write characters to a process returned by exec_command. Omit chars or pass an empty string to poll. Pass \\u0003 to send Ctrl-C.",
+        inputSchema: {
+            workspaceId: z
+                .string()
+                .describe("Workspace identifier used to start the process."),
+            sessionId: z
+                .number()
+                .describe("Process session identifier returned by exec_command."),
+            chars: z
+                .string()
+                .optional()
+                .describe("Characters to write. Omit or pass an empty string to poll."),
+            columns: z
+                .number()
+                .int()
+                .min(1)
+                .max(1_000)
+                .optional()
+                .describe("Resize a PTY to this width."),
+            rows: z
+                .number()
+                .int()
+                .min(1)
+                .max(1_000)
+                .optional()
+                .describe("Resize a PTY to this height."),
+            yieldTimeMs: z
+                .number()
+                .int()
+                .min(0)
+                .max(30_000)
+                .optional()
+                .describe("Milliseconds to wait for process output or completion. Defaults to 10000."),
+            maxOutputTokens: z
+                .number()
+                .int()
+                .positive()
+                .max(100_000)
+                .optional()
+                .describe("Approximate output token budget. Defaults to 10000."),
+        },
+        outputSchema: processOutputSchema(),
+        annotations: SHELL_TOOL_ANNOTATIONS,
+    }, async ({ workspaceId, sessionId, chars, columns, rows, yieldTimeMs, maxOutputTokens, }) => {
+        const startedAt = performance.now();
+        const snapshot = await runLoggedToolOperation(config, { tool: "write_stdin", workspaceId }, startedAt, async () => {
+            workspaces.getWorkspace(workspaceId);
+            return processSessions.write({
+                workspaceId,
+                sessionId,
+                chars,
+                columns,
+                rows,
+                yieldTimeMs,
+                maxOutputTokens,
+            });
+        });
+        return processToolResponse(snapshot);
+    });
+}

package/dist/tool-surfaces/index.js

@@ -0,0 +1,15 @@
+import { codexInstructions, registerCodexTools } from "./codex.js";
+import { claudeInstructions, registerClaudeTools } from "./claude.js";
+const TOOL_SURFACES = {
+    claude: {
+        register: registerClaudeTools,
+        instructions: claudeInstructions,
+    },
+    codex: {
+        register: registerCodexTools,
+        instructions: codexInstructions,
+    },
+};
+export function getToolSurface(mode) {
+    return TOOL_SURFACES[mode];
+}

package/dist/tool-surfaces/shared.js

@@ -0,0 +1,228 @@
+import * as z from "zod/v4";
+import { logEvent, commandPreview } from "../logger.js";
+import { classifyCommand, decideExecution, } from "../policy/command-policy.js";
+import { createSnapshot } from "../snapshot-manager.js";
+import { probeSandboxAdapter } from "../policy/sandbox.js";
+import { commandListVerdict, resolveExecutionForWorkspace, } from "../policy/workspace-profiles.js";
+import { WORKSPACE_APP_URI, } from "./types.js";
+/**
+ * Policy gate for model-invoked shell commands. Every shell tool call passes
+ * through here before any process is spawned. Returns a denial response or
+ * the verdict allowing execution (with classification for audit/snapshot use).
+ */
+export function enforceShellPolicy(config, fields, approvedByUser) {
+    const resolved = fields.workspaceRoot
+        ? resolveExecutionForWorkspace(config, fields.workspaceRoot)
+        : globalExecution(config);
+    const classification = classifyCommand(fields.command);
+    // Workspace allow/deny command lists run before the tier engine: an
+    // explicit deny is final; an allow list restricts to matching commands.
+    const listVerdict = commandListVerdict(resolved, fields.command);
+    if (!listVerdict.allowed) {
+        const reason = `Blocked by workspace policy: ${listVerdict.rule}. Ask the workspace owner to adjust this workspace's profile.`;
+        logEvent(config.logging, "warn", "policy_decision", {
+            tool: fields.tool,
+            workspaceId: fields.workspaceId,
+            tier: classification.tier,
+            decision: "deny",
+            mode: resolved.mode,
+            rule: listVerdict.rule,
+            commandPreview: commandPreview(fields.command),
+        });
+        return {
+            classification,
+            decision: { decision: "deny", reason },
+            denial: {
+                content: [{ type: "text", text: reason }],
+                isError: true,
+                structuredContent: { result: reason },
+            },
+        };
+    }
+    const decision = decideExecution({
+        mode: resolved.mode,
+        tier: classification.tier,
+        approvedByUser,
+    });
+    logEvent(config.logging, decision.decision === "allow" ? "info" : "warn", "policy_decision", {
+        tool: fields.tool,
+        workspaceId: fields.workspaceId,
+        tier: classification.tier,
+        rules: classification.rules,
+        decision: decision.decision,
+        mode: resolved.mode,
+        workspaceProfile: resolved.profilePath,
+        approvalClaimed: decision.approvalClaimed ?? (approvedByUser === true && classification.tier >= 2),
+        commandPreview: commandPreview(fields.command),
+    });
+    if (decision.decision === "allow") {
+        return { classification, decision };
+    }
+    return {
+        classification,
+        decision,
+        denial: {
+            content: [{ type: "text", text: decision.reason }],
+            isError: true,
+            // Structured content must match the tool's declared output schema
+            // (resultOutputSchema); tier/rule details live in the audit log.
+            structuredContent: {
+                result: decision.reason,
+            },
+        },
+    };
+}
+/**
+ * Best-effort snapshot before autonomous tier-2 execution. Best-effort by
+ * decision (ADR-006a): a non-Git workspace or a snapshot failure logs a
+ * warning and continues, because blocking every autonomous command on
+ * snapshot availability would make the mode unusable outside git repos.
+ */
+export async function snapshotBeforeRiskyExecution(config, workspace, command) {
+    if (config.execution.mode !== "autonomous")
+        return;
+    if (classifyCommand(command).tier < 2)
+        return;
+    try {
+        const snapshot = await createSnapshot({
+            root: workspace.root,
+            workspaceId: workspace.id,
+            label: `pre-tier2 ${commandPreview(command)}`,
+        });
+        logEvent(config.logging, "info", "snapshot_created", {
+            workspaceId: workspace.id,
+            snapshotId: snapshot.snapshotId,
+            reason: "autonomous_tier2",
+            commandPreview: commandPreview(command),
+        });
+    }
+    catch (error) {
+        logEvent(config.logging, "warn", "snapshot_failed", {
+            workspaceId: workspace.id,
+            reason: error instanceof Error ? error.message : String(error),
+            commandPreview: commandPreview(command),
+        });
+    }
+}
+export function resultOutputSchema(extra = {}) {
+    return {
+        result: z
+            .string()
+            .describe("Model-readable result text for follow-up reasoning and plain MCP hosts."),
+        ...extra,
+    };
+}
+export function workspaceAppDescriptorMeta(config) {
+    if (!config.uiEnabled)
+        return { _meta: {} };
+    return {
+        _meta: {
+            ui: {
+                resourceUri: WORKSPACE_APP_URI,
+                visibility: ["model"],
+            },
+        },
+    };
+}
+export function logToolCall(config, fields) {
+    if (!config.logging.toolCalls)
+        return;
+    const { command, ...safeFields } = fields;
+    logEvent(config.logging, fields.success ? "info" : "warn", "tool_call", {
+        ...safeFields,
+        commandPreview: config.logging.shellCommands && command
+            ? commandPreview(command)
+            : undefined,
+    });
+}
+export async function runLoggedToolOperation(config, fields, startedAt, operation) {
+    try {
+        const result = await operation();
+        logToolCall(config, {
+            ...fields,
+            success: true,
+            durationMs: Math.round(performance.now() - startedAt),
+        });
+        return result;
+    }
+    catch (error) {
+        logToolCall(config, {
+            ...fields,
+            success: false,
+            durationMs: Math.round(performance.now() - startedAt),
+            error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
+}
+export function contentText(content) {
+    return content
+        .filter((item) => item.type === "text")
+        .map((item) => item.text)
+        .join("\n");
+}
+function toolErrorPreview(content) {
+    const text = contentText(content).replace(/\s+/g, " ").trim();
+    if (!text)
+        return undefined;
+    return text.length > 240 ? `${text.slice(0, 237)}...` : text;
+}
+export function logFailedToolResponse(config, fields, content, startedAt) {
+    logToolCall(config, {
+        ...fields,
+        success: false,
+        durationMs: Math.round(performance.now() - startedAt),
+        error: toolErrorPreview(content),
+    });
+}
+export function textBlock(text) {
+    return { type: "text", text };
+}
+export function countDiffStats(diff) {
+    if (!diff)
+        return { additions: 0, removals: 0 };
+    let additions = 0;
+    let removals = 0;
+    for (const line of diff.split("\n")) {
+        if (line.startsWith("+") && !line.startsWith("+++"))
+            additions++;
+        if (line.startsWith("-") && !line.startsWith("---"))
+            removals++;
+    }
+    return { additions, removals };
+}
+/**
+ * Sandbox decision for one command. "auto" sandboxes autonomous-mode
+ * executions when an adapter is available; requireSandboxForAutonomous
+ * hard-gates tier-2 commands on sandbox availability.
+ */
+export function sandboxDecision(config, tier, workspaceRoot) {
+    const resolved = workspaceRoot
+        ? resolveExecutionForWorkspace(config, workspaceRoot)
+        : globalExecution(config);
+    const sandboxSetting = resolved.sandbox ?? config.execution.sandbox;
+    if (sandboxSetting === "none")
+        return { enabled: false };
+    const available = probeSandboxAdapter() !== "none";
+    const autonomous = resolved.mode === "autonomous";
+    if (autonomous && tier >= 2 && !available && resolved.requireSandboxForAutonomous) {
+        return {
+            enabled: false,
+            denialReason: "Autonomous tier-2 commands require an OS sandbox, but none is available on this machine. " +
+                "Install bubblewrap (Linux), set execution.sandbox to 'none' explicitly, or set " +
+                "execution.requireSandboxForAutonomous to false.",
+        };
+    }
+    return { enabled: autonomous && available };
+}
+function globalExecution(config) {
+    return {
+        mode: config.execution.mode,
+        sandbox: undefined,
+        sandboxNetwork: undefined,
+        requireSandboxForAutonomous: config.execution.requireSandboxForAutonomous,
+        commandAllow: [],
+        commandDeny: [],
+        agentsAllowed: true,
+    };
+}

package/dist/tool-surfaces/types.js

@@ -0,0 +1,27 @@
+export const WORKSPACE_APP_URI = "ui://hearth/workspace-app.html";
+export const toolNames = {
+    openWorkspace: "open_workspace",
+    read: "read",
+    write: "write",
+    edit: "edit",
+    shell: "bash",
+};
+export const workspaceIdDescription = "Workspace to use. Reuse the current project's workspaceId.";
+export const WRITE_TOOL_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+};
+export const EDIT_TOOL_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+};
+export const SHELL_TOOL_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+};