@niwa-labs/agent 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 +2 -2
- package/package.json +19 -4
- package/src/digest.ts +93 -0
- package/src/index.ts +900 -0
- package/src/records.ts +386 -0
- package/src/workflows/session-digest.ts +22 -0
- package/tsconfig.json +6 -0
package/src/records.ts
ADDED
|
@@ -0,0 +1,386 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The records entry of the agent module: what another plugin may import from it. The definition of an
|
|
3
|
+
* agent, the records the module writes, the typed references of its actions and the hooks a later plugin
|
|
4
|
+
* reads (the sections of a briefing, the digests of attached sessions); no factory and nothing that runs.
|
|
5
|
+
*
|
|
6
|
+
* An agent is a lasting actor with a name, called at `agent:<name>`. Its definition says what it runs on,
|
|
7
|
+
* what it is told and what it may reach; which session it is on, what waits in its inbox and which native
|
|
8
|
+
* sessions are attached to it are facts of the journal, folded when they are needed.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import { createHash } from "node:crypto";
|
|
12
|
+
|
|
13
|
+
import { z } from "zod";
|
|
14
|
+
|
|
15
|
+
import { Address, actionRef, providerWrote, record, stableJson } from "@niwa-labs/core";
|
|
16
|
+
import { ReplyRoute } from "@niwa-labs/messages/records";
|
|
17
|
+
import { offerKey, trigger } from "@niwa-labs/plugin";
|
|
18
|
+
import type { OfferKey, Trigger } from "@niwa-labs/plugin";
|
|
19
|
+
import { DeliveryReceiptSchema } from "@niwa-labs/sessions/records";
|
|
20
|
+
|
|
21
|
+
/** The name of an agent: lowercase words joined by `-`, `_` or `.`; its address is `agent:<name>`. */
|
|
22
|
+
export const AgentName = z
|
|
23
|
+
.string()
|
|
24
|
+
.regex(/^[a-z0-9][a-z0-9._-]{0,63}$/, "an agent's name is lowercase letters, digits, '.', '_' or '-', at most 64");
|
|
25
|
+
export type AgentName = z.output<typeof AgentName>;
|
|
26
|
+
|
|
27
|
+
/** The tools an agent's sessions may use: the harness's own, only niwa's, or exactly these of the harness's own. */
|
|
28
|
+
export const AgentTools = z.union([z.literal("all"), z.literal("niwa-only"), z.object({ allow: z.array(z.string().min(1)) }).strict()]);
|
|
29
|
+
export type AgentTools = z.output<typeof AgentTools>;
|
|
30
|
+
|
|
31
|
+
/** The project an agent is bound to: the directory its sessions work in, and the direction it leads, when it leads one. */
|
|
32
|
+
export const AgentProject = z.object({ cwd: z.string().min(1), direction: z.string().min(1).optional() }).strict();
|
|
33
|
+
export type AgentProject = z.output<typeof AgentProject>;
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* What an agent is: what it runs on (a harness installation, or a role the composition maps to one), what
|
|
37
|
+
* its sessions are told (its prompt, and its character apart from it), its hands (the niwa actions its
|
|
38
|
+
* sessions see: what is offered to the model; each call is still held to the session's grant), the tools
|
|
39
|
+
* of the harness it may use, and the project it is bound to.
|
|
40
|
+
*/
|
|
41
|
+
export const AgentDefinition = z
|
|
42
|
+
.object({
|
|
43
|
+
name: AgentName,
|
|
44
|
+
harness: z.string().min(1).optional(),
|
|
45
|
+
role: z.string().min(1).optional(),
|
|
46
|
+
prompt: z.string().min(1),
|
|
47
|
+
character: z.string().min(1).optional(),
|
|
48
|
+
hands: z.array(z.string().min(1)).default([]),
|
|
49
|
+
tools: AgentTools.default("all"),
|
|
50
|
+
project: AgentProject.optional(),
|
|
51
|
+
})
|
|
52
|
+
.strict()
|
|
53
|
+
.refine((definition) => (definition.harness === undefined) !== (definition.role === undefined), "an agent runs on a harness or on a role, exactly one of them");
|
|
54
|
+
export type AgentDefinition = z.output<typeof AgentDefinition>;
|
|
55
|
+
export type AgentDefinitionInput = z.input<typeof AgentDefinition>;
|
|
56
|
+
|
|
57
|
+
/** The parts of a definition that are versioned apart: a session started from it says the version of each. */
|
|
58
|
+
export const DEFINITION_PARTS = ["prompt", "character", "hands", "tools", "project"] as const;
|
|
59
|
+
export type DefinitionPart = (typeof DEFINITION_PARTS)[number];
|
|
60
|
+
|
|
61
|
+
/** The version of a part: the first twelve hex digits of the SHA-256 of its value. */
|
|
62
|
+
export const PartVersion = z.string().regex(/^[0-9a-f]{12}$/);
|
|
63
|
+
|
|
64
|
+
/** The versions of the parts a definition has. */
|
|
65
|
+
export const PartVersions = z.partialRecord(z.enum(DEFINITION_PARTS), PartVersion);
|
|
66
|
+
export type PartVersions = z.output<typeof PartVersions>;
|
|
67
|
+
|
|
68
|
+
/** The versions of the parts of a definition; a part the definition does not have has none. */
|
|
69
|
+
export function partVersions(definition: AgentDefinition): PartVersions {
|
|
70
|
+
const versions: PartVersions = {};
|
|
71
|
+
for (const part of DEFINITION_PARTS) {
|
|
72
|
+
const value = definition[part];
|
|
73
|
+
if (value !== undefined) versions[part] = createHash("sha256").update(stableJson(value)).digest("hex").slice(0, 12);
|
|
74
|
+
}
|
|
75
|
+
return versions;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** A session as the sessions module names it: `<harness> <native>`. */
|
|
79
|
+
export const SessionRefText = z.string().regex(/^\S+ \S+$/, "a session is named `<harness> <native>`");
|
|
80
|
+
|
|
81
|
+
/** An agent was made while the host ran (`agent.create`); one in the composition needs no record. */
|
|
82
|
+
export const AgentCreated = record("agent.created", z.object({ agent: AgentName, definition: AgentDefinition }));
|
|
83
|
+
|
|
84
|
+
/** How an agent's new main session came to be: its first, or one seeded from the session before it. */
|
|
85
|
+
export const SessionOrigin = z.discriminatedUnion("kind", [
|
|
86
|
+
z.object({ kind: z.literal("first") }),
|
|
87
|
+
z.object({
|
|
88
|
+
kind: z.literal("seeded"),
|
|
89
|
+
/** The session before it, which the seed points back to. */
|
|
90
|
+
from: SessionRefText,
|
|
91
|
+
/** What the seed is: the harness's own compaction summary, or a brief niwa read from the transcript. */
|
|
92
|
+
seed: z.enum(["compaction", "transcript"]),
|
|
93
|
+
}),
|
|
94
|
+
]);
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* An agent got a new main session. The role it was started under and the version of each part of the
|
|
98
|
+
* definition are written with it, so what a verdict of that session rested on is known later.
|
|
99
|
+
*/
|
|
100
|
+
export const AgentSessionStarted = record(
|
|
101
|
+
"agent.session.started",
|
|
102
|
+
z.object({
|
|
103
|
+
agent: AgentName,
|
|
104
|
+
session: SessionRefText,
|
|
105
|
+
/** The id niwa gave the session (`s-…`). */
|
|
106
|
+
id: z.string().min(1),
|
|
107
|
+
/** The harness installation the session runs on. */
|
|
108
|
+
harness: z.string().min(1),
|
|
109
|
+
/** The role the harness was chosen by, when the agent runs on a role. */
|
|
110
|
+
role: z.string().min(1).optional(),
|
|
111
|
+
firstTurn: z.object({ turn: z.string(), receipt: DeliveryReceiptSchema.optional() }).optional(),
|
|
112
|
+
parts: PartVersions,
|
|
113
|
+
origin: SessionOrigin,
|
|
114
|
+
}),
|
|
115
|
+
);
|
|
116
|
+
|
|
117
|
+
/** Who a turn is from. An address, or niwa itself (a handler, a workflow run): a fact niwa states. */
|
|
118
|
+
export const TurnAuthor = z.union([Address, z.object({ kind: z.literal("niwa"), by: z.string().min(1) }).strict()]);
|
|
119
|
+
export type TurnAuthor = z.output<typeof TurnAuthor>;
|
|
120
|
+
|
|
121
|
+
/** Where a fact came from, when it is more than its author: the digest of an attached session, from a locator up to one. */
|
|
122
|
+
export const TurnSource = z.discriminatedUnion("kind", [
|
|
123
|
+
z.object({
|
|
124
|
+
kind: z.literal("session-digest"),
|
|
125
|
+
session: SessionRefText,
|
|
126
|
+
/** The locator the digest was read after; absent from the start of the transcript. */
|
|
127
|
+
from: z.string().min(1).optional(),
|
|
128
|
+
/** The last record the digest holds: where the next digest of the session is read after. */
|
|
129
|
+
upto: z.string().min(1),
|
|
130
|
+
}),
|
|
131
|
+
z.object({ kind: z.literal("task"), task: z.string().min(1) }),
|
|
132
|
+
]);
|
|
133
|
+
export type TurnSource = z.output<typeof TurnSource>;
|
|
134
|
+
|
|
135
|
+
/** The id of a turn: the id of the message it carries, or `fact-<hex>` for a fact. */
|
|
136
|
+
export const TurnId = z.string().regex(/^(msg|fact)-[0-9a-f]{6,16}$/);
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* A turn waits in an agent's inbox: a message to its address, or a fact it was told.
|
|
140
|
+
*
|
|
141
|
+
* The author is kept as it was, and the turn carries no rights of its author: the session it reaches holds
|
|
142
|
+
* its own grant, made from the agent's hands, whoever wrote.
|
|
143
|
+
*/
|
|
144
|
+
export const AgentTurnQueued = record(
|
|
145
|
+
"agent.turn.queued",
|
|
146
|
+
z.object({
|
|
147
|
+
agent: AgentName,
|
|
148
|
+
turn: TurnId,
|
|
149
|
+
kind: z.enum(["message", "fact"]),
|
|
150
|
+
author: TurnAuthor,
|
|
151
|
+
replyTo: ReplyRoute.optional(),
|
|
152
|
+
text: z.string(),
|
|
153
|
+
source: TurnSource.optional(),
|
|
154
|
+
attachment: z.string().optional(),
|
|
155
|
+
more: z.boolean().optional(),
|
|
156
|
+
}),
|
|
157
|
+
{ providerOnly: "agents" },
|
|
158
|
+
);
|
|
159
|
+
|
|
160
|
+
/** The main session and delivery path selected before this turn touches a harness. */
|
|
161
|
+
export const AgentTurnRouted = record("agent.turn.routed", z.object({
|
|
162
|
+
agent: AgentName, turn: TurnId, session: SessionRefText.optional(), held: z.boolean(),
|
|
163
|
+
}), { providerOnly: "agents" });
|
|
164
|
+
|
|
165
|
+
/** A turn reached the agent's main session. */
|
|
166
|
+
export const AgentTurnDelivered = record(
|
|
167
|
+
"agent.turn.delivered",
|
|
168
|
+
z.object({ agent: AgentName, turn: TurnId, session: SessionRefText, receipt: DeliveryReceiptSchema }),
|
|
169
|
+
{ providerOnly: "agents" },
|
|
170
|
+
);
|
|
171
|
+
|
|
172
|
+
/** The session accepted a routed turn and answered it. Each turn has one reply. */
|
|
173
|
+
export const AgentTurnReplied = record("agent.turn.replied", z.object({
|
|
174
|
+
agent: AgentName, turn: TurnId, text: z.string().min(1), replyTo: ReplyRoute,
|
|
175
|
+
}), {
|
|
176
|
+
providerOnly: "agents",
|
|
177
|
+
guard: {
|
|
178
|
+
group: "agent.turn.reply",
|
|
179
|
+
key: (reply) => reply.turn,
|
|
180
|
+
initial: () => false,
|
|
181
|
+
admit: (answered) => answered ? { code: "already-answered", reason: "The turn already has a reply" } : undefined,
|
|
182
|
+
fold: (answered, _reply, row) => answered || providerWrote(row, "agents"),
|
|
183
|
+
},
|
|
184
|
+
});
|
|
185
|
+
|
|
186
|
+
/** A turn did not reach the agent: `unsent` when it surely did not go, `possibly-sent` when it may have. */
|
|
187
|
+
export const AgentTurnFailed = record(
|
|
188
|
+
"agent.turn.failed",
|
|
189
|
+
z.object({ agent: AgentName, turn: TurnId, status: z.enum(["unsent", "possibly-sent"]), reason: z.string() }),
|
|
190
|
+
{ providerOnly: "agents" },
|
|
191
|
+
);
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* A native session was attached to an agent. A session is attached to one agent: a new attachment replaces
|
|
195
|
+
* the one before. `from` is the last record of the transcript when it was attached: what the agent learns
|
|
196
|
+
* of the session begins after it, and what came before is in the briefing's place, not in a digest.
|
|
197
|
+
*/
|
|
198
|
+
export const AgentAttached = record(
|
|
199
|
+
"agent.attached",
|
|
200
|
+
z.object({ agent: AgentName, session: SessionRefText, cwd: z.string().min(1), from: z.string().min(1).optional(), pending: z.literal(true).optional() }),
|
|
201
|
+
);
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* An attached session paused or ended: what it did since the last digest is due to its agent. Only the
|
|
205
|
+
* sessions attached to an agent have one, so the workflow that reads the digest runs for them alone.
|
|
206
|
+
*/
|
|
207
|
+
export const AgentDigestDue = record("agent.digest.due", z.object({ agent: AgentName, session: SessionRefText, attachment: z.string(), ended: z.boolean() }));
|
|
208
|
+
|
|
209
|
+
/** A native session was let go of. */
|
|
210
|
+
export const AgentDetached = record("agent.detached", z.object({ agent: AgentName, session: SessionRefText }));
|
|
211
|
+
|
|
212
|
+
/** The journal position before an attach or detach starts changing a watch. */
|
|
213
|
+
export const AgentAttachmentChanging = record("agent.attachment.changing", z.object({ session: SessionRefText }));
|
|
214
|
+
|
|
215
|
+
/** A transcript boundary established without sending a fact. */
|
|
216
|
+
export const AgentDigestAdvanced = record("agent.digest.advanced", z.object({
|
|
217
|
+
session: SessionRefText, attachment: z.string(), upto: z.string().optional(), operation: z.string(), more: z.boolean(),
|
|
218
|
+
}));
|
|
219
|
+
|
|
220
|
+
/** The record types the module declares. */
|
|
221
|
+
export const AGENT_TYPES = [AgentCreated, AgentSessionStarted, AgentTurnRouted, AgentTurnQueued, AgentTurnDelivered, AgentTurnReplied, AgentTurnFailed, AgentAttached, AgentDetached, AgentDigestDue, AgentAttachmentChanging, AgentDigestAdvanced] as const;
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* The digests of attached sessions, as they reach an agent: what a plugin that takes them in (a memory)
|
|
225
|
+
* subscribes to. The fact carries the agent, the text and where in the transcript it was read.
|
|
226
|
+
*/
|
|
227
|
+
export const SessionDigestTaken: Trigger<z.output<typeof AgentTurnQueued.schema>> = trigger(AgentTurnQueued, {
|
|
228
|
+
name: "agent.turn.queued:session-digest",
|
|
229
|
+
filter: { "source.kind": "session-digest" },
|
|
230
|
+
});
|
|
231
|
+
|
|
232
|
+
/** A section a plugin adds to every briefing: the action that writes it, asked with `{ agent }`, answering `{ text }`. */
|
|
233
|
+
export interface BriefingSection {
|
|
234
|
+
/** The heading of the section. */
|
|
235
|
+
readonly title: string;
|
|
236
|
+
/** The action that writes it: input `BriefingSectionInput`, output `BriefingSectionOutput`. */
|
|
237
|
+
readonly action: string;
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
/** Where a plugin offers a section of the briefing (`api.offer(AGENT_BRIEFING, { title, action })`). */
|
|
241
|
+
export const AGENT_BRIEFING: OfferKey<BriefingSection> = offerKey("agent.briefing", "agents");
|
|
242
|
+
|
|
243
|
+
/** What the action of a briefing section is asked with. */
|
|
244
|
+
export const BriefingSectionInput = z.object({ agent: AgentName });
|
|
245
|
+
/** What it answers: the text of the section; an empty text leaves the section out. */
|
|
246
|
+
export const BriefingSectionOutput = z.object({ text: z.string() });
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* A section a plugin adds to the prompt of an agent's sessions: the action that writes it, asked with `{ agent }` when a
|
|
250
|
+
* session of the agent starts, answering `{ text }`. It goes as a stable section after the agent's own prompt, so what it
|
|
251
|
+
* says is read live at each start (a charter that grows), not fixed when the plugin is set up. An empty text leaves it out.
|
|
252
|
+
*/
|
|
253
|
+
export interface PromptSectionOffer {
|
|
254
|
+
/** Its name among the sections of the offering plugin; the session sees it as `<plugin>:<id>`. */
|
|
255
|
+
readonly id: string;
|
|
256
|
+
/** The action that writes it: input `PromptSectionInput`, output `PromptSectionOutput`. */
|
|
257
|
+
readonly action: string;
|
|
258
|
+
/** The agent whose sessions it is for; absent, every agent's. */
|
|
259
|
+
readonly agent?: string;
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
/** Where a plugin offers a section of the prompt of an agent's sessions (`api.offer(AGENT_PROMPT_SECTION, { id, action })`). */
|
|
263
|
+
export const AGENT_PROMPT_SECTION: OfferKey<PromptSectionOffer> = offerKey("agent.prompt", "agents");
|
|
264
|
+
|
|
265
|
+
/** What the action of a prompt section is asked with. */
|
|
266
|
+
export const PromptSectionInput = z.object({ agent: AgentName });
|
|
267
|
+
/** What it answers: the text of the section; an empty text leaves the section out. */
|
|
268
|
+
export const PromptSectionOutput = z.object({ text: z.string() });
|
|
269
|
+
|
|
270
|
+
/** One agent as the list shows it. */
|
|
271
|
+
export const AgentStatus = z.enum(["new", "working", "asleep"]);
|
|
272
|
+
export type AgentStatus = z.output<typeof AgentStatus>;
|
|
273
|
+
|
|
274
|
+
const AgentItem = z.object({
|
|
275
|
+
name: AgentName,
|
|
276
|
+
address: z.object({ kind: z.literal("agent"), id: AgentName }),
|
|
277
|
+
/** Where the agent is defined: the composition, or `agent.create`. */
|
|
278
|
+
source: z.enum(["config", "runtime"]),
|
|
279
|
+
status: AgentStatus,
|
|
280
|
+
/** The main session, when it has one. */
|
|
281
|
+
session: SessionRefText.optional(),
|
|
282
|
+
});
|
|
283
|
+
|
|
284
|
+
export const agentCreate = actionRef("agent.create", {
|
|
285
|
+
description:
|
|
286
|
+
"Makes an agent while the host runs: its name, the harness or role it runs on, its prompt and character, its hands (the niwa actions its sessions see), its tools and its project. A name that is taken is refused. The agent sleeps until something is said to it.",
|
|
287
|
+
input: AgentDefinition,
|
|
288
|
+
output: z.object({ agent: AgentName, address: z.object({ kind: z.literal("agent"), id: AgentName }) }),
|
|
289
|
+
});
|
|
290
|
+
|
|
291
|
+
export const agentList = actionRef("agent.list", {
|
|
292
|
+
description: "Lists the agents: the ones of the composition and the ones made with agent.create, with where each stands and its main session.",
|
|
293
|
+
input: z.object({}),
|
|
294
|
+
output: z.object({ items: z.array(AgentItem) }),
|
|
295
|
+
});
|
|
296
|
+
|
|
297
|
+
export const agentGet = actionRef("agent.get", {
|
|
298
|
+
description: "Gets one agent: its definition, where it stands, its main session, the turns waiting in its inbox and the native sessions attached to it.",
|
|
299
|
+
input: z.object({ agent: AgentName }),
|
|
300
|
+
output: AgentItem.extend({
|
|
301
|
+
definition: AgentDefinition,
|
|
302
|
+
queued: z.number().int().nonnegative(),
|
|
303
|
+
attached: z.array(z.object({ session: SessionRefText, cwd: z.string() })),
|
|
304
|
+
}),
|
|
305
|
+
});
|
|
306
|
+
|
|
307
|
+
export const agentReply = actionRef("agent.reply", {
|
|
308
|
+
description: "Reply once to the owner in the conversation of a turn delivered to this session. Use the turn ID in the incoming message.",
|
|
309
|
+
input: z.strictObject({ turn: TurnId, text: z.string().min(1) }),
|
|
310
|
+
output: z.object({ turn: TurnId }),
|
|
311
|
+
});
|
|
312
|
+
|
|
313
|
+
export const agentTell = actionRef("agent.tell", {
|
|
314
|
+
description:
|
|
315
|
+
"Says something to an agent: a message to its address, from the address the caller speaks as. It becomes a turn of the agent's main session, which wakes for it; the answer is not waited for.",
|
|
316
|
+
input: z.object({ agent: AgentName, text: z.string().min(1), replyTo: ReplyRoute.optional() }),
|
|
317
|
+
output: z.object({ message: z.string().min(1) }),
|
|
318
|
+
});
|
|
319
|
+
|
|
320
|
+
export const agentNotify = actionRef("agent.notify", {
|
|
321
|
+
description:
|
|
322
|
+
"Tells an agent a fact: a turn of its main session that says what happened, from whoever states it. A fact carries no right of its author: it is never the owner's decision.",
|
|
323
|
+
input: z.object({ agent: AgentName, text: z.string().min(1), source: z.object({ kind: z.literal("task"), task: z.string().min(1) }).optional() }),
|
|
324
|
+
output: z.object({ turn: TurnId }),
|
|
325
|
+
});
|
|
326
|
+
|
|
327
|
+
export const agentAttach = actionRef("agent.attach", {
|
|
328
|
+
description:
|
|
329
|
+
"Attaches a native session to an agent (the default agent when none is named) and answers the agent's briefing. The session is named by its harness installation or its kind and its native id; a session is attached to one agent, and a new attachment replaces the one before. The session is watched from now on, and what it does reaches the agent as digests at its pauses.",
|
|
330
|
+
input: z
|
|
331
|
+
.object({
|
|
332
|
+
agent: AgentName.optional(),
|
|
333
|
+
/** The harness installation the session belongs to. */
|
|
334
|
+
harness: z.string().min(1).optional(),
|
|
335
|
+
/** The kind of harness, when the caller knows only that: the installation of that kind is found. */
|
|
336
|
+
kind: z.string().min(1).optional(),
|
|
337
|
+
native: z.string().min(1),
|
|
338
|
+
cwd: z.string().min(1),
|
|
339
|
+
/** The process of the harness the session runs in, when the caller knows it: its exit is a sign of the session's end. */
|
|
340
|
+
pid: z.number().int().positive().optional(),
|
|
341
|
+
})
|
|
342
|
+
.refine((input) => input.harness !== undefined || input.kind !== undefined, "the session needs its harness or its kind"),
|
|
343
|
+
output: z.object({ agent: AgentName, session: SessionRefText, replaced: AgentName.optional(), watching: z.boolean(), pending: z.literal(true).optional(), briefing: z.string() }),
|
|
344
|
+
});
|
|
345
|
+
|
|
346
|
+
export const agentDetach = actionRef("agent.detach", {
|
|
347
|
+
description: "Lets go of a native session attached to an agent: it is no longer watched for the agent.",
|
|
348
|
+
input: z.object({ session: SessionRefText }),
|
|
349
|
+
output: z.object({ agent: AgentName.optional() }),
|
|
350
|
+
});
|
|
351
|
+
|
|
352
|
+
export const agentAttachment = actionRef("agent.attachment", {
|
|
353
|
+
description: "The agent a native session is attached to, and the locator its last digest was read up to (or the one it was attached at).",
|
|
354
|
+
input: z.object({ session: SessionRefText }),
|
|
355
|
+
output: z.object({ agent: AgentName.optional(), attachment: z.string().optional(), pending: z.literal(true).optional(), upto: z.string().min(1).optional() }),
|
|
356
|
+
});
|
|
357
|
+
|
|
358
|
+
/** Read and publish the next bounded part of the current attachment's transcript. */
|
|
359
|
+
export const agentDigestRead = actionRef("agent.digest.read", {
|
|
360
|
+
description: "Reads a part of an attached session and commits its digest if its attachment and starting position still match.",
|
|
361
|
+
input: z.object({ session: SessionRefText, attachment: z.string(), from: z.string().optional(), pending: z.boolean().optional(), ended: z.boolean() }),
|
|
362
|
+
output: z.object({ more: z.boolean(), stale: z.literal(true).optional(), upto: z.string().optional() }),
|
|
363
|
+
});
|
|
364
|
+
|
|
365
|
+
export const agentBriefing = actionRef("agent.briefing", {
|
|
366
|
+
description:
|
|
367
|
+
"The briefing of an agent: where its work stands, what waits in its inbox, the tasks it asked for that are open, its questions to the owner that wait, the latest facts it was told, and the sections other plugins add.",
|
|
368
|
+
input: z.object({ agent: AgentName }),
|
|
369
|
+
output: z.object({ text: z.string() }),
|
|
370
|
+
});
|
|
371
|
+
|
|
372
|
+
export const agentBounds = actionRef("agent.bounds", {
|
|
373
|
+
description:
|
|
374
|
+
"What an agent may reach: its hands (the niwa actions its sessions see), the tools of the harness, its project, and the rules its main session holds. A turn never widens them, whoever wrote it.",
|
|
375
|
+
input: z.object({ agent: AgentName }),
|
|
376
|
+
output: z.object({
|
|
377
|
+
agent: AgentName,
|
|
378
|
+
hands: z.array(z.string()),
|
|
379
|
+
tools: AgentTools,
|
|
380
|
+
project: AgentProject.optional(),
|
|
381
|
+
harness: z.string().optional(),
|
|
382
|
+
role: z.string().optional(),
|
|
383
|
+
/** The rules of the main session's grant, when it has a session. */
|
|
384
|
+
grant: z.array(z.string()).optional(),
|
|
385
|
+
}),
|
|
386
|
+
});
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
// Each step commits one bounded part against the attachment's current cursor. A final event drains
|
|
2
|
+
// the remaining parts, and a pause skips silent windows until it can report what the session did.
|
|
3
|
+
import type { ScriptApi } from "@niwa-labs/script";
|
|
4
|
+
|
|
5
|
+
declare const niwa: ScriptApi["niwa"];
|
|
6
|
+
declare const workflow: ScriptApi["workflow"];
|
|
7
|
+
|
|
8
|
+
export default workflow(
|
|
9
|
+
{ on: ["agent.digest.due"], uses: ["agent.attachment", "agent.digest.read"] },
|
|
10
|
+
async (trigger: { data: { session: string; attachment: string; ended: boolean } }) => {
|
|
11
|
+
const { session, attachment, ended } = trigger.data;
|
|
12
|
+
for (let part = 0; ; part++) {
|
|
13
|
+
const current = await niwa.agent.attachment({ session }, { label: `attachment-${part}` }) as { attachment?: string; upto?: string; pending?: boolean };
|
|
14
|
+
if (current.attachment !== attachment) return;
|
|
15
|
+
const next = await niwa.agent.digest.read(
|
|
16
|
+
{ session, attachment, ended, ...(current.upto === undefined ? {} : { from: current.upto }), ...(current.pending ? { pending: true } : {}) },
|
|
17
|
+
{ label: `part-${part}` },
|
|
18
|
+
) as { more: boolean; stale?: boolean };
|
|
19
|
+
if (!next.more && !(ended && next.stale)) return;
|
|
20
|
+
}
|
|
21
|
+
},
|
|
22
|
+
);
|