@oharness/engine 0.1.0

package/dist/sync/settings.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+/**
+ * Whether to mirror, and where to.
+ *
+ * Sync is on by default, which is a decision about defaults rather than about
+ * consent: it cannot do anything until there is a destination and a token, and
+ * the token comes from signing in. So the honest reading of "on" is "as soon
+ * as you have an account", and a machine that never signs in never sends
+ * anything.
+ *
+ * Three ways to stop it, in the order they are checked. Each exists because
+ * the others do not cover its case:
+ *
+ *   `OHARNESS_SYNC=0`   one run, or every run in CI, without editing a file.
+ *   `sync.enabled`      this machine, or this repository (off only — see
+ *                       `mergeSync` on why a project cannot switch it on).
+ *   `sync.exclude`      one project, while everything else keeps mirroring.
+ */
+/** The official service. Overridden by `sync.url` for self-hosted servers. */
+export const DEFAULT_SYNC_URL = "https://sync.oharness.ai";
+export function resolveSync(inputs) {
+    const env = inputs.env ?? process.env;
+    const flag = env["OHARNESS_SYNC"];
+    if (flag !== undefined && OFF.has(flag.trim().toLowerCase())) {
+        return { on: false, reason: "disabled" };
+    }
+    if (inputs.config?.enabled === false)
+        return { on: false, reason: "disabled" };
+    const url = (inputs.config?.url ?? env["OHARNESS_SYNC_URL"] ?? DEFAULT_SYNC_URL).replace(/\/+$/, "");
+    const token = inputs.config?.token ?? env["OHARNESS_SYNC_TOKEN"] ?? inputs.accountToken;
+    // Not an error: an unauthenticated harness is the normal state before the
+    // first sign-in, and it should behave exactly like one with sync switched
+    // off rather than logging a failure on every write.
+    if (!token)
+        return { on: false, reason: "no-credential" };
+    return { on: true, target: { url, token } };
+}
+/**
+ * Whether one project is excluded.
+ *
+ * Matched against both the project id and the worktree path, because neither
+ * alone is what a person reaches for: the id is a commit hash nobody has
+ * memorised, and the path is what they would type.
+ */
+export function isExcluded(config, project) {
+    const list = config?.exclude ?? [];
+    if (list.length === 0)
+        return false;
+    const cwd = project.cwd ? path.resolve(project.cwd) : undefined;
+    return list.some((entry) => {
+        const trimmed = entry.trim();
+        if (!trimmed)
+            return false;
+        if (trimmed === project.id)
+            return true;
+        return cwd !== undefined && path.resolve(trimmed) === cwd;
+    });
+}
+const OFF = new Set(["0", "false", "off", "no"]);
+//# sourceMappingURL=settings.js.map

package/dist/sync/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../src/sync/settings.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B;;;;;;;;;;;;;;;;GAgBG;AAEH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAyB3D,MAAM,UAAU,WAAW,CAAC,MAAkB;IAC5C,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IAEtC,MAAM,IAAI,GAAG,GAAG,CAAC,eAAe,CAAC,CAAC;IAClC,IAAI,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QAC7D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC3C,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,KAAK,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAE/E,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,mBAAmB,CAAC,IAAI,gBAAgB,CAAC,CAAC,OAAO,CACtF,MAAM,EACN,EAAE,CACH,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,GAAG,CAAC,qBAAqB,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC;IACxF,0EAA0E;IAC1E,0EAA0E;IAC1E,oDAAoD;IACpD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAE1D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACxB,MAA8B,EAC9B,OAAqC;IAErC,MAAM,IAAI,GAAG,MAAM,EAAE,OAAO,IAAI,EAAE,CAAC;IACnC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAEpC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAChE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;QACzB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC3B,IAAI,OAAO,KAAK,OAAO,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QACxC,OAAO,GAAG,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC"}

package/dist/tools/builtin/artifact.d.ts

@@ -0,0 +1,16 @@
+import { MAX_ARTIFACT_BYTES } from "../../artifacts/store.ts";
+/**
+ * Where an artifact descriptor rides back to the agent loop.
+ *
+ * On `metadata`, which the type for it says is "not sent to the model;
+ * available to hooks and the UI" — exactly the channel this needs. The agent
+ * reads it after the tool returns and turns it into an `artifact` event, since
+ * a tool has no way to yield into the event stream itself.
+ */
+export declare const ARTIFACT_METADATA_KEY = "artifact";
+export declare const artifactTool: import("../types.ts").Tool;
+/** Read an artifact back, for a model that needs to reason over what it made. */
+export declare const artifactReadTool: import("../types.ts").Tool;
+/** Both artifact tools, for registries that take the pair. */
+export declare const artifactTools: import("../types.ts").Tool[];
+export { MAX_ARTIFACT_BYTES };

package/dist/tools/builtin/artifact.js

@@ -0,0 +1,134 @@
+import { z } from "zod";
+import { defineTool } from "../define.js";
+import { toolError, toolText } from "../types.js";
+import { CANVAS_MIME, getArtifactStore, MAX_ARTIFACT_BYTES } from "../../artifacts/store.js";
+import { errorMessage } from "../../core/errors.js";
+/**
+ * Where an artifact descriptor rides back to the agent loop.
+ *
+ * On `metadata`, which the type for it says is "not sent to the model;
+ * available to hooks and the UI" — exactly the channel this needs. The agent
+ * reads it after the tool returns and turns it into an `artifact` event, since
+ * a tool has no way to yield into the event stream itself.
+ */
+export const ARTIFACT_METADATA_KEY = "artifact";
+export const artifactTool = defineTool({
+    name: "artifact_write",
+    description: [
+        "Create or revise a rendered artifact: a chart, a document, a self-contained HTML page, an SVG.",
+        "Use this for output whose value is in being *looked at* rather than read as a tool result,",
+        "and which does not belong in the working tree as a file.",
+        "Call it again with the same `id` to revise — that keeps one artifact with a version history",
+        "instead of littering the panel with near-duplicates. Send the complete new content every time.",
+        "Prefer the `write` tool for anything the user will keep: source files, configs, real documents.",
+        "An artifact lives only for this session.",
+        // Stated here rather than only in the artifact-authoring skill because a
+        // skill is opt-in and this is not: an artifact that breaks this rule is
+        // stored, published and rendered as a blank rectangle, with nothing
+        // anywhere saying why. See PUBLISHED_ARTIFACT_CSP.
+        "HTML artifacts MUST be a single self-contained file: they run under a sandbox that blocks",
+        "every external resource. Scripts, stylesheets, fonts and images from a CDN or any URL will",
+        "NOT load (so no React, Vue, Tailwind, Chart.js or D3 from a CDN, and no JSX — there is no",
+        "build step), and fetch/XHR/WebSocket are blocked. Inline <style> and inline <script> do run;",
+        "use plain DOM, canvas or SVG, embed data as literals, and use data: URIs for images.",
+        // Named here and not only in the skill for the same reason the CSP rule
+        // is: a model that has never heard of this mime will never author one, and
+        // the whole editing surface stays unreachable.
+        `Mime \`${CANVAS_MIME}\` makes a *canvas*: a pan-and-zoom board of artboards the user can`,
+        "select, edit and save directly. Write only `<artboard title=\"…\" width=… height=…>` blocks",
+        "(plus an optional leading `<style>`) — the editor, the layout and the chrome come from the",
+        "harness, so do not write `<html>`, a viewport, or any pan/zoom code of your own.",
+        "Read the artifact-authoring skill before writing one.",
+    ].join(" "),
+    parameters: z.object({
+        id: z
+            .string()
+            .describe("Stable identifier, e.g. `sales-chart`. Reuse it to revise the same artifact. Letters, digits, dot, dash, underscore."),
+        title: z.string().min(1).describe("Human-readable name shown in the artifact list"),
+        mime: z
+            .string()
+            .describe("Content type: text/plain, text/markdown, text/html, image/svg+xml, application/json, " +
+            `${CANVAS_MIME} (an editable canvas of artboards).`),
+        content: z.string().describe("The complete artifact body. Replaces any previous revision."),
+        language: z
+            .string()
+            .optional()
+            .describe("Language hint for syntax highlighting when the content is source code"),
+    }),
+    // Writes to the session's in-memory store and nothing else. Before this the
+    // approval dialog arrived *after* the model had already written the whole
+    // artifact — the content is the tool's argument — so it could not prevent the
+    // work, only the showing of it, and it presented several kilobytes of escaped
+    // source as the thing to judge.
+    sessionLocal: true,
+    renderTitle: (input) => `Artifact(${input.id})`,
+    async execute(input, ctx) {
+        const store = getArtifactStore(ctx.host.state);
+        // Read before writing, because after the put the previous revision is no
+        // longer the latest and this question can no longer be asked. The model
+        // has no other way to find out that the version it is revising was not the
+        // one it wrote: it sent content derived from its own last output, and a
+        // person's edits are about to stop being what the user sees.
+        const replaced = store.get(input.id)?.revision.author === "user";
+        let descriptor;
+        try {
+            descriptor = store.put({
+                id: input.id,
+                title: input.title,
+                mime: input.mime,
+                content: input.content,
+                ...(input.language !== undefined ? { language: input.language } : {}),
+            });
+        }
+        catch (err) {
+            // The store's rules (id shape, size ceiling) come back as tool errors so
+            // the model can correct itself on the next turn rather than the turn
+            // dying on an exception.
+            return toolError(errorMessage(err));
+        }
+        // What goes back to the model is a receipt, not the content: it just sent
+        // the content, and echoing it doubles the artifact's cost in the
+        // transcript for no information gained.
+        const revision = descriptor.version === 1
+            ? "created"
+            : `revised (version ${descriptor.version} of ${descriptor.versionCount} kept)`;
+        return toolText(`Artifact "${descriptor.title}" ${revision}. ` +
+            `id=${descriptor.id} kind=${descriptor.kind} ${descriptor.bytes} bytes.` +
+            (replaced
+                ? ` Note: version ${descriptor.version - 1} was edited by the user and your revision` +
+                    ` replaced it. Nothing is lost — read version ${descriptor.version - 1} to see what` +
+                    ` they changed — but say so, and offer to fold their edits back in.`
+                : ""), { [ARTIFACT_METADATA_KEY]: descriptor });
+    },
+});
+/** Read an artifact back, for a model that needs to reason over what it made. */
+export const artifactReadTool = defineTool({
+    name: "artifact_read",
+    description: "Read back the content of an artifact you created earlier in this session, optionally at a specific version.",
+    readOnly: true,
+    parameters: z.object({
+        id: z.string().describe("The artifact's id"),
+        version: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Which revision to read. Defaults to the latest."),
+    }),
+    renderTitle: (input) => `ArtifactRead(${input.id}${input.version ? `@${input.version}` : ""})`,
+    async execute(input, ctx) {
+        const store = getArtifactStore(ctx.host.state);
+        const found = store.get(input.id, input.version);
+        if (!found) {
+            const known = store.list().map((a) => a.id);
+            return toolError(known.length
+                ? `No artifact ${input.id}${input.version ? ` at version ${input.version}` : ""}. Known: ${known.join(", ")}.`
+                : `No artifact ${input.id}. Nothing has been created this session.`);
+        }
+        return toolText(found.revision.content);
+    },
+});
+/** Both artifact tools, for registries that take the pair. */
+export const artifactTools = [artifactTool, artifactReadTool];
+export { MAX_ARTIFACT_BYTES };
+//# sourceMappingURL=artifact.js.map

package/dist/tools/builtin/artifact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.js","sourceRoot":"","sources":["../../../src/tools/builtin/artifact.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtin/bash.d.ts

@@ -0,0 +1,3 @@
+import type { ToolResult } from "../types.ts";
+export declare const bashTool: import("../types.ts").Tool;
+export declare function bashResultText(result: ToolResult): string;

package/dist/tools/builtin/bash.js

@@ -0,0 +1,142 @@
+import { spawn } from "node:child_process";
+import { isWindowsShell, shellFor } from "../../util/shell.js";
+import path from "node:path";
+import { z } from "zod";
+import { defineTool } from "../define.js";
+import { toolText } from "../types.js";
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_TIMEOUT_MS = 600_000;
+const MAX_OUTPUT_CHARS = 30_000;
+/**
+ * `cd` inside one command would otherwise be lost, because each call is its
+ * own process. We keep a per-session working directory instead of holding a
+ * long-lived shell open, which avoids a whole class of wedged-process bugs.
+ */
+const CWD_KEY = "bash:cwd";
+export const bashTool = defineTool({
+    name: "bash",
+    description: [
+        "Run a shell command. The working directory persists across calls within a session, so `cd` works as expected.",
+        "Prefer the dedicated read/write/edit/glob/grep tools for file work — they are safer and produce better output.",
+        "Output is truncated at 30k characters; redirect to a file and read it if you need more.",
+    ].join(" "),
+    parameters: z.object({
+        command: z.string().min(1).describe("The command to run"),
+        description: z
+            .string()
+            .optional()
+            .describe("Short description of what the command does, shown to the user"),
+        timeoutMs: z
+            .number()
+            .int()
+            .min(1_000)
+            .max(MAX_TIMEOUT_MS)
+            .optional()
+            .describe(`Timeout in milliseconds (default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS})`),
+    }),
+    renderTitle: (input) => `Bash(${input.command})`,
+    async execute(input, ctx) {
+        const cwd = sessionCwd(ctx);
+        const timeout = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const result = await runShell(input.command, cwd, timeout, ctx);
+        if (result.newCwd)
+            ctx.host.state.set(CWD_KEY, result.newCwd);
+        const parts = [];
+        if (result.stdout)
+            parts.push(result.stdout);
+        if (result.stderr)
+            parts.push(result.stderr);
+        let body = parts.join("\n").trimEnd();
+        if (body.length > MAX_OUTPUT_CHARS) {
+            const kept = body.slice(0, MAX_OUTPUT_CHARS);
+            body = `${kept}\n\n… output truncated (${body.length - MAX_OUTPUT_CHARS} more characters).`;
+        }
+        if (result.timedOut) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Command timed out after ${timeout}ms and was killed.\n${body}`.trimEnd(),
+                    },
+                ],
+                isError: true,
+                metadata: { exitCode: null, timedOut: true, cwd },
+            };
+        }
+        if (result.code !== 0) {
+            return {
+                content: [
+                    { type: "text", text: `Exit code ${result.code}\n${body}`.trimEnd() },
+                ],
+                isError: true,
+                metadata: { exitCode: result.code, cwd },
+            };
+        }
+        return toolText(body === "" ? "(no output)" : body, { exitCode: 0, cwd });
+    },
+});
+function sessionCwd(ctx) {
+    const stored = ctx.host.state.get(CWD_KEY);
+    return typeof stored === "string" ? stored : ctx.cwd;
+}
+/**
+ * Runs the command and then echoes the resulting directory on a sentinel line,
+ * so a `cd` performed by the command carries into the next call.
+ */
+function runShell(command, cwd, timeoutMs, ctx) {
+    const sentinel = "__OHARNESS_CWD__";
+    // cmd.exe has no $PWD, no `printf` and no `exit $?` — the probe that tracks
+    // directory changes has to be written in each shell's own dialect.
+    const wrapped = isWindowsShell()
+        ? `${command}\r\n@set __oh_status=%ERRORLEVEL%\r\n@echo.\r\n@echo ${sentinel}%CD%\r\n@exit /b %__oh_status%`
+        : `${command}\n__oh_status=$?\nprintf '\\n${sentinel}%s\\n' "$PWD"\nexit $__oh_status`;
+    const shell = shellFor(wrapped);
+    return new Promise((resolve) => {
+        const child = spawn(shell.command, shell.args, {
+            cwd,
+            env: { ...process.env, OHARNESS_SESSION: ctx.sessionId },
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let settled = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, timeoutMs);
+        const onAbort = () => child.kill("SIGKILL");
+        ctx.signal.addEventListener("abort", onAbort, { once: true });
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            ctx.signal.removeEventListener("abort", onAbort);
+            let newCwd;
+            const marker = stdout.lastIndexOf(sentinel);
+            if (marker !== -1) {
+                const end = stdout.indexOf("\n", marker);
+                const value = stdout.slice(marker + sentinel.length, end === -1 ? undefined : end).trim();
+                if (value)
+                    newCwd = path.resolve(value);
+                stdout = stdout.slice(0, marker).trimEnd();
+            }
+            resolve({ code, stdout, stderr, timedOut, newCwd });
+        };
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", (err) => {
+            stderr += `\n${String(err)}`;
+            finish(127);
+        });
+        child.on("close", (code) => finish(code));
+    });
+}
+export function bashResultText(result) {
+    return result.content.map((b) => (b.type === "text" ? b.text : "")).join("");
+}
+//# sourceMappingURL=bash.js.map

package/dist/tools/builtin/bash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash.js","sourceRoot":"","sources":["../../../src/tools/builtin/bash.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtin/fs.d.ts

@@ -0,0 +1,19 @@
+import type { ToolContext } from "../types.ts";
+/**
+ * Resolve a model-supplied path and keep it inside the roots the agent is
+ * allowed to touch.
+ *
+ * Defers to the host, which owns the workspace policy and therefore knows
+ * about roots beyond the working directory — the user-level skills directory
+ * the skill registry loads from, for one, which this used to refuse to read or
+ * write while the harness happily loaded skills out of it.
+ *
+ * The fallback is for a host without a policy: confine to the working
+ * directory, which is what this did unconditionally before.
+ */
+export declare function resolvePath(ctx: ToolContext, input: string, access?: "read" | "write"): string;
+export declare const readTool: import("../types.ts").Tool;
+export declare const writeTool: import("../types.ts").Tool;
+export declare const editTool: import("../types.ts").Tool;
+export declare const listTool: import("../types.ts").Tool;
+export declare const fileTools: import("../types.ts").Tool[];