@aigne/agent-runtime 1.12.0-beta.5

package/dist/program/scoped-afs.d.cts

@@ -0,0 +1,245 @@
+import { BudgetConfig } from "../agent-runners/budget.cjs";
+import { ScratchProvider, ScratchRetention } from "../agent-runners/scratchpad-afs.cjs";
+import { AFSRoot, AgentManifest } from "@aigne/afs";
+import { ToolEntry } from "@aigne/afs-ash";
+
+//#region src/program/scoped-afs.d.ts
+/**
+ * Chain-depth hard cap. Mirrors `HARD_CAP` in
+ * `providers/basic/ash/src/spawn-depth.ts`; kept in sync manually because
+ * importing across package boundaries for a constant isn't worth the
+ * dependency. Any change there must be reflected here.
+ *
+ * Semantics match `spawn-depth.ts`: a child whose post-increment depth
+ * would be **>= HARD_CAP** is rejected with `CHAIN_DEPTH_EXCEEDED`. With
+ * root.chainDepth = 0 this means the deepest reachable child is depth 9;
+ * attempting to spawn depth 10 throws.
+ */
+declare const CHAIN_DEPTH_HARD_CAP = 10;
+/**
+ * Mutable budget accounting backing a single scope's `/.meta/budget/*`
+ * mount and its exec middleware. `rootSession` is the mutex key shared by
+ * every scope in one spawn chain; ancestor aggregation happens naturally
+ * because `child.exec` delegates to `parent.exec` through the prototype
+ * chain, so each ancestor's middleware runs once per call and applies its
+ * own increment — no parent pointer needed.
+ */
+interface BudgetState {
+  readonly rootSession: string;
+  readonly limit: number;
+  consumed: number;
+}
+/**
+ * Per-scope descriptor threaded through every AFS call a runner makes.
+ *
+ * - `session` — this scope's session id (not the underlying WS session)
+ * - `parentSession` — the session that spawned us (used for event aggregation)
+ * - `rootSession` — the session at the root of the spawn chain. All children
+ *   of the same root share this value; P4's budget exec middleware uses it
+ *   as the mutex key so concurrent sub-runs serialize correctly against the
+ *   same budget file. Root scope: rootSession === session.
+ * - `chainDepth` — distance from the root scope (root = 0). Enforced against
+ *   `CHAIN_DEPTH_HARD_CAP` on every `projectForChild` call.
+ * - `allowedPaths` — paths visible inside this scope. Populated from the
+ *   intersection of the parent's `allowedTools` and the child manifest's
+ *   declared tools (P1).
+ * - `allowedTools` — intersected `ToolEntry[]` (paths + ops + maxDepth +
+ *   exclude_actions). Carried alongside `allowedPaths` because runners
+ *   need the ops metadata to build the LLM tool catalog; the `.actions/`
+ *   mount in later phases will let consumers list tools directly from the
+ *   scope and this field will become a cache.
+ */
+interface AgentScopeDescriptorFields {
+  readonly session: string;
+  readonly parentSession?: string;
+  readonly rootSession: string;
+  readonly chainDepth: number;
+  readonly allowedPaths: readonly string[];
+  readonly allowedTools: readonly ToolEntry[];
+  /**
+   * Tenant string that the scope's `/memory/` mount was instantiated with.
+   * Absent on scopes where `manifest.memory` is falsy — child scopes inherit
+   * this value when they declare `memory: true` without an explicit domain.
+   * See `docs/architecture/agent-memory.md` §3.3 for the precedence ladder.
+   */
+  readonly memoryDomain?: string;
+  /**
+   * Live budget state backing this scope's `/.meta/budget/*` mount. Absent
+   * on scopes that never opted into budget tracking (legacy callers that
+   * synthesize a scope without declaring a limit). When present, the exec
+   * middleware reads/writes this object under the rootSession mutex;
+   * children created via `projectForChild` inherit a new state whose
+   * `parent` pointer links here so decrements walk up the chain.
+   */
+  readonly budget?: BudgetState;
+}
+/**
+ * A scoped AFS view handed to an agent runner. Same shape as `AFSRoot`
+ * (list/read/write/exec/…) with an extra `scope` descriptor.
+ *
+ * Runners read session / chain / permissions from `scope` rather than
+ * from their own arguments. The five sibling phases (P1 tools, P2 scratch,
+ * P3 memory, P4 budget, P5 session) wire mounts into the scope so the
+ * runner never needs provider-specific fields on its context.
+ */
+interface AgentScope extends AFSRoot {
+  readonly scope: AgentScopeDescriptorFields;
+}
+/**
+ * Options accepted by `projectForChild`.
+ *
+ * **Closed at 3 fields** — permission-widening fields (tools / budget /
+ * scratch / memory / budgetRemaining / …) are intentionally absent. The
+ * implementation must derive those from `childManifest` and the parent
+ * scope. Extending this type to smuggle in a wider budget or tool set
+ * defeats the whole point of scope-based projection.
+ */
+interface ProjectForChildOptions {
+  /** Required — where the child agent lives in the parent's mount tree (e.g. "members/reviewer"). */
+  readonly memberPath: string;
+  /** Required — scratch/memory/tools/budget are all derived from this. */
+  readonly childManifest: AgentManifest;
+  /**
+   * Optional — if omitted, the runtime generates
+   * `${parent.scope.session}.${memberName}.${counter}`. Must not contain
+   * path separators, null bytes, or be empty.
+   */
+  readonly session?: string;
+}
+/**
+ * Phase 2 sandbox serialization target. When the runtime needs to hand a
+ * scope to an out-of-process worker (code agent, sandboxed MCP server, …),
+ * it serializes to this descriptor and the far side rebuilds an AgentScope
+ * backed by an MCP bridge.
+ *
+ * Phase 0 only defines the shape — `toJSON()` throws until Phase 2 lands.
+ */
+interface AgentScopeDescriptor {
+  readonly kind: "agent-scope";
+  readonly session: string;
+  readonly parentSession?: string;
+  readonly rootSession: string;
+  readonly chainDepth: number;
+  readonly allowedPaths: readonly string[];
+  readonly mountDescriptors: ReadonlyArray<{
+    readonly path: string;
+    readonly providerDescriptor: unknown;
+  }>;
+}
+/**
+ * Normalize a manifest's `tools` field into `ToolEntry[]`, rejecting shapes
+ * that would let a dispatcher smuggle traversal or typo past intersection:
+ *   - non-string / empty path → TOOL_PATH_INVALID
+ *   - path containing `..` or `\0` → TOOL_PATH_INVALID
+ *   - ops must be a non-empty string[] when provided
+ *
+ * The Phase 1 contract: one call site (projectForChild) owns normalization;
+ * older runner-local normalize helpers delegate here.
+ */
+declare function normalizeManifestTools(manifest: {
+  tools?: AgentManifest["tools"];
+}): ToolEntry[];
+/**
+ * Lift a raw `AFSRoot` into a root-level `AgentScope`. Root scopes are
+ * unbounded by construction — `scope.allowedTools` is the caller's own
+ * manifest tools (or fully permissive when omitted), and `chainDepth` is 0.
+ *
+ * Top-level runners (agent-run action handler, test harnesses) use this to
+ * bootstrap the scope chain; downstream runners never construct a root
+ * scope themselves. Omit `manifestTools` (or pass `[]`) to keep the root
+ * fully permissive — useful for tests that don't declare tools.
+ */
+declare function rootAgentScope(afs: AFSRoot, opts: {
+  session: string;
+  manifestTools?: ToolEntry[];
+  /**
+   * Optional manifest budget config for the root scope. When set, the
+   * returned scope carries a `/.meta/budget/*` mount and the exec
+   * middleware; children projected from it inherit clamped budgets.
+   * Omitted → scope is unbudgeted (legacy behaviour).
+   */
+  budget?: BudgetConfig;
+  /**
+   * Optional memory domain to stamp into the root scope descriptor.
+   * Callers that pre-attached a `/memory/*` mount (e.g. team-runner when
+   * the team manifest declares memory at the top level) pass the domain
+   * so downstream `scope.memoryDomain` reads resolve authoritatively.
+   * Omitted → scope carries no memory domain (legacy behaviour).
+   */
+  memoryDomain?: string;
+}): AgentScope;
+/**
+ * Top-level runner bootstrap — if the caller's AFS is already a scope, use
+ * it verbatim; otherwise synthesize a root scope and attach a fresh
+ * `/scratch/*` mount. Team and orchestrator runners call this so hook
+ * events and `state.yml` writes land in the scope-local scratch rather
+ * than the legacy `/modules/memory/runs/` tree.
+ *
+ * Pass `manifestTools` + `session` to drive the synthetic root scope's
+ * descriptor; the caller's own manifest is typically the source, and
+ * `scratchRetention` follows `manifest.scratch` (run → session default).
+ */
+declare function ensureScopeWithMounts(afs: AFSRoot, opts: {
+  session: string;
+  manifestTools?: ToolEntry[];
+  scratchRetention?: ScratchRetention;
+  scratchProvider?: ScratchProvider;
+  /**
+   * Manifest budget for the synthetic root scope. Forwarded to
+   * `rootAgentScope` so the bootstrap scope carries the budget mount
+   * and children projected from it inherit the clamp. Optional — when
+   * unset, the scope stays unbudgeted (legacy behaviour).
+   */
+  budget?: BudgetConfig;
+  /**
+   * Top-level team's `manifest.memory`. When the team declares memory,
+   * the synthetic root scope stamps `memoryDomain` so downstream G2
+   * handoff read-through resolves authoritatively without re-reading
+   * the manifest. Does NOT attach a memory mount — the caller is
+   * expected to have one already (tests use `attachMemoryMount`;
+   * production wires via the per-scope scaffolding).
+   */
+  memory?: unknown;
+}): AgentScope;
+/**
+ * Resolve the `AgentScope` a parent runner projects children from.
+ *
+ * Phase 6 — if the caller already handed us a scoped AFS (via
+ * `projectForChild` / `ensureScopeWithMounts`), reuse it: its `allowedTools`
+ * is already the post-intersection view. Otherwise synthesize a root scope
+ * from the caller's `manifest.tools`, normalized via `normalizeManifestTools`
+ * for a single source of truth. Callers that want a tighter inherited
+ * set must hand over a scoped AFS built via `projectForChild` or
+ * `ensureScopeWithMounts`.
+ */
+declare function resolveParentAgentScope(opts: {
+  afs: AFSRoot;
+  manifest: AgentManifest;
+  session?: string;
+}): AgentScope;
+/**
+ * Narrow down `parent` for a child agent:
+ *   - path projection via existing `projectSubAgent` (rewrite + readonly)
+ *   - tool ACL intersection via existing `intersectTools` (paths + ops)
+ *   - scope descriptor: session / rootSession / chainDepth+1 / allowedPaths
+ *
+ * If the parent has a non-empty `scope.allowedTools` and the child declares
+ * a non-empty `manifest.tools` that doesn't overlap (intersection empty),
+ * we throw `TOOL_INTERSECTION_EMPTY` — an empty intersection means the
+ * dispatcher has asked for an unreachable child scope, which is a hard
+ * error rather than a silently-permissive default.
+ *
+ * See design.md §5 for the full six-step mount composition; P2–P5 add
+ * scratch / memory / budget / session arms to the same function.
+ */
+declare function projectForChild(parent: AgentScope, options: ProjectForChildOptions): AgentScope;
+/**
+ * Phase 2 target — serialize a scope for cross-process hand-off (MCP
+ * sandbox worker, code-agent runner, …). Always throws in Phase 0/1 so
+ * no caller is tempted to persist a partial descriptor before the sandbox
+ * boundary exists.
+ */
+declare function toJSON(_scope: AgentScope): AgentScopeDescriptor;
+//#endregion
+export { AgentScope, AgentScopeDescriptor, AgentScopeDescriptorFields, CHAIN_DEPTH_HARD_CAP, ProjectForChildOptions, ensureScopeWithMounts, normalizeManifestTools, projectForChild, resolveParentAgentScope, rootAgentScope, toJSON };
+//# sourceMappingURL=scoped-afs.d.cts.map

package/dist/program/scoped-afs.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-afs.d.cts","names":[],"sources":["../../src/program/scoped-afs.ts"],"mappings":";;;;;;;;;;;AAmZA;;;;;;cAxVa,oBAAA;;;AAqWb;;;;;;UApRiB,WAAA;EAAA,SACN,WAAA;EAAA,SACA,KAAA;EACT,QAAA;AAAA;;;;;;;;AAibF;;;;;;;;;;;;;UA/MiB,0BAAA;EAAA,SACN,OAAA;EAAA,SACA,aAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA;EAAA,SACA,YAAA;EAAA,SACA,YAAA,WAAuB,SAAA;EA8NrB;AAsCb;;;;;EAtCa,SAvNF,YAAA;EAmQW;;;;;;;;EAAA,SA1PX,MAAA,GAAS,WAAA;AAAA;;;;;;;;;;UAYH,UAAA,SAAmB,OAAA;EAAA,SACzB,KAAA,EAAO,0BAAA;AAAA;;;;;;;;;;UAYD,sBAAA;EAkRL;EAAA,SAhRD,UAAA;EA8Q6B;EAAA,SA5Q7B,aAAA,EAAe,aAAA;EAgRZ;;AAoCd;;;EApCc,SA1QH,OAAA;AAAA;;;;;;;;;UAWM,oBAAA;EAAA,SACN,IAAA;EAAA,SACA,OAAA;EAAA,SACA,aAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA;EAAA,SACA,YAAA;EAAA,SACA,gBAAA,EAAkB,aAAA;IAAA,SAChB,IAAA;IAAA,SACA,kBAAA;EAAA;AAAA;;;;;;;;;;;iBA8CG,sBAAA,CAAuB,QAAA;EAAY,KAAA,GAAQ,aAAA;AAAA,IAA2B,SAAA;;;;;;;;;;;iBAoFtE,cAAA,CACd,GAAA,EAAK,OAAA,EACL,IAAA;EACE,OAAA;EACA,aAAA,GAAgB,SAAA;;;;;;;EAOhB,MAAA,GAAS,YAAA;;;;;;;;EAQT,YAAA;AAAA,IAED,UAAA;;;;;;;;;;;;iBAsCa,qBAAA,CACd,GAAA,EAAK,OAAA,EACL,IAAA;EACE,OAAA;EACA,aAAA,GAAgB,SAAA;EAChB,gBAAA,GAAmB,gBAAA;EACnB,eAAA,GAAkB,eAAA;;;;;;;EAOlB,MAAA,GAAS,YAAA;;;;;;;;;EAST,MAAA;AAAA,IAED,UAAA;;;;;;;;;;;;iBA6Ba,uBAAA,CAAwB,IAAA;EACtC,GAAA,EAAK,OAAA;EACL,QAAA,EAAU,aAAA;EACV,OAAA;AAAA,IACE,UAAA;;;;;;;;;;;;;;;;iBAoCY,eAAA,CAAgB,MAAA,EAAQ,UAAA,EAAY,OAAA,EAAS,sBAAA,GAAyB,UAAA;;;;;;;iBA8JtE,MAAA,CAAO,MAAA,EAAQ,UAAA,GAAa,oBAAA"}

package/dist/program/scoped-afs.d.mts

@@ -0,0 +1,245 @@
+import { BudgetConfig } from "../agent-runners/budget.mjs";
+import { ScratchProvider, ScratchRetention } from "../agent-runners/scratchpad-afs.mjs";
+import { AFSRoot, AgentManifest } from "@aigne/afs";
+import { ToolEntry } from "@aigne/afs-ash";
+
+//#region src/program/scoped-afs.d.ts
+/**
+ * Chain-depth hard cap. Mirrors `HARD_CAP` in
+ * `providers/basic/ash/src/spawn-depth.ts`; kept in sync manually because
+ * importing across package boundaries for a constant isn't worth the
+ * dependency. Any change there must be reflected here.
+ *
+ * Semantics match `spawn-depth.ts`: a child whose post-increment depth
+ * would be **>= HARD_CAP** is rejected with `CHAIN_DEPTH_EXCEEDED`. With
+ * root.chainDepth = 0 this means the deepest reachable child is depth 9;
+ * attempting to spawn depth 10 throws.
+ */
+declare const CHAIN_DEPTH_HARD_CAP = 10;
+/**
+ * Mutable budget accounting backing a single scope's `/.meta/budget/*`
+ * mount and its exec middleware. `rootSession` is the mutex key shared by
+ * every scope in one spawn chain; ancestor aggregation happens naturally
+ * because `child.exec` delegates to `parent.exec` through the prototype
+ * chain, so each ancestor's middleware runs once per call and applies its
+ * own increment — no parent pointer needed.
+ */
+interface BudgetState {
+  readonly rootSession: string;
+  readonly limit: number;
+  consumed: number;
+}
+/**
+ * Per-scope descriptor threaded through every AFS call a runner makes.
+ *
+ * - `session` — this scope's session id (not the underlying WS session)
+ * - `parentSession` — the session that spawned us (used for event aggregation)
+ * - `rootSession` — the session at the root of the spawn chain. All children
+ *   of the same root share this value; P4's budget exec middleware uses it
+ *   as the mutex key so concurrent sub-runs serialize correctly against the
+ *   same budget file. Root scope: rootSession === session.
+ * - `chainDepth` — distance from the root scope (root = 0). Enforced against
+ *   `CHAIN_DEPTH_HARD_CAP` on every `projectForChild` call.
+ * - `allowedPaths` — paths visible inside this scope. Populated from the
+ *   intersection of the parent's `allowedTools` and the child manifest's
+ *   declared tools (P1).
+ * - `allowedTools` — intersected `ToolEntry[]` (paths + ops + maxDepth +
+ *   exclude_actions). Carried alongside `allowedPaths` because runners
+ *   need the ops metadata to build the LLM tool catalog; the `.actions/`
+ *   mount in later phases will let consumers list tools directly from the
+ *   scope and this field will become a cache.
+ */
+interface AgentScopeDescriptorFields {
+  readonly session: string;
+  readonly parentSession?: string;
+  readonly rootSession: string;
+  readonly chainDepth: number;
+  readonly allowedPaths: readonly string[];
+  readonly allowedTools: readonly ToolEntry[];
+  /**
+   * Tenant string that the scope's `/memory/` mount was instantiated with.
+   * Absent on scopes where `manifest.memory` is falsy — child scopes inherit
+   * this value when they declare `memory: true` without an explicit domain.
+   * See `docs/architecture/agent-memory.md` §3.3 for the precedence ladder.
+   */
+  readonly memoryDomain?: string;
+  /**
+   * Live budget state backing this scope's `/.meta/budget/*` mount. Absent
+   * on scopes that never opted into budget tracking (legacy callers that
+   * synthesize a scope without declaring a limit). When present, the exec
+   * middleware reads/writes this object under the rootSession mutex;
+   * children created via `projectForChild` inherit a new state whose
+   * `parent` pointer links here so decrements walk up the chain.
+   */
+  readonly budget?: BudgetState;
+}
+/**
+ * A scoped AFS view handed to an agent runner. Same shape as `AFSRoot`
+ * (list/read/write/exec/…) with an extra `scope` descriptor.
+ *
+ * Runners read session / chain / permissions from `scope` rather than
+ * from their own arguments. The five sibling phases (P1 tools, P2 scratch,
+ * P3 memory, P4 budget, P5 session) wire mounts into the scope so the
+ * runner never needs provider-specific fields on its context.
+ */
+interface AgentScope extends AFSRoot {
+  readonly scope: AgentScopeDescriptorFields;
+}
+/**
+ * Options accepted by `projectForChild`.
+ *
+ * **Closed at 3 fields** — permission-widening fields (tools / budget /
+ * scratch / memory / budgetRemaining / …) are intentionally absent. The
+ * implementation must derive those from `childManifest` and the parent
+ * scope. Extending this type to smuggle in a wider budget or tool set
+ * defeats the whole point of scope-based projection.
+ */
+interface ProjectForChildOptions {
+  /** Required — where the child agent lives in the parent's mount tree (e.g. "members/reviewer"). */
+  readonly memberPath: string;
+  /** Required — scratch/memory/tools/budget are all derived from this. */
+  readonly childManifest: AgentManifest;
+  /**
+   * Optional — if omitted, the runtime generates
+   * `${parent.scope.session}.${memberName}.${counter}`. Must not contain
+   * path separators, null bytes, or be empty.
+   */
+  readonly session?: string;
+}
+/**
+ * Phase 2 sandbox serialization target. When the runtime needs to hand a
+ * scope to an out-of-process worker (code agent, sandboxed MCP server, …),
+ * it serializes to this descriptor and the far side rebuilds an AgentScope
+ * backed by an MCP bridge.
+ *
+ * Phase 0 only defines the shape — `toJSON()` throws until Phase 2 lands.
+ */
+interface AgentScopeDescriptor {
+  readonly kind: "agent-scope";
+  readonly session: string;
+  readonly parentSession?: string;
+  readonly rootSession: string;
+  readonly chainDepth: number;
+  readonly allowedPaths: readonly string[];
+  readonly mountDescriptors: ReadonlyArray<{
+    readonly path: string;
+    readonly providerDescriptor: unknown;
+  }>;
+}
+/**
+ * Normalize a manifest's `tools` field into `ToolEntry[]`, rejecting shapes
+ * that would let a dispatcher smuggle traversal or typo past intersection:
+ *   - non-string / empty path → TOOL_PATH_INVALID
+ *   - path containing `..` or `\0` → TOOL_PATH_INVALID
+ *   - ops must be a non-empty string[] when provided
+ *
+ * The Phase 1 contract: one call site (projectForChild) owns normalization;
+ * older runner-local normalize helpers delegate here.
+ */
+declare function normalizeManifestTools(manifest: {
+  tools?: AgentManifest["tools"];
+}): ToolEntry[];
+/**
+ * Lift a raw `AFSRoot` into a root-level `AgentScope`. Root scopes are
+ * unbounded by construction — `scope.allowedTools` is the caller's own
+ * manifest tools (or fully permissive when omitted), and `chainDepth` is 0.
+ *
+ * Top-level runners (agent-run action handler, test harnesses) use this to
+ * bootstrap the scope chain; downstream runners never construct a root
+ * scope themselves. Omit `manifestTools` (or pass `[]`) to keep the root
+ * fully permissive — useful for tests that don't declare tools.
+ */
+declare function rootAgentScope(afs: AFSRoot, opts: {
+  session: string;
+  manifestTools?: ToolEntry[];
+  /**
+   * Optional manifest budget config for the root scope. When set, the
+   * returned scope carries a `/.meta/budget/*` mount and the exec
+   * middleware; children projected from it inherit clamped budgets.
+   * Omitted → scope is unbudgeted (legacy behaviour).
+   */
+  budget?: BudgetConfig;
+  /**
+   * Optional memory domain to stamp into the root scope descriptor.
+   * Callers that pre-attached a `/memory/*` mount (e.g. team-runner when
+   * the team manifest declares memory at the top level) pass the domain
+   * so downstream `scope.memoryDomain` reads resolve authoritatively.
+   * Omitted → scope carries no memory domain (legacy behaviour).
+   */
+  memoryDomain?: string;
+}): AgentScope;
+/**
+ * Top-level runner bootstrap — if the caller's AFS is already a scope, use
+ * it verbatim; otherwise synthesize a root scope and attach a fresh
+ * `/scratch/*` mount. Team and orchestrator runners call this so hook
+ * events and `state.yml` writes land in the scope-local scratch rather
+ * than the legacy `/modules/memory/runs/` tree.
+ *
+ * Pass `manifestTools` + `session` to drive the synthetic root scope's
+ * descriptor; the caller's own manifest is typically the source, and
+ * `scratchRetention` follows `manifest.scratch` (run → session default).
+ */
+declare function ensureScopeWithMounts(afs: AFSRoot, opts: {
+  session: string;
+  manifestTools?: ToolEntry[];
+  scratchRetention?: ScratchRetention;
+  scratchProvider?: ScratchProvider;
+  /**
+   * Manifest budget for the synthetic root scope. Forwarded to
+   * `rootAgentScope` so the bootstrap scope carries the budget mount
+   * and children projected from it inherit the clamp. Optional — when
+   * unset, the scope stays unbudgeted (legacy behaviour).
+   */
+  budget?: BudgetConfig;
+  /**
+   * Top-level team's `manifest.memory`. When the team declares memory,
+   * the synthetic root scope stamps `memoryDomain` so downstream G2
+   * handoff read-through resolves authoritatively without re-reading
+   * the manifest. Does NOT attach a memory mount — the caller is
+   * expected to have one already (tests use `attachMemoryMount`;
+   * production wires via the per-scope scaffolding).
+   */
+  memory?: unknown;
+}): AgentScope;
+/**
+ * Resolve the `AgentScope` a parent runner projects children from.
+ *
+ * Phase 6 — if the caller already handed us a scoped AFS (via
+ * `projectForChild` / `ensureScopeWithMounts`), reuse it: its `allowedTools`
+ * is already the post-intersection view. Otherwise synthesize a root scope
+ * from the caller's `manifest.tools`, normalized via `normalizeManifestTools`
+ * for a single source of truth. Callers that want a tighter inherited
+ * set must hand over a scoped AFS built via `projectForChild` or
+ * `ensureScopeWithMounts`.
+ */
+declare function resolveParentAgentScope(opts: {
+  afs: AFSRoot;
+  manifest: AgentManifest;
+  session?: string;
+}): AgentScope;
+/**
+ * Narrow down `parent` for a child agent:
+ *   - path projection via existing `projectSubAgent` (rewrite + readonly)
+ *   - tool ACL intersection via existing `intersectTools` (paths + ops)
+ *   - scope descriptor: session / rootSession / chainDepth+1 / allowedPaths
+ *
+ * If the parent has a non-empty `scope.allowedTools` and the child declares
+ * a non-empty `manifest.tools` that doesn't overlap (intersection empty),
+ * we throw `TOOL_INTERSECTION_EMPTY` — an empty intersection means the
+ * dispatcher has asked for an unreachable child scope, which is a hard
+ * error rather than a silently-permissive default.
+ *
+ * See design.md §5 for the full six-step mount composition; P2–P5 add
+ * scratch / memory / budget / session arms to the same function.
+ */
+declare function projectForChild(parent: AgentScope, options: ProjectForChildOptions): AgentScope;
+/**
+ * Phase 2 target — serialize a scope for cross-process hand-off (MCP
+ * sandbox worker, code-agent runner, …). Always throws in Phase 0/1 so
+ * no caller is tempted to persist a partial descriptor before the sandbox
+ * boundary exists.
+ */
+declare function toJSON(_scope: AgentScope): AgentScopeDescriptor;
+//#endregion
+export { AgentScope, AgentScopeDescriptor, AgentScopeDescriptorFields, CHAIN_DEPTH_HARD_CAP, ProjectForChildOptions, ensureScopeWithMounts, normalizeManifestTools, projectForChild, resolveParentAgentScope, rootAgentScope, toJSON };
+//# sourceMappingURL=scoped-afs.d.mts.map

package/dist/program/scoped-afs.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-afs.d.mts","names":[],"sources":["../../src/program/scoped-afs.ts"],"mappings":";;;;;;;;;;;AAmZA;;;;;;cAxVa,oBAAA;;;AAqWb;;;;;;UApRiB,WAAA;EAAA,SACN,WAAA;EAAA,SACA,KAAA;EACT,QAAA;AAAA;;;;;;;;AAibF;;;;;;;;;;;;;UA/MiB,0BAAA;EAAA,SACN,OAAA;EAAA,SACA,aAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA;EAAA,SACA,YAAA;EAAA,SACA,YAAA,WAAuB,SAAA;EA8NrB;AAsCb;;;;;EAtCa,SAvNF,YAAA;EAmQW;;;;;;;;EAAA,SA1PX,MAAA,GAAS,WAAA;AAAA;;;;;;;;;;UAYH,UAAA,SAAmB,OAAA;EAAA,SACzB,KAAA,EAAO,0BAAA;AAAA;;;;;;;;;;UAYD,sBAAA;EAkRL;EAAA,SAhRD,UAAA;EA8Q6B;EAAA,SA5Q7B,aAAA,EAAe,aAAA;EAgRZ;;AAoCd;;;EApCc,SA1QH,OAAA;AAAA;;;;;;;;;UAWM,oBAAA;EAAA,SACN,IAAA;EAAA,SACA,OAAA;EAAA,SACA,aAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA;EAAA,SACA,YAAA;EAAA,SACA,gBAAA,EAAkB,aAAA;IAAA,SAChB,IAAA;IAAA,SACA,kBAAA;EAAA;AAAA;;;;;;;;;;;iBA8CG,sBAAA,CAAuB,QAAA;EAAY,KAAA,GAAQ,aAAA;AAAA,IAA2B,SAAA;;;;;;;;;;;iBAoFtE,cAAA,CACd,GAAA,EAAK,OAAA,EACL,IAAA;EACE,OAAA;EACA,aAAA,GAAgB,SAAA;;;;;;;EAOhB,MAAA,GAAS,YAAA;;;;;;;;EAQT,YAAA;AAAA,IAED,UAAA;;;;;;;;;;;;iBAsCa,qBAAA,CACd,GAAA,EAAK,OAAA,EACL,IAAA;EACE,OAAA;EACA,aAAA,GAAgB,SAAA;EAChB,gBAAA,GAAmB,gBAAA;EACnB,eAAA,GAAkB,eAAA;;;;;;;EAOlB,MAAA,GAAS,YAAA;;;;;;;;;EAST,MAAA;AAAA,IAED,UAAA;;;;;;;;;;;;iBA6Ba,uBAAA,CAAwB,IAAA;EACtC,GAAA,EAAK,OAAA;EACL,QAAA,EAAU,aAAA;EACV,OAAA;AAAA,IACE,UAAA;;;;;;;;;;;;;;;;iBAoCY,eAAA,CAAgB,MAAA,EAAQ,UAAA,EAAY,OAAA,EAAS,sBAAA,GAAyB,UAAA;;;;;;;iBA8JtE,MAAA,CAAO,MAAA,EAAQ,UAAA,GAAa,oBAAA"}