@namzu/sdk 27.0.0 → 28.0.0

package/dist/{gateway → scheduler}/completion-inbox.js

@@ -1,6 +1,7 @@
 import { wrapUntrusted } from '../tools/untrusted-envelope.js';
 import { isTerminalAgentTaskState } from '../types/agent/task.js';
-import { getRootLogger } from '../utils/logger.js';
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js';
+import { resolveLogger } from '../utils/logger.js';
 /**
  * How many unclaimed announcements may wait for an owner at once.
  *
@@ -48,11 +49,12 @@ const UNOWNED_BUFFER_LIMIT = 32;
  * Claiming is what tells the two apart: a tool that delivers a completion
  * says so, and only unclaimed completions become envelopes.
  *
- * It attaches through `onTaskCompleted`, which every `TaskGateway` already
+ * It attaches through `onTaskCompleted`, which every `TaskScheduler` already
  * has, so a host gateway needs no change to take part — a host that was
  * firing completions into a listener set with no listeners now has one.
  */
 export class CompletionInbox {
+    log;
     unheard = new Map();
     claimed = new Set();
     /** Launched with nothing waiting on it, and not settled yet. */
@@ -77,7 +79,7 @@ export class CompletionInbox {
      *
      * `gateway.createTask` resolves one microtask before its caller can name
      * the task, and a worker that finishes inside that window is announced
-     * first — `LocalTaskGateway` attaches its completion continuation before
+     * first — `LocalTaskScheduler` attaches its completion continuation before
      * it returns the handle, so the ordering is guaranteed to be reachable
      * rather than merely possible. Dropping an unowned announcement outright
      * would therefore turn the leak fix into a LOST RESULT for exactly the
@@ -93,6 +95,13 @@ export class CompletionInbox {
     detach;
     /** Kept for {@link launched}: the source of truth about a task's state. */
     gateway;
+    /**
+     * `log` is optional and unresolved until it is actually needed (the
+     * eviction-warning path in `hold()`), same reason as `LocalTaskScheduler`.
+     */
+    constructor(log) {
+        this.log = log;
+    }
     /**
      * Start listening.
      *
@@ -142,9 +151,12 @@ export class CompletionInbox {
             const oldest = this.unowned.keys().next();
             if (!oldest.done) {
                 this.unowned.delete(oldest.value);
-                getRootLogger()
-                    .child({ component: 'CompletionInbox' })
-                    .warn("Unclaimed completion buffer is full — dropped the oldest. If that task was this run's, its result is now unreachable; raise UNOWNED_BUFFER_LIMIT or launch fewer tasks per turn.", { dropped: oldest.value, limit: UNOWNED_BUFFER_LIMIT });
+                resolveLogger(this.log)
+                    .child({ [SCOPE_ATTRIBUTE]: 'scheduler/completion-inbox' })
+                    .warn("Unclaimed completion buffer is full — dropped the oldest. If that task was this run's, its result is now unreachable; raise UNOWNED_BUFFER_LIMIT or launch fewer tasks per turn.", {
+                    'namzu.scheduler.dropped': oldest.value,
+                    'namzu.scheduler.limit': UNOWNED_BUFFER_LIMIT,
+                });
             }
         }
         this.unowned.set(handle.taskId, handle);
@@ -169,7 +181,7 @@ export class CompletionInbox {
      * announcement it already made. Asking `getTask` covers the case the
      * buffer cannot — an announcement evicted under load — but it rests on a
      * gateway still knowing about a task it has just settled, which is a
-     * property of the implementations here rather than of the `TaskGateway`
+     * property of the implementations here rather than of the `TaskScheduler`
      * contract, and `getTask`'s own docs now say so.
      */
     launched(taskId) {

package/dist/scheduler/completion-inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-inbox.js","sourceRoot":"","sources":["../../src/scheduler/completion-inbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAE9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AAEjE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAe,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,oBAAoB,GAAG,EAAE,CAAA;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,eAAe;IA8CE;IA7CZ,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAA;IACvC,OAAO,GAAG,IAAI,GAAG,EAAU,CAAA;IAC5C,gEAAgE;IAC/C,WAAW,GAAG,IAAI,GAAG,EAAU,CAAA;IAChD;;;;;;;;;;;;;OAaG;IACc,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IACzC;;;;;;;;;;;;;;;OAeG;IACc,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAA;IACvC,QAAQ,GAAG,IAAI,GAAG,EAAc,CAAA;IACzC,MAAM,CAAa;IAC3B,2EAA2E;IACnE,OAAO,CAAgB;IAE/B;;;OAGG;IACH,YAA6B,GAAY;QAAZ,QAAG,GAAH,GAAG,CAAS;IAAG,CAAC;IAE7C;;;;;;;OAOG;IACH,MAAM,CAAC,OAAsB;QAC5B,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC,MAAM,CAAA;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QACtB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,MAAM,EAAE,EAAE;YAChD,iEAAiE;YACjE,kEAAkE;YAClE,8DAA8D;YAC9D,mDAAmD;YACnD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;gBACnC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;gBACjB,OAAM;YACP,CAAC;YACD,6DAA6D;YAC7D,8DAA8D;YAC9D,+BAA+B;YAC/B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YACtC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC;gBAAE,OAAM;YAC3C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;YACvC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,QAAQ;gBAAE,IAAI,EAAE,CAAA;QACzC,CAAC,CAAC,CAAA;QACF,OAAO,IAAI,CAAC,MAAM,CAAA;IACnB,CAAC;IAED;;;;;;;;;;OAUG;IACK,IAAI,CAAC,MAAkB;QAC9B,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,oBAAoB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YACnF,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAA;YACzC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBAClB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBACjC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;qBACrB,KAAK,CAAC,EAAE,CAAC,eAAe,CAAC,EAAE,4BAA4B,EAAE,CAAC;qBAC1D,IAAI,CACJ,kLAAkL,EAClL;oBACC,yBAAyB,EAAE,MAAM,CAAC,KAAK;oBACvC,uBAAuB,EAAE,oBAAoB;iBAC7C,CACD,CAAA;YACH,CAAC;QACF,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,MAAc;QACtB,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAM;QACjC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QAErB,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAM;QAEhE,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QACvC,IAAI,MAAM,EAAE,CAAC;YACZ,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YAC3B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;YAChC,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;gBAAE,IAAI,EAAE,CAAA;YAC7C,OAAM;QACP,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;QAC7C,IAAI,CAAC,OAAO,IAAI,CAAC,wBAAwB,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAM;QAChE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACjC,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;YAAE,IAAI,EAAE,CAAA;IAC9C,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAc;QACpB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;QACrB,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAM;QACpC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAC7B,CAAC;IAED,sEAAsE;IACtE,IAAI,cAAc;QACjB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,GAAG,CAAC,CAAA;IAC1D,CAAC;IAED;;;;;;OAMG;IACH,cAAc,CAAC,SAAiB;QAC/B,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC;YAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;QACnD,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;QAEzD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC9B,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,SAAS,CAAC,CAG1C;YAAC,KAAgC,CAAC,KAAK,EAAE,EAAE,CAAA;YAE5C,SAAS,MAAM;gBACd,YAAY,CAAC,KAAK,CAAC,CAAA;gBACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;gBAChB,OAAO,EAAE,CAAA;YACV,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CACzB,GAAG,EAAE;gBACJ,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;oBAChB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;oBAC1B,MAAM,EAAE,CAAA;gBACT,CAAC;YACF,CAAC,EACD,EAAE,IAAI,EAAE,KAAK,EAAE,CACf,CAAA;YACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACxB,CAAC,CAAC,CAAA;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAc;QACnB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QACxB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC3B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAChC,CAAC;IAED,8CAA8C;IAC9C,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,CAAA;IAC7B,CAAC;IAED;;;;;;OAMG;IACH,IAAI,kBAAkB;QACrB,OAAO,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAA;IAC7B,CAAC;IAED;;;;;OAKG;IACH,KAAK;QACJ,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,EAAE,CAAA;QACtC,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;QAC1C,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QACpB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC9B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YAC/B,gEAAgE;YAChE,iEAAiE;YACjE,gEAAgE;YAChE,kEAAkE;YAClE,kEAAkE;YAClE,iEAAiE;YACjE,iEAAiE;YACjE,mEAAmE;YACnE,+DAA+D;YAC/D,oEAAoE;YACpE,EAAE;YACF,+DAA+D;YAC/D,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACvC,CAAC;QACD,OAAO,OAAO,CAAA;IACf,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAc;QACpB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC/B,yCAAyC;QACzC,EAAE;QACF,qEAAqE;QACrE,oEAAoE;QACpE,qEAAqE;QACrE,kEAAkE;QAClE,0CAA0C;QAC1C,EAAE;QACF,mEAAmE;QACnE,iEAAiE;QACjE,iEAAiE;QACjE,uEAAuE;QACvE,qEAAqE;QACrE,EAAE;QACF,uEAAuE;QACvE,oEAAoE;QACpE,uCAAuC;QACvC,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;YAAE,IAAI,EAAE,CAAA;IAC9C,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK;QACJ,IAAI,CAAC,MAAM,EAAE,EAAE,CAAA;QACf,IAAI,CAAC,MAAM,GAAG,SAAS,CAAA;QACvB,IAAI,CAAC,OAAO,GAAG,SAAS,CAAA;QACxB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QACpB,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAA;QACxB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAA;QACjB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QACpB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QACpB,oEAAoE;QACpE,uEAAuE;QACvE,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;YAAE,IAAI,EAAE,CAAA;QAC7C,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAA;IACtB,CAAC;CACD;AAED,sEAAsE;AACtE,MAAM,yBAAyB,GAAG,KAAK,CAAA;AAEvC,MAAM,sBAAsB,GAAG,qBAAqB,CAAA;AAEpD;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAS,+BAA+B,CAAC,OAAe;IACvD,OAAO,OAAO,CAAC,OAAO,CAAC,sBAAsB,EAAE,mBAAmB,CAAC,CAAA;AACpE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,4BAA4B,CAAC,OAA8B;IAC1E,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QACrC,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAA;QACzF,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAA;QACtE,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,GAAG,yBAAyB,CAAA;QAC3D,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,yBAAyB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;QAE7E,mEAAmE;QACnE,uEAAuE;QACvE,uEAAuE;QACvE,oEAAoE;QACpE,sEAAsE;QACtE,oEAAoE;QACpE,oEAAoE;QACpE,EAAE;QACF,wEAAwE;QACxE,sEAAsE;QACtE,uEAAuE;QACvE,8BAA8B;QAC9B,MAAM,IAAI,GACT,KAAK,CAAC,MAAM,GAAG,CAAC;YACf,CAAC,CAAC,aAAa,CACb;gBACC,IAAI,EAAE,cAAc;gBACpB,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE;gBAC1D,UAAU,EAAE,8CAA8C,MAAM,CAAC,OAAO,+BAA+B;aACvG,EACD,+BAA+B,CAAC,KAAK,CAAC,CACtC;YACF,CAAC,CAAC,+BAA+B,CAAA;QAEnC,MAAM,KAAK,GAAG;YACb,YAAY,MAAM,CAAC,MAAM,EAAE;YAC3B,UAAU,MAAM,CAAC,OAAO,EAAE;YAC1B,UAAU,MAAM,CAAC,KAAK,EAAE;YACxB,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,gBAAgB,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,EAAE;YACF,IAAI;YACJ,0DAA0D;YAC1D,oEAAoE;YACpE,6DAA6D;YAC7D,4BAA4B;YAC5B,EAAE;YACF,oEAAoE;YACpE,oEAAoE;YACpE,iEAAiE;YACjE,sDAAsD;YACtD,GAAG,CAAC,SAAS;gBACZ,CAAC,CAAC,CAAC,iDAAiD,MAAM,CAAC,MAAM,wBAAwB,CAAC;gBAC1F,CAAC,CAAC,EAAE,CAAC;SACN,CAAA;QACD,OAAO,wBAAwB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,wBAAwB,CAAA;IACxE,CAAC,CAAC,CAAA;IAEF,MAAM,QAAQ,GACb,OAAO,CAAC,MAAM,KAAK,CAAC;QACnB,CAAC,CAAC,qIAAqI;QACvI,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,6IAA6I,CAAA;IAElK,OAAO,GAAG,QAAQ,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAA;AAC/C,CAAC"}

package/dist/scheduler/delegating.d.ts

@@ -0,0 +1,90 @@
+import type { Delegate } from '../types/agent/delegate.js';
+import type { CreateTaskOptions, TaskHandle, TaskScheduler } from '../types/agent/scheduler.js';
+import type { TaskId } from '../types/ids/index.js';
+/**
+ * Presents a set of foreign delegates as a `TaskScheduler`.
+ *
+ * The two delegation tools, the completion inbox and the sibling-failure
+ * policy all speak `TaskScheduler`, and none of them should have to learn
+ * that a specialist moved out of process. So the seam is here rather than
+ * in the tools: an id this knows about is dispatched to its `Delegate`, and
+ * anything else falls through to the local scheduler untouched.
+ *
+ * **The mapping onto `TaskHandle` is the load-bearing part.** `taskSucceeded`
+ * and `taskFailed` require the gateway state and the run status to AGREE,
+ * because locally they are two independent authorities and a check reading
+ * only one of them has already shipped a failed worker as an answer. A
+ * foreign delegate has only its own word, so both fields are written from
+ * that one answer — which keeps every existing predicate correct without
+ * inventing a second authority that would only ever agree with the first.
+ */
+export interface DelegatingTaskSchedulerConfig {
+    /**
+     * Where an id no delegate claims goes.
+     *
+     * Optional, and its absence is a real configuration: a host that
+     * delegates ONLY to foreign peers has no local scheduler to fall back
+     * to, and an unknown id there is a caller error rather than something to
+     * pass along.
+     */
+    readonly local?: TaskScheduler;
+    readonly delegates: readonly Delegate[];
+}
+/** Two delegates, or a delegate and nothing, claiming one id. */
+export declare class DelegateIdCollisionError extends Error {
+    readonly details: {
+        id: string;
+    };
+    constructor(details: {
+        id: string;
+    });
+}
+/** A delegate whose declared capabilities do not match its methods. */
+export declare class DelegateCapabilityMismatchError extends Error {
+    readonly details: {
+        id: string;
+        capability: string;
+    };
+    constructor(details: {
+        id: string;
+        capability: string;
+    });
+}
+/** An operation the delegate said it cannot do. */
+export declare class DelegateCapabilityError extends Error {
+    readonly details: {
+        id: string;
+        capability: string;
+    };
+    constructor(details: {
+        id: string;
+        capability: string;
+    });
+}
+/** An agent id nothing can serve. */
+export declare class NoDelegateError extends Error {
+    readonly details: {
+        agentId: string;
+    };
+    constructor(details: {
+        agentId: string;
+    });
+}
+export declare class DelegatingTaskScheduler implements TaskScheduler {
+    private readonly config;
+    private readonly byId;
+    private readonly tasks;
+    private readonly listeners;
+    constructor(config: DelegatingTaskSchedulerConfig);
+    /** The delegate serving this id, or `undefined` for the local path. */
+    delegateFor(agentId: string): Delegate | undefined;
+    createTask(options: CreateTaskOptions): Promise<TaskHandle>;
+    private settle;
+    waitForTask(taskId: TaskId): Promise<TaskHandle>;
+    continueTask(taskId: TaskId, message: string): Promise<void>;
+    cancelTask(taskId: TaskId): void;
+    getTask(taskId: TaskId): TaskHandle | undefined;
+    listTasks(): TaskHandle[];
+    onTaskCompleted(callback: (handle: TaskHandle) => void): () => void;
+}
+//# sourceMappingURL=delegating.d.ts.map

package/dist/scheduler/delegating.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegating.d.ts","sourceRoot":"","sources":["../../src/scheduler/delegating.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAmC,MAAM,4BAA4B,CAAA;AAC3F,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAG/F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAGnD;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,6BAA6B;IAC7C;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAA;CACvC;AAED,iEAAiE;AACjE,qBAAa,wBAAyB,SAAQ,KAAK;IAClD,QAAQ,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;gBAEpB,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE;CAKnC;AAED,uEAAuE;AACvE,qBAAa,+BAAgC,SAAQ,KAAK;IACzD,QAAQ,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;gBAExC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;CAOvD;AAED,mDAAmD;AACnD,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,QAAQ,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;gBAExC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;CAKvD;AAED,qCAAqC;AACrC,qBAAa,eAAgB,SAAQ,KAAK;IACzC,QAAQ,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;gBAEzB,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE;CAOxC;AAkCD,qBAAa,uBAAwB,YAAW,aAAa;IAKhD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8B;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0C;gBAEvC,MAAM,EAAE,6BAA6B;IAkBlE,uEAAuE;IACvE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAI5C,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC;IAiDjE,OAAO,CAAC,MAAM;IA6BR,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAUhD,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAelE,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAYhC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C,SAAS,IAAI,UAAU,EAAE;IASzB,eAAe,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI;CAQnE"}

package/dist/scheduler/delegating.js

@@ -0,0 +1,230 @@
+import { EMPTY_TOKEN_USAGE, ZERO_COST } from '../constants/limits.js';
+import { asRunId, generateTaskId } from '../utils/id.js';
+/** Two delegates, or a delegate and nothing, claiming one id. */
+export class DelegateIdCollisionError extends Error {
+    details;
+    constructor(details) {
+        super(`Two delegates are registered under the id "${details.id}".`);
+        this.name = 'DelegateIdCollisionError';
+        this.details = details;
+    }
+}
+/** A delegate whose declared capabilities do not match its methods. */
+export class DelegateCapabilityMismatchError extends Error {
+    details;
+    constructor(details) {
+        super(`Delegate "${details.id}" declares capabilities.${details.capability} but does not implement it.`);
+        this.name = 'DelegateCapabilityMismatchError';
+        this.details = details;
+    }
+}
+/** An operation the delegate said it cannot do. */
+export class DelegateCapabilityError extends Error {
+    details;
+    constructor(details) {
+        super(`Delegate "${details.id}" does not support ${details.capability}.`);
+        this.name = 'DelegateCapabilityError';
+        this.details = details;
+    }
+}
+/** An agent id nothing can serve. */
+export class NoDelegateError extends Error {
+    details;
+    constructor(details) {
+        super(`No delegate is registered for "${details.agentId}", and this scheduler has no local fallback.`);
+        this.name = 'NoDelegateError';
+        this.details = details;
+    }
+}
+/**
+ * The two authorities a delegate's one answer is written onto.
+ *
+ * **Cancelled is not failed, and conflating them cancels a fan-out.**
+ * `taskFailed` is `state === 'failed' || result.status === 'failed'`, and
+ * `SiblingFailurePolicy: 'cancel-siblings'` acts on it — so writing
+ * `status: 'failed'` for a delegation somebody deliberately stopped would
+ * tear down every healthy sibling as a consequence of the stop. The first
+ * draft here did exactly that, in the same commit as a comment saying it
+ * must not.
+ *
+ * Note the spelling difference, which is the tree's and not a typo:
+ * `AgentTaskState` has `'canceled'`, `RunExecutionStatus` has
+ * `'cancelled'`. A table is what keeps that from being written from memory
+ * at each site.
+ */
+const OUTCOME = {
+    completed: { state: 'completed', status: 'completed' },
+    failed: { state: 'failed', status: 'failed' },
+    cancelled: { state: 'canceled', status: 'cancelled' },
+};
+export class DelegatingTaskScheduler {
+    config;
+    byId = new Map();
+    tasks = new Map();
+    listeners = new Set();
+    constructor(config) {
+        this.config = config;
+        for (const delegate of config.delegates) {
+            if (this.byId.has(delegate.id)) {
+                // Refused rather than resolved by precedence. A precedence rule
+                // makes which delegate answers depend on registration order,
+                // which is not visible at the call site that gets the wrong one.
+                throw new DelegateIdCollisionError({ id: delegate.id });
+            }
+            if (delegate.capabilities.continue && typeof delegate.continue !== 'function') {
+                // Checked at registration, not at the call. A capability that
+                // claims a method the object does not have is a lie the caller
+                // would otherwise find mid-delegation, with a worker running.
+                throw new DelegateCapabilityMismatchError({ id: delegate.id, capability: 'continue' });
+            }
+            this.byId.set(delegate.id, delegate);
+        }
+    }
+    /** The delegate serving this id, or `undefined` for the local path. */
+    delegateFor(agentId) {
+        return this.byId.get(agentId);
+    }
+    async createTask(options) {
+        const delegate = this.byId.get(options.agentId);
+        if (!delegate) {
+            if (!this.config.local)
+                throw new NoDelegateError({ agentId: options.agentId });
+            return await this.config.local.createTask(options);
+        }
+        const taskId = generateTaskId();
+        const controller = new AbortController();
+        const request = {
+            prompt: options.prompt,
+            workingDirectory: options.workingDirectory,
+            ...(options.runtimeContext ? { runtimeContext: options.runtimeContext } : {}),
+            ...(options.configOverrides?.env ? { env: options.configOverrides.env } : {}),
+        };
+        const entry = {
+            handle: {
+                taskId,
+                agentId: options.agentId,
+                state: 'running',
+                createdAt: Date.now(),
+            },
+            delegate,
+            controller,
+            settled: Promise.resolve(),
+        };
+        this.tasks.set(taskId, entry);
+        entry.settled = (async () => {
+            let result;
+            try {
+                result = await delegate.dispatch(request, { signal: controller.signal });
+            }
+            catch (err) {
+                // A delegate that threw failed; it did not vanish. Leaving the
+                // handle `running` would have `waitForTask` hang forever on a
+                // delegation that is already over.
+                result = {
+                    status: 'failed',
+                    error: err instanceof Error ? err.message : String(err),
+                };
+            }
+            entry.handle = this.settle(entry.handle, result);
+            for (const listener of this.listeners)
+                listener(entry.handle);
+        })();
+        return entry.handle;
+    }
+    settle(handle, result) {
+        const outcome = OUTCOME[result.status];
+        return {
+            ...handle,
+            state: outcome.state,
+            completedAt: Date.now(),
+            result: {
+                // A synthetic run record. The id names the task rather than
+                // borrowing a run id that does not exist: a foreign delegate has
+                // no run in this kernel, and minting a plausible-looking `run_`
+                // would put an id in the transcript that nothing can resolve.
+                runId: asRunId(`run_delegate_${handle.taskId}`),
+                status: outcome.status,
+                // Zero, and honestly so: this kernel did not spend these tokens
+                // and has no way to learn what the delegate spent. `ZERO_COST`
+                // carries no rate card for exactly this reason — a rate of zero
+                // would read as "the model is free" rather than "nobody priced
+                // this".
+                usage: { ...EMPTY_TOKEN_USAGE },
+                cost: { ...ZERO_COST },
+                iterations: 0,
+                durationMs: Date.now() - handle.createdAt,
+                messages: [],
+                ...(result.output === undefined ? {} : { result: result.output }),
+                ...(result.error === undefined ? {} : { lastError: result.error }),
+            },
+        };
+    }
+    async waitForTask(taskId) {
+        const entry = this.tasks.get(taskId);
+        if (!entry) {
+            if (!this.config.local)
+                throw new Error(`No task ${taskId}.`);
+            return await this.config.local.waitForTask(taskId);
+        }
+        await entry.settled;
+        return entry.handle;
+    }
+    async continueTask(taskId, message) {
+        const entry = this.tasks.get(taskId);
+        if (!entry) {
+            if (!this.config.local)
+                throw new Error(`No task ${taskId}.`);
+            return await this.config.local.continueTask(taskId, message);
+        }
+        if (!entry.delegate.capabilities.continue || !entry.delegate.continue) {
+            // Refused, not silently dropped. A no-op here has the parent
+            // believe it steered a worker that never heard it — and it would
+            // go on believing that until the answer came back unchanged.
+            throw new DelegateCapabilityError({ id: entry.delegate.id, capability: 'continue' });
+        }
+        await entry.delegate.continue(message);
+    }
+    cancelTask(taskId) {
+        const entry = this.tasks.get(taskId);
+        if (!entry) {
+            this.config.local?.cancelTask(taskId);
+            return;
+        }
+        if (!entry.delegate.capabilities.cancel) {
+            throw new DelegateCapabilityError({ id: entry.delegate.id, capability: 'cancel' });
+        }
+        controllerAbort(entry);
+    }
+    getTask(taskId) {
+        return this.tasks.get(taskId)?.handle ?? this.config.local?.getTask(taskId);
+    }
+    listTasks() {
+        // Both, because a supervisor listing its children should not have to
+        // know which of them happen to be foreign.
+        return [
+            ...[...this.tasks.values()].map((e) => e.handle),
+            ...(this.config.local?.listTasks() ?? []),
+        ];
+    }
+    onTaskCompleted(callback) {
+        this.listeners.add(callback);
+        const localOff = this.config.local?.onTaskCompleted(callback);
+        return () => {
+            this.listeners.delete(callback);
+            localOff?.();
+        };
+    }
+}
+/**
+ * Abort, and let the dispatch settle itself.
+ *
+ * Deliberately NOT writing the `canceled` state here. The delegate's own
+ * `dispatch` is what resolves — with `cancelled`, or with an answer it had
+ * already finished producing — and marking the handle from outside would
+ * race that: a delegate that completed a microsecond before the abort would
+ * be recorded as cancelled while its answer sat unread.
+ */
+function controllerAbort(entry) {
+    entry.controller.abort();
+}
+//# sourceMappingURL=delegating.js.map

package/dist/scheduler/delegating.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegating.js","sourceRoot":"","sources":["../../src/scheduler/delegating.ts"],"names":[],"mappings":"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"}

package/dist/{gateway → scheduler}/local.d.ts

@@ -1,10 +1,11 @@
 import type { AgentInput } from '../types/agent/base.js';
-import type { CreateTaskOptions, SiblingFailurePolicy, TaskGateway, TaskHandle } from '../types/agent/gateway.js';
 import type { AgentManagerContract } from '../types/agent/manager.js';
+import type { CreateTaskOptions, SiblingFailurePolicy, TaskHandle, TaskScheduler } from '../types/agent/scheduler.js';
 import type { AgentTaskContext } from '../types/agent/task.js';
 import type { TaskId } from '../types/ids/index.js';
 import type { RunEventListener } from '../types/run/events.js';
-export declare class LocalTaskGateway implements TaskGateway {
+import { type Logger } from '../utils/logger.js';
+export declare class LocalTaskScheduler implements TaskScheduler {
     private agentManager;
     private taskContext;
     private listener;
@@ -28,8 +29,15 @@ export declare class LocalTaskGateway implements TaskGateway {
     private siblingFailurePolicy;
     /** See {@link onTaskProgress}. */
     private readonly progressListeners;
+    /** Raw, unresolved — kept as the caller handed it so each of the two log
+     * sites below resolves it independently via `resolveLogger`, rather than
+     * this constructor baking in ONE `.child()` binding both would then share
+     * (which would also change how many `component:` bindings this file has,
+     * a different ratchet than the one this task moves). */
+    private readonly log?;
     constructor(agentManager: AgentManagerContract, taskContext: AgentTaskContext, listener?: RunEventListener, parentInput?: Pick<AgentInput, 'taskStore' | 'runtimeToolOverrides' | 'runtimeContext'>, options?: {
         siblingFailurePolicy?: SiblingFailurePolicy;
+        log?: Logger;
     });
     createTask(options: CreateTaskOptions): Promise<TaskHandle>;
     /**

package/dist/scheduler/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/scheduler/local.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AACrE,OAAO,KAAK,EACX,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACV,aAAa,EACb,MAAM,6BAA6B,CAAA;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAG9D,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,oBAAoB,CAAA;AAa/D,qBAAa,kBAAmB,YAAW,aAAa;IACvD,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,cAAc,CAAyB;IAE/C,OAAO,CAAC,WAAW,CAAC,CAA2E;IAE/F,OAAO,CAAC,mBAAmB,CAA+C;IAE1E;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,cAAc,CAAqC;IAE3D,OAAO,CAAC,oBAAoB,CAAmC;IAC/D,kCAAkC;IAClC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAsC;IACxE;;;;4DAIwD;IACxD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAQ;gBAG5B,YAAY,EAAE,oBAAoB,EAClC,WAAW,EAAE,gBAAgB,EAC7B,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,WAAW,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,GAAG,sBAAsB,GAAG,gBAAgB,CAAC,EACvF,OAAO,CAAC,EAAE;QAAE,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;IAYlE,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC;IA8GjE;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,kBAAkB;IA0BpB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAShD,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlE,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIhC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAK/C;;;;OAIG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAKrC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,qBAAqB;IAS7B,SAAS,IAAI,UAAU,EAAE;IAgBzB;;;;;;;OAOG;IACH,cAAc,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAO9D,eAAe,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI;CAMnE"}

package/dist/{gateway → scheduler}/local.js

@@ -1,7 +1,9 @@
+import { GENAI } from '../constants/telemetry/index.js';
 import { taskFailed } from '../tools/coordinator/outcome.js';
 import { createUserMessage } from '../types/message/index.js';
 import { toErrorMessage } from '../utils/error.js';
-import { getRootLogger } from '../utils/logger.js';
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js';
+import { resolveLogger } from '../utils/logger.js';
 /**
  * How many launched tasks a gateway remembers.
  *
@@ -12,7 +14,7 @@ import { getRootLogger } from '../utils/logger.js';
  * the life of the process.
  */
 const GATEWAY_TASK_LEDGER_CAP = 1_000;
-export class LocalTaskGateway {
+export class LocalTaskScheduler {
     agentManager;
     taskContext;
     listener;
@@ -36,11 +38,18 @@ export class LocalTaskGateway {
     siblingFailurePolicy = 'continue';
     /** See {@link onTaskProgress}. */
     progressListeners = new Set();
+    /** Raw, unresolved — kept as the caller handed it so each of the two log
+     * sites below resolves it independently via `resolveLogger`, rather than
+     * this constructor baking in ONE `.child()` binding both would then share
+     * (which would also change how many `component:` bindings this file has,
+     * a different ratchet than the one this task moves). */
+    log;
     constructor(agentManager, taskContext, listener, parentInput, options) {
         this.agentManager = agentManager;
         this.taskContext = taskContext;
         this.listener = listener;
         this.parentInput = parentInput;
+        this.log = options?.log;
         if (options?.siblingFailurePolicy) {
             this.siblingFailurePolicy = options.siblingFailurePolicy;
         }
@@ -141,11 +150,11 @@ export class LocalTaskGateway {
             }
         })
             .catch((err) => {
-            getRootLogger()
-                .child({ component: 'LocalTaskGateway' })
+            resolveLogger(this.log)
+                .child({ [SCOPE_ATTRIBUTE]: 'scheduler/local' })
                 .error('Task completion tracking failed', {
-                taskId: task.taskId,
-                error: toErrorMessage(err),
+                'namzu.task.id': task.taskId,
+                'exception.message': toErrorMessage(err),
             });
         });
         return toHandle(task);
@@ -184,12 +193,12 @@ export class LocalTaskGateway {
             cancelled.push(taskId);
         }
         if (cancelled.length > 0) {
-            getRootLogger()
-                .child({ component: 'LocalTaskGateway' })
+            resolveLogger(this.log)
+                .child({ [SCOPE_ATTRIBUTE]: 'scheduler/local' })
                 .info('Cancelled siblings after a child failed', {
-                failed: finished.taskId,
-                agentId: finished.agentId,
-                cancelled,
+                'namzu.scheduler.failed': finished.taskId,
+                [GENAI.AGENT_ID]: finished.agentId,
+                'namzu.scheduler.cancelled': cancelled,
             });
         }
     }

package/dist/scheduler/local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.js","sourceRoot":"","sources":["../../src/scheduler/local.ts"],"names":[],"mappings":"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"}

package/dist/session/actor-scope.d.ts

@@ -0,0 +1,52 @@
+import type { ActorRef } from '../types/session/actor.js';
+/**
+ * Walking the actor chain that was already there.
+ *
+ * `ActorRef`'s agent variant has carried `parentActor` since the 0.2.0
+ * design, and its docblock says permission audit events walk this chain to
+ * attribute a subagent's actions back to the originating user. Nothing
+ * walked it — `rg 'isDescendantOf|ancestor'` over this package found no
+ * reader at all. A declared hierarchy with no code that traverses it is a
+ * `declared-but-undriven` primitive, and every cross-tree concern that came
+ * along instead invented its own propagation: `resumeHandler` is threaded
+ * by hand at the spawn site, and a tool scope was about to be.
+ *
+ * **Not a parallel parent registry.** The obvious fix is a `WeakMap` from
+ * child to parent maintained by the manager, and it is the wrong one: the
+ * chain is already persisted on the actor, so a second structure gives the
+ * tree two answers to the same question that can disagree — and the one a
+ * check reads would be the one that is NOT written to disk.
+ */
+/**
+ * How far the walk goes before giving up.
+ *
+ * A chain is built by the manager one link per spawn, and the spawn depth
+ * limit is far below this — so reaching it means the chain is malformed or
+ * cyclic, not that somebody legitimately nested a hundred deep. Bounded
+ * rather than cycle-detected with a `Set` because the bound is the thing
+ * that must hold: a containment check that hangs is a denial of service on
+ * whatever holds the lock, and a check that allocates per call to prove a
+ * property nobody can trigger is worse than one that stops.
+ */
+export declare const MAX_ACTOR_CHAIN_DEPTH = 64;
+/** The chain from `actor` up to its root, newest first, `actor` included. */
+export declare function actorChain(actor: ActorRef, opts?: {
+    readonly maxDepth?: number;
+}): readonly ActorRef[];
+/**
+ * Whether `ancestor` appears strictly above `actor` in its chain.
+ *
+ * Strictly: an actor is not its own ancestor. The question this answers is
+ * "may what happened up there constrain what happens here", and an actor
+ * constraining itself is not a hierarchy fact — reading it as one makes
+ * every self-comparison silently true and hides a caller that passed the
+ * same actor twice by mistake.
+ *
+ * Returns `false` on a malformed or cyclic chain rather than throwing. The
+ * callers are authorization checks, and the honest answer to "is this
+ * contained by that" when the chain cannot be read is no.
+ */
+export declare function isDescendantOfActor(actor: ActorRef, ancestor: ActorRef, opts?: {
+    readonly maxDepth?: number;
+}): boolean;
+//# sourceMappingURL=actor-scope.d.ts.map

package/dist/session/actor-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-scope.d.ts","sourceRoot":"","sources":["../../src/session/actor-scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAA;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAA;AAmDvC,6EAA6E;AAC7E,wBAAgB,UAAU,CACzB,KAAK,EAAE,QAAQ,EACf,IAAI,GAAE;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,SAAS,QAAQ,EAAE,CASrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,QAAQ,EACf,QAAQ,EAAE,QAAQ,EAClB,IAAI,GAAE;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,OAAO,CAKT"}