@zhivex-ai/harness 1.4.0-rc.6 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/README.md +124 -71
  3. package/SECURITY.md +1 -1
  4. package/SUPPORT.md +2 -2
  5. package/contracts/engine-api.json +55 -0
  6. package/contracts/stable-api-signatures.json +33 -33
  7. package/dist/acp-cli.js +18 -15
  8. package/dist/cli/arguments.d.ts +3 -0
  9. package/dist/cli/console/console-budget.d.ts +8 -2
  10. package/dist/{cli-s1rs15vv.js → cli-2h37qyvg.js} +34 -15
  11. package/dist/{cli-entry-d5788aay.js → cli-entry-20w6nh0k.js} +359 -21
  12. package/dist/{cli-entry-9c2k0zwz.js → cli-entry-4ngptr62.js} +2902 -1482
  13. package/dist/{cli-entry-4k1cf0m3.js → cli-entry-w0hterjs.js} +8 -5
  14. package/dist/cli.js +2 -2
  15. package/dist/client/json-contracts.d.ts +95 -2
  16. package/dist/client/local-service.d.ts +2 -2
  17. package/dist/client/protocol.d.ts +3 -0
  18. package/dist/client/stream.d.ts +2 -1
  19. package/dist/compat/code-support.d.ts +6 -0
  20. package/dist/compat/code-support.js +29 -6
  21. package/dist/{config-c002f06f.js → config-j9624t6t.js} +1 -1
  22. package/dist/{config-j3jga5wh.js → config-qt69hkqj.js} +4 -2
  23. package/dist/engine/acp.js +14 -12
  24. package/dist/engine/client.js +11 -10
  25. package/dist/engine/desktop-providers-v1.js +2 -1
  26. package/dist/engine/desktop-state-v1.js +9 -9
  27. package/dist/engine/index.js +48 -46
  28. package/dist/engine/mcp-stdio-v1.js +7 -6
  29. package/dist/engine/protocol.js +30 -2
  30. package/dist/engine/service.js +12 -11
  31. package/dist/hostile-repository-demo.js +4773 -3027
  32. package/dist/{index-49ys3s4q.js → index-5jhgatga.js} +35 -16
  33. package/dist/{index-wq2tax80.js → index-61gthdz6.js} +1 -1
  34. package/dist/index-6dft2vev.js +343 -0
  35. package/dist/{index-gq9xagx2.js → index-8zjmnyw5.js} +25 -138
  36. package/dist/index-937cb7y8.js +705 -0
  37. package/dist/index-bpc596v3.js +154 -0
  38. package/dist/index-fm84men1.js +239 -0
  39. package/dist/{index-e6r04a18.js → index-m34q25jj.js} +1127 -170
  40. package/dist/index-m49jx72n.js +220 -0
  41. package/dist/{index-dj5z774k.js → index-m82cfspw.js} +35 -16
  42. package/dist/{index-qfpz5y2v.js → index-nmjdwd4p.js} +8 -2
  43. package/dist/{index-0g939pfs.js → index-pdmevfxv.js} +10 -7
  44. package/dist/{index-4j1h4j8c.js → index-pp474137.js} +1598 -973
  45. package/dist/{index-2tgb2b4e.js → index-rkbf7dqg.js} +3 -5
  46. package/dist/index-s2k2edts.js +3778 -0
  47. package/dist/{index-z6br6qdn.js → index-tfzta544.js} +28 -11
  48. package/dist/index.js +44 -42
  49. package/dist/persistence/operations.d.ts +3 -0
  50. package/dist/providers/vertex-auth.d.ts +5 -1
  51. package/dist/runtime/config.d.ts +8 -0
  52. package/dist/runtime/context-runtime.d.ts +1 -0
  53. package/dist/runtime/error-diagnostics.d.ts +8 -0
  54. package/dist/runtime/errors.d.ts +10 -0
  55. package/dist/runtime/harness.d.ts +9 -0
  56. package/dist/runtime/policy-inspection.d.ts +1 -0
  57. package/dist/runtime/provider-transient.d.ts +33 -0
  58. package/dist/runtime/runtime-diagnostics.d.ts +3 -0
  59. package/dist/runtime/runtime-policy.d.ts +8 -10
  60. package/dist/runtime/task-acceptance-host.d.ts +1 -1
  61. package/dist/runtime/task-budget-host.d.ts +217 -0
  62. package/dist/runtime/task-budget.d.ts +147 -0
  63. package/dist/runtime/task-continuity.d.ts +434 -0
  64. package/dist/runtime/task-telemetry.d.ts +63 -0
  65. package/dist/runtime/task-transport.d.ts +3 -0
  66. package/dist/runtime/task-usage-context.d.ts +13 -0
  67. package/dist/runtime/time-to-safe-fix.d.ts +8 -0
  68. package/dist/runtime/usage-ledger.d.ts +17 -0
  69. package/dist/service-cli.js +12 -11
  70. package/dist/{service-client-cli-b52c67hx.js → service-client-cli-fn54ev6w.js} +18 -7
  71. package/dist/verify-historical-migrations.js +2426 -652
  72. package/dist/zhx.js +2 -2
  73. package/docs/CLI.md +38 -8
  74. package/docs/CLIENT_PROTOCOL.md +9 -1
  75. package/docs/CODE_RELEASE.md +118 -1
  76. package/docs/DURABLE_OPERATIONS.md +1 -1
  77. package/docs/EXTENSIBILITY.md +1 -1
  78. package/docs/FIRST_USE.md +6 -6
  79. package/docs/MINIMUM_OFFLINE_EVALS.md +31 -0
  80. package/docs/MINIMUM_TASK_AUTHORITY.md +395 -0
  81. package/docs/PROJECT_MEMORY.md +1 -1
  82. package/docs/README.md +2 -0
  83. package/docs/STABILITY.md +1 -1
  84. package/docs/WEB_LIMITS.md +117 -0
  85. package/evaluations/representative-assembly-matrix.json +28 -1
  86. package/examples/README.md +5 -5
  87. package/package.json +8 -5
  88. package/dist/index-8705zxpr.js +0 -145
  89. package/dist/index-a1q355va.js +0 -600
  90. package/dist/index-r0tdj04h.js +0 -976
  91. package/dist/index-rd0s3gqj.js +0 -1669
  92. package/dist/index-vtqfjnab.js +0 -1626
@@ -0,0 +1,705 @@
1
+ import {
2
+ openWorkspaceCheckpointStore
3
+ } from "./index-6dft2vev.js";
4
+ import {
5
+ APPROVAL_HISTORY_KEY,
6
+ appendUserMessage,
7
+ approvalDecisionViews,
8
+ approvalInputDigest,
9
+ checkEvidence,
10
+ createPolicyDecisionEvidence,
11
+ hostPolicyIdentity,
12
+ inspectHarnessPolicy,
13
+ issueExplicitReviewResponses,
14
+ issueRecordedApprovalResponses,
15
+ observeHarnessPolicyDecisions,
16
+ readApprovalDecisions,
17
+ requiresExplicitHostReview,
18
+ runHarness
19
+ } from "./index-pp474137.js";
20
+ import {
21
+ ASSISTANT_RESPONSE_KEY,
22
+ SESSION_RUN_STATUSES,
23
+ USAGE_LEDGER_KEY,
24
+ assistantResponses,
25
+ cancelHarnessRun,
26
+ inspectUsageLedger,
27
+ openCliSessionStore
28
+ } from "./index-s2k2edts.js";
29
+ import {
30
+ createEditProposal,
31
+ editProposalInputSchema,
32
+ fileDigestSchema
33
+ } from "./index-m34q25jj.js";
34
+ import {
35
+ CLI_JSON_SCHEMA_VERSION,
36
+ harnessClientRequestSchema
37
+ } from "./index-nmjdwd4p.js";
38
+ import {
39
+ HarnessStateConflictError,
40
+ harnessErrorDocument,
41
+ providerStreamDiagnostic
42
+ } from "./index-bpc596v3.js";
43
+
44
+ // src/client/continuation.ts
45
+ function terminalContinuationMessages(messages) {
46
+ const recorded = new Set(messages.flatMap((message) => message.parts.flatMap((part) => part.type === "tool-result" ? [part.toolResult.toolCallId] : [])));
47
+ return messages.flatMap((message) => {
48
+ if (message.role !== "assistant")
49
+ return [message];
50
+ const missing = message.parts.filter((part) => part.type === "tool-call" && !recorded.has(part.toolCall.id));
51
+ if (!missing.length)
52
+ return [message];
53
+ return [message, { role: "tool", parts: missing.map((part) => {
54
+ if (part.type !== "tool-call")
55
+ throw new Error("INVALID_CONTINUATION");
56
+ return { type: "tool-result", toolResult: { toolCallId: part.toolCall.id, toolName: part.toolCall.name, isError: true, output: { status: "outcome_unknown", reason: "Previous run ended without a recorded tool result. Inspect current state before any new proposal; do not assume execution or success." } } };
57
+ }) }];
58
+ });
59
+ }
60
+
61
+ // src/client/run-document.ts
62
+ import { getAgentBudgetStatus } from "@zhivex-ai/agents";
63
+ import { estimateAgentRunCost } from "@zhivex-ai/agents/ops";
64
+ var costPricing = (harness) => harness.config.costBudget ? {
65
+ inputCostPer1kTokens: harness.config.costBudget.inputCostPer1kTokens,
66
+ outputCostPer1kTokens: harness.config.costBudget.outputCostPer1kTokens,
67
+ currency: "USD"
68
+ } : undefined;
69
+ var runResultDocument = (result, harness) => ({
70
+ schemaVersion: CLI_JSON_SCHEMA_VERSION,
71
+ kind: "run-result",
72
+ runId: result.state.runId,
73
+ status: result.status,
74
+ provider: result.state.provider,
75
+ model: result.state.modelId,
76
+ output: result.outputText,
77
+ steps: result.steps.length,
78
+ toolCalls: result.toolResults.length,
79
+ verification: checkEvidence(result.toolResults),
80
+ mutations: harness.workspace.mutationAudit(),
81
+ pendingApprovals: result.state.pendingApprovals.map((approval) => ({
82
+ id: approval.id,
83
+ kind: approval.kind ?? "provider",
84
+ name: approval.name,
85
+ arguments: approval.arguments,
86
+ ...approval.childRunId ? { childRunId: approval.childRunId } : {},
87
+ ...approval.childAgentId ? { childAgentId: approval.childAgentId } : {}
88
+ })),
89
+ children: (result.state.childRuns ?? []).map((child) => ({
90
+ runId: child.runId,
91
+ agentId: child.agentId,
92
+ toolName: child.toolName,
93
+ status: child.status,
94
+ steps: child.steps,
95
+ toolCalls: child.toolCalls,
96
+ toolErrors: child.toolErrors,
97
+ usage: child.usage
98
+ })),
99
+ usage: result.usage,
100
+ ...result.state.metadata?.[USAGE_LEDGER_KEY] ? { usageLedger: inspectUsageLedger(result.state.metadata[USAGE_LEDGER_KEY]) } : {},
101
+ budget: getAgentBudgetStatus(result.state, harness.config.budget, result),
102
+ ...harness.config.costBudget ? {
103
+ costBudget: {
104
+ limitUsd: harness.config.costBudget.maxCostUsd,
105
+ estimate: estimateAgentRunCost(result.state, costPricing(harness))
106
+ }
107
+ } : {},
108
+ scope: result.state.scope,
109
+ capabilities: harness.capabilities,
110
+ orchestration: {
111
+ profiles: harness.config.orchestration.profiles,
112
+ childBudget: harness.config.orchestration.childBudget,
113
+ mcpServers: harness.mcpConfiguration.servers.map((server) => server.name)
114
+ },
115
+ execution: harness.executionEnvironment ? {
116
+ backend: "oci",
117
+ binding: result.state.executionEnvironment,
118
+ image: harness.executionEnvironment.image
119
+ } : { backend: "none" },
120
+ store: {
121
+ backend: harness.config.storeBackend,
122
+ stateDirectory: harness.config.stateDirectory,
123
+ migration: harness.persistence?.migration
124
+ },
125
+ stateDirectory: harness.config.stateDirectory
126
+ });
127
+
128
+ // src/approvals/approval-diff.ts
129
+ import { createHash } from "node:crypto";
130
+ import { z } from "zod";
131
+ var APPROVAL_DIFFS_KEY = "clientApprovalDiffsV1";
132
+ var sha = z.string().regex(/^sha256:[a-f0-9]{64}$/);
133
+ var file = z.object({ path: z.string().max(1024), expectedDigest: sha.nullable(), before: z.string().nullable(), after: z.string().nullable(), afterDigest: sha.nullable(), beforeMode: z.number().int().optional(), afterMode: z.number().int().optional(), operation: z.enum(["create", "update", "delete"]).optional() }).strict();
134
+ var archive = z.object({ approvalId: z.string().max(256), digest: z.string().regex(/^[a-f0-9]{64}$/), proposalId: sha, files: z.array(file).min(1).max(50) }).strict();
135
+ var archives = z.array(archive).max(512);
136
+ var maxBytes = 2 * 1024 * 1024;
137
+ var contentDigest = (content) => content === null ? null : `sha256:${createHash("sha256").update(content).digest("hex")}`;
138
+ function read(state) {
139
+ const value = state.metadata?.[APPROVAL_DIFFS_KEY] ?? [];
140
+ if (Buffer.byteLength(JSON.stringify(value)) > maxBytes)
141
+ throw new Error("APPROVAL_DIFF_LIMIT");
142
+ return archives.parse(value);
143
+ }
144
+ function captureApprovalDiffs(state, run, approved) {
145
+ const result = read(state);
146
+ for (const item of run.approvals) {
147
+ if (!approved.has(item.approvalId) || item.filePreview?.status !== "complete")
148
+ continue;
149
+ const parsed = archive.safeParse({ approvalId: item.approvalId, digest: item.digest, proposalId: item.filePreview.proposalId, files: item.filePreview.files });
150
+ if (!parsed.success || result.length >= 512)
151
+ continue;
152
+ const next = [...result, parsed.data];
153
+ if (Buffer.byteLength(JSON.stringify(next)) > maxBytes)
154
+ continue;
155
+ result.push(parsed.data);
156
+ }
157
+ return result;
158
+ }
159
+ function attachAppliedDiffs(state, decisions) {
160
+ let saved;
161
+ try {
162
+ saved = read(state);
163
+ } catch {
164
+ saved = [];
165
+ }
166
+ return decisions.map((row) => {
167
+ if (row.status !== "applied")
168
+ return row;
169
+ const missing = { ...row, finalDiff: { status: "unavailable" } };
170
+ const entry = saved.find((item) => item.approvalId === row.approvalId && item.digest === row.digest);
171
+ const effects = row.evidence?.effects;
172
+ if (!entry || !effects || entry.proposalId !== (row.evidence?.reviewedProposalId ?? row.evidence?.proposalId) || entry.files.length !== effects.length)
173
+ return missing;
174
+ if (new Set(entry.files.map((file2) => file2.path)).size !== entry.files.length || new Set(effects.map((effect) => effect.path)).size !== effects.length)
175
+ return missing;
176
+ if (entry.files.some((file2) => {
177
+ const effect = effects.find((effect2) => effect2.path === file2.path);
178
+ return !effect || effect.beforeDigest !== file2.expectedDigest || effect.afterDigest !== file2.afterDigest || contentDigest(file2.before) !== file2.expectedDigest || contentDigest(file2.after) !== file2.afterDigest;
179
+ }))
180
+ return missing;
181
+ return { ...row, finalDiff: { status: "complete", files: entry.files } };
182
+ });
183
+ }
184
+
185
+ // src/approvals/approval-preview.ts
186
+ import { z as z2 } from "zod";
187
+ async function attachApprovalPreviews(run, workspace, options = {}) {
188
+ let remaining = 256 * 1024;
189
+ for (const approval of run.approvals) {
190
+ const action = approval.action;
191
+ if (!action || !["apply_patch", "apply_reviewed_edits", "apply_reviewed_replacement", "apply_environment_patch", "verify_and_apply_environment_patch", "verify_and_apply_reviewed_edits"].includes(String(action.name)))
192
+ continue;
193
+ approval.filePreview = { status: "unavailable" };
194
+ try {
195
+ if (typeof action.arguments !== "string" || Buffer.byteLength(action.arguments) > 256 * 1024)
196
+ continue;
197
+ const args = JSON.parse(action.arguments);
198
+ const preview = action.name === "apply_environment_patch" || action.name === "verify_and_apply_environment_patch" ? await (async () => {
199
+ if (!options.environment)
200
+ throw new Error("OCI_REVIEW_UNAVAILABLE");
201
+ const patchId = fileDigestSchema.parse(args?.patchId);
202
+ const patch = await options.environment.previewPatch({ runId: run.runId, ...options.scope ? { scope: options.scope } : {} }, patchId);
203
+ return { proposalId: patch.patchId, files: patch.entries.map((entry) => ({ path: entry.path, expectedDigest: entry.beforeDigest ?? null, before: entry.beforeContent ?? null, after: entry.afterContent ?? null, afterDigest: entry.afterDigest ?? null, operation: entry.operation, ...entry.beforeMode === undefined ? {} : { beforeMode: entry.beforeMode }, ...entry.afterMode === undefined ? {} : { afterMode: entry.afterMode } })) };
204
+ })() : action.name === "verify_and_apply_reviewed_edits" ? await (async () => {
205
+ if (!options.environment)
206
+ throw new Error("OCI_REVIEW_UNAVAILABLE");
207
+ const { changes } = editProposalInputSchema.extend({ command: z2.string().min(1), args: z2.array(z2.string()).default([]) }).parse(args);
208
+ return workspace.previewPatch({ changes, proposalId: createEditProposal({ changes }).proposalId });
209
+ })() : action.name === "apply_reviewed_replacement" ? await workspace.previewReplacement(args) : action.name === "apply_patch" ? await workspace.previewPatch(args) : await (async () => {
210
+ const { changes } = editProposalInputSchema.parse(args);
211
+ return workspace.previewPatch({ changes, proposalId: createEditProposal({ changes }).proposalId });
212
+ })();
213
+ const bytes = Buffer.byteLength(JSON.stringify(preview));
214
+ if (bytes > remaining)
215
+ continue;
216
+ remaining -= bytes;
217
+ approval.filePreview = { status: "complete", ...preview };
218
+ } catch {}
219
+ }
220
+ return run;
221
+ }
222
+
223
+ // src/client/adapter.ts
224
+ import { createHash as createHash2, randomUUID } from "node:crypto";
225
+ var canonical = (value) => {
226
+ if (Array.isArray(value))
227
+ return `[${value.map(canonical).join(",")}]`;
228
+ if (value && typeof value === "object")
229
+ return `{${Object.entries(value).filter(([, v]) => v !== undefined).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
230
+ return JSON.stringify(value) ?? "null";
231
+ };
232
+ var digest = (value) => createHash2("sha256").update(canonical(value)).digest("hex");
233
+
234
+ class ClientFault extends Error {
235
+ code;
236
+ constructor(code) {
237
+ super(code);
238
+ this.code = code;
239
+ }
240
+ }
241
+ var fail = (code) => {
242
+ throw new ClientFault(code);
243
+ };
244
+ var sessionStatus = (status) => {
245
+ if (!SESSION_RUN_STATUSES.includes(status))
246
+ return fail("INVALID_STATE");
247
+ return status;
248
+ };
249
+ var sessionDocument = (value) => structuredClone(value);
250
+ var runDocument = (state, approvalMaxAgeMs) => ({
251
+ runId: state.runId,
252
+ revision: state.revision ?? 0,
253
+ status: state.status,
254
+ output: state.outputText ?? "",
255
+ ...state.status === "failed" && state.error ? { error: harnessErrorDocument({
256
+ ...state.error,
257
+ ...state.metadata?.clientProviderStreamDiagnostic ? { ...state.metadata.clientProviderStreamDiagnostic, category: "provider-stream" } : {}
258
+ }).error } : {},
259
+ ...state.metadata?.clientCliResultV1 ? { cliResult: state.metadata.clientCliResultV1 } : {},
260
+ approvals: state.pendingApprovals.map((a) => ({
261
+ approvalId: a.id,
262
+ expiresAt: (state.updatedAt ?? state.startedAt ?? 0) + approvalMaxAgeMs,
263
+ provider: a.provider,
264
+ kind: a.kind ?? "provider",
265
+ digest: digest(a),
266
+ action: a
267
+ }))
268
+ });
269
+ var createHarnessClientAdapter = async (harness, options = {}) => {
270
+ const approvalMaxAgeMs = options.approvalMaxAgeMs ?? 15 * 60000;
271
+ if (!Number.isSafeInteger(approvalMaxAgeMs) || approvalMaxAgeMs < 1)
272
+ throw new Error("APPROVAL_TTL_INVALID");
273
+ const documentRun = async (state, offset = 0, includeDiff = false) => {
274
+ const total = readApprovalDecisions(state).length;
275
+ const decisions = approvalDecisionViews(state, await harness.store.listToolCalls?.(state.runId, harness.config.scope) ?? [], offset);
276
+ return { ...runDocument(state, approvalMaxAgeMs), decisions: includeDiff ? attachAppliedDiffs(state, decisions) : decisions, decisionTotal: total, ...offset + 25 < total ? { decisionNextOffset: offset + 25 } : {} };
277
+ };
278
+ const sessions = await openCliSessionStore({
279
+ workspace: harness.config.workspace,
280
+ stateDirectory: harness.config.stateDirectory,
281
+ scope: harness.config.scope
282
+ });
283
+ const projectId = `project_${digest([sessions.workspaceKey, sessions.scopeKey])}`;
284
+ const connectionId = `connection_${randomUUID()}`;
285
+ let checkpoints;
286
+ const checkpointStore = async () => checkpoints ??= await openWorkspaceCheckpointStore(harness.workspace, sessions);
287
+ const restoreDocument = async (operation) => {
288
+ let preview = { status: "unavailable" };
289
+ try {
290
+ preview = { status: "available", diff: await (await checkpointStore()).previewRestore(operation.id) };
291
+ } catch {}
292
+ return { kind: "restore", operation: {
293
+ id: operation.id,
294
+ checkpointId: operation.checkpoint.id,
295
+ proposalId: operation.proposalId,
296
+ stage: operation.stage,
297
+ ...operation.forkSessionId ? { forkSessionId: operation.forkSessionId } : {}
298
+ }, preview };
299
+ };
300
+ let closed = false, busy = false;
301
+ let active;
302
+ const invoke = async (sessionId, input, prompt) => {
303
+ const runId = "state" in input ? input.state.runId : input.runId;
304
+ let settle;
305
+ const settled = new Promise((resolve) => {
306
+ settle = resolve;
307
+ });
308
+ const controller = new AbortController;
309
+ active = { sessionId, runId, controller, settled };
310
+ let prepared;
311
+ try {
312
+ if (prompt !== undefined)
313
+ await options.onPrompt?.(sessionId, runId, prompt);
314
+ prepared = await options.prepareRun?.({ sessionId, runId, resuming: "state" in input, signal: controller.signal });
315
+ const runtime = prepared?.harness ?? harness;
316
+ if (runtime.store !== harness.store || runtime.workspace.root !== harness.workspace.root || canonical(runtime.config) !== canonical(harness.config)) {
317
+ throw new Error("CLIENT_RUNTIME_BINDING_MISMATCH");
318
+ }
319
+ if (controller.signal.aborted)
320
+ throw new Error("CLIENT_RUNTIME_PREPARATION_CANCELLED");
321
+ active.runtime = runtime;
322
+ const mutationOffset = runtime.workspace.mutationAudit().length;
323
+ const policyEvidence = createPolicyDecisionEvidence();
324
+ const result = await observeHarnessPolicyDecisions(async (event) => {
325
+ policyEvidence.append(event);
326
+ await options.onPolicyDecision?.(sessionId, runId, event);
327
+ }, () => runHarness(runtime, { ...input, abortSignal: controller.signal }, {
328
+ onEvent: (event) => options.onEvent?.(sessionId, runId, event)
329
+ }));
330
+ const document = { ...runResultDocument(result, runtime), policyEvidence: policyEvidence.snapshot(), mutations: runtime.workspace.mutationAudit().slice(mutationOffset) };
331
+ const latest = { ...result.state, metadata: { ...result.state.metadata, clientCliResultV1: JSON.parse(JSON.stringify(document)) } };
332
+ await harness.store.save(latest, { expectedRevision: result.state.revision ?? 0 });
333
+ const saved = await harness.store.load(runId, harness.config.scope);
334
+ if (!saved)
335
+ throw new Error("CLIENT_RESULT_STATE_MISSING");
336
+ await options.onCheckpoint?.(sessionId, runId, saved.status);
337
+ return { ...result, state: saved };
338
+ } catch (e) {
339
+ let persisted;
340
+ try {
341
+ persisted = await harness.store.load(runId, harness.config.scope);
342
+ if (!persisted && !("state" in input)) {
343
+ const now = Date.now();
344
+ await harness.store.save({
345
+ schemaVersion: 1,
346
+ revision: 0,
347
+ runId,
348
+ scope: harness.config.scope,
349
+ provider: harness.agent.model.provider,
350
+ modelId: harness.agent.model.modelId,
351
+ status: controller.signal.aborted ? "cancelled" : "failed",
352
+ messages: input.messages ?? [],
353
+ steps: [],
354
+ toolResults: [],
355
+ currentStep: 0,
356
+ maxSteps: harness.config.budget.unlimitedSteps ? "unlimited" : harness.config.maxSteps,
357
+ outputText: "",
358
+ pendingApprovals: [],
359
+ startedAt: now,
360
+ updatedAt: now,
361
+ error: { message: "Run stopped before initialization." }
362
+ });
363
+ persisted = await harness.store.load(runId, harness.config.scope);
364
+ }
365
+ } catch {}
366
+ const diagnostic = providerStreamDiagnostic(e);
367
+ if (diagnostic && persisted?.status === "failed") {
368
+ try {
369
+ await harness.store.save({ ...persisted, metadata: { ...persisted.metadata, clientProviderStreamDiagnostic: { ...diagnostic } } }, { expectedRevision: persisted.revision ?? 0 });
370
+ } catch {}
371
+ }
372
+ await options.onCheckpoint?.(sessionId, runId, persisted?.status ?? "interrupted");
373
+ throw e;
374
+ } finally {
375
+ try {
376
+ await prepared?.release();
377
+ } finally {
378
+ active = undefined;
379
+ settle();
380
+ }
381
+ }
382
+ };
383
+ const receipts = new Map;
384
+ const getSession = async (sessionId) => {
385
+ const found = await sessions.get(sessionId);
386
+ if (!found || found.archivedAt || found.deletedAt)
387
+ return fail("NOT_FOUND");
388
+ return found;
389
+ };
390
+ const getRun = async (s, runId) => {
391
+ if (!s.runs.some((r) => r.runId === runId))
392
+ return fail("NOT_FOUND");
393
+ const found = await harness.store.load(runId, harness.config.scope);
394
+ if (!found)
395
+ return fail("INVALID_STATE");
396
+ return found;
397
+ };
398
+ const refresh = async (s) => {
399
+ for (const ref of s.runs) {
400
+ const state = await getRun(s, ref.runId);
401
+ if (ref.status !== state.status)
402
+ s = await sessions.updateRun(s.sessionId, ref.runId, { status: sessionStatus(state.status) });
403
+ }
404
+ return s;
405
+ };
406
+ const reviewedRequests = new WeakSet;
407
+ const execute = async (c, hostReviewed = false) => {
408
+ if (c.projectId !== projectId)
409
+ return fail("NOT_FOUND");
410
+ if (c.method === "project.get")
411
+ return { kind: "project", projectId };
412
+ if (c.method === "policy.get")
413
+ return { kind: "policy", policy: inspectHarnessPolicy(active?.runtime ?? harness) };
414
+ if (c.method === "session.create")
415
+ return { kind: "session", session: sessionDocument(await sessions.create(c.title === undefined ? {} : { title: c.title })) };
416
+ if (c.method === "session.list") {
417
+ const listed = await sessions.list(c.search === undefined ? {} : { search: c.search });
418
+ const result = [];
419
+ for (const s2 of listed)
420
+ result.push(sessionDocument(await refresh(await getSession(s2.sessionId))));
421
+ return { kind: "sessions", sessions: result };
422
+ }
423
+ let s = await refresh(await getSession(c.sessionId));
424
+ if (c.method === "session.get")
425
+ return { kind: "session", session: sessionDocument(s) };
426
+ if (c.method === "checkpoint.list") {
427
+ const store = await checkpointStore();
428
+ return { kind: "checkpoints", checkpoints: store.listCheckpoints(s.sessionId), restores: store.listRestores(s.sessionId) };
429
+ }
430
+ if (c.method === "checkpoint.capture") {
431
+ if (s.revision !== c.expectedRevision)
432
+ return fail("REVISION_CONFLICT");
433
+ const store = await checkpointStore();
434
+ const checkpoint = await store.capture({ sessionId: s.sessionId, turnId: c.turnId, paths: c.paths });
435
+ return { kind: "checkpoint", inspection: await store.inspectCheckpoint(checkpoint.id) };
436
+ }
437
+ if (c.method === "checkpoint.inspect" || c.method === "restore.prepare") {
438
+ const store = await checkpointStore();
439
+ if (store.getCheckpoint(c.checkpointId).sessionId !== s.sessionId)
440
+ return fail("NOT_FOUND");
441
+ if (c.method === "checkpoint.inspect")
442
+ return { kind: "checkpoint", inspection: await store.inspectCheckpoint(c.checkpointId) };
443
+ if (s.revision !== c.expectedRevision)
444
+ return fail("REVISION_CONFLICT");
445
+ return restoreDocument((await store.prepareRestore(c.checkpointId, c.expected)).operation);
446
+ }
447
+ if (c.method === "restore.get" || c.method === "restore.apply" || c.method === "restore.recoverFork") {
448
+ const store = await checkpointStore();
449
+ const operation = store.getOperation(c.operationId);
450
+ if (operation.checkpoint.sessionId !== s.sessionId)
451
+ return fail("NOT_FOUND");
452
+ if (c.method === "restore.get")
453
+ return restoreDocument(operation);
454
+ if (s.revision !== c.expectedRevision)
455
+ return fail("REVISION_CONFLICT");
456
+ if (s.runs.some((run) => !["completed", "failed", "cancelled", "timed_out"].includes(run.status)))
457
+ return fail("INVALID_STATE");
458
+ if (c.method === "restore.recoverFork")
459
+ return restoreDocument(await store.recoverFork(operation.id, c.forkSessionId));
460
+ const complete = await store.applyRestore(operation.id, c.reviewedProposalId);
461
+ const fork = await getSession(complete.forkSessionId);
462
+ return { ...await restoreDocument(complete), session: sessionDocument(fork) };
463
+ }
464
+ if (c.method === "session.rename" || c.method === "run.start") {
465
+ if (s.revision !== c.expectedRevision)
466
+ return fail("REVISION_CONFLICT");
467
+ if (c.method === "session.rename")
468
+ return { kind: "session", session: sessionDocument(await sessions.rename(s.sessionId, c.title, { expectedRevision: c.expectedRevision })) };
469
+ const last = s.runs.at(-1);
470
+ const previous = last ? await getRun(s, last.runId) : undefined;
471
+ if (previous && !["completed", "failed", "cancelled", "timed_out"].includes(previous.status))
472
+ return fail("INVALID_STATE");
473
+ const runId = `run_${randomUUID()}`;
474
+ s = await sessions.appendRun(s.sessionId, { runId, provider: harness.config.provider, model: harness.config.model, status: "created" }, { expectedRevision: c.expectedRevision });
475
+ const result = await invoke(s.sessionId, {
476
+ runId,
477
+ scope: harness.config.scope,
478
+ metadata: { [ASSISTANT_RESPONSE_KEY]: assistantResponses(previous?.metadata) },
479
+ messages: appendUserMessage(terminalContinuationMessages(previous?.messages ?? []), c.prompt)
480
+ }, c.prompt);
481
+ s = await sessions.updateRun(s.sessionId, runId, { status: sessionStatus(result.state.status) });
482
+ return { kind: "run", session: sessionDocument(s), run: await documentRun(result.state) };
483
+ }
484
+ let state = await getRun(s, c.runId);
485
+ if (c.method === "run.get")
486
+ return { kind: "run", session: sessionDocument(s), run: c.includeReview ? await attachApprovalPreviews(await documentRun(state, c.decisionOffset, c.includeDiff), harness.workspace, { environment: harness.executionEnvironment, scope: harness.config.scope }) : await documentRun(state, c.decisionOffset, c.includeDiff) };
487
+ if ((state.revision ?? 0) !== c.expectedRevision)
488
+ return fail("REVISION_CONFLICT");
489
+ if (c.method === "run.cancel") {
490
+ if (["created", "running", "queued", "cancel_requested"].includes(state.status)) {
491
+ const ownerId = `cancel_${randomUUID()}`;
492
+ if (!harness.store.acquireLease || !harness.store.releaseLease)
493
+ return fail("INVALID_STATE");
494
+ if (!await harness.store.acquireLease(state.runId, { ownerId, ttlMs: 30000 }, harness.config.scope))
495
+ return fail("BUSY");
496
+ try {
497
+ state = await getRun(s, state.runId);
498
+ if ((state.revision ?? 0) !== c.expectedRevision)
499
+ return fail("REVISION_CONFLICT");
500
+ const visited = new Set([state.runId]);
501
+ const requestChildren = async (parentRunId) => {
502
+ for (const child of await harness.store.findByParentRunId?.(parentRunId, harness.config.scope) ?? []) {
503
+ if (visited.has(child.runId))
504
+ continue;
505
+ visited.add(child.runId);
506
+ await requestChildren(child.runId);
507
+ if (!["completed", "failed", "cancelled", "timed_out"].includes(child.status)) {
508
+ await cancelHarnessRun(harness.store, harness.config, child.runId);
509
+ }
510
+ }
511
+ };
512
+ await requestChildren(state.runId);
513
+ await cancelHarnessRun(harness.store, harness.config, state.runId, { final: true });
514
+ state = await getRun(s, state.runId);
515
+ } finally {
516
+ await harness.store.releaseLease(state.runId, ownerId, harness.config.scope);
517
+ }
518
+ }
519
+ if (!["completed", "failed", "cancelled", "timed_out"].includes(state.status)) {
520
+ await cancelHarnessRun(harness.store, harness.config, state.runId, { final: true, cascade: true });
521
+ state = await getRun(s, state.runId);
522
+ }
523
+ await options.onCheckpoint?.(s.sessionId, state.runId, state.status);
524
+ } else {
525
+ if (state.status !== "waiting_approval")
526
+ return fail("INVALID_STATE");
527
+ const explicitPositive = requiresExplicitHostReview(harness) && c.decisions.some((decision) => decision.approve);
528
+ if (explicitPositive && !hostReviewed)
529
+ return fail("EXPLICIT_REVIEW_REQUIRED");
530
+ if ((options.now ?? Date.now)() > (state.updatedAt ?? state.startedAt ?? 0) + approvalMaxAgeMs)
531
+ return fail("APPROVAL_MISMATCH");
532
+ const pending = state.pendingApprovals;
533
+ if (c.decisions.length !== pending.length || new Set(c.decisions.map((d) => d.approvalId)).size !== pending.length)
534
+ return fail("APPROVAL_MISMATCH");
535
+ const approvals = c.decisions.map((d) => {
536
+ const a = pending.find((a2) => a2.id === d.approvalId);
537
+ if (!a || digest(a) !== d.digest)
538
+ return fail("APPROVAL_MISMATCH");
539
+ return { provider: a.provider, approvalRequestId: a.id, approve: d.approve };
540
+ });
541
+ const history = readApprovalDecisions(state);
542
+ if (history.length + c.decisions.length > 512)
543
+ return fail("CAPACITY_EXCEEDED");
544
+ if (c.decisions.some((d) => history.some((row) => row.approvalId === d.approvalId && row.digest === d.digest)))
545
+ return fail("APPROVAL_MISMATCH");
546
+ const recorded = c.decisions.map((d) => {
547
+ const a = pending.find((a2) => a2.id === d.approvalId);
548
+ let inputDigest;
549
+ try {
550
+ inputDigest = approvalInputDigest(JSON.parse(a.arguments));
551
+ } catch {}
552
+ return {
553
+ approvalId: d.approvalId,
554
+ digest: d.digest,
555
+ name: a.name,
556
+ approved: d.approve,
557
+ decidedAt: (options.now ?? Date.now)(),
558
+ reviewedRevision: c.expectedRevision,
559
+ provenance: { schemaVersion: 1, origin: hostReviewed ? "interactive" : "application", channel: hostReviewed ? "desktop-host" : "client-protocol-v1", policyDigest: hostPolicyIdentity(harness) },
560
+ ...a.toolCallId ? { toolCallId: a.toolCallId } : {},
561
+ ...inputDigest ? { inputDigest } : {}
562
+ };
563
+ });
564
+ const approvedIds = new Set(c.decisions.filter((decision) => decision.approve).map((decision) => decision.approvalId));
565
+ const toArchive = runDocument(state, approvalMaxAgeMs);
566
+ toArchive.approvals = toArchive.approvals.filter((approval) => approvedIds.has(approval.approvalId));
567
+ const reviewed = await attachApprovalPreviews(toArchive, harness.workspace, { environment: harness.executionEnvironment, scope: harness.config.scope });
568
+ const captured = captureApprovalDiffs(state, reviewed, approvedIds);
569
+ const admitted = { ...state, metadata: { ...state.metadata, [APPROVAL_DIFFS_KEY]: JSON.parse(JSON.stringify(captured)), ...!explicitPositive ? { [APPROVAL_HISTORY_KEY]: JSON.parse(JSON.stringify([...history, ...recorded])) } : {} } };
570
+ readApprovalDecisions(admitted);
571
+ await harness.store.save(admitted, { expectedRevision: state.revision ?? 0 });
572
+ state = await getRun(s, c.runId);
573
+ const authorized = explicitPositive ? issueExplicitReviewResponses(harness, state, approvals, "desktop-host", (options.now ?? Date.now)(), c.expectedRevision) : issueRecordedApprovalResponses(harness, state, approvals);
574
+ state = (await invoke(s.sessionId, { state, approvals: authorized, toolExecution: { stopOnError: true } })).state;
575
+ }
576
+ s = await sessions.updateRun(s.sessionId, state.runId, { status: sessionStatus(state.status) });
577
+ return { kind: "run", session: sessionDocument(s), run: await documentRun(state) };
578
+ };
579
+ const adapter = {
580
+ async dispatchReviewed(value) {
581
+ if (!value || typeof value !== "object")
582
+ return { protocolVersion: 1, requestId: null, ok: false, error: { code: "INVALID_REQUEST" } };
583
+ reviewedRequests.add(value);
584
+ try {
585
+ return await adapter.dispatch(value);
586
+ } finally {
587
+ reviewedRequests.delete(value);
588
+ }
589
+ },
590
+ async cancelActive() {
591
+ const current = active;
592
+ if (!current)
593
+ return;
594
+ if (await harness.store.load(current.runId, harness.config.scope)) {
595
+ await cancelHarnessRun(harness.store, harness.config, current.runId, { cascade: true });
596
+ } else {
597
+ current.controller.abort();
598
+ await current.settled;
599
+ if (!await harness.store.load(current.runId, harness.config.scope))
600
+ throw new Error("CLIENT_CANCELLATION_NOT_PERSISTED");
601
+ return;
602
+ }
603
+ current.controller.abort();
604
+ },
605
+ negotiate(versions) {
606
+ if (closed)
607
+ return { ok: false, error: { code: "CONNECTION_EXPIRED" } };
608
+ if (!versions.includes(1))
609
+ return { ok: false, error: { code: "VERSION_UNSUPPORTED" } };
610
+ return { ok: true, protocolVersion: 1, connectionId, projectId, capabilities: ["project.get", "policy.get", "session.list", "session.create", "session.get", "session.rename", "run.start", "run.get", "approval.resolve", "run.cancel.checkpoint", "run.cancel.active", "idempotency.connection", "revision.precondition", "checkpoint.list", "checkpoint.inspect", "checkpoint.capture", "restore.prepare", "restore.get", "restore.apply", "restore.recoverFork"] };
611
+ },
612
+ async dispatch(value) {
613
+ const hostReviewed = Boolean(value && typeof value === "object" && reviewedRequests.delete(value));
614
+ const parsed = harnessClientRequestSchema.safeParse(value);
615
+ if (!parsed.success)
616
+ return { protocolVersion: 1, requestId: null, ok: false, error: { code: "INVALID_REQUEST" } };
617
+ const request = parsed.data;
618
+ const error = (code, cause) => {
619
+ const diagnostic = providerStreamDiagnostic(cause);
620
+ return { protocolVersion: 1, requestId: request.requestId, ok: false, error: { code, ...diagnostic ? { providerDiagnostic: diagnostic } : {} } };
621
+ };
622
+ if (closed || request.connectionId !== connectionId)
623
+ return error("CONNECTION_EXPIRED");
624
+ const c = request.command;
625
+ if (hostReviewed && c.method !== "approval.resolve")
626
+ return error("INVALID_REQUEST");
627
+ const key = "idempotencyKey" in c ? c.idempotencyKey : undefined;
628
+ const fingerprint = digest({ command: c, hostReviewed });
629
+ const existing = key ? receipts.get(key) : undefined;
630
+ if (existing)
631
+ return existing.fingerprint === fingerprint ? { ...structuredClone(await existing.response), requestId: request.requestId } : error("IDEMPOTENCY_CONFLICT");
632
+ if (busy) {
633
+ if (c.method === "run.cancel" && c.projectId === projectId && active?.runId === c.runId && active.sessionId === c.sessionId) {
634
+ if (key && receipts.size >= 1024)
635
+ return error("CAPACITY_EXCEEDED");
636
+ const cancellation = (async () => {
637
+ try {
638
+ const s = await getSession(c.sessionId);
639
+ const state = await getRun(s, c.runId);
640
+ if ((state.revision ?? 0) !== c.expectedRevision)
641
+ return error("REVISION_CONFLICT");
642
+ const controller = active?.controller;
643
+ await cancelHarnessRun(harness.store, harness.config, c.runId, { cascade: true });
644
+ controller?.abort();
645
+ const latest = await getRun(s, c.runId);
646
+ await options.onCheckpoint?.(s.sessionId, c.runId, latest.status);
647
+ return { protocolVersion: 1, requestId: request.requestId, ok: true, data: { kind: "run", session: sessionDocument(s), run: await documentRun(latest) } };
648
+ } catch {
649
+ return error("EXECUTION_FAILED");
650
+ }
651
+ })();
652
+ if (key)
653
+ receipts.set(key, { fingerprint, response: cancellation });
654
+ return structuredClone(await cancellation);
655
+ }
656
+ if (c.projectId === projectId && ["project.get", "policy.get", "session.get", "session.list"].includes(c.method)) {
657
+ try {
658
+ const data = c.method === "project.get" ? { kind: "project", projectId } : c.method === "policy.get" ? { kind: "policy", policy: inspectHarnessPolicy(active?.runtime ?? harness) } : c.method === "session.get" ? { kind: "session", session: sessionDocument(await getSession(c.sessionId)) } : { kind: "sessions", sessions: await Promise.all((await sessions.list(c.method === "session.list" && c.search !== undefined ? { search: c.search } : {})).map(async (s) => sessionDocument(await getSession(s.sessionId)))) };
659
+ return { protocolVersion: 1, requestId: request.requestId, ok: true, data };
660
+ } catch {
661
+ return error("NOT_FOUND");
662
+ }
663
+ }
664
+ if (c.method === "run.get" && c.projectId === projectId) {
665
+ try {
666
+ const s = await getSession(c.sessionId);
667
+ const state = await getRun(s, c.runId);
668
+ return { protocolVersion: 1, requestId: request.requestId, ok: true, data: { kind: "run", session: sessionDocument(s), run: c.includeReview ? await attachApprovalPreviews(await documentRun(state, c.decisionOffset, c.includeDiff), harness.workspace, { environment: harness.executionEnvironment, scope: harness.config.scope }) : await documentRun(state, c.decisionOffset, c.includeDiff) } };
669
+ } catch {
670
+ return error("NOT_FOUND");
671
+ }
672
+ }
673
+ return error(c.method === "approval.resolve" ? "REVISION_CONFLICT" : "BUSY");
674
+ }
675
+ if (key && receipts.size >= 1024)
676
+ return error("CAPACITY_EXCEEDED");
677
+ busy = true;
678
+ const response = (async () => {
679
+ try {
680
+ return { protocolVersion: 1, requestId: request.requestId, ok: true, data: await execute(c, hostReviewed) };
681
+ } catch (e) {
682
+ return error(e instanceof ClientFault ? e.code : e instanceof HarnessStateConflictError ? "REVISION_CONFLICT" : "EXECUTION_FAILED", e);
683
+ } finally {
684
+ busy = false;
685
+ }
686
+ })();
687
+ if (key)
688
+ receipts.set(key, { fingerprint, response });
689
+ return structuredClone(await response);
690
+ },
691
+ close() {
692
+ if (closed)
693
+ return;
694
+ if (busy)
695
+ return fail("BUSY");
696
+ closed = true;
697
+ checkpoints?.close();
698
+ sessions.close();
699
+ receipts.clear();
700
+ }
701
+ };
702
+ return adapter;
703
+ };
704
+
705
+ export { terminalContinuationMessages, runResultDocument, createHarnessClientAdapter };