@zhivex-ai/harness 1.0.0 → 1.1.0-rc.2

package/dist/client-contract.d.ts

@@ -0,0 +1,208 @@
+import { type ApprovalDecisionView } from "./approval-history.js";
+import { type ApprovalFilePreview } from "./approval-preview.js";
+import { z } from "zod";
+import type { AgentStreamEvent } from "@zhivex-ai/agents";
+import { type ZhivexHarness } from "./harness.js";
+import { type CliSession } from "./sessions.js";
+export declare const HARNESS_CLIENT_PROTOCOL_VERSION: 1;
+/** Strict command union; configuration, credentials and filesystem paths are host-owned. */
+export declare const harnessClientCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    projectId: z.ZodString;
+    method: z.ZodLiteral<"project.get">;
+}, z.core.$strict>, z.ZodObject<{
+    projectId: z.ZodString;
+    method: z.ZodLiteral<"session.list">;
+    search: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    projectId: z.ZodString;
+    idempotencyKey: z.ZodString;
+    method: z.ZodLiteral<"session.create">;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    projectId: z.ZodString;
+    sessionId: z.ZodString;
+    method: z.ZodLiteral<"session.get">;
+}, z.core.$strict>, z.ZodObject<{
+    projectId: z.ZodString;
+    sessionId: z.ZodString;
+    idempotencyKey: z.ZodString;
+    method: z.ZodLiteral<"session.rename">;
+    expectedRevision: z.ZodNumber;
+    title: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    projectId: z.ZodString;
+    sessionId: z.ZodString;
+    idempotencyKey: z.ZodString;
+    method: z.ZodLiteral<"run.start">;
+    expectedRevision: z.ZodNumber;
+    prompt: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    projectId: z.ZodString;
+    sessionId: z.ZodString;
+    runId: z.ZodString;
+    method: z.ZodLiteral<"run.get">;
+    includeReview: z.ZodOptional<z.ZodBoolean>;
+    includeDiff: z.ZodOptional<z.ZodBoolean>;
+    decisionOffset: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    projectId: z.ZodString;
+    sessionId: z.ZodString;
+    runId: z.ZodString;
+    idempotencyKey: z.ZodString;
+    method: z.ZodLiteral<"approval.resolve">;
+    expectedRevision: z.ZodNumber;
+    decisions: z.ZodArray<z.ZodObject<{
+        approvalId: z.ZodString;
+        digest: z.ZodString;
+        approve: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    projectId: z.ZodString;
+    sessionId: z.ZodString;
+    runId: z.ZodString;
+    idempotencyKey: z.ZodString;
+    method: z.ZodLiteral<"run.cancel">;
+    expectedRevision: z.ZodNumber;
+}, z.core.$strict>], "method">;
+export declare const harnessClientRequestSchema: z.ZodObject<{
+    protocolVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    connectionId: z.ZodString;
+    command: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        projectId: z.ZodString;
+        method: z.ZodLiteral<"project.get">;
+    }, z.core.$strict>, z.ZodObject<{
+        projectId: z.ZodString;
+        method: z.ZodLiteral<"session.list">;
+        search: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        projectId: z.ZodString;
+        idempotencyKey: z.ZodString;
+        method: z.ZodLiteral<"session.create">;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        projectId: z.ZodString;
+        sessionId: z.ZodString;
+        method: z.ZodLiteral<"session.get">;
+    }, z.core.$strict>, z.ZodObject<{
+        projectId: z.ZodString;
+        sessionId: z.ZodString;
+        idempotencyKey: z.ZodString;
+        method: z.ZodLiteral<"session.rename">;
+        expectedRevision: z.ZodNumber;
+        title: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        projectId: z.ZodString;
+        sessionId: z.ZodString;
+        idempotencyKey: z.ZodString;
+        method: z.ZodLiteral<"run.start">;
+        expectedRevision: z.ZodNumber;
+        prompt: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        projectId: z.ZodString;
+        sessionId: z.ZodString;
+        runId: z.ZodString;
+        method: z.ZodLiteral<"run.get">;
+        includeReview: z.ZodOptional<z.ZodBoolean>;
+        includeDiff: z.ZodOptional<z.ZodBoolean>;
+        decisionOffset: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        projectId: z.ZodString;
+        sessionId: z.ZodString;
+        runId: z.ZodString;
+        idempotencyKey: z.ZodString;
+        method: z.ZodLiteral<"approval.resolve">;
+        expectedRevision: z.ZodNumber;
+        decisions: z.ZodArray<z.ZodObject<{
+            approvalId: z.ZodString;
+            digest: z.ZodString;
+            approve: z.ZodBoolean;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        projectId: z.ZodString;
+        sessionId: z.ZodString;
+        runId: z.ZodString;
+        idempotencyKey: z.ZodString;
+        method: z.ZodLiteral<"run.cancel">;
+        expectedRevision: z.ZodNumber;
+    }, z.core.$strict>], "method">;
+}, z.core.$strict>;
+export type HarnessClientCommand = z.infer<typeof harnessClientCommandSchema>;
+export type HarnessClientRequest = z.infer<typeof harnessClientRequestSchema>;
+export type HarnessClientErrorCode = "INVALID_REQUEST" | "VERSION_UNSUPPORTED" | "CONNECTION_EXPIRED" | "NOT_FOUND" | "REVISION_CONFLICT" | "IDEMPOTENCY_CONFLICT" | "CAPACITY_EXCEEDED" | "APPROVAL_MISMATCH" | "INVALID_STATE" | "BUSY" | "EXECUTION_FAILED";
+export interface HarnessClientSession extends CliSession {
+}
+export interface HarnessClientRun {
+    runId: string;
+    revision: number;
+    status: string;
+    output: string;
+    cliResult?: unknown;
+    decisions?: ApprovalDecisionView[];
+    decisionTotal?: number;
+    decisionNextOffset?: number;
+    approvals: {
+        approvalId: string;
+        digest: string;
+        provider: string;
+        kind: string;
+        action: unknown;
+        expiresAt: number;
+        filePreview?: ApprovalFilePreview;
+    }[];
+}
+export type HarnessClientData = {
+    kind: "project";
+    projectId: string;
+} | {
+    kind: "session";
+    session: HarnessClientSession;
+} | {
+    kind: "sessions";
+    sessions: HarnessClientSession[];
+} | {
+    kind: "run";
+    session: HarnessClientSession;
+    run: HarnessClientRun;
+};
+export type HarnessClientResponse = {
+    protocolVersion: 1;
+    requestId: string | null;
+} & ({
+    ok: true;
+    data: HarnessClientData;
+} | {
+    ok: false;
+    error: {
+        code: HarnessClientErrorCode;
+    };
+});
+export type HarnessClientNegotiation = {
+    ok: true;
+    protocolVersion: 1;
+    connectionId: string;
+    projectId: string;
+    capabilities: readonly string[];
+} | {
+    ok: false;
+    error: {
+        code: "VERSION_UNSUPPORTED" | "CONNECTION_EXPIRED";
+    };
+};
+export interface HarnessClientAdapterOptions {
+    approvalMaxAgeMs?: number;
+    now?: () => number;
+    onPrompt?: (sessionId: string, runId: string, prompt: string) => void | Promise<void>;
+    onEvent?: (sessionId: string, runId: string, event: AgentStreamEvent) => void | Promise<void>;
+    onCheckpoint?: (sessionId: string, runId: string, status: string) => void | Promise<void>;
+}
+export interface HarnessClientAdapter {
+    negotiate(versions: readonly number[]): HarnessClientNegotiation;
+    dispatch(request: unknown): Promise<HarnessClientResponse>;
+    /** Trusted host shutdown control; requests cancellation without finalizing effects. */
+    cancelActive(): Promise<void>;
+    /** Closes this connection and its session index, not the host-owned harness. */
+    close(): void;
+}
+/** One trusted host, one workspace/scope, one connection epoch; no multi-writer guarantee. */
+export declare const createHarnessClientAdapter: (harness: ZhivexHarness, options?: HarnessClientAdapterOptions) => Promise<HarnessClientAdapter>;

package/dist/console-commands.d.ts

@@ -0,0 +1,6 @@
+/** Presentation shared by the direct console and the local-service client. */
+export declare const CONSOLE_COMMAND_CATALOG: readonly [readonly ["/menu", "Open navigation menu", true], readonly ["/help", "Show commands; /help all shows everything", true], readonly ["/credentials", "Manage provider keys in the system keychain or this session", false], readonly ["/provider", "Select a provider", false], readonly ["/model", "Select a model", false], readonly ["/route", "Configure specialist model routes", false], readonly ["/status", "Inspect the current session and run", true], readonly ["/diff", "Review workspace changes", false], readonly ["/review", "Review a task", false], readonly ["/resume", "Reopen a conversation by session ID", true], readonly ["/pending", "Inspect pending approvals", true], readonly ["/approve", "Approve the pending actions", true], readonly ["/deny", "Deny the pending actions", true], readonly ["/compact", "Compact conversation context", false], readonly ["/new", "Start a new conversation", true], readonly ["/rename", "Rename the current conversation", true], readonly ["/clear", "Clear conversation context", false], readonly ["/exit", "Exit the console", true], readonly ["/paste", "Compose a literal multiline draft", true], readonly ["/verbose", "Toggle full or compact activity details", false], readonly ["/context", "Inspect project rules and selected context", false], readonly ["/attach", "Attach a workspace file to the next request", false], readonly ["/attachments", "List selected attachments", false], readonly ["/detach", "Remove selected attachments", false], readonly ["/sessions", "Find saved conversations", true], readonly ["/usage", "Inspect transport usage", false], readonly ["/cancel", "Cancel the active run", true]];
+export type ConsoleMode = "direct" | "service";
+export declare const consoleCommands: (mode?: ConsoleMode) => (readonly ["/approve", "Approve the pending actions", true] | readonly ["/attach", "Attach a workspace file to the next request", false] | readonly ["/attachments", "List selected attachments", false] | readonly ["/cancel", "Cancel the active run", true] | readonly ["/clear", "Clear conversation context", false] | readonly ["/compact", "Compact conversation context", false] | readonly ["/context", "Inspect project rules and selected context", false] | readonly ["/credentials", "Manage provider keys in the system keychain or this session", false] | readonly ["/deny", "Deny the pending actions", true] | readonly ["/detach", "Remove selected attachments", false] | readonly ["/diff", "Review workspace changes", false] | readonly ["/exit", "Exit the console", true] | readonly ["/help", "Show commands; /help all shows everything", true] | readonly ["/menu", "Open navigation menu", true] | readonly ["/model", "Select a model", false] | readonly ["/new", "Start a new conversation", true] | readonly ["/paste", "Compose a literal multiline draft", true] | readonly ["/pending", "Inspect pending approvals", true] | readonly ["/provider", "Select a provider", false] | readonly ["/rename", "Rename the current conversation", true] | readonly ["/resume", "Reopen a conversation by session ID", true] | readonly ["/review", "Review a task", false] | readonly ["/route", "Configure specialist model routes", false] | readonly ["/sessions", "Find saved conversations", true] | readonly ["/status", "Inspect the current session and run", true] | readonly ["/usage", "Inspect transport usage", false] | readonly ["/verbose", "Toggle full or compact activity details", false])[];
+export declare const searchConsoleCommands: (query: string, mode?: ConsoleMode) => (readonly ["/approve", "Approve the pending actions", true] | readonly ["/attach", "Attach a workspace file to the next request", false] | readonly ["/attachments", "List selected attachments", false] | readonly ["/cancel", "Cancel the active run", true] | readonly ["/clear", "Clear conversation context", false] | readonly ["/compact", "Compact conversation context", false] | readonly ["/context", "Inspect project rules and selected context", false] | readonly ["/credentials", "Manage provider keys in the system keychain or this session", false] | readonly ["/deny", "Deny the pending actions", true] | readonly ["/detach", "Remove selected attachments", false] | readonly ["/diff", "Review workspace changes", false] | readonly ["/exit", "Exit the console", true] | readonly ["/help", "Show commands; /help all shows everything", true] | readonly ["/menu", "Open navigation menu", true] | readonly ["/model", "Select a model", false] | readonly ["/new", "Start a new conversation", true] | readonly ["/paste", "Compose a literal multiline draft", true] | readonly ["/pending", "Inspect pending approvals", true] | readonly ["/provider", "Select a provider", false] | readonly ["/rename", "Rename the current conversation", true] | readonly ["/resume", "Reopen a conversation by session ID", true] | readonly ["/review", "Review a task", false] | readonly ["/route", "Configure specialist model routes", false] | readonly ["/sessions", "Find saved conversations", true] | readonly ["/status", "Inspect the current session and run", true] | readonly ["/usage", "Inspect transport usage", false] | readonly ["/verbose", "Toggle full or compact activity details", false])[];
+export declare const formatConsoleHelp: (mode?: ConsoleMode, all?: boolean) => string;

package/dist/console-context.d.ts

@@ -1,6 +1,10 @@
 import type { ZhivexHarness } from "./harness.js";
 import type { Workspace } from "./workspace.js";
-export declare const formatConsoleContext: (context: ZhivexHarness["context"]) => string;
+export declare const formatConsoleContext: (context: ZhivexHarness["context"], options?: {
+    attachments: ReturnType<ConsoleAttachments["list"]>;
+    config: ZhivexHarness["config"];
+    messages: unknown[];
+}) => string;
 export declare const formatConsoleDiff: (diff: string, color: boolean) => string;
 /** Explicit attachments use the same bounded, secret-excluding reads as model tools. */
 export declare class ConsoleAttachments {

package/dist/console-input.d.ts

@@ -1,5 +1,6 @@
-import type { Readable, Writable } from "node:stream";
-export declare const CONSOLE_COMMANDS: readonly ["/help", "/provider", "/model", "/route", "/status", "/diff", "/review", "/resume", "/pending", "/approve", "/deny", "/compact", "/new", "/rename", "/clear", "/exit", "/paste", "/context", "/attach", "/attachments", "/detach"];
+import { type Readable, Writable } from "node:stream";
+import { type ConsoleMode } from "./console-commands.js";
+export declare const CONSOLE_COMMANDS: ("/approve" | "/attach" | "/attachments" | "/cancel" | "/clear" | "/compact" | "/context" | "/credentials" | "/deny" | "/detach" | "/diff" | "/exit" | "/help" | "/menu" | "/model" | "/new" | "/paste" | "/pending" | "/provider" | "/rename" | "/resume" | "/review" | "/route" | "/sessions" | "/status" | "/usage" | "/verbose")[];
 export declare const MAX_CONSOLE_INPUT_BYTES: number;
 export declare const completeConsoleCommand: (line: string) => [string[], string];
 /** Lines received without an active question are discarded, never replayed as approvals. */
@@ -7,18 +8,57 @@ export declare class ConsoleInput {
     private readonly input;
     private readonly output;
     private readonly terminal;
+    private readonly mode;
+    private hidden;
     private readonly reader;
+    private readonly keyboard;
+    private readonly display;
+    private readonly decoder;
+    private escape;
+    private clipboard;
+    private clipboardBytes;
+    private clipboardAllowed;
+    private draftWasPaste;
+    lastSubmissionWasPaste: boolean;
     private closed;
     private completeCommands;
     private history;
     private historyPosition;
     private historyDraft;
+    private historyDraftWasPaste;
     private pending;
     private paste;
     onInterrupt: (() => void) | undefined;
-    constructor(input: Readable, output: Writable, terminal?: boolean);
+    constructor(input: Readable, output: Writable, terminal?: boolean, mode?: ConsoleMode);
+    private selection;
+    private selectionMatches;
+    private finishSelection;
+    select<T>(title: string, items: readonly {
+        value: T;
+        label: string;
+        detail?: string;
+    }[]): Promise<T | undefined>;
+    private taskPrompt;
+    private shortcutsShown;
+    private historySearch;
+    private historyMatches;
+    private finishHistorySearch;
+    private menuVisible;
+    private menuSelection;
+    private menuQuery;
+    private menuDismissed;
+    private escapeMenuTimer;
+    private standaloneMenuEscape;
+    private hideMenu;
+    private renderMenu;
+    private readonly onEnd;
+    private readonly onResize;
+    private finishSecret;
+    secret(prompt: string): Promise<string>;
+    private readonly onData;
+    private insert;
     private readonly onKeypress;
-    rememberPrompt(prompt: string): void;
+    rememberPrompt(prompt: string, literal?: boolean): void;
     clearHistory(): void;
     private interrupt;
     get isClosed(): boolean;

package/dist/console-model-catalog.d.ts

@@ -0,0 +1,25 @@
+export declare const CONSOLE_MODEL_CATALOG: {
+    readonly sdkVersion: "1.25.1";
+    readonly providers: {
+        readonly openai: {
+            readonly revision: "2026-09-12";
+            readonly sourceSha256: "af33783afbf76d7fd12776a2a19244663c286a0f7bc6f05549e2ffe8a3e41900";
+            readonly models: readonly ["gpt-6-astra", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-4o-mini"];
+        };
+        readonly qwen: {
+            readonly revision: "2026-09-20";
+            readonly sourceSha256: "f52a311095ad69f94bdfdbb71f7011ec7e19d24a5c7d7a116f53d7d13c8c6008";
+            readonly models: readonly ["qwen3.8-omni-flash", "qwen3.8-max-0902", "qwen3.8-max", "qwen3.8-flash", "qwen3.8-max-preview", "qwen3.7-max", "qwen3.7-plus", "qwen3.6-flash", "qwen3.5-omni-plus", "qwen-plus"];
+        };
+        readonly gemini: {
+            readonly revision: "2026-09-16";
+            readonly sourceSha256: "ef26943ffd54a786e06f232adf06585ccfdddb6450dd090b2e7bc01d668153b4";
+            readonly models: readonly ["gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash", "gemini-3.5-flash-lite", "gemini-3.5-flash", "gemini-3.1-pro-preview", "gemini-3.1-pro-preview-customtools", "gemini-3-flash-preview", "gemini-3.1-flash-lite"];
+        };
+        readonly meta: {
+            readonly revision: "2026-09-04";
+            readonly sourceSha256: "0e655bb5cee4dd5430336bec10d1a9cfb08a4fdc5902c211d91599f6f92492f6";
+            readonly models: readonly ["muse-spark-1.3", "muse-spark-1.2", "muse-spark-1.2-contributor", "muse-spark-1.1"];
+        };
+    };
+};

package/dist/console-navigation.d.ts

@@ -0,0 +1,27 @@
+import type { ConsoleInput } from "./console-input.js";
+import type { ProviderAvailability } from "./providers.js";
+export declare const consoleModelChoices: (provider: string, defaultModel: string, current?: string) => {
+    value: string;
+    label: string;
+    detail: string;
+}[];
+export type ConsoleNavigationResult = {
+    command: string;
+} | {
+    provider: string;
+    model: string;
+};
+export declare const navigateConsole: (input: Pick<ConsoleInput, "select" | "question">, options: {
+    entry: "menu" | "provider" | "model";
+    current: {
+        provider: string;
+        model: string;
+    };
+    providers: readonly ProviderAvailability[];
+    sessions: () => Promise<readonly {
+        value: string;
+        label: string;
+        detail?: string;
+    }[]>;
+    service?: boolean;
+}) => Promise<ConsoleNavigationResult | undefined>;

package/dist/console-presentation.d.ts

@@ -0,0 +1,18 @@
+/** Bound presentation metadata without allowing paths/titles to control the terminal. */
+export declare const consoleLabel: (text: string, width: number) => string;
+export declare const formatComposer: (input: {
+    model: string;
+    title?: string;
+    status: string;
+    attachments?: number;
+    automaticApprovals?: boolean;
+}, columns?: number, color?: boolean) => string;
+export declare const CONSOLE_SHORTCUTS: string;
+export declare const chooseConsoleItem: <T>(title: string, items: readonly {
+    value: T;
+    label: string;
+    detail?: string;
+}[], io: {
+    write(text: string): void;
+    ask(prompt: string): Promise<string>;
+}) => Promise<T | undefined>;

package/dist/console-welcome.d.ts

@@ -0,0 +1,13 @@
+export declare const ZHIVEX_TERMINAL_LOGO: string;
+export declare const formatConsoleWelcome: (input: {
+    version: string;
+    workspace: string;
+    sessionId?: string;
+    sessionTitle?: string;
+    provider?: string;
+    model?: string;
+    service?: boolean;
+}, options?: {
+    color?: boolean;
+    columns?: number;
+}) => string;

package/dist/execution-environment.d.ts

@@ -168,6 +168,10 @@ export interface HarnessExecutionSession extends AgentExecutionEnvironmentSessio
 export declare const harnessExecutionSession: (context: ToolExecutionContext | undefined) => HarnessExecutionSession | undefined;
 export interface HarnessOciExecutionEnvironment extends AgentExecutionEnvironment {
     acquire(request: AgentExecutionEnvironmentAcquireRequest): Promise<HarnessExecutionSession>;
+    previewPatch(request: Pick<AgentExecutionEnvironmentAcquireRequest, "runId" | "scope">, expectedPatchId: FileDigest): Promise<{
+        patchId: FileDigest;
+        entries: EnvironmentPatchEntry[];
+    }>;
     readonly image: OciImageInspection;
     readonly runtime: HarnessOciRuntimeAdapter;
 }

package/dist/harness.d.ts

@@ -1,3 +1,4 @@
+import { UsageLedger, type UsageAccountingOptions } from "./usage-ledger.js";
 import { createModelBudget } from "./model-budget.js";
 import { createRepairProgress } from "./repair-progress.js";
 import { Agent, type AgentApprovalRequest, type AgentApprovalResponse, type AgentRunInput, type AgentRunOutput, type AgentStreamEvent, type LanguageModel, type ToolDefinition } from "@zhivex-ai/agents";
@@ -16,6 +17,7 @@ export declare const HARNESS_INSTRUCTIONS = "You are Zhivex Harness, a provider-
 /** Render only guidance whose named tools exist in this runtime's catalog. */
 export declare const renderHarnessInstructions: (names: readonly string[]) => string;
 export interface CreateHarnessOptions extends HarnessConfigInput {
+    usageAccounting?: UsageAccountingOptions;
     env?: NodeJS.ProcessEnv;
     providerRegistry?: HarnessProviderRegistry;
     modelInstance?: LanguageModel;
@@ -31,6 +33,7 @@ export interface CreateHarnessOptions extends HarnessConfigInput {
     onLifecycleHookError?: (failure: HarnessLifecycleHookFailure) => void | Promise<void>;
 }
 export interface ZhivexHarness {
+    usageLedger?: UsageLedger;
     config: HarnessConfig;
     workspace: Workspace;
     agent: Agent<LanguageModel>;