@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
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The wire of `zcode app-server`, typed. What ZCode sends is
|
|
3
|
+
* read here into a union by method, and a session event into a union by type; the schemas are
|
|
4
|
+
* generated from ZCode's own zod protocol (`generated/zcode-protocol.ts`, `scripts/gen-zcode.ts`).
|
|
5
|
+
*
|
|
6
|
+
* The snapshot is one version of ZCode; the installed one may be newer (the generated header says
|
|
7
|
+
* which is which). What a newer ZCode sends that the snapshot does not know is never a crash and
|
|
8
|
+
* never lost: it is read as an `UnknownVariant` that names the protocol, the discriminator and its
|
|
9
|
+
* value, and keeps the raw message, and the control side shows it in the session's log.
|
|
10
|
+
*
|
|
11
|
+
* Nothing here talks to a process.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
import type { z } from "zod";
|
|
15
|
+
|
|
16
|
+
import { ProtocolNameSchema, VariantNameSchema } from "@niwa-labs/harness";
|
|
17
|
+
import type { ProtocolName, VariantName } from "@niwa-labs/harness";
|
|
18
|
+
|
|
19
|
+
import {
|
|
20
|
+
ANSWER_SCHEMAS,
|
|
21
|
+
NOTIFICATION_SCHEMAS,
|
|
22
|
+
NotificationSessionEventSchema,
|
|
23
|
+
REQUEST_SCHEMAS,
|
|
24
|
+
SESSION_EVENT_TYPES,
|
|
25
|
+
V4_NOTIFICATION_METHODS,
|
|
26
|
+
} from "./generated/zcode-protocol.ts";
|
|
27
|
+
import * as wire from "./generated/zcode-protocol.ts";
|
|
28
|
+
|
|
29
|
+
export type { NotificationSessionEvent as SessionEvent } from "./generated/zcode-protocol.ts";
|
|
30
|
+
|
|
31
|
+
export type NotificationMethod = keyof typeof NOTIFICATION_SCHEMAS;
|
|
32
|
+
export type RequestMethod = keyof typeof REQUEST_SCHEMAS;
|
|
33
|
+
|
|
34
|
+
/** A notification of ZCode: its method, and the params as the snapshot has them. */
|
|
35
|
+
export type Notification = {
|
|
36
|
+
[M in NotificationMethod]: { readonly method: M; readonly params: z.output<(typeof NOTIFICATION_SCHEMAS)[M]> };
|
|
37
|
+
}[NotificationMethod];
|
|
38
|
+
|
|
39
|
+
/** A request of ZCode to the client. The params are `undefined` when they do not fit the snapshot. */
|
|
40
|
+
export type ServerRequest = {
|
|
41
|
+
[M in RequestMethod]: { readonly method: M; readonly params: z.output<(typeof REQUEST_SCHEMAS)[M]> | undefined };
|
|
42
|
+
}[RequestMethod];
|
|
43
|
+
|
|
44
|
+
/** The answer ZCode takes to a request, as the snapshot has it. */
|
|
45
|
+
export type RequestAnswer<M extends RequestMethod> = z.input<(typeof ANSWER_SCHEMAS)[M]>;
|
|
46
|
+
|
|
47
|
+
/** The name of this wire protocol in a record of an unknown variant. */
|
|
48
|
+
export const ZCODE_PROTOCOL: ProtocolName = ProtocolNameSchema.parse("zcode app-server");
|
|
49
|
+
|
|
50
|
+
/** A message the snapshot does not know, or knows by name but not by shape. */
|
|
51
|
+
export interface UnknownVariant {
|
|
52
|
+
readonly protocol: "zcode";
|
|
53
|
+
/** What failed to match: the method of a message, or the type of a session event. */
|
|
54
|
+
readonly discriminator: "method" | "event type";
|
|
55
|
+
readonly value: string;
|
|
56
|
+
readonly why: "not in the snapshot" | "does not fit the snapshot";
|
|
57
|
+
/** The message as it came. */
|
|
58
|
+
readonly raw: unknown;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** What a notification is: one of ZCode's, a message of its v4 side channel, or unknown. */
|
|
62
|
+
export type NotificationRead =
|
|
63
|
+
| { readonly kind: "known"; readonly notification: Notification }
|
|
64
|
+
/** `v4/*`: the conversation view of ZCode's own desktop, which a session driver has no use for. */
|
|
65
|
+
| { readonly kind: "side-channel"; readonly method: string }
|
|
66
|
+
| { readonly kind: "unknown"; readonly unknown: UnknownVariant };
|
|
67
|
+
|
|
68
|
+
/** What a request is. `unknown` says why the log should show it; `request` is set when the method is ZCode's. */
|
|
69
|
+
export interface RequestRead {
|
|
70
|
+
readonly request: ServerRequest | undefined;
|
|
71
|
+
readonly unknown: UnknownVariant | undefined;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** How much of a raw message the log keeps. */
|
|
75
|
+
const RAW_CHARS = 4000;
|
|
76
|
+
|
|
77
|
+
function recordOf(value: unknown): Record<string, unknown> | undefined {
|
|
78
|
+
return typeof value === "object" && value !== null && !Array.isArray(value) ? Object.fromEntries(Object.entries(value)) : undefined;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** The params of a schema that fit it, or `undefined`. */
|
|
82
|
+
function fit<M extends string, S extends z.ZodType>(method: M, schema: S, params: unknown): { readonly method: M; readonly params: z.output<S> } | undefined {
|
|
83
|
+
const parsed = schema.safeParse(params);
|
|
84
|
+
return parsed.success ? { method, params: parsed.data } : undefined;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
const isNotificationMethod = (method: string): method is NotificationMethod => Object.hasOwn(NOTIFICATION_SCHEMAS, method);
|
|
88
|
+
const isRequestMethod = (method: string): method is RequestMethod => Object.hasOwn(REQUEST_SCHEMAS, method);
|
|
89
|
+
const isV4 = (method: string): boolean => (V4_NOTIFICATION_METHODS as readonly string[]).includes(method);
|
|
90
|
+
const isSessionEventType = (type: string): boolean => (SESSION_EVENT_TYPES as readonly string[]).includes(type);
|
|
91
|
+
|
|
92
|
+
function parseNotification(method: NotificationMethod, params: unknown): Notification | undefined {
|
|
93
|
+
switch (method) {
|
|
94
|
+
case "session/event":
|
|
95
|
+
return fit(method, NotificationSessionEventSchema, params);
|
|
96
|
+
case "state.updated":
|
|
97
|
+
return fit(method, wire.NotificationStateUpdatedSchema, params);
|
|
98
|
+
case "session/lifecycle/changed":
|
|
99
|
+
return fit(method, wire.NotificationSessionLifecycleChangedSchema, params);
|
|
100
|
+
case "startup/pluginsDegraded":
|
|
101
|
+
return fit(method, wire.NotificationPluginsDegradedSchema, params);
|
|
102
|
+
case "startup/storageState":
|
|
103
|
+
return fit(method, wire.NotificationStorageStateSchema, params);
|
|
104
|
+
case "interaction/providerRuntimeHeadersCancelled":
|
|
105
|
+
return fit(method, wire.NotificationProviderRuntimeHeadersCancelledSchema, params);
|
|
106
|
+
case "process/mcpTelemetry":
|
|
107
|
+
return fit(method, wire.NotificationMcpTelemetrySchema, params);
|
|
108
|
+
case "process/mcpResourceSamples":
|
|
109
|
+
return fit(method, wire.NotificationMcpResourceSamplesSchema, params);
|
|
110
|
+
case "process/toolExecResource":
|
|
111
|
+
return fit(method, wire.NotificationToolExecResourceSchema, params);
|
|
112
|
+
case "plugins/operationProgress":
|
|
113
|
+
return fit(method, wire.NotificationPluginOperationProgressSchema, params);
|
|
114
|
+
case "process/resourceSample":
|
|
115
|
+
return fit(method, wire.NotificationProcessResourceSampleSchema, params);
|
|
116
|
+
case "process/networkRequests":
|
|
117
|
+
return fit(method, wire.NotificationNetworkRequestsSchema, params);
|
|
118
|
+
case "computer-use/operation-event":
|
|
119
|
+
return fit(method, wire.NotificationComputerUseOperationEventSchema, params);
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
function parseRequest(method: RequestMethod, params: unknown): ServerRequest {
|
|
124
|
+
switch (method) {
|
|
125
|
+
case "session/requestRuntimePreferences":
|
|
126
|
+
return { method, params: fit(method, wire.RequestRuntimePreferencesParamsSchema, params)?.params };
|
|
127
|
+
case "interaction/requestPermission":
|
|
128
|
+
return { method, params: fit(method, wire.RequestPermissionParamsSchema, params)?.params };
|
|
129
|
+
case "interaction/requestUserInput":
|
|
130
|
+
return { method, params: fit(method, wire.RequestUserInputParamsSchema, params)?.params };
|
|
131
|
+
case "interaction/requestProviderRuntimeHeaders":
|
|
132
|
+
return { method, params: fit(method, wire.RequestProviderRuntimeHeadersParamsSchema, params)?.params };
|
|
133
|
+
case "interaction/requestOfficialMcpAuthHeaders":
|
|
134
|
+
return { method, params: fit(method, wire.RequestOfficialMcpAuthHeadersParamsSchema, params)?.params };
|
|
135
|
+
case "interaction/requestCredentialCipher":
|
|
136
|
+
return { method, params: fit(method, wire.RequestCredentialCipherParamsSchema, params)?.params };
|
|
137
|
+
case "interaction/browserList":
|
|
138
|
+
return { method, params: fit(method, wire.RequestBrowserListParamsSchema, params)?.params };
|
|
139
|
+
case "interaction/browserExecute":
|
|
140
|
+
return { method, params: fit(method, wire.RequestBrowserExecuteParamsSchema, params)?.params };
|
|
141
|
+
case "subagents/readRuntimeConfig":
|
|
142
|
+
return { method, params: fit(method, wire.RequestSubagentsRuntimeConfigParamsSchema, params)?.params };
|
|
143
|
+
case "bot/channel/reply":
|
|
144
|
+
return { method, params: fit(method, wire.RequestChannelReplyParamsSchema, params)?.params };
|
|
145
|
+
case "topic/resource/read":
|
|
146
|
+
return { method, params: fit(method, wire.RequestTopicResourceReadParamsSchema, params)?.params };
|
|
147
|
+
case "topic/resource/cancel":
|
|
148
|
+
return { method, params: fit(method, wire.RequestTopicResourceCancelParamsSchema, params)?.params };
|
|
149
|
+
case "appControl/listProjects":
|
|
150
|
+
return { method, params: fit(method, wire.RequestAppControlListProjectsParamsSchema, params)?.params };
|
|
151
|
+
case "appControl/listSessions":
|
|
152
|
+
return { method, params: fit(method, wire.RequestAppControlListSessionsParamsSchema, params)?.params };
|
|
153
|
+
case "appControl/readSession":
|
|
154
|
+
return { method, params: fit(method, wire.RequestAppControlReadSessionParamsSchema, params)?.params };
|
|
155
|
+
case "appControl/createSession":
|
|
156
|
+
return { method, params: fit(method, wire.RequestAppControlCreateSessionParamsSchema, params)?.params };
|
|
157
|
+
case "appControl/forkSession":
|
|
158
|
+
return { method, params: fit(method, wire.RequestAppControlForkSessionParamsSchema, params)?.params };
|
|
159
|
+
case "appControl/sendToSession":
|
|
160
|
+
return { method, params: fit(method, wire.RequestAppControlSendToSessionParamsSchema, params)?.params };
|
|
161
|
+
case "appControl/waitSessions":
|
|
162
|
+
return { method, params: fit(method, wire.RequestAppControlWaitSessionsParamsSchema, params)?.params };
|
|
163
|
+
case "appControl/interruptSession":
|
|
164
|
+
return { method, params: fit(method, wire.RequestAppControlInterruptSessionParamsSchema, params)?.params };
|
|
165
|
+
case "appControl/renameSession":
|
|
166
|
+
return { method, params: fit(method, wire.RequestAppControlRenameSessionParamsSchema, params)?.params };
|
|
167
|
+
case "appControl/openSession":
|
|
168
|
+
return { method, params: fit(method, wire.RequestAppControlOpenSessionParamsSchema, params)?.params };
|
|
169
|
+
case "appControl/setSessionArchived":
|
|
170
|
+
return { method, params: fit(method, wire.RequestAppControlSetSessionArchivedParamsSchema, params)?.params };
|
|
171
|
+
case "appControl/setSessionPinned":
|
|
172
|
+
return { method, params: fit(method, wire.RequestAppControlSetSessionPinnedParamsSchema, params)?.params };
|
|
173
|
+
case "appControl/cancel":
|
|
174
|
+
return { method, params: fit(method, wire.RequestAppControlCancelParamsSchema, params)?.params };
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/**
|
|
179
|
+
* Reads a notification (a message with a method and no id). A `session/event` is read as its
|
|
180
|
+
* params, or, as some bundles frame it, as `{ event: <its params> }`.
|
|
181
|
+
*/
|
|
182
|
+
export function readNotification(method: string, params: unknown): NotificationRead {
|
|
183
|
+
const raw = { method, params };
|
|
184
|
+
if (!isNotificationMethod(method)) {
|
|
185
|
+
if (isV4(method)) return { kind: "side-channel", method };
|
|
186
|
+
return { kind: "unknown", unknown: { protocol: "zcode", discriminator: "method", value: method, why: "not in the snapshot", raw } };
|
|
187
|
+
}
|
|
188
|
+
const framed = method === "session/event" ? (recordOf(params)?.["event"] ?? params) : params;
|
|
189
|
+
const notification = parseNotification(method, framed);
|
|
190
|
+
if (notification !== undefined) return { kind: "known", notification };
|
|
191
|
+
if (method === "session/event") {
|
|
192
|
+
const type = recordOf(framed)?.["type"];
|
|
193
|
+
if (typeof type === "string" && !isSessionEventType(type)) {
|
|
194
|
+
return { kind: "unknown", unknown: { protocol: "zcode", discriminator: "event type", value: type, why: "not in the snapshot", raw } };
|
|
195
|
+
}
|
|
196
|
+
return {
|
|
197
|
+
kind: "unknown",
|
|
198
|
+
unknown: { protocol: "zcode", discriminator: "event type", value: typeof type === "string" ? type : "(none)", why: "does not fit the snapshot", raw },
|
|
199
|
+
};
|
|
200
|
+
}
|
|
201
|
+
return { kind: "unknown", unknown: { protocol: "zcode", discriminator: "method", value: method, why: "does not fit the snapshot", raw } };
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/** Reads a request of ZCode to the client (a message with a method and an id). */
|
|
205
|
+
export function readRequest(id: number | string, method: string, params: unknown): RequestRead {
|
|
206
|
+
const raw = { id, method, params };
|
|
207
|
+
if (!isRequestMethod(method)) {
|
|
208
|
+
return { request: undefined, unknown: { protocol: "zcode", discriminator: "method", value: method, why: "not in the snapshot", raw } };
|
|
209
|
+
}
|
|
210
|
+
const request = parseRequest(method, params);
|
|
211
|
+
return {
|
|
212
|
+
request,
|
|
213
|
+
unknown: request.params === undefined ? { protocol: "zcode", discriminator: "method", value: method, why: "does not fit the snapshot", raw } : undefined,
|
|
214
|
+
};
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/**
|
|
218
|
+
* The discriminator value of an unknown variant, as a record names it: the method of a message, or
|
|
219
|
+
* the type of a `session/event` (an event type is read only in that notification).
|
|
220
|
+
*/
|
|
221
|
+
export function unknownVariantName(unknown: UnknownVariant): VariantName {
|
|
222
|
+
return VariantNameSchema.parse(unknown.discriminator === "method" ? unknown.value : `session/event ${unknown.value}`);
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/** The words that put an unknown variant in a session's log: the protocol, the discriminator and its value, and the raw message. */
|
|
226
|
+
export function unknownDetail(unknown: UnknownVariant): string {
|
|
227
|
+
const raw = JSON.stringify(unknown.raw) ?? "undefined";
|
|
228
|
+
const shown = raw.length > RAW_CHARS ? `${raw.slice(0, RAW_CHARS)}... (${raw.length - RAW_CHARS} more characters)` : raw;
|
|
229
|
+
return `unknown ${unknown.protocol} ${unknown.discriminator} "${unknown.value}" (${unknown.why}): ${shown}`;
|
|
230
|
+
}
|