copilotz 1.0.0-rc.27 → 1.0.0-rc.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +2 -2
  3. package/hosts/web/node/mod.d.ts +30 -2
  4. package/hosts/web/node/mod.js +30 -2
  5. package/hosts/web/node/serve.d.ts +55 -0
  6. package/hosts/web/node/serve.js +83 -0
  7. package/package.json +1 -1
  8. package/plugins/agents/chat/actions/send.d.ts +3 -2
  9. package/plugins/agents/chat/actions/send.js +10 -4
  10. package/plugins/agents/chat/collections/intent.d.ts +59 -0
  11. package/plugins/agents/chat/collections/intent.js +21 -0
  12. package/plugins/agents/chat/collections/wait.d.ts +12 -3
  13. package/plugins/agents/chat/collections/wait.js +4 -2
  14. package/plugins/agents/chat/mod.d.ts +5 -1
  15. package/plugins/agents/chat/mod.js +5 -1
  16. package/plugins/agents/chat/processors/turn.js +79 -9
  17. package/plugins/agents/chat/shared/types.d.ts +36 -4
  18. package/plugins/agents/chat/views/web/conversation.js +1 -1
  19. package/plugins/agents/chat/views/web/over.d.ts +5 -2
  20. package/plugins/agents/chat/views/web/over.js +10 -3
  21. package/plugins/compute/computers/actions/approve.js +34 -5
  22. package/plugins/compute/computers/actions/forget.js +13 -1
  23. package/plugins/compute/computers/collections/approval.d.ts +25 -1
  24. package/plugins/compute/computers/collections/approval.js +10 -2
  25. package/plugins/compute/computers/collections/env-var.d.ts +1 -1
  26. package/plugins/compute/computers/mod.d.ts +2 -1
  27. package/plugins/compute/computers/mod.js +2 -1
  28. package/plugins/compute/computers/program/version.d.ts +1 -1
  29. package/plugins/compute/computers/program/version.js +1 -1
  30. package/plugins/compute/computers/resources/downloads.js +1 -1
  31. package/plugins/compute/computers/shared/ask.d.ts +11 -3
  32. package/plugins/compute/computers/shared/ask.js +67 -17
  33. package/plugins/compute/computers/shared/grants.d.ts +9 -3
  34. package/plugins/compute/computers/shared/grants.js +21 -6
  35. package/plugins/compute/computers/views/context.js +4 -2
  36. package/plugins/compute/computers/views/web/asks.d.ts +4 -3
  37. package/plugins/compute/computers/views/web/asks.js +10 -7
  38. package/plugins/interfaces/web/actions/sending.js +6 -2
  39. package/stores/sql/postgres/lease.d.ts +55 -0
  40. package/stores/sql/postgres/lease.js +102 -0
  41. package/stores/sql/postgres/mod.d.ts +1 -0
  42. package/stores/sql/postgres/mod.js +1 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,49 @@
1
1
  ## Unreleased
2
2
 
3
+ ## 1.0.0-rc.29 — 2026-11-07
4
+
5
+ - **An agent waiting on your yes waits within its turn.** A command, job or file write that needs a
6
+ person's OK used to end the agent's turn ("Waiting for ana's yes…"). The turn's answer went to
7
+ whoever had asked it, and the yes then started a new turn that answered the person. So when one
8
+ agent asked another, and that one needed a yes, the first got "I'm waiting on your yes" as its
9
+ answer and the real answer went to the person. Now the turn pauses, as it does for the messages it
10
+ sends. The call asks its person a question: the agent's message to them, answered on the approval
11
+ card. The answer is a reply to that question, and the same turn goes on. The call runs again as
12
+ itself, in a step after the answer, so the agent reads its question, the answer, then what the
13
+ command did, and its answer goes to whoever started the turn. Several asks in one step wait
14
+ together, and the turn goes on once, when the last is answered: what was allowed runs, and what
15
+ wasn't says no. A yes in this conversation, or always, answers the agent's other asks it covers,
16
+ and their turns go on too. A reply typed to the question isn't a yes: the call doesn't run, and
17
+ says what they said. A card asked in a side thread shows in its conversation too ("in a side
18
+ thread"). A card answered before its step is written is refused (`busy`, "answer in a moment");
19
+ the card shows only once the step is written anyway. Forgetting a computer tells a turn waiting on
20
+ it no. A model outside (MCP) still gets "Waiting for…" and asks again later, as before.
21
+ - **Tools can wait for a person** (`ToolContext.ask`, in chat's contract). In a turn, a tool asks
22
+ `{ to, text }` and gets the question's id; the turn waits for a reply to it (a message with that
23
+ `replyTo`), then runs the call again with `answer` (who answered, and what they said). The
24
+ question is written with the step. Steps record it (`Step.asked`), as they record what they sent
25
+ (`sent`). The `conversation` resource's Views get the conversation's side threads too (hint
26
+ `side`).
27
+
28
+ ## 1.0.0-rc.28 — 2026-11-07
29
+
30
+ - **A deploy hands over instead of fencing** (`serve` in `copilotz/web/node`, `lease` in
31
+ `copilotz/stores/postgres`). While a deploy moves traffic, the platform keeps the old process
32
+ running for as long as its browsers' sockets stay open, and the new process's store fenced it:
33
+ every write those browsers sent failed ("This owner was fenced"). Now one process at a time holds
34
+ the store's lease: `serve` listens first (a request is told it's starting: a 503 to retry, a page
35
+ that reloads itself), waits for the lease, then opens the app; the old process, asked for it,
36
+ stops listening (its browsers reconnect, to the new one), lets running work finish, and lets go.
37
+ Only a deploy at least as new asks (`revision`); a process that loses the lease stops. Its table
38
+ is `copilotz_lease`, in the schema it's given (`public` by default).
39
+ - **A contact's message may go to nobody** (`chat.send` with `to: []`), as a person's already could:
40
+ it's kept in the chat, its agents read it the next time they answer there (with its `tap`, as
41
+ `[tapped: <id>]`), and none answers it. It's how a page beside the chat says what the customer did
42
+ there (a trip chosen in a booking panel) without a turn for each tap. A contact still names no
43
+ agent: any other `to` goes to its chat's agents, as before. `contactSend` hooks are told
44
+ (`to: []`): a web line's visitor's message to nobody counts against its limits but holds none of
45
+ the line's budget, since no turn will be charged for it.
46
+
3
47
  ## 1.0.0-rc.27 — 2026-11-06
4
48
 
5
49
  **Upgrading.** Chat's `file.content` query is `file.about`, and answers a file without its content
package/README.md CHANGED
@@ -22,7 +22,7 @@ bun add copilotz # Bun
22
22
  deno add jsr:@copilotz/copilotz # Deno (or `deno add npm:copilotz`)
23
23
  ```
24
24
 
25
- On Deno, name it `copilotz` in `deno.json` (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.27"`),
25
+ On Deno, name it `copilotz` in `deno.json` (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.29"`),
26
26
  and the imports below are the same everywhere. Some pieces need a package of their own, installed
27
27
  beside it: `esbuild` to bundle the page's code on Node (`bundle`), `@electric-sql/pglite` for
28
28
  PostgreSQL in the process, and `@types/react` for the front ends' types.
@@ -631,7 +631,7 @@ and an app serves it from there by default:
631
631
  import { computerDownloads } from "copilotz/plugins/compute/downloads";
632
632
 
633
633
  plugins: [...plugins, await computerDownloads()], // this Copilotz's release
634
- plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.27" })], // its own: /computer/download/
634
+ plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.29" })], // its own: /computer/download/
635
635
  plugins: [...plugins, await computerDownloads({ url: "https://downloads.example.com/computer/" })], // or elsewhere
636
636
  ```
637
637
 
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * Copilotz on Node: what an app needs beside its runtime to serve it there.
3
3
  * `listen` serves a fetch handler with Node's HTTP server, through Oxian's
4
- * Node adapter, sockets included (`runtime.fetch` accepts its own); `bundle`
4
+ * Node adapter, sockets included (`runtime.fetch` accepts its own); `serve`
5
+ * serves a runtime through a deploy (below); `bundle`
5
6
  * makes the browser's code with esbuild (code splitting, as on Deno), for
6
7
  * the page (`webPage`'s `code`). Bun and Deno run it too.
7
8
  *
@@ -22,6 +23,33 @@
22
23
  * await runtime.close({ drain: 8_000 });
23
24
  * });
24
25
  * ```
26
+ *
27
+ * `serve` does what a deploy needs around that: it listens first (requests
28
+ * are told it's starting), takes the store's lease (`lease` from
29
+ * `copilotz/stores/postgres`), waiting for the previous process to hand
30
+ * over, then opens the runtime; and it hands over in turn when a newer
31
+ * process asks, so no two processes write the store at once and browsers
32
+ * reconnect to the newer one instead of being fenced.
33
+ *
34
+ * ```ts
35
+ * import { lease, postgresPool, postgresStore } from "copilotz/stores/postgres";
36
+ * import { serve } from "copilotz/web/node";
37
+ *
38
+ * const pool = await postgresPool({ url: process.env.DATABASE_URL!, writes: 5, reads: 5 });
39
+ * const sigterm = new AbortController();
40
+ * process.once("SIGTERM", () => sigterm.abort());
41
+ * const { server } = await serve(
42
+ * async () => createRuntime({ store: await postgresStore({ pool }), plugins }),
43
+ * {
44
+ * hostname: "0.0.0.0",
45
+ * port: 8080,
46
+ * signal: sigterm.signal,
47
+ * // Each deploy's number (Cloud Run's revision: app-00015-8bs is 15) asks older ones only.
48
+ * hold: (on) => lease(pool, { revision: Number(process.env.K_REVISION?.split("-").at(-2) ?? 0), ...on }),
49
+ * stopped: (code) => void pool.close().finally(() => process.exit(code)),
50
+ * },
51
+ * );
52
+ * ```
25
53
  */
26
54
  export { bundle, type BundleOptions } from "./bundle.js";
27
- export { listen, type Listener, type ListenOptions } from "./serve.js";
55
+ export { type App, type Holding, listen, type Listener, type ListenOptions, serve, type ServeOptions, } from "./serve.js";
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * Copilotz on Node: what an app needs beside its runtime to serve it there.
3
3
  * `listen` serves a fetch handler with Node's HTTP server, through Oxian's
4
- * Node adapter, sockets included (`runtime.fetch` accepts its own); `bundle`
4
+ * Node adapter, sockets included (`runtime.fetch` accepts its own); `serve`
5
+ * serves a runtime through a deploy (below); `bundle`
5
6
  * makes the browser's code with esbuild (code splitting, as on Deno), for
6
7
  * the page (`webPage`'s `code`). Bun and Deno run it too.
7
8
  *
@@ -22,6 +23,33 @@
22
23
  * await runtime.close({ drain: 8_000 });
23
24
  * });
24
25
  * ```
26
+ *
27
+ * `serve` does what a deploy needs around that: it listens first (requests
28
+ * are told it's starting), takes the store's lease (`lease` from
29
+ * `copilotz/stores/postgres`), waiting for the previous process to hand
30
+ * over, then opens the runtime; and it hands over in turn when a newer
31
+ * process asks, so no two processes write the store at once and browsers
32
+ * reconnect to the newer one instead of being fenced.
33
+ *
34
+ * ```ts
35
+ * import { lease, postgresPool, postgresStore } from "copilotz/stores/postgres";
36
+ * import { serve } from "copilotz/web/node";
37
+ *
38
+ * const pool = await postgresPool({ url: process.env.DATABASE_URL!, writes: 5, reads: 5 });
39
+ * const sigterm = new AbortController();
40
+ * process.once("SIGTERM", () => sigterm.abort());
41
+ * const { server } = await serve(
42
+ * async () => createRuntime({ store: await postgresStore({ pool }), plugins }),
43
+ * {
44
+ * hostname: "0.0.0.0",
45
+ * port: 8080,
46
+ * signal: sigterm.signal,
47
+ * // Each deploy's number (Cloud Run's revision: app-00015-8bs is 15) asks older ones only.
48
+ * hold: (on) => lease(pool, { revision: Number(process.env.K_REVISION?.split("-").at(-2) ?? 0), ...on }),
49
+ * stopped: (code) => void pool.close().finally(() => process.exit(code)),
50
+ * },
51
+ * );
52
+ * ```
25
53
  */
26
54
  export { bundle } from "./bundle.js";
27
- export { listen } from "./serve.js";
55
+ export { listen, serve, } from "./serve.js";
@@ -18,3 +18,58 @@ export type Listener = {
18
18
  };
19
19
  /** Serves a fetch handler (`runtime.fetch`): every request, sockets' upgrades included. */
20
20
  export declare function listen(fetch: (request: Request) => Response | Promise<Response>, options?: ListenOptions): Promise<Listener>;
21
+ /** What `serve` serves: a runtime, or anything that answers requests and closes like one. */
22
+ export type App = {
23
+ fetch(request: Request): Response | Promise<Response>;
24
+ close(options?: {
25
+ drain?: number;
26
+ }): Promise<void>;
27
+ };
28
+ /** What `serve` gives the lease it holds (`lease` from `copilotz/stores/postgres` takes it all). */
29
+ export type Holding = {
30
+ /** Aborts when it stops while still waiting for the lease. */
31
+ signal: AbortSignal;
32
+ /** Another process holds it, and this one waits. */
33
+ waiting(): void;
34
+ /** A newer process waits for it: this one hands over. */
35
+ asked(): void;
36
+ /** It was lost: this one stops. */
37
+ lost(why: string): void;
38
+ };
39
+ export type ServeOptions = ListenOptions & {
40
+ /**
41
+ * Takes the store's lease before the app opens, so one process at a time
42
+ * writes it (`(on) => lease(pool, { revision, ...on })`): this process waits
43
+ * for the one holding it, and hands over to the next.
44
+ */
45
+ hold?: (holding: Holding) => Promise<{
46
+ release(): Promise<void>;
47
+ }>;
48
+ /** What a request gets until the app is open: a 503 to retry in 2 s (a page that reloads itself) by default. */
49
+ starting?: (request: Request) => Response | Promise<Response>;
50
+ /** How long running work gets to finish when it stops, in ms: 8 000 by default. */
51
+ drain?: number;
52
+ /**
53
+ * Said once it has stopped by itself (it handed over: 0; it lost the lease:
54
+ * 1) or by its `signal` (0); a process exits with it.
55
+ */
56
+ stopped?: (code: number) => void;
57
+ };
58
+ /**
59
+ * Serves an app the way a deploy needs: it listens first, so the platform
60
+ * sees it's up (requests are told it's starting), takes the store's lease if
61
+ * it's given one (`hold`), then opens the app and serves it. It stops when
62
+ * its `signal` aborts (SIGTERM), when `stop` is called, or when a newer
63
+ * process asks for the lease: it stops listening (its sockets close, and
64
+ * browsers reconnect, to the newer process), the app's running work gets
65
+ * `drain` to finish, and the lease goes to whoever waits. A process that
66
+ * loses the lease stops too, rather than write beside another.
67
+ *
68
+ * It rejects when it stops before the app is open, or the app fails to open.
69
+ * What the app's `open` opened (its pool) stays the app's to close.
70
+ */
71
+ export declare function serve<A extends App>(open: () => Promise<A>, options?: ServeOptions): Promise<{
72
+ app: A;
73
+ server: Listener;
74
+ stop(): Promise<void>;
75
+ }>;
@@ -15,3 +15,86 @@ export async function listen(fetch, options = {}) {
15
15
  };
16
16
  return await oxian({ hypervisor: front, hostname, port, signal });
17
17
  }
18
+ /**
19
+ * Serves an app the way a deploy needs: it listens first, so the platform
20
+ * sees it's up (requests are told it's starting), takes the store's lease if
21
+ * it's given one (`hold`), then opens the app and serves it. It stops when
22
+ * its `signal` aborts (SIGTERM), when `stop` is called, or when a newer
23
+ * process asks for the lease: it stops listening (its sockets close, and
24
+ * browsers reconnect, to the newer process), the app's running work gets
25
+ * `drain` to finish, and the lease goes to whoever waits. A process that
26
+ * loses the lease stops too, rather than write beside another.
27
+ *
28
+ * It rejects when it stops before the app is open, or the app fails to open.
29
+ * What the app's `open` opened (its pool) stays the app's to close.
30
+ */
31
+ export async function serve(open, options = {}) {
32
+ const { hold, starting = startingPage, drain = 8_000, stopped, signal, ...where } = options;
33
+ signal?.throwIfAborted();
34
+ /** The app once it's open; until then, requests are told it's starting. */
35
+ let app;
36
+ const server = await listen((request) => app ? app.fetch(request) : starting(request), where);
37
+ const waiting = new AbortController();
38
+ let held;
39
+ let opening;
40
+ let stopping;
41
+ const stop = () => stopping ??= (async () => {
42
+ waiting.abort(new DOMException("It stopped before the app opened", "AbortError"));
43
+ try {
44
+ await server.shutdown();
45
+ }
46
+ finally {
47
+ try {
48
+ // An app still opening closes once it's open.
49
+ await (await opening?.catch(() => undefined))?.close({ drain });
50
+ }
51
+ finally {
52
+ await held?.release();
53
+ }
54
+ }
55
+ })();
56
+ let said = false;
57
+ /** It stops by itself (or by its signal), and says so, once. */
58
+ const stopBy = (code, why) => {
59
+ if (said)
60
+ return;
61
+ said = true;
62
+ if (why)
63
+ (code ? console.error : console.log)(why);
64
+ void stop().finally(() => stopped?.(code));
65
+ };
66
+ const aborted = () => stopBy(0);
67
+ signal?.addEventListener("abort", aborted, { once: true });
68
+ try {
69
+ if (hold) {
70
+ held = await hold({
71
+ signal: waiting.signal,
72
+ waiting: () => console.log("Waiting for the previous process to let go of the store…"),
73
+ asked: () => stopBy(0, "A newer process asks for the store: handing over"),
74
+ lost: (why) => stopBy(1, `Lost the store's lease (${why}): stopping`),
75
+ });
76
+ // Taken just as it stopped: let go of it again.
77
+ if (stopping)
78
+ await held.release();
79
+ waiting.signal.throwIfAborted();
80
+ }
81
+ opening = open();
82
+ app = await opening;
83
+ }
84
+ catch (error) {
85
+ signal?.removeEventListener("abort", aborted);
86
+ await stop();
87
+ throw error;
88
+ }
89
+ return { app, server, stop };
90
+ }
91
+ /** While it waits for the store: a page that tries again by itself, or a 503 to retry. */
92
+ function startingPage(request) {
93
+ const headers = { "retry-after": "2" };
94
+ if (request.method === "GET" && request.headers.get("accept")?.includes("text/html")) {
95
+ return new Response('<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="2">' +
96
+ '<meta name="viewport" content="width=device-width, initial-scale=1">' +
97
+ "<title>Starting</title><p>Starting, one moment…</p>", { status: 503, headers: { ...headers, "content-type": "text/html; charset=utf-8" } });
98
+ }
99
+ return Response.json({ error: "starting" }, { status: 503, headers });
100
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "copilotz",
3
- "version": "1.0.0-rc.27",
3
+ "version": "1.0.0-rc.29",
4
4
  "description": "Copilotz: one runtime for Node, Deno, Bun, Cloudflare Workers and the browser.",
5
5
  "keywords": [
6
6
  "agents",
@@ -11,8 +11,9 @@ export declare const MEDIA_TYPE: RegExp;
11
11
  /**
12
12
  * A `contactSend` resource: the Action that lets a contact's message in,
13
13
  * asked as the contact before anything's sent, with where it goes (`thread`,
14
- * when it names one) and what it carries (each file's name, media type and
15
- * size). It refuses it (a limit), or answers where it goes when it names no
14
+ * when it names one), what it carries (each file's name, media type and
15
+ * size), and `to: []` when it goes to nobody (no agent answers it: no turn
16
+ * to pay for). It refuses it (a limit), or answers where it goes when it names no
16
17
  * chat (`thread`: the contact's own) and `transcribe: false` when its audio
17
18
  * goes untranscribed.
18
19
  */
@@ -3,9 +3,11 @@
3
3
  * shared with them: the rules keep them to it). It goes to `to` when given,
4
4
  * else to the agents `@mentioned` in it, else to the sender of the message
5
5
  * it replies to, else to the thread's agents (a new thread's: those it
6
- * names, or who answers new chats in its space). A contact's goes to the
7
- * sender of what it replies to, else the thread's agents: never whom it
8
- * names. It replies only to a message of the same conversation that its
6
+ * names, or who answers new chats in its space); `to: []`, to nobody: it's
7
+ * said, agents read it later, and none answers it (what someone did on a
8
+ * page beside the chat). A contact's goes to the sender of what it replies
9
+ * to, else the thread's agents: never whom it names, though it too may say
10
+ * something to nobody (`to: []`). It replies only to a message of the same conversation that its
9
11
  * sender reads. Only agents answering in
10
12
  * its space answer there: naming one that doesn't fails (`not_here`). Audio
11
13
  * sent with it is transcribed first (what agents read): if that fails,
@@ -51,6 +53,7 @@ async function letIn(ctx, asked) {
51
53
  const answer = await ctx.call(hook.action, {
52
54
  ...(asked.thread ? { thread: asked.thread } : {}),
53
55
  files: asked.files,
56
+ ...(asked.to ? { to: asked.to } : {}),
54
57
  });
55
58
  said = {
56
59
  ...said,
@@ -182,6 +185,8 @@ export const sendAction = defineAction({
182
185
  // A contact talks with whom its chat is with: what it says names nobody else, and the app
183
186
  // lets it in first (its line's limits, the files it takes, its own chat).
184
187
  const contact = ctx.actor?.kind === "contact";
188
+ // A contact names no agent, but may say something to nobody: no agent answers it.
189
+ const nobody = input.to?.length === 0;
185
190
  if (contact && said.length > CONTACT_TEXT) {
186
191
  throw failure("invalid", `A message says ${CONTACT_TEXT} characters at most.`, {
187
192
  public: true,
@@ -195,6 +200,7 @@ export const sendAction = defineAction({
195
200
  ...(f.type ? { type: f.type } : {}),
196
201
  size: sizeOf(f.data),
197
202
  })),
203
+ ...(nobody ? { to: [] } : {}),
198
204
  })
199
205
  : {};
200
206
  const threads = ctx.db.collection("thread");
@@ -210,7 +216,7 @@ export const sendAction = defineAction({
210
216
  const roster = await rosterOf(ctx, where);
211
217
  const members = existing ? existing.agents ?? [] : roster.default;
212
218
  const mentioned = contact ? [] : await mentionsIn(ctx, said, threadId, roster, members);
213
- const asked = (contact ? undefined : input.to) ??
219
+ const asked = (contact ? (nobody ? [] : undefined) : input.to) ??
214
220
  (mentioned.length ? mentioned : replied ? [replied.from] : members);
215
221
  // Agents answer only where they work: one named that doesn't is refused; one gone, left out.
216
222
  const agents = await agentsNamed(ctx, asked);
@@ -64,6 +64,41 @@ export declare const intent: {
64
64
  readonly type: "string";
65
65
  };
66
66
  };
67
+ /** The question a call asked as it ran (`ToolContext.ask`), by its place in `calls`. */
68
+ readonly asks: {
69
+ readonly type: "object";
70
+ readonly additionalProperties: {
71
+ readonly type: "object";
72
+ readonly properties: {
73
+ readonly to: {
74
+ readonly type: "string";
75
+ };
76
+ readonly text: {
77
+ readonly type: "string";
78
+ };
79
+ };
80
+ readonly required: readonly ["to", "text"];
81
+ };
82
+ };
83
+ /**
84
+ * Calls run again once their questions were answered, by place in `calls`:
85
+ * the call's own id (it runs as itself) and the question it asked.
86
+ */
87
+ readonly again: {
88
+ readonly type: "object";
89
+ readonly additionalProperties: {
90
+ readonly type: "object";
91
+ readonly properties: {
92
+ readonly call: {
93
+ readonly type: "string";
94
+ };
95
+ readonly question: {
96
+ readonly type: "string";
97
+ };
98
+ };
99
+ readonly required: readonly ["call", "question"];
100
+ };
101
+ };
67
102
  readonly at: {
68
103
  readonly type: "string";
69
104
  };
@@ -86,6 +121,20 @@ export declare const intent: {
86
121
  name: string;
87
122
  text: string;
88
123
  }[] | undefined;
124
+ asks?: {
125
+ [x: string]: {
126
+ [x: string]: unknown;
127
+ to: string;
128
+ text: string;
129
+ };
130
+ } | undefined;
131
+ again?: {
132
+ [x: string]: {
133
+ [x: string]: unknown;
134
+ call: string;
135
+ question: string;
136
+ };
137
+ } | undefined;
89
138
  at: string;
90
139
  thread: string;
91
140
  agent: string;
@@ -116,8 +165,18 @@ export type Intent = {
116
165
  told?: Told[];
117
166
  calls: ToolCall[];
118
167
  outputs: Record<string, string>;
168
+ asks?: Record<string, Question>;
169
+ again?: Record<string, {
170
+ call: string;
171
+ question: string;
172
+ }>;
119
173
  at: string;
120
174
  };
175
+ /** What a tool asks someone, its call waiting for their answer (`ToolContext.ask`). */
176
+ export type Question = {
177
+ to: string;
178
+ text: string;
179
+ };
121
180
  /** What a call that never returned says, in the step a turn keeps when it ends without it. */
122
181
  export declare const CUT_SHORT: string;
123
182
  /** What a message that was never sent says there. */
@@ -40,6 +40,27 @@ const intentSchema = {
40
40
  },
41
41
  /** What each call returned, by its place in `calls`. */
42
42
  outputs: { type: "object", additionalProperties: { type: "string" } },
43
+ /** The question a call asked as it ran (`ToolContext.ask`), by its place in `calls`. */
44
+ asks: {
45
+ type: "object",
46
+ additionalProperties: {
47
+ type: "object",
48
+ properties: { to: { type: "string" }, text: { type: "string" } },
49
+ required: ["to", "text"],
50
+ },
51
+ },
52
+ /**
53
+ * Calls run again once their questions were answered, by place in `calls`:
54
+ * the call's own id (it runs as itself) and the question it asked.
55
+ */
56
+ again: {
57
+ type: "object",
58
+ additionalProperties: {
59
+ type: "object",
60
+ properties: { call: { type: "string" }, question: { type: "string" } },
61
+ required: ["call", "question"],
62
+ },
63
+ },
43
64
  at: { type: "string" },
44
65
  },
45
66
  required: ["thread", "agent", "step", "calls", "outputs", "at"],
@@ -1,4 +1,4 @@
1
- /** Waits: an agent paused until every message it sent has a reply. */
1
+ /** Waits: an agent paused until every message it sent, and every question its tools asked, has a reply. */
2
2
  import { type Infer } from "../../../../runtime/mod.js";
3
3
  declare const waitSchema: {
4
4
  readonly type: "object";
@@ -16,7 +16,7 @@ declare const waitSchema: {
16
16
  readonly hops: {
17
17
  readonly type: "integer";
18
18
  };
19
- /** Messages still without a reply. Empty: the agent resumes. */
19
+ /** Messages still without a reply (its own and its tools' questions). Empty: the agent resumes. */
20
20
  readonly waitingFor: {
21
21
  readonly type: "array";
22
22
  readonly items: {
@@ -29,6 +29,10 @@ declare const waitSchema: {
29
29
  readonly type: "string";
30
30
  };
31
31
  };
32
+ /** The step that asked questions: its asked calls run again once they're answered. */
33
+ readonly step: {
34
+ readonly type: "string";
35
+ };
32
36
  readonly at: {
33
37
  readonly type: "string";
34
38
  };
@@ -52,7 +56,7 @@ export declare const wait: {
52
56
  readonly hops: {
53
57
  readonly type: "integer";
54
58
  };
55
- /** Messages still without a reply. Empty: the agent resumes. */
59
+ /** Messages still without a reply (its own and its tools' questions). Empty: the agent resumes. */
56
60
  readonly waitingFor: {
57
61
  readonly type: "array";
58
62
  readonly items: {
@@ -65,6 +69,10 @@ export declare const wait: {
65
69
  readonly type: "string";
66
70
  };
67
71
  };
72
+ /** The step that asked questions: its asked calls run again once they're answered. */
73
+ readonly step: {
74
+ readonly type: "string";
75
+ };
68
76
  readonly at: {
69
77
  readonly type: "string";
70
78
  };
@@ -78,6 +86,7 @@ export declare const wait: {
78
86
  private?: string[];
79
87
  queries?: Record<string, import("../../../../runtime/define.js").QueryDef<{
80
88
  [x: string]: unknown;
89
+ step?: string | undefined;
81
90
  at: string;
82
91
  hops: number;
83
92
  thread: string;
@@ -1,4 +1,4 @@
1
- /** Waits: an agent paused until every message it sent has a reply. */
1
+ /** Waits: an agent paused until every message it sent, and every question its tools asked, has a reply. */
2
2
  import { defineCollection } from "../../../../runtime/mod.js";
3
3
  const names = { type: "array", items: { type: "string" } };
4
4
  const waitSchema = {
@@ -9,9 +9,11 @@ const waitSchema = {
9
9
  /** What the agent's turn answers, so it can answer once resumed. */
10
10
  trigger: { type: "string" },
11
11
  hops: { type: "integer" },
12
- /** Messages still without a reply. Empty: the agent resumes. */
12
+ /** Messages still without a reply (its own and its tools' questions). Empty: the agent resumes. */
13
13
  waitingFor: names,
14
14
  received: names,
15
+ /** The step that asked questions: its asked calls run again once they're answered. */
16
+ step: { type: "string" },
15
17
  at: { type: "string" },
16
18
  },
17
19
  required: ["agent", "thread", "trigger", "hops", "waitingFor", "received", "at"],
@@ -14,7 +14,11 @@
14
14
  * document. Each reply checks itself off; the last one resumes the agent
15
15
  * with every reply in its history. Waiting holds nothing open.
16
16
  * - People are reached the same way: a question to a person waits until they
17
- * reply to it.
17
+ * reply to it. So does a tool that needs a person's answer to go on (a yes
18
+ * to run a command, `ctx.ask`): its turn waits with the step's other
19
+ * messages, and resumes with that call run again, as itself, after the
20
+ * answer. An agent another one asked still answers it, whatever it waited
21
+ * on meanwhile.
18
22
  * - What an agent is writing shows as it comes: a `live` document per running
19
23
  * turn, kept in memory, swapped for the step or reply it became in one commit.
20
24
  * - A step's tool calls are written (an `intent`) before any of them runs, and
@@ -14,7 +14,11 @@
14
14
  * document. Each reply checks itself off; the last one resumes the agent
15
15
  * with every reply in its history. Waiting holds nothing open.
16
16
  * - People are reached the same way: a question to a person waits until they
17
- * reply to it.
17
+ * reply to it. So does a tool that needs a person's answer to go on (a yes
18
+ * to run a command, `ctx.ask`): its turn waits with the step's other
19
+ * messages, and resumes with that call run again, as itself, after the
20
+ * answer. An agent another one asked still answers it, whatever it waited
21
+ * on meanwhile.
18
22
  * - What an agent is writing shows as it comes: a `live` document per running
19
23
  * turn, kept in memory, swapped for the step or reply it became in one commit.
20
24
  * - A step's tool calls are written (an `intent`) before any of them runs, and