@intentic/sandbox-contract 1.344.0 → 1.346.0

package/src/protocol/peer-dial.test.ts

@@ -47,16 +47,22 @@ class FakeSocket implements SocketLike {
 // This door's silence deadline, named so the assertions can read it off the same number the loop is given.
 const SILENCE_MS = 30_000;
 
-// A ladder that answers with a fixed delay and records what it was told, so the test can read the held time.
+// A ladder that answers with a fixed delay and records what it was told, so the test can read the held time, and how
+// often it was put back on its floor.
 const ladder = (delay = 1_000) => {
     const held: number[] = [];
-    return {
+    const rungs = {
         held,
+        resets: 0,
         next: (heldMs: number) => {
             held.push(heldMs);
             return delay;
         },
+        reset: () => {
+            rungs.resets += 1;
+        },
     };
+    return rungs;
 };
 
 const dialling = (delay?: number) => {
@@ -64,6 +70,7 @@ const dialling = (delay?: number) => {
     const attached: FakeSocket[] = [];
     const said: string[] = [];
     const revoked = jest.fn();
+    const backoff = ladder(delay);
     const link = dialPeer<FakeSocket>({
         open: async () => {
             const socket = new FakeSocket();
@@ -72,12 +79,12 @@ const dialling = (delay?: number) => {
         },
         hello: () => ({ type: "hello", token: "iht_test", version: "1.0.0" }),
         attach: (socket) => void attached.push(socket),
-        backoff: ladder(delay),
+        backoff,
         silenceMs: SILENCE_MS,
         log: (message) => void said.push(message),
         revoked,
     });
-    return { link, sockets, attached, said, revoked };
+    return { link, sockets, attached, said, revoked, backoff };
 };
 
 test("the handler is attached before the hello goes out, and the hello is the first frame", async () => {
@@ -305,6 +312,85 @@ test("a link nobody has answered in a long time rests between tries, and is neve
     }
 });
 
+/* A FAR END SOMEBODY KNOWS IS BACK (a sandbox the machine agent just woke) is dialled at once, whatever the ladder had
+   left to wait, and a dial that still finds it booting is back on the ladder's first rung, not on the long rest. */
+test("retryNow ends the long rest and dials at once, and the outage behind it no longer counts", async () => {
+    jest.useFakeTimers();
+    try {
+        const RUNG_MS = 30_000;
+        const { link, sockets, said, backoff } = dialling(RUNG_MS);
+        for (let attempt = 1; attempt <= LONG_OUTAGE_ATTEMPTS; attempt += 1) {
+            // one drop per attempt is serial by definition
+            await waitFor(() => expect(sockets).toHaveLength(attempt));
+            sockets.at(-1)?.drops(1006);
+            if (attempt < LONG_OUTAGE_ATTEMPTS) {
+                // ditto
+                await advanceTimersByTimeAsync(RUNG_MS);
+            }
+        }
+        // Resting now: the long outage's quarter hour on top of the rung.
+        expect(link.outage()).toEqual({ failures: LONG_OUTAGE_ATTEMPTS, since: expect.any(Number) });
+        await advanceTimersByTimeAsync(RUNG_MS);
+        expect(sockets).toHaveLength(LONG_OUTAGE_ATTEMPTS);
+
+        link.retryNow();
+        await waitFor(() => expect(sockets).toHaveLength(LONG_OUTAGE_ATTEMPTS + 1));
+        expect(backoff.resets).toBe(1);
+        expect(link.outage()).toBeUndefined();
+        expect(link.state()).toBe("connecting");
+
+        // Still booting: the first failure of a new outage, said out loud, waits one rung and no rest.
+        sockets.at(-1)?.drops(PEER_TRY_AGAIN);
+        expect(said.at(-1)).toBe("the sandbox is not ready to admit this connection yet; reconnecting in 30s");
+        expect(link.outage()).toEqual({ failures: 1, since: expect.any(Number) });
+        await advanceTimersByTimeAsync(RUNG_MS);
+        await waitFor(() => expect(sockets).toHaveLength(LONG_OUTAGE_ATTEMPTS + 2));
+
+        // Nothing of the cut wait is left to fire (the one dial it owed has been made): the open socket's watchdog is
+        // the one timer armed.
+        sockets.at(-1)?.opens();
+        expect(link.state()).toBe("open");
+        expect(jest.getTimerCount()).toBe(1);
+
+        link.stop();
+        await link.done;
+    } finally {
+        jest.useRealTimers();
+    }
+});
+
+test("retryNow dials nothing beside an open link or a dial in flight, and nothing once the link is stopped", async () => {
+    jest.useFakeTimers();
+    try {
+        const { link, sockets, backoff } = dialling(60_000);
+        await waitFor(() => expect(sockets).toHaveLength(1));
+        // In flight: no second dial beside it, though its ladder is reset so a failure of it retries on the floor.
+        link.retryNow();
+        await advanceTimersByTimeAsync(0);
+        expect(sockets).toHaveLength(1);
+        expect(backoff.resets).toBe(1);
+
+        sockets[0]?.opens();
+        link.retryNow();
+        await advanceTimersByTimeAsync(0);
+        expect(sockets).toHaveLength(1);
+        expect(backoff.resets).toBe(1);
+        expect(link.state()).toBe("open");
+
+        sockets[0]?.drops(1006);
+        link.stop();
+        await link.done;
+        link.retryNow();
+        await advanceTimersByTimeAsync(120_000);
+        expect(sockets).toHaveLength(1);
+        expect(backoff.resets).toBe(1);
+        expect(jest.getTimerCount()).toBe(0);
+        expect(link.state()).toBe("closed");
+    } finally {
+        jest.useRealTimers();
+    }
+});
+
 // A stop that lands while the address is still being decided has nothing to close and must open nothing after
 // the fact: a socket dialled by a loop that has already reported itself done would be a connection nobody stops.
 test("a stop during resolution opens nothing, and a socket a slow resolver still hands over is closed", async () => {

package/src/protocol/peer-dial.ts

@@ -58,8 +58,9 @@ export interface PeerDialSpec<S extends SocketLike> {
     readonly hello: () => Promise<Record<string, unknown>> | Record<string, unknown>;
     // Hand the open socket to the oRPC handler serving the door's contract.
     readonly attach: (socket: S) => void;
-    // The retry ladder: how long to wait after a drop, given how long the socket had held.
-    readonly backoff: { readonly next: (heldMs: number) => number };
+    // The retry ladder: how long to wait after a drop, given how long the socket had held; `reset` puts it back on its
+    // floor (`retryNow`).
+    readonly backoff: { readonly next: (heldMs: number) => number; readonly reset: () => void };
 /* How long this socket may hear nothing before the link is presumed dead: `peerLinkSilenceMs` of the heartbeat the door's own hub pings on. */
     readonly silenceMs: number;
     readonly log: (message: string) => void;
@@ -86,8 +87,71 @@ export interface PeerLink {
     readonly stop: (reason?: string) => void;
     readonly state: () => PeerLinkState;
     readonly outage: () => PeerOutage | undefined;
+    /* SOMEBODY KNOWS THE FAR END IS BACK, so the link need not wait to find out (2026-10-19). A machine agent that has
+       just woken a sleeping sandbox knows it is starting, but the link to it had spent the sleep on the ladder: past
+       LONG_OUTAGE_ATTEMPTS each try rests a quarter of an hour, and on rog a sandbox woken at 16:48 had its link back at
+       17:12, 24 minutes with no device tools. This ends a wait on the ladder (the long rest included) and dials now,
+       and puts the outage behind it as an answer would (`failures`, the quiet rule, its `since`, the ladder's rung), so
+       a dial that finds the sandbox still booting retries on the fast floor. A dial in flight is left to finish and
+       only its ladder is reset, so a failure of it retries fast too; an open or stopped link is untouched. */
+    readonly retryNow: () => void;
 }
 
+/* ONE OUTAGE'S BOOKKEEPING: the attempts that have failed since the link was last open, when the first of them was, and
+   what each may say (the quiet rule above). An answer clears it, and so does `retryNow`. */
+const failureRun = (log: (message: string) => void) => {
+    let failures = 0;
+    // When the loop last complained out loud, and when the CURRENT outage began.
+    let quietSince = 0;
+    let since: number | undefined;
+    return {
+        count: (): number => failures,
+        // One more failed attempt; answers how many that makes.
+        fail: (): number => {
+            failures += 1;
+            since ??= Date.now();
+            return failures;
+        },
+        /* What ONE failed attempt is allowed to say. */
+        complain: (said: string, delay: number): void => {
+            const every = `retrying every ${Math.round(delay / 1000)}s`;
+            if (failures <= LOUD_ATTEMPTS) {
+                log(`${said}; reconnecting in ${Math.round(delay / 1000)}s`);
+                return;
+            }
+            if (failures === LOUD_ATTEMPTS + 1) {
+                quietSince = Date.now();
+                log(`${said}; still nothing after ${failures} attempts — ${every}, and saying so at most every ${Math.round(QUIET_LOG_MS / 60_000)} minutes from here`);
+                return;
+            }
+            if (Date.now() - quietSince >= QUIET_LOG_MS) {
+                quietSince = Date.now();
+                log(`${said}; ${failures} failed attempts, ${every}`);
+            }
+        },
+        clear: (): void => {
+            failures = 0;
+            quietSince = 0;
+            since = undefined;
+        },
+        reading: (): PeerOutage | undefined => (since === undefined ? undefined : { failures, since }),
+    };
+};
+
+/* THE WAIT ON THE LADDER hangs off the loop's stop, so a link stopped during it is done at once and never dials again,
+   and off a controller of its own, which `retryNow` aborts to dial at once. Cutting a wait already over does nothing. */
+const ladderWaits = (stopping: AbortSignal) => {
+    let resting: AbortController | undefined;
+    return {
+        wait: (delay: number, dial: () => Promise<void>): void => {
+            const rest = new AbortController();
+            resting = rest;
+            void sleep(delay, { signal: anySignal(stopping, rest.signal) }).then(() => (stopping.aborted ? undefined : dial()));
+        },
+        cut: (): void => resting?.abort(),
+    };
+};
+
 export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink => {
     // The loop's whole life: every way it ends (a stop, a revocation, a pairing gone) aborts this, and everything the
     // loop arms hangs off it, so nothing it left behind can dial, wait or fire once it is over. A stopped link that
@@ -96,32 +160,8 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
     const done = new Promise<void>((resolve) => void whenAborted(stopping.signal, () => resolve()));
     let socket: S | undefined;
     let openedAt: number | undefined;
-    // Consecutive attempts that have failed since this link was last open, and when the loop last complained out
-    // loud: between them they are the whole of the quiet rule above.
-    let failures = 0;
-    let quietSince = 0;
-    // When the CURRENT outage began, as opposed to when this link was last complained about.
-    let failingSince: number | undefined;
-
-/* What ONE failed attempt is allowed to say. */
-    const complain = (said: string, delay: number): void => {
-        const every = `retrying every ${Math.round(delay / 1000)}s`;
-        if (failures <= LOUD_ATTEMPTS) {
-            spec.log(`${said}; reconnecting in ${Math.round(delay / 1000)}s`);
-            return;
-        }
-        if (failures === LOUD_ATTEMPTS + 1) {
-            quietSince = Date.now();
-            spec.log(
-                `${said}; still nothing after ${failures} attempts — ${every}, and saying so at most every ${Math.round(QUIET_LOG_MS / 60_000)} minutes from here`,
-            );
-            return;
-        }
-        if (Date.now() - quietSince >= QUIET_LOG_MS) {
-            quietSince = Date.now();
-            spec.log(`${said}; ${failures} failed attempts, ${every}`);
-        }
-    };
+    const outage = failureRun(spec.log);
+    const ladder = ladderWaits(stopping.signal);
 
     const open = async (): Promise<void> => {
         const attempt = await spec.open(stopping.signal);
@@ -155,14 +195,11 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
             }
             const rung = spec.backoff.next(openedAt === undefined ? 0 : Date.now() - openedAt);
             openedAt = undefined;
-            failures += 1;
-            failingSince ??= Date.now();
             // The rest is added to the ladder's draw rather than replacing it: a flat fifteen minutes would bring back in
             // lockstep every link that entered the long outage together.
-            const delay = failures >= LONG_OUTAGE_ATTEMPTS ? LONG_OUTAGE_MS + rung : rung;
-            complain(said, delay);
-            // The wait hangs off the stop: a link stopped during it is done at once and never dials again.
-            void sleep(delay, { signal: stopping.signal }).then(() => (stopping.signal.aborted ? undefined : open()));
+            const delay = outage.fail() >= LONG_OUTAGE_ATTEMPTS ? LONG_OUTAGE_MS + rung : rung;
+            outage.complain(said, delay);
+            ladder.wait(delay, open);
         };
 
         const arm = (): void => {
@@ -189,9 +226,7 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
             openedAt = Date.now();
             // A link that is up owes nothing to the failures behind it: the next outage is news again, and the
             // "connected to …" line this open is about to log is what reports the recovery.
-            failures = 0;
-            quietSince = 0;
-            failingSince = undefined;
+            outage.clear();
             arm();
             spec.attach(ws);
             const send = (hello: Record<string, unknown>): void => {
@@ -230,7 +265,7 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
 
         /* Socket errors record a cause; the close event owns retry scheduling. */
         ws.addEventListener("error", () => {
-            if (failures < LOUD_ATTEMPTS) {
+            if (outage.count() < LOUD_ATTEMPTS) {
                 spec.log("connection error");
             }
         });
@@ -251,6 +286,15 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
         // ladder) and a finished one is closed: read off the loop itself, not a flag kept beside it that a redial
         // firing after the stop could set back.
         state: () => (socket?.readyState === OPEN ? "open" : stopping.signal.aborted ? "closed" : "connecting"),
-        outage: () => (failingSince === undefined ? undefined : { failures, since: failingSince }),
+        outage: outage.reading,
+        retryNow: () => {
+            if (stopping.signal.aborted || socket?.readyState === OPEN) {
+                return;
+            }
+            outage.clear();
+            spec.backoff.reset();
+            // Waiting on the ladder: the wait ends now and its dial follows. A dial in flight has no wait to end.
+            ladder.cut();
+        },
     };
 };

package/src/protocol/raw/raw-json-routes.ts

@@ -17,6 +17,15 @@ import { HostsListSchema } from "../../schemas/hosts.js";
 import { VoicesViewSchema } from "../../schemas/voice.js";
 import { MemberEmailSchema, MemberGrantSchema, MemberSelfSchema, MembersListSchema, MembersRosterSchema } from "../../schemas/members.js";
 import { PhonesListSchema, PhoneWakeRegistrationSchema } from "../../schemas/phone.js";
+import {
+    PhoneKeyringsResultSchema,
+    PhonePasswordsCaptureResultSchema,
+    PhonePasswordsCaptureSchema,
+    PhonePasswordsFillResultSchema,
+    PhonePasswordsFillSchema,
+    PhonePasswordsPairResultSchema,
+    PhonePasswordsPairSchema,
+} from "../../schemas/phone-passwords.js";
 import { OkSchema } from "../../schemas/shared.js";
 import { EnrollCodeAnswerSchema, EnrollCodeRequestSchema, PeerPairingAnswerSchema, SyncPairAnswerSchema, SyncPairRequestSchema } from "../../schemas/short-codes.js";
 import { SpeechStatusSchema, SpeechTranscriptSchema, SpeechWakeClaimSchema, SpeechWakeGrantSchema } from "../../schemas/speech.js";
@@ -133,6 +142,10 @@ export const RAW_JSON_ROUTES = {
     "POST /system/phones/pair": { output: PeerPairingAnswerSchema },
     "DELETE /system/phones/{id}": { output: OkSchema },
     "POST /system/phones/{id}/wake": { input: PhoneWakeRegistrationSchema, output: OkSchema },
+    "GET /system/phones/passwords/keyrings": { output: PhoneKeyringsResultSchema },
+    "POST /system/phones/passwords/pair": { input: PhonePasswordsPairSchema, output: PhonePasswordsPairResultSchema },
+    "POST /system/phones/passwords/capture": { input: PhonePasswordsCaptureSchema, output: PhonePasswordsCaptureResultSchema },
+    "POST /system/phones/passwords/fill": { input: PhonePasswordsFillSchema, output: PhonePasswordsFillResultSchema },
     "GET /system/runners": { output: RunnersListSchema },
     "DELETE /system/runners/{id}": { output: OkSchema },
     "POST /system/runners/{id}/definition/sync": { output: RunnerDefinitionAppliedSchema },

package/src/protocol/raw/raw-routes.ts

@@ -13,6 +13,8 @@ export const RAW_ROUTES = {
     // A person opening this sandbox's own address in a browser: sent to the app's /open on it, the address being what
     // they may still hold when the platform has lost the rest. Anything else gets the same 401 as before it existed.
     "GET /": { auth: "door", beforeBoot: true },
+    // The tab icon a browser asks for on that address: the lotus in the sandbox green, the same bytes for everyone.
+    "GET /favicon.ico": { auth: "door", beforeBoot: true },
     "GET /diff/raw": { lane: "bulk" },
     // Arming the dictation model is a read any tier makes; dictating is writing a message, the collaborator's grant.
     "GET /speech/status": { guest: true },
@@ -144,14 +146,17 @@ export const RAW_ROUTES = {
     "POST /children/answer": { agent: true, control: "never" },
     "POST /children/cancel": { agent: true, control: "never" },
     "POST /children/merge": { agent: true, control: "never" },
+    "POST /children/settle": { agent: true, control: "never" },
     // Handing a task to another of the owner's sandboxes over a link card (`agents delegate`), and which links this
     // conversation's turn may hand work to (`agents links`); held to the cards the turn was granted, like the tool.
     "POST /children/delegate": { agent: true, control: "never" },
     "GET /children/links": { agent: true, control: "never" },
     "GET /children": { agent: true, control: "never" },
-    // The fleet reads, and the one write: words in front of another conversation, which a person can do by typing.
+    // The fleet reads, and its two writes: words in front of another conversation, which a person can do by typing, and
+    // the Continue a person can press on one a spent allowance or a stop held (`agents resume`).
     "GET /fleet": { agent: true },
     "POST /fleet/message": { agent: true },
+    "POST /fleet/resume": { agent: true },
     "GET /fleet/{handle}": { agent: true },
     // The `devices push` CLI: a program the agent built, carried to one of the owner's computers in chunks; held to the
     // devices the calling conversation's turn mounts, and refused by the machine itself unless "Run programs" is on.
@@ -192,6 +197,7 @@ export const RAW_ROUTES = {
     "DELETE /system/hosts/{id}": { control: "never" },
     // A peer's socket reconnects on its own backoff, so it answers before boot.
     "GET /system/hosts/connect": { auth: "door", beforeBoot: true, control: "never" },
+    "POST /system/hosts/keyring-changed": { auth: "door", control: "never" },
     "POST /system/webext/pair": { control: "never" },
     "POST /system/webext/enroll": { auth: "door", control: "never" },
     "GET /system/webext": { control: "never" },
@@ -204,6 +210,11 @@ export const RAW_ROUTES = {
     "GET /system/phones/connect": { auth: "door", beforeBoot: true, control: "never" },
     // The editor hands over the push-relay channel it registered for a phone, so the sandbox can wake it.
     "POST /system/phones/{id}/wake": { control: "never" },
+    // The phone as Android's autofill service (schemas/phone-passwords.ts): each checks the phone's enrollment token itself.
+    "GET /system/phones/passwords/keyrings": { auth: "door", control: "never" },
+    "POST /system/phones/passwords/pair": { auth: "door", control: "never" },
+    "POST /system/phones/passwords/capture": { auth: "door", control: "never" },
+    "POST /system/phones/passwords/fill": { auth: "door", control: "never" },
     "POST /system/runners/pair": { control: "never" },
     "POST /system/runners/enroll": { auth: "door", control: "never" },
     "GET /system/runners": { control: "never" },
@@ -219,6 +230,7 @@ export const RAW_ROUTES = {
     // A secret the browser types for the agent (`type_secret` aimed at it): one value for one ticket the daemon minted
     // for this browser and one host, handed back on the browser's own request rather than over the tool socket.
     "POST /system/webext/secret": { auth: "door", control: "never" },
+    "POST /system/webext/grants-changed": { auth: "door", control: "never" },
     // This sandbox's keyring keys (schemas/keyring.ts), public halves only: a keyring fetches them here over TLS, from the
     // sandbox's own address, before it shares anything with it, rather than take them from whoever relays the share.
     "GET /keyring/keys": { auth: "door", control: "never" },

package/src/schemas/agent-next.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+
+// WHAT MOVES A CONVERSATION NEXT WITH NOBODY PRESSING ANYTHING: the one answer every surface reads (AgentSummary.next).
+// Five mechanisms can carry a conversation on by themselves: a spent allowance's held turn re-run at its reopen or moved
+// to another account, a message held for memory sent once memory frees, and messages a person booked for a time or for
+// after another conversation lands. Each used to publish its own raw state on the card (a booking flag copied onto the
+// stored ending and re-synced every beat, the queue's own shadow, a failure code plus an answer the editor looked up in
+// Settings), and each surface rebuilt "does it go by itself" from its own subset: the lane from two of them, the card's
+// corner from three, the chat's bar from one more. They disagreed (a memory hold "sends when room" in the corner and
+// waited in Attention; a booked resend read as Attention after a restart; a booked message cancelled with an archive
+// that never counted it). The daemon now derives this one value from what the conversation holds, every time the card
+// is read (conversation-next.ts), and nothing else on the card says whether or when it goes by itself.
+export const AgentNextSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("rerun"),
+        at: z.number().describe("When the held turn goes again, in milliseconds: its allowance's reopen, or the next pass for a move. Already past means any moment now."),
+        onto: z.string().optional().describe("The account the owner's answer to the limit is moving it to. Absent when it goes again where it was refused."),
+    }),
+    z.object({ kind: z.literal("room") }).describe("A message, or a turn the sandbox kept, held because memory ran short: it goes once memory has stayed free a while."),
+    z.object({
+        kind: z.literal("send"),
+        at: z.number().describe("When the soonest booked message goes, in milliseconds."),
+        count: z.number().int().min(1).describe("How many messages are booked to go by themselves."),
+    }),
+    z.object({
+        kind: z.literal("land"),
+        after: z.string().describe("The conversation whose landed work the first booked message waits for."),
+        count: z.number().int().min(1).describe("How many messages are booked to go by themselves."),
+    }),
+]);
+export type AgentNext = z.infer<typeof AgentNextSchema>;
+
+/** Whether a conversation carries on by itself, with nobody pressing anything: the one reading of `next`. */
+export const goesBySelf = (agent: { readonly next?: AgentNext | undefined }): boolean => agent.next !== undefined;

package/src/schemas/agent-place.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+// Words put in an agent's mouth (`agents.place`): what is asked, and what the record answers.
+
+// Bounded just above the handoff's per-message render cap, so a line too long to carry whole doesn't reach the agent
+// truncated.
+export const AgentPlaceSchema = z.object({
+    id: z.string().min(1).describe("Which conversation."),
+    text: z
+        .string()
+        .trim()
+        .min(1)
+        .max(8_000)
+        .describe(
+            "The words to put in the agent's mouth. Bounded just above what the next turn can carry whole, because a line too long to be handed over intact would reach the agent truncated and quietly break the very thing this is for.",
+        ),
+});
+// The placed line's own id, so the window that placed it holds the same row its next read of the record brings.
+export const AgentPlacedSchema = z.object({
+    ok: z.literal(true).describe("Always true: the line is on the record."),
+    rowId: z.string().optional().describe("The `rowId` the line was recorded under. Absent from a sandbox older than row ids."),
+});

package/src/schemas/agent-search.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+// The board's search over what conversations said: the query, and what came back with its evidence.
+
+// Searches only speech, both sides of the conversation, never thinking, tool output or protocol text, which would
+// otherwise match nearly the whole board. Two-char minimum; `caseSensitive` off means case-insensitive, matching
+// workspace search's own switch.
+export const AgentSearchQuerySchema = z.object({
+    query: z
+        .string()
+        .trim()
+        .min(2)
+        .describe(
+            "What to look for. Searched against what was said, both sides of the conversation, and nothing else: not the thinking, not the tool output, which between them name nearly every identifier in the workspace and would return most of the board.",
+        ),
+    caseSensitive: z.stringbool().optional().describe("Whether capitals matter."),
+});
+// Why a row survived the filter: the matched line, windowed, and who said it. `speaker` rides with the text since agent
+// prose alone can read as something the user typed.
+export const SpeakerSchema = z.enum(["user", "agent"]);
+export type Speaker = z.infer<typeof SpeakerSchema>;
+export const MatchSnippetSchema = z.object({
+    text: z.string().describe("The matching line, with a little either side of it."),
+    speaker: SpeakerSchema.describe(
+        "Who said it. Carried with the words rather than beside them, because a line of the agent's prose under a card reads as something you typed until the row says otherwise.",
+    ),
+});
+export type MatchSnippet = z.infer<typeof MatchSnippetSchema>;
+// One matching agent and its evidence; `snippet` is absent for a title match, which the card already shows.
+export const AgentMatchSchema = z.object({
+    id: z.string().describe("Which conversation matched."),
+    snippet: MatchSnippetSchema.optional().describe(
+        "Why, in its own words. Absent when the title was the match, which the card already shows: repeating it underneath is noise where evidence was wanted.",
+    ),
+});
+export type AgentMatch = z.infer<typeof AgentMatchSchema>;
+// How many agents were actually read, so the board can say a search saw less than the whole fleet.
+export const AgentSearchResultSchema = z.object({
+    matches: z.array(AgentMatchSchema).describe("What matched, from the live fleet and the archive together."),
+    scanned: z
+        .number()
+        .describe(
+            "How many conversations were actually read, so a screen can say when a search saw less than everything rather than implying it saw all of it.",
+        ),
+    indexing: z
+        .boolean()
+        .describe(
+            "Whether what was said is still being read in the background. True means this answer can still grow, so a screen must say it is incomplete rather than presenting it as the whole list.",
+        ),
+});
+export type AgentSearchResult = z.infer<typeof AgentSearchResultSchema>;