@joe-broadhead/messaging 0.8.0 → 0.9.0

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

@@ -14,8 +14,9 @@ import { Jws } from "../jelly.js";
 import { DeviceKind } from "../directory.js";
 import { DeviceChangeView, DeviceRemoveParams } from "./device.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`. */
@@ -34,9 +35,11 @@ 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.
  */
@@ -46,6 +49,8 @@ export const Notice = z.object({
     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: requests held for them. Conversation read state remains staged. */
@@ -102,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({
@@ -110,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

@@ -12,6 +12,12 @@ 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.
@@ -94,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"),
@@ -109,7 +126,49 @@ 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 retained task envelope went: an agent session `person/agent@label`.
  */

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

@@ -23,7 +23,7 @@ import { DEVICE_METHODS, DeviceStatus, LoginPurpose } from "./ipc/device.js";
 import { Artifact, Message, Part, TaskState, TaskStatus } from "./a2a.js";
 import { AgentKind, DeliveryStage, DeliveryTier, EncKey, Hash, MachineId, MachineLabel, MemberRole, Millis, PersonId, PersonName, RelayUrl, SessionAddress, SessionName, SessionState, TeamId, TeamName, Ulid, LIMITS, } from "./common.js";
 import { ErrorCode } from "./errors.js";
-import { InboxItem, SessionKey, TaskRecord } from "./ipc/shapes.js";
+import { ActionToken, InboxItem, PersonTask, SessionKey, TASK_SIGN_IN_TOOL_CHARS, TaskQuestion, TaskRecord } from "./ipc/shapes.js";
 import { SURFACE_METHODS } from "./ipc/surfaces.js";
 import { Member } from "./roster.js";
 import { CONSENT_METHODS } from "./ipc/consent.js";
@@ -206,11 +206,53 @@ export const IPC_METHODS = {
             artifact: Artifact.optional(),
             append: z.boolean().optional(),
             lastChunk: z.boolean().optional(),
-        }),
+            /** With `TASK_STATE_AUTH_REQUIRED` only: the tool whose sign-in the task waits on (spec §6.2, "Sign-in"). */
+            signIn: z.strictObject({ tool: z.string().min(1).max(TASK_SIGN_IN_TOOL_CHARS) }).optional(),
+        }).refine((p) => p.signIn === undefined || p.state === "TASK_STATE_AUTH_REQUIRED", "signIn goes with TASK_STATE_AUTH_REQUIRED"),
         result: TaskRecord,
     },
+    /**
+     * Agent tier, from the executing session's runtime (never a model tool). Ties a task the session `key` runs (its
+     * executor side), in `AUTH_REQUIRED` or `INPUT_REQUIRED`, to the host's own pending approval or question it waits on;
+     * `question: null` unties it. `sessionId` must be the session's own, when its registration named one (`host`).
+     * Held in memory only, shown only to the person's own clients (admin socket, no key), never sent (spec §8.2).
+     */
+    "task.question": {
+        params: z.strictObject({ key: SessionKey, taskId: Ulid, question: TaskQuestion.nullable() }),
+        result: z.object({ ok: z.literal(true) }),
+    },
+    /**
+     * Human tier, admin socket only, no session key. The tasks this person's agents on this device are in, as requester
+     * or executor, across their sessions, most recently updated first: the person's task view (spec §8.2, "The person's
+     * tasks"). Never another person's tasks: this device holds only its own sessions' sides.
+     */
+    "tasks.list": {
+        params: z.strictObject({
+            role: z.enum(["requester", "executor"]).optional(),
+            state: TaskState.optional(),
+            session: SessionName.optional().describe("only this agent's tasks"),
+            cursor: z.string().min(1).max(200).optional().describe("opaque; from a previous nextCursor"),
+            limit: z.number().int().min(1).max(100).optional(),
+        }),
+        result: z.object({
+            tasks: z.array(PersonTask),
+            nextCursor: z.string().max(200).optional().describe("absent when there are no more pages"),
+            total: z.number().int().nonnegative(),
+        }),
+    },
+    /** Human tier. One side of a task of this person's agents; `role` when this device holds both sides. */
+    "tasks.get": {
+        params: z.strictObject({ taskId: Ulid, role: z.enum(["requester", "executor"]).optional() }),
+        result: PersonTask,
+    },
+    /**
+     * As the requester session (`key`), or, on the human tier, as the person with the task's `cancel` action (`token`,
+     * spec §8.2, "Action tokens"): exactly one of the two.
+     */
     "task.cancel": {
-        params: z.strictObject({ key: SessionKey, taskId: Ulid, reason: z.string().max(1000).optional() }),
+        params: z
+            .strictObject({ key: SessionKey.optional(), taskId: Ulid, reason: z.string().max(1000).optional(), token: ActionToken.optional() })
+            .refine((p) => (p.key === undefined) !== (p.token === undefined), "give exactly one of key or token"),
         result: TaskRecord,
     },
     "events.subscribe": { params: z.strictObject({ keys: z.array(SessionKey).min(1).max(256) }), result: Ok },
@@ -327,6 +369,7 @@ export const AGENT_METHODS = [
     "task.get",
     "task.update",
     "task.cancel",
+    "task.question",
 ];
 /**
  * The human tier (design §7.5): methods that act as the person, on `run/admin.sock` only: their
@@ -340,6 +383,9 @@ export const HUMAN_METHODS = [
     "grant.list",
     "grant.set",
     "grant.set.preview",
+    "reach.get",
+    "reach.set",
+    "reach.set.preview",
     "request.list",
     "request.answer",
     "request.answer.preview",
@@ -349,6 +395,8 @@ export const HUMAN_METHODS = [
     "notice.subscribe",
     "notice.list",
     "notice.ack",
+    "tasks.list",
+    "tasks.get",
     "device.approve.preview",
     "device.remove.preview",
     "identity.replace.preview",

package/dist/lib/modules/core/version.js

@@ -3,4 +3,4 @@
  * its IPC hello and a client compares it with its own (spec §8.2). A test keeps it equal to the
  * root package.json.
  */
-export const VERSION = "0.8.0";
+export const VERSION = "0.9.0";