@scp-dev/core 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -404,7 +404,7 @@ 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";
+type Wake = "channels" | "pi" | "opencode-plugin" | "codex-app-server" | "claude-inbox" | "none";
 declare const WAKES: readonly Wake[];
 type ActivityKind = "session_start" | "tool" | "stop" | "note" | "session_end";
 declare const ACTIVITY_KINDS: readonly ActivityKind[];
@@ -658,6 +658,10 @@ interface Envelope {
     expires_at: string;
     /** a request whose sender holds the recipient's stop until it replies */
     require_reply?: true;
+    /** a broker-issued request to link under its sender */
+    link?: {
+        parent: string;
+    };
     /** set by inbox on a message a background hook already showed (and marked read), whose text may reach the agent only after this call */
     shown_at?: string;
     /**
@@ -769,6 +773,12 @@ interface SendResult {
     held?: JudgeHeld;
     redacted?: JudgeRedacted;
 }
+interface AdoptResult {
+    endpoint: EndpointView;
+    parent: string;
+    requested?: string;
+    held?: JudgeHeld;
+}
 /**
  * a message the caller sent and, per recipient, when it read the message (acked), or when a background hook delivered it (acked by that
  * showing; the agent gets it with its next request), and when a hook or channel showed it: ISO times, or null
@@ -792,7 +802,7 @@ interface AuditRow {
     detail: Record<string, unknown>;
 }
 /** fields only the server sets: a client that sends them gets invalid_params */
-declare const SERVER_FIELDS: readonly ["from", "id", "seq", "hop", "created_at", "auth", "expires_at", "relation"];
+declare const SERVER_FIELDS: readonly ["from", "id", "seq", "hop", "created_at", "auth", "expires_at", "relation", "link"];
 
 /**
  * `*`, `ep:<handle>` (that one agent), `handle:<glob>`, `harness:<name>`, `kind:<agent|human>` or `label:<key>=<value>`, plus the scope selectors: `tree:self|root|parent|siblings|children`,
@@ -1133,7 +1143,11 @@ interface MessageRow {
     expires_at: number;
     sender_tty: number | null;
     require_reply: number | null;
+    link_parent: string | null;
 }
+type AdoptSend = (from: string, params: SendParams, origin: {
+    link: "session" | "self";
+}) => Promise<SendResult>;
 interface CoreOptions {
     /** the local user's address part; `me` until a login names one */
     user?: string;
@@ -1384,16 +1398,23 @@ declare class RelayCore {
      * when given, renames it in place ({@link rename}'s rules). Nothing is kept when the rename is refused
      */
     joinSession(claim: Claim, handle?: unknown, under?: unknown): EndpointView;
-    /**
-     * links a local root agent under `parent`, as a spawned worker sits: in the parent's tree one level down, under the policy's child scope.
-     * Only the human at a terminal links another session, or an agent from its own shell with a terminal attached, under itself by default.
-     * A session links itself with {@link joinSession}'s `under`
-     */
+    /** the human links a local root directly; an agent asks it to consent through the normal send path */
     adopt(actor: ScopeActor, params: {
         endpoint: unknown;
         parent?: unknown;
     }, options?: {
         tty?: boolean;
+    }): AdoptResult;
+    adopt(actor: ScopeActor, params: {
+        endpoint: unknown;
+        parent?: unknown;
+    }, options: {
+        tty?: boolean;
+        send: AdoptSend;
+    }): AdoptResult | Promise<AdoptResult>;
+    /** accepts a broker-issued request delivered to the caller's own session */
+    linkAccept(actor: ScopeActor, params: {
+        id: unknown;
     }): {
         endpoint: EndpointView;
         parent: string;
@@ -1459,6 +1480,7 @@ declare class RelayCore {
     send(from: string, params: SendParams, origin?: {
         tty?: boolean;
         unverified?: boolean;
+        link?: "session" | "self";
     }): SendResult;
     /** a local agent recipient's {@link Reach} for a send from `sender`; none for a human, the relay or another machine's row */
     private reach;
@@ -2534,4 +2556,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, GENERIC_HARNESSES, 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, harnessFits, hasScope, honestSender, isLeaving, joinRedacted, judgeBoundary, judgeDetailForAgents, judgeFellBack, judgeModel, judgePrompt, keepLast, keptHarness, 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 };
+export { ACCOUNT_HANDLE, ACTIVITY_KINDS, type ActivityKind, type ActivityRow, type Admission, type AdoptResult, 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, GENERIC_HARNESSES, 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, harnessFits, hasScope, honestSender, isLeaving, joinRedacted, judgeBoundary, judgeDetailForAgents, judgeFellBack, judgeModel, judgePrompt, keepLast, keptHarness, 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,7 +179,7 @@ var RelayError = class extends Error {
   retryAfterS;
   detail;
 };
-var WAKES = ["channels", "pi", "opencode-plugin", "codex-app-server", "none"];
+var WAKES = ["channels", "pi", "opencode-plugin", "codex-app-server", "claude-inbox", "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"];
@@ -201,7 +201,7 @@ function keptHarness(held, claimed) {
   return generic(claimed) && !generic(held) ? held : claimed;
 }
 var SCOPE_PRESETS = ["open", "tree", "parent", "none"];
-var SERVER_FIELDS = ["from", "id", "seq", "hop", "created_at", "auth", "expires_at", "relation"];
+var SERVER_FIELDS = ["from", "id", "seq", "hop", "created_at", "auth", "expires_at", "relation", "link"];
 
 // src/scrub.ts
 var KEY_KIND = "[A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----";
@@ -1327,6 +1327,7 @@ var RelayCore = class {
     const messageColumns = this.sql.all(`PRAGMA table_info(messages)`).map((c) => c.name);
     if (!messageColumns.includes("sender_tty")) this.sql.all(`ALTER TABLE messages ADD COLUMN sender_tty INTEGER`);
     if (!messageColumns.includes("require_reply")) this.sql.all(`ALTER TABLE messages ADD COLUMN require_reply INTEGER`);
+    if (!messageColumns.includes("link_parent")) this.sql.all(`ALTER TABLE messages ADD COLUMN link_parent TEXT`);
     const endpointColumns = this.sql.all(`PRAGMA table_info(endpoints)`).map((c) => c.name);
     if (!endpointColumns.includes("session")) this.sql.all(`ALTER TABLE endpoints ADD COLUMN session TEXT`);
     if (!endpointColumns.includes("hook_seen")) this.sql.all(`ALTER TABLE endpoints ADD COLUMN hook_seen INTEGER`);
@@ -2278,30 +2279,52 @@ var RelayCore = class {
       return this.whoami(row.id);
     });
   }
-  /**
-   * links a local root agent under `parent`, as a spawned worker sits: in the parent's tree one level down, under the policy's child scope.
-   * Only the human at a terminal links another session, or an agent from its own shell with a terminal attached, under itself by default.
-   * A session links itself with {@link joinSession}'s `under`
-   */
   adopt(actor, params, options = {}) {
-    return this.scopeTx(() => {
+    const prepared = this.scopeTx(() => {
       const me = this.actorRow(actor);
       if (actor.kind === "human") this.needTerminal(actor, me, params.endpoint);
-      else if (options.tty !== true)
-        throw this.scopeRefused(
-          actor,
-          me,
-          { target: String(params.endpoint), reason: "adopt" },
-          `only the human at a terminal links another session under a parent; the session links itself with ${CLI_NAME} join --under`
-        );
+      else if (actor.auth === "lineage")
+        throw this.scopeRefused(actor, me, { target: String(params.endpoint), reason: "adopt" }, "only the session itself may request a link");
       const target = this.resolve(params.endpoint);
       if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint can be linked");
       const parentAddress = params.parent ?? (actor.kind === "human" ? void 0 : this.address(me));
       if (parentAddress === void 0 || parentAddress === null || parentAddress === "")
         throw new RelayError("invalid_params", "the human names the parent to link under");
       const parent = this.resolve(parentAddress);
-      this.link(target, parent, this.actorDetail(actor, me));
-      return { endpoint: this.whoami(target.id), parent: this.address(parent) };
+      if (actor.kind !== "human" && parent.id !== me.id)
+        throw this.scopeRefused(actor, me, { target: this.address(target), reason: "adopt" }, "an agent may request a link only under itself");
+      const result2 = { endpoint: this.whoami(target.id), parent: this.address(parent) };
+      if (actor.kind === "human" || options.tty === true) {
+        this.link(target, parent, this.actorDetail(actor, me));
+        return { result: { ...result2, endpoint: this.whoami(target.id) } };
+      }
+      if (target.parent_ep !== null || target.parent_addr !== null) throw this.alreadyLinked(target);
+      const auth2 = actor.auth === "self" ? "self" : "session";
+      return { result: result2, sender: { from: me.id, auth: auth2 } };
+    });
+    if (!prepared.sender) return prepared.result;
+    const { result } = prepared;
+    const { from, auth } = prepared.sender;
+    const send = {
+      to: result.endpoint.address,
+      kind: "request",
+      ttl_s: 86400,
+      body: `${result.parent} asks you to link under it as its worker. To accept, run ${CLI_NAME} link accept <id> with this message's id, or ${CLI_NAME} join --under ${result.parent} (relay_link_accept {id} or relay_join {under: "${result.parent}"}).`
+    };
+    const requested = (sent) => ({ ...result, ...sent.held ? { held: sent.held } : { requested: sent.id } });
+    return options.send ? options.send(from, send, { link: auth }).then(requested) : requested(this.send(from, send, { link: auth }));
+  }
+  /** accepts a broker-issued request delivered to the caller's own session */
+  linkAccept(actor, params) {
+    return this.scopeTx(() => {
+      if (actor.kind !== "endpoint" || actor.auth === "lineage") throw new RelayError("scope_refused", "only the session itself accepts a link request");
+      const me = this.actorRow(actor);
+      const request = this.delivered(me.id, params.id);
+      if (!request?.link || request.kind !== "request") throw new RelayError("not_found", "no link request delivered to this endpoint");
+      const parent = this.mustEndpoint(request.from.endpoint);
+      if (parent.kind !== "agent") throw new RelayError("invalid_params", "the requesting parent is no longer an agent");
+      this.link(me, parent, { ...this.actorDetail(actor, me), request: request.id });
+      return { endpoint: this.whoami(me.id), parent: this.address(parent) };
     });
   }
   /**
@@ -2368,7 +2391,7 @@ var RelayCore = class {
       this.sql.all(`UPDATE endpoints SET parent_addr = ?, linked = ? WHERE id = ?`, key, this.now(), row.id);
       this.scopeMemo?.ancestors.clear();
       this.scopeMemo?.limited.clear();
-      this.audit("adopt", row.id, null, { ...by, target: this.address(row), parent: this.address(parent) });
+      this.audit("adopt", row.id, by.request ?? null, { ...by, target: this.address(row), parent: this.address(parent) });
       return;
     }
     if (parent.kind !== "agent") throw new RelayError("invalid_params", "the parent is an agent endpoint");
@@ -2397,7 +2420,7 @@ var RelayCore = class {
     );
     this.scopeMemo?.ancestors.clear();
     this.scopeMemo?.limited.clear();
-    this.audit("adopt", row.id, null, { ...by, target: this.address(row), parent: this.address(parent) });
+    this.audit("adopt", row.id, by.request ?? null, { ...by, target: this.address(row), parent: this.address(parent) });
   }
   /** a link of `row`, which already sits under a parent, to another one */
   alreadyLinked(row) {
@@ -2504,6 +2527,7 @@ var RelayCore = class {
    * sends without a terminal, so the scopes check it like any unplaced sender
    */
   send(from, params, origin = {}) {
+    if ("link" in params) throw new RelayError("invalid_params", "link is set by the relay, not the sender");
     const sender = this.mustEndpoint(from);
     const senderTty = sender.kind === "human" ? origin.tty === true ? 1 : 0 : null;
     const unverified = sender.kind === "human" && origin.unverified === true;
@@ -2565,6 +2589,9 @@ var RelayCore = class {
     const pending = [...unjoined.values()].map((grant) => ({ key: pendingKey(grant.token_hash), address: `${this.user}/${grant.name}` }));
     const reached = recipients.length + pending.length;
     if (reached > LIMITS.fanOutTotal) throw new RelayError("too_large", `the send reaches ${reached} endpoints, more than ${LIMITS.fanOutTotal}`);
+    if (origin.link && (sender.kind !== "agent" || kind !== "request" || recipients.length !== 1 || pending.length || recipients[0].kind !== "agent" || !this.localRow(recipients[0])))
+      throw new RelayError("invalid_params", "a link request is from an agent to one local root agent");
+    if (origin.link && (recipients[0].parent_ep !== null || recipients[0].parent_addr !== null)) throw this.alreadyLinked(recipients[0]);
     const requestedThread = this.threadRef(from, cleanText(params.thread, "thread", 64));
     const payloadHash = this.hash(
       JSON.stringify([
@@ -2577,7 +2604,8 @@ var RelayCore = class {
         attachments.map((a) => a.path).sort(),
         mime,
         ttl,
-        params.require_reply === true
+        params.require_reply === true,
+        ...origin.link ? [origin.link] : []
       ])
     );
     if (clientId) {
@@ -2735,8 +2763,8 @@ var RelayCore = class {
       const expires = now + ttl * 1e3;
       const to = targets.length === 1 ? String(targets[0]) : targets.join(",");
       this.sql.all(
-        `INSERT INTO messages (id, thread, reply_to, kind, from_ep, to_addr, body, mime, data_class, attachments, hop, created_at, expires_at, sender_tty, require_reply)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        `INSERT INTO messages (id, thread, reply_to, kind, from_ep, to_addr, body, mime, data_class, attachments, hop, created_at, expires_at, sender_tty, require_reply, link_parent)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         id,
         thread,
         parent?.id ?? null,
@@ -2751,7 +2779,8 @@ var RelayCore = class {
         now,
         expires,
         senderTty,
-        params.require_reply === true ? 1 : null
+        params.require_reply === true ? 1 : null,
+        origin.link ? this.address(sender) : null
       );
       if (parent) this.sql.all(`UPDATE deliveries SET acked_at = ? WHERE message_id = ? AND endpoint = ? AND acked_at IS NULL`, now, parent.id, from);
       const deliveries = [];
@@ -2793,6 +2822,13 @@ var RelayCore = class {
         );
       }
       this.audit("send", from, id, { to: deliveries.map((d) => d.address), kind, bytes, hop, thread, data_class: dataClass });
+      if (origin.link)
+        this.audit("adopt_request", from, id, {
+          by: this.address(sender),
+          auth: origin.link,
+          target: this.address(recipients[0]),
+          parent: this.address(sender)
+        });
       for (const recipient of recipients) this.detectPingPong(sender, recipient);
       return sent;
     });
@@ -5538,6 +5574,7 @@ ${stderr}` : "";
       created_at: iso(row.created_at),
       expires_at: iso(row.expires_at),
       ...row.require_reply === 1 ? { require_reply: true } : {},
+      ...row.link_parent ? { link: { parent: row.link_parent } } : {},
       ...kin
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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

@@ -4,6 +4,7 @@ import {
   CLI_NAME,
   type ActivityKind,
   type ActivityRow,
+  type AdoptResult,
   type AuditRow,
   type Claim,
   type DataClass,
@@ -291,8 +292,11 @@ export interface MessageRow {
   expires_at: number
   sender_tty: number | null
   require_reply: number | null
+  link_parent: string | null
 }
 
+type AdoptSend = (from: string, params: SendParams, origin: { link: "session" | "self" }) => Promise<SendResult>
+
 export interface CoreOptions {
   /** the local user's address part; `me` until a login names one */
   user?: string
@@ -523,6 +527,7 @@ export class RelayCore {
     const messageColumns = this.sql.all<{ name: string }>(`PRAGMA table_info(messages)`).map((c) => c.name)
     if (!messageColumns.includes("sender_tty")) this.sql.all(`ALTER TABLE messages ADD COLUMN sender_tty INTEGER`)
     if (!messageColumns.includes("require_reply")) this.sql.all(`ALTER TABLE messages ADD COLUMN require_reply INTEGER`)
+    if (!messageColumns.includes("link_parent")) this.sql.all(`ALTER TABLE messages ADD COLUMN link_parent TEXT`)
     const endpointColumns = this.sql.all<{ name: string }>(`PRAGMA table_info(endpoints)`).map((c) => c.name)
     if (!endpointColumns.includes("session")) this.sql.all(`ALTER TABLE endpoints ADD COLUMN session TEXT`)
     if (!endpointColumns.includes("hook_seen")) this.sql.all(`ALTER TABLE endpoints ADD COLUMN hook_seen INTEGER`)
@@ -1592,30 +1597,60 @@ export class RelayCore {
     })
   }
 
-  /**
-   * links a local root agent under `parent`, as a spawned worker sits: in the parent's tree one level down, under the policy's child scope.
-   * Only the human at a terminal links another session, or an agent from its own shell with a terminal attached, under itself by default.
-   * A session links itself with {@link joinSession}'s `under`
-   */
-  adopt(actor: ScopeActor, params: { endpoint: unknown; parent?: unknown }, options: { tty?: boolean } = {}): { endpoint: EndpointView; parent: string } {
-    return this.scopeTx(() => {
+  /** the human links a local root directly; an agent asks it to consent through the normal send path */
+  adopt(actor: ScopeActor, params: { endpoint: unknown; parent?: unknown }, options?: { tty?: boolean }): AdoptResult
+  adopt(actor: ScopeActor, params: { endpoint: unknown; parent?: unknown }, options: { tty?: boolean; send: AdoptSend }): AdoptResult | Promise<AdoptResult>
+  adopt(
+    actor: ScopeActor,
+    params: { endpoint: unknown; parent?: unknown },
+    options: { tty?: boolean; send?: AdoptSend } = {},
+  ): AdoptResult | Promise<AdoptResult> {
+    const prepared: { result: AdoptResult; sender?: { from: string; auth: "session" | "self" } } = this.scopeTx(() => {
       const me = this.actorRow(actor)
       if (actor.kind === "human") this.needTerminal(actor, me, params.endpoint)
-      else if (options.tty !== true)
-        throw this.scopeRefused(
-          actor,
-          me,
-          { target: String(params.endpoint), reason: "adopt" },
-          `only the human at a terminal links another session under a parent; the session links itself with ${CLI_NAME} join --under`,
-        )
+      else if (actor.auth === "lineage")
+        throw this.scopeRefused(actor, me, { target: String(params.endpoint), reason: "adopt" }, "only the session itself may request a link")
       const target = this.resolve(params.endpoint)
       if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint can be linked")
       const parentAddress = params.parent ?? (actor.kind === "human" ? undefined : this.address(me))
       if (parentAddress === undefined || parentAddress === null || parentAddress === "")
         throw new RelayError("invalid_params", "the human names the parent to link under")
       const parent = this.resolve(parentAddress)
-      this.link(target, parent, this.actorDetail(actor, me))
-      return { endpoint: this.whoami(target.id), parent: this.address(parent) }
+      if (actor.kind !== "human" && parent.id !== me.id)
+        throw this.scopeRefused(actor, me, { target: this.address(target), reason: "adopt" }, "an agent may request a link only under itself")
+      const result: AdoptResult = { endpoint: this.whoami(target.id), parent: this.address(parent) }
+      if (actor.kind === "human" || options.tty === true) {
+        this.link(target, parent, this.actorDetail(actor, me))
+        return { result: { ...result, endpoint: this.whoami(target.id) } }
+      }
+      if (target.parent_ep !== null || target.parent_addr !== null) throw this.alreadyLinked(target)
+      const auth = actor.auth === "self" ? "self" : "session"
+      return { result, sender: { from: me.id, auth } }
+    })
+    if (!prepared.sender) return prepared.result
+    const { result } = prepared
+    const { from, auth } = prepared.sender
+    const send: SendParams = {
+      to: result.endpoint.address,
+      kind: "request",
+      ttl_s: 86_400,
+      body: `${result.parent} asks you to link under it as its worker. To accept, run ${CLI_NAME} link accept <id> with this message's id, or ${CLI_NAME} join --under ${result.parent} (relay_link_accept {id} or relay_join {under: "${result.parent}"}).`,
+    }
+    const requested = (sent: SendResult): AdoptResult => ({ ...result, ...(sent.held ? { held: sent.held } : { requested: sent.id }) })
+    return options.send ? options.send(from, send, { link: auth }).then(requested) : requested(this.send(from, send, { link: auth }))
+  }
+
+  /** accepts a broker-issued request delivered to the caller's own session */
+  linkAccept(actor: ScopeActor, params: { id: unknown }): { endpoint: EndpointView; parent: string } {
+    return this.scopeTx(() => {
+      if (actor.kind !== "endpoint" || actor.auth === "lineage") throw new RelayError("scope_refused", "only the session itself accepts a link request")
+      const me = this.actorRow(actor)
+      const request = this.delivered(me.id, params.id)
+      if (!request?.link || request.kind !== "request") throw new RelayError("not_found", "no link request delivered to this endpoint")
+      const parent = this.mustEndpoint(request.from.endpoint)
+      if (parent.kind !== "agent") throw new RelayError("invalid_params", "the requesting parent is no longer an agent")
+      this.link(me, parent, { ...this.actorDetail(actor, me), request: request.id })
+      return { endpoint: this.whoami(me.id), parent: this.address(parent) }
     })
   }
 
@@ -1676,7 +1711,7 @@ export class RelayCore {
    * `row`, a root, and its subtree moved under `parent`, a local agent that is neither `row` nor one of its descendants; a parent on another
    * machine goes to {@link linkAcross}
    */
-  private link(row: EndpointRow, parent: EndpointRow, by: { by: string; auth: string }): void {
+  private link(row: EndpointRow, parent: EndpointRow, by: { by: string; auth: string; request?: string }): void {
     if (!this.localRow(parent)) {
       const key = this.linkAcross(row, parent)
       if (row.parent_addr === key) return
@@ -1684,7 +1719,7 @@ export class RelayCore {
       this.sql.all(`UPDATE endpoints SET parent_addr = ?, linked = ? WHERE id = ?`, key, this.now(), row.id)
       this.scopeMemo?.ancestors.clear()
       this.scopeMemo?.limited.clear()
-      this.audit("adopt", row.id, null, { ...by, target: this.address(row), parent: this.address(parent) })
+      this.audit("adopt", row.id, by.request ?? null, { ...by, target: this.address(row), parent: this.address(parent) })
       return
     }
     if (parent.kind !== "agent") throw new RelayError("invalid_params", "the parent is an agent endpoint")
@@ -1713,7 +1748,7 @@ export class RelayCore {
     )
     this.scopeMemo?.ancestors.clear()
     this.scopeMemo?.limited.clear()
-    this.audit("adopt", row.id, null, { ...by, target: this.address(row), parent: this.address(parent) })
+    this.audit("adopt", row.id, by.request ?? null, { ...by, target: this.address(row), parent: this.address(parent) })
   }
 
   /** a link of `row`, which already sits under a parent, to another one */
@@ -1829,7 +1864,8 @@ export class RelayCore {
    * `origin.tty` is recorded on messages the human inbox sends: whether its client said a terminal was attached. `origin.unverified`: the human
    * sends without a terminal, so the scopes check it like any unplaced sender
    */
-  send(from: string, params: SendParams, origin: { tty?: boolean; unverified?: boolean } = {}): SendResult {
+  send(from: string, params: SendParams, origin: { tty?: boolean; unverified?: boolean; link?: "session" | "self" } = {}): SendResult {
+    if ("link" in params) throw new RelayError("invalid_params", "link is set by the relay, not the sender")
     const sender = this.mustEndpoint(from)
     const senderTty = sender.kind === "human" ? (origin.tty === true ? 1 : 0) : null
     const unverified = sender.kind === "human" && origin.unverified === true
@@ -1897,6 +1933,17 @@ export class RelayCore {
     const pending = [...unjoined.values()].map((grant) => ({ key: pendingKey(grant.token_hash), address: `${this.user}/${grant.name}` }))
     const reached = recipients.length + pending.length
     if (reached > LIMITS.fanOutTotal) throw new RelayError("too_large", `the send reaches ${reached} endpoints, more than ${LIMITS.fanOutTotal}`)
+    if (
+      origin.link &&
+      (sender.kind !== "agent" ||
+        kind !== "request" ||
+        recipients.length !== 1 ||
+        pending.length ||
+        recipients[0]!.kind !== "agent" ||
+        !this.localRow(recipients[0]!))
+    )
+      throw new RelayError("invalid_params", "a link request is from an agent to one local root agent")
+    if (origin.link && (recipients[0]!.parent_ep !== null || recipients[0]!.parent_addr !== null)) throw this.alreadyLinked(recipients[0]!)
     const requestedThread = this.threadRef(from, cleanText(params.thread, "thread", 64))
     const payloadHash = this.hash(
       JSON.stringify([
@@ -1910,6 +1957,7 @@ export class RelayCore {
         mime,
         ttl,
         params.require_reply === true,
+        ...(origin.link ? [origin.link] : []),
       ]),
     )
     if (clientId) {
@@ -2079,8 +2127,8 @@ export class RelayCore {
       const expires = now + ttl * 1000
       const to = targets.length === 1 ? String(targets[0]) : targets.join(",")
       this.sql.all(
-        `INSERT INTO messages (id, thread, reply_to, kind, from_ep, to_addr, body, mime, data_class, attachments, hop, created_at, expires_at, sender_tty, require_reply)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        `INSERT INTO messages (id, thread, reply_to, kind, from_ep, to_addr, body, mime, data_class, attachments, hop, created_at, expires_at, sender_tty, require_reply, link_parent)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         id,
         thread,
         parent?.id ?? null,
@@ -2096,6 +2144,7 @@ export class RelayCore {
         expires,
         senderTty,
         params.require_reply === true ? 1 : null,
+        origin.link ? this.address(sender) : null,
       )
       if (parent) this.sql.all(`UPDATE deliveries SET acked_at = ? WHERE message_id = ? AND endpoint = ? AND acked_at IS NULL`, now, parent.id, from)
       const deliveries: SendResult["deliveries"] = []
@@ -2137,6 +2186,13 @@ export class RelayCore {
         )
       }
       this.audit("send", from, id, { to: deliveries.map((d) => d.address), kind, bytes, hop, thread, data_class: dataClass })
+      if (origin.link)
+        this.audit("adopt_request", from, id, {
+          by: this.address(sender),
+          auth: origin.link,
+          target: this.address(recipients[0]!),
+          parent: this.address(sender),
+        })
       for (const recipient of recipients) this.detectPingPong(sender, recipient)
       return sent
     })
@@ -5249,6 +5305,7 @@ export class RelayCore {
       created_at: iso(row.created_at)!,
       expires_at: iso(row.expires_at)!,
       ...(row.require_reply === 1 ? { require_reply: true as const } : {}),
+      ...(row.link_parent ? { link: { parent: row.link_parent } } : {}),
       ...kin,
     }
   }

package/src/protocol.ts

@@ -112,8 +112,8 @@ 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 Wake = "channels" | "pi" | "opencode-plugin" | "codex-app-server" | "claude-inbox" | "none"
+export const WAKES: readonly Wake[] = ["channels", "pi", "opencode-plugin", "codex-app-server", "claude-inbox", "none"]
 
 export type ActivityKind = "session_start" | "tool" | "stop" | "note" | "session_end"
 export const ACTIVITY_KINDS: readonly ActivityKind[] = ["session_start", "tool", "stop", "note", "session_end"]
@@ -358,6 +358,8 @@ export interface Envelope {
   expires_at: string
   /** a request whose sender holds the recipient's stop until it replies */
   require_reply?: true
+  /** a broker-issued request to link under its sender */
+  link?: { parent: string }
   /** set by inbox on a message a background hook already showed (and marked read), whose text may reach the agent only after this call */
   shown_at?: string
   /**
@@ -473,6 +475,13 @@ export interface SendResult {
   redacted?: JudgeRedacted
 }
 
+export interface AdoptResult {
+  endpoint: EndpointView
+  parent: string
+  requested?: string
+  held?: JudgeHeld
+}
+
 /**
  * a message the caller sent and, per recipient, when it read the message (acked), or when a background hook delivered it (acked by that
  * showing; the agent gets it with its next request), and when a hook or channel showed it: ISO times, or null
@@ -493,4 +502,4 @@ export interface AuditRow {
 }
 
 /** fields only the server sets: a client that sends them gets invalid_params */
-export const SERVER_FIELDS = ["from", "id", "seq", "hop", "created_at", "auth", "expires_at", "relation"] as const
+export const SERVER_FIELDS = ["from", "id", "seq", "hop", "created_at", "auth", "expires_at", "relation", "link"] as const