@oharness/engine 0.1.0

package/dist/util/schema.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+/** Convert a zod schema to a JSON Schema object suitable for tool definitions. */
+export function zodToJsonSchema(schema) {
+    const raw = z.toJSONSchema(schema, { target: "draft-7", io: "input" });
+    return normalizeObjectSchema(raw);
+}
+/**
+ * Every provider expects a top-level object schema for tool inputs, and every
+ * provider chokes on `$schema`/`$id` at the top level of a function parameter.
+ */
+export function normalizeObjectSchema(schema) {
+    const { $schema, $id, ...rest } = schema;
+    void $schema;
+    void $id;
+    if (rest["type"] === undefined && rest["properties"] === undefined) {
+        return { type: "object", properties: {}, ...rest };
+    }
+    if (rest["type"] === "object" && rest["properties"] === undefined) {
+        rest["properties"] = {};
+    }
+    return rest;
+}
+/**
+ * Gemini accepts only a subset of OpenAPI 3.0 schema. Strip what it rejects
+ * rather than letting the request 400.
+ */
+const GEMINI_ALLOWED = new Set([
+    "type",
+    "format",
+    "description",
+    "nullable",
+    "enum",
+    "maxItems",
+    "minItems",
+    "properties",
+    "required",
+    "items",
+    "anyOf",
+    "propertyOrdering",
+]);
+export function sanitizeForGemini(schema) {
+    return walk(schema);
+    function walk(node) {
+        if (Array.isArray(node))
+            return node.map(walk);
+        if (node === null || typeof node !== "object")
+            return node;
+        const src = node;
+        const out = {};
+        // `oneOf`/`allOf` are unsupported; the closest legal construct is anyOf.
+        const union = src["oneOf"] ?? src["allOf"];
+        if (union && !src["anyOf"])
+            out["anyOf"] = walk(union);
+        for (const [key, value] of Object.entries(src)) {
+            if (!GEMINI_ALLOWED.has(key))
+                continue;
+            if (key === "properties" && value && typeof value === "object") {
+                const props = {};
+                for (const [pk, pv] of Object.entries(value)) {
+                    props[pk] = walk(pv);
+                }
+                out["properties"] = props;
+                continue;
+            }
+            out[key] = walk(value);
+        }
+        // Gemini requires `type` on object nodes that declare properties.
+        if (out["properties"] && !out["type"])
+            out["type"] = "object";
+        if (out["items"] && !out["type"])
+            out["type"] = "array";
+        return out;
+    }
+}
+/**
+ * OpenAI strict function calling requires `additionalProperties: false` and
+ * every property listed in `required`. We only apply it when asked, because it
+ * also forbids optional fields.
+ */
+export function toStrictOpenAiSchema(schema) {
+    return walk(schema);
+    function walk(node) {
+        if (Array.isArray(node))
+            return node.map(walk);
+        if (node === null || typeof node !== "object")
+            return node;
+        const src = node;
+        const out = {};
+        for (const [key, value] of Object.entries(src))
+            out[key] = walk(value);
+        if (out["type"] === "object" && out["properties"]) {
+            out["additionalProperties"] = false;
+            out["required"] = Object.keys(out["properties"]);
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/util/schema.js.map

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

package/dist/util/shell.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Which shell to run a command string through.
+ *
+ * The harness hands the model's command to a shell rather than parsing it
+ * itself — pipes, redirects and quoting are the model's to use. That means
+ * picking a shell per platform: `bash -c` simply does not exist on a stock
+ * Windows install, so every shell-backed feature was silently unavailable
+ * there.
+ */
+export interface ShellCommand {
+    command: string;
+    args: string[];
+}
+/**
+ * `SHELL` is honoured on POSIX so a user on zsh/fish gets their own
+ * environment; `ComSpec` is the Windows equivalent.
+ */
+export declare function shellFor(script: string): ShellCommand;
+/** True when the platform's shell is cmd.exe rather than a POSIX shell. */
+export declare function isWindowsShell(): boolean;

package/dist/util/shell.js

@@ -0,0 +1,24 @@
+/**
+ * `SHELL` is honoured on POSIX so a user on zsh/fish gets their own
+ * environment; `ComSpec` is the Windows equivalent.
+ */
+export function shellFor(script) {
+    if (process.platform === "win32") {
+        const comspec = process.env["ComSpec"] ?? "cmd.exe";
+        // PowerShell needs a different invocation than cmd, and `-Command` is the
+        // only form that accepts a full script string.
+        if (/powershell|pwsh/i.test(comspec)) {
+            return { command: comspec, args: ["-NoProfile", "-Command", script] };
+        }
+        return { command: comspec, args: ["/d", "/s", "/c", script] };
+    }
+    const shell = process.env["SHELL"];
+    // Fall back to bash rather than sh: the tool descriptions promise bash
+    // syntax, and a login shell may be something that cannot run it.
+    return { command: shell && shell.trim() !== "" ? shell : "/bin/bash", args: ["-c", script] };
+}
+/** True when the platform's shell is cmd.exe rather than a POSIX shell. */
+export function isWindowsShell() {
+    return process.platform === "win32" && !/powershell|pwsh/i.test(process.env["ComSpec"] ?? "");
+}
+//# sourceMappingURL=shell.js.map

package/dist/util/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/util/shell.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc;IACrC,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC;QACpD,0EAA0E;QAC1E,+CAA+C;QAC/C,IAAI,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACrC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,YAAY,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,CAAC;QACxE,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;IAChE,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACnC,uEAAuE;IACvE,iEAAiE;IACjE,OAAO,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;AAC/F,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,cAAc;IAC5B,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;AAChG,CAAC"}

package/official.json

@@ -0,0 +1,4 @@
+{
+  "supabaseUrl": "https://xuqupogshrptlyrbcgne.supabase.co",
+  "supabaseAnonKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Inh1cXVwb2dzaHJwdGx5cmJjZ25lIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NDI2MzY3ODEsImV4cCI6MjA1ODIxMjc4MX0.aSmArTFk0hgMdaueEULtceSzCKfC8mOSLNhNSeLojUo"
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@oharness/engine",
+  "version": "0.1.0",
+  "description": "The agent loop, tool execution, context management and permissions. No frontend, no transport.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "oharness-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.ts": {
+      "oharness-source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "official.json"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/providers/catalog.json dist/providers/catalog.json && cp src/mcp/registry.json dist/mcp/registry.json",
+    "prepack": "node scripts/write-official.mjs",
+    "postpack": "node scripts/write-official.mjs --clean"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.84.3",
+    "zod": "^4.1.5"
+  }
+}

package/skills/artifact-authoring/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: artifact-authoring
+description: Making and revising artifacts — which kind to use, what an HTML artifact is allowed to contain, and when writing a file is the better answer.
+---
+
+# Authoring artifacts
+
+An artifact is something the user **looks at**: a chart, a rendered page, a
+document being iterated on. It is not a file. If the thing you are making is
+source code, a config, or anything the user will keep and edit, use `write` —
+artifacts live in memory and disappear when the process does.
+
+## The one rule that will otherwise waste a turn
+
+**An HTML artifact must be a single self-contained file.** It is served into a
+sandbox whose policy is `default-src 'none'`, so:
+
+- `<script src="https://cdn…">` — **blocked**. React, Vue, Tailwind, Chart.js,
+  D3 or anything else from a CDN will not load, and the page renders blank.
+- `<link rel="stylesheet" href="https://…">` — **blocked**. So are remote
+  fonts and remote images.
+- `fetch()`, `XMLHttpRequest`, `WebSocket` — **blocked**. An artifact cannot
+  reach the network, including the harness that served it.
+- JSX/TSX — there is no build step, and the usual workaround (Babel from a CDN)
+  is blocked by the first rule.
+
+Nothing warns you when this happens. The artifact stores fine, publishes fine,
+and shows an empty rectangle.
+
+What *does* work, and is enough for most things worth looking at:
+
+- Inline `<style>` and inline `<script>` — both run.
+- Plain DOM, canvas, SVG, CSS animation, CSS grid.
+- `data:` URIs for images and fonts.
+- Any data the page needs, written into the file as a literal.
+
+Draw charts by emitting SVG or by drawing to a `<canvas>` in inline script.
+That is a few dozen lines, and it always renders.
+
+## Canvases
+
+`text/canvas+html` makes a board of artboards the user can select, edit and save
+back. It has enough rules of its own to be its own skill — read **canvas**
+before writing one.
+
+## Choosing a kind
+
+Set `mime` to match what you actually wrote:
+
+| You are making | `mime` |
+| --- | --- |
+| A layout the user will want to nudge by hand | `text/canvas+html` (see the canvas skill) |
+| A rendered page or interactive widget | `text/html` |
+| A diagram or chart with no interaction | `image/svg+xml` |
+| Prose, a report, notes | `text/markdown` |
+| Data or source to be read, not run | `application/json`, `text/plain` |
+
+Prefer `image/svg+xml` over `text/html` when nothing needs to be clickable: it
+renders everywhere, including places an HTML artifact only gets a summary line.
+
+## Revising
+
+Reuse the same `id` to revise. That keeps one artifact with a version history
+rather than filling the panel with near-duplicates, and it keeps any link that
+was already shared pointing at the same place.
+
+Send the **complete** new content every time — there is no patching.
+
+Choose an id that describes the thing (`sales-chart`, `onboarding-flow`), not
+the moment (`chart-v2`, `chart-final`). The version number is kept for you.
+
+## What publishing does
+
+Publishing copies the artifact to the website and returns a URL. Two things
+follow that are worth telling the user:
+
+- The link serves the revision that was **published**, not the latest one.
+  Revise five times without republishing and the recipient still sees the
+  first. The panel shows this, and offers to update the link.
+- Publishing needs an account, and the content leaves the machine. Do not
+  publish anything containing credentials, private paths, or customer data.

package/skills/canvas/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: canvas
+description: Create a canvas: a pan/zoom board of `<artboard>` blocks the user can select, edit and save back as their own revision. Use for mockups, screen flows, dashboards, landing pages, posters — any layout better nudged by hand. Write only the artboards; the editor is the harness's.
+---
+
+# Canvases
+
+A canvas is the one artifact the user can edit back. Write it with
+`artifact_write` and `mime: text/canvas+html`.
+
+## Write the artboards, nothing else
+
+The stage, the zoom, the selection outline, the properties panel, undo and Save
+all come from the harness. You supply an optional `<style>` and a list of
+artboards — no `<html>`, no `<head>`, no viewport, no pan/zoom code. Writing
+your own editor means two editors fighting over the same clicks, and it costs
+you the whole artifact size budget.
+
+```html
+<style>
+  .screen { font: 15px/1.5 ui-sans-serif, system-ui, sans-serif; padding: 24px; }
+  .screen h2 { margin: 0 0 8px; font-size: 22px; }
+  .muted { color: #71717a; }
+</style>
+
+<artboard title="Empty state" width="390" height="600">
+  <div class="screen">
+    <h2>No projects yet</h2>
+    <p class="muted">Create one to get started.</p>
+  </div>
+</artboard>
+
+<artboard title="With projects" width="390" height="600">
+  <div class="screen">
+    <h2>Projects</h2>
+    <p class="muted">3 active</p>
+  </div>
+</artboard>
+```
+
+- `title`, `width` and `height` are the only attributes that mean anything.
+  Position is not one of them: boards are packed and wrapped for you, in the
+  order you wrote them. Put related states next to each other.
+- The leading `<style>` is shared by every board and survives every save.
+  **Style your own classes.** A `*` or a bare `h2` selector reaches inside every
+  artboard at once — occasionally what you want, usually a surprise.
+- Everything in [artifact-authoring](../artifact-authoring/SKILL.md) still
+  applies: one self-contained document, no CDN, no fetch, `data:` URIs for
+  images.
+
+## Sizes worth reaching for
+
+| Artboard | width x height |
+| --- | --- |
+| Phone screen | 390 x 844, or 390 x 600 for a crop |
+| Tablet | 834 x 1112 |
+| Desktop app or landing page | 1440 x 1024 |
+| Poster / flyer (A4 at 96dpi) | 794 x 1123 |
+| Social card | 1200 x 630 |
+
+A flow is one artboard per state. A document is one tall artboard, not five
+stacked ones.
+
+## What happens after you hand it over
+
+**Their edits are real revisions.** A save writes a new version authored by
+them, on top of yours. Revising the same id afterwards replaces what they
+changed — nothing is lost, the earlier version is still in the history, and the
+tool receipt tells you when it has just happened. When it does: say so, read
+the version back with `artifact_read`, and fold their changes in rather than
+silently reverting them.
+
+**Saving needs a frontend that offers it.** A canvas opened in its own tab, or
+published to the website, still pans and zooms but has no Save — there is no
+session behind it to write a revision to. It is a fine thing to share, and a
+poor place to ask someone to make changes.
+
+## When not to reach for this
+
+- The thing must *run* — a working widget, a simulation, a chart with
+  interaction. That is a `text/html` artifact.
+- Nothing needs to be clickable and nobody will nudge it. An `image/svg+xml`
+  artifact renders in more places, including ones a canvas only gets a summary
+  line in.
+- The user will keep and edit the result as a file. Use `write`.

package/skills/skill-authoring/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: skill-authoring
+description: Writing a SKILL.md — the frontmatter, where skills are discovered, and what makes a description one that actually gets matched.
+---
+
+# Writing a skill
+
+A skill is packaged instructions loaded on demand. Its **description** sits in
+the system prompt of every request; its **body** is only loaded when a task
+matches. That split is the whole point, and it drives every rule below.
+
+## The file
+
+One directory, one `SKILL.md`:
+
+```
+my-skill/
+  SKILL.md
+  scripts/check.py      ← optional, referenced from the body by relative path
+  reference/api.md
+```
+
+```markdown
+---
+name: my-skill
+description: One line. This is the only thing seen before the skill is loaded.
+---
+
+# My skill
+
+The instructions.
+```
+
+`description` is required — a skill without one can never be selected, and is
+skipped with a warning. `name` defaults to the directory name.
+
+Relative paths in the body resolve against the skill's own directory, and the
+files in it are listed when the skill loads, so `run scripts/check.py` is a
+usable instruction rather than a dead reference.
+
+## Where they go
+
+| Location | Scope |
+| --- | --- |
+| `<project>/.oharness/skills/` | This repository. Overrides the two below. |
+| `~/.oharness/skills/` | This user, every project. |
+| shipped with the harness | Built-in. Overridden by either of the above. |
+
+Same name in two places: the more specific one wins. That is how a repository
+pins its own version of a skill without anyone editing a global file.
+
+Writing a `SKILL.md` into one of those directories registers it **immediately**
+— there is no restart. Authoring a skill for yourself mid-task and then using
+it in the same session works.
+
+## Writing a description that gets matched
+
+This is where most skills fail. The description is matched against a task
+before anything else is known, so it has to name the situation, not the skill.
+
+- **Weak:** "Helper for deployments." — matches nothing in particular.
+- **Better:** "Deploying to Railway: which service takes which variables, and
+  the migration order that avoids downtime."
+
+Name the concrete nouns someone would use for the task. Avoid "helps you",
+"utilities for", and anything that describes the file rather than the job.
+
+## Writing the body
+
+Write it for someone competent who has not seen this system. That means:
+
+- Say **why**, not only what. A rule with a reason survives a refactor; a bare
+  instruction gets dropped the first time it is inconvenient.
+- Put the thing that will otherwise be got wrong at the top, not in a section
+  near the end.
+- Prefer a short table over a long list of prose alternatives.
+- Do not restate what any competent model already knows. Every line you add is
+  read on every use of the skill; earn it.
+
+## When *not* to write a skill
+
+If the knowledge is a hard constraint that must always hold — an API that will
+reject a call, a policy that will block a write — it belongs in the relevant
+tool's description, not a skill. Skills are opt-in and may not be installed;
+a tool description is seen every time.