@xingular/harness 0.1.7 → 1.0.0

package/dist/sdk/capabilities/runSnapshot.js

@@ -0,0 +1,47 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { HarnessError, invalid } from "../core/errors.js";
+import { readJson, safeId, writeJson } from "../core/fs.js";
+const path = (root, runId) => join(root, 'runs', safeId(runId), 'capabilities.json');
+function strings(value) {
+    return Array.isArray(value) ? [...new Set(value.filter((item) => typeof item === 'string' && item.length > 0))] : [];
+}
+export function capabilitySet(value) {
+    if (!value || typeof value !== 'object' || value.version !== 1)
+        throw invalid('A capability set must use version 1.');
+    const record = value;
+    return { version: 1, tools: strings(record.tools), connectors: strings(record.connectors), contributions: strings(record.contributions) };
+}
+/** Writes a run's capability set once. A resumed or duplicate launch cannot replace it. */
+export function freezeRun(root, runId, caller, set) {
+    const target = path(root, runId);
+    const snapshot = {
+        version: 1,
+        caller: { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null },
+        tools: strings(set.tools),
+        connectors: strings(set.connectors),
+        contributions: strings(set.contributions)
+    };
+    const existing = existsSync(target) ? readJson(target) : null;
+    if (existing) {
+        if (JSON.stringify(existing) !== JSON.stringify(snapshot))
+            throw new HarnessError('capabilities_frozen', 'This run already has a different frozen capability set.');
+        return existing;
+    }
+    writeJson(target, snapshot);
+    return snapshot;
+}
+export function loadRun(root, runId) {
+    const stored = readJson(path(root, runId));
+    if (!stored || typeof stored !== 'object' || stored.version !== 1)
+        return null;
+    const record = stored;
+    const caller = record.caller && typeof record.caller === 'object' ? record.caller : {};
+    return {
+        version: 1,
+        caller: { agentId: typeof caller.agentId === 'string' ? caller.agentId : null, projectId: typeof caller.projectId === 'string' ? caller.projectId : null },
+        tools: strings(record.tools),
+        connectors: strings(record.connectors),
+        contributions: strings(record.contributions)
+    };
+}

package/dist/sdk/capabilities/types.d.ts

@@ -0,0 +1,29 @@
+import type { AttachScope, Attachment } from "../plugins/attachments.js";
+import type { ContributionKind, ContributionState, PluginSource } from "../plugins/types.js";
+export type CapabilityKind = ContributionKind | 'plugin';
+/** One item the caller can switch on or off, or that a plugin makes available. */
+export interface Capability {
+    id: string;
+    pluginId: string;
+    kind: CapabilityKind;
+    name: string;
+    description: string;
+    source: PluginSource;
+    state: ContributionState;
+    attachment: Attachment | null;
+}
+export interface CapabilityCatalogue {
+    plugins: import("../plugins/types.js").Plugin[];
+    capabilities: Capability[];
+}
+/** The callable capabilities a run starts with. Permission to run still goes through the gate. */
+export interface CapabilitySet {
+    version: 1;
+    tools: string[];
+    connectors: string[];
+    contributions: string[];
+}
+export interface CapabilityScope extends AttachScope {
+    cwd?: string | null;
+    accountId?: string | null;
+}

package/dist/sdk/capabilities/types.js

@@ -0,0 +1 @@
+export {};

package/dist/sdk/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/sdk/cli.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// The `xharness` command.
+//
+//   xharness serve --state <dir> [--data <dir>] [--name <product>] [--builtins <dir>]…
+//                  [--host-secrets] [--host-policy] [--host-tools] [--host-directory]
+//       Serves the harness to a host process over stdin/stdout (newline-delimited JSON).
+//   xharness wiki <command>     Project notes, skills and history, from inside a terminal session.
+//   xharness refine <command>   Refine a variant from evidence (refine demo needs no model).
+//   xharness mcp <command>      Connected apps, from inside a terminal session.
+//   xharness plugins <command>  List, install, switch and trust plugins.
+//   xharness web <command>      Search keys for web_search.
+//   xharness browser <command>  How the agent's browser runs.
+import { resolve } from 'node:path';
+import manifest from "../../package.json" with { type: 'json' };
+import { log } from "./core/bus.js";
+import { createHarness } from "./harness.js";
+import { runPluginsCli, terminalAsk } from "./plugins/cli.js";
+import { runHubCli } from "./hub/cli.js";
+import { runRefineCli } from "./refine/cli.js";
+import { runBrowserCli, runWebCli } from "./world/cli.js";
+import { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from "./server/remote.js";
+import { RpcPeer, stdioTransport } from "./server/rpc.js";
+import { attach } from "./server/serve.js";
+import { runAppsCli, runWikiCli } from "./terminal/cli.js";
+import { runStandaloneTerminal, standaloneArguments } from "./terminal/standalone.js";
+const USAGE = `Usage: xharness [--data <dir>] [--state <dir>]
+       xharness <terminal | serve | wiki | mcp | plugins | hub | refine | web | browser> [arguments]
+
+  --version          Print the package version
+  (no command)       Start the interactive Harness terminal
+  terminal           Start the interactive Harness terminal
+  serve --state <dir> [--data <dir>] [--name <product>] [--builtins <dir>]
+        [--host-secrets] [--host-policy] [--host-tools] [--host-directory]
+                     Serve the harness over newline-delimited JSON
+  wiki <command>     Wiki, skill and history commands for a terminal session
+  mcp <command>      Connected-app commands for a terminal session
+  plugins <command>  List, install, switch and trust plugins (plugins help)
+  hub <command>      Browse and install curated items (hub help)
+  refine <command>   Refine a harness from evidence (refine demo, refine run)
+  web <command>      Search keys for the web tools (web help)
+  browser <command>  How the agent's browser runs (browser help)
+
+Standalone terminal options:
+  --data <dir>       Data directory (installed default: ~/.xingular-harness/data;
+                     npm run dev default: ~/.xingular-harness-dev/data)
+  --state <dir>      State directory (installed default: ~/.xingular-harness/state;
+                     npm run dev default: ~/.xingular-harness-dev/state)
+`;
+function flags(argv) {
+    const values = {};
+    const switches = new Set();
+    for (let index = 0; index < argv.length; index += 1) {
+        const name = argv[index];
+        if (!name.startsWith('--'))
+            continue;
+        const next = argv[index + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            ;
+            (values[name.slice(2)] ??= []).push(next);
+            index += 1;
+        }
+        else
+            switches.add(name.slice(2));
+    }
+    return { values, switches };
+}
+function serveCommand(argv) {
+    const { values, switches } = flags(argv);
+    const stateArgument = values.state?.[0];
+    if (!stateArgument) {
+        process.stderr.write('serve needs --state <dir>.\n');
+        return Promise.resolve(2);
+    }
+    // The socket path is built from this folder, so a relative one would depend on where the host ran.
+    const stateDir = resolve(stateArgument);
+    const peer = new RpcPeer(stdioTransport());
+    const options = {
+        stateDir,
+        dataRoot: values.data?.[0] ? resolve(values.data[0]) : null,
+        productName: values.name?.[0],
+        builtins: values.builtins,
+        ...(switches.has('host-secrets') ? { secrets: remoteSecrets(peer) } : {}),
+        ...(switches.has('host-policy') ? { policy: remotePolicy(peer) } : {}),
+        ...(switches.has('host-directory') ? { directory: remoteDirectory(peer) } : {})
+    };
+    const harness = createHarness(options);
+    if (switches.has('host-tools'))
+        harness.sessions.provide(remoteTools(peer));
+    attach(harness, peer);
+    return new Promise((resolve) => {
+        let closing = false;
+        const shutdown = () => {
+            if (closing)
+                return;
+            closing = true;
+            void Promise.race([harness.close(), new Promise((done) => setTimeout(done, 5000))]).then(() => resolve(0));
+        };
+        peer.handle('harness.shutdown', () => void setImmediate(shutdown));
+        process.stdin.on('end', shutdown);
+        process.on('SIGTERM', shutdown);
+        process.on('SIGINT', shutdown);
+        peer.send({ notice: { type: 'ready' } });
+        log('ready');
+    });
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-v')) {
+        process.stdout.write(`${manifest.version}\n`);
+        return 0;
+    }
+    const [command, ...rest] = argv;
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    const terminalArgs = standaloneArguments(argv);
+    if (terminalArgs !== null)
+        return runStandaloneTerminal(terminalArgs);
+    if (command === 'serve')
+        return serveCommand(rest);
+    if (command === 'wiki')
+        return runWikiCli(rest);
+    if (command === 'mcp')
+        return runAppsCli(rest);
+    if (command === 'plugins')
+        return runPluginsCli(rest, { ask: terminalAsk() });
+    if (command === 'hub')
+        return runHubCli(rest);
+    if (command === 'refine')
+        return runRefineCli(rest);
+    if (command === 'web')
+        return runWebCli(rest);
+    if (command === 'browser')
+        return runBrowserCli(rest);
+    process.stdout.write(USAGE);
+    return command ? 2 : 0;
+}
+void main().then((code) => process.exit(code), (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/sdk/core/bus.d.ts

@@ -0,0 +1,23 @@
+export interface Notice {
+    /** `accounts.changed`, `accounts.login`, `accounts.loginEvent`, `wiki.changed`, `wiki.maintenance`, … */
+    type: string;
+    [key: string]: unknown;
+}
+export type NoticeListener = (notice: Notice) => void;
+export declare class Bus {
+    private readonly listeners;
+    on(listener: NoticeListener): () => void;
+    emit(notice: Notice): void;
+}
+/**
+ * Sends diagnostics somewhere other than stderr, or back to stderr with `null`. A host whose stderr is
+ * the terminal a frontend is drawing on must not write into it, so it sets a sink.
+ */
+export declare function setLogSink(sink: ((text: string) => void) | null): void;
+/** One line of diagnostics. Diagnostics go to stderr by default; stdout may be carrying a protocol. */
+export declare function logLine(text: string): void;
+/** Redacts common credentials and URL query values before diagnostic text is persisted or shown. */
+export declare function redactLogText(text: string): string;
+/** Records useful failure detail without persisting credentials or response bodies. */
+export declare function logDiagnostic(scope: string, error: unknown, metadata?: Record<string, unknown>): void;
+export declare function log(...parts: unknown[]): void;

package/dist/sdk/core/bus.js

@@ -0,0 +1,76 @@
+// Notices: what the harness tells whoever embeds it. Run events travel separately, through the
+// run tracker; a notice says that some state changed and should be read again.
+export class Bus {
+    listeners = new Set();
+    on(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    emit(notice) {
+        for (const listener of this.listeners) {
+            try {
+                listener(notice);
+            }
+            catch (error) {
+                log('a notice listener failed', error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+}
+let logSink = null;
+/**
+ * Sends diagnostics somewhere other than stderr, or back to stderr with `null`. A host whose stderr is
+ * the terminal a frontend is drawing on must not write into it, so it sets a sink.
+ */
+export function setLogSink(sink) {
+    logSink = sink;
+}
+/** One line of diagnostics. Diagnostics go to stderr by default; stdout may be carrying a protocol. */
+export function logLine(text) {
+    if (logSink)
+        logSink(text);
+    else
+        process.stderr.write(`${text}\n`);
+}
+/** Redacts common credentials and URL query values before diagnostic text is persisted or shown. */
+export function redactLogText(text) {
+    return text
+        .replace(/\bBearer\s+\S+/gi, 'Bearer [redacted]')
+        .replace(/(["']?(?:authorization|proxy-authorization|cookie|set-cookie|x-[\w-]*(?:token|key)|[\w-]*(?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|token|secret|password|client[_-]?secret))["']?\s*[:=]\s*["']?)[^"'\s,;]+/gi, '$1[redacted]')
+        .replace(/\b(?:sk|sess)-[A-Za-z0-9_-]{16,}\b/gi, '[redacted]')
+        .replace(/\bhttps?:\/\/[^\s"'<>]+/gi, (raw) => {
+        const punctuation = /[),.;!?]+$/.exec(raw)?.[0] ?? '';
+        const address = punctuation ? raw.slice(0, -punctuation.length) : raw;
+        try {
+            const url = new URL(address);
+            url.username = '';
+            url.password = '';
+            url.search = '';
+            url.hash = '';
+            return `${url.href}${punctuation}`;
+        }
+        catch {
+            return raw;
+        }
+    });
+}
+/** Records useful failure detail without persisting credentials or response bodies. */
+export function logDiagnostic(scope, error, metadata = {}) {
+    const failure = error instanceof Error ? error : new Error(String(error));
+    const details = {
+        ...metadata,
+        message: failure.message,
+        ...(failure.stack ? { stack: failure.stack } : {})
+    };
+    let serialized;
+    try {
+        serialized = JSON.stringify(details);
+    }
+    catch {
+        serialized = JSON.stringify({ message: failure.message, stack: failure.stack });
+    }
+    logLine(`[harness] ${redactLogText(scope)} ${redactLogText(serialized)}`);
+}
+export function log(...parts) {
+    logLine(`[harness] ${parts.map((part) => (typeof part === 'string' ? part : JSON.stringify(part))).join(' ')}`);
+}

package/dist/sdk/core/caller.d.ts

@@ -0,0 +1,22 @@
+import { type Project } from "./projects.js";
+export interface CallerContext {
+    /** Opaque, host-owned policy data frozen when this session starts. The harness only forwards it to the embedding app's tool policy. */
+    policyContext?: unknown;
+    runId?: string | null;
+    sessionId?: string | null;
+    projectId?: string | null;
+    /** The caller: decides which plugins and connectors reach it, and whose history it recalls. */
+    agentId?: string | null;
+    /** Callers whose conversations this one may not recall (opaque ids from the embedding host). */
+    recallExcludeAgents?: string[] | null;
+    /** The caller's name, recorded on what it writes. */
+    agentName?: string | null;
+    /** `Chat` for an agent's own conversation, `Code` for a session in a project. */
+    actor?: string | null;
+    /** `cli` when the caller reaches the harness through a terminal command. */
+    surface?: string | null;
+}
+export declare const isSession: (context: CallerContext) => boolean;
+export declare const actorOf: (context: CallerContext) => string;
+export declare const usesCli: (context: CallerContext) => boolean;
+export declare function projectOf(root: string, context: CallerContext): Project | null;

package/dist/sdk/core/caller.js

@@ -0,0 +1,16 @@
+// Who a session works as. The embedding application supplies this when a session starts; the
+// harness never looks an agent up by itself. The ids are opaque to the harness.
+import { findProject } from "./projects.js";
+export const isSession = (context) => context.actor === 'Code';
+export const actorOf = (context) => (isSession(context) ? 'Code' : 'Chat');
+export const usesCli = (context) => context.surface === 'cli';
+export function projectOf(root, context) {
+    if (!context.projectId)
+        return null;
+    try {
+        return findProject(root, context.projectId);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/sdk/core/changes.d.ts

@@ -0,0 +1,15 @@
+export interface Change {
+    /** The Wiki folder the entry is in. */
+    wiki: string;
+    id: string;
+    /** The file that was written. */
+    path: string;
+    /** Its new contents, front matter included. */
+    text: string;
+    actor: string;
+    reason: string;
+}
+type Listener = (change: Change) => void;
+export declare function noteChange(change: Change): void;
+export declare function onChange(listener: Listener): () => void;
+export {};

package/dist/sdk/core/changes.js

@@ -0,0 +1,15 @@
+const listeners = new Set();
+export function noteChange(change) {
+    for (const listener of listeners) {
+        try {
+            listener(change);
+        }
+        catch {
+            // A listener must never break the write it is told about.
+        }
+    }
+}
+export function onChange(listener) {
+    listeners.add(listener);
+    return () => void listeners.delete(listener);
+}

package/dist/sdk/core/effort.d.ts

@@ -0,0 +1,2 @@
+export declare const EFFORTS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type Effort = (typeof EFFORTS)[number];

package/dist/sdk/core/effort.js

@@ -0,0 +1 @@
+export const EFFORTS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];

package/dist/sdk/core/env.d.ts

@@ -0,0 +1,18 @@
+/** Names the harness shows but does not own. Every lookup may answer `null`. */
+export interface Directory {
+    /** An agent's display name. */
+    agentName(agentId: string): string | null;
+    /** The agent a conversation belongs to, when the session id is not the agent's own id. */
+    sessionAgent(sessionId: string): string | null;
+}
+/** The name used when an application gives none. */
+export declare const DEFAULT_PRODUCT_NAME = "Xingular Harness";
+export declare const EMPTY_DIRECTORY: Directory;
+export interface HarnessEnv {
+    /** The data root: `wiki/`, `registry/`, `runs/`, `config/`, `index.sqlite`. */
+    root: string;
+    directory: Directory;
+    /** How the harness names itself to a model and in the Wiki it creates. */
+    productName: string;
+}
+export declare function createEnv(root: string, options?: Partial<Omit<HarnessEnv, 'root'>>): HarnessEnv;

package/dist/sdk/core/env.js

@@ -0,0 +1,8 @@
+// What every harness module is given: where the data lives, and what the embedding application
+// knows that the harness does not.
+/** The name used when an application gives none. */
+export const DEFAULT_PRODUCT_NAME = 'Xingular Harness';
+export const EMPTY_DIRECTORY = { agentName: () => null, sessionAgent: () => null };
+export function createEnv(root, options = {}) {
+    return { root, directory: options.directory ?? EMPTY_DIRECTORY, productName: options.productName ?? DEFAULT_PRODUCT_NAME };
+}

package/dist/sdk/core/errors.d.ts

@@ -0,0 +1,15 @@
+/** A typed failure: a stable code, a message a person can read, and an optional hint on what to do next. */
+export declare class HarnessError extends Error {
+    readonly code: string;
+    readonly retryHint: string | null;
+    constructor(code: string, message: string, retryHint?: string | null);
+    withHint(hint: string): HarnessError;
+}
+export declare const invalid: (message: string) => HarnessError;
+export declare const notFound: (what: string) => HarnessError;
+export interface ErrorShape {
+    code: string;
+    message: string;
+    retryHint?: string | null;
+}
+export declare function toErrorShape(error: unknown, fallbackCode?: string): ErrorShape;

package/dist/sdk/core/errors.js

@@ -0,0 +1,24 @@
+/** A typed failure: a stable code, a message a person can read, and an optional hint on what to do next. */
+export class HarnessError extends Error {
+    code;
+    retryHint;
+    constructor(code, message, retryHint = null) {
+        super(message);
+        this.name = 'HarnessError';
+        this.code = code;
+        this.retryHint = retryHint;
+    }
+    withHint(hint) {
+        return new HarnessError(this.code, this.message, hint);
+    }
+}
+export const invalid = (message) => new HarnessError('invalid_request', message);
+export const notFound = (what) => new HarnessError('not_found', `${what} was not found.`);
+export function toErrorShape(error, fallbackCode = 'harness_error') {
+    if (error instanceof HarnessError)
+        return { code: error.code, message: error.message, retryHint: error.retryHint };
+    const code = error?.code;
+    if (error instanceof Error && typeof code === 'string' && code.startsWith('E'))
+        return { code: 'io_error', message: error.message };
+    return { code: fallbackCode, message: error instanceof Error ? error.message : String(error) };
+}

package/dist/sdk/core/frontmatter.d.ts

@@ -0,0 +1,12 @@
+export declare function split(text: string): {
+    yaml: string;
+    body: string;
+} | null;
+/** The frontmatter as a plain object and the body, or `null` when the block is missing or is not a mapping. */
+export declare function parse(text: string): {
+    front: Record<string, unknown>;
+    body: string;
+} | null;
+/** The text after a readable frontmatter block, or the whole text when there is none. */
+export declare function bodyOf(text: string): string;
+export declare function serialize(front: Record<string, unknown>, body: string): string;

package/dist/sdk/core/frontmatter.js

@@ -0,0 +1,50 @@
+// Markdown files with a YAML frontmatter block (`---` … `---`), used by Wiki pages, facts, blocks and registry items.
+import { parse as parseYaml, stringify } from 'yaml';
+import { HarnessError } from "./errors.js";
+export function split(text) {
+    const rest = text.startsWith('---\n') ? text.slice(4) : text.startsWith('---\r\n') ? text.slice(5) : null;
+    if (rest === null)
+        return null;
+    const end = rest.indexOf('\n---');
+    if (end < 0)
+        return null;
+    return { yaml: rest.slice(0, end), body: rest.slice(end + 4).replace(/^[\r\n]+/, '') };
+}
+/** The frontmatter as a plain object and the body, or `null` when the block is missing or is not a mapping. */
+export function parse(text) {
+    const parts = split(text);
+    if (!parts)
+        return null;
+    try {
+        const front = parseYaml(parts.yaml);
+        if (!front || typeof front !== 'object' || Array.isArray(front))
+            return null;
+        return { front: front, body: parts.body };
+    }
+    catch {
+        return null;
+    }
+}
+/** The text after a readable frontmatter block, or the whole text when there is none. */
+export function bodyOf(text) {
+    const parts = split(text);
+    if (!parts)
+        return text;
+    try {
+        parseYaml(parts.yaml);
+        return parts.body;
+    }
+    catch {
+        return text;
+    }
+}
+export function serialize(front, body) {
+    let yaml;
+    try {
+        yaml = stringify(front, { lineWidth: 0 });
+    }
+    catch (error) {
+        throw new HarnessError('invalid_data', error instanceof Error ? error.message : String(error));
+    }
+    return `---\n${yaml}---\n\n${body.trimEnd()}\n`;
+}

package/dist/sdk/core/fs.d.ts

@@ -0,0 +1,18 @@
+/** Writes through a temporary sibling file and renames it into place so readers never see a partial file. */
+export declare function atomicWrite(path: string, contents: string | Uint8Array): void;
+export declare function writeJson(path: string, value: unknown): void;
+/** `null` when the file does not exist; a file that exists but does not parse is an error. */
+export declare function readJson<T>(path: string): T | null;
+/** `readJson` for callers that treat an unreadable file like a missing one. */
+export declare function readJsonOr<T>(path: string, fallback: T): T;
+export declare function readText(path: string): string | null;
+export declare function appendLine(path: string, line: string): void;
+/** Accepts only IDs that are safe as a single path segment. */
+export declare function safeId(id: string): string;
+/** Accepts a relative path that stays inside its base directory. */
+export declare function safeRelative(path: string): string;
+/** Millisecond UTC timestamp, the format every record uses. */
+export declare function now(): string;
+export declare function newId(): string;
+export declare function isDir(path: string): boolean;
+export declare function isFile(path: string): boolean;