@niwa-labs/harness-zcode 0.0.0-stage → 0.0.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.
- package/LICENSE +21 -0
- package/README.md +8 -2
- package/package.json +20 -4
- package/scripts/gen-zcode.ts +384 -0
- package/src/config.ts +33 -0
- package/src/control.ts +1478 -0
- package/src/dispatch.ts +211 -0
- package/src/fixtures.ts +175 -0
- package/src/format.ts +153 -0
- package/src/index.ts +116 -0
- package/src/paths.ts +21 -0
- package/src/protocol/generated/zcode-protocol.ts +393 -0
- package/src/protocol/index.ts +230 -0
- package/src/reading.ts +506 -0
- package/src/reverse.ts +170 -0
- package/src/skills.ts +6 -0
- package/src/tools.ts +45 -0
- package/test/conformance.test.ts +29 -0
- package/test/control.test.ts +983 -0
- package/test/fixtures/zcode/captured-0.17.3.ndjson +23 -0
- package/test/fixtures/zcode/session-messages-0.17.3.json +241 -0
- package/test/live/control.test.ts +195 -0
- package/test/mode.test.ts +100 -0
- package/test/profile.test.ts +20 -0
- package/test/protocol.test.ts +437 -0
- package/test/reading.test.ts +332 -0
- package/tsconfig.json +8 -0
package/src/control.ts
ADDED
|
@@ -0,0 +1,1478 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The control side for ZCode: how niwa starts, steers and stops sessions over
|
|
3
|
+
* `zcode app-server --stdio`.
|
|
4
|
+
*
|
|
5
|
+
* The wire is NDJSON, one JSON object per line: `{id, method, params}` out, `{id, result|error}`
|
|
6
|
+
* back, no `jsonrpc` field and no handshake; `runtime/capabilities` is the readiness ping. The
|
|
7
|
+
* server also asks things of the client while a session materializes and while a turn runs, and
|
|
8
|
+
* every one of those is answered, or the turn waits forever.
|
|
9
|
+
*
|
|
10
|
+
* Each session owns one child in its own process group, as the owner asked: no process is reused.
|
|
11
|
+
* The session's MCP servers, tool allow-list and tool deny-list go in `session/create` (and in a
|
|
12
|
+
* cold `session/resume`), where the server reads them.
|
|
13
|
+
* The native session id is ZCode's own (`sess_<uuid>`). The model is not set at create (ZCode
|
|
14
|
+
* fails the create on it) but goes with every `session/send`, with the effort as its reasoning
|
|
15
|
+
* level. A message to a busy session is queued by default and becomes a turn of its own when the
|
|
16
|
+
* current turn ends; only a caller that asks for it is steered into the running turn. ZCode refuses a
|
|
17
|
+
* `session/send` while a prompt runs, so a steer goes through `v4/command`, as a `sendText` that asks
|
|
18
|
+
* for the delivery `guide`; a ZCode without that method refuses the steer by name.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
import { randomUUID } from "node:crypto";
|
|
22
|
+
import { resolve } from "node:path";
|
|
23
|
+
|
|
24
|
+
import { z } from "zod";
|
|
25
|
+
|
|
26
|
+
import { assertNever, timestamp } from "@niwa-labs/core";
|
|
27
|
+
import type { Answer, Question } from "@niwa-labs/core";
|
|
28
|
+
import {
|
|
29
|
+
DEFAULT_TURN_TIMEOUT_MS,
|
|
30
|
+
HarnessIdSchema,
|
|
31
|
+
InputNotSent,
|
|
32
|
+
inputFailure,
|
|
33
|
+
Unavailable,
|
|
34
|
+
Unsupported,
|
|
35
|
+
modeOf,
|
|
36
|
+
modelName,
|
|
37
|
+
requireLaunch,
|
|
38
|
+
sessionId as makeSessionId,
|
|
39
|
+
unknownVariantSigns,
|
|
40
|
+
} from "@niwa-labs/harness";
|
|
41
|
+
import type {
|
|
42
|
+
AskAnswer,
|
|
43
|
+
AskOptions,
|
|
44
|
+
DeliveryReceipt,
|
|
45
|
+
Dispatch,
|
|
46
|
+
HarnessId,
|
|
47
|
+
LaunchCapabilities,
|
|
48
|
+
LifeEvent,
|
|
49
|
+
McpServerSpec,
|
|
50
|
+
Prompt,
|
|
51
|
+
ResumeOptions,
|
|
52
|
+
ReverseHandler,
|
|
53
|
+
SendOptions,
|
|
54
|
+
SessionControl,
|
|
55
|
+
SessionId,
|
|
56
|
+
SessionMode,
|
|
57
|
+
SessionState,
|
|
58
|
+
StartOptions,
|
|
59
|
+
StartedSession,
|
|
60
|
+
ToolsMode,
|
|
61
|
+
VisibleActions,
|
|
62
|
+
} from "@niwa-labs/harness";
|
|
63
|
+
import { LIVE_PROCESS_REFUSAL, spawnAgent } from "@niwa-labs/sandbox";
|
|
64
|
+
import type { AgentProcess, BoxRequest } from "@niwa-labs/sandbox";
|
|
65
|
+
|
|
66
|
+
import { notificationAction, requestAction } from "./dispatch.ts";
|
|
67
|
+
import type { Answered, TurnEnd } from "./dispatch.ts";
|
|
68
|
+
import { SessionMessageSchema } from "./protocol/generated/zcode-protocol.ts";
|
|
69
|
+
import type { RequestPermissionParams, RequestUserInputParams } from "./protocol/generated/zcode-protocol.ts";
|
|
70
|
+
import { readNotification, readRequest, unknownDetail, unknownVariantName, ZCODE_PROTOCOL } from "./protocol/index.ts";
|
|
71
|
+
import type { UnknownVariant } from "./protocol/index.ts";
|
|
72
|
+
import { dbPathOf } from "./paths.ts";
|
|
73
|
+
import { directoryOf, persistedModeOf } from "./reading.ts";
|
|
74
|
+
import { INPUT_CANCELLED, readPermission, readUserInput } from "./reverse.ts";
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* What a ZCode session takes at launch: a model as `providerId/modelId`, and the reasoning level
|
|
78
|
+
* of it. The levels are the ones the GLM models list as their variants; a model with a level of
|
|
79
|
+
* its own (`enabled`) is left to its default.
|
|
80
|
+
*/
|
|
81
|
+
export const ZCODE_LAUNCH: LaunchCapabilities = { model: true, effort: ["low", "high", "max"], modes: ["ask", "auto", "full"] };
|
|
82
|
+
|
|
83
|
+
/** The mode of a ZCode session for each working mode: `guarded` asks, `edit` takes edits, `yolo` asks nothing. */
|
|
84
|
+
const SESSION_MODES = { ask: "guarded", auto: "edit", full: "yolo" } as const satisfies Record<SessionMode, string>;
|
|
85
|
+
|
|
86
|
+
/** What happens when a tool asks for permission: the answer to a request the session still makes. */
|
|
87
|
+
export type ZcodePermissionPolicy = "allow" | "deny";
|
|
88
|
+
|
|
89
|
+
export interface ZcodeControlOptions {
|
|
90
|
+
/** The harness instance id: half of a session's identity. */
|
|
91
|
+
readonly harness: string;
|
|
92
|
+
/** The `zcode` binary, resolved through PATH when it is a bare name. */
|
|
93
|
+
readonly binary?: string;
|
|
94
|
+
/**
|
|
95
|
+
* The directory of the installation, which holds `cli/db/db.sqlite`: where a session to resume is
|
|
96
|
+
* asked which directory it ran in, and where the children store their sessions and a box may write.
|
|
97
|
+
* Without it a child keeps to `~/.zcode`.
|
|
98
|
+
*/
|
|
99
|
+
readonly home?: string;
|
|
100
|
+
/** The working mode of sessions, when the caller does not choose one per start. Default: `auto`. */
|
|
101
|
+
readonly mode?: SessionMode;
|
|
102
|
+
/**
|
|
103
|
+
* What happens when a tool asks for permission: `"allow"` (the default) grants the request,
|
|
104
|
+
* `"deny"` refuses it. A session in `full` mode is never asked.
|
|
105
|
+
*/
|
|
106
|
+
readonly permissions?: ZcodePermissionPolicy;
|
|
107
|
+
/** The model sessions talk to, as `providerId/modelId`, when the caller does not choose one per start. */
|
|
108
|
+
readonly model?: string;
|
|
109
|
+
/** The reasoning level, when the caller does not choose one per start. */
|
|
110
|
+
readonly effort?: string;
|
|
111
|
+
/** How long one call waits for its answer, in milliseconds. */
|
|
112
|
+
readonly callTimeoutMs?: number;
|
|
113
|
+
/** How long a turn waits for its end, in milliseconds. */
|
|
114
|
+
readonly turnTimeoutMs?: number;
|
|
115
|
+
/** How long a graceful stop waits before each signal, in milliseconds. */
|
|
116
|
+
readonly stopGraceMs?: number;
|
|
117
|
+
/**
|
|
118
|
+
* What ZCode's `mcpServers` entry of a server takes beyond niwa's own spec, by the name of the
|
|
119
|
+
* server. A server not named here gets ZCode's own defaults.
|
|
120
|
+
*/
|
|
121
|
+
readonly mcp?: Readonly<Record<string, ZcodeMcpOptions>>;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/** The optional fields of a ZCode `mcpServers` entry, as ZCode's protocol names them. */
|
|
125
|
+
export interface ZcodeMcpOptions {
|
|
126
|
+
readonly alwaysLoad?: boolean;
|
|
127
|
+
readonly timeoutMs?: number;
|
|
128
|
+
readonly isolation?: "session" | "workspace";
|
|
129
|
+
readonly scope?: "user" | "workspace";
|
|
130
|
+
readonly cwd?: string;
|
|
131
|
+
readonly protocolVersion?: "legacy" | "auto" | "2026-07-28";
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** A `SessionControl` that also owns the processes it started. */
|
|
135
|
+
export interface ZcodeSessionControl extends SessionControl {
|
|
136
|
+
/** Stops a session and lets it go: the contract's release of one session. */
|
|
137
|
+
close(id: SessionId): Promise<void>;
|
|
138
|
+
|
|
139
|
+
/** Stops a session and the process group it owns. */
|
|
140
|
+
stop(id: SessionId): Promise<void>;
|
|
141
|
+
|
|
142
|
+
/** Stops every session this control side owns, including ones still starting. */
|
|
143
|
+
dispose(): Promise<void>;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
const DEFAULT_CALL_TIMEOUT_MS = 180_000;
|
|
147
|
+
/** A node process that writes its database needs time to drain after its input ends. */
|
|
148
|
+
const DEFAULT_STOP_GRACE_MS = 1_500;
|
|
149
|
+
const MAX_FRAME_BYTES = 16 * 1024 * 1024;
|
|
150
|
+
const STDERR_TAIL_CHARS = 2000;
|
|
151
|
+
|
|
152
|
+
/** The subscription kind the server takes, newest spelling first: the enum moved between bundles. */
|
|
153
|
+
const DELIVERY_KINDS = ["desktop-continuous", "desktop"] as const;
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* One envelope: a response, a notification or a request of the server, by which fields are present.
|
|
158
|
+
* ZCode's own `zcodeProtocolMessageSchema` is a union of those four that, once it is not strict, takes an
|
|
159
|
+
* error for a result, so the kind of an envelope is told by its fields, here.
|
|
160
|
+
*/
|
|
161
|
+
const FrameSchema = z.looseObject({
|
|
162
|
+
id: z.union([z.number(), z.string(), z.null()]).optional(),
|
|
163
|
+
method: z.string().optional(),
|
|
164
|
+
params: z.unknown().optional(),
|
|
165
|
+
result: z.unknown().optional(),
|
|
166
|
+
error: z.looseObject({ code: z.number().optional(), message: z.string().optional() }).optional(),
|
|
167
|
+
});
|
|
168
|
+
|
|
169
|
+
/** What ZCode answers a command of `v4/command` with: whether it took it, and how. */
|
|
170
|
+
const CommandAckSchema = z.looseObject({
|
|
171
|
+
status: z.enum(["accepted", "rejected", "stale", "duplicate", "noop", "failed"]),
|
|
172
|
+
reasonCode: z.string().optional(),
|
|
173
|
+
message: z.string().optional(),
|
|
174
|
+
result: z.looseObject({ delivery: z.enum(["startNow", "queue", "guide"]).optional() }).optional(),
|
|
175
|
+
});
|
|
176
|
+
|
|
177
|
+
/** JSON-RPC's code for a method the server does not have. */
|
|
178
|
+
const METHOD_NOT_FOUND = -32601;
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* What `runtime/capabilities` answers: a report of what the installation offers, one flag each. The
|
|
182
|
+
* flags are ZCode's to add, so only the shape of the report is required of it.
|
|
183
|
+
*/
|
|
184
|
+
const CapabilitiesSchema = z.looseObject({});
|
|
185
|
+
|
|
186
|
+
/** What ZCode answers a `session/send` with when it takes the message. */
|
|
187
|
+
const SendAckSchema = z.looseObject({ accepted: z.literal(true), sessionId: z.string() });
|
|
188
|
+
|
|
189
|
+
/** What a `session/messages` result is made of; each message is read by the snapshot's schema on its own, so one it does not know costs only itself. */
|
|
190
|
+
const MessagesResultSchema = z.object({ messages: z.array(z.unknown()) });
|
|
191
|
+
|
|
192
|
+
/** The result of one call. A refusal is an outcome, not a rejection. */
|
|
193
|
+
interface Outcome {
|
|
194
|
+
readonly ok: boolean;
|
|
195
|
+
readonly result?: unknown;
|
|
196
|
+
readonly error?: string;
|
|
197
|
+
/** The code of the error the server answered with, when it gave one. */
|
|
198
|
+
readonly code?: number;
|
|
199
|
+
/** How far a call that failed got: never written, refused by the CLI, or written and never answered. */
|
|
200
|
+
readonly dispatch?: Dispatch;
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/** The model a send names, and the reasoning level it thinks with. */
|
|
204
|
+
interface ModelSelection {
|
|
205
|
+
readonly providerId: string;
|
|
206
|
+
readonly modelId: string;
|
|
207
|
+
readonly options?: { readonly reasoningLevel: string };
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/** How a turn ended, and which message of the transcript began it, when the server said. */
|
|
211
|
+
interface EndedTurn extends TurnEnd {
|
|
212
|
+
readonly messageId?: string | undefined;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
interface TurnWait {
|
|
216
|
+
readonly done: Promise<EndedTurn | undefined>;
|
|
217
|
+
cancel(): void;
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/** A request of the server that waits for the client's answer, and every id it was announced under. */
|
|
221
|
+
interface Asking {
|
|
222
|
+
readonly requestId: string;
|
|
223
|
+
readonly toolCallId: string | undefined;
|
|
224
|
+
/** The server announces a request again, under a new id, while it waits: each id is answered. */
|
|
225
|
+
readonly ids: Array<number | string>;
|
|
226
|
+
readonly controller: AbortController;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/** How many answered requests are remembered, to answer an announcement that was already on its way. */
|
|
230
|
+
const SETTLED_LIMIT = 32;
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* What a session's process was launched with. A process that replaces it is launched with the
|
|
234
|
+
* same: what a resume does not name again stays what it was.
|
|
235
|
+
*/
|
|
236
|
+
interface Launch {
|
|
237
|
+
readonly env: Readonly<Record<string, string>> | undefined;
|
|
238
|
+
readonly box: BoxRequest | undefined;
|
|
239
|
+
readonly servers: readonly McpServerSpec[] | undefined;
|
|
240
|
+
readonly tools: ToolsMode | undefined;
|
|
241
|
+
readonly visible: VisibleActions | undefined;
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
/** A watcher gets events, then `undefined` once when the child is gone. */
|
|
245
|
+
type Watcher = (event: LifeEvent | undefined) => void;
|
|
246
|
+
|
|
247
|
+
/** A turn that waits for the running one; an ask also waits for its answer. */
|
|
248
|
+
interface QueuedTurn {
|
|
249
|
+
readonly text: string;
|
|
250
|
+
readonly ask?: { resolve: (end: string) => void; reject: (error: unknown) => void };
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
function asRecord(value: unknown): Record<string, unknown> {
|
|
254
|
+
return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : {};
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
function stringOf(value: unknown): string | undefined {
|
|
258
|
+
return typeof value === "string" && value !== "" ? value : undefined;
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/** How many turn signs are kept for the first watcher of a session. */
|
|
262
|
+
const UNWATCHED_LIMIT = 64;
|
|
263
|
+
|
|
264
|
+
class LiveSession {
|
|
265
|
+
nativeId = "";
|
|
266
|
+
/** The turns niwa has started; the running one, if any, has this number. */
|
|
267
|
+
turn = 0;
|
|
268
|
+
busy = false;
|
|
269
|
+
/** Whether the running turn's start was reported. */
|
|
270
|
+
began = false;
|
|
271
|
+
/** The message of the transcript the running turn began with, once the server has named it. */
|
|
272
|
+
turnMessage: string | undefined;
|
|
273
|
+
stopping = false;
|
|
274
|
+
ended = false;
|
|
275
|
+
/** The surface (servers, allow-list, deny-list) the process was given, as JSON; a resume compares it. */
|
|
276
|
+
surface = "{}";
|
|
277
|
+
/** What the process was launched with. */
|
|
278
|
+
launch: Launch = { env: undefined, box: undefined, servers: undefined, tools: undefined, visible: undefined };
|
|
279
|
+
cwd: string | undefined;
|
|
280
|
+
failure: string | undefined;
|
|
281
|
+
stderrTail = "";
|
|
282
|
+
readonly queue: QueuedTurn[] = [];
|
|
283
|
+
/** The model every send names; none when the session runs the installation's default. */
|
|
284
|
+
selection: ModelSelection | undefined;
|
|
285
|
+
/** The subscription kind the server took. */
|
|
286
|
+
delivery: string | undefined;
|
|
287
|
+
nextId = 1;
|
|
288
|
+
/** Where this session's reverse requests go, when it has been given a place for them. */
|
|
289
|
+
reverse: ReverseHandler | undefined;
|
|
290
|
+
/** The reverse requests waiting for an answer, by the server's own id of them. */
|
|
291
|
+
readonly asking = new Map<string, Asking>();
|
|
292
|
+
/** The answers given to the last requests, by the server's own id of them. */
|
|
293
|
+
readonly settled = new Map<string, Answered>();
|
|
294
|
+
|
|
295
|
+
readonly watchers = new Set<Watcher>();
|
|
296
|
+
/** The turn signs before anyone watched: the first watcher is given them, after it nothing is kept. */
|
|
297
|
+
private unwatched: LifeEvent[] | undefined = [];
|
|
298
|
+
readonly pending = new Map<number, (outcome: Outcome) => void>();
|
|
299
|
+
private readonly turnWaiters: Array<(end: EndedTurn | undefined) => void> = [];
|
|
300
|
+
|
|
301
|
+
constructor(readonly child: AgentProcess) {}
|
|
302
|
+
|
|
303
|
+
watch(watcher: Watcher): void {
|
|
304
|
+
const missed = this.unwatched ?? [];
|
|
305
|
+
this.unwatched = undefined;
|
|
306
|
+
for (const event of missed) watcher(event);
|
|
307
|
+
this.watchers.add(watcher);
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
/** The server stops waiting for a request, or for all of them: what they asked is no longer wanted. */
|
|
311
|
+
cancelAsking(which?: { readonly requestId: string | undefined; readonly toolCallId: string | undefined }): void {
|
|
312
|
+
for (const asking of [...this.asking.values()]) {
|
|
313
|
+
if (which !== undefined) {
|
|
314
|
+
const same = which.requestId !== undefined ? asking.requestId === which.requestId : asking.toolCallId === which.toolCallId;
|
|
315
|
+
if (!same) continue;
|
|
316
|
+
}
|
|
317
|
+
asking.controller.abort();
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
/** Fail every queued ask, and drop the queue; returns how many turns were dropped. */
|
|
322
|
+
dropQueue(reason: string): number {
|
|
323
|
+
const dropped = this.queue.splice(0);
|
|
324
|
+
for (const turn of dropped) turn.ask?.reject(new Error(reason));
|
|
325
|
+
return dropped.length;
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
emit(event: LifeEvent): void {
|
|
329
|
+
if (this.unwatched !== undefined && event.kind !== "activity") {
|
|
330
|
+
this.unwatched.push(event);
|
|
331
|
+
if (this.unwatched.length > UNWATCHED_LIMIT) this.unwatched.shift();
|
|
332
|
+
}
|
|
333
|
+
for (const watcher of [...this.watchers]) {
|
|
334
|
+
try {
|
|
335
|
+
watcher(event);
|
|
336
|
+
} catch {
|
|
337
|
+
// A broken watcher must not break the session.
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
expectTurn(timeoutMs: number): TurnWait {
|
|
343
|
+
if (this.ended) return { done: Promise.resolve(undefined), cancel: () => {} };
|
|
344
|
+
let waiter: (end: EndedTurn | undefined) => void = () => {};
|
|
345
|
+
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
346
|
+
const drop = (): void => {
|
|
347
|
+
clearTimeout(timer);
|
|
348
|
+
const at = this.turnWaiters.indexOf(waiter);
|
|
349
|
+
if (at !== -1) this.turnWaiters.splice(at, 1);
|
|
350
|
+
};
|
|
351
|
+
const done = new Promise<EndedTurn | undefined>((resolve) => {
|
|
352
|
+
waiter = (end) => {
|
|
353
|
+
clearTimeout(timer);
|
|
354
|
+
resolve(end);
|
|
355
|
+
};
|
|
356
|
+
this.turnWaiters.push(waiter);
|
|
357
|
+
timer = setTimeout(() => {
|
|
358
|
+
drop();
|
|
359
|
+
resolve(undefined);
|
|
360
|
+
}, timeoutMs);
|
|
361
|
+
});
|
|
362
|
+
return { done, cancel: drop };
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
settleTurn(end: EndedTurn | undefined): void {
|
|
366
|
+
for (const waiter of this.turnWaiters.splice(0)) waiter(end);
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/** The child is gone: every call in flight and every waiter is released, every watcher told. */
|
|
370
|
+
end(failure?: string): void {
|
|
371
|
+
if (this.ended) return;
|
|
372
|
+
this.ended = true;
|
|
373
|
+
this.busy = false;
|
|
374
|
+
this.cancelAsking();
|
|
375
|
+
const lost = this.dropQueue(failure ?? "the session ended");
|
|
376
|
+
if (failure !== undefined) {
|
|
377
|
+
this.failure = failure;
|
|
378
|
+
this.emit({ kind: "activity", at: Date.now(), detail: failure });
|
|
379
|
+
}
|
|
380
|
+
if (lost > 0) {
|
|
381
|
+
this.emit({ kind: "activity", at: Date.now(), detail: `${lost} queued message(s) were never delivered: the session ended` });
|
|
382
|
+
}
|
|
383
|
+
const reason = this.failure ?? "the session process closed";
|
|
384
|
+
const pending = [...this.pending.values()];
|
|
385
|
+
this.pending.clear();
|
|
386
|
+
for (const settle of pending) settle({ ok: false, error: reason, dispatch: "uncertain" });
|
|
387
|
+
this.settleTurn(undefined);
|
|
388
|
+
for (const watcher of [...this.watchers]) watcher(undefined);
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
/** The control side for ZCode. It owns every process it starts and terminates them itself. */
|
|
393
|
+
export function zcodeControl(options: ZcodeControlOptions): ZcodeSessionControl {
|
|
394
|
+
const binary = options.binary ?? "zcode";
|
|
395
|
+
const permissions = options.permissions ?? "allow";
|
|
396
|
+
const callTimeoutMs = options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
|
|
397
|
+
const turnTimeoutMs = options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
|
|
398
|
+
const stopGraceMs = options.stopGraceMs ?? DEFAULT_STOP_GRACE_MS;
|
|
399
|
+
const harnessId = HarnessIdSchema.parse(options.harness);
|
|
400
|
+
|
|
401
|
+
// The installation is resolved once. The reading side opens its database; the child is told the same
|
|
402
|
+
// directory and database (a child left to itself uses `~/.zcode`). What a box gives it is the
|
|
403
|
+
// installation's profile, resolved with the rest of the box.
|
|
404
|
+
const home = options.home === undefined ? undefined : resolve(options.home);
|
|
405
|
+
const installationEnv: Readonly<Record<string, string>> =
|
|
406
|
+
home === undefined ? {} : { ZCODE_STORAGE_DIR: home, ZCODE_SESSION_DB_PATH: dbPathOf(home) };
|
|
407
|
+
|
|
408
|
+
/** The sessions by id; `owned` also holds those still starting. */
|
|
409
|
+
const sessions = new Map<string, LiveSession>();
|
|
410
|
+
const owned = new Set<LiveSession>();
|
|
411
|
+
/** The launches under way: a process that is being born is not yet in `owned`. */
|
|
412
|
+
const launching = new Set<Promise<unknown>>();
|
|
413
|
+
/** The resumes under way, by session: the last of those waiting for the session's turn at it. */
|
|
414
|
+
const resuming = new Map<string, Promise<void>>();
|
|
415
|
+
let disposed = false;
|
|
416
|
+
|
|
417
|
+
function unavailable(ability: string, detail: string): Unavailable {
|
|
418
|
+
return new Unavailable(harnessId, "control", ability, detail);
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
// -- the client ----------------------------------------------------------
|
|
422
|
+
|
|
423
|
+
function writeLine(session: LiveSession, line: string): void {
|
|
424
|
+
const stdin = session.child.stdin;
|
|
425
|
+
if (stdin === null || stdin.destroyed || session.stopping || session.ended) {
|
|
426
|
+
throw unavailable("send", session.failure ?? "the session is not running");
|
|
427
|
+
}
|
|
428
|
+
stdin.write(`${line}\n`);
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
/** One call, matched to its answer by id. It never rejects. */
|
|
432
|
+
function call(session: LiveSession, method: string, params: Record<string, unknown>): Promise<Outcome> {
|
|
433
|
+
const id = session.nextId;
|
|
434
|
+
session.nextId += 1;
|
|
435
|
+
return new Promise<Outcome>((resolve) => {
|
|
436
|
+
const timer = setTimeout(() => {
|
|
437
|
+
if (session.pending.delete(id)) resolve({ ok: false, error: `the call ${method} timed out`, dispatch: "uncertain" });
|
|
438
|
+
}, callTimeoutMs);
|
|
439
|
+
session.pending.set(id, (outcome) => {
|
|
440
|
+
clearTimeout(timer);
|
|
441
|
+
resolve(outcome);
|
|
442
|
+
});
|
|
443
|
+
try {
|
|
444
|
+
writeLine(session, JSON.stringify({ id, method, params }));
|
|
445
|
+
} catch (error) {
|
|
446
|
+
clearTimeout(timer);
|
|
447
|
+
session.pending.delete(id);
|
|
448
|
+
resolve({ ok: false, error: error instanceof Error ? error.message : String(error), dispatch: "unsent" });
|
|
449
|
+
}
|
|
450
|
+
});
|
|
451
|
+
}
|
|
452
|
+
|
|
453
|
+
// -- the demux ------------------------------------------------------------
|
|
454
|
+
|
|
455
|
+
function handleLine(session: LiveSession, line: string): void {
|
|
456
|
+
if (line.length === 0) return;
|
|
457
|
+
let value: unknown;
|
|
458
|
+
try {
|
|
459
|
+
value = JSON.parse(line);
|
|
460
|
+
} catch (error) {
|
|
461
|
+
session.emit({ kind: "activity", at: Date.now(), detail: `a line of the output stream could not be read: ${String(error)}` });
|
|
462
|
+
return;
|
|
463
|
+
}
|
|
464
|
+
const read = FrameSchema.safeParse(value);
|
|
465
|
+
if (!read.success) {
|
|
466
|
+
session.emit({ kind: "activity", at: Date.now(), detail: `a line of the output stream is not an envelope: ${line.slice(0, 200)}` });
|
|
467
|
+
return;
|
|
468
|
+
}
|
|
469
|
+
const frame = read.data;
|
|
470
|
+
if (frame.method === undefined) {
|
|
471
|
+
if (typeof frame.id !== "number") return;
|
|
472
|
+
const settle = session.pending.get(frame.id);
|
|
473
|
+
if (settle === undefined) return;
|
|
474
|
+
session.pending.delete(frame.id);
|
|
475
|
+
settle(
|
|
476
|
+
frame.error === undefined
|
|
477
|
+
? { ok: true, result: frame.result }
|
|
478
|
+
: {
|
|
479
|
+
ok: false,
|
|
480
|
+
error: frame.error.message ?? "the call failed",
|
|
481
|
+
...(frame.error.code === undefined ? {} : { code: frame.error.code }),
|
|
482
|
+
dispatch: "refused",
|
|
483
|
+
},
|
|
484
|
+
);
|
|
485
|
+
} else if (frame.id !== undefined && frame.id !== null) {
|
|
486
|
+
answerServerRequest(session, frame.id, frame.method, frame.params);
|
|
487
|
+
} else {
|
|
488
|
+
handleNotification(session, frame.method, frame.params);
|
|
489
|
+
}
|
|
490
|
+
}
|
|
491
|
+
|
|
492
|
+
/** A message the snapshot does not know: the typed unknown, and the words of it in the log. */
|
|
493
|
+
function emitUnknown(session: LiveSession, unknown: UnknownVariant): void {
|
|
494
|
+
for (const sign of unknownVariantSigns(Date.now(), ZCODE_PROTOCOL, unknownVariantName(unknown), unknown.raw, unknownDetail(unknown))) {
|
|
495
|
+
session.emit(sign);
|
|
496
|
+
}
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
/**
|
|
500
|
+
* Answer a request the server makes of the client, whichever it is: unanswered, the turn waits
|
|
501
|
+
* forever, and an answer that does not fit the schema of its method is refused by the server.
|
|
502
|
+
* What each request comes to is `requestAction`'s: a permission and a question go to the place
|
|
503
|
+
* the session's reverse requests go, and a session with none answers a permission by its policy
|
|
504
|
+
* and declines a question, since nobody is there to ask. A request the snapshot does not know
|
|
505
|
+
* gets an empty answer, which the server takes (the language of the reply), and is told in the log.
|
|
506
|
+
*/
|
|
507
|
+
function answerServerRequest(session: LiveSession, id: number | string, method: string, params: unknown): void {
|
|
508
|
+
const read = readRequest(id, method, params);
|
|
509
|
+
if (read.unknown !== undefined) emitUnknown(session, read.unknown);
|
|
510
|
+
const action = requestAction(read.request, { asksQuestions: session.reverse !== undefined });
|
|
511
|
+
switch (action.do) {
|
|
512
|
+
case "answer":
|
|
513
|
+
reply(session, [id], action.result);
|
|
514
|
+
return;
|
|
515
|
+
case "error":
|
|
516
|
+
replyError(session, id, action.code, action.message);
|
|
517
|
+
return;
|
|
518
|
+
case "permission":
|
|
519
|
+
if (session.reverse !== undefined) void askPermission(session, session.reverse, id, action.params, params);
|
|
520
|
+
else reply(session, [id], { decision: permissions, reason: `niwa ${permissions === "allow" ? "allowed" : "denied"} this request` });
|
|
521
|
+
return;
|
|
522
|
+
case "user-input":
|
|
523
|
+
if (session.reverse !== undefined) void askUserInput(session, session.reverse, id, action.params, params);
|
|
524
|
+
else reply(session, [id], { action: "decline", reason: "niwa has no one to ask" });
|
|
525
|
+
return;
|
|
526
|
+
default:
|
|
527
|
+
assertNever(action, "request action");
|
|
528
|
+
}
|
|
529
|
+
}
|
|
530
|
+
|
|
531
|
+
/** Answer the server's requests, once each; a child that is going away has nobody to answer. */
|
|
532
|
+
function reply(session: LiveSession, ids: readonly (number | string)[], result: Answered): void {
|
|
533
|
+
for (const id of ids) {
|
|
534
|
+
try {
|
|
535
|
+
writeLine(session, JSON.stringify({ id, result }));
|
|
536
|
+
} catch {
|
|
537
|
+
// The child is going away; there is no one to answer.
|
|
538
|
+
}
|
|
539
|
+
}
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
/** Refuse a request the way JSON-RPC does: with an error in place of a result. */
|
|
543
|
+
function replyError(session: LiveSession, id: number | string, code: number, message: string): void {
|
|
544
|
+
try {
|
|
545
|
+
writeLine(session, JSON.stringify({ id, error: { code, message } }));
|
|
546
|
+
} catch {
|
|
547
|
+
// The child is going away; there is no one to answer.
|
|
548
|
+
}
|
|
549
|
+
}
|
|
550
|
+
|
|
551
|
+
/**
|
|
552
|
+
* Begin to wait for the answer to a request. The server announces a request again, under a new id,
|
|
553
|
+
* while it waits for it: that is the same request, answered when the first is. Nothing is returned
|
|
554
|
+
* for an announcement of a request already waited for, or already answered.
|
|
555
|
+
*/
|
|
556
|
+
function beginAsking(session: LiveSession, id: number | string, requestId: string, toolCallId: string | undefined): Asking | undefined {
|
|
557
|
+
const waiting = session.asking.get(requestId);
|
|
558
|
+
if (waiting !== undefined) {
|
|
559
|
+
waiting.ids.push(id);
|
|
560
|
+
return undefined;
|
|
561
|
+
}
|
|
562
|
+
const answered = session.settled.get(requestId);
|
|
563
|
+
if (answered !== undefined) {
|
|
564
|
+
reply(session, [id], answered);
|
|
565
|
+
return undefined;
|
|
566
|
+
}
|
|
567
|
+
const asking: Asking = { requestId, toolCallId, ids: [id], controller: new AbortController() };
|
|
568
|
+
session.asking.set(requestId, asking);
|
|
569
|
+
return asking;
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
/** The request is answered: every id it was announced under gets the answer. */
|
|
573
|
+
function endAsking(session: LiveSession, asking: Asking, answer: Answered): void {
|
|
574
|
+
session.asking.delete(asking.requestId);
|
|
575
|
+
session.settled.set(asking.requestId, answer);
|
|
576
|
+
if (session.settled.size > SETTLED_LIMIT) {
|
|
577
|
+
const oldest = session.settled.keys().next().value;
|
|
578
|
+
if (oldest !== undefined) session.settled.delete(oldest);
|
|
579
|
+
}
|
|
580
|
+
reply(session, asking.ids, answer);
|
|
581
|
+
}
|
|
582
|
+
|
|
583
|
+
/**
|
|
584
|
+
* Hand a question to the place a session's reverse requests go, and wait for the answer.
|
|
585
|
+
* The server's wait is the request's: the signal is aborted when the server stops waiting. A
|
|
586
|
+
* handler that fails answers nothing.
|
|
587
|
+
*/
|
|
588
|
+
async function reverseAnswer(
|
|
589
|
+
session: LiveSession,
|
|
590
|
+
handler: ReverseHandler,
|
|
591
|
+
asking: Asking,
|
|
592
|
+
question: Question,
|
|
593
|
+
raw: { readonly method: string; readonly params: unknown },
|
|
594
|
+
): Promise<Answer> {
|
|
595
|
+
try {
|
|
596
|
+
return await handler(makeSessionId(harnessId, session.nativeId), { question, raw, signal: asking.controller.signal });
|
|
597
|
+
} catch {
|
|
598
|
+
return { cancelled: true };
|
|
599
|
+
}
|
|
600
|
+
}
|
|
601
|
+
|
|
602
|
+
/** A permission request, as a question for whoever answers for the session. */
|
|
603
|
+
async function askPermission(
|
|
604
|
+
session: LiveSession,
|
|
605
|
+
handler: ReverseHandler,
|
|
606
|
+
id: number | string,
|
|
607
|
+
request: RequestPermissionParams,
|
|
608
|
+
raw: unknown,
|
|
609
|
+
): Promise<void> {
|
|
610
|
+
const read = readPermission(request);
|
|
611
|
+
const asking = beginAsking(session, id, read.requestId, read.toolCallId);
|
|
612
|
+
if (asking === undefined) return;
|
|
613
|
+
const answer = await reverseAnswer(session, handler, asking, read.ask.question, { method: "interaction/requestPermission", params: raw });
|
|
614
|
+
endAsking(session, asking, read.ask.answer(answer));
|
|
615
|
+
}
|
|
616
|
+
|
|
617
|
+
/**
|
|
618
|
+
* A user input request: its questions go one by one, each as a question of its own, and the answers
|
|
619
|
+
* go back together. A question left with no answer, or one the server stopped waiting for, ends the request.
|
|
620
|
+
*/
|
|
621
|
+
async function askUserInput(
|
|
622
|
+
session: LiveSession,
|
|
623
|
+
handler: ReverseHandler,
|
|
624
|
+
id: number | string,
|
|
625
|
+
request: RequestUserInputParams,
|
|
626
|
+
raw: unknown,
|
|
627
|
+
): Promise<void> {
|
|
628
|
+
const read = readUserInput(request);
|
|
629
|
+
const asking = beginAsking(session, id, read.requestId, read.toolCallId);
|
|
630
|
+
if (asking === undefined) return;
|
|
631
|
+
const texts: string[] = [];
|
|
632
|
+
for (const entry of read.ask.questions) {
|
|
633
|
+
const answer = asking.controller.signal.aborted
|
|
634
|
+
? ({ cancelled: true } as const)
|
|
635
|
+
: await reverseAnswer(session, handler, asking, entry.question, { method: "interaction/requestUserInput", params: raw });
|
|
636
|
+
const text = entry.textOf(answer);
|
|
637
|
+
if (text === undefined) {
|
|
638
|
+
endAsking(session, asking, INPUT_CANCELLED);
|
|
639
|
+
return;
|
|
640
|
+
}
|
|
641
|
+
texts.push(text);
|
|
642
|
+
}
|
|
643
|
+
endAsking(session, asking, read.ask.answer(texts));
|
|
644
|
+
}
|
|
645
|
+
|
|
646
|
+
/**
|
|
647
|
+
* The notifications of the server: the end of a turn matters, the rest is a sign of life or nothing.
|
|
648
|
+
* What each comes to is `notificationAction`'s; what the snapshot does not know is told in the log.
|
|
649
|
+
*/
|
|
650
|
+
function handleNotification(session: LiveSession, method: string, params: unknown): void {
|
|
651
|
+
const read = readNotification(method, params);
|
|
652
|
+
switch (read.kind) {
|
|
653
|
+
case "known":
|
|
654
|
+
break;
|
|
655
|
+
// The conversation view of ZCode's own desktop: nothing a session's driver has use for.
|
|
656
|
+
case "side-channel":
|
|
657
|
+
return;
|
|
658
|
+
case "unknown":
|
|
659
|
+
emitUnknown(session, read.unknown);
|
|
660
|
+
return;
|
|
661
|
+
default:
|
|
662
|
+
assertNever(read, "notification");
|
|
663
|
+
}
|
|
664
|
+
const notification = read.notification;
|
|
665
|
+
const action = notificationAction(notification);
|
|
666
|
+
// The server says it no longer waits for a request when it resolves it, by whom or why: that is
|
|
667
|
+
// all niwa sees of a cancel. A subagent's request is asked under this session, so it is closed by its id.
|
|
668
|
+
if (action.do === "stop-asking") {
|
|
669
|
+
if (action.requestId !== undefined || action.toolCallId !== undefined) {
|
|
670
|
+
session.cancelAsking({ requestId: action.requestId, toolCallId: action.toolCallId });
|
|
671
|
+
}
|
|
672
|
+
session.emit({ kind: "activity", at: Date.now(), detail: action.detail });
|
|
673
|
+
return;
|
|
674
|
+
}
|
|
675
|
+
// A subagent's turn is not this session's.
|
|
676
|
+
if (notification.method === "session/event" && notification.params.sessionId !== session.nativeId) return;
|
|
677
|
+
if (notification.method === "session/event" && notification.params.type === "turn.started") {
|
|
678
|
+
session.turnMessage = notification.params.payload?.messageId;
|
|
679
|
+
}
|
|
680
|
+
switch (action.do) {
|
|
681
|
+
case "end-turn":
|
|
682
|
+
endTurn(session, action.end);
|
|
683
|
+
return;
|
|
684
|
+
case "activity":
|
|
685
|
+
session.emit({ kind: "activity", at: Date.now(), detail: action.detail });
|
|
686
|
+
return;
|
|
687
|
+
case "ignore":
|
|
688
|
+
return;
|
|
689
|
+
default:
|
|
690
|
+
assertNever(action, "notification action");
|
|
691
|
+
}
|
|
692
|
+
}
|
|
693
|
+
|
|
694
|
+
function endTurn(session: LiveSession, end: TurnEnd): void {
|
|
695
|
+
const at = Date.now();
|
|
696
|
+
// The turn is over: nothing it asked is waited for any more.
|
|
697
|
+
session.cancelAsking();
|
|
698
|
+
// An end with no turn running ends nothing: it is a stray, and a sign of life at most.
|
|
699
|
+
if (!session.busy) {
|
|
700
|
+
session.emit({ kind: "activity", at, detail: `a turn ended while none was running (${end.outcome})` });
|
|
701
|
+
return;
|
|
702
|
+
}
|
|
703
|
+
// The end of a turn that came before the answer to its send is still preceded by its start.
|
|
704
|
+
if (!session.began) {
|
|
705
|
+
session.began = true;
|
|
706
|
+
session.emit({ kind: "turn-started", turn: session.turn, at });
|
|
707
|
+
}
|
|
708
|
+
session.busy = false;
|
|
709
|
+
if (end.error !== undefined) session.emit({ kind: "activity", at, detail: end.error });
|
|
710
|
+
// A turn that was cut or broke did not complete.
|
|
711
|
+
session.emit({ kind: "turn-ended", turn: session.turn, at, outcome: end.outcome === "completed" ? "completed" : "failed" });
|
|
712
|
+
session.settleTurn({ ...end, messageId: session.turnMessage });
|
|
713
|
+
// A message that waited for this turn becomes a turn of its own.
|
|
714
|
+
drainQueue(session);
|
|
715
|
+
}
|
|
716
|
+
|
|
717
|
+
// -- the child ------------------------------------------------------------
|
|
718
|
+
|
|
719
|
+
function hasExited(session: LiveSession): boolean {
|
|
720
|
+
return session.child.exitCode !== null || session.child.signalCode !== null;
|
|
721
|
+
}
|
|
722
|
+
|
|
723
|
+
function signalGroup(session: LiveSession, pid: number, signal: NodeJS.Signals): void {
|
|
724
|
+
try {
|
|
725
|
+
process.kill(-pid, signal);
|
|
726
|
+
} catch {
|
|
727
|
+
try {
|
|
728
|
+
session.child.kill(signal);
|
|
729
|
+
} catch {
|
|
730
|
+
// Already gone.
|
|
731
|
+
}
|
|
732
|
+
}
|
|
733
|
+
}
|
|
734
|
+
|
|
735
|
+
function waitForExit(session: LiveSession, timeoutMs: number): Promise<boolean> {
|
|
736
|
+
if (hasExited(session)) return Promise.resolve(true);
|
|
737
|
+
return new Promise<boolean>((resolve) => {
|
|
738
|
+
const onClose = (): void => {
|
|
739
|
+
clearTimeout(timer);
|
|
740
|
+
resolve(true);
|
|
741
|
+
};
|
|
742
|
+
const timer = setTimeout(() => {
|
|
743
|
+
session.child.off("close", onClose);
|
|
744
|
+
resolve(false);
|
|
745
|
+
}, timeoutMs);
|
|
746
|
+
session.child.once("close", onClose);
|
|
747
|
+
});
|
|
748
|
+
}
|
|
749
|
+
|
|
750
|
+
/** Ends the input and lets the child drain, then SIGTERM to the process group, then SIGKILL. */
|
|
751
|
+
async function stopSession(session: LiveSession): Promise<void> {
|
|
752
|
+
const pid = session.child.pid;
|
|
753
|
+
session.stopping = true;
|
|
754
|
+
if (pid === undefined) {
|
|
755
|
+
session.end();
|
|
756
|
+
return;
|
|
757
|
+
}
|
|
758
|
+
if (!hasExited(session)) {
|
|
759
|
+
session.child.stdin?.end();
|
|
760
|
+
if (!(await waitForExit(session, stopGraceMs))) {
|
|
761
|
+
signalGroup(session, pid, "SIGTERM");
|
|
762
|
+
if (!(await waitForExit(session, stopGraceMs))) {
|
|
763
|
+
signalGroup(session, pid, "SIGKILL");
|
|
764
|
+
await waitForExit(session, stopGraceMs);
|
|
765
|
+
}
|
|
766
|
+
}
|
|
767
|
+
}
|
|
768
|
+
// What the child started may outlive the leader.
|
|
769
|
+
signalGroup(session, pid, "SIGKILL");
|
|
770
|
+
session.end();
|
|
771
|
+
}
|
|
772
|
+
|
|
773
|
+
/** Spawns a child and pings it. A child that does not answer is stopped. */
|
|
774
|
+
async function spawnSession(cwd: string | undefined, plan: Pick<StartOptions, "env" | "box">): Promise<LiveSession> {
|
|
775
|
+
const launch = launchSession(cwd, plan);
|
|
776
|
+
launching.add(launch);
|
|
777
|
+
try {
|
|
778
|
+
return await launch;
|
|
779
|
+
} finally {
|
|
780
|
+
launching.delete(launch);
|
|
781
|
+
}
|
|
782
|
+
}
|
|
783
|
+
|
|
784
|
+
async function launchSession(cwd: string | undefined, plan: Pick<StartOptions, "env" | "box">): Promise<LiveSession> {
|
|
785
|
+
if (disposed) throw unavailable("start", "the control side is disposed");
|
|
786
|
+
const child = await spawnAgent({
|
|
787
|
+
harness: harnessId,
|
|
788
|
+
program: binary,
|
|
789
|
+
args: ["app-server", "--stdio", ...(cwd === undefined ? [] : ["--cwd", cwd])],
|
|
790
|
+
cwd,
|
|
791
|
+
// Its own process group, so a stop reaches everything ZCode started and nothing else.
|
|
792
|
+
detached: true,
|
|
793
|
+
// The installation comes last: a child that kept to another one would write where the reader does not look.
|
|
794
|
+
env: { ...plan.env, ...installationEnv },
|
|
795
|
+
box: plan.box,
|
|
796
|
+
});
|
|
797
|
+
const session = new LiveSession(child);
|
|
798
|
+
owned.add(session);
|
|
799
|
+
|
|
800
|
+
let buffer = "";
|
|
801
|
+
child.stdout.setEncoding("utf8");
|
|
802
|
+
child.stdout.on("data", (chunk: string) => {
|
|
803
|
+
buffer += chunk;
|
|
804
|
+
for (let newline = buffer.indexOf("\n"); newline !== -1; newline = buffer.indexOf("\n")) {
|
|
805
|
+
const line = buffer.slice(0, newline).trim();
|
|
806
|
+
buffer = buffer.slice(newline + 1);
|
|
807
|
+
try {
|
|
808
|
+
handleLine(session, line);
|
|
809
|
+
} catch (error) {
|
|
810
|
+
session.emit({ kind: "activity", at: Date.now(), detail: `a frame failed: ${String(error)}` });
|
|
811
|
+
}
|
|
812
|
+
}
|
|
813
|
+
if (buffer.length > MAX_FRAME_BYTES) {
|
|
814
|
+
buffer = "";
|
|
815
|
+
session.end("a line of the output stream was longer than the frame budget");
|
|
816
|
+
void stopSession(session);
|
|
817
|
+
}
|
|
818
|
+
});
|
|
819
|
+
child.stderr.setEncoding("utf8");
|
|
820
|
+
child.stderr.on("data", (chunk: string) => {
|
|
821
|
+
session.stderrTail = (session.stderrTail + chunk).slice(-STDERR_TAIL_CHARS);
|
|
822
|
+
});
|
|
823
|
+
// A write to a dead child is reported by the closing child, not thrown as an unhandled event.
|
|
824
|
+
child.stdin.on("error", () => {});
|
|
825
|
+
child.on("error", (error) => {
|
|
826
|
+
owned.delete(session);
|
|
827
|
+
session.end(`the session process failed: ${error.message}`);
|
|
828
|
+
});
|
|
829
|
+
child.on("close", (code, signal) => {
|
|
830
|
+
owned.delete(session);
|
|
831
|
+
if (child.pid !== undefined) signalGroup(session, child.pid, "SIGKILL");
|
|
832
|
+
session.end(
|
|
833
|
+
session.stopping ? "the session was stopped" : `the session process exited (${code ?? signal}): ${session.stderrTail.trim()}`,
|
|
834
|
+
);
|
|
835
|
+
});
|
|
836
|
+
|
|
837
|
+
// The control side was disposed while the process was being born: it is not served, and not left running.
|
|
838
|
+
if (disposed) {
|
|
839
|
+
await stopSession(session);
|
|
840
|
+
throw unavailable("start", "the control side was disposed while the process was starting");
|
|
841
|
+
}
|
|
842
|
+
|
|
843
|
+
// Ready is an answer that is a capabilities report: anything else is not an app-server of ZCode.
|
|
844
|
+
const ready = await call(session, "runtime/capabilities", {});
|
|
845
|
+
const report = ready.ok ? CapabilitiesSchema.safeParse(ready.result) : undefined;
|
|
846
|
+
if (!ready.ok || report?.success !== true) {
|
|
847
|
+
await stopSession(session);
|
|
848
|
+
throw unavailable("start", ready.ok ? "the CLI answered the readiness ping with no capabilities report" : (ready.error ?? "the CLI did not answer the readiness ping"));
|
|
849
|
+
}
|
|
850
|
+
return session;
|
|
851
|
+
}
|
|
852
|
+
|
|
853
|
+
/** Subscribes to the events of a session: without it the server streams none, and no turn can be seen to end. */
|
|
854
|
+
async function subscribe(session: LiveSession): Promise<void> {
|
|
855
|
+
let refusal: string | undefined;
|
|
856
|
+
for (const deliveryKind of DELIVERY_KINDS) {
|
|
857
|
+
const subscribed = await call(session, "session/subscribe", {
|
|
858
|
+
sessionId: session.nativeId,
|
|
859
|
+
deliveryKind,
|
|
860
|
+
includeSnapshot: false,
|
|
861
|
+
});
|
|
862
|
+
if (subscribed.ok) {
|
|
863
|
+
session.delivery = deliveryKind;
|
|
864
|
+
return;
|
|
865
|
+
}
|
|
866
|
+
refusal = subscribed.error;
|
|
867
|
+
}
|
|
868
|
+
throw unavailable("start", refusal ?? "the CLI took no subscription to the events of the session");
|
|
869
|
+
}
|
|
870
|
+
|
|
871
|
+
// -- the turns ------------------------------------------------------------
|
|
872
|
+
|
|
873
|
+
function promptText(prompt: Prompt): string {
|
|
874
|
+
return prompt.sections.map((section) => section.text).join("\n\n");
|
|
875
|
+
}
|
|
876
|
+
|
|
877
|
+
/**
|
|
878
|
+
* Ask ZCode to take a message as a turn. The wait for the turn's end is registered before the
|
|
879
|
+
* request is written, so a turn that ends in the same read as its answer is not missed.
|
|
880
|
+
*/
|
|
881
|
+
async function startTurn(session: LiveSession, text: string): Promise<{ turn: number; wait: TurnWait }> {
|
|
882
|
+
if (session.busy) throw new InputNotSent(harnessId, "send", "a turn is already running");
|
|
883
|
+
session.turn += 1;
|
|
884
|
+
session.busy = true;
|
|
885
|
+
session.began = false;
|
|
886
|
+
session.turnMessage = undefined;
|
|
887
|
+
const turn = session.turn;
|
|
888
|
+
const wait = session.expectTurn(turnTimeoutMs);
|
|
889
|
+
const params: Record<string, unknown> = { sessionId: session.nativeId, content: text };
|
|
890
|
+
if (session.selection !== undefined) params["modelSelection"] = session.selection;
|
|
891
|
+
const sent = await call(session, "session/send", params);
|
|
892
|
+
// An answer that is no acceptance of this session's message, after the message was written, may
|
|
893
|
+
// be an acceptance that was garbled: the message may be running.
|
|
894
|
+
const accepted = sent.ok ? SendAckSchema.safeParse(sent.result) : undefined;
|
|
895
|
+
const answer: Outcome =
|
|
896
|
+
accepted === undefined || (accepted.success && accepted.data.sessionId === session.nativeId)
|
|
897
|
+
? sent
|
|
898
|
+
: { ok: false, error: "the CLI's answer to the send was not an acceptance of it", dispatch: "uncertain" };
|
|
899
|
+
if (!answer.ok) {
|
|
900
|
+
const dispatch = answer.dispatch ?? "uncertain";
|
|
901
|
+
const failure = inputFailure(harnessId, "send", dispatch, answer.error ?? "the CLI refused the message");
|
|
902
|
+
if (dispatch === "uncertain") {
|
|
903
|
+
// The message may be a turn that is running: the session stays busy, so a later turn is not
|
|
904
|
+
// taken for it and what is queued waits. Its end releases the session; if none comes, the
|
|
905
|
+
// timeout of the turn does, which is all this side can tell.
|
|
906
|
+
void wait.done.then((end) => {
|
|
907
|
+
if (end !== undefined || session.ended || session.turn !== turn || !session.busy) return;
|
|
908
|
+
session.busy = false;
|
|
909
|
+
session.emit({ kind: "activity", at: Date.now(), detail: `turn ${turn} never reported its end: the session is taken for idle` });
|
|
910
|
+
drainQueue(session);
|
|
911
|
+
});
|
|
912
|
+
throw failure;
|
|
913
|
+
}
|
|
914
|
+
// The message was never taken: its turn never was, and what waited behind it goes on.
|
|
915
|
+
wait.cancel();
|
|
916
|
+
if (session.turn === turn) session.busy = false;
|
|
917
|
+
drainQueue(session);
|
|
918
|
+
throw failure;
|
|
919
|
+
}
|
|
920
|
+
if (!session.began && session.turn === turn) {
|
|
921
|
+
session.began = true;
|
|
922
|
+
session.emit({ kind: "turn-started", turn, at: Date.now() });
|
|
923
|
+
}
|
|
924
|
+
return { turn, wait };
|
|
925
|
+
}
|
|
926
|
+
|
|
927
|
+
/** Wait for a started turn; anything but a completed turn is an error. Returns its answer. */
|
|
928
|
+
async function finishTurn(session: LiveSession, wait: TurnWait, text: string): Promise<string> {
|
|
929
|
+
const end = await wait.done;
|
|
930
|
+
if (end === undefined) throw unavailable("send", session.failure ?? "the turn did not end");
|
|
931
|
+
if (end.outcome !== "completed") throw unavailable("send", `the turn was ${end.outcome}: ${end.error ?? "no reason given"}`);
|
|
932
|
+
return end.response !== "" ? end.response : await turnAnswer(session, end.messageId, text);
|
|
933
|
+
}
|
|
934
|
+
|
|
935
|
+
/**
|
|
936
|
+
* The answer of one turn, read back from the transcript when the end of the turn carried none: the
|
|
937
|
+
* last text of the assistant messages that answer the message the turn began with. That message is
|
|
938
|
+
* the one the server named when the turn started, else the last one that said what was sent. A turn
|
|
939
|
+
* that left no text of its own has none: the text of another turn is never its answer.
|
|
940
|
+
*/
|
|
941
|
+
async function turnAnswer(session: LiveSession, started: string | undefined, sent: string): Promise<string> {
|
|
942
|
+
const read = await call(session, "session/messages", { sessionId: session.nativeId });
|
|
943
|
+
const messages = MessagesResultSchema.safeParse(read.result);
|
|
944
|
+
if (!read.ok || !messages.success) return "";
|
|
945
|
+
const known: Array<z.output<typeof SessionMessageSchema>> = [];
|
|
946
|
+
for (const item of messages.data.messages) {
|
|
947
|
+
const message = SessionMessageSchema.safeParse(item);
|
|
948
|
+
if (message.success) {
|
|
949
|
+
known.push(message.data);
|
|
950
|
+
continue;
|
|
951
|
+
}
|
|
952
|
+
// One message the snapshot does not know costs that message, not the answer.
|
|
953
|
+
const unknown: UnknownVariant = { protocol: "zcode", discriminator: "method", value: "session/messages", why: "does not fit the snapshot", raw: item };
|
|
954
|
+
emitUnknown(session, unknown);
|
|
955
|
+
}
|
|
956
|
+
const textOf = (message: z.output<typeof SessionMessageSchema>): string =>
|
|
957
|
+
message.parts.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("");
|
|
958
|
+
const beginning =
|
|
959
|
+
started ?? known.findLast((message) => message.info.role === "user" && textOf(message).trim() === sent.trim())?.info.messageId;
|
|
960
|
+
if (beginning === undefined) return "";
|
|
961
|
+
let answer = "";
|
|
962
|
+
for (const message of known) {
|
|
963
|
+
if (message.info.role !== "assistant" || message.info.parentMessageId !== beginning) continue;
|
|
964
|
+
const text = textOf(message);
|
|
965
|
+
if (text.trim() !== "") answer = text;
|
|
966
|
+
}
|
|
967
|
+
return answer;
|
|
968
|
+
}
|
|
969
|
+
|
|
970
|
+
async function runTurn(session: LiveSession, text: string): Promise<string> {
|
|
971
|
+
const { wait } = await startTurn(session, text);
|
|
972
|
+
return finishTurn(session, wait, text);
|
|
973
|
+
}
|
|
974
|
+
|
|
975
|
+
/**
|
|
976
|
+
* Starts the turn that waited for the turn that just ended, in the order the messages came.
|
|
977
|
+
* The caller of a message does not wait for its turn; the caller of an ask waits for the answer.
|
|
978
|
+
*/
|
|
979
|
+
function drainQueue(session: LiveSession): void {
|
|
980
|
+
if (session.ended || session.stopping) return;
|
|
981
|
+
const next = session.queue.shift();
|
|
982
|
+
if (next === undefined) return;
|
|
983
|
+
void startTurn(session, next.text)
|
|
984
|
+
.then(({ wait }) => {
|
|
985
|
+
if (next.ask === undefined) {
|
|
986
|
+
wait.cancel();
|
|
987
|
+
return undefined;
|
|
988
|
+
}
|
|
989
|
+
return finishTurn(session, wait, next.text).then(next.ask.resolve, next.ask.reject);
|
|
990
|
+
})
|
|
991
|
+
.catch((error: unknown) => {
|
|
992
|
+
next.ask?.reject(error);
|
|
993
|
+
// The messages behind it are released by the start that failed, when its message was never taken.
|
|
994
|
+
session.emit({ kind: "activity", at: Date.now(), detail: `a queued message could not be started: ${String(error)}` });
|
|
995
|
+
});
|
|
996
|
+
}
|
|
997
|
+
|
|
998
|
+
/** Deliver a message the way a send does and say what became of it; nothing waits for the turn to end. */
|
|
999
|
+
async function deliver(session: LiveSession, message: string): Promise<DeliveryReceipt> {
|
|
1000
|
+
const at = Date.now();
|
|
1001
|
+
if (session.busy) {
|
|
1002
|
+
session.queue.push({ text: message });
|
|
1003
|
+
return { status: "queued", turn: session.turn + session.queue.length, at };
|
|
1004
|
+
}
|
|
1005
|
+
const { turn, wait } = await startTurn(session, message);
|
|
1006
|
+
wait.cancel();
|
|
1007
|
+
return { status: "started", turn, at };
|
|
1008
|
+
}
|
|
1009
|
+
|
|
1010
|
+
/**
|
|
1011
|
+
* Put a message into the turn that runs. ZCode refuses a `session/send` while a prompt runs, so this
|
|
1012
|
+
* is a `sendText` command that asks for the delivery `guide`; its acknowledgement says what became of
|
|
1013
|
+
* it. A ZCode that has no such command refuses by name, and nothing is sent.
|
|
1014
|
+
*/
|
|
1015
|
+
async function steer(session: LiveSession, message: string): Promise<DeliveryReceipt> {
|
|
1016
|
+
const at = Date.now();
|
|
1017
|
+
const turn = session.turn;
|
|
1018
|
+
const sent = await call(session, "v4/command", {
|
|
1019
|
+
...(session.cwd === undefined ? {} : wire(session.cwd)),
|
|
1020
|
+
commandId: `niwa-${randomUUID()}`,
|
|
1021
|
+
clientId: "niwa",
|
|
1022
|
+
sessionId: session.nativeId,
|
|
1023
|
+
type: "sendText",
|
|
1024
|
+
payload: { text: message, requestedDelivery: "guide" },
|
|
1025
|
+
issuedAt: at,
|
|
1026
|
+
});
|
|
1027
|
+
if (!sent.ok) {
|
|
1028
|
+
if (sent.code === METHOD_NOT_FOUND) {
|
|
1029
|
+
throw new Unsupported(harnessId, "control", "send", "this ZCode cannot steer a running turn: it has no v4/command");
|
|
1030
|
+
}
|
|
1031
|
+
throw inputFailure(harnessId, "send", sent.dispatch ?? "uncertain", sent.error ?? "the CLI refused the message");
|
|
1032
|
+
}
|
|
1033
|
+
// An answer that is no acknowledgement of the command is taken for a message that may have gone.
|
|
1034
|
+
const ack = CommandAckSchema.safeParse(sent.result);
|
|
1035
|
+
if (!ack.success) throw inputFailure(harnessId, "send", "uncertain", "the CLI's answer to the steer was not an acknowledgement");
|
|
1036
|
+
switch (ack.data.status) {
|
|
1037
|
+
case "accepted":
|
|
1038
|
+
case "duplicate":
|
|
1039
|
+
// The turn ended on its way: ZCode began a turn of the message instead of steering the old one.
|
|
1040
|
+
return ack.data.result?.delivery === "startNow" ? { status: "started", at } : { status: "delivered", turn, at };
|
|
1041
|
+
case "rejected":
|
|
1042
|
+
case "stale":
|
|
1043
|
+
case "noop":
|
|
1044
|
+
case "failed":
|
|
1045
|
+
throw new InputNotSent(harnessId, "send", `the CLI did not take the steer (${ack.data.status}): ${ack.data.reasonCode ?? ack.data.message ?? "no reason given"}`);
|
|
1046
|
+
default:
|
|
1047
|
+
return assertNever(ack.data.status, "command status");
|
|
1048
|
+
}
|
|
1049
|
+
}
|
|
1050
|
+
|
|
1051
|
+
function requireSession(id: SessionId, ability: string): LiveSession {
|
|
1052
|
+
const session = sessions.get(id.native);
|
|
1053
|
+
if (session === undefined) throw unavailable(ability, `the session ${id.native} is not held by this control side`);
|
|
1054
|
+
return session;
|
|
1055
|
+
}
|
|
1056
|
+
|
|
1057
|
+
/** The model and level a session's sends name; `reported` is the model the server says the session has. */
|
|
1058
|
+
function selectionOf(model: string | undefined, effort: string | undefined, reported: ModelRef | undefined): ModelSelection | undefined {
|
|
1059
|
+
const ref = model === undefined || model === "" ? reported : parseModel(harnessId, model);
|
|
1060
|
+
const level = effort === undefined || effort === "" ? undefined : effort;
|
|
1061
|
+
if (ref === undefined) {
|
|
1062
|
+
if (level === undefined) return undefined;
|
|
1063
|
+
throw new Unsupported(harnessId, "control", "start", `the effort "${level}" needs a model: none was chosen and the CLI named none`);
|
|
1064
|
+
}
|
|
1065
|
+
// No model chosen and no level: the session runs what the installation has, and the sends say nothing.
|
|
1066
|
+
if (ref === reported && level === undefined) return undefined;
|
|
1067
|
+
return { ...ref, ...(level === undefined ? {} : { options: { reasoningLevel: level } }) };
|
|
1068
|
+
}
|
|
1069
|
+
|
|
1070
|
+
const wire = (cwd: string): { workspace: { workspacePath: string; workspaceKey: string } } => ({
|
|
1071
|
+
workspace: { workspacePath: cwd, workspaceKey: cwd },
|
|
1072
|
+
});
|
|
1073
|
+
|
|
1074
|
+
/**
|
|
1075
|
+
* The model the snapshot of a session names is the model it runs only when no model was asked
|
|
1076
|
+
* for: a model that was asked for goes with every send, and ZCode names none back, so the
|
|
1077
|
+
* model of such a session is not known and the request is not taken for it.
|
|
1078
|
+
*/
|
|
1079
|
+
function reportModel(session: LiveSession, asked: string | undefined, reported: ModelRef | undefined): void {
|
|
1080
|
+
if ((asked === undefined || asked === "") && reported !== undefined) {
|
|
1081
|
+
session.emit({ kind: "model", model: modelName(`${reported.providerId}/${reported.modelId}`) });
|
|
1082
|
+
}
|
|
1083
|
+
}
|
|
1084
|
+
|
|
1085
|
+
/**
|
|
1086
|
+
* Takes the session on in a process of this side, and says what is left to do once it is: the turn of
|
|
1087
|
+
* the resume's prompt, which the caller runs after letting go of the session.
|
|
1088
|
+
*/
|
|
1089
|
+
async function resumeSession(id: SessionId, resumeOptions?: ResumeOptions): Promise<(() => Promise<void>) | undefined> {
|
|
1090
|
+
const text = resumeOptions?.prompt === undefined ? "" : promptText(resumeOptions.prompt);
|
|
1091
|
+
const named = surfaceOf(resumeOptions?.servers, resumeOptions?.tools, resumeOptions?.visible, options.mcp);
|
|
1092
|
+
let launch: Launch = {
|
|
1093
|
+
env: resumeOptions?.env,
|
|
1094
|
+
box: resumeOptions?.box,
|
|
1095
|
+
servers: resumeOptions?.servers,
|
|
1096
|
+
tools: resumeOptions?.tools,
|
|
1097
|
+
visible: resumeOptions?.visible,
|
|
1098
|
+
};
|
|
1099
|
+
|
|
1100
|
+
// A held session continues in its own child: a second child would be a second writer.
|
|
1101
|
+
const held = sessions.get(id.native);
|
|
1102
|
+
let carried: Watcher[] = [];
|
|
1103
|
+
if (held !== undefined && !held.ended && !held.stopping) {
|
|
1104
|
+
if (resumeOptions?.box !== undefined) throw new Unsupported(harnessId, "control", "resume", LIVE_PROCESS_REFUSAL);
|
|
1105
|
+
// What the process was born with is what it keeps: a surface that is the same changes
|
|
1106
|
+
// nothing, and one that differs is given to a new process, which takes the session on
|
|
1107
|
+
// again. That cannot be done under a running turn. What the resume does not name stays as it
|
|
1108
|
+
// was: the new process gets the box, the environment and the restrictions of the old one.
|
|
1109
|
+
launch = {
|
|
1110
|
+
env: resumeOptions?.env ?? held.launch.env,
|
|
1111
|
+
box: held.launch.box,
|
|
1112
|
+
servers: resumeOptions?.servers ?? held.launch.servers,
|
|
1113
|
+
tools: resumeOptions?.tools ?? held.launch.tools,
|
|
1114
|
+
visible: resumeOptions?.visible ?? held.launch.visible,
|
|
1115
|
+
};
|
|
1116
|
+
const surface = surfaceOf(launch.servers, launch.tools, launch.visible, options.mcp);
|
|
1117
|
+
const changed = Object.keys(named).length > 0 && JSON.stringify(surface) !== held.surface;
|
|
1118
|
+
if (!changed) {
|
|
1119
|
+
// The resume is accepted: its caller names where the reverse requests go from now on.
|
|
1120
|
+
if (resumeOptions?.reverse !== undefined) held.reverse = resumeOptions.reverse;
|
|
1121
|
+
if (text === "") return undefined;
|
|
1122
|
+
// The prompt of a resume waits behind a running turn, as a send does; it is not an error.
|
|
1123
|
+
if (held.busy) {
|
|
1124
|
+
held.queue.push({ text });
|
|
1125
|
+
return undefined;
|
|
1126
|
+
}
|
|
1127
|
+
return async () => void (await runTurn(held, text));
|
|
1128
|
+
}
|
|
1129
|
+
if (held.busy) {
|
|
1130
|
+
throw unavailable("resume", "a turn is running: the servers and tools of the session change only when it is idle");
|
|
1131
|
+
}
|
|
1132
|
+
// The watchers follow the session, not the process: they are handed to the new one.
|
|
1133
|
+
carried = [...held.watchers];
|
|
1134
|
+
held.watchers.clear();
|
|
1135
|
+
sessions.delete(id.native);
|
|
1136
|
+
await stopSession(held);
|
|
1137
|
+
}
|
|
1138
|
+
const surface = surfaceOf(launch.servers, launch.tools, launch.visible, options.mcp);
|
|
1139
|
+
|
|
1140
|
+
// The session is resumed in the directory it ran in: the database's, else the one the caller says
|
|
1141
|
+
// it started in. One neither knows is resumed where this process is, and the CLI says whether it has it.
|
|
1142
|
+
const cwd = (home === undefined ? undefined : directoryOf(home, id.native)) ?? resumeOptions?.cwd ?? held?.cwd ?? process.cwd();
|
|
1143
|
+
let session: LiveSession;
|
|
1144
|
+
try {
|
|
1145
|
+
session = await spawnSession(cwd, launch);
|
|
1146
|
+
} catch (error) {
|
|
1147
|
+
for (const watcher of carried) watcher(undefined);
|
|
1148
|
+
throw error;
|
|
1149
|
+
}
|
|
1150
|
+
session.cwd = cwd;
|
|
1151
|
+
session.reverse = resumeOptions?.reverse ?? held?.reverse;
|
|
1152
|
+
session.surface = JSON.stringify(surface);
|
|
1153
|
+
session.launch = launch;
|
|
1154
|
+
try {
|
|
1155
|
+
const resumed = await call(session, "session/resume", { sessionId: id.native, ...wire(cwd), ...surface });
|
|
1156
|
+
if (!resumed.ok) throw unavailable("resume", resumed.error ?? "the CLI did not resume the session");
|
|
1157
|
+
// ZCode restores the mode of a resumed session itself, from its last assistant message (the
|
|
1158
|
+
// project's default when it has none), and a resume names none: a session that comes back in
|
|
1159
|
+
// another mode than niwa started it in is not run.
|
|
1160
|
+
if (resumeOptions?.mode !== undefined) {
|
|
1161
|
+
const wanted = SESSION_MODES[resumeOptions.mode];
|
|
1162
|
+
const restored = home === undefined ? undefined : persistedModeOf(home, id.native);
|
|
1163
|
+
if (restored === undefined) {
|
|
1164
|
+
throw unavailable("resume", `the mode ZCode restores the session in cannot be read, so it cannot be compared with "${wanted}" (${resumeOptions.mode}); it was not resumed`);
|
|
1165
|
+
}
|
|
1166
|
+
if (restored !== wanted) {
|
|
1167
|
+
throw unavailable(
|
|
1168
|
+
"resume",
|
|
1169
|
+
`ZCode restores the session in the mode "${restored}", but niwa started it in "${wanted}" (${resumeOptions.mode}); it was not resumed`,
|
|
1170
|
+
);
|
|
1171
|
+
}
|
|
1172
|
+
}
|
|
1173
|
+
session.nativeId = id.native;
|
|
1174
|
+
const asked = resumeOptions?.model ?? options.model;
|
|
1175
|
+
const reported = modelRefOf(asRecord(asRecord(resumed.result)["session"])["model"]);
|
|
1176
|
+
// A process that replaces a held one keeps the model and the effort of the session it replaces.
|
|
1177
|
+
session.selection = held !== undefined && resumeOptions?.model === undefined ? held.selection : selectionOf(asked, options.effort, reported);
|
|
1178
|
+
reportModel(session, asked, reported);
|
|
1179
|
+
sessions.set(id.native, session);
|
|
1180
|
+
await subscribe(session);
|
|
1181
|
+
for (const watcher of carried) session.watch(watcher);
|
|
1182
|
+
carried = [];
|
|
1183
|
+
} catch (error) {
|
|
1184
|
+
// Only its own entry: another process that took the session on in the meantime is not this one's to drop.
|
|
1185
|
+
if (sessions.get(id.native) === session) sessions.delete(id.native);
|
|
1186
|
+
await stopSession(session);
|
|
1187
|
+
for (const watcher of carried) watcher(undefined);
|
|
1188
|
+
throw error;
|
|
1189
|
+
}
|
|
1190
|
+
return text === "" ? undefined : async () => void (await runTurn(session, text));
|
|
1191
|
+
}
|
|
1192
|
+
|
|
1193
|
+
// -- the contract ---------------------------------------------------------
|
|
1194
|
+
|
|
1195
|
+
return {
|
|
1196
|
+
async start(startOptions: StartOptions): Promise<StartedSession> {
|
|
1197
|
+
// Everything ZCode cannot do is refused before the child is spawned.
|
|
1198
|
+
const model = startOptions.model ?? options.model;
|
|
1199
|
+
const effort = startOptions.effort ?? options.effort;
|
|
1200
|
+
const mode = modeOf(startOptions.mode, options.mode, ZCODE_LAUNCH);
|
|
1201
|
+
requireLaunch(harnessId, ZCODE_LAUNCH, { model, effort, mode });
|
|
1202
|
+
const surface = surfaceOf(startOptions.servers, startOptions.tools, startOptions.visible, options.mcp);
|
|
1203
|
+
if (model !== undefined && model !== "") parseModel(harnessId, model);
|
|
1204
|
+
const cwd = startOptions.cwd ?? process.cwd();
|
|
1205
|
+
|
|
1206
|
+
const session = await spawnSession(cwd, startOptions);
|
|
1207
|
+
session.cwd = cwd;
|
|
1208
|
+
session.reverse = startOptions.reverse;
|
|
1209
|
+
session.surface = JSON.stringify(surface);
|
|
1210
|
+
session.launch = { env: startOptions.env, box: startOptions.box, servers: startOptions.servers, tools: startOptions.tools, visible: startOptions.visible };
|
|
1211
|
+
try {
|
|
1212
|
+
const created = await call(session, "session/create", {
|
|
1213
|
+
...wire(cwd),
|
|
1214
|
+
// The mode is always named: left out, the session would take the one the user's or the project's config sets.
|
|
1215
|
+
mode: SESSION_MODES[mode],
|
|
1216
|
+
...surface,
|
|
1217
|
+
});
|
|
1218
|
+
if (!created.ok) throw unavailable("start", created.error ?? "the CLI did not create a session");
|
|
1219
|
+
const snapshot = asRecord(asRecord(created.result)["session"]);
|
|
1220
|
+
const native = stringOf(snapshot["sessionId"]);
|
|
1221
|
+
if (native === undefined) throw unavailable("start", "the CLI created a session without naming it");
|
|
1222
|
+
session.nativeId = native;
|
|
1223
|
+
const reported = modelRefOf(snapshot["model"]);
|
|
1224
|
+
session.selection = selectionOf(model, effort, reported);
|
|
1225
|
+
reportModel(session, model, reported);
|
|
1226
|
+
sessions.set(native, session);
|
|
1227
|
+
await subscribe(session);
|
|
1228
|
+
} catch (error) {
|
|
1229
|
+
if (sessions.get(session.nativeId) === session) sessions.delete(session.nativeId);
|
|
1230
|
+
await stopSession(session);
|
|
1231
|
+
throw error;
|
|
1232
|
+
}
|
|
1233
|
+
const id = makeSessionId(harnessId, session.nativeId);
|
|
1234
|
+
// The caller knows the session before its prompt goes: a start cut off while its first turn
|
|
1235
|
+
// is on the way still finds it. A session whose name could not be kept is given no work.
|
|
1236
|
+
try {
|
|
1237
|
+
await startOptions.named?.(id);
|
|
1238
|
+
} catch (error) {
|
|
1239
|
+
if (sessions.get(session.nativeId) === session) sessions.delete(session.nativeId);
|
|
1240
|
+
await stopSession(session);
|
|
1241
|
+
throw error;
|
|
1242
|
+
}
|
|
1243
|
+
// The session exists once ZCode has named it. The prompt is its first turn, delivered like a
|
|
1244
|
+
// send: the start waits for ZCode to accept the turn, never for the turn to end.
|
|
1245
|
+
const text = promptText(startOptions.prompt);
|
|
1246
|
+
if (text === "") return { session: id, mode };
|
|
1247
|
+
try {
|
|
1248
|
+
return { session: id, first: await deliver(session, text), mode };
|
|
1249
|
+
} catch (error) {
|
|
1250
|
+
if (sessions.get(session.nativeId) === session) sessions.delete(session.nativeId);
|
|
1251
|
+
await stopSession(session);
|
|
1252
|
+
throw error;
|
|
1253
|
+
}
|
|
1254
|
+
},
|
|
1255
|
+
|
|
1256
|
+
async resume(id: SessionId, resumeOptions?: ResumeOptions): Promise<void> {
|
|
1257
|
+
// Resumes of one session go one at a time through the lookup, the launch and the publishing of its
|
|
1258
|
+
// process: two that both found it absent would launch two app-servers, and the later would hide the
|
|
1259
|
+
// earlier. The lock is let go before the prompt's turn, which can run for hours.
|
|
1260
|
+
const previous = resuming.get(id.native);
|
|
1261
|
+
let release: () => void = () => {};
|
|
1262
|
+
const mine = new Promise<void>((resolve) => {
|
|
1263
|
+
release = resolve;
|
|
1264
|
+
});
|
|
1265
|
+
const tail = (previous ?? Promise.resolve()).then(() => mine);
|
|
1266
|
+
resuming.set(id.native, tail);
|
|
1267
|
+
let afterwards: (() => Promise<void>) | undefined;
|
|
1268
|
+
try {
|
|
1269
|
+
await previous;
|
|
1270
|
+
afterwards = await resumeSession(id, resumeOptions);
|
|
1271
|
+
} finally {
|
|
1272
|
+
release();
|
|
1273
|
+
if (resuming.get(id.native) === tail) resuming.delete(id.native);
|
|
1274
|
+
}
|
|
1275
|
+
await afterwards?.();
|
|
1276
|
+
},
|
|
1277
|
+
|
|
1278
|
+
async send(id: SessionId, message: string, sendOptions?: SendOptions): Promise<DeliveryReceipt> {
|
|
1279
|
+
const session = sessions.get(id.native);
|
|
1280
|
+
if (session === undefined) {
|
|
1281
|
+
throw new InputNotSent(harnessId, "send", `the session ${id.native} is not held by this control side`);
|
|
1282
|
+
}
|
|
1283
|
+
// Only a caller that asks for it is steered into the running turn.
|
|
1284
|
+
if (session.busy && sendOptions?.into === "turn") return steer(session, message);
|
|
1285
|
+
return deliver(session, message);
|
|
1286
|
+
},
|
|
1287
|
+
|
|
1288
|
+
async interrupt(id: SessionId): Promise<void> {
|
|
1289
|
+
const session = requireSession(id, "interrupt");
|
|
1290
|
+
if (!session.busy) throw unavailable("interrupt", "no turn is running");
|
|
1291
|
+
// An explicit stop clears the queue: the messages that waited behind a turn the caller
|
|
1292
|
+
// just stopped must not fire as a surprise.
|
|
1293
|
+
session.dropQueue("the turn was interrupted");
|
|
1294
|
+
// `session/stop` bypasses the queue of the server, so it lands while the turn streams.
|
|
1295
|
+
const stopped = await call(session, "session/stop", { sessionId: id.native });
|
|
1296
|
+
if (!stopped.ok) throw unavailable("interrupt", stopped.error ?? "the CLI refused the interrupt");
|
|
1297
|
+
// A stopped turn waits for nothing, and the server says so on no wire.
|
|
1298
|
+
session.cancelAsking();
|
|
1299
|
+
},
|
|
1300
|
+
|
|
1301
|
+
async ask<T>(id: SessionId, askOptions: AskOptions<T>): Promise<AskAnswer<T>> {
|
|
1302
|
+
const session = requireSession(id, "ask");
|
|
1303
|
+
// The schema travels as text, and the answer is checked against the zod schema here: an
|
|
1304
|
+
// answer that does not pass is not an answer.
|
|
1305
|
+
const jsonSchema = z.toJSONSchema(askOptions.schema, { io: "output", unrepresentable: "any" });
|
|
1306
|
+
const instruction = [
|
|
1307
|
+
promptText(askOptions.prompt),
|
|
1308
|
+
"",
|
|
1309
|
+
"Answer with JSON only, matching this schema exactly:",
|
|
1310
|
+
JSON.stringify(jsonSchema),
|
|
1311
|
+
].join("\n");
|
|
1312
|
+
// An ask into a busy session waits for its turn, behind what is already queued.
|
|
1313
|
+
const text = session.busy
|
|
1314
|
+
? await new Promise<string>((resolve, reject) => {
|
|
1315
|
+
session.queue.push({ text: instruction, ask: { resolve, reject } });
|
|
1316
|
+
})
|
|
1317
|
+
: await runTurn(session, instruction);
|
|
1318
|
+
if (text.trim() === "") throw unavailable("ask", "the turn left no answer");
|
|
1319
|
+
const checked = askOptions.schema.safeParse(parseJson(text));
|
|
1320
|
+
if (!checked.success) {
|
|
1321
|
+
throw unavailable("ask", `the answer did not pass the schema: ${checked.error.issues.map((issue) => issue.path.join(".")).join(", ")}`);
|
|
1322
|
+
}
|
|
1323
|
+
return { session: id, value: checked.data, at: timestamp(Date.now()) };
|
|
1324
|
+
},
|
|
1325
|
+
|
|
1326
|
+
life(id: SessionId): AsyncIterable<LifeEvent> {
|
|
1327
|
+
const session = requireSession(id, "life");
|
|
1328
|
+
return {
|
|
1329
|
+
async *[Symbol.asyncIterator](): AsyncGenerator<LifeEvent> {
|
|
1330
|
+
const queue: LifeEvent[] = [];
|
|
1331
|
+
let finished = session.ended;
|
|
1332
|
+
let wake: (() => void) | undefined;
|
|
1333
|
+
const watcher: Watcher = (event) => {
|
|
1334
|
+
if (event === undefined) finished = true;
|
|
1335
|
+
else queue.push(event);
|
|
1336
|
+
wake?.();
|
|
1337
|
+
};
|
|
1338
|
+
session.watch(watcher);
|
|
1339
|
+
try {
|
|
1340
|
+
for (;;) {
|
|
1341
|
+
const event = queue.shift();
|
|
1342
|
+
if (event !== undefined) {
|
|
1343
|
+
yield event;
|
|
1344
|
+
} else if (finished) {
|
|
1345
|
+
return;
|
|
1346
|
+
} else {
|
|
1347
|
+
await new Promise<void>((resolve) => {
|
|
1348
|
+
wake = resolve;
|
|
1349
|
+
});
|
|
1350
|
+
wake = undefined;
|
|
1351
|
+
}
|
|
1352
|
+
}
|
|
1353
|
+
} finally {
|
|
1354
|
+
session.watchers.delete(watcher);
|
|
1355
|
+
}
|
|
1356
|
+
},
|
|
1357
|
+
};
|
|
1358
|
+
},
|
|
1359
|
+
|
|
1360
|
+
async state(id: SessionId): Promise<SessionState> {
|
|
1361
|
+
const session = sessions.get(id.native);
|
|
1362
|
+
// A session not held, or whose child is gone, proves nothing about now.
|
|
1363
|
+
if (session === undefined || session.ended || session.stopping) return "unknown";
|
|
1364
|
+
return session.busy ? "running" : "idle";
|
|
1365
|
+
},
|
|
1366
|
+
|
|
1367
|
+
/** The release the shared contract names: stops this session's process and no other. */
|
|
1368
|
+
async close(id: SessionId): Promise<void> {
|
|
1369
|
+
const session = sessions.get(id.native);
|
|
1370
|
+
if (session === undefined) return;
|
|
1371
|
+
sessions.delete(id.native);
|
|
1372
|
+
await stopSession(session);
|
|
1373
|
+
},
|
|
1374
|
+
|
|
1375
|
+
async stop(id: SessionId): Promise<void> {
|
|
1376
|
+
const session = sessions.get(id.native);
|
|
1377
|
+
if (session === undefined) return;
|
|
1378
|
+
sessions.delete(id.native);
|
|
1379
|
+
await stopSession(session);
|
|
1380
|
+
},
|
|
1381
|
+
|
|
1382
|
+
async dispose(): Promise<void> {
|
|
1383
|
+
disposed = true;
|
|
1384
|
+
sessions.clear();
|
|
1385
|
+
await Promise.all([...owned].map((session) => stopSession(session)));
|
|
1386
|
+
// A launch that is still under way stops its own child when it finds the control side disposed.
|
|
1387
|
+
await Promise.allSettled([...launching]);
|
|
1388
|
+
},
|
|
1389
|
+
};
|
|
1390
|
+
}
|
|
1391
|
+
|
|
1392
|
+
/** A model as ZCode names it: the provider and the model in it. */
|
|
1393
|
+
interface ModelRef {
|
|
1394
|
+
readonly providerId: string;
|
|
1395
|
+
readonly modelId: string;
|
|
1396
|
+
}
|
|
1397
|
+
|
|
1398
|
+
/** `providerId/modelId`, split at the first slash: a model id may hold slashes of its own. */
|
|
1399
|
+
function parseModel(harness: HarnessId, model: string): ModelRef {
|
|
1400
|
+
const slash = model.indexOf("/");
|
|
1401
|
+
if (slash <= 0 || slash === model.length - 1) {
|
|
1402
|
+
throw new Unsupported(harness, "control", "start", `a model is named "providerId/modelId", not "${model}"`);
|
|
1403
|
+
}
|
|
1404
|
+
return { providerId: model.slice(0, slash), modelId: model.slice(slash + 1) };
|
|
1405
|
+
}
|
|
1406
|
+
|
|
1407
|
+
/** The model a snapshot of a session names. */
|
|
1408
|
+
function modelRefOf(value: unknown): ModelRef | undefined {
|
|
1409
|
+
const record = asRecord(value);
|
|
1410
|
+
const providerId = stringOf(record["providerId"]);
|
|
1411
|
+
const modelId = stringOf(record["modelId"]);
|
|
1412
|
+
return providerId === undefined || modelId === undefined ? undefined : { providerId, modelId };
|
|
1413
|
+
}
|
|
1414
|
+
|
|
1415
|
+
/**
|
|
1416
|
+
* What `session/create` and `session/resume` take of a session's surface (ZCode's
|
|
1417
|
+
* `zcodeSessionCreateParamsSchema` and `zcodeSessionResumeParamsSchema`): `mcpServers`, with each
|
|
1418
|
+
* `env` as `[{name, value}]` rather than a record, `toolAllowlist` and `toolDenylist`. A resume
|
|
1419
|
+
* takes the same three, because a cold resume rebuilds the runtime and would drop them otherwise.
|
|
1420
|
+
* The keys are left out when empty, so a session with nothing asked for sends what it always did.
|
|
1421
|
+
*
|
|
1422
|
+
* niwa's tool mode is the allow-list (`niwa-only` names none of ZCode's own tools) and the
|
|
1423
|
+
* `disabledTools` of the visible actions the deny-list; both are the harness's own tool names. ZCode's allow-list is an exact-name filter on
|
|
1424
|
+
* every tool of the session, the MCP tools (`mcp__<server>__<tool>`) among them. So when there is
|
|
1425
|
+
* an allow-list, the tools niwa knows its servers list (`McpServerSpec.tools`: niwa's own server)
|
|
1426
|
+
* are appended to it as `mcp__<server>__<tool>`; a foreign server lists none here, and its tools
|
|
1427
|
+
* pass only when the allow-list names them itself. What the installation sets for a server by its
|
|
1428
|
+
* name (`ZcodeControlOptions.mcp`) is added to that server's entry.
|
|
1429
|
+
*/
|
|
1430
|
+
function surfaceOf(
|
|
1431
|
+
servers: readonly McpServerSpec[] | undefined,
|
|
1432
|
+
mode: ToolsMode | undefined,
|
|
1433
|
+
visible: VisibleActions | undefined,
|
|
1434
|
+
mcp: Readonly<Record<string, ZcodeMcpOptions>> | undefined,
|
|
1435
|
+
): Record<string, unknown> {
|
|
1436
|
+
const denied = visible?.disabledTools ?? [];
|
|
1437
|
+
const hasServers = servers !== undefined && servers.length > 0;
|
|
1438
|
+
// Only niwa's tools is an allow-list of none of ZCode's own.
|
|
1439
|
+
const own = mode === undefined || mode === "all" ? undefined : mode === "niwa-only" ? [] : mode.allow;
|
|
1440
|
+
const served =
|
|
1441
|
+
own === undefined
|
|
1442
|
+
? []
|
|
1443
|
+
: (servers ?? []).flatMap((server) => (server.tools ?? []).map((tool) => `mcp__${server.name}__${tool}`));
|
|
1444
|
+
const allowed = own === undefined ? undefined : [...new Set([...own, ...served])];
|
|
1445
|
+
return {
|
|
1446
|
+
...(hasServers
|
|
1447
|
+
? {
|
|
1448
|
+
mcpServers: servers.map((server) => ({
|
|
1449
|
+
name: server.name,
|
|
1450
|
+
command: server.command,
|
|
1451
|
+
args: [...server.args],
|
|
1452
|
+
env: Object.entries(server.env).map(([name, value]) => ({ name, value })),
|
|
1453
|
+
...mcp?.[server.name],
|
|
1454
|
+
})),
|
|
1455
|
+
}
|
|
1456
|
+
: {}),
|
|
1457
|
+
...(allowed === undefined ? {} : { toolAllowlist: allowed }),
|
|
1458
|
+
...(denied.length === 0 ? {} : { toolDenylist: [...denied] }),
|
|
1459
|
+
};
|
|
1460
|
+
}
|
|
1461
|
+
|
|
1462
|
+
/** The JSON an answer holds: the answer as it is, in a fence, or after words; text that has none is the text. */
|
|
1463
|
+
function parseJson(text: string): unknown {
|
|
1464
|
+
const trimmed = text.trim();
|
|
1465
|
+
const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(trimmed);
|
|
1466
|
+
const body = fenced?.[1]?.trim() ?? trimmed;
|
|
1467
|
+
try {
|
|
1468
|
+
return JSON.parse(body) as unknown;
|
|
1469
|
+
} catch {
|
|
1470
|
+
const start = body.search(/[[{]/);
|
|
1471
|
+
if (start === -1) return body;
|
|
1472
|
+
try {
|
|
1473
|
+
return JSON.parse(body.slice(start)) as unknown;
|
|
1474
|
+
} catch {
|
|
1475
|
+
return body;
|
|
1476
|
+
}
|
|
1477
|
+
}
|
|
1478
|
+
}
|