@niwa-labs/sessions 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.
@@ -0,0 +1,64 @@
1
+ /** A transcript as the page draws it: turns, tool calls with their results, and the notes between. */
2
+
3
+ import type { TranscriptRecord } from "./actions.ts";
4
+
5
+ export type TranscriptItem =
6
+ | { kind: "turn"; key: string; role: "user" | "assistant"; text: string; model?: string | undefined }
7
+ | { kind: "tool"; key: string; name: string; input: unknown; output: unknown; state: "running" | "done" | "failed" }
8
+ | { kind: "note"; key: string; label: string; text: string };
9
+
10
+ /**
11
+ * The items of a transcript, in order. A tool result joins the call it answers by the call's id, wherever it lies after it; a
12
+ * call with no result yet is running; a result whose call is not in the page (it lies before the window) stands alone.
13
+ */
14
+ export function itemsOf(records: readonly TranscriptRecord[]): TranscriptItem[] {
15
+ const items: TranscriptItem[] = [];
16
+ const open = new Map<string, Extract<TranscriptItem, { kind: "tool" }>>();
17
+ records.forEach((record, index) => {
18
+ const key = record.locator ?? `#${String(index)}`;
19
+ switch (record.kind) {
20
+ case "user":
21
+ case "assistant":
22
+ items.push({ kind: "turn", key, role: record.kind, text: record.text, ...(record.kind === "assistant" ? { model: record.model } : {}) });
23
+ return;
24
+ case "thinking":
25
+ items.push({ kind: "note", key, label: "Thinking", text: record.redacted ? "Kept sealed by the harness." : record.text });
26
+ return;
27
+ case "tool-call": {
28
+ const tool: Extract<TranscriptItem, { kind: "tool" }> = { kind: "tool", key, name: record.name, input: record.input, output: undefined, state: "running" };
29
+ open.set(record.callId, tool);
30
+ items.push(tool);
31
+ return;
32
+ }
33
+ case "tool-result": {
34
+ const call = open.get(record.callId);
35
+ const state = record.ok === false ? "failed" : "done";
36
+ if (call === undefined) {
37
+ items.push({ kind: "tool", key, name: record.name ?? "tool", input: undefined, output: record.output, state });
38
+ return;
39
+ }
40
+ call.output = record.output;
41
+ call.state = state;
42
+ return;
43
+ }
44
+ case "checklist": {
45
+ const done = record.items.filter((item) => item.state === "done").length;
46
+ items.push({ kind: "note", key, label: "Checklist", text: `${String(done)} of ${String(record.items.length)} done` });
47
+ return;
48
+ }
49
+ case "permission":
50
+ items.push({ kind: "note", key, label: "Permission", text: `${record.tool ?? "a tool"}: ${record.outcome}` });
51
+ return;
52
+ case "compaction":
53
+ items.push({ kind: "note", key, label: "Compacted", text: record.summary });
54
+ return;
55
+ case "nested":
56
+ items.push({ kind: "note", key, label: "Nested session", text: `${record.child.harness}/${record.child.native}` });
57
+ return;
58
+ case "unknown":
59
+ items.push({ kind: "note", key, label: "Unrecognised record", text: "" });
60
+ return;
61
+ }
62
+ });
63
+ return items;
64
+ }
package/src/confirm.ts ADDED
@@ -0,0 +1,228 @@
1
+ /**
2
+ * The owner confirms a discovered harness.
3
+ *
4
+ * A finding proposes; a proposal is not an instance. The id and the machine are the
5
+ * owner's to give, so the owner is asked: add this harness, and under what id and on what machine?
6
+ * The answer "yes" writes the confirmation and registers the instance; the
7
+ * answer "no" leaves the proposal as it is — a proposal nobody confirmed is not an instance.
8
+ *
9
+ * The question is a form in the common format (`Question`): the schema of the answer is its schema.
10
+ * This module does not import the requests module, so the question is made by its name, as a
11
+ * step of the handler. The requests module must be installed: a question asked by a name nobody
12
+ * serves is a failed step.
13
+ */
14
+
15
+ import { z } from "zod";
16
+
17
+ import { FormSchemaSchema, actionName, record, seq, stableJson, toJsonSchema } from "@niwa-labs/core";
18
+ import { plugin } from "@niwa-labs/plugin";
19
+ import type { ActionName, Answer, Question, Step, Timestamp } from "@niwa-labs/core";
20
+ import type { Plugin } from "@niwa-labs/plugin";
21
+ import {
22
+ HarnessBinarySchema,
23
+ HarnessIdSchema,
24
+ HarnessKindSchema,
25
+ HarnessProposalSchema,
26
+ MachineIdSchema,
27
+ } from "@niwa-labs/harness";
28
+ import type {
29
+ Harness,
30
+ HarnessBinding,
31
+ HarnessInstanceRegistry,
32
+ HarnessKindRegistry,
33
+ HarnessProposal,
34
+ SideCapabilities,
35
+ } from "@niwa-labs/harness";
36
+
37
+ import { HarnessProposed } from "./discover.ts";
38
+
39
+ /** The name of the action that asks a question and waits for the answer. */
40
+ const REQUEST_ASK: ActionName = actionName("request.ask");
41
+
42
+ /** The name of the question the owner is asked about a discovered harness. */
43
+ export const HARNESS_CONFIRM_QUESTION = "harness.confirm";
44
+
45
+ /** The fields the owner must give: an instance has an id and a machine. */
46
+ export const HARNESS_CONFIRM_FIELDS = ["id", "machine"] as const;
47
+
48
+ /** The answer of the owner: yes, with the fields the instance needs; or no. */
49
+ export const HarnessConfirmAnswerSchema = z.discriminatedUnion("answer", [
50
+ z.object({
51
+ answer: z.literal("yes"),
52
+ id: HarnessIdSchema,
53
+ machine: MachineIdSchema,
54
+ }),
55
+ z.object({ answer: z.literal("no") }),
56
+ ]);
57
+ export type HarnessConfirmAnswer = z.output<typeof HarnessConfirmAnswerSchema>;
58
+
59
+ /** The installation the owner confirmed: an instance without its sides. */
60
+ const ConfirmedInstallationSchema = z.object({
61
+ id: HarnessIdSchema,
62
+ kind: HarnessKindSchema,
63
+ machine: MachineIdSchema,
64
+ binary: HarnessBinarySchema.optional(),
65
+ home: z.string().min(1),
66
+ });
67
+
68
+ type ConfirmedInstallation = z.output<typeof ConfirmedInstallationSchema>;
69
+
70
+ /** The owner confirmed a discovered harness. */
71
+ export const HarnessConfirmed = record("harness.confirmed", ConfirmedInstallationSchema);
72
+
73
+ /** The fields the owner gives, as a form: the JSON Schema of the answer. */
74
+ const CONFIRM_FORM = FormSchemaSchema.parse(toJsonSchema(HarnessConfirmAnswerSchema, "input"));
75
+
76
+ /** The question about a discovered harness: a form the owner fills to say yes, or says no in. */
77
+ function confirmQuestion(proposal: HarnessProposal): Question {
78
+ return {
79
+ kind: "form",
80
+ title: "add this harness?",
81
+ detail: [`kind: ${proposal.kind}`, ...(proposal.binary === undefined ? [] : [`binary: ${proposal.binary}`]), `home: ${proposal.home}`].join("\n"),
82
+ schema: CONFIRM_FORM,
83
+ };
84
+ }
85
+
86
+ /**
87
+ * What the requests module is asked for.
88
+ *
89
+ * The shape is the contract of the name: this module does not import the requests module,
90
+ * so it declares what it sends, and the requests module checks it.
91
+ */
92
+ interface RequestAskInput {
93
+ /** Who may answer. */
94
+ to: { readonly kind: "owner" };
95
+ /** The name of the question. */
96
+ question: string;
97
+ /** What is asked: the question, whole. */
98
+ input: Question;
99
+ /** When the question stops waiting. Without one it waits for ever. */
100
+ deadline?: Timestamp;
101
+ }
102
+
103
+ /** What the requests module answers: the answer, with the id of the request. */
104
+ interface RequestAskOutput {
105
+ readonly answer: Answer;
106
+ }
107
+
108
+ /** What the plugin needs to confirm a proposal. */
109
+ export interface HarnessConfirmOptions {
110
+ /** Where the confirmed instances are put. */
111
+ readonly registry: HarnessInstanceRegistry;
112
+ /**
113
+ * The sides of each kind, by kind name. The kind says which sides it has; this says what each
114
+ * of them can do. A kind that is not named has no sides.
115
+ */
116
+ readonly sides?: Readonly<Record<string, SideCapabilities>>;
117
+ /**
118
+ * The kinds, when they are known: a confirmed installation is bound by its kind, and may claim no
119
+ * more than the kind declares, so sides that would widen the declaration are refused instead of
120
+ * registered.
121
+ */
122
+ readonly kinds?: HarnessKindRegistry;
123
+ }
124
+
125
+ /** The plugin that asks the owner about a proposal and registers what the owner confirms. */
126
+ export function harnessConfirm(options: HarnessConfirmOptions): Plugin {
127
+ const registry = options.registry;
128
+ const sides = options.sides ?? {};
129
+ // With its kind known, a confirmed installation is bound by it: it gets its own sides, and claims no more than the kind declares.
130
+ const bindingOf = (confirmed: ConfirmedInstallation): HarnessBinding => {
131
+ const claimed = sides[String(confirmed.kind)] ?? {};
132
+ const kind = options.kinds?.get(confirmed.kind);
133
+ if (kind === undefined) return { instance: { ...confirmed, sides: claimed } };
134
+ return kind.bind({ ...confirmed, sides: claimed });
135
+ };
136
+ return plugin("harness-confirm", (api) => {
137
+ api.declare(HarnessConfirmed);
138
+
139
+ // The registry is memory and the journal is the truth: what the owner confirmed before the
140
+ // host stopped is put back when it serves again.
141
+ api.service(() => {
142
+ for (const written of api.journal?.()?.since(seq(0), [HarnessConfirmed.name]) ?? []) {
143
+ register(registry, bindingOf(ConfirmedInstallationSchema.parse(written.data)));
144
+ }
145
+ return () => {};
146
+ });
147
+
148
+ api.on(HarnessProposed, async (data, step, record) => {
149
+ const answer = await askOwner(step, data, record.id);
150
+ // The question ended without an answer: the proposal stays a proposal.
151
+ if (answer === undefined) return;
152
+ // The owner said no: nothing is written and nothing is registered.
153
+ if (answer.answer === "no") return;
154
+
155
+ const confirmed = {
156
+ id: answer.id,
157
+ kind: data.kind,
158
+ machine: answer.machine,
159
+ home: data.home,
160
+ ...(data.binary === undefined ? {} : { binary: data.binary }),
161
+ };
162
+ const binding = bindingOf(confirmed);
163
+ // Refused before anything is written: a confirmation the registry cannot take must not
164
+ // reach the journal, where it would be put back at every start.
165
+ checkFree(registry, binding.instance);
166
+ await step.emit(HarnessConfirmed, confirmed);
167
+ register(registry, binding);
168
+ });
169
+ });
170
+ }
171
+
172
+ /**
173
+ * The question for the owner, and the answer when there is one.
174
+ *
175
+ * A request that is cancelled or has expired ends the wait with a typed error of its own. The
176
+ * owner did not answer, so the proposal stays a proposal and nothing is registered.
177
+ */
178
+ async function askOwner(
179
+ step: Step,
180
+ proposal: HarnessProposal,
181
+ key: string,
182
+ ): Promise<HarnessConfirmAnswer | undefined> {
183
+ try {
184
+ const { answer } = await step<RequestAskInput, RequestAskOutput>(
185
+ REQUEST_ASK,
186
+ { to: { kind: "owner" }, question: HARNESS_CONFIRM_QUESTION, input: confirmQuestion(proposal) },
187
+ // The step is named by the proposal: the same proposal is the same question, however many
188
+ // times it is found.
189
+ { key },
190
+ );
191
+ // The requests module checked the value against the schema of the form; it is read here once more for its type.
192
+ return "form" in answer ? HarnessConfirmAnswerSchema.parse(answer.form) : undefined;
193
+ } catch (error) {
194
+ if (reasonOf(error) === undefined) throw error;
195
+ return undefined;
196
+ }
197
+ }
198
+
199
+ /**
200
+ * Put the confirmed instance into the registry.
201
+ *
202
+ * An id is taken once: a confirmation that is made again finds the instance that is already there
203
+ * and changes nothing. A different instance under the same id is refused — the owner's id names
204
+ * one installation, and two of them cannot both be it.
205
+ */
206
+ function register(registry: HarnessInstanceRegistry, binding: HarnessBinding): void {
207
+ if (checkFree(registry, binding.instance)) registry.register(binding);
208
+ }
209
+
210
+ /** True when the id is free; false when the very same instance is there; throws for another one. */
211
+ function checkFree(registry: HarnessInstanceRegistry, instance: Harness): boolean {
212
+ const there = registry.get(instance.id);
213
+ if (there === undefined) return true;
214
+ if (stableJson(there) !== stableJson(instance)) {
215
+ throw new Error(
216
+ `harness instance "${instance.id}" is already registered and is not the one that was confirmed`,
217
+ );
218
+ }
219
+ return false;
220
+ }
221
+
222
+ /** Why the wait ended without an answer: "cancelled" or "expired"; nothing else is ours. */
223
+ function reasonOf(error: unknown): "cancelled" | "expired" | undefined {
224
+ if (!(error instanceof Error)) return undefined;
225
+ if (error.name === "RequestCancelled") return "cancelled";
226
+ if (error.name === "RequestExpired") return "expired";
227
+ return undefined;
228
+ }
@@ -0,0 +1,107 @@
1
+ /**
2
+ * The plugin that finds the installed harnesses.
3
+ *
4
+ * The finding itself, `discover()`, is the harness module's: it looks at the machine and says what
5
+ * it found. This is the niwa side of it: the record of a proposal, and the action
6
+ * `harness.discover` that makes the finding and writes the proposals.
7
+ */
8
+
9
+ import { createHash } from "node:crypto";
10
+
11
+ import { z } from "zod";
12
+
13
+ import { action, actionRef, record, recordId, stableJson } from "@niwa-labs/core";
14
+ import { plugin } from "@niwa-labs/plugin";
15
+ import type { Plugin } from "@niwa-labs/plugin";
16
+ import { HarnessMissingSchema, HarnessProposalSchema, discover } from "@niwa-labs/harness";
17
+ import type { DiscoverEnv, HarnessKindDefinition, HarnessProposal } from "@niwa-labs/harness";
18
+
19
+ /** An installation was found. The owner confirms it, and the instance it becomes is the owner's. */
20
+ export const HarnessProposed = record("harness.proposed", HarnessProposalSchema);
21
+
22
+ /**
23
+ * The id of the record of a proposal.
24
+ *
25
+ * It follows the installation: the same kind, the same binary, the same version and the same
26
+ * home are one proposal, so a second finding finds the record that is already there and writes
27
+ * nothing new. The home is part of the id because the record carries it: an installation whose
28
+ * home has moved is another proposal, not a contradiction of the first one.
29
+ */
30
+ export function proposalIdOf(proposal: HarnessProposal): string {
31
+ const hash = createHash("sha256")
32
+ .update(
33
+ stableJson({
34
+ kind: proposal.kind,
35
+ path: proposal.binary?.path ?? "",
36
+ version: proposal.binary?.version ?? "",
37
+ home: proposal.home,
38
+ }),
39
+ )
40
+ .digest("hex");
41
+ return recordId(`prop_${hash.slice(0, 32)}`);
42
+ }
43
+
44
+ /** The name of the action the finding is called by. */
45
+ export const HARNESS_DISCOVER_ACTION = "harness.discover";
46
+
47
+ /** What the action answers: the installations that are there, and the kinds that are not. */
48
+ export const HarnessDiscoverOutputSchema = z.object({
49
+ proposals: z.array(HarnessProposalSchema),
50
+ missing: z.array(HarnessMissingSchema),
51
+ });
52
+ export type HarnessDiscoverOutput = z.output<typeof HarnessDiscoverOutputSchema>;
53
+
54
+ /** The finding, as a typed reference: what a caller imports to call `harness.discover`. */
55
+ export const harnessDiscover = actionRef(HARNESS_DISCOVER_ACTION, {
56
+ description:
57
+ "Finds the harnesses installed on this machine and proposes instances of them. A proposal is not an instance: the id and the machine are the owner's to give.",
58
+ input: z.object({
59
+ /** Only these kinds. Every kind of the plugin when it is absent. */
60
+ kinds: z.array(z.string().min(1)).optional(),
61
+ }),
62
+ output: HarnessDiscoverOutputSchema,
63
+ });
64
+
65
+ /** What the finding is given. */
66
+ export interface HarnessDiscoveryOptions {
67
+ /** The kinds to look for. Each of them says how it is found. */
68
+ readonly kinds: readonly HarnessKindDefinition[];
69
+ /** The environment to look in. The environment of the process when it is absent. */
70
+ readonly env?: DiscoverEnv;
71
+ }
72
+
73
+ /**
74
+ * The plugin that finds the installed harnesses.
75
+ *
76
+ * It declares the record of a proposal and the action that makes the finding. The proposals
77
+ * are written by the plugin and not by the call: their ids follow the installations, so a
78
+ * second finding of the same installations writes nothing new.
79
+ */
80
+ export function harnessDiscovery(options: HarnessDiscoveryOptions): Plugin {
81
+ const env = options.env ?? process.env;
82
+ return plugin("harness-discovery", (api) => {
83
+ api.declare(HarnessProposed);
84
+
85
+ api.action(
86
+ action(harnessDiscover, {
87
+ // The finding changes nothing that cannot be made again: the proposals are written
88
+ // under ids that follow the installations.
89
+ recovery: "repeat",
90
+ effect: "read",
91
+ world: "local",
92
+ run: async (input): Promise<HarnessDiscoverOutput> => {
93
+ const wanted = input.kinds;
94
+ const kinds =
95
+ wanted === undefined
96
+ ? options.kinds
97
+ : options.kinds.filter((kind) => wanted.includes(String(kind.kind)));
98
+ const { proposals, missing } = await discover(kinds, env);
99
+ for (const proposal of proposals) {
100
+ await api.emit(HarnessProposed, proposal, { id: proposalIdOf(proposal) });
101
+ }
102
+ return { proposals: [...proposals], missing: [...missing] };
103
+ },
104
+ }),
105
+ );
106
+ });
107
+ }
@@ -0,0 +1,64 @@
1
+ /**
2
+ * The identity of a session, as niwa sees it.
3
+ *
4
+ * A session is the pair of a harness id and the id that harness gave it: two harnesses may use the
5
+ * same native id, and they are different sessions. A session niwa starts also gets an id of niwa's
6
+ * own, `s-…`, issued from the starting call and recorded next to the pair: that is what a person
7
+ * reads and types. Where the harness has not named a session yet, there is no session, only a
8
+ * start in progress.
9
+ */
10
+
11
+ import { z } from "zod";
12
+
13
+ import { idSchema } from "@niwa-labs/core";
14
+ import type { Id } from "@niwa-labs/core";
15
+
16
+ import { HarnessIdSchema, NativeSessionIdSchema } from "@niwa-labs/harness";
17
+ import type { SessionId } from "@niwa-labs/harness";
18
+
19
+ /**
20
+ * How a session is named in niwa's own records.
21
+ *
22
+ * It is the same pair the harness uses, written as one string so it can be a record field and a
23
+ * key of the index. The separator is a space, which no harness id and no native id may hold: a
24
+ * harness id has no whitespace, and a native id with whitespace in it is not a name.
25
+ */
26
+ export const SessionRefSchema = z.string().min(1).brand<"SessionRef">();
27
+
28
+ export type SessionRef = z.output<typeof SessionRefSchema>;
29
+
30
+ /** The id niwa gives a session it started: `s-3fa9c2`. */
31
+ export const NiwaSessionIdSchema = idSchema("session");
32
+
33
+ export type NiwaSessionId = Id<"session">;
34
+
35
+ /** The separator between the two parts of a session reference. */
36
+ const SEPARATOR = " ";
37
+
38
+ /**
39
+ * The reference of a session: the harness id and the native id, joined.
40
+ *
41
+ * The two parts are joined rather than nested so that a reference is a key: the catalog indexes
42
+ * by it, and two references are equal when they are the same string.
43
+ */
44
+ export function sessionRef(id: SessionId): SessionRef {
45
+ return SessionRefSchema.parse(`${id.harness}${SEPARATOR}${id.native}`);
46
+ }
47
+
48
+ /**
49
+ * The session a reference names.
50
+ *
51
+ * A reference that does not name two parts is refused: a reference that cannot be split would
52
+ * name no harness, and a session without a harness is not a session.
53
+ */
54
+ export function sessionOf(ref: SessionRef): SessionId {
55
+ const text = ref as unknown as string;
56
+ const at = text.indexOf(SEPARATOR);
57
+ if (at <= 0 || at === text.length - 1) {
58
+ throw new TypeError(`a session reference must be "<harness> <native>", got ${JSON.stringify(text)}`);
59
+ }
60
+ return {
61
+ harness: HarnessIdSchema.parse(text.slice(0, at)),
62
+ native: NativeSessionIdSchema.parse(text.slice(at + 1)),
63
+ };
64
+ }