@scp-dev/core 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -385,8 +385,10 @@ declare const LIMITS: {
     readonly grantTtlS: number;
     readonly groupIdleS: 86400;
     readonly policyLoadsKept: 8;
+    /** the prompts between two refreshes of a title a hook inferred */
+    readonly titleRefreshTurns: 5;
 };
-type ErrorCode = "not_found" | "inbox_full" | "rate_limited" | "loop_guard" | "data_class_refused" | "secret_refused" | "policy_refused" | "too_large" | "invalid_params" | "unauthorized" | "method_not_found" | "scope_refused" | "unavailable" | "judge_refused";
+type ErrorCode = "not_found" | "inbox_full" | "rate_limited" | "loop_guard" | "data_class_refused" | "secret_refused" | "policy_refused" | "too_large" | "invalid_params" | "unauthorized" | "method_not_found" | "scope_refused" | "unavailable" | "judge_refused" | "not_live";
 declare class RelayError extends Error {
     readonly code: ErrorCode;
     readonly retryAfterS?: number | undefined;
@@ -695,6 +697,8 @@ interface SendParams {
     mime?: string;
     /** on a request only: the recipient's stop is held until it replies */
     require_reply?: boolean;
+    /** refuse `not_live`, queueing nothing, when an agent recipient has no live session */
+    live?: boolean;
 }
 /** what ask and ask_wait answer: the reply; or pending, with `ended` once every recipient present at the send went offline without replying; or expired */
 interface AskResult {
@@ -744,6 +748,8 @@ interface SendResult {
         last_seen: string | null;
         state?: Reach;
     }[];
+    /** one line per agent recipient no live session holds: `queued: no live session holds <address>` */
+    warnings?: string[];
     duplicate?: boolean;
     held?: JudgeHeld;
     redacted?: JudgeRedacted;
@@ -803,6 +809,8 @@ interface PolicyDefaults {
     /** `inherit`: a child of a capped parent reaches only what the parent reaches; a preset caps every placed child without grant caps */
     child_default?: ScopePreset | "inherit";
     verify_lineage?: "spike" | boolean;
+    /** who may rename an agent besides the human at a terminal: `root` (default) only a root session itself, `self` any agent itself, spawned ones too */
+    rename?: "root" | "self";
 }
 interface Policy {
     rules: PolicyRule[];
@@ -1017,6 +1025,8 @@ interface Sql {
 declare const one: <T>(sql: Sql, query: string, ...params: SqlValue[]) => T | undefined;
 
 declare const HUMAN_HANDLE = "_human";
+/** an agent title's length cap */
+declare const TITLE_CHARS = 64;
 declare const SYSTEM_HANDLE = "_relay";
 declare const GONE_PREFIX = "_gone_";
 interface EndpointRow {
@@ -1064,12 +1074,20 @@ interface EndpointRow {
     /** JSON {@link ScopeCaps} */
     caps: string | null;
     title: string | null;
+    /** the title a hook last inferred: the title is inferred while it equals this */
+    title_auto: string | null;
+    /** the prompt count when a summary last set the inferred title; null when the first prompt set it */
+    title_turn: number | null;
+    /** the prompt count when the status note last changed or a hook last reminded the agent to refresh it */
+    tldr_turn: number | null;
     /** when a new spawn last took the endpoint over: mail and messages from before it were the earlier holder's */
     reset_at: number | null;
     /** when a new spawn last took the endpoint over: with its id, names the holder another machine sees */
     spawned_at: number | null;
     /** who may peek: null is off */
     peek: PeekLevel | null;
+    /** when the session last set its handle itself (join or rename): a later claim with another handle does not rename it back */
+    named: number | null;
 }
 interface MessageRow {
     id: string;
@@ -1118,6 +1136,8 @@ declare class RelayCore {
     private readonly capEverySender;
     private readonly alive;
     private readonly hostMachine;
+    private readonly namedMachine;
+    private readonly hostname;
     private policy;
     /** the identity each policy `group:<name>` naming no policy group bound to when the policy's text first loaded: that group's then, or `none` */
     private policyBinds;
@@ -1126,6 +1146,8 @@ declare class RelayCore {
     private scopeMemo;
     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 */
+    private machineLabel;
     migrate(): void;
     /** every stored list that is exactly `tree:self`, the tree preset's old list, narrows once to the preset's list */
     private migrateTreePreset;
@@ -1279,6 +1301,49 @@ declare class RelayCore {
     status(endpoint: string, state: unknown, note: unknown): void;
     /** an agent's own title, shown in list and whoami; empty clears it, and no claim overwrites it */
     title(endpoint: string, value: unknown): EndpointView;
+    /**
+     * a hook's guess at the session's title, from the harness's own summary or the first prompt's first line; whether it changed the title.
+     * Never over a title set explicitly; the first prompt fills only an empty title, and a summary replaces an inferred one at most every
+     * ${LIMITS.titleRefreshTurns} prompts, or at once over the first prompt's
+     */
+    inferTitle(endpoint: string, params: {
+        text?: unknown;
+        from?: unknown;
+    }, options?: {
+        transient?: boolean;
+        process?: string;
+    }): boolean;
+    /**
+     * 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
+     */
+    joinSession(claim: Claim, handle?: unknown): EndpointView;
+    /**
+     * renames an agent in place: its id, mail, threads, status, title and relations stay. An agent renames only itself, and only a root unless
+     * the policy's `defaults.rename` is `self`; the human at a terminal renames any local agent. The new handle is valid and held by no other endpoint
+     */
+    rename(actor: ScopeActor, params: {
+        endpoint?: unknown;
+        handle: unknown;
+    }): {
+        endpoint: EndpointView;
+        from: string;
+        session: string | null;
+    };
+    /** the endpoint's handle set to `value`, with the stored `ep:` and `fleet:` selectors that named it */
+    private renameRow;
+    /**
+     * a session leaves: it lets go of its session and token and shows offline, its mail kept; a later join takes it back. An agent leaves only
+     * itself, the human at a terminal any local root. A spawned worker stays joined while it runs
+     */
+    leaveSession(actor: ScopeActor, params?: {
+        endpoint?: unknown;
+    }): {
+        endpoint: EndpointView;
+        session: string | null;
+    };
+    /** the harness session key an endpoint holds, if any */
+    sessionOf(endpoint: string): string | null;
     /**
      * `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
@@ -1339,6 +1404,7 @@ declare class RelayCore {
      * `directive_seqs`. Any call says `brief` once the session was shown the full preamble ({@link briefed}), and one that is no stop names in
      * `intro` the spawner of an endpoint a `swarm spawn` grant placed, with the grant's steer key in `intro_key`, until a hook showed it
      * ({@link introduced}). A hook of another process than the one holding the endpoint (a child that inherited the session key) gets nothing.
+     * A wake also offers live workers' messages.
      */
     inject(endpoint: string, options?: {
         stop?: boolean;
@@ -1347,6 +1413,7 @@ declare class RelayCore {
         directives?: boolean;
         transient?: boolean;
         process?: string;
+        wake?: boolean;
     }): {
         messages: Envelope[];
         offered: number[];
@@ -1415,6 +1482,8 @@ declare class RelayCore {
         transient?: boolean;
         process?: string;
     }): boolean;
+    /** whether a prompt should remind the agent to refresh its status note: `every` prompts passed since the note or the last reminder; counts the reminder */
+    tldrDue(endpoint: string, every: number): boolean;
     /** the background hooks' showings ({@link injected}) older than ${LIMITS.deferredSettleMs} ms reached the agent: inbox no longer lists them */
     private settle;
     /**
@@ -1544,6 +1613,8 @@ declare class RelayCore {
     }): AuditRow[];
     /** drops what expired: deliveries, message bodies past their grace, old guard state and old audit rows */
     sweep(): void;
+    /** ends the hook presence of local agent endpoints whose harness process exited without a session_end, as one would */
+    endExited(now?: number): void;
     /** an agent endpoint left offline drops a working or waiting status, which no one is left to keep current */
     private settleOffline;
     /**
@@ -2351,4 +2422,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, 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, 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 };

package/dist/index.js

@@ -164,7 +164,9 @@ var LIMITS = {
   groupPerMinute: 60,
   grantTtlS: 7 * 86400,
   groupIdleS: 86400,
-  policyLoadsKept: 8
+  policyLoadsKept: 8,
+  /** the prompts between two refreshes of a title a hook inferred */
+  titleRefreshTurns: 5
 };
 var RelayError = class extends Error {
   constructor(code, message, retryAfterS, detail) {
@@ -699,7 +701,7 @@ function parsePolicy(value, options = {}) {
   }
   if (defaults !== void 0) {
     if (!isObject2(defaults)) throw new RelayError("invalid_params", "defaults is an object");
-    const { human_always, symmetric_presets, child_default, verify_lineage, ...extra } = defaults;
+    const { human_always, symmetric_presets, child_default, verify_lineage, rename, ...extra } = defaults;
     if (Object.keys(extra).length) throw new RelayError("invalid_params", `unknown defaults: ${Object.keys(extra).join(", ")}`);
     const parsed = {};
     for (const [key, flag] of [
@@ -723,6 +725,10 @@ function parsePolicy(value, options = {}) {
         throw new RelayError("invalid_params", "defaults.verify_lineage true needs the peer-pid check, which this relay does not have yet: use spike or false");
       parsed.verify_lineage = verify_lineage;
     }
+    if (rename !== void 0) {
+      if (rename !== "root" && rename !== "self") throw new RelayError("invalid_params", "defaults.rename is root or self");
+      parsed.rename = rename;
+    }
     policy.defaults = parsed;
   }
   if (judge !== void 0) policy.judge = parseJudgePolicy(judge, options.judgeProviders);
@@ -1065,6 +1071,7 @@ function utf8Bytes(text) {
 
 // src/core.ts
 var HUMAN_HANDLE = "_human";
+var TITLE_CHARS = 64;
 var SYSTEM_HANDLE = "_relay";
 var GONE_PREFIX = "_gone_";
 var MIGRATION = [
@@ -1247,6 +1254,8 @@ var RelayCore = class {
     this.capEverySender = options.capEverySender === true;
     this.alive = options.alive ?? (() => true);
     this.hostMachine = options.machine ?? options.hostname ?? null;
+    this.namedMachine = options.machine ?? null;
+    this.hostname = options.hostname ?? null;
   }
   sql;
   user;
@@ -1256,6 +1265,8 @@ var RelayCore = class {
   capEverySender;
   alive;
   hostMachine;
+  namedMachine;
+  hostname;
   policy = null;
   /** the identity each policy `group:<name>` naming no policy group bound to when the policy's text first loaded: that group's then, or `none` */
   policyBinds = /* @__PURE__ */ new Map();
@@ -1263,6 +1274,11 @@ var RelayCore = class {
   /** while a scope world derives a node: what it already derived of ancestor lists and limits */
   scopeMemo = null;
   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) {
+    if (this.namedMachine !== null && labels.machine !== void 0 && labels.machine === this.hostname) labels.machine = this.namedMachine;
+    return labels;
+  }
   migrate() {
     for (const statement of MIGRATION) this.sql.all(statement);
     const columns = this.sql.all(`PRAGMA table_info(idempotency)`).map((c) => c.name);
@@ -1295,7 +1311,11 @@ var RelayCore = class {
       ["introduced", "INTEGER"],
       ["directive_holds", "INTEGER"],
       ["harness_session", "TEXT"],
-      ["harness_transcript", "TEXT"]
+      ["harness_transcript", "TEXT"],
+      ["title_auto", "TEXT"],
+      ["title_turn", "INTEGER"],
+      ["tldr_turn", "INTEGER"],
+      ["named", "INTEGER"]
     ]) {
       if (!endpointColumns.includes(column)) this.sql.all(`ALTER TABLE endpoints ADD COLUMN ${column} ${type}`);
     }
@@ -1452,7 +1472,7 @@ var RelayCore = class {
       model: cleanText(claim.model, "model", 128),
       cwd: cleanText(claim.cwd, "cwd", 1024),
       parent: cleanText(claim.parent, "parent", 128),
-      labels: JSON.stringify(cleanLabels(claim.labels)),
+      labels: JSON.stringify(this.machineLabel(cleanLabels(claim.labels))),
       session: cleanText(claim.session, "session", 128),
       process: cleanText(claim.process, "process", 128)
     };
@@ -1551,6 +1571,7 @@ var RelayCore = class {
   }
   claimRow(wanted, harness, fields, transient, scope = { handle: wanted, lineage: [], grant: null, rules: {}, groups: [], cwd: fields.cwd }) {
     const now = this.now();
+    this.endExited(now);
     const bare = transient && fields.session !== null && BARE_PID_KEY.test(fields.session);
     let row = fields.session ? one(
       this.sql,
@@ -1574,7 +1595,7 @@ var RelayCore = class {
     } else if (row && !transient && !sameProcess(row, fields.process)) {
       row = void 0;
       session = null;
-    } else if (row && !transient && row.token_hash === null && row.handle !== wanted && !row.handle.startsWith(`${wanted.slice(0, 58)}-`)) {
+    } else if (row && !transient && row.token_hash === null && row.named === null && row.handle !== wanted && !row.handle.startsWith(`${wanted.slice(0, 58)}-`)) {
       const hooks = row;
       let settled = false;
       for (let n = 1; n < (scope.exact ? 2 : 1e3) && !settled; n++) {
@@ -2012,6 +2033,7 @@ var RelayCore = class {
    */
   list(filters = {}) {
     const now = this.now();
+    this.endExited(now);
     this.settleOffline(now);
     const cutoff = now - LIMITS.listOfflineWithinS * 1e3;
     const viewer = filters.viewer === void 0 ? void 0 : this.mustEndpoint(filters.viewer);
@@ -2065,10 +2087,12 @@ var RelayCore = class {
     const text = oneLine(note, "note", LIMITS.noteChars);
     if (text && findSecret(text)) throw this.refuse(endpoint, "secret_refused", "the status note looks like it carries a credential");
     this.sql.all(
-      `UPDATE endpoints SET status_state = COALESCE(?, status_state, 'working'), status_note = COALESCE(?, status_note, ''), last_seen = ? WHERE id = ?`,
+      `UPDATE endpoints SET status_state = COALESCE(?, status_state, 'working'), status_note = COALESCE(?, status_note, ''), last_seen = ?,
+       tldr_turn = CASE WHEN ? THEN COALESCE(prompts, 0) ELSE tldr_turn END WHERE id = ?`,
       state ?? null,
       text,
       this.now(),
+      text === null ? 0 : 1,
       endpoint
     );
   }
@@ -2078,10 +2102,117 @@ var RelayCore = class {
     if (row.kind !== "agent") throw new RelayError("invalid_params", "only an agent endpoint has a title");
     const title = oneLine(value, "title", 64) || null;
     if (title && findSecret(title)) throw this.refuse(endpoint, "secret_refused", "the title looks like it carries a credential");
-    this.sql.all(`UPDATE endpoints SET title = ? WHERE id = ?`, title, endpoint);
+    this.sql.all(`UPDATE endpoints SET title = ?, title_auto = NULL, title_turn = NULL WHERE id = ?`, title, endpoint);
     this.audit("title", endpoint, null, { title });
     return this.whoami(endpoint);
   }
+  /**
+   * a hook's guess at the session's title, from the harness's own summary or the first prompt's first line; whether it changed the title.
+   * Never over a title set explicitly; the first prompt fills only an empty title, and a summary replaces an inferred one at most every
+   * ${LIMITS.titleRefreshTurns} prompts, or at once over the first prompt's
+   */
+  inferTitle(endpoint, params, options = {}) {
+    if (params.from !== "summary" && params.from !== "prompt") throw new RelayError("invalid_params", "from is summary or prompt");
+    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;
+    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;
+    if (params.from === "summary" && row.title !== null && row.title_turn !== null && turn - row.title_turn < LIMITS.titleRefreshTurns) return false;
+    this.sql.all(`UPDATE endpoints SET title = ?, title_auto = ?, title_turn = ? WHERE id = ?`, title, title, params.from === "summary" ? turn : null, endpoint);
+    return true;
+  }
+  /**
+   * 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
+   */
+  joinSession(claim, handle) {
+    return this.scopeTx(() => {
+      const { endpoint } = this.claim(claim, { transient: true });
+      const row = this.mustEndpoint(endpoint.id);
+      if (handle !== void 0 && handle !== null && handle !== "") this.renameRow(row, handle, false);
+      this.sql.all(`UPDATE endpoints SET hook_seen = ?, hook_ended = NULL WHERE id = ?`, this.now(), row.id);
+      this.audit("join", row.id, null, { handle: this.byId(row.id).handle });
+      return this.whoami(row.id);
+    });
+  }
+  /**
+   * renames an agent in place: its id, mail, threads, status, title and relations stay. An agent renames only itself, and only a root unless
+   * the policy's `defaults.rename` is `self`; the human at a terminal renames any local agent. The new handle is valid and held by no other endpoint
+   */
+  rename(actor, params) {
+    return this.scopeTx(() => {
+      const me = this.actorRow(actor);
+      if (actor.kind === "human") this.needTerminal(actor, me, params.endpoint);
+      else if (actor.auth === "lineage") throw new RelayError("scope_refused", "only the session itself renames it: run this from the session's own shell");
+      const target = params.endpoint === void 0 ? me : this.resolve(params.endpoint);
+      if (actor.kind !== "human" && target.id !== me.id) throw new RelayError("scope_refused", "an agent renames only itself");
+      if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint can be renamed");
+      this.renameRow(target, params.handle, actor.kind === "human");
+      return { endpoint: this.whoami(target.id), from: target.handle, session: target.session };
+    });
+  }
+  /** the endpoint's handle set to `value`, with the stored `ep:` and `fleet:` selectors that named it */
+  renameRow(row, value, byHuman) {
+    const handle = typeof value === "string" ? value.trim().replace(/^me\//, "") : "";
+    if (!validHandle(handle)) throw new RelayError("invalid_params", `handle ${JSON.stringify(handle)} is not valid: lowercase letters, digits, . _ -`);
+    if (findSecret(handle)) throw new RelayError("secret_refused", "the handle looks like it carries a credential");
+    if (handle === row.handle) {
+      this.sql.all(`UPDATE endpoints SET named = COALESCE(named, ?) WHERE id = ?`, this.now(), row.id);
+      return;
+    }
+    if (!byHuman && row.parent_ep !== null && this.policy?.defaults?.rename !== "self") {
+      const parent = this.byId(row.parent_ep);
+      throw new RelayError("scope_refused", `spawned by ${parent ? this.address(parent) : "another agent"}; its name is set by the spawner`);
+    }
+    const held = this.byHandle(handle);
+    if (held) {
+      const how = held.kind !== "agent" ? "reserved" : presenceOf(held, this.now()) === "offline" ? "held by an offline endpoint" : "held by a live endpoint";
+      throw new RelayError("invalid_params", `${handle} is ${how}: pick another name`);
+    }
+    const from = row.handle;
+    this.sql.all(`UPDATE endpoints SET handle = ?, named = ? WHERE id = ?`, handle, this.now(), row.id);
+    this.sql.all(`UPDATE grants SET name = ? WHERE used_by = ? AND name = ?`, handle, row.id, from);
+    for (const prefix of row.parent_ep === null ? ["ep:", "fleet:"] : ["ep:"]) {
+      const [a, b] = [JSON.stringify(`${prefix}${from}`), JSON.stringify(`${prefix}${handle}`)];
+      for (const [table, column] of [
+        ["endpoints", "rules"],
+        ["endpoints", "caps"],
+        ["groups", "rules"],
+        ["grants", "caps"]
+      ])
+        this.sql.all(`UPDATE ${table} SET ${column} = REPLACE(${column}, ?, ?) WHERE instr(${column}, ?) > 0`, a, b, a);
+    }
+    this.audit("rename", row.id, null, { from, to: handle });
+  }
+  /**
+   * a session leaves: it lets go of its session and token and shows offline, its mail kept; a later join takes it back. An agent leaves only
+   * itself, the human at a terminal any local root. A spawned worker stays joined while it runs
+   */
+  leaveSession(actor, params = {}) {
+    return this.scopeTx(() => {
+      const me = this.actorRow(actor);
+      if (actor.kind === "human") this.needTerminal(actor, me, params.endpoint);
+      else if (actor.auth === "lineage") throw new RelayError("scope_refused", "only the session itself leaves: run this from the session's own shell");
+      const target = params.endpoint === void 0 ? me : this.resolve(params.endpoint);
+      if (actor.kind !== "human" && target.id !== me.id) throw new RelayError("scope_refused", "an agent leaves only for itself");
+      if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint can leave");
+      if (target.parent_ep !== null) {
+        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.audit("leave", target.id, null, { handle: target.handle });
+      return { endpoint: this.whoami(target.id), session: target.session };
+    });
+  }
+  /** the harness session key an endpoint holds, if any */
+  sessionOf(endpoint) {
+    return this.byId(endpoint)?.session ?? null;
+  }
   // messages
   /**
    * `origin.tty` is recorded on messages the human inbox sends: whether its client said a terminal was attached. `origin.unverified`: the human
@@ -2139,6 +2270,13 @@ var RelayCore = class {
       resolved.push(row);
     }
     const recipients = [...new Map(resolved.map((row) => [row.id, row])).values()];
+    if (params.live !== void 0 && typeof params.live !== "boolean") throw new RelayError("invalid_params", "live must be true or false");
+    const dark = recipients.filter(
+      (r) => r.kind === "agent" && presenceOf(r, now) === "offline" && (now - Math.max(r.last_seen ?? 0, r.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS || r.session === null && r.token_hash === null && r.hook_ended !== null) && !this.unjoinedSpawn(sender, r.handle, now)
+    );
+    if (params.live === true && dark.length)
+      throw new RelayError("not_live", `no live session holds ${dark.map((r) => this.address(r)).join(", ")}: nothing was queued`);
+    const warnings = dark.map((r) => `queued: no live session holds ${this.address(r)}`);
     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}`);
@@ -2356,7 +2494,7 @@ var RelayCore = class {
         deliveries.push({ endpoint: key, address, seq, offline: false, queued: true, last_seen: null, state: "starting" });
       }
       for (const name of fanOut) this.sql.all(`INSERT INTO tree_events (tree, at) VALUES (?, ?)`, `group:${name}`, now);
-      const sent = { id, thread, hop, deliveries };
+      const sent = { id, thread, hop, deliveries, ...warnings.length ? { warnings } : {} };
       if (clientId) {
         this.sql.all(
           `INSERT OR REPLACE INTO idempotency (from_ep, client_id, payload_hash, result, created_at) VALUES (?, ?, ?, ?, ?)`,
@@ -2494,6 +2632,7 @@ var RelayCore = class {
    * `directive_seqs`. Any call says `brief` once the session was shown the full preamble ({@link briefed}), and one that is no stop names in
    * `intro` the spawner of an endpoint a `swarm spawn` grant placed, with the grant's steer key in `intro_key`, until a hook showed it
    * ({@link introduced}). A hook of another process than the one holding the endpoint (a child that inherited the session key) gets nothing.
+   * A wake also offers live workers' messages.
    */
   inject(endpoint, options = {}) {
     const now = this.now();
@@ -2561,7 +2700,7 @@ var RelayCore = class {
       now,
       LIMITS.inboxPage
     );
-    const { shown, offered } = this.budget(rows, LIMITS.injectBytes, () => this.pushable(me, now));
+    const { shown, offered } = this.budget(rows, LIMITS.injectBytes, options.wake ? void 0 : () => this.pushable(me, now));
     const hold = this.hold(offered, now);
     this.received(endpoint, shown, now);
     return { messages: shown.map((row) => this.envelope(row, row.seq)), offered, hold, more: waiting - shown.length, unread, block: false, ...brief, ...intro };
@@ -2731,6 +2870,15 @@ var RelayCore = class {
     this.settle(endpoint);
     return true;
   }
+  /** whether a prompt should remind the agent to refresh its status note: `every` prompts passed since the note or the last reminder; counts the reminder */
+  tldrDue(endpoint, every) {
+    if (!Number.isInteger(every) || every <= 0) return false;
+    const row = this.mustEndpoint(endpoint);
+    const turn = row.prompts ?? 0;
+    if (row.kind !== "agent" || turn - (row.tldr_turn ?? 0) < every) return false;
+    this.sql.all(`UPDATE endpoints SET tldr_turn = ? WHERE id = ?`, turn, endpoint);
+    return true;
+  }
   /** the background hooks' showings ({@link injected}) older than ${LIMITS.deferredSettleMs} ms reached the agent: inbox no longer lists them */
   settle(endpoint) {
     this.sql.all(
@@ -3185,6 +3333,7 @@ var RelayCore = class {
     this.sql.all(`DELETE FROM idempotency WHERE created_at <= ?`, now - LIMITS.idempotencyS * 1e3);
     this.sql.all(`DELETE FROM pair_events WHERE at <= ?`, now - 3600 * 1e3);
     this.sql.all(`DELETE FROM blocks WHERE until <= ?`, now);
+    this.endExited(now);
     this.settleOffline(now);
     this.sql.all(
       `DELETE FROM endpoints WHERE kind = 'agent' AND connections = 0 AND COALESCE(last_seen, created_at) <= ?
@@ -3210,6 +3359,16 @@ var RelayCore = class {
       if (!root || root.handle.startsWith(GONE_PREFIX) || !seen) this.dropGroup(group.name);
     }
   }
+  /** ends the hook presence of local agent endpoints whose harness process exited without a session_end, as one would */
+  endExited(now = this.now()) {
+    for (const row of this.sql.all(
+      `SELECT * FROM endpoints WHERE kind = 'agent' AND connections = 0 AND hook_seen IS NOT NULL AND process IS NOT NULL`
+    )) {
+      const pid = Number(/^pid:(\d+)/.exec(row.process)?.[1]);
+      if (!pid || !this.localRow(row) || this.alive(pid)) continue;
+      this.sql.all(`UPDATE endpoints SET hook_seen = NULL, hook_ended = ?, session = NULL WHERE id = ? AND connections = 0`, now, row.id);
+    }
+  }
   /** an agent endpoint left offline drops a working or waiting status, which no one is left to keep current */
   settleOffline(now) {
     for (const row of this.sql.all(
@@ -3263,15 +3422,19 @@ var RelayCore = class {
           endpoint
         );
     } else if (params.kind === "session_start") {
+      const fresh = own && summary !== "compact" && summary !== "resume";
       this.sql.all(
         `UPDATE endpoints SET hook_seen = COALESCE(?, hook_seen), hook_ended = NULL, stop_blocks = CASE WHEN ? THEN 0 ELSE stop_blocks END, pushes = CASE WHEN ? THEN 0 ELSE pushes END,
-         briefed = CASE WHEN ? THEN NULL ELSE briefed END, introduced = CASE WHEN ? THEN NULL ELSE introduced END, directive_holds = CASE WHEN ? THEN NULL ELSE directive_holds END WHERE id = ?`,
+         briefed = CASE WHEN ? THEN NULL ELSE briefed END, introduced = CASE WHEN ? THEN NULL ELSE introduced END, directive_holds = CASE WHEN ? THEN NULL ELSE directive_holds END,
+         title = CASE WHEN ? AND title = title_auto THEN NULL ELSE title END, title_auto = CASE WHEN ? THEN NULL ELSE title_auto END WHERE id = ?`,
         options.transient ? now : null,
         own ? 1 : 0,
         own ? 1 : 0,
         own ? 1 : 0,
         own ? 1 : 0,
         own ? 1 : 0,
+        fresh ? 1 : 0,
+        fresh ? 1 : 0,
         endpoint
       );
     } else if (options.transient) {
@@ -4985,7 +5148,7 @@ ${stderr}` : "";
   }
   /** the user parts an address of this core may carry */
   addressUsers() {
-    return [this.user, "me"];
+    return [this.user, "me", "local"];
   }
   /** whether the row is this host's own, the only rows with a tree, groups, rules and caps here */
   localRow(_row) {
@@ -4997,7 +5160,7 @@ ${stderr}` : "";
     const slash = text.indexOf("/");
     const user = slash === -1 ? null : text.slice(0, slash);
     const handle = slash === -1 ? text : text.slice(slash + 1);
-    if (user !== null && user !== "me" && user !== this.user) throw unreachable(text);
+    if (user !== null && user !== "me" && user !== "local" && user !== this.user) throw unreachable(text);
     const row = handle === "" ? this.byHandle(HUMAN_HANDLE) : validHandle(handle) ? this.byHandle(handle) : void 0;
     if (!row) throw unreachable(text);
     return row;
@@ -6054,6 +6217,7 @@ export {
   SHORT_ID,
   STATUS_STATES,
   SYSTEM_HANDLE,
+  TITLE_CHARS,
   VerdictCache,
   XCounters,
   XLIMITS,

package/package.json

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

@@ -69,6 +69,8 @@ import { one, type Sql, type SqlValue } from "./sql"
 import { utf8Bytes } from "./utf8"
 
 export const HUMAN_HANDLE = "_human"
+/** an agent title's length cap */
+export const TITLE_CHARS = 64
 export const SYSTEM_HANDLE = "_relay"
 export const GONE_PREFIX = "_gone_"
 
@@ -240,12 +242,20 @@ export interface EndpointRow {
   /** JSON {@link ScopeCaps} */
   caps: string | null
   title: string | null
+  /** the title a hook last inferred: the title is inferred while it equals this */
+  title_auto: string | null
+  /** the prompt count when a summary last set the inferred title; null when the first prompt set it */
+  title_turn: number | null
+  /** the prompt count when the status note last changed or a hook last reminded the agent to refresh it */
+  tldr_turn: number | null
   /** when a new spawn last took the endpoint over: mail and messages from before it were the earlier holder's */
   reset_at: number | null
   /** when a new spawn last took the endpoint over: with its id, names the holder another machine sees */
   spawned_at: number | null
   /** who may peek: null is off */
   peek: PeekLevel | null
+  /** when the session last set its handle itself (join or rename): a later claim with another handle does not rename it back */
+  named: number | null
 }
 
 export interface MessageRow {
@@ -442,6 +452,8 @@ export class RelayCore {
   private readonly capEverySender: boolean
   private readonly alive: (pid: number) => boolean
   private readonly hostMachine: string | null
+  private readonly namedMachine: string | null
+  private readonly hostname: string | null
   private policy: Policy | null = null
   /** the identity each policy `group:<name>` naming no policy group bound to when the policy's text first loaded: that group's then, or `none` */
   private policyBinds = new Map<string, string>()
@@ -461,6 +473,14 @@ export class RelayCore {
     this.capEverySender = options.capEverySender === true
     this.alive = options.alive ?? (() => true)
     this.hostMachine = options.machine ?? options.hostname ?? null
+    this.namedMachine = options.machine ?? null
+    this.hostname = options.hostname ?? null
+  }
+
+  /** a `machine` label naming this host by its hostname, as clients default it, names it by its machine name when one is set */
+  private machineLabel(labels: Record<string, string>): Record<string, string> {
+    if (this.namedMachine !== null && labels.machine !== undefined && labels.machine === this.hostname) labels.machine = this.namedMachine
+    return labels
   }
 
   migrate(): void {
@@ -496,6 +516,10 @@ export class RelayCore {
       ["directive_holds", "INTEGER"],
       ["harness_session", "TEXT"],
       ["harness_transcript", "TEXT"],
+      ["title_auto", "TEXT"],
+      ["title_turn", "INTEGER"],
+      ["tldr_turn", "INTEGER"],
+      ["named", "INTEGER"],
     ] as const) {
       if (!endpointColumns.includes(column)) this.sql.all(`ALTER TABLE endpoints ADD COLUMN ${column} ${type}`)
     }
@@ -658,7 +682,7 @@ export class RelayCore {
       model: cleanText(claim.model, "model", 128),
       cwd: cleanText(claim.cwd, "cwd", 1024),
       parent: cleanText(claim.parent, "parent", 128),
-      labels: JSON.stringify(cleanLabels(claim.labels)),
+      labels: JSON.stringify(this.machineLabel(cleanLabels(claim.labels))),
       session: cleanText(claim.session, "session", 128),
       process: cleanText(claim.process, "process", 128),
     }
@@ -773,6 +797,7 @@ export class RelayCore {
     scope: ClaimScope = { handle: wanted, lineage: [], grant: null, rules: {}, groups: [], cwd: fields.cwd },
   ): { endpoint: EndpointView; token?: string; created?: true } {
     const now = this.now()
+    this.endExited(now)
     const bare = transient && fields.session !== null && BARE_PID_KEY.test(fields.session)
     let row = fields.session
       ? one<EndpointRow>(
@@ -798,7 +823,14 @@ export class RelayCore {
     } else if (row && !transient && !sameProcess(row, fields.process)) {
       row = undefined
       session = null
-    } else if (row && !transient && row.token_hash === null && row.handle !== wanted && !row.handle.startsWith(`${wanted.slice(0, 58)}-`)) {
+    } else if (
+      row &&
+      !transient &&
+      row.token_hash === null &&
+      row.named === null &&
+      row.handle !== wanted &&
+      !row.handle.startsWith(`${wanted.slice(0, 58)}-`)
+    ) {
       const hooks = row
       let settled = false
       for (let n = 1; n < (scope.exact ? 2 : 1000) && !settled; n++) {
@@ -1297,6 +1329,7 @@ export class RelayCore {
     } = {},
   ): EndpointView[] {
     const now = this.now()
+    this.endExited(now)
     this.settleOffline(now)
     const cutoff = now - LIMITS.listOfflineWithinS * 1000
     const viewer = filters.viewer === undefined ? undefined : this.mustEndpoint(filters.viewer)
@@ -1364,10 +1397,12 @@ export class RelayCore {
     const text = oneLine(note, "note", LIMITS.noteChars)
     if (text && findSecret(text)) throw this.refuse(endpoint, "secret_refused", "the status note looks like it carries a credential")
     this.sql.all(
-      `UPDATE endpoints SET status_state = COALESCE(?, status_state, 'working'), status_note = COALESCE(?, status_note, ''), last_seen = ? WHERE id = ?`,
+      `UPDATE endpoints SET status_state = COALESCE(?, status_state, 'working'), status_note = COALESCE(?, status_note, ''), last_seen = ?,
+       tldr_turn = CASE WHEN ? THEN COALESCE(prompts, 0) ELSE tldr_turn END WHERE id = ?`,
       state ?? null,
       text,
       this.now(),
+      text === null ? 0 : 1,
       endpoint,
     )
   }
@@ -1378,11 +1413,126 @@ export class RelayCore {
     if (row.kind !== "agent") throw new RelayError("invalid_params", "only an agent endpoint has a title")
     const title = oneLine(value, "title", 64) || null
     if (title && findSecret(title)) throw this.refuse(endpoint, "secret_refused", "the title looks like it carries a credential")
-    this.sql.all(`UPDATE endpoints SET title = ? WHERE id = ?`, title, endpoint)
+    this.sql.all(`UPDATE endpoints SET title = ?, title_auto = NULL, title_turn = NULL WHERE id = ?`, title, endpoint)
     this.audit("title", endpoint, null, { title })
     return this.whoami(endpoint)
   }
 
+  /**
+   * a hook's guess at the session's title, from the harness's own summary or the first prompt's first line; whether it changed the title.
+   * Never over a title set explicitly; the first prompt fills only an empty title, and a summary replaces an inferred one at most every
+   * ${LIMITS.titleRefreshTurns} prompts, or at once over the first prompt's
+   */
+  inferTitle(endpoint: string, params: { text?: unknown; from?: unknown }, options: { transient?: boolean; process?: string } = {}): boolean {
+    if (params.from !== "summary" && params.from !== "prompt") throw new RelayError("invalid_params", "from is summary or prompt")
+    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
+    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
+    if (params.from === "summary" && row.title !== null && row.title_turn !== null && turn - row.title_turn < LIMITS.titleRefreshTurns) return false
+    this.sql.all(`UPDATE endpoints SET title = ?, title_auto = ?, title_turn = ? WHERE id = ?`, title, title, params.from === "summary" ? turn : null, endpoint)
+    return true
+  }
+
+  /**
+   * 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
+   */
+  joinSession(claim: Claim, handle?: unknown): EndpointView {
+    return this.scopeTx(() => {
+      const { endpoint } = this.claim(claim, { transient: true })
+      const row = this.mustEndpoint(endpoint.id)
+      if (handle !== undefined && handle !== null && handle !== "") this.renameRow(row, handle, false)
+      this.sql.all(`UPDATE endpoints SET hook_seen = ?, hook_ended = NULL WHERE id = ?`, this.now(), row.id)
+      this.audit("join", row.id, null, { handle: this.byId(row.id)!.handle })
+      return this.whoami(row.id)
+    })
+  }
+
+  /**
+   * renames an agent in place: its id, mail, threads, status, title and relations stay. An agent renames only itself, and only a root unless
+   * the policy's `defaults.rename` is `self`; the human at a terminal renames any local agent. The new handle is valid and held by no other endpoint
+   */
+  rename(actor: ScopeActor, params: { endpoint?: unknown; handle: unknown }): { endpoint: EndpointView; from: string; session: string | null } {
+    return this.scopeTx(() => {
+      const me = this.actorRow(actor)
+      if (actor.kind === "human") this.needTerminal(actor, me, params.endpoint)
+      else if (actor.auth === "lineage") throw new RelayError("scope_refused", "only the session itself renames it: run this from the session's own shell")
+      const target = params.endpoint === undefined ? me : this.resolve(params.endpoint)
+      if (actor.kind !== "human" && target.id !== me.id) throw new RelayError("scope_refused", "an agent renames only itself")
+      if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint can be renamed")
+      this.renameRow(target, params.handle, actor.kind === "human")
+      return { endpoint: this.whoami(target.id), from: target.handle, session: target.session }
+    })
+  }
+
+  /** the endpoint's handle set to `value`, with the stored `ep:` and `fleet:` selectors that named it */
+  private renameRow(row: EndpointRow, value: unknown, byHuman: boolean): void {
+    const handle = typeof value === "string" ? value.trim().replace(/^me\//, "") : ""
+    if (!validHandle(handle)) throw new RelayError("invalid_params", `handle ${JSON.stringify(handle)} is not valid: lowercase letters, digits, . _ -`)
+    if (findSecret(handle)) throw new RelayError("secret_refused", "the handle looks like it carries a credential")
+    if (handle === row.handle) {
+      this.sql.all(`UPDATE endpoints SET named = COALESCE(named, ?) WHERE id = ?`, this.now(), row.id)
+      return
+    }
+    if (!byHuman && row.parent_ep !== null && this.policy?.defaults?.rename !== "self") {
+      const parent = this.byId(row.parent_ep)
+      throw new RelayError("scope_refused", `spawned by ${parent ? this.address(parent) : "another agent"}; its name is set by the spawner`)
+    }
+    const held = this.byHandle(handle)
+    if (held) {
+      const how = held.kind !== "agent" ? "reserved" : presenceOf(held, this.now()) === "offline" ? "held by an offline endpoint" : "held by a live endpoint"
+      throw new RelayError("invalid_params", `${handle} is ${how}: pick another name`)
+    }
+    const from = row.handle
+    this.sql.all(`UPDATE endpoints SET handle = ?, named = ? WHERE id = ?`, handle, this.now(), row.id)
+    this.sql.all(`UPDATE grants SET name = ? WHERE used_by = ? AND name = ?`, handle, row.id, from)
+    for (const prefix of row.parent_ep === null ? ["ep:", "fleet:"] : ["ep:"]) {
+      const [a, b] = [JSON.stringify(`${prefix}${from}`), JSON.stringify(`${prefix}${handle}`)]
+      for (const [table, column] of [
+        ["endpoints", "rules"],
+        ["endpoints", "caps"],
+        ["groups", "rules"],
+        ["grants", "caps"],
+      ] as const)
+        this.sql.all(`UPDATE ${table} SET ${column} = REPLACE(${column}, ?, ?) WHERE instr(${column}, ?) > 0`, a, b, a)
+    }
+    this.audit("rename", row.id, null, { from, to: handle })
+  }
+
+  /**
+   * a session leaves: it lets go of its session and token and shows offline, its mail kept; a later join takes it back. An agent leaves only
+   * itself, the human at a terminal any local root. A spawned worker stays joined while it runs
+   */
+  leaveSession(actor: ScopeActor, params: { endpoint?: unknown } = {}): { endpoint: EndpointView; session: string | null } {
+    return this.scopeTx(() => {
+      const me = this.actorRow(actor)
+      if (actor.kind === "human") this.needTerminal(actor, me, params.endpoint)
+      else if (actor.auth === "lineage") throw new RelayError("scope_refused", "only the session itself leaves: run this from the session's own shell")
+      const target = params.endpoint === undefined ? me : this.resolve(params.endpoint)
+      if (actor.kind !== "human" && target.id !== me.id) throw new RelayError("scope_refused", "an agent leaves only for itself")
+      if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint can leave")
+      if (target.parent_ep !== null) {
+        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.audit("leave", target.id, null, { handle: target.handle })
+      return { endpoint: this.whoami(target.id), session: target.session }
+    })
+  }
+
+  /** the harness session key an endpoint holds, if any */
+  sessionOf(endpoint: string): string | null {
+    return this.byId(endpoint)?.session ?? null
+  }
+
   // messages
 
   /**
@@ -1443,6 +1593,17 @@ export class RelayCore {
       resolved.push(row)
     }
     const recipients = [...new Map(resolved.map((row) => [row.id, row])).values()]
+    if (params.live !== undefined && typeof params.live !== "boolean") throw new RelayError("invalid_params", "live must be true or false")
+    const dark = recipients.filter(
+      (r) =>
+        r.kind === "agent" &&
+        presenceOf(r, now) === "offline" &&
+        (now - Math.max(r.last_seen ?? 0, r.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS || (r.session === null && r.token_hash === null && r.hook_ended !== null)) &&
+        !this.unjoinedSpawn(sender, r.handle, now),
+    )
+    if (params.live === true && dark.length)
+      throw new RelayError("not_live", `no live session holds ${dark.map((r) => this.address(r)).join(", ")}: nothing was queued`)
+    const warnings = dark.map((r) => `queued: no live session holds ${this.address(r)}`)
     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}`)
@@ -1672,7 +1833,7 @@ export class RelayCore {
         deliveries.push({ endpoint: key, address, seq, offline: false, queued: true, last_seen: null, state: "starting" })
       }
       for (const name of fanOut) this.sql.all(`INSERT INTO tree_events (tree, at) VALUES (?, ?)`, `group:${name}`, now)
-      const sent: SendResult = { id, thread, hop, deliveries }
+      const sent: SendResult = { id, thread, hop, deliveries, ...(warnings.length ? { warnings } : {}) }
       if (clientId) {
         this.sql.all(
           `INSERT OR REPLACE INTO idempotency (from_ep, client_id, payload_hash, result, created_at) VALUES (?, ?, ?, ?, ?)`,
@@ -1819,10 +1980,11 @@ export class RelayCore {
    * `directive_seqs`. Any call says `brief` once the session was shown the full preamble ({@link briefed}), and one that is no stop names in
    * `intro` the spawner of an endpoint a `swarm spawn` grant placed, with the grant's steer key in `intro_key`, until a hook showed it
    * ({@link introduced}). A hook of another process than the one holding the endpoint (a child that inherited the session key) gets nothing.
+   * A wake also offers live workers' messages.
    */
   inject(
     endpoint: string,
-    options: { stop?: boolean; count?: boolean; holdUnread?: boolean; directives?: boolean; transient?: boolean; process?: string } = {},
+    options: { stop?: boolean; count?: boolean; holdUnread?: boolean; directives?: boolean; transient?: boolean; process?: string; wake?: boolean } = {},
   ): {
     messages: Envelope[]
     offered: number[]
@@ -1912,7 +2074,7 @@ export class RelayCore {
       now,
       LIMITS.inboxPage,
     )
-    const { shown, offered } = this.budget(rows, LIMITS.injectBytes, () => this.pushable(me, now))
+    const { shown, offered } = this.budget(rows, LIMITS.injectBytes, options.wake ? undefined : () => this.pushable(me, now))
     const hold = this.hold(offered, now)
     this.received(endpoint, shown, now)
     return { messages: shown.map((row) => this.envelope(row, row.seq)), offered, hold, more: waiting - shown.length, unread, block: false, ...brief, ...intro }
@@ -2100,6 +2262,16 @@ export class RelayCore {
     return true
   }
 
+  /** whether a prompt should remind the agent to refresh its status note: `every` prompts passed since the note or the last reminder; counts the reminder */
+  tldrDue(endpoint: string, every: number): boolean {
+    if (!Number.isInteger(every) || every <= 0) return false
+    const row = this.mustEndpoint(endpoint)
+    const turn = row.prompts ?? 0
+    if (row.kind !== "agent" || turn - (row.tldr_turn ?? 0) < every) return false
+    this.sql.all(`UPDATE endpoints SET tldr_turn = ? WHERE id = ?`, turn, endpoint)
+    return true
+  }
+
   /** the background hooks' showings ({@link injected}) older than ${LIMITS.deferredSettleMs} ms reached the agent: inbox no longer lists them */
   private settle(endpoint: string): void {
     this.sql.all(
@@ -2612,6 +2784,7 @@ export class RelayCore {
     this.sql.all(`DELETE FROM idempotency WHERE created_at <= ?`, now - LIMITS.idempotencyS * 1000)
     this.sql.all(`DELETE FROM pair_events WHERE at <= ?`, now - 3600 * 1000)
     this.sql.all(`DELETE FROM blocks WHERE until <= ?`, now)
+    this.endExited(now)
     this.settleOffline(now)
     this.sql.all(
       `DELETE FROM endpoints WHERE kind = 'agent' AND connections = 0 AND COALESCE(last_seen, created_at) <= ?
@@ -2638,6 +2811,17 @@ export class RelayCore {
     }
   }
 
+  /** ends the hook presence of local agent endpoints whose harness process exited without a session_end, as one would */
+  endExited(now = this.now()): void {
+    for (const row of this.sql.all<EndpointRow>(
+      `SELECT * FROM endpoints WHERE kind = 'agent' AND connections = 0 AND hook_seen IS NOT NULL AND process IS NOT NULL`,
+    )) {
+      const pid = Number(/^pid:(\d+)/.exec(row.process!)?.[1])
+      if (!pid || !this.localRow(row) || this.alive(pid)) continue
+      this.sql.all(`UPDATE endpoints SET hook_seen = NULL, hook_ended = ?, session = NULL WHERE id = ? AND connections = 0`, now, row.id)
+    }
+  }
+
   /** an agent endpoint left offline drops a working or waiting status, which no one is left to keep current */
   private settleOffline(now: number): void {
     for (const row of this.sql.all<EndpointRow>(
@@ -2697,15 +2881,19 @@ export class RelayCore {
           endpoint,
         )
     } else if (params.kind === "session_start") {
+      const fresh = own && summary !== "compact" && summary !== "resume"
       this.sql.all(
         `UPDATE endpoints SET hook_seen = COALESCE(?, hook_seen), hook_ended = NULL, stop_blocks = CASE WHEN ? THEN 0 ELSE stop_blocks END, pushes = CASE WHEN ? THEN 0 ELSE pushes END,
-         briefed = CASE WHEN ? THEN NULL ELSE briefed END, introduced = CASE WHEN ? THEN NULL ELSE introduced END, directive_holds = CASE WHEN ? THEN NULL ELSE directive_holds END WHERE id = ?`,
+         briefed = CASE WHEN ? THEN NULL ELSE briefed END, introduced = CASE WHEN ? THEN NULL ELSE introduced END, directive_holds = CASE WHEN ? THEN NULL ELSE directive_holds END,
+         title = CASE WHEN ? AND title = title_auto THEN NULL ELSE title END, title_auto = CASE WHEN ? THEN NULL ELSE title_auto END WHERE id = ?`,
         options.transient ? now : null,
         own ? 1 : 0,
         own ? 1 : 0,
         own ? 1 : 0,
         own ? 1 : 0,
         own ? 1 : 0,
+        fresh ? 1 : 0,
+        fresh ? 1 : 0,
         endpoint,
       )
     } else if (options.transient) {
@@ -4657,7 +4845,7 @@ export class RelayCore {
 
   /** the user parts an address of this core may carry */
   protected addressUsers(): string[] {
-    return [this.user, "me"]
+    return [this.user, "me", "local"]
   }
 
   /** whether the row is this host's own, the only rows with a tree, groups, rules and caps here */
@@ -4671,7 +4859,7 @@ export class RelayCore {
     const slash = text.indexOf("/")
     const user = slash === -1 ? null : text.slice(0, slash)
     const handle = slash === -1 ? text : text.slice(slash + 1)
-    if (user !== null && user !== "me" && user !== this.user) throw unreachable(text)
+    if (user !== null && user !== "me" && user !== "local" && user !== this.user) throw unreachable(text)
     const row = handle === "" ? this.byHandle(HUMAN_HANDLE) : validHandle(handle) ? this.byHandle(handle) : undefined
     if (!row) throw unreachable(text)
     return row

package/src/index.ts

@@ -9,6 +9,7 @@ export {
   RelayCore,
   seqList,
   SYSTEM_HANDLE,
+  TITLE_CHARS,
   unreachable,
   type CoreOptions,
   type EndpointRow,

package/src/policy.ts

@@ -36,6 +36,8 @@ export interface PolicyDefaults {
   /** `inherit`: a child of a capped parent reaches only what the parent reaches; a preset caps every placed child without grant caps */
   child_default?: ScopePreset | "inherit"
   verify_lineage?: "spike" | boolean
+  /** who may rename an agent besides the human at a terminal: `root` (default) only a root session itself, `self` any agent itself, spawned ones too */
+  rename?: "root" | "self"
 }
 
 export interface Policy {
@@ -164,7 +166,7 @@ export function parsePolicy(value: unknown, options: { judgeProviders?: Readonly
   }
   if (defaults !== undefined) {
     if (!isObject(defaults)) throw new RelayError("invalid_params", "defaults is an object")
-    const { human_always, symmetric_presets, child_default, verify_lineage, ...extra } = defaults
+    const { human_always, symmetric_presets, child_default, verify_lineage, rename, ...extra } = defaults
     if (Object.keys(extra).length) throw new RelayError("invalid_params", `unknown defaults: ${Object.keys(extra).join(", ")}`)
     const parsed: PolicyDefaults = {}
     for (const [key, flag] of [
@@ -188,6 +190,10 @@ export function parsePolicy(value: unknown, options: { judgeProviders?: Readonly
         throw new RelayError("invalid_params", "defaults.verify_lineage true needs the peer-pid check, which this relay does not have yet: use spike or false")
       parsed.verify_lineage = verify_lineage
     }
+    if (rename !== undefined) {
+      if (rename !== "root" && rename !== "self") throw new RelayError("invalid_params", "defaults.rename is root or self")
+      parsed.rename = rename
+    }
     policy.defaults = parsed
   }
   if (judge !== undefined) policy.judge = parseJudgePolicy(judge, options.judgeProviders)

package/src/protocol.ts

@@ -73,6 +73,8 @@ export const LIMITS = {
   grantTtlS: 7 * 86_400,
   groupIdleS: 86_400,
   policyLoadsKept: 8,
+  /** the prompts between two refreshes of a title a hook inferred */
+  titleRefreshTurns: 5,
 } as const
 
 export type ErrorCode =
@@ -90,6 +92,7 @@ export type ErrorCode =
   | "scope_refused"
   | "unavailable"
   | "judge_refused"
+  | "not_live"
 
 export class RelayError extends Error {
   constructor(
@@ -386,6 +389,8 @@ export interface SendParams {
   mime?: string
   /** on a request only: the recipient's stop is held until it replies */
   require_reply?: boolean
+  /** refuse `not_live`, queueing nothing, when an agent recipient has no live session */
+  live?: boolean
 }
 
 /** what ask and ask_wait answer: the reply; or pending, with `ended` once every recipient present at the send went offline without replying; or expired */
@@ -429,6 +434,8 @@ export interface SendResult {
    * offline; `state`: an agent recipient's {@link Reach} on this machine (an older broker leaves it out)
    */
   deliveries: { endpoint: string; address: string; seq: number; offline: boolean; queued?: boolean; last_seen: string | null; state?: Reach }[]
+  /** one line per agent recipient no live session holds: `queued: no live session holds <address>` */
+  warnings?: string[]
   duplicate?: boolean
   held?: JudgeHeld
   redacted?: JudgeRedacted