@joe-broadhead/messaging 0.7.1 → 0.9.0

package/dist/lib/modules/core/schema/ipc/conversation-views.js

@@ -0,0 +1,87 @@
+/** Rendered conversation projections for the future conversation IPC cut-over.
+ * Peer names, text and file names are untrusted; clients must fence or sanitize them.
+ * These schemas do not register a method on either socket.
+ */
+import { z } from "../../../vendor/zod/index.js";
+import { LIMITS, Millis, SessionName, Ulid } from "../common.js";
+import { AgentContext, ConvId, ConvKind, ConvRole, HistoryPolicy, Mention, ParticipantId, RespondTo, Visibility } from "../conversation.js";
+import { TaskState } from "../a2a.js";
+import { ActionToken, PersonTask } from "./shapes.js";
+const Count = z.number().int().nonnegative().safe();
+const Seq = z.number().int().nonnegative().safe();
+const Name = z.string().max(200);
+export const ParticipantView = z.object({
+    p: ParticipantId,
+    kind: z.enum(["person", "agent"]),
+    role: ConvRole,
+    state: z.enum(["member", "invited"]),
+    name: Name,
+    handle: z.string().max(64).optional(),
+    org: z.enum(["same", "other", "none"]),
+    presence: z.enum(["online", "away", "offline", "unknown"]),
+    agentState: z.enum(["idle", "busy", "kept"]).optional(),
+    respondTo: RespondTo.optional(),
+});
+/** Names travel with a notice so rendering it does not need one lookup per participant. */
+export const NoticeView = z.object({
+    op: z.enum(["create", "add", "accept", "join", "leave", "remove", "role", "seat", "settings", "archive", "meta", "policy"]),
+    by: ParticipantView.pick({ p: true, kind: true, name: true }),
+    participants: z.array(ParticipantView.pick({ p: true, kind: true, name: true })).max(LIMITS.convOpParticipants).optional(),
+    fields: z.array(z.enum(["name", "topic", "purpose", "visibility", "history", "retainDays", "post", "invite", "pins", "agentContext", "bridges"])).max(12).optional(),
+});
+/** A file projection deliberately excludes the key and nonce in the encrypted wire attachment. */
+export const FileView = z.object({
+    blob: z.string().regex(/^b_[A-Za-z0-9_-]{43}$/),
+    name: z.string().max(255), mime: z.string().max(100), bytes: z.number().int().positive().max(LIMITS.blobBytes),
+});
+/**
+ * `cancel`: the source-issued action that stops the task (spec §8.2, "Action tokens"), redeemed with
+ * `task.cancel {taskId, token}`. Only on a task this person's agent asked that has not ended, and only on the human tier.
+ */
+export const TaskView = z.object({ id: Ulid, state: TaskState, cancel: z.strictObject({ name: z.literal("cancel"), token: ActionToken }).optional() });
+export const EventView = z.object({
+    cid: ConvId, id: Ulid, seq: z.number().int().positive().safe(), at: Millis,
+    author: ParticipantView.pick({ p: true, kind: true, name: true }),
+    kind: z.enum(["line", "task", "notice"]),
+    text: z.string().max(LIMITS.lineChars).optional(), format: z.enum(["plain", "md"]).optional(),
+    thread: Ulid.optional(), broadcast: z.boolean().optional(),
+    mentions: z.array(Mention).max(LIMITS.mentions).optional(), mentionsMe: z.boolean(),
+    files: z.array(FileView).max(LIMITS.files).optional(), edited: Millis.optional(), deleted: z.boolean().optional(),
+    reactions: z.array(z.object({ key: z.string().min(1).max(64), count: Count, mine: z.boolean() })).max(LIMITS.reactionsPerEvent).optional(),
+    pinned: z.boolean().optional(),
+    replies: z.object({ count: Count, lastAt: Millis, participants: z.array(ParticipantId).max(5), unread: Count.optional(), following: z.boolean().optional() }).optional(),
+    task: TaskView.optional(), notice: NoticeView.optional(),
+    delivery: z.enum(["pending", "sent", "delivered", "read", "failed"]).optional(),
+    clientId: z.string().min(1).max(200).optional(),
+}).refine((event) => !event.deleted || (event.text === undefined && event.files === undefined), {
+    message: "a deleted event contains no text or files",
+});
+export const ConvView = z.object({
+    cid: ConvId, kind: ConvKind, visibility: Visibility.optional(), history: HistoryPolicy,
+    retainDays: z.number().int().min(1).max(LIMITS.retainDaysMax), agentContext: AgentContext,
+    name: z.string().max(80).optional(), topic: z.string().max(250).optional(), purpose: z.string().max(250).optional(),
+    archived: z.boolean(), role: ConvRole, participants: Count, dmWith: ParticipantView.optional(), last: EventView.optional(),
+    headSeq: Seq, readUpTo: Seq.optional(), unread: Count.optional(), mentions: Count.optional(), threadsUnread: Count.optional(),
+    notify: z.enum(["all", "mentions", "none"]).optional(), mutedUntil: Millis.optional(), draft: z.string().max(8000).optional(),
+});
+export const ActivityBody = z.object({
+    session: SessionName, turn: Ulid, seq: Seq,
+    source: z.object({ item: Ulid.optional(), cid: ConvId.optional(), task: Ulid.optional() }).optional(),
+    kind: z.enum(["turn_started", "step", "turn_ended", "error", "cancelled"]), summary: z.string().max(200).optional(),
+});
+export const ConvStreamEvent = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("event"), pos: Seq, event: EventView }),
+    z.object({ type: z.literal("event.update"), pos: Seq, cid: ConvId, id: Ulid,
+        change: z.enum(["edit", "delete", "react", "pin", "replies", "delivery", "task"]), event: EventView }),
+    z.object({ type: z.literal("conv"), pos: Seq, conv: ConvView }),
+    z.object({ type: z.literal("member"), pos: Seq, cid: ConvId, participant: ParticipantView,
+        change: z.enum(["added", "invited", "removed", "role", "seat", "presence"]) }),
+    z.object({ type: z.literal("read"), pos: Seq, cid: ConvId, readUpTo: Seq, unread: Count, mentions: Count }),
+    z.object({ type: z.literal("typing"), cid: ConvId, p: ParticipantId, thread: Ulid.optional(), until: Millis }),
+    z.object({ type: z.literal("activity"), body: ActivityBody }),
+    z.object({ type: z.literal("gap"), pos: Seq }),
+    /** Human tier, person-level `conv.sync` only (no session key): a task of this person's agents changed (spec §12.4). */
+    z.object({ type: z.literal("task"), pos: Seq, task: PersonTask }),
+]).refine((entry) => entry.type !== "event.update" || (entry.cid === entry.event.cid && entry.id === entry.event.id), {
+    message: "event.update names the same conversation and event as its projection",
+});

package/dist/lib/modules/core/schema/ipc/conversations.js

@@ -0,0 +1,132 @@
+/** Conversation contracts, including later lanes. Only LIVE_CONVERSATION_METHODS registers IPC. */
+import { z } from "../../../vendor/zod/index.js";
+import { LIMITS, MachineId, Millis, PersonId, SessionName, Ulid } from "../common.js";
+import { AgentContext, Attachment, ContextAccess, ContextRules, ConvId, ConvKind, ConvMeta, ConvRole, HistoryPolicy, Mention, ParticipantId, Permit, RespondTo, Seat, Visibility } from "../conversation.js";
+import { PersonSummary } from "./surfaces.js";
+import { SessionKey } from "./shapes.js";
+import { ActivityBody, ConvStreamEvent, ConvView, EventView, ParticipantView } from "./conversation-views.js";
+const Empty = z.strictObject({});
+const Ok = z.object({ ok: z.literal(true) });
+const Count = z.number().int().nonnegative().safe();
+const Seq = z.number().int().nonnegative().safe();
+const Limit = z.number().int().min(1).max(50).optional();
+const Cursor = z.string().min(1).max(512).optional();
+const Key = SessionKey.optional(); // required by the daemon on an agent connection
+const Cid = { cid: ConvId };
+const Page = { limit: Limit, cursor: Cursor };
+const Id = { cid: ConvId, id: Ulid };
+const Text = z.string().min(1).max(LIMITS.lineChars);
+const CommonErrors = ["invalid_request", "forbidden", "not_found", "too_large", "internal", "no_identity", "unknown_session", "grant_required", "grant_invalid", "directory_unavailable", "directory_inconsistent"];
+const WriteErrors = [...CommonErrors, "invalid_state", "conv_conflict", "stale_epoch", "relay_unavailable", "rate_limited", "duplicate", "secret_refused", "refused", "declined", "request_required", "loop_guard", "unknown_device", "binding_invalid"];
+const ReadErrors = [...CommonErrors, "relay_unavailable"];
+const Write = (params) => ({ params, result: Ok, errors: WriteErrors });
+const Read = (params, result) => ({ params, result, errors: ReadErrors });
+const EventPage = z.object({ events: z.array(EventView).max(50), more: z.boolean(), cursor: Cursor });
+const ConvPage = z.object({ conversations: z.array(ConvView).max(50), cursor: Cursor });
+const PageParams = z.strictObject({ ...Cid, ...Page });
+const Hold = z.object({ stage: z.literal("held"), code: z.enum(["context", "audience"]), expect: z.literal("on_consent") });
+const LineFields = { text: Text, format: z.enum(["plain", "md"]).optional(), thread: Ulid.optional(), broadcast: z.boolean().optional(),
+    mentions: z.array(Mention).max(LIMITS.mentions).optional(), files: z.array(Attachment).max(LIMITS.files).optional() };
+const OptionalSettings = { visibility: Visibility.optional(), history: HistoryPolicy.optional(), retainDays: z.number().int().min(1).max(LIMITS.retainDaysMax).optional(),
+    post: Permit.optional(), invite: Permit.optional(), pins: Permit.optional() };
+/** Explicit consent evidence and unconfirmed delivery are different states. */
+export const WaitingOnThemView = z.object({
+    id: Ulid, kind: z.enum(["message", "task", "contact"]), to: PersonId,
+    name: z.string().max(200), at: Millis, cid: ConvId.optional(), agent: SessionName.optional(),
+    /**
+     * `resend`: a request sent before the cut-over and held unanswered; it must be sent again. `outdated`: the recipient
+     * accepted it on a client before conversations, which cannot open the dm; they update, then it is sent again (§8.3).
+     */
+    state: z.enum(["held", "pending-delivery", "resend", "outdated"]),
+});
+export const ConvListParams = z.strictObject({ key: Key, filter: z.strictObject({ unread: z.boolean().optional(), mentions: z.boolean().optional(), kind: ConvKind.optional(), archived: z.boolean().optional() }).optional(), ...Page });
+export const ConvListResult = ConvPage;
+export const ConvReadParams = z.strictObject({ key: Key, ...Cid, thread: Ulid.optional(), before: Seq.optional(), after: Seq.optional(), around: Ulid.optional(), limit: Limit, cursor: Cursor })
+    .refine((p) => [p.before, p.after, p.around, p.cursor].filter((v) => v !== undefined).length <= 1, "choose one page position");
+export const ConvReadResult = z.union([EventPage, Hold]);
+export const ConvSendParams = z.strictObject({ key: Key, cid: ConvId.optional(), to: ParticipantId.optional(), ...LineFields, answer: Ulid.optional(), clientId: z.string().min(1).max(200) })
+    .refine((p) => (p.cid === undefined) !== (p.to === undefined), "choose exactly one of cid or to")
+    .refine((p) => p.broadcast !== true || p.thread !== undefined, "broadcast needs a thread");
+export const ConvSendResult = z.union([z.object({ cid: ConvId, id: Ulid, clientId: z.string().min(1).max(200), stage: z.literal("pending") }), Hold]);
+export const ConvSyncParams = z.strictObject({ key: Key, after: Seq.optional(), waitMs: z.number().int().min(0).max(25_000).optional(), limit: Limit });
+export const ConvSyncResult = z.object({ events: z.array(ConvStreamEvent).max(50), pos: Seq });
+export const ConvCreateParams = z.strictObject({ kind: z.enum(["dm", "group", "channel"]), participants: z.array(Seat).min(1).max(LIMITS.convParticipants), visibility: Visibility.optional(), history: HistoryPolicy, retainDays: z.number().int().min(1).max(LIMITS.retainDaysMax), meta: ConvMeta.optional() })
+    .refine((p) => p.kind !== "dm" || p.participants.length === 2, "a dm has exactly two participants")
+    .refine((p) => p.kind !== "group" || (p.participants.length >= 3 && p.participants.length <= LIMITS.groupParticipants), "a group has 3 to 50 participants")
+    .refine((p) => p.kind === "channel" || p.visibility === undefined, "only a channel has visibility");
+export const ConvSeatParams = z.strictObject({ ...Cid, p: ParticipantId, device: MachineId.optional(), respondTo: RespondTo.optional() })
+    .refine((p) => p.p.includes("/"), "a seat names an agent");
+export const PeopleGetParams = z.strictObject({ people: z.array(PersonId).min(1).max(100).refine((p) => new Set(p).size === p.length, "each person once") });
+export const PeopleGetResult = z.object({ people: z.array(PersonSummary).max(100), missing: z.array(PersonId).max(100) });
+/** Socket tiers are declared alongside this table below. */
+export const CONVERSATION_METHODS = {
+    "conv.list": Read(ConvListParams, ConvListResult),
+    "conv.get": Read(z.strictObject({ key: Key, ...Cid }), ConvView),
+    "conv.members": Read(PageParams, z.object({ participants: z.array(ParticipantView).max(50), cursor: Cursor })),
+    "conv.read": Read(ConvReadParams, ConvReadResult),
+    "conv.threads": Read(z.strictObject({ ...Cid, filter: z.enum(["all", "unread", "following"]).optional(), ...Page }), EventPage),
+    "conv.send": { params: ConvSendParams, result: ConvSendResult, errors: WriteErrors },
+    "conv.react": Write(z.strictObject({ key: Key, ...Id, reaction: z.string().min(1).max(64), on: z.boolean() })),
+    "conv.edit": Write(z.strictObject({ key: Key, ...Id, text: Text, mentions: z.array(Mention).max(LIMITS.mentions).optional() })),
+    "conv.delete": Write(z.strictObject({ key: Key, ...Id })),
+    "conv.pin": Write(z.strictObject({ ...Id, on: z.boolean() })),
+    "conv.create": { params: ConvCreateParams, result: z.object({ cid: ConvId }), errors: WriteErrors },
+    "conv.add": Write(z.strictObject({ ...Cid, participants: z.array(Seat).min(1).max(LIMITS.convOpParticipants) })),
+    "conv.remove": Write(z.strictObject({ ...Cid, participants: z.array(ParticipantId).min(1).max(LIMITS.convOpParticipants) })),
+    "conv.role": Write(z.strictObject({ ...Cid, p: ParticipantId, role: ConvRole })),
+    "conv.seat": Write(ConvSeatParams),
+    "conv.settings": Write(z.strictObject({ ...Cid, ...OptionalSettings }).refine((p) => Object.values(p).some((v, i) => i > 0 && v !== undefined), "set at least one setting")),
+    "conv.meta": Write(z.strictObject({ ...Cid, meta: ConvMeta })),
+    "conv.archive": Write(z.strictObject({ ...Cid, on: z.boolean() })),
+    "conv.leave": Write(z.strictObject(Cid)),
+    "conv.join": Write(z.strictObject(Cid)),
+    "conv.accept": Write(z.strictObject(Cid)),
+    "conv.catalogue": Read(z.strictObject({ query: z.string().max(200).optional(), limit: Limit }), z.object({ channels: z.array(z.object({ cid: ConvId, name: z.string().max(80), topic: z.string().max(250).optional(), purpose: z.string().max(250).optional(), participants: Count })).max(50) })),
+    "conv.publish": Write(z.strictObject({ ...Cid, on: z.boolean() })),
+    "conv.markRead": Write(z.strictObject({ ...Cid, upTo: Seq, thread: Ulid.optional() })),
+    "conv.markUnread": Write(z.strictObject({ ...Cid, from: z.number().int().positive().safe() })),
+    "conv.prefs": Write(z.strictObject({ ...Cid, notify: z.enum(["all", "mentions", "none"]), muteUntil: Millis.optional(), receipts: z.boolean().optional(), typing: z.boolean().optional() })),
+    "conv.follow": Write(z.strictObject({ ...Cid, thread: Ulid, on: z.boolean() })),
+    "conv.save": Write(z.strictObject({ ...Id, on: z.boolean() })),
+    "conv.saved": Read(PageParams, EventPage),
+    "conv.draft": Write(z.strictObject({ ...Cid, thread: Ulid.optional(), text: z.string().max(8000) })),
+    "conv.schedule": { params: z.strictObject({ ...Cid, ...LineFields, at: Millis, clientId: z.string().min(1).max(200) }), result: z.object({ id: Ulid }), errors: WriteErrors },
+    "conv.scheduled": Read(z.strictObject(Page), z.object({ items: z.array(z.object({ id: Ulid, cid: ConvId, at: Millis, text: Text })).max(50), cursor: Cursor })),
+    "conv.unschedule": Write(z.strictObject({ id: Ulid })),
+    "conv.typing": Write(z.strictObject({ ...Cid, thread: Ulid.optional() })),
+    "conv.search": Read(z.strictObject({ key: Key, query: z.string().min(1).max(200), cid: ConvId.optional(), from: ParticipantId.optional(), after: Millis.optional(), before: Millis.optional(), thread: Ulid.optional(), has: z.enum(["file", "link"]).optional(), ...Page }), z.union([EventPage, Hold])),
+    "conv.context": Read(z.strictObject({ key: Key, ...Cid, event: Ulid, before: z.number().int().min(0).max(20).optional(), after: z.number().int().min(0).max(20).optional() }), z.union([z.object({ events: z.array(EventView).max(41), root: EventView.optional() }), Hold])),
+    "conv.access": Read(z.strictObject({ key: SessionKey, cid: ConvId.optional(), ...Page }), z.object({ conversations: z.array(z.object({ conv: ConvView, reason: z.enum(["seat", "allow", "ask"]), lookbackDays: z.number().int().positive().max(LIMITS.retainDaysMax), indexedFrom: Millis.optional(), complete: z.boolean() })).max(50), cursor: Cursor })),
+    "context.get": Read(Empty, z.object({ rules: ContextRules, defaults: ContextRules, effective: z.array(z.object({ agent: SessionName, cid: ConvId, access: ContextAccess })).max(500) })),
+    "context.set": Write(z.strictObject({ rules: ContextRules })),
+    "context.set.preview": Read(z.strictObject({ rules: ContextRules }), z.object({ changes: z.array(z.object({ agent: SessionName, cid: ConvId, from: ContextAccess, to: ContextAccess })).max(500) })),
+    "conv.policy": Write(z.strictObject({ ...Cid, agentContext: AgentContext })),
+    "conv.localRetention": Write(z.strictObject({ ...Cid, days: z.number().int().min(1).max(LIMITS.retainDaysMax) })),
+    "conv.backfill": { params: z.strictObject(Cid), result: z.object({ indexedFrom: Millis.optional(), complete: z.boolean() }), errors: WriteErrors },
+    "file.get": Read(z.strictObject({ ...Cid, blob: z.string().regex(/^b_[A-Za-z0-9_-]{43}$/), offset: Count.optional(), limit: z.number().int().min(1).max(512 * 1024).optional() }), z.object({ data: z.string().regex(/^[A-Za-z0-9+/]*={0,2}$/).max(699_052), offset: Count, more: z.boolean(), mime: z.string().max(100), name: z.string().max(255) })),
+    "session.activity": Write(z.strictObject({ key: SessionKey, body: ActivityBody })),
+    "turn.cancel": Write(z.strictObject({ device: MachineId, session: SessionName, turn: Ulid.optional() })),
+    "conv.sync": Read(ConvSyncParams, ConvSyncResult),
+    "people.get": Read(PeopleGetParams, PeopleGetResult),
+    "sessions.list": Read(Empty, z.object({ sessions: z.array(z.object({ agent: SessionName, state: z.enum(["idle", "busy", "kept"]), seats: z.array(ConvId) })) })),
+    "request.waiting": Read(z.strictObject(Page), z.object({ items: z.array(WaitingOnThemView).max(50), cursor: Cursor })),
+};
+/** Staged contracts have no live handler or socket tier until their owning lane ships. */
+export const STAGED_CONVERSATION_METHODS = [
+    "conv.catalogue", "conv.publish", "conv.markRead", "conv.markUnread", "conv.prefs", "conv.follow",
+    "conv.save", "conv.saved", "conv.draft", "conv.schedule", "conv.scheduled", "conv.unschedule", "conv.typing",
+    "context.get", "context.set", "context.set.preview", "conv.localRetention", "file.get", "session.activity", "turn.cancel",
+];
+export const LIVE_CONVERSATION_METHODS = Object.fromEntries(Object.entries(CONVERSATION_METHODS)
+    .filter(([name]) => !STAGED_CONVERSATION_METHODS.includes(name)));
+/** agent means both sockets, human means admin socket only. session.activity is runtime-only, not a model tool. */
+export const CONVERSATION_TIERS = {
+    "conv.list": "agent", "conv.get": "human", "conv.members": "human", "conv.read": "agent", "conv.threads": "human", "conv.send": "agent",
+    "conv.react": "agent", "conv.edit": "agent", "conv.delete": "agent", "conv.pin": "human", "conv.create": "human", "conv.add": "human",
+    "conv.remove": "human", "conv.role": "human", "conv.seat": "human", "conv.settings": "human", "conv.meta": "human", "conv.archive": "human",
+    "conv.leave": "human", "conv.join": "human", "conv.accept": "human", "conv.catalogue": "human", "conv.publish": "human", "conv.markRead": "human",
+    "conv.markUnread": "human", "conv.prefs": "human", "conv.follow": "human", "conv.save": "human", "conv.saved": "human", "conv.draft": "human",
+    "conv.schedule": "human", "conv.scheduled": "human", "conv.unschedule": "human", "conv.typing": "human", "conv.search": "agent", "conv.context": "agent",
+    "conv.access": "agent", "context.get": "human", "context.set": "human", "context.set.preview": "human", "conv.policy": "human", "conv.localRetention": "human",
+    "conv.backfill": "human", "file.get": "human", "session.activity": "agent", "turn.cancel": "human", "conv.sync": "agent", "people.get": "human", "request.waiting": "human", "sessions.list": "human",
+};

package/dist/lib/modules/core/schema/ipc/device.js

@@ -52,6 +52,8 @@ export const DeviceChangeView = z.object({
     approver: MachineLabel.optional(),
     at: Millis,
 });
+/** A presence feature name, such as `tasks`, `conversations` or `reach`. */
+export const PresenceFeature = z.string().regex(/^[a-z][a-z0-9-]{0,31}$/, "a feature name");
 /** One device of this device's person. */
 export const DeviceListEntry = z.object({
     device: MachineId,
@@ -67,9 +69,16 @@ export const DeviceListEntry = z.object({
     via: z.enum(["host", "browser"]).optional(),
     current: z.boolean(),
     self: z.boolean(),
+    /** This local Jelly host has no attached person window. Unknown remote presence is omitted. */
+    away: z.literal(true).optional(),
     since: Millis.optional(),
     /** For a removed device of a directory realm: when, why and by which device. */
     unbound: z.object({ at: Millis, reason: UnbindReason, by: MachineId }).optional(),
+    /**
+     * The protocol features the device advertises (spec §8.2, "Devices"): this device's own, or the last verified presence
+     * of another device of the person. Absent when no presence of it has been seen, which is unknown, not none.
+     */
+    features: z.array(PresenceFeature).max(32).optional(),
 });
 /** A link request's text (`messaging-link.…`, spec §15.3): what a new device shows and its person's device reads. */
 const LinkText = z.string().min(1).max(2048);

package/dist/lib/modules/core/schema/ipc/jelly.js

@@ -2,8 +2,7 @@
  * The IPC methods a Jelly host needs (spec §8.2, §8.11; design §13.6, §13.10-§13.12), served in every deployment:
  *
  * - Agent tier: `daemon.health`, a cheap status with no secrets and no counts.
- * - Human tier: `agents.list` and `agents.read` (the person's view of their own agents' traffic on this device),
- *   `notice.subscribe`, `notice.list` and `notice.ack` (notices in fixed categories), and the read-only preview
+ * - Human tier: `notice.subscribe`, `notice.list` and `notice.ack` (notices in fixed categories), and the read-only preview
  *   `device.remove.preview`.
  *
  * Spread into `IPC_METHODS`; `HOST_SCOPE_METHODS` (in `ipc.ts`) is what a host-scope action grant allows.
@@ -14,11 +13,10 @@ import { WAKE_AGENTS, WAKE_TICKET_BYTES, WakeUrl } from "../directory-frames.js"
 import { Jws } from "../jelly.js";
 import { DeviceKind } from "../directory.js";
 import { DeviceChangeView, DeviceRemoveParams } from "./device.js";
-import { ConvCursor, ConvEntry } from "./shapes.js";
-import { ConversationRef } from "./surfaces.js";
 /**
- * A notice's id, stable per source: `m_<line id>` (a line), `r_<request id>` (a held request), `a_<id>` (an alert).
- * A replay repeats the same ids, so a host rings once.
+ * A notice's id, stable per source: `m_<line id>` (a line), `m_task<task id>` (a task another person's agent asked of
+ * one of this person's agents), `r_<request id>` (a held request), `a_<id>` (an alert). A replay repeats the same ids, so
+ * a host rings once.
  */
 export const NoticeId = z.string().regex(/^[mra]_[0-9A-Za-z]{1,64}$/, "notice id");
 /** Most characters of a notice's `line`. */
@@ -37,23 +35,26 @@ export const NoticeDevice = DeviceChangeView.extend({
     remove: z.enum(["token", "sign-in", "team"]).optional(),
 });
 /**
- * One notice (design §13.11). `message`: a line in a DM or a channel from another person or their agent, or an
- * agent's line to its own person; `request`: a request held for the person; `alert`: an alarm of this device, a
- * change of the person's other devices (with `device`), or trust the person gave that ends within 7 days (with `from`).
+ * One notice (design §13.11). `message`: a line in a DM or a channel from another person or their agent, an
+ * agent's line to its own person, or a task another person's agent asked of one of this person's agents (with `key`
+ * `task:<task id>`, and `from` that person), never a request: it waits on the agent, not the person; `request`: a request
+ * held for the person (an ask held for consent stays one); `alert`: an alarm of this device, a change of the person's
+ * other devices (with `device`), or trust the person gave that ends within 7 days (with `from`).
  * `line` is the first line of a message, through `cleanPeerText`, only when the caller asked for lines; alerts carry
  * fixed text. `from.name` and `from.email` are untrusted text in a hosted realm.
  */
 export const Notice = z.object({
     id: NoticeId,
     category: z.enum(["message", "request", "alert"]),
-    conversation: ConversationRef.optional(),
     from: z.object({ name: z.string().max(200), email: z.string().max(320).optional(), org: z.enum(["same", "other", "none"]) }).optional(),
     line: z.string().max(NOTICE_LINE_CHARS).optional(),
     device: NoticeDevice.optional(),
+    /** Where a host opens it in its section: `task:<task id>` for a task notice; absent for the others. */
+    key: z.string().regex(/^task:[0-9A-HJKMNP-TV-Z]{26}$/, "task:<task id>").optional(),
     at: Millis,
 });
-/** What the person's badges count: unread lines in their conversations, and requests held for them. */
-export const NoticeCounts = z.object({ unread: z.number().int().nonnegative(), requests: z.number().int().nonnegative() });
+/** What the person's badges count: requests held for them. Conversation read state remains staged. */
+export const NoticeCounts = z.object({ requests: z.number().int().nonnegative() });
 /** `daemon.health` (spec §8.2): the daemon's state, with no secrets and no counts. */
 export const DaemonHealth = z.object({
     state: z.enum(["starting", "running", "stopping"]),
@@ -66,43 +67,12 @@ export const DaemonHealth = z.object({
     version: z.string().max(64),
     storeSchema: z.number().int().positive(),
 });
-/** One local agent (a registered or kept session) and its traffic on this device. */
-export const AgentSummary = z.object({
-    agent: SessionName,
-    /** Other agents it has mail or tasks with. */
-    conversations: z.number().int().nonnegative(),
-    /** Mail it received and has not read. */
-    unread: z.number().int().nonnegative(),
-    lastAt: Millis.optional(),
-    state: z.enum(["idle", "busy", "kept"]),
-});
-const AgentConversation = z.object({ conversation: ConversationRef, unread: z.number().int().nonnegative(), lastAt: Millis });
 export const JELLY_METHODS = {
     /**
      * Agent tier. A cheap status for a host that polls: the daemon's state, the relay, the directory, an alarm, and
      * whether it is busy. No counts: they are the person's (`notice.list`).
      */
     "daemon.health": { params: z.strictObject({}), result: DaemonHealth },
-    /** Human tier. This person's local agents on this device, most recent first. Read-only. */
-    "agents.list": { params: z.strictObject({}), result: z.object({ agents: z.array(AgentSummary) }) },
-    /**
-     * Human tier. One local agent's traffic: without `conversation`, the other agents it has mail or tasks with, most
-     * recent first; with `conversation` (`agent:<person>/<agent>`), a page of its entries, as `conv.read` gives them to
-     * the agent, latest first unless `before` names an entry. Changes no stage and sends no receipt. Peer text is
-     * untrusted: a client cleans it for display.
-     */
-    "agents.read": {
-        params: z.strictObject({
-            agent: SessionName,
-            conversation: ConversationRef.refine((c) => c.startsWith("agent:"), { message: "a conversation with an agent: agent:<person>/<agent>" }).optional(),
-            before: ConvCursor.optional(),
-            limit: z.number().int().min(1).max(100).optional(),
-        }),
-        result: z.discriminatedUnion("kind", [
-            z.object({ kind: z.literal("conversations"), conversations: z.array(AgentConversation) }),
-            z.object({ kind: z.literal("entries"), conversation: ConversationRef, entries: z.array(ConvEntry), more: z.boolean() }),
-        ]),
-    },
     /**
      * Human tier; host scope in `deployment: "jelly"`. Replays the unacknowledged notices after `after` (all of them
      * without it), oldest first, as `notice` events on this connection, then sends each new one. With `lines`, a
@@ -137,7 +107,9 @@ export const JELLY_METHODS = {
      * whose own person's mail may wake the host, and the tasks those sessions await (their unfinished requests). The relay
      * presents the ticket once, for such traffic only, while this device is offline (spec §7, "Wake tickets"). `relay`:
      * `armed` once the relay holds it, `pending` while it is not connected (it is sent at the next connection);
-     * `awaiting`: how many task requests the relay may wake for. A directory realm only.
+     * `awaiting`: how many task requests the relay may wake for; `dms`: how many dms the relay may wake for, those whose
+     * other person shares a channel with this person and is not blocked or muted (spec §8.11, "Wake tickets"). A
+     * directory realm only.
      */
     "wake.arm": {
         params: z.strictObject({
@@ -145,7 +117,7 @@ export const JELLY_METHODS = {
             ticket: Jws.refine((ticket) => ticket.length <= WAKE_TICKET_BYTES, { message: `at most ${WAKE_TICKET_BYTES} bytes` }),
             agents: z.array(SessionName).max(WAKE_AGENTS),
         }),
-        result: z.object({ relay: z.enum(["armed", "pending"]), awaiting: z.number().int().nonnegative() }),
+        result: z.object({ relay: z.enum(["armed", "pending"]), awaiting: z.number().int().nonnegative(), dms: z.number().int().nonnegative() }),
     },
     /** Admin tier; host scope in `deployment: "jelly"`. The relay forgets this device's wake ticket (`pending` until connected). */
     "wake.disarm": { params: z.strictObject({}), result: z.object({ relay: z.enum(["disarmed", "pending"]) }) },

package/dist/lib/modules/core/schema/ipc/shapes.js

@@ -5,12 +5,19 @@
  * imports `ipc.ts` (which spreads their tables).
  */
 import { z } from "../../../vendor/zod/index.js";
-import { Task, TaskState } from "../a2a.js";
+import { Task } from "../a2a.js";
+import { ConvId, ParticipantId } from "../conversation.js";
 import { AgentKind, DeliveryStage, DeliveryTier, MachineId, MachineLabel, Millis, PersonId, SessionAddress, SessionName, SessionState, Ulid, LIMITS, } from "../common.js";
 import { DelegationSummary } from "../delegation.js";
 import { ErrorCode } from "../errors.js";
 /** Opaque, client-chosen session key, stable for the life of a client session, e.g. "opencode:<sessionID>". */
 export const SessionKey = z.string().min(1).max(200);
+/**
+ * A source-issued action token (spec §8.2, "Action tokens"): 32 random bytes, base64url. The daemon mints one per
+ * action, item and human-tier view, keeps it in memory only, and spends it at its first presentation. Opaque to
+ * clients; never logged.
+ */
+export const ActionToken = z.string().regex(/^[A-Za-z0-9_-]{43}$/, "action token");
 /**
  * When the recipient will likely see a message (spec §8.2): a hint from its machine's last presence
  * at send time, never a promise.
@@ -41,42 +48,10 @@ export const DirectoryEntry = z.object({
     self: z.boolean().describe("true for sessions registered on this machine"),
     /**
      * When a message sent to this session now, with the wake hint set, would likely be seen: the
-     * same `SendExpect` a `msg.send` result carries (spec §8.2). Absent when no presence lists it.
+     * same `SendExpect` a task send result carries (spec §8.2). Absent when no presence lists it.
      */
     expect: SendExpect.optional(),
 });
-/** Chat text, at most `LIMITS.chatChars` UTF-16 code units (`max` would count code points). */
-export const ChatText = z.string().refine((text) => text.length <= LIMITS.chatChars, { message: `at most ${LIMITS.chatChars} UTF-16 code units` });
-/**
- * A position in this machine's chat order (spec §6.8): every filed line and every chat change takes
- * the next one. Local: another machine numbers the same line differently. 0 is before the first.
- */
-export const ChatSeq = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
-/** One transcript line (spec §6.8). `id` is the line's `messageId`, the same on every machine. */
-export const ChatLine = z.object({
-    id: Ulid,
-    /** This machine's filing order of the line: the cursor for `conv.read` paging and `conv.markRead`. */
-    seq: ChatSeq,
-    at: Millis,
-    person: PersonId,
-    /** The sending agent, when an agent posted it; absent on the person's own line. */
-    agent: SessionName.optional(),
-    direction: z.enum(["in", "out"]),
-    body: ChatText,
-    /** The `id` of the thread's first line; absent on a first line. */
-    thread: Ulid.optional(),
-    /**
-     * On a line this machine sent to other persons (spec §6.8): `sent` until every person has a
-     * delivered copy, `delivered` then, `refused` once some person's every copy was rejected or expired.
-     * `held` while every person still to deliver it holds it for their person to answer: a message request
-     * waiting to be accepted (spec §6.9).
-     */
-    state: z.enum(["sent", "held", "delivered", "refused"]).optional(),
-    /** With `refused`: the persons whose every copy was rejected or expired. */
-    refused: z.array(PersonId).max(LIMITS.channelPersons).optional(),
-    /** A line this daemon wrote about a channel change or a refusal of one; its text is the daemon's, never a peer's. */
-    notice: z.literal(true).optional(),
-});
 /** The other end of an item or a task: a person's device and, when an agent wrote it, the agent. */
 export const PeerRef = z.object({
     address: SessionAddress,
@@ -86,9 +61,12 @@ export const PeerRef = z.object({
     label: MachineLabel,
 });
 export const InboxItem = z.object({
-    id: Ulid.describe("envelope id"),
+    id: Ulid.describe("task envelope id, or conversation event id"),
     key: SessionKey,
-    from: PeerRef,
+    from: PeerRef.extend({ address: z.union([SessionAddress, ParticipantId]), device: MachineId.optional(), label: MachineLabel.optional() }),
+    /** A projected line is addressed by this pair. Task envelopes have neither field. */
+    cid: ConvId.optional(),
+    eventId: Ulid.optional(),
     kind: z.enum(["message", "task"]),
     messageId: z.string().min(1).max(128),
     taskId: Ulid.optional(),
@@ -108,10 +86,11 @@ export const InboxItem = z.object({
      * Absent only on items stored before consent.
      */
     consent: z.enum(["self", "guarded", "trusted"]).optional(),
-});
+}).refine((item) => item.cid !== undefined
+    ? item.eventId === item.id && item.kind === "message" && item.taskId === undefined
+    : item.eventId === undefined && PeerRef.safeParse(item.from).success, "a projected line has a matching cid/eventId; an envelope has device provenance");
 /**
- * A message this side sent to continue a task it requested (`msg.send` with `kind: "message"`
- * and the `taskId`), and how far it got, from this daemon's own delivery records (spec §6.3).
+ * A task continuation and its stage from this daemon's own delivery records (spec §6.3).
  */
 export const TaskFollowUp = z.object({
     envelopeId: Ulid,
@@ -121,7 +100,18 @@ export const TaskFollowUp = z.object({
     /** When it reached `stage`. */
     at: Millis,
 });
-export const TaskRecord = z.object({
+/** Most characters of `TaskRecord.signIn.tool`: the executor's words, cleaned and capped like a preview. */
+export const TASK_SIGN_IN_TOOL_CHARS = LIMITS.previewChars;
+/** Most characters of `TaskRecord.refusal.reason`: the executor's words, cleaned and capped like a message request. */
+export const TASK_REFUSAL_CHARS = LIMITS.requestChars;
+/** An id a host's engine chose for its session or its pending approval or question: an opaque, plain identifier. */
+export const HostLocalId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/, "a plain identifier of at most 200 characters");
+/**
+ * The executor host's own pending approval or question that an `AUTH_REQUIRED` or `INPUT_REQUIRED` task waits on
+ * (spec §8.2, "The task view"): set by the person's own client with `task.question`, held in this daemon's memory only.
+ */
+export const TaskQuestion = z.strictObject({ sessionId: HostLocalId, approvalId: HostLocalId });
+const TaskRecordFields = z.object({
     task: Task.extend({ id: Ulid }),
     role: z.enum(["requester", "executor"]),
     key: SessionKey.describe("local session that owns this side of the task"),
@@ -136,12 +126,53 @@ export const TaskRecord = z.object({
      * Absent when there are none.
      */
     followUps: z.array(TaskFollowUp).min(1).max(LIMITS.taskFollowUps).optional(),
+    // ---- the task view (spec §8.2, "The task view"): computed by this daemon as it projects the record; never stored or sent ----
+    /** The counterpart agent: the session the verified envelopes name (`peer.agent`). */
+    agent: SessionName.optional(),
+    /**
+     * The counterpart agent's person: `peer.person` and the display name the realm verified for it (the person id when
+     * the realm cannot name them). Never parsed from an agent's name. Absent while this daemon has not named them yet.
+     */
+    person: z.object({ id: PersonId, name: z.string().max(200) }).optional(),
+    /** That person's relation to this device's person, as `ParticipantView.org` computes it; absent with `person`. */
+    org: z.enum(["same", "other", "none"]).optional(),
+    /**
+     * `AUTH_REQUIRED` only. `by`: `you` when the executor is an agent of this device's person, else `them`, computed here,
+     * never read from the peer. `tool`: the tool the executor named (`metadata[URI.signIn]` of its status message), as
+     * plain text cleaned and capped at `TASK_SIGN_IN_TOOL_CHARS`; absent when it named none.
+     */
+    signIn: z.object({ tool: z.string().min(1).max(TASK_SIGN_IN_TOOL_CHARS).optional(), by: z.enum(["you", "them"]) }).optional(),
+    /** `REJECTED` only, when the executor gave words: its status message's text, cleaned and capped at `TASK_REFUSAL_CHARS`. */
+    refusal: z.object({ reason: z.string().min(1).max(TASK_REFUSAL_CHARS) }).optional(),
+    /**
+     * The executor's side, on the admin socket only (human tier), in `AUTH_REQUIRED` or `INPUT_REQUIRED`: the host's own
+     * approval or question the task waits on (`task.question`). Never on the agent tier, never sent to the peer.
+     */
+    question: TaskQuestion.optional(),
 });
+/** The task view's fields go with the states they belong to (spec §8.2, "The task view"). */
+function taskViewRules(schema) {
+    return schema
+        .refine((r) => r.signIn === undefined || r.task.status.state === "TASK_STATE_AUTH_REQUIRED", "signIn is for an AUTH_REQUIRED task")
+        .refine((r) => r.refusal === undefined || r.task.status.state === "TASK_STATE_REJECTED", "refusal is for a REJECTED task")
+        .refine((r) => r.question === undefined || (r.role === "executor" && (r.task.status.state === "TASK_STATE_AUTH_REQUIRED" || r.task.status.state === "TASK_STATE_INPUT_REQUIRED")), "question is for the executor's side of an AUTH_REQUIRED or INPUT_REQUIRED task");
+}
+export const TaskRecord = taskViewRules(TaskRecordFields);
+/**
+ * One side of a task one of this person's agents on this device is in, as the person's own clients see it (spec §8.2,
+ * "The person's tasks"): the task view without the session key (a bearer credential), with `session` the agent's name
+ * and, on the requester side of a task that has not ended, J2's `cancel` action minted for this view.
+ */
+export const PersonTask = taskViewRules(TaskRecordFields.omit({ key: true }).extend({
+    /** Never present: a session key is a bearer credential for its session. */
+    key: z.never().optional(),
+    session: SessionName.describe("this person's agent on this device that holds this side of the task"),
+    cancel: z.strictObject({ name: z.literal("cancel"), token: ActionToken }).optional(),
+})).refine((r) => r.cancel === undefined || r.role === "requester", "cancel is for the requester side");
 /**
- * Where a send went (`msg.send`, spec §8.2): an agent session `person/agent@label`, a person (a line
- * from an agent to them) or `#<channel>` (a post).
+ * Where a retained task envelope went: an agent session `person/agent@label`.
  */
-export const SendTarget = z.union([SessionAddress, PersonId, z.string().regex(/^#[a-z][a-z0-9-]{0,31}$/, "#<channel>")]);
+export const SendTarget = SessionAddress;
 export const SendResult = z.object({
     to: SendTarget,
     envelopeId: Ulid,
@@ -153,33 +184,3 @@ export const SendResult = z.object({
     /** Absent when the stage is `rejected` or `expired`, or when no presence lists the session. */
     expect: SendExpect.optional(),
 });
-/** A place in a conversation page (`conv.read`): an entry's time and id. */
-export const ConvCursor = z.strictObject({ at: Millis, id: Ulid });
-/**
- * One entry of a conversation between a local session and one other session (spec §8.2
- * `conv.read`): mail either way, or a task either way. `text` is untrusted peer text for incoming
- * mail and for a task the other side asked for; clients frame it as data.
- */
-export const ConvEntry = z.object({
-    /** The envelope id (mail) or the task id (task). */
-    id: Ulid,
-    kind: z.enum(["mail", "task"]),
-    /** `in`: from the other session (mail it sent, a task it asked this session to run); `out`: the reverse. */
-    direction: z.enum(["in", "out"]),
-    /** The other session, as this machine knows it. */
-    peer: SessionAddress,
-    /** Mail: received (in) or sent (out). Task: created. */
-    at: Millis,
-    /**
-     * Incoming mail: its preview. Task: the start of its request. Absent on outgoing mail: the
-     * daemon keeps no copy of what it sent.
-     */
-    text: z.string().max(LIMITS.previewChars).optional(),
-    /** Mail that continues a task. */
-    taskId: Ulid.optional(),
-    /** Mail: its stage (incoming: this side's inbox stage; outgoing: how far it got). */
-    stage: DeliveryStage.optional(),
-    /** Task: this session's role and the task's state now. */
-    role: z.enum(["requester", "executor"]).optional(),
-    state: TaskState.optional(),
-});