@zhivex-ai/harness 1.2.0 → 1.3.0-rc.7

package/dist/engine/protocol.d.ts

@@ -0,0 +1,7 @@
+/** Explicit Harness integration surface. See contracts/engine-api.json for stability tiers. */
+export { HARNESS_CLIENT_PROTOCOL_VERSION, harnessClientCommandSchema, harnessClientRequestSchema } from "../client/protocol.js";
+export type { HarnessClientCommand, HarnessClientRequest, HarnessClientErrorCode, HarnessClientSession, HarnessClientRun, HarnessClientData, HarnessClientResponse, HarnessClientNegotiation, HarnessClientAdapterOptions, HarnessClientAdapter } from "../client/protocol.js";
+export { CLI_JSON_SCHEMA_VERSION, CLI_EVENT_SCHEMA_VERSION, streamEventDocument, serializeStreamEvent, streamResultDocument, serializeStreamResult } from "../client/stream.js";
+export type { StreamRunResultSource } from "../client/stream.js";
+export type { HarnessActivityEvent, HarnessActivityRun, HarnessActivitySnapshot, HarnessActivityPage } from "../client/service-events.js";
+export type { ApprovalDecisionView } from "../approvals/approval-history.js";

package/dist/engine/protocol.js

@@ -0,0 +1,182 @@
+// src/client/protocol.ts
+import { z } from "zod";
+var HARNESS_CLIENT_PROTOCOL_VERSION = 1;
+var id = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/);
+var revision = z.number().int().nonnegative().safe();
+var scoped = { projectId: id };
+var session = { ...scoped, sessionId: id };
+var run = { ...session, runId: id };
+var mutation = { idempotencyKey: id };
+var checkpoint = { ...session, checkpointId: z.string().uuid() };
+var restore = { ...session, operationId: z.string().uuid() };
+var fileDigest = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+var harnessClientCommandSchema = z.discriminatedUnion("method", [
+  z.object({ method: z.literal("project.get"), ...scoped }).strict(),
+  z.object({ method: z.literal("policy.get"), ...scoped }).strict(),
+  z.object({ method: z.literal("session.list"), ...scoped, search: z.string().max(256).optional() }).strict(),
+  z.object({ method: z.literal("session.create"), ...scoped, ...mutation, title: z.string().max(256).optional() }).strict(),
+  z.object({ method: z.literal("session.get"), ...session }).strict(),
+  z.object({ method: z.literal("session.rename"), ...session, ...mutation, expectedRevision: revision, title: z.string().max(256) }).strict(),
+  z.object({ method: z.literal("checkpoint.list"), ...session }).strict(),
+  z.object({ method: z.literal("checkpoint.inspect"), ...checkpoint }).strict(),
+  z.object({
+    method: z.literal("checkpoint.capture"),
+    ...session,
+    ...mutation,
+    expectedRevision: revision,
+    turnId: id,
+    paths: z.array(z.string().min(1).max(1024)).min(1).max(20)
+  }).strict(),
+  z.object({
+    method: z.literal("restore.prepare"),
+    ...checkpoint,
+    ...mutation,
+    expectedRevision: revision,
+    expected: z.record(z.string().min(1).max(1024), fileDigest).refine((value) => Object.keys(value).length >= 1 && Object.keys(value).length <= 20)
+  }).strict(),
+  z.object({ method: z.literal("restore.get"), ...restore }).strict(),
+  z.object({ method: z.literal("restore.apply"), ...restore, ...mutation, expectedRevision: revision, reviewedProposalId: fileDigest }).strict(),
+  z.object({ method: z.literal("restore.recoverFork"), ...restore, ...mutation, expectedRevision: revision, forkSessionId: id }).strict(),
+  z.object({ method: z.literal("run.start"), ...session, ...mutation, expectedRevision: revision, prompt: z.string().min(1).max(64 * 1024) }).strict(),
+  z.object({ method: z.literal("run.get"), ...run, includeReview: z.boolean().optional(), includeDiff: z.boolean().optional(), decisionOffset: z.number().int().min(0).max(512).optional() }).strict(),
+  z.object({
+    method: z.literal("approval.resolve"),
+    ...run,
+    ...mutation,
+    expectedRevision: revision,
+    decisions: z.array(z.object({ approvalId: z.string().min(1).max(256), digest: z.string().regex(/^[a-f0-9]{64}$/), approve: z.boolean() }).strict()).min(1).max(64)
+  }).strict(),
+  z.object({ method: z.literal("run.cancel"), ...run, ...mutation, expectedRevision: revision }).strict()
+]);
+var harnessClientRequestSchema = z.object({
+  protocolVersion: z.literal(HARNESS_CLIENT_PROTOCOL_VERSION),
+  requestId: id,
+  connectionId: id,
+  command: harnessClientCommandSchema
+}).strict();
+// src/client/stream.ts
+var CLI_JSON_SCHEMA_VERSION = 1;
+var CLI_EVENT_SCHEMA_VERSION = 1;
+var streamEventDocument = (event, sequence = 0) => {
+  if (!Number.isSafeInteger(sequence) || sequence < 0) {
+    throw new Error("JSONL event sequence must be a non-negative integer.");
+  }
+  const base = {
+    schemaVersion: CLI_EVENT_SCHEMA_VERSION,
+    kind: "run-event",
+    sequence,
+    type: event.type
+  };
+  switch (event.type) {
+    case "text-delta":
+      return { ...base, textDelta: event.textDelta };
+    case "tool-call":
+      return { ...base, toolCallId: event.toolCall.id, toolName: event.toolCall.name };
+    case "tool-result":
+      return {
+        ...base,
+        toolCallId: event.toolResult.toolCallId,
+        toolName: event.toolResult.toolName,
+        isError: event.toolResult.isError
+      };
+    case "tool-approval-request":
+    case "agent-approval-request":
+      return {
+        ...base,
+        approvalRequestId: event.approval.id,
+        approvalKind: event.approval.kind ?? "provider",
+        toolName: event.approval.name
+      };
+    case "agent-approval-resolved":
+      return {
+        ...base,
+        approvalRequestId: event.approval.approvalRequestId,
+        approved: event.approval.approve
+      };
+    case "provider-data":
+      return { ...base, provider: event.provider };
+    case "image-generation":
+      return {
+        ...base,
+        provider: event.provider,
+        partial: event.partial,
+        ...event.id ? { id: event.id } : {},
+        ...event.index !== undefined ? { index: event.index } : {}
+      };
+    case "finish":
+      return {
+        ...base,
+        ...event.finishReason ? { finishReason: event.finishReason } : {},
+        ...event.usage ? { usage: event.usage } : {}
+      };
+    case "error":
+      return { ...base, error: "Provider stream failed." };
+    case "agent-run-start":
+      return { ...base, currentStep: event.currentStep, maxSteps: event.maxSteps };
+    case "agent-step-start":
+      return { ...base, stepIndex: event.stepIndex };
+    case "agent-step-finish":
+      return {
+        ...base,
+        stepIndex: event.step.index,
+        status: event.step.status,
+        toolCalls: event.step.toolResults.length
+      };
+    case "agent-compaction":
+      return {
+        ...base,
+        compactionId: event.compaction.id,
+        reasons: event.compaction.reasons,
+        messageCountBefore: event.compaction.messageCountBefore,
+        messageCountAfter: event.compaction.messageCountAfter
+      };
+    case "agent-run-finish":
+      return {
+        ...base,
+        runId: event.state.runId,
+        status: event.status,
+        provider: event.state.provider,
+        model: event.state.modelId
+      };
+  }
+};
+var serializeStreamEvent = (event, sequence = 0) => JSON.stringify(streamEventDocument(event, sequence));
+var streamResultDocument = (result, sequence = 0) => {
+  if (!Number.isSafeInteger(sequence) || sequence < 0) {
+    throw new Error("JSONL result sequence must be a non-negative integer.");
+  }
+  return {
+    schemaVersion: CLI_EVENT_SCHEMA_VERSION,
+    kind: "run-stream-result",
+    sequence,
+    runId: result.runId,
+    status: result.status,
+    provider: result.provider,
+    model: result.model,
+    steps: result.steps,
+    toolCalls: result.toolCalls,
+    pendingApprovals: (result.pendingApprovals ?? []).map((approval) => ({
+      id: approval.id,
+      kind: approval.kind,
+      name: approval.name,
+      ...approval.childRunId ? { childRunId: approval.childRunId } : {},
+      ...approval.childAgentId ? { childAgentId: approval.childAgentId } : {}
+    })),
+    children: (result.children ?? []).map((child) => ({
+      runId: child.runId,
+      status: child.status
+    }))
+  };
+};
+var serializeStreamResult = (result, sequence = 0) => JSON.stringify(streamResultDocument(result, sequence));
+export {
+  CLI_EVENT_SCHEMA_VERSION,
+  CLI_JSON_SCHEMA_VERSION,
+  HARNESS_CLIENT_PROTOCOL_VERSION,
+  harnessClientCommandSchema,
+  harnessClientRequestSchema,
+  serializeStreamEvent,
+  serializeStreamResult,
+  streamEventDocument,
+  streamResultDocument
+};

package/dist/engine/service.d.ts

@@ -0,0 +1,5 @@
+/** Explicit Harness integration surface. See contracts/engine-api.json for stability tiers. */
+export { harnessLocalCredentialsSchema, startHarnessLocalService, readHarnessLocalCredentials, requestHarnessLocalService, recoverHarnessLocalService } from "../client/local-service.js";
+export type { HarnessLocalService, HarnessLocalServiceOptions, HarnessLocalCredentials } from "../client/local-service.js";
+export { openHarnessActivityStore } from "../client/service-events.js";
+export type { HarnessActivityEvent, HarnessActivityRun, HarnessActivitySnapshot, HarnessActivityPage, HarnessActivityStore, HarnessActivityOptions } from "../client/service-events.js";

package/dist/engine/service.js

@@ -0,0 +1,28 @@
+import {
+  harnessLocalCredentialsSchema,
+  openHarnessActivityStore,
+  readHarnessLocalCredentials,
+  recoverHarnessLocalService,
+  requestHarnessLocalService,
+  startHarnessLocalService
+} from "../index-2gz7jv7g.js";
+import"../index-jgrx804e.js";
+import"../index-h0mqx2ed.js";
+import"../index-8zzhggxv.js";
+import"../index-42gp2hy8.js";
+import"../index-t60rva31.js";
+import"../index-z0qxmkm2.js";
+import"../index-yb239ghk.js";
+import"../index-gq9xagx2.js";
+import"../index-8705zxpr.js";
+import"../index-xqxeypt5.js";
+import"../index-qfpz5y2v.js";
+import"../index-1bx83sw4.js";
+export {
+  harnessLocalCredentialsSchema,
+  openHarnessActivityStore,
+  readHarnessLocalCredentials,
+  recoverHarnessLocalService,
+  requestHarnessLocalService,
+  startHarnessLocalService
+};

package/dist/execution/acceptance-snapshot.d.ts

@@ -0,0 +1,2 @@
+/** Verification identity includes ignored/hidden files too; never exposes their contents. */
+export declare function acceptanceSnapshotDigest(root: string, maxBytes: number): Promise<string>;

package/dist/execution/execution-environment.d.ts

@@ -93,6 +93,14 @@ export declare class CliOciRuntimeAdapter implements HarnessOciRuntimeAdapter {
     removeRunContainers(runId: string): Promise<number>;
     cleanupOrphans(): Promise<number>;
 }
+interface SnapshotFile {
+    path: string;
+    digest: FileDigest;
+    contents: Buffer;
+    mode: number;
+    bytes: number;
+}
+type SnapshotFileMetadata = Omit<SnapshotFile, "contents">;
 export interface HarnessExecutionIoMetrics {
     inventoryPasses: number;
     inventoryPages: number;
@@ -106,6 +114,8 @@ export interface HarnessExecutionIoMetrics {
     workspacePublishes: number;
     workspaceExports: number;
 }
+export declare const collectSnapshotInventory: (workspace: Workspace, maxWorkspaceBytes: number, metrics?: HarnessExecutionIoMetrics, maxEntries?: number) => Promise<Map<string, SnapshotFileMetadata>>;
+export declare const readSnapshotFile: (workspace: Workspace, expected: SnapshotFileMetadata, metrics?: HarnessExecutionIoMetrics, requireSingleLink?: boolean) => Promise<SnapshotFile>;
 interface EnvironmentPatchEntry {
     path: string;
     operation: "create" | "update" | "delete";

package/dist/execution/mcp-oci-channel.d.ts

@@ -0,0 +1,11 @@
+import type { IsolatedMcpChannel } from '../integrations/mcp-stdio-client.js';
+/** Internal cleanup primitive; the owning channel supplies its fixed Docker endpoint. */
+export declare function removeDockerMcpBoundary(cli: (args: string[]) => Promise<string>, id: string): Promise<void>;
+/** Internal handle for a host-created OCI container, never a client-supplied command. */
+export declare function openDockerMcpChannel(options: {
+    containerId: string;
+    imageId: string;
+    sessionMs: number;
+    maxOutputBytes: number;
+    attest?: (inspection: unknown) => void;
+}): Promise<IsolatedMcpChannel>;

package/dist/execution/mcp-oci-server.d.ts

@@ -0,0 +1,38 @@
+import { reserveMcpResources } from '../persistence/mcp-resource-journal.js';
+import { withAdmittedMcpLaunch } from '../integrations/mcp-stdio-launch.js';
+import { IsolatedMcpStdioClient } from '../integrations/mcp-stdio-client.js';
+import type { McpStdioLaunchProposal } from '../integrations/mcp-stdio-admission.js';
+import { createIsolatedMcpTools } from '../integrations/mcp-stdio-tools.js';
+export declare function effectiveMcpContainerEnvironment(input: unknown): Record<string, string>;
+/** Complete pre-start checks in addition to openDockerMcpChannel's isolation checks. */
+export declare function attestMcpServer(inspection: unknown, expected: {
+    imageId: string;
+    volumeName: string;
+    proposal: Readonly<McpStdioLaunchProposal>;
+    environment: Readonly<Record<string, string>>;
+}): void;
+/** Internal host API. Per-tool approvals and durable lifecycle integration remain above this layer. */
+export declare function launchDockerMcpServer(options: Omit<Parameters<typeof withAdmittedMcpLaunch>[0], 'seed'> & {
+    provisionerImageId: string;
+    resourceJournal?: Pick<Parameters<typeof reserveMcpResources>[0], 'store' | 'runId' | 'scope' | 'hostId'>;
+}): Promise<IsolatedMcpStdioClient>;
+/** Agent-facing internal bridge; does not expose the unguarded transport client. */
+type McpToolLaunchOptions = Parameters<typeof launchDockerMcpServer>[0] & {
+    journal: NonNullable<Parameters<typeof createIsolatedMcpTools>[0]['journal']> & {
+        hostId: string;
+    };
+};
+export declare function launchDockerMcpTools(options: McpToolLaunchOptions): Promise<Readonly<{
+    tools: import("@zhivex-ai/core").ToolSet;
+    hostSession: Readonly<Record<never, never>>;
+    close: () => Promise<void>;
+}>>;
+/** One host-owned batch. Recovery is performed by the first launch; later members
+ * belong to that batch and must not treat their live siblings as crashed owners. */
+export declare function launchDockerMcpGroup(input: readonly (McpToolLaunchOptions & {
+    proposal: McpStdioLaunchProposal;
+})[], signal?: AbortSignal): Promise<Readonly<{
+    hostSession: Readonly<Record<never, never>>;
+    close: () => Promise<void>;
+}>>;
+export {};

package/dist/execution/mcp-oci-workspace.d.ts

@@ -0,0 +1,23 @@
+import type { McpResourceLeaseJournal } from '../persistence/mcp-resource-journal.js';
+import type { McpStdioLaunchProposal } from '../integrations/mcp-stdio-admission.js';
+type File = {
+    path: string;
+    contents: Uint8Array;
+    executable: boolean;
+};
+export interface DockerMcpWorkspaceLease {
+    /** Private volume must be mounted only by the admitted server, read-only unless write was admitted. */
+    readonly volumeName: string;
+    /** Keep the seeder alive until the server mounts the tmpfs, otherwise its data disappears. */
+    stopSeeder(): Promise<void>;
+    /** The owner must first remove every server using this volume. */
+    close(): Promise<void>;
+}
+/** Host-only creator, invoked inside withAdmittedMcpLaunch's seed callback. */
+export declare function createDockerMcpWorkspace(options: {
+    provisionerImageId: string;
+    resources?: McpResourceLeaseJournal;
+    proposal: Readonly<McpStdioLaunchProposal>;
+    files: AsyncIterable<File>;
+}): Promise<DockerMcpWorkspaceLease>;
+export {};

package/dist/execution/mcp-resource-recovery.d.ts

@@ -0,0 +1,19 @@
+import type { AgentRunStore, AgentStoreScope } from '@zhivex-ai/core';
+type DockerCli = (args: string[]) => Promise<string>;
+/** Internal recovery primitive. CLI must target the host-selected Docker daemon. */
+export declare function recoverMcpResources(options: {
+    store: AgentRunStore;
+    runId: string;
+    scope: AgentStoreScope;
+    hostId: string;
+    cli: DockerCli;
+}): Promise<{
+    closed: number;
+    deferred: number;
+}>;
+/** Host-only entry point; never discovers or sweeps resources outside persisted names. */
+export declare function recoverDockerMcpResources(options: Omit<Parameters<typeof recoverMcpResources>[0], 'cli'>): Promise<{
+    closed: number;
+    deferred: number;
+}>;
+export {};

package/dist/execution/mcp-workspace-snapshot.d.ts

@@ -0,0 +1,20 @@
+import type { Workspace } from '../workspace/workspace.js';
+export interface McpWorkspaceSnapshot {
+    readonly digest: string;
+    readonly workspace: string;
+    readonly files: number;
+    readonly bytes: number;
+}
+/** Host-only snapshot preparation. No container, secrets, commands or model input. */
+export declare function prepareMcpWorkspaceSnapshot(workspace: Workspace, maxWorkspaceBytes: number): Promise<McpWorkspaceSnapshot>;
+/** Single-use, identity-bound handoff to the trusted OCI volume seeder. */
+export declare function consumeMcpWorkspaceSnapshot(snapshot: McpWorkspaceSnapshot, expected: {
+    snapshotDigest: string;
+    workspace: string;
+    maxWorkspaceBytes: number;
+}, seed: (files: AsyncIterable<{
+    path: string;
+    contents: Uint8Array;
+    executable: boolean;
+}>) => Promise<void>): Promise<void>;
+export declare function discardMcpWorkspaceSnapshot(snapshot: McpWorkspaceSnapshot): Promise<void>;