@scp-dev/core 0.1.3 → 0.1.4

package/dist/index.d.ts

@@ -403,6 +403,9 @@ type MessageKind = "message" | "request" | "reply" | "status";
 type DataClass = "public" | "private";
 type Presence = "online" | "idle" | "offline";
 type StatusState = "working" | "waiting" | "blocked" | "done";
+/** how an idle agent is woken by a message: a channel push, the pi extension, the OpenCode plugin's waiter or codex app-server; `none` reads at its next turn */
+type Wake = "channels" | "pi" | "opencode-plugin" | "codex-app-server" | "none";
+declare const WAKES: readonly Wake[];
 type ActivityKind = "session_start" | "tool" | "stop" | "note" | "session_end";
 declare const ACTIVITY_KINDS: readonly ActivityKind[];
 interface ActivityRow {
@@ -438,8 +441,9 @@ interface Claim {
     exact?: boolean;
     /**
      * a hook's claim for an in-process subagent of the harness holding the claim's lineage endpoint: the broker places it under that endpoint,
-     * as `<its handle>-<type>-<first 6 of id>` with a session of its own, and only for a hook of that endpoint's own harness process. A stop's
-     * claim (`stop`) takes only an endpoint the subagent already has, else is refused not_found; any other claim of a done one resumes it working
+     * as `<its current handle>-<short type>-<first 4 of id>` (`gp` for general-purpose, else the type's first word) with a session of its own, and
+     * only for a hook of that endpoint's own harness process. A stop's claim (`stop`) takes only an endpoint the subagent already has, else is
+     * refused not_found; any other claim of a done one resumes it working
      */
     subagent?: {
         id: string;
@@ -567,6 +571,8 @@ interface EndpointView {
     scope?: ScopePreset | "custom";
     /** set only in a viewer's list, when that viewer may peek this endpoint */
     peekable?: PeekLevel;
+    /** an agent's: how an idle agent is woken by a message; null or `none`: it reads at its next turn */
+    wake?: Wake | null;
 }
 type PeekLevel = "local";
 interface PeekTurn {
@@ -737,7 +743,8 @@ interface SendResult {
     hop: number;
     /**
      * `queued`: the recipient is not connected now; `offline`: it has been gone past a short grace, so a client polling between waits is not
-     * offline; `state`: an agent recipient's {@link Reach} on this machine (an older broker leaves it out)
+     * offline; `state`: an agent recipient's {@link Reach} on this machine (an older broker leaves it out); `wake`: how it is woken, only when
+     * it can be; `idle`: its presence is idle
      */
     deliveries: {
         endpoint: string;
@@ -747,6 +754,8 @@ interface SendResult {
         queued?: boolean;
         last_seen: string | null;
         state?: Reach;
+        wake?: Wake;
+        idle?: true;
     }[];
     /** one line per agent recipient no live session holds: `queued: no live session holds <address>` */
     warnings?: string[];
@@ -1092,6 +1101,8 @@ interface EndpointRow {
     named: number | null;
     /** when the session itself or the human linked it under a parent by hand: a later root claim of it takes it back where it sits */
     linked: number | null;
+    /** how the session that holds the endpoint wakes it: a {@link Wake} other than none, or null */
+    wake: string | null;
 }
 interface MessageRow {
     id: string;
@@ -1148,6 +1159,8 @@ declare class RelayCore {
     private scopeDepth;
     /** while a scope world derives a node: what it already derived of ancestor lists and limits */
     private scopeMemo;
+    /** subagent titles from their parents' hooks, by `<parent id> <subagent id>`, until the subagent's first claim */
+    private readonly subagentTitles;
     private readonly deferred;
     constructor(sql: Sql, options: CoreOptions);
     /** a `machine` label naming this host by its hostname, as clients default it, names it by its machine name when one is set */
@@ -1317,6 +1330,29 @@ declare class RelayCore {
         transient?: boolean;
         process?: string;
     }): boolean;
+    /**
+     * how the session holding an agent endpoint wakes it when idle, one of {@link WAKES}; `none` clears it. Only the process holding the
+     * endpoint sets it through a hook; whether it changed
+     */
+    setWake(endpoint: string, value: unknown, options?: {
+        transient?: boolean;
+        process?: string;
+    }): boolean;
+    /**
+     * a title for the caller's in-process subagent `id` from the description its parent gave it; the subagent's endpoint id when it changed one.
+     * It fills only a title nobody set, as an inferred one, and waits for the subagent's claim when it has no endpoint yet
+     */
+    subagentTitle(endpoint: string, params: {
+        id?: unknown;
+        title?: unknown;
+    }, options?: {
+        transient?: boolean;
+        process?: string;
+    }): string | null;
+    /** the title a parent named subagent `id` with before it had an endpoint, given to `endpoint`; whether it changed its title */
+    private takeSubagentTitle;
+    /** an inferred title for an endpoint whose title nobody set */
+    private fillTitle;
     /**
      * a session joins on demand: its hook claim registers or takes back its endpoint, marked seen now even right after a leave, and `handle`,
      * when given, renames it in place ({@link rename}'s rules). Nothing is kept when the rename is refused
@@ -2089,12 +2125,16 @@ declare function steerNote(parent: string, key: string): string;
 declare function stripSteerNote(text: string): string;
 /** a send's recipient as a line shows it: offline only past the short grace, else queued while it is not connected */
 declare function deliveryText(d: Pick<SendResult["deliveries"][number], "address" | "offline" | "queued">): string;
-type Delivery = Pick<SendResult["deliveries"][number], "address" | "offline" | "queued" | "state">;
+type Delivery = Pick<SendResult["deliveries"][number], "address" | "offline" | "queued" | "state" | "wake" | "idle">;
 /**
  * a send's recipients as lines, one each, saying when each sees the message by its state, one without a state as {@link deliveryText}; none
  * when the broker named no state. With `late`, only those that will not see it at their next turn boundary
  */
 declare function reachLines(deliveries: Delivery[], late?: boolean): string[];
+/** an endpoint's presence as a line shows it: an idle agent no message wakes reads at its next turn */
+declare function presenceText(e: Pick<EndpointView, "kind" | "presence" | "wake">): string;
+/** an agent's wake as a column shows it, `turn` when it reads at its next turn; `-` for any other endpoint */
+declare function wakeText(e: Pick<EndpointView, "kind" | "wake">): string;
 /** a time, as ms or ISO, as `HH:MM:SS` in local time */
 declare function clock(at: number | string): string;
 /**
@@ -2452,4 +2492,4 @@ declare function sha256Hex(text: string): string;
 /** the UTF-8 byte length of text, the unit every byte limit counts in */
 declare function utf8Bytes(text: string): number;
 
-export { ACCOUNT_HANDLE, ACTIVITY_KINDS, type ActivityKind, type ActivityRow, type Admission, type AskResult, type Attachment, type AuditRow, BROKER_CAPABILITIES, type BreakerAdmission, CAPABILITIES, CLI_NAME, type Claim, type CoreOptions, type CrossAccountGate, type CrossAccountLink, DEFAULT_IMPLEMENTATION_PREFIXES, DEFAULT_JUDGE_BUDGET, DEFAULT_JUDGE_EFFORT, type DataClass, ERROR_CODES, type EndpointKind, type EndpointRow, type EndpointView, type Envelope, type ErrorCode, FakeJudgeClient, GONE_PREFIX, GROUP_NAME, type GateContext, type GateVerdict, HANDBACK_CUT, HUMAN_HANDLE, HttpJudgeClient, type HttpJudgeOptions, JUDGE_BREAKER_DEFAULTS, JUDGE_CATEGORIES, JUDGE_EFFORTS, JUDGE_FALLBACK_NOTE, JUDGE_MAX_OUTPUT_TOKENS, JUDGE_PROMPT_VERSION, JUDGE_PROVIDERS, JUDGE_VERDICTS, type JudgeAuditDetail, type JudgeAuditEvent, type JudgeBoundary, JudgeBreaker, type JudgeBreakerOptions, type JudgeBudget, type JudgeCategory, type JudgeClient, type JudgeContext, type JudgeEffort, type JudgeHeld, type JudgeModelConfig, type JudgePolicy, type JudgeProvider, JudgeProviderError, type JudgeRedacted, type JudgeSide, type JudgeStats, type JudgeVerdict, LIMITS, MESSAGE_KINDS, type MessageKind, type MessageReceipts, type MessageRow, OMITTED, PASS_GATE, PEEK, PREAMBLE, PREAMBLE_BRIEF, PRESET_LISTS, PROTOCOL, type PeekLevel, type PeekResult, type PeekSeen, type PeekState, type PeekTurn, type PeerView, type PiiHit, type Policy, type PolicyDefaults, type PolicyGroup, type PolicyRule, type PolicySubject, type Prefiltered, type Presence, REDACTION_KINDS, type Reach, type Redaction, RelayCore, RelayError, type RunJudgeInput, SCOPE_PRESETS, SERVER_FIELDS, SHORT_ID, STATUS_STATES, SYSTEM_HANDLE, type ScopeActor, type ScopeCap, type ScopeCaps, type ScopeChange, type ScopeDecision, type ScopeDirection, type ScopeEntry, type ScopeGroupIdentity, type ScopeGroupRules, type ScopeList, type ScopeNode, type ScopePolicyCap, type ScopePreset, type ScopeRules, type ScopeSubject, type ScopeView, type ScopeWorld, type SecretScanner, type Selector, type SendParams, type SendResult, type Sql, type SqlValue, type StatusState, type StopNudge, type StopWaitResult, TITLE_CHARS, type ThreadMessage, type Verdict, VerdictCache, type WhyResult, type XAllow, type XContact, XCounters, type XDelivered, type XEnvelopeFrom, XLIMITS, type XLimitConfig, type XLimits, type XListed, type XMessage, type XRelease, admits, allowlisted, applyRedactions, canonicalPolicy, cleanLabels, cleanText, clip, clipPasses, clipped, clock, collapseTools, createSecretScanner, crossFleet, dayStart, declaredLimits, deliveryText, digestText, dropQuoted, effectiveSelector, expandRules, findPii, findSecret, gateRefusal, groupCapKey, handbackOutput, hasScope, honestSender, isLeaving, joinRedacted, judgeBoundary, judgeDetailForAgents, judgeFellBack, judgeModel, judgePrompt, keepLast, leavesFleet, matches, mergeVerdicts, narrower, newId, newJudgeStats, one, parseJudgePolicy, parsePolicy, parseVerdict, parseXMessage, peekLevel, policyRefusal, prefilter, presetOf, randomHex, reachLines, readText, receiptLines, redactPii, redactSecrets, redactionKind, relation, relationText, replyGrant, runJudge, sameSecret, scopeDecision, scopeLists, seqList, setImplementationPrefixes, sha256Hex, shortId, steerNote, stripControl, stripRelaySpans, stripSteerNote, unreachable, untilTomorrow, utf8Bytes, validHandle, validHarness, validSelector, widenText, wrapMessage, wrapPeek, xlimits };
+export { ACCOUNT_HANDLE, ACTIVITY_KINDS, type ActivityKind, type ActivityRow, type Admission, type AskResult, type Attachment, type AuditRow, BROKER_CAPABILITIES, type BreakerAdmission, CAPABILITIES, CLI_NAME, type Claim, type CoreOptions, type CrossAccountGate, type CrossAccountLink, DEFAULT_IMPLEMENTATION_PREFIXES, DEFAULT_JUDGE_BUDGET, DEFAULT_JUDGE_EFFORT, type DataClass, ERROR_CODES, type EndpointKind, type EndpointRow, type EndpointView, type Envelope, type ErrorCode, FakeJudgeClient, GONE_PREFIX, GROUP_NAME, type GateContext, type GateVerdict, HANDBACK_CUT, HUMAN_HANDLE, HttpJudgeClient, type HttpJudgeOptions, JUDGE_BREAKER_DEFAULTS, JUDGE_CATEGORIES, JUDGE_EFFORTS, JUDGE_FALLBACK_NOTE, JUDGE_MAX_OUTPUT_TOKENS, JUDGE_PROMPT_VERSION, JUDGE_PROVIDERS, JUDGE_VERDICTS, type JudgeAuditDetail, type JudgeAuditEvent, type JudgeBoundary, JudgeBreaker, type JudgeBreakerOptions, type JudgeBudget, type JudgeCategory, type JudgeClient, type JudgeContext, type JudgeEffort, type JudgeHeld, type JudgeModelConfig, type JudgePolicy, type JudgeProvider, JudgeProviderError, type JudgeRedacted, type JudgeSide, type JudgeStats, type JudgeVerdict, LIMITS, MESSAGE_KINDS, type MessageKind, type MessageReceipts, type MessageRow, OMITTED, PASS_GATE, PEEK, PREAMBLE, PREAMBLE_BRIEF, PRESET_LISTS, PROTOCOL, type PeekLevel, type PeekResult, type PeekSeen, type PeekState, type PeekTurn, type PeerView, type PiiHit, type Policy, type PolicyDefaults, type PolicyGroup, type PolicyRule, type PolicySubject, type Prefiltered, type Presence, REDACTION_KINDS, type Reach, type Redaction, RelayCore, RelayError, type RunJudgeInput, SCOPE_PRESETS, SERVER_FIELDS, SHORT_ID, STATUS_STATES, SYSTEM_HANDLE, type ScopeActor, type ScopeCap, type ScopeCaps, type ScopeChange, type ScopeDecision, type ScopeDirection, type ScopeEntry, type ScopeGroupIdentity, type ScopeGroupRules, type ScopeList, type ScopeNode, type ScopePolicyCap, type ScopePreset, type ScopeRules, type ScopeSubject, type ScopeView, type ScopeWorld, type SecretScanner, type Selector, type SendParams, type SendResult, type Sql, type SqlValue, type StatusState, type StopNudge, type StopWaitResult, TITLE_CHARS, type ThreadMessage, type Verdict, VerdictCache, WAKES, type Wake, type WhyResult, type XAllow, type XContact, XCounters, type XDelivered, type XEnvelopeFrom, XLIMITS, type XLimitConfig, type XLimits, type XListed, type XMessage, type XRelease, admits, allowlisted, applyRedactions, canonicalPolicy, cleanLabels, cleanText, clip, clipPasses, clipped, clock, collapseTools, createSecretScanner, crossFleet, dayStart, declaredLimits, deliveryText, digestText, dropQuoted, effectiveSelector, expandRules, findPii, findSecret, gateRefusal, groupCapKey, handbackOutput, hasScope, honestSender, isLeaving, joinRedacted, judgeBoundary, judgeDetailForAgents, judgeFellBack, judgeModel, judgePrompt, keepLast, leavesFleet, matches, mergeVerdicts, narrower, newId, newJudgeStats, one, parseJudgePolicy, parsePolicy, parseVerdict, parseXMessage, peekLevel, policyRefusal, prefilter, presenceText, presetOf, randomHex, reachLines, readText, receiptLines, redactPii, redactSecrets, redactionKind, relation, relationText, replyGrant, runJudge, sameSecret, scopeDecision, scopeLists, seqList, setImplementationPrefixes, sha256Hex, shortId, steerNote, stripControl, stripRelaySpans, stripSteerNote, unreachable, untilTomorrow, utf8Bytes, validHandle, validHarness, validSelector, wakeText, widenText, wrapMessage, wrapPeek, xlimits };

package/dist/index.js

@@ -179,6 +179,7 @@ var RelayError = class extends Error {
   retryAfterS;
   detail;
 };
+var WAKES = ["channels", "pi", "opencode-plugin", "codex-app-server", "none"];
 var ACTIVITY_KINDS = ["session_start", "tool", "stop", "note", "session_end"];
 var MESSAGE_KINDS = ["message", "request", "reply", "status"];
 var STATUS_STATES = ["working", "waiting", "blocked", "done"];
@@ -876,9 +877,20 @@ var REACH_TEXT = {
   offline: "offline; it will not see this unless it comes back",
   starting: "not joined yet; it is handed over when the worker starts"
 };
+function reachText(d) {
+  if (d.state !== "running" || !d.idle) return REACH_TEXT[d.state];
+  return d.wake && d.wake !== "none" ? "delivered; waking it" : "delivered; it sees this at its next turn";
+}
 function reachLines(deliveries, late = false) {
   if (!deliveries.some((d) => d.state)) return [];
-  return deliveries.filter((d) => !late || d.state && d.state !== "running").map((d) => d.state ? `${d.address}: ${REACH_TEXT[d.state]}` : deliveryText(d));
+  return deliveries.filter((d) => !late || d.state && d.state !== "running").map((d) => d.state ? `${d.address}: ${reachText({ ...d, state: d.state })}` : deliveryText(d));
+}
+function presenceText(e) {
+  return e.kind === "agent" && e.presence === "idle" && (!e.wake || e.wake === "none") ? "idle (next turn)" : e.presence;
+}
+function wakeText(e) {
+  if (e.kind !== "agent") return "-";
+  return e.wake && e.wake !== "none" ? e.wake : "turn";
 }
 var pad = (n) => String(n).padStart(2, "0");
 function clock(at) {
@@ -1277,6 +1289,8 @@ var RelayCore = class {
   scopeDepth = 0;
   /** while a scope world derives a node: what it already derived of ancestor lists and limits */
   scopeMemo = null;
+  /** subagent titles from their parents' hooks, by `<parent id> <subagent id>`, until the subagent's first claim */
+  subagentTitles = /* @__PURE__ */ new Map();
   deferred = /* @__PURE__ */ new WeakMap();
   /** a `machine` label naming this host by its hostname, as clients default it, names it by its machine name when one is set */
   machineLabel(labels) {
@@ -1320,7 +1334,8 @@ var RelayCore = class {
       ["title_turn", "INTEGER"],
       ["tldr_turn", "INTEGER"],
       ["named", "INTEGER"],
-      ["linked", "INTEGER"]
+      ["linked", "INTEGER"],
+      ["wake", "TEXT"]
     ]) {
       if (!endpointColumns.includes(column)) this.sql.all(`ALTER TABLE endpoints ADD COLUMN ${column} ${type}`);
     }
@@ -1513,9 +1528,9 @@ var RelayCore = class {
         );
         if (subagent.stop && !had) throw new RelayError("not_found", "that subagent has no endpoint: it never ran a tool");
         const claimed = this.claimRow(scope.handle, harness, fields, true, scope);
-        if (subagent.stop || !one(this.sql, `UPDATE endpoints SET status_state = 'working' WHERE id = ? AND status_state = 'done' RETURNING id`, claimed.endpoint.id)) {
-          return { ...claimed, subagent: true };
-        }
+        const titled = this.takeSubagentTitle(root.id, subagent.id, claimed.endpoint.id);
+        const resumed = !subagent.stop && one(this.sql, `UPDATE endpoints SET status_state = 'working' WHERE id = ? AND status_state = 'done' RETURNING id`, claimed.endpoint.id);
+        if (!titled && !resumed) return { ...claimed, subagent: true };
         return { ...claimed, endpoint: this.view(this.byId(claimed.endpoint.id)), subagent: true };
       }
       const bound = scope.grant === null && !scope.exact ? this.boundGrant(scope, fields.process) : void 0;
@@ -1639,7 +1654,7 @@ var RelayCore = class {
         this.sql.all(`INSERT INTO endpoints (id, handle, kind, harness, labels, created_at) VALUES (?, ?, 'agent', ?, '{}', ?)`, id, handle, harness, now);
         row = this.byId(id);
         created = true;
-      } else if (held.kind === "agent" && held.connections === 0 && presenceOf(held, now) === "offline" && held.harness === harness && held.id !== scope.subagent?.root) {
+      } else if (held.kind === "agent" && held.connections === 0 && presenceOf(held, now) === "offline" && held.harness === harness && held.id !== scope.subagent?.root && !(scope.subagent && held.session?.startsWith("sub:") && held.session !== fields.session)) {
         own = transient && held.process !== null && fields.process !== null && sameHarness(held.process, fields.process);
         const ended = held.hook_ended !== null || (held.last_seen ?? held.created_at) < now - LIMITS.restartGraceS * 1e3;
         if ((!transient || own || ended) && (this.restarts(held, this.placement(scope, now).parent, fields.process) || this.redeems(held, scope, { harness, ...fields })))
@@ -1748,10 +1763,10 @@ var RelayCore = class {
     this.sql.all(`UPDATE admins SET revoked_at = ? WHERE subject = ? AND revoked_at IS NULL`, now, row.id);
     const caps = this.capsOf(this.byId(row.id)).caps.filter((cap) => kind === "process" || cap.by === "human").map((cap) => ({ ...cap, sels: cap.sels.filter((entry) => entry.via === void 0 || entry.via === cap.by) }));
     const stored = caps.length ? JSON.stringify({ caps, allow: {} }) : null;
-    if (kind === "process") this.sql.all(`UPDATE endpoints SET caps = ?, reset_at = ?, peek = NULL WHERE id = ?`, stored, now, row.id);
+    if (kind === "process") this.sql.all(`UPDATE endpoints SET caps = ?, reset_at = ?, peek = NULL, wake = NULL WHERE id = ?`, stored, now, row.id);
     else
       this.sql.all(
-        `UPDATE endpoints SET rules = NULL, caps = ?, status_state = NULL, status_note = NULL, title = NULL, reset_at = ?, spawned_at = ?, peek = NULL, harness_session = NULL WHERE id = ?`,
+        `UPDATE endpoints SET rules = NULL, caps = ?, status_state = NULL, status_note = NULL, title = NULL, reset_at = ?, spawned_at = ?, peek = NULL, harness_session = NULL, wake = NULL WHERE id = ?`,
         stored,
         now,
         now,
@@ -2121,8 +2136,8 @@ var RelayCore = class {
     if (typeof params.text !== "string") throw new RelayError("invalid_params", "text must be a string");
     const row = this.mustEndpoint(endpoint);
     if (row.kind !== "agent" || !this.holds(row, options)) return false;
-    const title = stripControl(redactSecrets(params.text.slice(0, 4096).replace(/\s+/g, " ").trim())).slice(0, TITLE_CHARS).trim();
-    if (!title || findSecret(title) || title === row.title) return false;
+    const title = hookTitle(params.text);
+    if (!title || title === row.title) return false;
     if (row.title !== null && row.title !== row.title_auto) return false;
     const turn = row.prompts ?? 0;
     if (params.from === "prompt" && row.title !== null) return false;
@@ -2130,6 +2145,66 @@ var RelayCore = class {
     this.sql.all(`UPDATE endpoints SET title = ?, title_auto = ?, title_turn = ? WHERE id = ?`, title, title, params.from === "summary" ? turn : null, endpoint);
     return true;
   }
+  /**
+   * how the session holding an agent endpoint wakes it when idle, one of {@link WAKES}; `none` clears it. Only the process holding the
+   * endpoint sets it through a hook; whether it changed
+   */
+  setWake(endpoint, value, options = {}) {
+    if (typeof value !== "string" || !WAKES.includes(value)) throw new RelayError("invalid_params", `via must be one of ${WAKES.join(", ")}`);
+    const row = this.mustEndpoint(endpoint);
+    if (row.kind !== "agent") throw new RelayError("invalid_params", "only an agent endpoint wakes");
+    if (!this.holds(row, options)) return false;
+    const wake = value === "none" ? null : value;
+    if (row.wake === wake) return false;
+    this.sql.all(`UPDATE endpoints SET wake = ? WHERE id = ?`, wake, endpoint);
+    return true;
+  }
+  /**
+   * a title for the caller's in-process subagent `id` from the description its parent gave it; the subagent's endpoint id when it changed one.
+   * It fills only a title nobody set, as an inferred one, and waits for the subagent's claim when it has no endpoint yet
+   */
+  subagentTitle(endpoint, params, options = {}) {
+    if (typeof params.id !== "string" || !SUBAGENT_ID.test(params.id)) throw new RelayError("invalid_params", "id is the subagent's id");
+    if (typeof params.title !== "string") throw new RelayError("invalid_params", "title must be a string");
+    const row = this.mustEndpoint(endpoint);
+    const title = hookTitle(params.title);
+    if (row.kind !== "agent" || !this.holds(row, options) || !title) return null;
+    const prefix = `sub:${params.id}:`;
+    const sub = one(
+      this.sql,
+      `SELECT id FROM endpoints WHERE kind = 'agent' AND parent_ep = ? AND substr(session, 1, ?) = ? ORDER BY COALESCE(last_seen, created_at) DESC LIMIT 1`,
+      row.id,
+      prefix.length,
+      prefix
+    );
+    if (sub) return this.fillTitle(sub.id, title) ? sub.id : null;
+    const key = `${row.id} ${params.id}`;
+    this.subagentTitles.delete(key);
+    this.subagentTitles.set(key, title);
+    for (const old of this.subagentTitles.keys()) {
+      if (this.subagentTitles.size <= SUBAGENT_TITLES_KEPT) break;
+      this.subagentTitles.delete(old);
+    }
+    return null;
+  }
+  /** the title a parent named subagent `id` with before it had an endpoint, given to `endpoint`; whether it changed its title */
+  takeSubagentTitle(root, id, endpoint) {
+    const title = this.subagentTitles.get(`${root} ${id}`);
+    if (title === void 0) return false;
+    this.subagentTitles.delete(`${root} ${id}`);
+    return this.fillTitle(endpoint, title);
+  }
+  /** an inferred title for an endpoint whose title nobody set */
+  fillTitle(endpoint, title) {
+    return one(
+      this.sql,
+      `UPDATE endpoints SET title = ?, title_auto = ?, title_turn = NULL WHERE id = ? AND (title IS NULL OR title = title_auto) AND title IS NOT ? RETURNING id`,
+      title,
+      title,
+      endpoint,
+      title
+    ) !== void 0;
+  }
   /**
    * a session joins on demand: its hook claim registers or takes back its endpoint, marked seen now even right after a leave, and `handle`,
    * when given, renames it in place ({@link rename}'s rules). Nothing is kept when the rename is refused
@@ -2317,7 +2392,7 @@ var RelayCore = class {
         const parent = this.byId(target.parent_ep);
         throw new RelayError("scope_refused", `spawned by ${parent ? this.address(parent) : "another agent"}; a spawned worker stays joined while it runs`);
       }
-      this.sql.all(`UPDATE endpoints SET session = NULL, token_hash = NULL, hook_seen = NULL, hook_ended = ? WHERE id = ?`, this.now(), target.id);
+      this.sql.all(`UPDATE endpoints SET session = NULL, token_hash = NULL, hook_seen = NULL, hook_ended = ?, wake = NULL WHERE id = ?`, this.now(), target.id);
       this.audit("leave", target.id, null, { handle: target.handle });
       return { endpoint: this.whoami(target.id), session: target.session };
     });
@@ -2598,7 +2673,9 @@ var RelayCore = class {
           offline,
           ...queued ? { queued } : {},
           last_seen: view.last_seen,
-          ...state ? { state } : {}
+          ...state ? { state } : {},
+          ...view.wake ? { wake: view.wake } : {},
+          ...view.presence === "idle" ? { idle: true } : {}
         });
       }
       for (const { key, address } of pending) {
@@ -5309,7 +5386,7 @@ ${stderr}` : "";
       presence,
       status: row.status_state ? { state: row.status_state, note: row.status_note ?? "" } : null,
       last_seen: iso(row.last_seen),
-      ...row.kind === "agent" ? this.placeView(row, shown) : {}
+      ...row.kind === "agent" ? { ...this.placeView(row, shown), wake: wakeOf(row) } : {}
     };
   }
   placeView(row, shown) {
@@ -5493,24 +5570,36 @@ function sameProcess(row, key) {
   if (row.connections > 0 || key === null || row.process === null) return false;
   return row.token_hash === null ? sameHarness(row.process, key) : row.process === key && PROCESS_KEY.test(key);
 }
+var SUBAGENT_ID = /^(?=.*[A-Za-z0-9])[A-Za-z0-9_-]{1,64}$/;
+var SUBAGENT_TITLES_KEPT = 256;
+function hookTitle(text) {
+  const title = stripControl(redactSecrets(text.slice(0, 4096).replace(/\s+/g, " ").trim())).slice(0, TITLE_CHARS).trim();
+  return title && !findSecret(title) ? title : null;
+}
 function subagentOf(value) {
   if (value === void 0 || value === null) return void 0;
   const { id, type, stop } = typeof value === "object" ? value : {};
-  if (typeof id !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(id) || !/[A-Za-z0-9]/.test(id))
-    throw new RelayError("invalid_params", "subagent is {id, type}: id letters, digits, _ and -");
+  if (typeof id !== "string" || !SUBAGENT_ID.test(id)) throw new RelayError("invalid_params", "subagent is {id, type}: id letters, digits, _ and -");
   if (type !== void 0 && (typeof type !== "string" || type.length > 64))
     throw new RelayError("invalid_params", "subagent type is a name of at most 64 characters");
   if (stop !== void 0 && typeof stop !== "boolean") throw new RelayError("invalid_params", "subagent stop is true or false");
   return { id, ...type ? { type } : {}, ...stop ? { stop: true } : {} };
 }
+function subagentKind(type) {
+  if (type?.toLowerCase() === "general-purpose") return "gp";
+  const word = (type ?? "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).find(Boolean);
+  return word ? word.toLowerCase().slice(0, 16) : "agent";
+}
 function subagentHandle(root, subagent) {
-  const kind = (subagent.type ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+/, "").slice(0, 16).replace(/-+$/, "") || "agent";
-  const tail = `-${kind}-${subagent.id.toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 6)}`;
+  const tail = `-${subagentKind(subagent.type)}-${subagent.id.toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 4)}`;
   return `${root.slice(0, 58 - tail.length).replace(/[-.]+$/, "")}${tail}`;
 }
 function sameHarness(a, b) {
   return a === b || BARE_PID_KEY.test(a) && b.startsWith(`${a}:`) || BARE_PID_KEY.test(b) && a.startsWith(`${b}:`);
 }
+function wakeOf(row) {
+  return row.wake && row.wake !== "none" && WAKES.includes(row.wake) ? row.wake : null;
+}
 function presenceOf(row, now) {
   if (row.connections > 0) return (row.last_seen ?? 0) >= now - LIMITS.onlineWithinS * 1e3 ? "online" : "idle";
   if (!row.hook_seen) return "offline";
@@ -6332,6 +6421,7 @@ export {
   SYSTEM_HANDLE,
   TITLE_CHARS,
   VerdictCache,
+  WAKES,
   XCounters,
   XLIMITS,
   admits,
@@ -6383,6 +6473,7 @@ export {
   peekLevel,
   policyRefusal,
   prefilter,
+  presenceText,
   presetOf,
   randomHex,
   reachLines,
@@ -6412,6 +6503,7 @@ export {
   validHandle,
   validHarness,
   validSelector,
+  wakeText,
   widenText,
   wrapMessage,
   wrapPeek,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/core",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Swarm Communication Protocol core: wire types, framing, scopes, policy, judge and the relay core.",
   "license": "Apache-2.0",
   "homepage": "https://scp.dev",

package/src/core.ts

@@ -40,6 +40,8 @@ import {
   type ThreadMessage,
   validHandle,
   validHarness,
+  type Wake,
+  WAKES,
   type WhyResult,
 } from "./protocol"
 import { digestText, PEEK, peekLevel, readText } from "./peek"
@@ -258,6 +260,8 @@ export interface EndpointRow {
   named: number | null
   /** when the session itself or the human linked it under a parent by hand: a later root claim of it takes it back where it sits */
   linked: number | null
+  /** how the session that holds the endpoint wakes it: a {@link Wake} other than none, or null */
+  wake: string | null
 }
 
 export interface MessageRow {
@@ -462,6 +466,8 @@ export class RelayCore {
   private scopeDepth = 0
   /** while a scope world derives a node: what it already derived of ancestor lists and limits */
   private scopeMemo: { ancestors: Map<string, string[]>; limited: Map<string, boolean> } | null = null
+  /** subagent titles from their parents' hooks, by `<parent id> <subagent id>`, until the subagent's first claim */
+  private readonly subagentTitles = new Map<string, string>()
   private readonly deferred = new WeakMap<RelayError, { endpoint: string | null; detail: Record<string, unknown> }>()
 
   constructor(
@@ -523,6 +529,7 @@ export class RelayCore {
       ["tldr_turn", "INTEGER"],
       ["named", "INTEGER"],
       ["linked", "INTEGER"],
+      ["wake", "TEXT"],
     ] as const) {
       if (!endpointColumns.includes(column)) this.sql.all(`ALTER TABLE endpoints ADD COLUMN ${column} ${type}`)
     }
@@ -721,12 +728,11 @@ export class RelayCore {
         )
         if (subagent.stop && !had) throw new RelayError("not_found", "that subagent has no endpoint: it never ran a tool")
         const claimed = this.claimRow(scope.handle, harness, fields, true, scope)
-        if (
-          subagent.stop ||
-          !one(this.sql, `UPDATE endpoints SET status_state = 'working' WHERE id = ? AND status_state = 'done' RETURNING id`, claimed.endpoint.id)
-        ) {
-          return { ...claimed, subagent: true as const }
-        }
+        const titled = this.takeSubagentTitle(root.id, subagent.id, claimed.endpoint.id)
+        const resumed =
+          !subagent.stop &&
+          one(this.sql, `UPDATE endpoints SET status_state = 'working' WHERE id = ? AND status_state = 'done' RETURNING id`, claimed.endpoint.id)
+        if (!titled && !resumed) return { ...claimed, subagent: true as const }
         return { ...claimed, endpoint: this.view(this.byId(claimed.endpoint.id)!), subagent: true as const }
       }
       const bound = scope.grant === null && !scope.exact ? this.boundGrant(scope, fields.process) : undefined
@@ -876,7 +882,8 @@ export class RelayCore {
         held.connections === 0 &&
         presenceOf(held, now) === "offline" &&
         held.harness === harness &&
-        held.id !== scope.subagent?.root
+        held.id !== scope.subagent?.root &&
+        !(scope.subagent && held.session?.startsWith("sub:") && held.session !== fields.session)
       ) {
         own = transient && held.process !== null && fields.process !== null && sameHarness(held.process, fields.process)
         const ended = held.hook_ended !== null || (held.last_seen ?? held.created_at) < now - LIMITS.restartGraceS * 1000
@@ -1004,10 +1011,10 @@ export class RelayCore {
       .caps.filter((cap) => kind === "process" || cap.by === "human")
       .map((cap) => ({ ...cap, sels: cap.sels.filter((entry) => entry.via === undefined || entry.via === cap.by) }))
     const stored = caps.length ? JSON.stringify({ caps, allow: {} }) : null
-    if (kind === "process") this.sql.all(`UPDATE endpoints SET caps = ?, reset_at = ?, peek = NULL WHERE id = ?`, stored, now, row.id)
+    if (kind === "process") this.sql.all(`UPDATE endpoints SET caps = ?, reset_at = ?, peek = NULL, wake = NULL WHERE id = ?`, stored, now, row.id)
     else
       this.sql.all(
-        `UPDATE endpoints SET rules = NULL, caps = ?, status_state = NULL, status_note = NULL, title = NULL, reset_at = ?, spawned_at = ?, peek = NULL, harness_session = NULL WHERE id = ?`,
+        `UPDATE endpoints SET rules = NULL, caps = ?, status_state = NULL, status_note = NULL, title = NULL, reset_at = ?, spawned_at = ?, peek = NULL, harness_session = NULL, wake = NULL WHERE id = ?`,
         stored,
         now,
         now,
@@ -1431,10 +1438,8 @@ export class RelayCore {
     if (typeof params.text !== "string") throw new RelayError("invalid_params", "text must be a string")
     const row = this.mustEndpoint(endpoint)
     if (row.kind !== "agent" || !this.holds(row, options)) return false
-    const title = stripControl(redactSecrets(params.text.slice(0, 4096).replace(/\s+/g, " ").trim()))
-      .slice(0, TITLE_CHARS)
-      .trim()
-    if (!title || findSecret(title) || title === row.title) return false
+    const title = hookTitle(params.text)
+    if (!title || title === row.title) return false
     if (row.title !== null && row.title !== row.title_auto) return false
     const turn = row.prompts ?? 0
     if (params.from === "prompt" && row.title !== null) return false
@@ -1443,6 +1448,72 @@ export class RelayCore {
     return true
   }
 
+  /**
+   * how the session holding an agent endpoint wakes it when idle, one of {@link WAKES}; `none` clears it. Only the process holding the
+   * endpoint sets it through a hook; whether it changed
+   */
+  setWake(endpoint: string, value: unknown, options: { transient?: boolean; process?: string } = {}): boolean {
+    if (typeof value !== "string" || !WAKES.includes(value as Wake)) throw new RelayError("invalid_params", `via must be one of ${WAKES.join(", ")}`)
+    const row = this.mustEndpoint(endpoint)
+    if (row.kind !== "agent") throw new RelayError("invalid_params", "only an agent endpoint wakes")
+    if (!this.holds(row, options)) return false
+    const wake = value === "none" ? null : value
+    if (row.wake === wake) return false
+    this.sql.all(`UPDATE endpoints SET wake = ? WHERE id = ?`, wake, endpoint)
+    return true
+  }
+
+  /**
+   * a title for the caller's in-process subagent `id` from the description its parent gave it; the subagent's endpoint id when it changed one.
+   * It fills only a title nobody set, as an inferred one, and waits for the subagent's claim when it has no endpoint yet
+   */
+  subagentTitle(endpoint: string, params: { id?: unknown; title?: unknown }, options: { transient?: boolean; process?: string } = {}): string | null {
+    if (typeof params.id !== "string" || !SUBAGENT_ID.test(params.id)) throw new RelayError("invalid_params", "id is the subagent's id")
+    if (typeof params.title !== "string") throw new RelayError("invalid_params", "title must be a string")
+    const row = this.mustEndpoint(endpoint)
+    const title = hookTitle(params.title)
+    if (row.kind !== "agent" || !this.holds(row, options) || !title) return null
+    const prefix = `sub:${params.id}:`
+    const sub = one<{ id: string }>(
+      this.sql,
+      `SELECT id FROM endpoints WHERE kind = 'agent' AND parent_ep = ? AND substr(session, 1, ?) = ? ORDER BY COALESCE(last_seen, created_at) DESC LIMIT 1`,
+      row.id,
+      prefix.length,
+      prefix,
+    )
+    if (sub) return this.fillTitle(sub.id, title) ? sub.id : null
+    const key = `${row.id} ${params.id}`
+    this.subagentTitles.delete(key)
+    this.subagentTitles.set(key, title)
+    for (const old of this.subagentTitles.keys()) {
+      if (this.subagentTitles.size <= SUBAGENT_TITLES_KEPT) break
+      this.subagentTitles.delete(old)
+    }
+    return null
+  }
+
+  /** the title a parent named subagent `id` with before it had an endpoint, given to `endpoint`; whether it changed its title */
+  private takeSubagentTitle(root: string, id: string, endpoint: string): boolean {
+    const title = this.subagentTitles.get(`${root} ${id}`)
+    if (title === undefined) return false
+    this.subagentTitles.delete(`${root} ${id}`)
+    return this.fillTitle(endpoint, title)
+  }
+
+  /** an inferred title for an endpoint whose title nobody set */
+  private fillTitle(endpoint: string, title: string): boolean {
+    return (
+      one(
+        this.sql,
+        `UPDATE endpoints SET title = ?, title_auto = ?, title_turn = NULL WHERE id = ? AND (title IS NULL OR title = title_auto) AND title IS NOT ? RETURNING id`,
+        title,
+        title,
+        endpoint,
+        title,
+      ) !== undefined
+    )
+  }
+
   /**
    * a session joins on demand: its hook claim registers or takes back its endpoint, marked seen now even right after a leave, and `handle`,
    * when given, renames it in place ({@link rename}'s rules). Nothing is kept when the rename is refused
@@ -1636,7 +1707,7 @@ export class RelayCore {
         const parent = this.byId(target.parent_ep)
         throw new RelayError("scope_refused", `spawned by ${parent ? this.address(parent) : "another agent"}; a spawned worker stays joined while it runs`)
       }
-      this.sql.all(`UPDATE endpoints SET session = NULL, token_hash = NULL, hook_seen = NULL, hook_ended = ? WHERE id = ?`, this.now(), target.id)
+      this.sql.all(`UPDATE endpoints SET session = NULL, token_hash = NULL, hook_seen = NULL, hook_ended = ?, wake = NULL WHERE id = ?`, this.now(), target.id)
       this.audit("leave", target.id, null, { handle: target.handle })
       return { endpoint: this.whoami(target.id), session: target.session }
     })
@@ -1939,6 +2010,8 @@ export class RelayCore {
           ...(queued ? { queued } : {}),
           last_seen: view.last_seen,
           ...(state ? { state } : {}),
+          ...(view.wake ? { wake: view.wake } : {}),
+          ...(view.presence === "idle" ? { idle: true as const } : {}),
         })
       }
       for (const { key, address } of pending) {
@@ -5014,7 +5087,7 @@ export class RelayCore {
       presence,
       status: row.status_state ? { state: row.status_state, note: row.status_note ?? "" } : null,
       last_seen: iso(row.last_seen),
-      ...(row.kind === "agent" ? this.placeView(row, shown) : {}),
+      ...(row.kind === "agent" ? { ...this.placeView(row, shown), wake: wakeOf(row) } : {}),
     }
   }
 
@@ -5242,31 +5315,44 @@ function sameProcess(row: EndpointRow, key: string | null): boolean {
   return row.token_hash === null ? sameHarness(row.process, key) : row.process === key && PROCESS_KEY.test(key)
 }
 
+const SUBAGENT_ID = /^(?=.*[A-Za-z0-9])[A-Za-z0-9_-]{1,64}$/
+const SUBAGENT_TITLES_KEPT = 256
+
+/** a title a hook offers: one line of at most the cap, credentials redacted; null when nothing is left or it still looks like a credential */
+function hookTitle(text: string): string | null {
+  const title = stripControl(redactSecrets(text.slice(0, 4096).replace(/\s+/g, " ").trim()))
+    .slice(0, TITLE_CHARS)
+    .trim()
+  return title && !findSecret(title) ? title : null
+}
+
 /** a claim's subagent: an id of letters, digits, `_` and `-` (Claude Code's are hex), an optional type, and `stop` for its stop's claim */
 function subagentOf(value: unknown): { id: string; type?: string; stop?: true } | undefined {
   if (value === undefined || value === null) return undefined
   const { id, type, stop } = (typeof value === "object" ? value : {}) as { id?: unknown; type?: unknown; stop?: unknown }
-  if (typeof id !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(id) || !/[A-Za-z0-9]/.test(id))
-    throw new RelayError("invalid_params", "subagent is {id, type}: id letters, digits, _ and -")
+  if (typeof id !== "string" || !SUBAGENT_ID.test(id)) throw new RelayError("invalid_params", "subagent is {id, type}: id letters, digits, _ and -")
   if (type !== undefined && (typeof type !== "string" || type.length > 64))
     throw new RelayError("invalid_params", "subagent type is a name of at most 64 characters")
   if (stop !== undefined && typeof stop !== "boolean") throw new RelayError("invalid_params", "subagent stop is true or false")
   return { id, ...(type ? { type } : {}), ...(stop ? { stop: true as const } : {}) }
 }
 
-/** `<root handle>-<type>-<first 6 of id>`, the root's part clipped so the whole leaves room for a `-<n>` suffix */
+/** a subagent type's short name: `gp` for general-purpose, else its first word (split at non-alphanumerics and camelCase humps) lowercased, `agent` for none */
+function subagentKind(type: string | undefined): string {
+  if (type?.toLowerCase() === "general-purpose") return "gp"
+  const word = (type ?? "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[^A-Za-z0-9]+/)
+    .find(Boolean)
+  return word ? word.toLowerCase().slice(0, 16) : "agent"
+}
+
+/** `<root handle>-<short type>-<first 4 alphanumerics of id>`, the root's part clipped so the whole leaves room for a `-<n>` suffix */
 export function subagentHandle(root: string, subagent: { id: string; type?: string }): string {
-  const kind =
-    (subagent.type ?? "")
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, "-")
-      .replace(/^-+/, "")
-      .slice(0, 16)
-      .replace(/-+$/, "") || "agent"
-  const tail = `-${kind}-${subagent.id
+  const tail = `-${subagentKind(subagent.type)}-${subagent.id
     .toLowerCase()
     .replace(/[^a-z0-9]/g, "")
-    .slice(0, 6)}`
+    .slice(0, 4)}`
   return `${root.slice(0, 58 - tail.length).replace(/[-.]+$/, "")}${tail}`
 }
 
@@ -5275,6 +5361,11 @@ function sameHarness(a: string, b: string): boolean {
   return a === b || (BARE_PID_KEY.test(a) && b.startsWith(`${a}:`)) || (BARE_PID_KEY.test(b) && a.startsWith(`${b}:`))
 }
 
+/** a row's stored wake when it is a known one other than `none` */
+function wakeOf(row: EndpointRow): Wake | null {
+  return row.wake && row.wake !== "none" && WAKES.includes(row.wake as Wake) ? (row.wake as Wake) : null
+}
+
 /** a connection's presence by its last request; without one, a hook's by the last time a hook reported */
 function presenceOf(row: EndpointRow, now: number): Presence {
   if (row.connections > 0) return (row.last_seen ?? 0) >= now - LIMITS.onlineWithinS * 1000 ? "online" : "idle"

package/src/index.ts

@@ -22,6 +22,7 @@ export {
   deliveryText,
   PREAMBLE,
   PREAMBLE_BRIEF,
+  presenceText,
   reachLines,
   receiptLines,
   SHORT_ID,
@@ -29,6 +30,7 @@ export {
   steerNote,
   stripControl,
   stripSteerNote,
+  wakeText,
   widenText,
   wrapMessage,
   wrapPeek,

package/src/protocol.ts

@@ -111,6 +111,9 @@ export type MessageKind = "message" | "request" | "reply" | "status"
 export type DataClass = "public" | "private"
 export type Presence = "online" | "idle" | "offline"
 export type StatusState = "working" | "waiting" | "blocked" | "done"
+/** how an idle agent is woken by a message: a channel push, the pi extension, the OpenCode plugin's waiter or codex app-server; `none` reads at its next turn */
+export type Wake = "channels" | "pi" | "opencode-plugin" | "codex-app-server" | "none"
+export const WAKES: readonly Wake[] = ["channels", "pi", "opencode-plugin", "codex-app-server", "none"]
 
 export type ActivityKind = "session_start" | "tool" | "stop" | "note" | "session_end"
 export const ACTIVITY_KINDS: readonly ActivityKind[] = ["session_start", "tool", "stop", "note", "session_end"]
@@ -160,8 +163,9 @@ export interface Claim {
   exact?: boolean
   /**
    * a hook's claim for an in-process subagent of the harness holding the claim's lineage endpoint: the broker places it under that endpoint,
-   * as `<its handle>-<type>-<first 6 of id>` with a session of its own, and only for a hook of that endpoint's own harness process. A stop's
-   * claim (`stop`) takes only an endpoint the subagent already has, else is refused not_found; any other claim of a done one resumes it working
+   * as `<its current handle>-<short type>-<first 4 of id>` (`gp` for general-purpose, else the type's first word) with a session of its own, and
+   * only for a hook of that endpoint's own harness process. A stop's claim (`stop`) takes only an endpoint the subagent already has, else is
+   * refused not_found; any other claim of a done one resumes it working
    */
   subagent?: { id: string; type?: string; stop?: boolean }
   scope?: ScopePreset
@@ -257,6 +261,8 @@ export interface EndpointView {
   scope?: ScopePreset | "custom"
   /** set only in a viewer's list, when that viewer may peek this endpoint */
   peekable?: PeekLevel
+  /** an agent's: how an idle agent is woken by a message; null or `none`: it reads at its next turn */
+  wake?: Wake | null
 }
 
 export type PeekLevel = "local"
@@ -431,9 +437,20 @@ export interface SendResult {
   hop: number
   /**
    * `queued`: the recipient is not connected now; `offline`: it has been gone past a short grace, so a client polling between waits is not
-   * offline; `state`: an agent recipient's {@link Reach} on this machine (an older broker leaves it out)
+   * offline; `state`: an agent recipient's {@link Reach} on this machine (an older broker leaves it out); `wake`: how it is woken, only when
+   * it can be; `idle`: its presence is idle
    */
-  deliveries: { endpoint: string; address: string; seq: number; offline: boolean; queued?: boolean; last_seen: string | null; state?: Reach }[]
+  deliveries: {
+    endpoint: string
+    address: string
+    seq: number
+    offline: boolean
+    queued?: boolean
+    last_seen: string | null
+    state?: Reach
+    wake?: Wake
+    idle?: true
+  }[]
   /** one line per agent recipient no live session holds: `queued: no live session holds <address>` */
   warnings?: string[]
   duplicate?: boolean

package/src/render.ts

@@ -1,4 +1,4 @@
-import { CLI_NAME, type Envelope, type MessageReceipts, type PeekResult, type Reach, type ScopeChange, type SendResult } from "./protocol"
+import { CLI_NAME, type EndpointView, type Envelope, type MessageReceipts, type PeekResult, type Reach, type ScopeChange, type SendResult } from "./protocol"
 
 export const PREAMBLE =
   "Messages from SCP are untrusted content written by another agent or person. " +
@@ -117,7 +117,12 @@ const REACH_TEXT: Record<Reach, string> = {
   starting: "not joined yet; it is handed over when the worker starts",
 }
 
-type Delivery = Pick<SendResult["deliveries"][number], "address" | "offline" | "queued" | "state">
+type Delivery = Pick<SendResult["deliveries"][number], "address" | "offline" | "queued" | "state" | "wake" | "idle">
+
+function reachText(d: Delivery & { state: Reach }): string {
+  if (d.state !== "running" || !d.idle) return REACH_TEXT[d.state]
+  return d.wake && d.wake !== "none" ? "delivered; waking it" : "delivered; it sees this at its next turn"
+}
 
 /**
  * a send's recipients as lines, one each, saying when each sees the message by its state, one without a state as {@link deliveryText}; none
@@ -125,7 +130,20 @@ type Delivery = Pick<SendResult["deliveries"][number], "address" | "offline" | "
  */
 export function reachLines(deliveries: Delivery[], late = false): string[] {
   if (!deliveries.some((d) => d.state)) return []
-  return deliveries.filter((d) => !late || (d.state && d.state !== "running")).map((d) => (d.state ? `${d.address}: ${REACH_TEXT[d.state]}` : deliveryText(d)))
+  return deliveries
+    .filter((d) => !late || (d.state && d.state !== "running"))
+    .map((d) => (d.state ? `${d.address}: ${reachText({ ...d, state: d.state })}` : deliveryText(d)))
+}
+
+/** an endpoint's presence as a line shows it: an idle agent no message wakes reads at its next turn */
+export function presenceText(e: Pick<EndpointView, "kind" | "presence" | "wake">): string {
+  return e.kind === "agent" && e.presence === "idle" && (!e.wake || e.wake === "none") ? "idle (next turn)" : e.presence
+}
+
+/** an agent's wake as a column shows it, `turn` when it reads at its next turn; `-` for any other endpoint */
+export function wakeText(e: Pick<EndpointView, "kind" | "wake">): string {
+  if (e.kind !== "agent") return "-"
+  return e.wake && e.wake !== "none" ? e.wake : "turn"
 }
 
 const pad = (n: number) => String(n).padStart(2, "0")