@adecore/agent-contracts 0.0.1 → 0.17.0-beta.1

package/src/envelope.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+
+export const ErrorSchema = z.object({
+    code: z.string().min(1),
+    message: z.string()
+});
+export type WireError = z.infer<typeof ErrorSchema>;
+
+export const RequestSchema = z.object({
+    id: z.string().min(1),
+    type: z.string().min(1),
+    payload: z.unknown()
+});
+export type Request = z.infer<typeof RequestSchema>;
+
+export const ReplyOkSchema = z.object({
+    id: z.string().min(1),
+    ok: z.literal(true),
+    result: z.unknown()
+});
+export type ReplyOk = z.infer<typeof ReplyOkSchema>;
+
+// The id is nullable so the server can still answer a frame it could not parse at all.
+export const ReplyErrorSchema = z.object({
+    id: z.string().min(1).nullable(),
+    ok: z.literal(false),
+    error: ErrorSchema
+});
+export type ReplyError = z.infer<typeof ReplyErrorSchema>;
+
+export const ReplySchema = z.discriminatedUnion('ok', [ReplyOkSchema, ReplyErrorSchema]);
+export type Reply = z.infer<typeof ReplySchema>;
+
+export const EventSchema = z.object({
+    type: z.literal('event'),
+    event: z.string().min(1),
+    payload: z.unknown()
+});
+export type Event = z.infer<typeof EventSchema>;
+
+export const ServerFrameSchema = z.union([ReplySchema, EventSchema]);
+export type ServerFrame = z.infer<typeof ServerFrameSchema>;
+
+export type ParseResult<T> = { ok: true; value: T } | { ok: false; message: string };
+
+function toResult<T>(parsed: z.ZodSafeParseResult<T>): ParseResult<T> {
+    if (parsed.success) {
+        return { ok: true, value: parsed.data };
+    }
+    return { ok: false, message: z.prettifyError(parsed.error) };
+}
+
+export function parseRequest(input: unknown): ParseResult<Request> {
+    return toResult(RequestSchema.safeParse(input));
+}
+
+export function parseServerFrame(input: unknown): ParseResult<ServerFrame> {
+    return toResult(ServerFrameSchema.safeParse(input));
+}

package/src/ids.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+
+// The client picks the id (its node id), so the only rule is that it is not empty.
+export const SessionIdSchema = z.string().min(1);
+export type SessionId = z.infer<typeof SessionIdSchema>;

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from './agent.ts';
+export * from './chat.ts';
+export * from './envelope.ts';
+export * from './ids.ts';
+export * from './model.ts';
+export * from './protocol.ts';
+export * from './provider-accounts.ts';
+export * from './task.ts';
+export * from './text.ts';
+export * from './usage.ts';
+export * from './worktree.ts';
+export type * from './port.ts';

package/src/model.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import { AgentKindSchema } from './agent.ts';
+
+// Options a model exposes (effort, context window, thinking). Generic descriptors instead of
+// per-provider enums: a new model is a catalog entry, not a code change.
+export const ModelOptionChoiceSchema = z.object({
+    id: z.string().min(1),
+    label: z.string(),
+    description: z.string().optional()
+});
+export type ModelOptionChoice = z.infer<typeof ModelOptionChoiceSchema>;
+
+export const ModelOptionDescriptorSchema = z.discriminatedUnion('type', [
+    z.object({
+        id: z.string().min(1),
+        label: z.string(),
+        type: z.literal('select'),
+        choices: z.array(ModelOptionChoiceSchema).min(1),
+        defaultChoice: z.string()
+    }),
+    z.object({
+        id: z.string().min(1),
+        label: z.string(),
+        type: z.literal('boolean'),
+        defaultValue: z.boolean(),
+        // The line under the label in the picker: what turning it on costs or asks for.
+        description: z.string().optional()
+    })
+]);
+export type ModelOptionDescriptor = z.infer<typeof ModelOptionDescriptorSchema>;
+
+export const ModelInfoSchema = z.object({
+    slug: z.string().min(1),
+    name: z.string(),
+    badge: z.string().optional(),
+    legacy: z.boolean(),
+    isDefault: z.boolean(),
+    options: z.array(ModelOptionDescriptorSchema)
+});
+export type ModelInfo = z.infer<typeof ModelInfoSchema>;
+
+export const ModelSelectionSchema = z.object({
+    model: z.string().min(1),
+    options: z.record(z.string(), z.union([z.string(), z.boolean()]))
+});
+export type ModelSelection = z.infer<typeof ModelSelectionSchema>;
+
+// A slug ends up on a CLI's command line, so it never starts with a dash and carries no brackets.
+const ModelSlugSchema = z.string().regex(/^[a-z0-9][a-z0-9._-]*$/, 'Expected a model slug');
+
+export const ModelCatalogProfileSchema = z.object({
+    options: z.array(ModelOptionDescriptorSchema),
+    // Context size per value of the `contextWindow` option, or `*` when the model has one size.
+    contextWindowTokens: z.record(z.string(), z.number().int().positive())
+});
+export type ModelCatalogProfile = z.infer<typeof ModelCatalogProfileSchema>;
+
+export const ModelCatalogEntrySchema = z.object({
+    slug: ModelSlugSchema,
+    name: z.string().min(1),
+    badge: z.string().optional(),
+    profile: z.string().min(1),
+    aliases: z.array(z.string().min(1)).optional(),
+    legacy: z.boolean().optional()
+});
+export type ModelCatalogEntry = z.infer<typeof ModelCatalogEntrySchema>;
+
+/*
+ * The models one provider offers, as a host ships them and as a catalog service hands out a newer
+ * copy. `updatedAt` orders the two, so a copy older than the one a host shipped with is never taken.
+ */
+export const ModelCatalogDataSchema = z
+    .object({
+        updatedAt: z.iso.datetime(),
+        defaultModel: ModelSlugSchema,
+        profiles: z.record(z.string(), ModelCatalogProfileSchema),
+        models: z.array(ModelCatalogEntrySchema).min(1)
+    })
+    .refine((data) => data.models.every((model) => data.profiles[model.profile] !== undefined), 'Every model needs a profile the catalog has')
+    .refine((data) => data.models.some((model) => model.slug === data.defaultModel), 'The default model has to be one of the models');
+export type ModelCatalogData = z.infer<typeof ModelCatalogDataSchema>;
+
+// The thread's permission policy, one vocabulary for every provider; each adapter maps it.
+export const RuntimeModeSchema = z.enum(['supervised', 'auto-accept-edits', 'auto', 'full-access']);
+export type RuntimeMode = z.infer<typeof RuntimeModeSchema>;
+
+// What a provider's CLI can do, so a client never offers what it would drop and the daemon
+// never asks for what the protocol has no room for. Read by the composer and the thread rows.
+export const ProviderCapabilitiesSchema = z.object({
+    // Where this CLI can be opened: as a chat node, as a terminal node, or both.
+    chat: z.boolean(),
+    terminal: z.boolean(),
+    // Whether the daemon understands this CLI's hooks; without them a node shows the session status only.
+    hooks: z.boolean(),
+    // Partial output while a tool call runs, for the live row under it.
+    streamsToolOutput: z.boolean(),
+    // How a file change reaches the thread: as a unified diff, as the text before and after, or not at all.
+    diffs: z.enum(['unified', 'before-after', 'none']),
+    attachments: z.boolean(),
+    mentions: z.boolean(),
+    // Whether a decline carries a reason for the agent.
+    denyReason: z.boolean(),
+    allowAlways: z.boolean(),
+    // A question the person may leave alone while the turn goes on.
+    asyncQuestions: z.boolean(),
+    // Folding the context: a call of its own, a slash command sent as a turn, or nothing.
+    compaction: z.enum(['native', 'prompt', 'none']),
+    reportsCost: z.boolean(),
+    reportsContextWindow: z.boolean(),
+    // Whether the CLI hands over what the model thought before it answered.
+    reportsThinking: z.boolean(),
+    slashCommands: z.boolean()
+});
+export type ProviderCapabilities = z.infer<typeof ProviderCapabilitiesSchema>;
+
+export const ProviderInfoSchema = z.object({
+    kind: AgentKindSchema,
+    name: z.string(),
+    installed: z.boolean(),
+    version: z.string().nullable(),
+    // Empty while the CLI is not installed or has no chat backend yet.
+    models: z.array(ModelInfoSchema),
+    defaultModel: z.string().nullable(),
+    capabilities: ProviderCapabilitiesSchema,
+    // What a terminal runs to continue one of this CLI's sessions. `{id}` stands for the session id
+    // and `{flags}` for the flags the launch carries, which is where in the line each CLI takes them.
+    resumeCommand: z.string()
+});
+export type ProviderInfo = z.infer<typeof ProviderInfoSchema>;
+
+export const ProviderListResultSchema = z.object({
+    providers: z.array(ProviderInfoSchema)
+});
+export type ProviderListResult = z.infer<typeof ProviderListResultSchema>;
+
+/*
+ * Fills a provider's resume template; the id is quoted so a shell takes it as one word. `{flags}` is
+ * a word of its own rather than a substring, since it stands for none, one or several words and a
+ * substitution would leave a double space behind where a launch carries no flags at all.
+ */
+export function resumeCommandFor(template: string, agentSessionId: string, flags: string[] = []): string {
+    const id = `'${agentSessionId.replaceAll("'", `'\\''`)}'`;
+    return template
+        .split(' ')
+        .flatMap((word) => (word === '{flags}' ? flags : [word.replace('{id}', id)]))
+        .join(' ');
+}

package/src/port.ts

@@ -0,0 +1,11 @@
+import type { Request, ServerFrame } from './envelope.ts';
+
+/*
+ * Two ends that pass the wire's frames without a socket: a MessagePort between a renderer and the
+ * process that runs the chats, or a pair in a test. A frame is checked where it arrives, so it
+ * crosses as `unknown`.
+ */
+export interface FramePort {
+    send(frame: Request | ServerFrame): void;
+    onFrame(listener: (frame: unknown) => void): () => void;
+}

package/src/protocol.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import {
+    ChatAddBookmarkPayloadSchema,
+    ChatAnswerPayloadSchema,
+    ChatApprovePayloadSchema,
+    ChatAttachPayloadSchema,
+    ChatAttachResultSchema,
+    ChatBookmarksEventSchema,
+    ChatBookmarksResultSchema,
+    ChatCancelPayloadSchema,
+    ChatClearPayloadSchema,
+    ChatConfigurePayloadSchema,
+    ChatContinueOnPayloadSchema,
+    ChatContinueOnResultSchema,
+    ChatCreatePayloadSchema,
+    ChatDismissPayloadSchema,
+    ChatEventEnvelopeSchema,
+    ChatForkInfoPayloadSchema,
+    ChatForkInfoResultSchema,
+    ChatForkPayloadSchema,
+    ChatForkResultSchema,
+    ChatHistoryPayloadSchema,
+    ChatHistoryResultSchema,
+    ChatInfoSchema,
+    ChatListResultSchema,
+    ChatPreferencesPayloadSchema,
+    ChatQueuePayloadSchema,
+    ChatRemoveBookmarkPayloadSchema,
+    ChatRenameBookmarkPayloadSchema,
+    ChatSendPayloadSchema,
+    ChatSendResultSchema,
+    ChatStatusEventSchema,
+    ChatStopSubagentPayloadSchema,
+    ChatStopTaskPayloadSchema,
+    ChatSubagentChangedEventSchema,
+    ChatSubagentPayloadSchema,
+    ChatSubagentResultSchema,
+    ChatSummarizePayloadSchema,
+    ChatSummarizeResultSchema,
+    ChatTargetPayloadSchema,
+    ChatTurnDiffPayloadSchema,
+    ChatTurnDiffResultSchema,
+    ChatUnqueueResultSchema,
+    SkillsListPayloadSchema,
+    SkillsListResultSchema
+} from './chat.ts';
+import { ProviderListResultSchema } from './model.ts';
+import {
+    ProviderAccountCreatePayloadSchema,
+    ProviderAccountCreateResultSchema,
+    ProviderAccountWatchLoginPayloadSchema,
+    ProviderAccountsSavePayloadSchema,
+    ProviderAccountsSchema
+} from './provider-accounts.ts';
+import { UsageChangedEventSchema, UsageLimitsSnapshotSchema, UsageSummaryPayloadSchema, UsageSummaryResultSchema } from './usage.ts';
+
+export const EmptySchema = z.object({});
+
+/*
+ * The requests a chat, its providers and their usage answer, with what goes in and what comes back.
+ * An application places each one in its own wire table, so a host that only runs chats serves
+ * exactly these and a client reads the same shapes either way.
+ */
+export const AGENT_REQUEST_SCHEMAS = {
+    'chat.create': { payload: ChatCreatePayloadSchema, result: ChatInfoSchema },
+    'chat.history': { payload: ChatHistoryPayloadSchema, result: ChatHistoryResultSchema },
+    'chat.attach': { payload: ChatAttachPayloadSchema, result: ChatAttachResultSchema },
+    'chat.detach': { payload: ChatTargetPayloadSchema, result: EmptySchema },
+    'chat.send': { payload: ChatSendPayloadSchema, result: ChatSendResultSchema },
+    'chat.unqueue': { payload: ChatQueuePayloadSchema, result: ChatUnqueueResultSchema },
+    'chat.sendNow': { payload: ChatQueuePayloadSchema, result: EmptySchema },
+    'chat.cancel': { payload: ChatCancelPayloadSchema, result: EmptySchema },
+    'chat.approve': { payload: ChatApprovePayloadSchema, result: EmptySchema },
+    'chat.answer': { payload: ChatAnswerPayloadSchema, result: EmptySchema },
+    'chat.dismiss': { payload: ChatDismissPayloadSchema, result: EmptySchema },
+    'chat.configure': { payload: ChatConfigurePayloadSchema, result: ChatInfoSchema },
+    'chat.setPreferences': { payload: ChatPreferencesPayloadSchema, result: EmptySchema },
+    'chat.compact': { payload: ChatTargetPayloadSchema, result: EmptySchema },
+    'chat.clear': { payload: ChatClearPayloadSchema, result: EmptySchema },
+    'chat.turnDiff': { payload: ChatTurnDiffPayloadSchema, result: ChatTurnDiffResultSchema },
+    'chat.fork': { payload: ChatForkPayloadSchema, result: ChatForkResultSchema },
+    'chat.continueOn': { payload: ChatContinueOnPayloadSchema, result: ChatContinueOnResultSchema },
+    'chat.forkInfo': { payload: ChatForkInfoPayloadSchema, result: ChatForkInfoResultSchema },
+    'chat.summarize': { payload: ChatSummarizePayloadSchema, result: ChatSummarizeResultSchema },
+    'chat.subagent': { payload: ChatSubagentPayloadSchema, result: ChatSubagentResultSchema },
+    'chat.stopSubagent': { payload: ChatStopSubagentPayloadSchema, result: EmptySchema },
+    'chat.stopTask': { payload: ChatStopTaskPayloadSchema, result: EmptySchema },
+    'chat.addBookmark': { payload: ChatAddBookmarkPayloadSchema, result: ChatBookmarksResultSchema },
+    'chat.renameBookmark': { payload: ChatRenameBookmarkPayloadSchema, result: ChatBookmarksResultSchema },
+    'chat.removeBookmark': { payload: ChatRemoveBookmarkPayloadSchema, result: ChatBookmarksResultSchema },
+    'skills.list': { payload: SkillsListPayloadSchema, result: SkillsListResultSchema },
+    'provider.list': { payload: EmptySchema, result: ProviderListResultSchema },
+    'accounts.list': { payload: EmptySchema, result: ProviderAccountsSchema },
+    'accounts.save': { payload: ProviderAccountsSavePayloadSchema, result: ProviderAccountsSchema },
+    // Asks every CLI again and answers once they all did.
+    'accounts.refresh': { payload: EmptySchema, result: ProviderAccountsSchema },
+    'accounts.create': { payload: ProviderAccountCreatePayloadSchema, result: ProviderAccountCreateResultSchema },
+    // Answers at once; what the CLI says arrives as `accounts.changed`.
+    'accounts.watchLogin': { payload: ProviderAccountWatchLoginPayloadSchema, result: EmptySchema },
+    'usage.summary': { payload: UsageSummaryPayloadSchema, result: UsageSummaryResultSchema },
+    'usage.subscribe': { payload: EmptySchema, result: EmptySchema },
+    'usage.unsubscribe': { payload: EmptySchema, result: EmptySchema },
+    'usage.limits': { payload: EmptySchema, result: UsageLimitsSnapshotSchema },
+    'usage.refreshLimits': { payload: EmptySchema, result: UsageLimitsSnapshotSchema },
+    'chat.kill': { payload: ChatTargetPayloadSchema, result: EmptySchema },
+    'chat.list': { payload: EmptySchema, result: ChatListResultSchema }
+} as const;
+
+export const AGENT_EVENT_SCHEMAS = {
+    'chat.event': ChatEventEnvelopeSchema,
+    'chat.status': ChatStatusEventSchema,
+    'chat.subagentChanged': ChatSubagentChangedEventSchema,
+    'chat.bookmarks': ChatBookmarksEventSchema,
+    'usage.changed': UsageChangedEventSchema,
+    'usage.limitsChanged': UsageLimitsSnapshotSchema,
+    'accounts.changed': ProviderAccountsSchema
+} as const;
+
+export type AgentRequestType = keyof typeof AGENT_REQUEST_SCHEMAS;
+export type AgentEventType = keyof typeof AGENT_EVENT_SCHEMAS;

package/src/provider-accounts.ts

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+import { AgentKindSchema } from './agent.ts';
+
+/*
+ * An account of an agent CLI is one config folder of that CLI, handed to it through the variable it
+ * reads its folder from. The person signs in with the CLI itself; the daemon only asks the CLI who
+ * that is. Accounts belong to one host and live in its provider account store.
+ */
+
+/* A slug, never a path. The default account of a CLI has the CLI's kind as its id. */
+export const ProviderAccountIdSchema = z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/);
+export type ProviderAccountId = z.infer<typeof ProviderAccountIdSchema>;
+
+/*
+ * A variable the CLI of an account is started with. A sensitive value lives in the keychain of the
+ * machine and never on the wire: the daemon sends it as an empty `value` with `valueRedacted`, and a
+ * save that sends that back keeps what the keychain holds.
+ */
+export const ProviderAccountVariableSchema = z.object({
+    name: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,127}$/),
+    value: z.string(),
+    sensitive: z.boolean(),
+    valueRedacted: z.boolean().optional()
+});
+export type ProviderAccountVariable = z.infer<typeof ProviderAccountVariableSchema>;
+
+export const ProviderAccountSchema = z.object({
+    // An agent kind. A kind this version does not know still parses, so the entry is written back unchanged.
+    kind: z.string().min(1),
+    label: z.string().optional(),
+    // A node accent name (`NODE_ACCENT_NAMES`), kept a plain string so an older name is written back; the client paints any other with its accent.
+    color: z.string().optional(),
+    // Absent is on. An account that is off is left out of every picker.
+    enabled: z.boolean().optional(),
+    // The CLI's config folder, `~` allowed. Absent on the default account, which uses the CLI's own folder.
+    home: z.string().min(1).optional(),
+    // Codex only: a folder of its own for the login, sharing everything else with `home`.
+    shadowHome: z.string().min(1).optional(),
+    // Set on the CLI's environment after the login variables are taken off, so a key here is one a person chose.
+    env: z.array(ProviderAccountVariableSchema).optional()
+});
+export type ProviderAccount = z.infer<typeof ProviderAccountSchema>;
+
+export const ProviderAccountStateSchema = z.enum([
+    'checking',
+    'disabled',
+    // The CLI is not installed on this machine.
+    'not-found',
+    'signed-out',
+    'ready',
+    'folder-missing',
+    // A kind this version does not know, or a CLI with no variable for its config folder.
+    'unavailable',
+    'failed'
+]);
+export type ProviderAccountState = z.infer<typeof ProviderAccountStateSchema>;
+
+/* What the CLI said about an account the last time it was asked. Never stored: the CLI is the truth. */
+export const ProviderAccountStatusSchema = z.object({
+    id: ProviderAccountIdSchema,
+    kind: z.string(),
+    state: ProviderAccountStateSchema,
+    email: z.string().nullable(),
+    plan: z.string().nullable(),
+    organization: z.string().nullable(),
+    // The folder the CLI is started with, resolved; empty for a CLI without a config folder variable.
+    home: z.string(),
+    // Where the account's conversations are written, resolved: a chat goes on under another account only when both write here.
+    transcripts: z.string().optional(),
+    // Why the state is what it is, in a sentence, when the CLI or the daemon said.
+    message: z.string().nullable(),
+    // Milliseconds since the epoch; 0 while the account was never checked.
+    checkedAt: z.number()
+});
+export type ProviderAccountStatus = z.infer<typeof ProviderAccountStatusSchema>;
+
+export const ProviderAccountMapSchema = z.record(ProviderAccountIdSchema, ProviderAccountSchema);
+export type ProviderAccountMap = z.infer<typeof ProviderAccountMapSchema>;
+
+export const ProviderAccountsSchema = z.object({
+    accounts: ProviderAccountMapSchema,
+    statuses: z.array(ProviderAccountStatusSchema),
+    // Whether this machine can keep a sensitive variable; false off macOS, where no keychain is used.
+    secretsAvailable: z.boolean().optional(),
+    // Per agent kind, what a terminal types to sign that CLI in under an account, which the account's environment points at.
+    loginCommands: z.partialRecord(AgentKindSchema, z.string()).optional()
+});
+export type ProviderAccounts = z.infer<typeof ProviderAccountsSchema>;
+
+/* The whole map: an id left out is removed, and its folder stays where it is. */
+export const ProviderAccountsSavePayloadSchema = z.object({
+    accounts: ProviderAccountMapSchema
+});
+export type ProviderAccountsSavePayload = z.infer<typeof ProviderAccountsSavePayloadSchema>;
+
+/* An account in a folder the daemon makes for it under its account data directory; a Codex one is a shadow home over the CLI's own folder. */
+export const ProviderAccountCreatePayloadSchema = z.object({
+    kind: AgentKindSchema,
+    label: z.string().trim().min(1).max(80),
+    color: z.string().optional()
+});
+export type ProviderAccountCreatePayload = z.infer<typeof ProviderAccountCreatePayloadSchema>;
+
+export const ProviderAccountCreateResultSchema = ProviderAccountsSchema.extend({
+    // The id the daemon minted from the label.
+    id: ProviderAccountIdSchema
+});
+export type ProviderAccountCreateResult = z.infer<typeof ProviderAccountCreateResultSchema>;
+
+/* Asks the CLI of one account again every few seconds until it is signed in, for a login running in a terminal. */
+export const ProviderAccountWatchLoginPayloadSchema = z.object({
+    id: ProviderAccountIdSchema
+});
+export type ProviderAccountWatchLoginPayload = z.infer<typeof ProviderAccountWatchLoginPayloadSchema>;

package/src/task.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+export const TaskStatusSchema = z.enum(['open', 'done', 'failed', 'cancelled']);
+export type TaskStatus = z.infer<typeof TaskStatusSchema>;
+
+export const TaskResultSchema = z.object({
+    text: z.string(),
+    // How the result came about: the child called `done`, its first turn ended, or its process left.
+    source: z.enum(['done', 'turn', 'exit']),
+    at: z.number()
+});
+export type TaskResult = z.infer<typeof TaskResultSchema>;
+
+/*
+ * What a chat asked of a node it opened with `--task`, kept by the host under its data folder rather
+ * than anywhere an agent can write: waking the parent is a promise the host keeps.
+ */
+export const TaskSchema = z.object({
+    id: z.string().min(1),
+    projectId: z.string().min(1),
+    parentId: z.string().min(1),
+    childId: z.string().min(1),
+    title: z.string(),
+    prompt: z.string(),
+    // The one `team --task` call it came from: the parent is woken about that call once every task of it settled.
+    batchId: z.string().min(1).optional(),
+    requiresTaskTurn: z.boolean().optional(),
+    background: z.object({ turnId: z.string(), itemIds: z.array(z.string()), commands: z.array(z.string()) }).optional(),
+    status: TaskStatusSchema,
+    result: TaskResultSchema.nullable(),
+    createdAt: z.number(),
+    settledAt: z.number().nullable(),
+    // Whether the parent has been woken about this task yet; `none` for a task that never wakes anybody.
+    wake: z.enum(['pending', 'sent', 'none']),
+    // Set while the child's last turn stopped on a limit: the task stays open and wakes nobody, `until` the limit lifts when known.
+    paused: z.object({ kind: z.enum(['usage', 'overload']), until: z.number().optional() }).optional()
+});
+export type Task = z.infer<typeof TaskSchema>;
+
+export const TaskChangedEventSchema = z.object({ task: TaskSchema });
+export type TaskChangedEvent = z.infer<typeof TaskChangedEventSchema>;

package/src/text.ts

@@ -0,0 +1,20 @@
+const graphemes = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+
+/*
+ * The longest start of `text` that fits in `max` UTF-16 units, the measure a schema's `max` counts in,
+ * cut only between characters as a person sees them. A cut between the halves of a surrogate pair
+ * leaves a lone half, which JSON writes as an escape the iPhone app refuses along with its whole frame.
+ */
+export function clipText(text: string, max: number): string {
+    if (text.length <= max) {
+        return text;
+    }
+    let end = 0;
+    for (const { segment } of graphemes.segment(text)) {
+        if (end + segment.length > max) {
+            break;
+        }
+        end += segment.length;
+    }
+    return text.slice(0, end);
+}