humanish 0.0.1 → 0.15.0

package/dist/observer.js

@@ -0,0 +1,353 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { buildObserverData } from "./observer-data.js";
+import { observerClientJs, observerCss } from "./observer-assets.js";
+import { listRuns, loadRunBundle, verifyRun } from "./run.js";
+export const OBSERVER_SCHEMA = "humanish.observer-result.v1";
+const observerRuntimeStreamUrls = new WeakMap();
+export function attachObserverRuntimeStreamUrls(result, streams) {
+    observerRuntimeStreamUrls.set(result, streams.filter((stream) => stream.streamId && stream.url));
+}
+export async function renderObserver(cwdInput, runInput, options = {}) {
+    const cwd = path.resolve(cwdInput);
+    const verified = await verifyRun(cwd, runInput);
+    if (!verified.ok) {
+        return {
+            schema: OBSERVER_SCHEMA,
+            ok: false,
+            cwd,
+            run: runInput,
+            warnings: [],
+            error: {
+                code: verified.error?.code === "HUMANISH_RUN_NOT_FOUND" ? "HUMANISH_RUN_NOT_FOUND" : "HUMANISH_INVALID_RUN_BUNDLE",
+                message: verified.error?.message ?? "Run bundle failed verification."
+            }
+        };
+    }
+    const loaded = await loadRunBundle(cwd, runInput);
+    if (!loaded) {
+        return {
+            schema: OBSERVER_SCHEMA,
+            ok: false,
+            cwd,
+            run: runInput,
+            warnings: [],
+            error: {
+                code: "HUMANISH_RUN_NOT_FOUND",
+                message: `Run not found: ${runInput}`
+            }
+        };
+    }
+    const observerDir = path.join(loaded.runDir, "observer");
+    const observerPath = path.join(observerDir, "index.html");
+    const observerDataPath = path.join(observerDir, "observer-data.json");
+    const eventsPath = path.join(loaded.runDir, "events.ndjson");
+    const observerData = buildObserverData(loaded.bundle);
+    await mkdir(observerDir, { recursive: true });
+    await writeJson(observerDataPath, observerData);
+    await writeFile(observerPath, renderObserverHtml(observerData), "utf8");
+    const relativeObserverPath = path.relative(cwd, observerPath);
+    const observerUrl = pathToFileURL(observerPath).href;
+    const openResult = options.open === true ? openTarget(observerPath) : { opened: false };
+    return {
+        schema: OBSERVER_SCHEMA,
+        ok: true,
+        cwd,
+        run: loaded.bundle.runId,
+        observerPath: relativeObserverPath,
+        observerDataPath: path.relative(cwd, observerDataPath),
+        eventsPath: path.relative(cwd, eventsPath),
+        observerUrl,
+        bundlePath: loaded.bundlePath,
+        opened: openResult.opened,
+        ...(openResult.command ? { openCommand: openResult.command } : {}),
+        warnings: [
+            loaded.bundle.mode === "live"
+                ? "Observer renders verified local evidence artifacts; runtime stream auth URLs are not persisted."
+                : "Observer renders local contract evidence only; dry-run lanes do not claim product behavior proof.",
+            "Before filing public feedback, use `humanish feedback issue` so redaction and public-safety checks gate the payload.",
+            ...(openResult.warning ? [openResult.warning] : [])
+        ]
+    };
+}
+export async function serveObserver(result, options = {}) {
+    if (!result.ok || !result.observerPath) {
+        throw new Error("Cannot serve an observer result that did not render successfully.");
+    }
+    const cwd = path.resolve(result.cwd);
+    const observerPath = path.join(cwd, result.observerPath);
+    const runRoot = path.dirname(path.dirname(observerPath));
+    const proofRoot = path.dirname(runRoot);
+    const runtimeStreamUrls = () => observerRuntimeStreamUrls.get(result) ?? [];
+    const server = createServer(async (request, response) => {
+        try {
+            const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "127.0.0.1"}`);
+            if (url.pathname === "/") {
+                response.writeHead(302, { location: "/observer/index.html" });
+                response.end();
+                return;
+            }
+            if (url.pathname === "/_humanish/history.json") {
+                const history = await buildHistoryIndex(cwd);
+                writeResponse(response, 200, JSON.stringify(history, null, 2), "application/json; charset=utf-8");
+                return;
+            }
+            const runRoute = matchRunRoute(url.pathname);
+            if (runRoute) {
+                const targetRoot = path.join(proofRoot, runRoute.runId);
+                await serveRunPath(targetRoot, runRoute.relativePath || "observer/index.html", response, runtimeStreamUrls());
+                return;
+            }
+            await serveRunPath(runRoot, decodeURIComponent(url.pathname.slice(1)), response, runtimeStreamUrls());
+        }
+        catch (error) {
+            writeResponse(response, 500, error instanceof Error ? error.message : String(error), "text/plain; charset=utf-8");
+        }
+    });
+    const port = await listen(server, options.port ?? 0);
+    const url = `http://127.0.0.1:${port}/observer/index.html`;
+    const openResult = options.open === true ? openTarget(url) : { opened: false };
+    return {
+        url,
+        opened: openResult.opened,
+        ...(openResult.command ? { openCommand: openResult.command } : {}),
+        ...(openResult.warning ? { warning: openResult.warning } : {}),
+        close: () => closeServer(server)
+    };
+}
+function renderObserverHtml(data) {
+    return `<!doctype html>
+<html lang="en" data-theme="dark">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>Humanish Observer - ${escapeHtml(data.run.runId)}</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;450;500;600;700&family=Geist+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+<style>${observerCss()}</style>
+</head>
+<body>
+<div class="app" id="app" aria-label="Humanish Observer mission control">
+  <div class="boot" id="boot" aria-hidden="true"></div>
+</div>
+<noscript>This Observer renders local run evidence with JavaScript. Inspect the run bundle directly at <code>../run.json</code>.</noscript>
+<script id="observer-data" type="application/json">${escapeJsonScript(data)}</script>
+<script>${observerClientJs()}</script>
+</body>
+</html>
+`;
+}
+async function serveRunPath(runRoot, relativePath, response, runtimeStreamUrls = []) {
+    const root = path.resolve(runRoot);
+    const cleanedRelativePath = relativePath === "" ? "observer/index.html" : relativePath;
+    const filePath = path.resolve(root, cleanedRelativePath);
+    if (!isPathInside(root, filePath)) {
+        writeResponse(response, 403, "Forbidden", "text/plain; charset=utf-8");
+        return;
+    }
+    if (cleanedRelativePath === "observer/index.html") {
+        const observerData = await readObserverData(root, runtimeStreamUrls);
+        if (!observerData) {
+            writeResponse(response, 404, "Observer data not found", "text/plain; charset=utf-8");
+            return;
+        }
+        writeResponse(response, 200, renderObserverHtml(observerData), "text/html; charset=utf-8");
+        return;
+    }
+    if (cleanedRelativePath === "observer/observer-data.json") {
+        const observerData = await readObserverData(root, runtimeStreamUrls);
+        if (!observerData) {
+            writeResponse(response, 404, "Observer data not found", "text/plain; charset=utf-8");
+            return;
+        }
+        writeResponse(response, 200, JSON.stringify(observerData, null, 2), "application/json; charset=utf-8");
+        return;
+    }
+    try {
+        const body = await readFile(filePath);
+        response.writeHead(200, {
+            "cache-control": "no-store",
+            "content-type": contentTypeForPath(filePath)
+        });
+        response.end(body);
+    }
+    catch {
+        writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
+    }
+}
+async function readObserverData(runRoot, runtimeStreamUrls = []) {
+    // Best-effort load from either source. Both reads swallow all errors on
+    // purpose: this runs on every browser poll of a live run, where run.json may
+    // be absent, still being written (a partial-JSON parse error), or superseded
+    // by observer-data.json. A transient failure just falls through to the next
+    // source, or to null -> a 404 the poller retries; it must not surface a 500.
+    try {
+        const bundle = JSON.parse(await readFile(path.join(runRoot, "run.json"), "utf8"));
+        return withRuntimeStreamUrls(buildObserverData(bundle), runtimeStreamUrls);
+    }
+    catch { }
+    try {
+        return withRuntimeStreamUrls(JSON.parse(await readFile(path.join(runRoot, "observer", "observer-data.json"), "utf8")), runtimeStreamUrls);
+    }
+    catch { }
+    return null;
+}
+function withRuntimeStreamUrls(data, runtimeStreamUrls) {
+    if (runtimeStreamUrls.length === 0) {
+        return data;
+    }
+    const urlsByStream = new Map(runtimeStreamUrls.map((stream) => [stream.streamId, stream.url]));
+    return {
+        ...data,
+        streams: data.streams.map((stream) => {
+            const runtimeUrl = urlsByStream.get(stream.id);
+            if (!runtimeUrl) {
+                return stream;
+            }
+            return {
+                ...stream,
+                embed: {
+                    ...(stream.embed ?? { title: stream.label }),
+                    kind: "iframe",
+                    url: runtimeUrl
+                },
+                transport: "sse",
+                url: runtimeUrl
+            };
+        })
+    };
+}
+async function buildHistoryIndex(cwd) {
+    const listed = await listRuns(cwd);
+    const runs = await Promise.all(listed.runs.slice(0, 80).map(async (run) => {
+        const root = path.join(cwd, run.path);
+        const data = await readObserverData(root);
+        return {
+            runId: run.runId,
+            createdAt: run.createdAt,
+            mode: run.mode,
+            href: `/_humanish/runs/${encodeURIComponent(run.runId)}/observer/index.html`,
+            status: data?.run.status ?? "unknown",
+            streamCount: data?.streams.length ?? 0
+        };
+    }));
+    return { latestRunId: listed.latest, runs };
+}
+function matchRunRoute(pathname) {
+    const match = pathname.match(/^\/_humanish\/runs\/([^/]+)(?:\/(.*))?$/);
+    if (!match)
+        return null;
+    return {
+        runId: decodeURIComponent(match[1] ?? ""),
+        relativePath: decodeURIComponent(match[2] || "observer/index.html")
+    };
+}
+function writeJson(filePath, value) {
+    return writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+function writeResponse(response, status, body, contentType) {
+    response.writeHead(status, {
+        "cache-control": "no-store",
+        "content-type": contentType
+    });
+    response.end(body);
+}
+function contentTypeForPath(filePath) {
+    switch (path.extname(filePath)) {
+        case ".html":
+            return "text/html; charset=utf-8";
+        case ".json":
+            return "application/json; charset=utf-8";
+        case ".md":
+            return "text/markdown; charset=utf-8";
+        case ".ndjson":
+            return "application/x-ndjson; charset=utf-8";
+        case ".png":
+            return "image/png";
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".webp":
+            return "image/webp";
+        default:
+            return "text/plain; charset=utf-8";
+    }
+}
+export function openTarget(target) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", target] : [target];
+    try {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: "ignore"
+        });
+        child.unref();
+        return { opened: true, command: [command, ...args].join(" ") };
+    }
+    catch (error) {
+        return {
+            opened: false,
+            command: [command, ...args].join(" "),
+            warning: `Could not open observer automatically: ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+}
+function listen(server, port) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", () => {
+            server.off("error", reject);
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                reject(new Error("Observer server did not bind to a TCP port."));
+                return;
+            }
+            resolve(address.port);
+        });
+    });
+}
+function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve();
+            }
+        });
+    });
+}
+function isPathInside(root, filePath) {
+    const relative = path.relative(root, filePath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => {
+        switch (char) {
+            case "&":
+                return "&amp;";
+            case "<":
+                return "&lt;";
+            case ">":
+                return "&gt;";
+            case "\"":
+                return "&quot;";
+            default:
+                return "&#39;";
+        }
+    });
+}
+function escapeJsonScript(value) {
+    return JSON.stringify(value)
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/&/g, "\\u0026")
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}
+//# sourceMappingURL=observer.js.map

package/dist/observer.js.map

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

package/dist/openai-responses-cu.d.ts

@@ -0,0 +1,113 @@
+import type { ActorCapabilities } from "./actor-contract.js";
+import type { CuaAction, CuaProvider, CuaSafetyCheck, CuaTurn } from "./computer-use.js";
+export declare const OPENAI_RESPONSES_CU_CAPABILITIES: ActorCapabilities;
+export declare const DEFAULT_OPENAI_CU_MODEL = "gpt-5.5";
+/**
+ * Map an OpenAI computer action object to a provider-neutral CuaAction, or null
+ * for an unknown type. Every coordinate and field is read defensively so a
+ * malformed action never throws and a non-number coordinate becomes 0.
+ */
+export declare function openAiActionToCua(action: unknown): CuaAction | null;
+export interface ParsedOpenAiResponse {
+    turn: CuaTurn;
+    callIds: string[];
+    outputItems: unknown[];
+}
+/**
+ * Parse a Responses API response into a provider-neutral CuaTurn plus the
+ * computer_call ids (needed to build the next turn's call outputs) and the raw
+ * output items (needed for ZDR explicit-context continuation). Pure: no network,
+ * no mutation of the input. Optional CuaTurn fields are only set when present so
+ * the result satisfies exactOptionalPropertyTypes.
+ */
+export declare function parseOpenAiResponse(raw: unknown): ParsedOpenAiResponse;
+export interface OpenAiCuContext {
+    model: string;
+    instructions: string;
+    reasoningEffort: "low" | "medium" | "high";
+    safetyIdentifier?: string;
+}
+/** Build the first-turn request body: instructions + an initial user text input. */
+export declare function buildInitialRequest(ctx: OpenAiCuContext): Record<string, unknown>;
+/**
+ * Build one computer_call_output for a pending call id, carrying the latest
+ * screenshot as an inline data URL. Acknowledged safety checks (if any) are
+ * echoed back so the model can proceed past a check the harness approved.
+ *
+ * The screenshot param is `Buffer | undefined` because CuaObservation.screenshot is now
+ * optional (a non-vision executor omits it). This provider is a VISION model (it sets
+ * requiresFrame), so a missing frame is a hard error here — defense-in-depth: the loop's
+ * per-turn requiresFrame guard already fails closed before this is reached, but throwing keeps
+ * the mapper self-validating and isolable.
+ */
+export declare function buildCallOutput(callId: string, screenshot: Buffer | undefined, acknowledged?: CuaSafetyCheck[]): Record<string, unknown>;
+export interface ContinuationRequestArgs {
+    ctx: OpenAiCuContext;
+    previousResponseId: string | undefined;
+    callOutputs: object[];
+    contextHint?: string;
+    explicitContextItems?: unknown[];
+}
+/**
+ * Build a continuation request body. Two modes:
+ *  - default: thread server-side state via previous_response_id and send only the
+ *    new call outputs (plus an optional hint).
+ *  - explicit-context (ZDR): no previous_response_id; the prior output items are
+ *    re-sent inline ahead of the new call outputs so the model has full context
+ *    without the server retaining any.
+ */
+export declare function buildContinuationRequest(args: ContinuationRequestArgs): Record<string, unknown>;
+/** The opt-in gate for response wire capture: a directory path, or unset for off. */
+export declare const WIRE_CAPTURE_ENV = "HUMANISH_CUA_WIRE_CAPTURE_DIR";
+/**
+ * Deep-copy a captured wire value with every string — object keys included —
+ * passed through the shared redactText, so a secret-shaped echo in a response
+ * can never persist to disk. Pure; non-string primitives pass through unchanged.
+ */
+export declare function redactWireJson(value: unknown): unknown;
+/** Deterministic ordered capture file name for the 1-based nth provider call. */
+export declare function wireCaptureFileName(callNumber: number): string;
+/**
+ * The minimal slice of the fetch contract the shim depends on. Injecting this
+ * (rather than importing a fetch type) keeps the module dependency-free and lets
+ * CI tests run with a fake that never touches the network.
+ */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}>;
+export interface OpenAiResponsesProviderOptions {
+    apiKey: string;
+    model?: string;
+    reasoningEffort?: "low" | "medium" | "high";
+    safetyIdentifier?: string;
+    endpoint?: string;
+    fetchFn?: FetchLike;
+    maxRetries?: number;
+    delayFn?: (ms: number) => Promise<void>;
+    zeroDataRetention?: boolean;
+    /**
+     * Environment for the wire-capture gate (HUMANISH_CUA_WIRE_CAPTURE_DIR — see the
+     * module header). Injectable so deterministic tests control the gate without
+     * mutating process.env. Defaults to process.env.
+     */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Create a stateful CuaProvider backed by the OpenAI Responses API. The first
+ * turn opens a session (buildInitialRequest); subsequent turns send the prior
+ * call outputs (with the latest screenshot) and thread state via
+ * previous_response_id, transparently falling back to explicit-context mode if
+ * the account rejects server-side retention. Transient HTTP failures are retried
+ * with exponential backoff. Returns ONLY a CuaTurn from nextTurn; nothing
+ * sensitive (the key, the request body, the screenshot, the raw response body)
+ * is ever returned or logged.
+ */
+export declare function createOpenAiResponsesProvider(options: OpenAiResponsesProviderOptions): CuaProvider;