@oharness/engine 0.1.0

package/dist/core/errors.js

@@ -0,0 +1,83 @@
+export class HarnessError extends Error {
+    code;
+    retryable;
+    cause;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = new.target.name;
+        this.code = opts.code ?? "harness_error";
+        this.retryable = opts.retryable ?? false;
+        this.cause = opts.cause;
+    }
+}
+export class ConfigError extends HarnessError {
+    constructor(message, cause) {
+        super(message, { code: "config_error", cause });
+    }
+}
+export class ProviderError extends HarnessError {
+    status;
+    provider;
+    constructor(provider, message, opts = {}) {
+        super(message, {
+            code: "provider_error",
+            retryable: opts.retryable ?? isRetryableStatus(opts.status),
+            cause: opts.cause,
+        });
+        this.provider = provider;
+        this.status = opts.status;
+    }
+}
+export class ToolError extends HarnessError {
+    toolName;
+    constructor(toolName, message, cause) {
+        super(message, { code: "tool_error", cause });
+        this.toolName = toolName;
+    }
+}
+export class PermissionDeniedError extends HarnessError {
+    constructor(message) {
+        super(message, { code: "permission_denied" });
+    }
+}
+export class McpError extends HarnessError {
+    server;
+    constructor(server, message, cause) {
+        super(message, { code: "mcp_error", cause });
+        this.server = server;
+    }
+}
+/**
+ * The server answered 401: it has an identity to check and we have not proved
+ * one. Distinct from `McpError` because it is not a failure to be reported —
+ * it is the start of a login, and the caller needs the challenge to begin it.
+ */
+export class McpAuthRequiredError extends McpError {
+    /** The `WWW-Authenticate` header, which carries where to go discover auth. */
+    challenge;
+    url;
+    constructor(server, url, challenge) {
+        super(server, "authorization required", undefined);
+        this.url = url;
+        if (challenge !== undefined)
+            this.challenge = challenge;
+    }
+}
+export function isRetryableStatus(status) {
+    if (status === undefined)
+        return false;
+    return status === 408 || status === 409 || status === 429 || status >= 500;
+}
+export function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === "string")
+        return err;
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

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

package/dist/core/tokens.d.ts

@@ -0,0 +1,12 @@
+import type { ContentBlock, Message, ToolSchema } from "./types.ts";
+export declare function estimateStringTokens(s: string): number;
+export declare function estimateBlockTokens(block: ContentBlock): number;
+export declare function estimateJsonTokens(value: unknown): number;
+export declare function estimateMessageTokens(message: Message): number;
+export declare function estimateMessagesTokens(messages: Message[]): number;
+export declare function estimateToolsTokens(tools: ToolSchema[]): number;
+export declare function estimateRequestTokens(input: {
+    system?: string;
+    messages: Message[];
+    tools?: ToolSchema[];
+}): number;

package/dist/core/tokens.js

@@ -0,0 +1,56 @@
+/**
+ * Cheap, provider-independent token estimate.
+ *
+ * We deliberately do not ship a tokenizer: every provider tokenizes
+ * differently and the harness only needs an estimate good enough to decide
+ * *when* to compact. Real numbers come back from the provider in `Usage` and
+ * override these estimates once a turn completes.
+ */
+const CHARS_PER_TOKEN = 3.6;
+/** Rough overhead per message envelope / per tool-call wrapper. */
+const MESSAGE_OVERHEAD = 4;
+const IMAGE_TOKENS = 1_600;
+export function estimateStringTokens(s) {
+    return Math.ceil(s.length / CHARS_PER_TOKEN);
+}
+export function estimateBlockTokens(block) {
+    switch (block.type) {
+        case "text":
+            return estimateStringTokens(block.text);
+        case "thinking":
+            return estimateStringTokens(block.thinking);
+        case "image":
+            return IMAGE_TOKENS;
+        case "tool_call":
+            return MESSAGE_OVERHEAD + estimateStringTokens(block.name) + estimateJsonTokens(block.input);
+        case "tool_result":
+            return (MESSAGE_OVERHEAD +
+                block.content.reduce((sum, b) => sum + estimateBlockTokens(b), 0));
+    }
+}
+export function estimateJsonTokens(value) {
+    try {
+        return estimateStringTokens(JSON.stringify(value) ?? "");
+    }
+    catch {
+        return 0;
+    }
+}
+export function estimateMessageTokens(message) {
+    return (MESSAGE_OVERHEAD + message.content.reduce((sum, b) => sum + estimateBlockTokens(b), 0));
+}
+export function estimateMessagesTokens(messages) {
+    return messages.reduce((sum, m) => sum + estimateMessageTokens(m), 0);
+}
+export function estimateToolsTokens(tools) {
+    return tools.reduce((sum, t) => sum +
+        estimateStringTokens(t.name) +
+        estimateStringTokens(t.description) +
+        estimateJsonTokens(t.inputSchema), 0);
+}
+export function estimateRequestTokens(input) {
+    return ((input.system ? estimateStringTokens(input.system) : 0) +
+        estimateMessagesTokens(input.messages) +
+        (input.tools ? estimateToolsTokens(input.tools) : 0));
+}
+//# sourceMappingURL=tokens.js.map

package/dist/core/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/core/tokens.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,eAAe,GAAG,GAAG,CAAC;AAC5B,mEAAmE;AACnE,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAC3B,MAAM,YAAY,GAAG,KAAK,CAAC;AAE3B,MAAM,UAAU,oBAAoB,CAAC,CAAS;IAC5C,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAmB;IACrD,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1C,KAAK,UAAU;YACb,OAAO,oBAAoB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC9C,KAAK,OAAO;YACV,OAAO,YAAY,CAAC;QACtB,KAAK,WAAW;YACd,OAAO,gBAAgB,GAAG,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC/F,KAAK,aAAa;YAChB,OAAO,CACL,gBAAgB;gBAChB,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAClE,CAAC;IACN,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,CAAC;QACH,OAAO,oBAAoB,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IACpD,OAAO,CACL,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CACvF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,QAAmB;IACxD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAmB;IACrD,OAAO,KAAK,CAAC,MAAM,CACjB,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CACT,GAAG;QACH,oBAAoB,CAAC,CAAC,CAAC,IAAI,CAAC;QAC5B,oBAAoB,CAAC,CAAC,CAAC,WAAW,CAAC;QACnC,kBAAkB,CAAC,CAAC,CAAC,WAAW,CAAC,EACnC,CAAC,CACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAIrC;IACC,OAAO,CACL,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,oBAAoB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,sBAAsB,CAAC,KAAK,CAAC,QAAQ,CAAC;QACtC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACrD,CAAC;AACJ,CAAC"}

package/dist/core/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Provider-neutral conversation types.
+ *
+ * Everything the harness stores, persists and replays is expressed in these
+ * types. Provider adapters translate them to/from wire formats. This is what
+ * makes mid-session model switching possible: history never carries a
+ * provider-specific shape.
+ */
+export type Role = "user" | "assistant";
+export interface TextBlock {
+    type: "text";
+    text: string;
+}
+/** Reasoning/thinking content. `signature` is opaque provider state (Anthropic). */
+export interface ThinkingBlock {
+    type: "thinking";
+    thinking: string;
+    signature?: string;
+    /** True when the provider only gave us a redacted/encrypted blob. */
+    redacted?: boolean;
+}
+export interface ImageBlock {
+    type: "image";
+    /** e.g. "image/png" */
+    mimeType: string;
+    /** base64, no data: prefix */
+    data: string;
+}
+export interface ToolCallBlock {
+    type: "tool_call";
+    /** Harness-owned id. Stable across providers for a given session. */
+    id: string;
+    name: string;
+    input: unknown;
+}
+export interface ToolResultBlock {
+    type: "tool_result";
+    toolCallId: string;
+    /**
+     * Kept alongside the id because some providers (Gemini) key tool results by
+     * function name rather than by call id.
+     */
+    toolName: string;
+    content: Array<TextBlock | ImageBlock>;
+    isError?: boolean;
+}
+export type ContentBlock = TextBlock | ThinkingBlock | ImageBlock | ToolCallBlock | ToolResultBlock;
+export interface Message {
+    role: Role;
+    content: ContentBlock[];
+    /** Bookkeeping that never reaches the model. */
+    meta?: MessageMeta;
+}
+export interface MessageMeta {
+    id?: string;
+    timestamp?: number;
+    /** Model that produced this assistant message, for audit after switching. */
+    model?: string;
+    provider?: string;
+    usage?: Usage;
+    stopReason?: StopReason;
+    /** Set on summary messages produced by compaction. */
+    compacted?: boolean;
+    /** Marks synthetic messages injected by the harness, not by the user. */
+    synthetic?: boolean;
+    [key: string]: unknown;
+}
+export interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+}
+export type StopReason = "end_turn" | "tool_use" | "max_tokens" | "stop_sequence" | "refusal" | "aborted" | "error";
+/** JSON Schema subset we pass around. Intentionally loose. */
+export type JSONSchema = Record<string, unknown>;
+/** Tool description as handed to a provider. */
+export interface ToolSchema {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+}
+export declare function text(s: string): TextBlock;
+export declare function userMessage(content: string | ContentBlock[]): Message;
+export declare function assistantMessage(content: ContentBlock[], meta?: MessageMeta): Message;
+/** Concatenated plain text of a message, ignoring thinking and tool blocks. */
+export declare function messageText(message: Message): string;
+export declare function toolCallsOf(message: Message): ToolCallBlock[];
+export declare function emptyUsage(): Usage;
+export declare function addUsage(a: Usage, b: Usage | undefined): Usage;

package/dist/core/types.js

@@ -0,0 +1,49 @@
+/**
+ * Provider-neutral conversation types.
+ *
+ * Everything the harness stores, persists and replays is expressed in these
+ * types. Provider adapters translate them to/from wire formats. This is what
+ * makes mid-session model switching possible: history never carries a
+ * provider-specific shape.
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+export function text(s) {
+    return { type: "text", text: s };
+}
+export function userMessage(content) {
+    return {
+        role: "user",
+        content: typeof content === "string" ? [text(content)] : content,
+        meta: { timestamp: Date.now() },
+    };
+}
+export function assistantMessage(content, meta) {
+    return { role: "assistant", content, meta: { timestamp: Date.now(), ...meta } };
+}
+/** Concatenated plain text of a message, ignoring thinking and tool blocks. */
+export function messageText(message) {
+    return message.content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .join("");
+}
+export function toolCallsOf(message) {
+    return message.content.filter((b) => b.type === "tool_call");
+}
+export function emptyUsage() {
+    return { inputTokens: 0, outputTokens: 0 };
+}
+export function addUsage(a, b) {
+    if (!b)
+        return a;
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        cacheReadTokens: (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0),
+        cacheWriteTokens: (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0),
+        reasoningTokens: (a.reasoningTokens ?? 0) + (b.reasoningTokens ?? 0),
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAsGH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,MAAM,UAAU,IAAI,CAAC,CAAS;IAC5B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAgC;IAC1D,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO;QAChE,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE;KAChC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAuB,EAAE,IAAkB;IAC1E,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC;AAClF,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,OAAO,OAAO,CAAC,OAAO;SACnB,MAAM,CAAC,CAAC,CAAC,EAAkB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAChD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAClB,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAsB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;AACnF,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,CAAQ,EAAE,CAAoB;IACrD,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,OAAO;QACL,WAAW,EAAE,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW;QAC1C,YAAY,EAAE,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY;QAC7C,eAAe,EAAE,CAAC,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC;QACpE,gBAAgB,EAAE,CAAC,CAAC,CAAC,gBAAgB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,gBAAgB,IAAI,CAAC,CAAC;QACvE,eAAe,EAAE,CAAC,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC;KACrE,CAAC;AACJ,CAAC"}

package/dist/harness.d.ts

@@ -0,0 +1,302 @@
+import { AuthManager } from "./auth/manager.ts";
+import type { AuthProvider, AuthStatus, AuthorizeResult } from "./auth/index.ts";
+import { Agent } from "./agent/agent.ts";
+import type { AgentEvent, AgentOptions } from "./agent/agent.ts";
+import { HookRegistry } from "./agent/hooks.ts";
+import type { AuditEntry, PermissionPrompt } from "./agent/permissions.ts";
+import { Session } from "./agent/session.ts";
+import { SessionStore } from "./agent/store.ts";
+import type { SessionMeta } from "./agent/store.ts";
+import { SubagentRegistry } from "./agent/subagent.ts";
+import { SkillRegistry } from "./agent/skills.ts";
+import { SettingsStore } from "./agent/settings.ts";
+import type { WorkspacePolicy } from "./agent/workspace.ts";
+import { MemoryStore } from "./agent/memory.ts";
+import type { HarnessConfig } from "./config.ts";
+import type { PluginDefinition } from "./plugins.ts";
+import { McpManager } from "./mcp/manager.ts";
+import { Scheduler } from "./schedule/scheduler.ts";
+import type { McpServerStatus } from "./mcp/manager.ts";
+import { ProviderRegistry } from "./providers/registry.ts";
+import type { Catalog, CatalogProvider } from "./providers/catalog.ts";
+import type { ModelSpec } from "./providers/types.ts";
+import { ToolRegistry } from "./tools/registry.ts";
+import type { Tool } from "./tools/types.ts";
+import type { Logger, LogSink } from "./util/logger.ts";
+/** Whether decisions are recorded, where else, and whose call that is. */
+export interface AuditStatus {
+    on: boolean;
+    /** The extra file, as configured — usually relative to the project. */
+    file?: string;
+    /** The same path resolved, for showing somebody where to look. */
+    path?: string;
+    source: "user" | "project";
+}
+export interface HarnessOptions {
+    cwd?: string;
+    config?: HarnessConfig;
+    permissionPrompt?: PermissionPrompt;
+    /** Extra tools registered on top of the builtins. */
+    tools?: Tool[];
+    /** Extra auth providers, e.g. a subscription vendor with your own client id. */
+    authProviders?: AuthProvider[];
+    logger?: Logger;
+    /**
+     * Where diagnostics go, when the default stderr is the wrong place.
+     *
+     * A full-screen frontend owns the terminal: a line written straight to
+     * stderr lands on top of the frame it is drawing, which is not a rendering
+     * bug the frontend can fix from its side. The level stays the engine's
+     * decision; only the destination moves.
+     */
+    logSink?: LogSink;
+    /** Skip session persistence entirely (useful in tests and embedded use). */
+    ephemeral?: boolean;
+}
+/**
+ * Top-level facade: owns providers, tools, MCP connections, hooks and
+ * subagents, and hands out `Agent` instances bound to a `Session`.
+ *
+ * Construct it with `Harness.create()` rather than `new`, because MCP
+ * connection and config loading are async.
+ */
+export declare class Harness {
+    readonly cwd: string;
+    readonly config: HarnessConfig;
+    readonly providers: ProviderRegistry;
+    readonly tools: ToolRegistry;
+    readonly hooks: HookRegistry;
+    readonly subagents: SubagentRegistry;
+    readonly skills: SkillRegistry;
+    readonly memory: MemoryStore;
+    readonly settings: SettingsStore;
+    readonly workspace: WorkspacePolicy;
+    readonly mcp: McpManager;
+    readonly store: SessionStore;
+    readonly auth: AuthManager;
+    readonly catalog: Catalog;
+    readonly scheduler: Scheduler;
+    private readonly ephemeral;
+    /** Mirrors this project's transcripts, when sync is on and signed in. */
+    private mirror;
+    private syncState;
+    /** Active declarative plugin bundles, in their effective override order. */
+    readonly plugins: PluginDefinition[];
+    readonly logger: Logger;
+    private readonly options;
+    private projectInstructions?;
+    private constructor();
+    static create(opts?: HarnessOptions): Promise<Harness>;
+    /**
+     * Begin mirroring, if this machine is configured and signed in for it.
+     *
+     * Every reason not to is a normal state rather than an error — not signed
+     * in, switched off, this one repository excluded — so nothing here logs a
+     * failure for them. Only an actual attempt that goes wrong is worth a line.
+     */
+    private startSync;
+    /**
+     * The roots this machine was told to allow, as opposed to the ones it
+     * worked out.
+     *
+     * `workspace.writableRoots` is the sum of a choice and a derivation: what
+     * the config named, plus every skill and agent directory the installed
+     * plugins contributed. Only the first half is editable, and telling them
+     * apart is the difference between a settings row that works and one whose
+     * changes come back on the next launch.
+     */
+    configuredWritableRoots(): string[];
+    /**
+     * Replace the roots this machine allows writes to.
+     *
+     * Takes effect on the next launch rather than now: the workspace policy is
+     * built once and handed to every tool, and swapping it under a turn already
+     * in flight would let a command that was checked against one answer run
+     * against another.
+     */
+    setWritableRoots(roots: string[]): Promise<string[]>;
+    /**
+     * Whether permission decisions are being recorded, and who decided that.
+     *
+     * Recording is on unless somebody turned it off: the trail is a handful of
+     * short lines per turn, it never leaves the machine, and the state where it
+     * is missing is exactly the state where it turns out to have been wanted.
+     *
+     * The source travels with the answer for the same reason sync carries a
+     * reason: a merged config cannot tell a value the user chose from one the
+     * repository imposed, and only the first can be changed from here. A switch
+     * offered over the second would appear to work and come back on the next
+     * launch, which is worse than no switch at all.
+     */
+    auditStatus(): Promise<AuditStatus>;
+    /**
+     * Start or stop recording permission decisions, and remember the choice.
+     *
+     * Only the recording is a choice here. Where an extra copy is written is
+     * `auditLog`, and that stays where somebody typed it: a switch that also
+     * deleted a configured path would turn "stop recording for now" into
+     * "forget where my collector reads from".
+     *
+     * On is written as the *absence* of the key, because on is the default and a
+     * config file should say what somebody decided, not restate what they left
+     * alone. Takes effect on the sessions already open — see `equip`.
+     */
+    setAudit(enabled: boolean): Promise<AuditStatus>;
+    /** A session's permission trail, oldest first. Empty for an ephemeral one. */
+    decisions(sessionId: string): Promise<AuditEntry[]>;
+    /**
+     * Push whatever is waiting, now.
+     *
+     * The mirror pushes on its own — this is for the person who wants to know it
+     * has happened before closing the laptop, which is not a question a
+     * background timer can answer. False means there was nothing to push it
+     * through: off, excluded, or not signed in.
+     */
+    syncNow(): Promise<boolean>;
+    /**
+     * The OHarness account access token, if signed in.
+     *
+     * Only `official` is asked. Other gateway entries in the catalog hold keys
+     * to *their* vendor, not to an OHarness account, and handing one of those to
+     * the artifact API would authenticate as nobody — the 401 that follows is a
+     * far worse way to find out than not trying.
+     *
+     * Public because publishing an artifact needs it too, and a second copy of
+     * this rule in the server package would be a second place to get it wrong.
+     */
+    accountToken(): Promise<string | undefined>;
+    /**
+     * Whether transcripts are leaving this machine, and why not when they are
+     * not.
+     *
+     * The reason is carried rather than collapsed to a boolean because "you
+     * turned this off" and "you are not signed in" look identical from outside
+     * and need opposite advice.
+     */
+    syncStatus(): {
+        on: boolean;
+        reason?: string;
+        url?: string;
+    };
+    /**
+     * Turn sync on or off now, and remember the choice.
+     *
+     * Written to the user's config rather than held in memory, because a switch
+     * that forgets on restart is not a switch — someone who turned sync off did
+     * not mean "until the next launch". Stopping aborts the poll in flight, so
+     * the connection does not outlive the decision.
+     */
+    setSyncEnabled(enabled: boolean): Promise<void>;
+    /** Connect an MCP server at runtime and expose its tools immediately. */
+    addMcpServer(name: string, config: NonNullable<HarnessConfig["mcpServers"]>[string]): Promise<McpServerStatus>;
+    /**
+     * Begin an OAuth login for a connector that asked for one.
+     *
+     * The connector does not have to be connected — a server that answered 401
+     * is exactly the case this exists for. On success the server is reconnected,
+     * so the tools appear without the user doing anything else.
+     */
+    mcpLogin(name: string): Promise<AuthorizeResult>;
+    /** Forget a connector's credential. It will ask again on the next connect. */
+    mcpLogout(name: string): Promise<boolean>;
+    removeMcpServer(name: string): Promise<void>;
+    mcpStatus(): McpServerStatus[];
+    authStatus(): Promise<AuthStatus[]>;
+    /** Providers that can actually authenticate right now. */
+    configuredProviders(): Promise<Set<string>>;
+    /**
+     * Ask providers which models they actually serve, and persist the result to
+     * the user catalog so the next run starts with a current list.
+     */
+    refreshModels(providerId?: string): Promise<ModelSpec[]>;
+    /** Merge discovered models into the user catalog on disk. */
+    private saveDiscovered;
+    /**
+     * Re-scan the skill directories.
+     *
+     * Skills are ordinary markdown on disk and the agent can write them, so
+     * without this an authored skill sits unusable until the next restart —
+     * which breaks the one loop that would let the agent improve itself.
+     */
+    reloadSkills(): Promise<number>;
+    /** Providers declared by the catalog, for `/models` and login hints. */
+    listCatalogProviders(): CatalogProvider[];
+    listModels(configuredOnly?: boolean): ModelSpec[];
+    listSessions(limit?: number): Promise<SessionMeta[]>;
+    /** Start a fresh session. */
+    createSession(overrides?: {
+        model?: string;
+        title?: string;
+    }): Session;
+    /**
+     * Give a session the machinery that outlives it: where remembered approvals
+     * are written, and where decisions are recorded.
+     */
+    private auditQueue;
+    /**
+     * The file the queue has already made a directory for.
+     *
+     * A path rather than a flag, because recording can be switched on and off
+     * while sessions are open: a boolean would remember that *some* directory
+     * exists and let the first write to a new one ENOENT into a log line.
+     */
+    private auditReadyFor?;
+    private equip;
+    /**
+     * Write one trail entry: to the session's own log, and to the configured
+     * file when there is one.
+     *
+     * Fire-and-forget so recording never delays or fails a tool call, but
+     * chained: concurrent appends of separate lines can interleave and a
+     * half-written record is worse than none. The chain also carries the
+     * one-time mkdir for the file sink — without it every write ENOENTs into a
+     * log line and the trail is silently empty.
+     *
+     * This is the one place this harness parts company with a stricter reading
+     * of the same idea, where a decision that cannot be recorded is a decision
+     * that does not happen. That trade buys an audit you can rely on at the cost
+     * of a tool call that fails because a disk did; here the tool call wins, and
+     * a failed write is a warning in the log rather than a refusal. Anything
+     * that needs the stronger guarantee needs this to be awaited on the call
+     * path, not just louder.
+     */
+    private record;
+    /**
+     * Branch a session. Omit `keepMessages` to branch from where it stands, or
+     * pass a count to rewind the branch to an earlier point.
+     */
+    forkSession(id: string, opts?: {
+        keepMessages?: number;
+        title?: string;
+        model?: string;
+    }): Promise<Session | undefined>;
+    deleteSession(id: string): Promise<boolean>;
+    /**
+     * Delete every session recorded in one tree.
+     *
+     * The directory itself is never touched — this throws away what the harness
+     * wrote about the work, not the work. Returns the ids, because whoever asked
+     * is probably holding some of them open.
+     */
+    deleteSessionsIn(cwd: string): Promise<string[]>;
+    renameSession(id: string, title: string): Promise<boolean>;
+    /** Reload a persisted session by id; returns undefined if it is unknown. */
+    resumeSession(id: string, model?: string): Promise<Session | undefined>;
+    /** Build an agent bound to a session, wired with everything the harness owns. */
+    agent(session: Session, overrides?: Partial<AgentOptions>): Agent;
+    /**
+     * One-shot convenience: run a prompt in a new session and stream events.
+     * For multi-turn use, keep a `Session` and reuse the agent.
+     */
+    run(prompt: string, opts?: {
+        model?: string;
+        signal?: AbortSignal;
+    }): AsyncGenerator<AgentEvent, void, void>;
+    close(): Promise<void>;
+    /**
+     * First model whose provider has credentials. Only the cheap synchronous
+     * check runs here — a subscription-only provider is picked up once the
+     * caller has awaited `configuredProviders()`.
+     */
+    private defaultModel;
+}