@xingular/harness 0.1.7 → 1.1.1

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

@@ -0,0 +1,22 @@
+import type { Harness } from "../harness.js";
+import type { CallerContext } from "../core/caller.js";
+import type { Launch } from "../prompt/compile.js";
+import * as pluginApi from "../plugins/api.js";
+import type { CapabilityCatalogue, CapabilityScope, CapabilitySet } from "./types.js";
+export interface ListParams extends CapabilityScope {
+}
+export interface InventoryParams extends CapabilityScope {
+    context?: CallerContext;
+    launch?: Launch;
+    tools?: string[];
+    connections?: boolean;
+}
+export declare function list(harness: Harness, params?: ListParams): Promise<CapabilityCatalogue>;
+/** The resolved callable set for one caller, based on the stores and caller-supplied tool list. */
+export declare function resolve(harness: Harness, params: ListParams & {
+    tools?: readonly string[];
+}): Promise<CapabilitySet>;
+export declare function toolIntersection(parent: CapabilitySet, assignee: CapabilitySet, taskTools?: readonly string[]): CapabilitySet;
+export declare function inventory(harness: Harness, params?: InventoryParams): Promise<import("../index.js").Inventory>;
+export declare function attach(harness: Harness, params: pluginApi.AttachParams, on: boolean): Promise<CapabilityCatalogue>;
+export declare function switchCapability(harness: Harness, params: pluginApi.AttachParams, on: boolean): Promise<CapabilityCatalogue>;

package/dist/sdk/capabilities/api.js

@@ -0,0 +1,54 @@
+// A generic view of what is available to a caller. The existing plugin, registry, and connector
+// stores remain the source of truth; this module gives hosts one capability-shaped contract.
+import { invalid } from "../core/errors.js";
+import * as pluginApi from "../plugins/api.js";
+const unique = (values) => [...new Set(values.filter((value) => value.length > 0))];
+function contributions(plugins) {
+    return plugins.flatMap((plugin) => plugin.contributions.map((item) => ({
+        id: item.id,
+        pluginId: plugin.id,
+        kind: item.kind,
+        name: item.name,
+        description: item.description,
+        source: plugin.source,
+        state: item.state,
+        attachment: item.attachment
+    })));
+}
+export async function list(harness, params = {}) {
+    const plugins = await pluginApi.list(harness, params);
+    return { plugins, capabilities: contributions(plugins) };
+}
+/** The resolved callable set for one caller, based on the stores and caller-supplied tool list. */
+export async function resolve(harness, params) {
+    const caller = { agentId: params.agentId ?? null, projectId: params.projectId ?? null };
+    const catalogue = await list(harness, params);
+    const connectors = harness.apps.connections.forScope(caller).map((connection) => connection.id);
+    return {
+        version: 1,
+        tools: unique(params.tools ?? []),
+        connectors: unique(connectors),
+        contributions: catalogue.capabilities.filter((item) => item.state === 'on').map((item) => item.id)
+    };
+}
+export function toolIntersection(parent, assignee, taskTools) {
+    const permitted = taskTools === undefined ? null : new Set(taskTools);
+    return {
+        version: 1,
+        tools: parent.tools.filter((tool) => assignee.tools.includes(tool) && (!permitted || permitted.has(tool))),
+        connectors: parent.connectors.filter((id) => assignee.connectors.includes(id)),
+        contributions: parent.contributions.filter((id) => assignee.contributions.includes(id))
+    };
+}
+export function inventory(harness, params = {}) {
+    return pluginApi.inventoryFor(harness, params);
+}
+export async function attach(harness, params, on) {
+    const plugins = await pluginApi.attach(harness, params, on);
+    return { plugins, capabilities: contributions(plugins) };
+}
+export async function switchCapability(harness, params, on) {
+    if (!params.id.trim())
+        throw invalid('A capability id is required.');
+    return attach(harness, params, on);
+}

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

@@ -0,0 +1,18 @@
+import type { CapabilitySet } from "./types.js";
+export interface RunCapabilitySnapshot {
+    version: 1;
+    caller: {
+        agentId: string | null;
+        projectId: string | null;
+    };
+    tools: string[];
+    connectors: string[];
+    contributions: string[];
+}
+export declare function capabilitySet(value: unknown): CapabilitySet;
+/** Writes a run's capability set once. A resumed or duplicate launch cannot replace it. */
+export declare function freezeRun(root: string, runId: string, caller: {
+    agentId?: string | null;
+    projectId?: string | null;
+}, set: CapabilitySet): RunCapabilitySnapshot;
+export declare function loadRun(root: string, runId: string): RunCapabilitySnapshot | null;

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,150 @@
+#!/usr/bin/env node
+// The `xagent` command.
+//
+//   xagent 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).
+//   xagent wiki <command>     Project notes, skills and history, from inside a terminal session.
+//   xagent refine <command>   Refine a variant from evidence (refine demo needs no model).
+//   xagent mcp <command>      Connected apps, from inside a terminal session.
+//   xagent plugins <command>  List, install, switch and trust plugins.
+//   xagent web <command>      Search keys for web_search.
+//   xagent browser <command>  How the agent's browser runs.
+//   xagent worktree <command> Managed git worktrees of the repository you are in.
+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";
+import { runWorktreeCli } from "./worktrees/cli.js";
+const USAGE = `Usage: xagent [--data <dir>] [--state <dir>]
+       xagent <terminal | serve | wiki | mcp | plugins | hub | refine | web | browser | worktree> [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)
+  worktree <command> Managed git worktrees (worktree 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)
+  --worktree [name], -w [name]
+                     Start in a new managed worktree of this repository, or in
+                     the named one
+`;
+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);
+    if (command === 'worktree')
+        return runWorktreeCli(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-]{0,64}(?:token|key)|[\w-]{0,64}(?: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 Agent";
+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 Agent';
+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`;
+}