pi-fabric 0.89.1 → 0.91.0

package/dist/agents.js

@@ -0,0 +1,615 @@
+import {
+  validateAgentResult
+} from "./chunks/chunk-3QECYQGA.js";
+import {
+  AGENTS_ACTION_DESCRIPTORS,
+  normalizeAgentRunRequest
+} from "./chunks/chunk-AAXQR7SZ.js";
+import {
+  actionArgNormalizer
+} from "./chunks/chunk-NQOEHX62.js";
+import {
+  AgentAdmission,
+  assertAgentTask,
+  beginAgentSettlement,
+  createAgentLifecycle,
+  finishAgentSettlement,
+  terminalAgentStatuses,
+  waitForAgent
+} from "./chunks/chunk-YDM3MYCO.js";
+import "./chunks/chunk-OTCASLY2.js";
+import "./chunks/chunk-MGWQOKBV.js";
+import "./chunks/chunk-3H7SDWZI.js";
+
+// src/agents/service-schema.ts
+import { Value } from "typebox/value";
+var native = (name) => {
+  const descriptor = AGENTS_ACTION_DESCRIPTORS.find((entry) => entry.name === name);
+  if (!descriptor) throw new Error(`Missing native agent descriptor: ${name}`);
+  return structuredClone(descriptor);
+};
+var run = native("run");
+var properties = { ...run.inputSchema.properties };
+for (const key of ["transport", "persona"]) delete properties[key];
+Object.assign(properties, {
+  runner: { type: "string", enum: ["pi"] },
+  kernel: { type: "string", enum: ["typescript", "inherit"] },
+  extensions: { type: "boolean", const: true },
+  worktree: { type: "boolean", const: false },
+  timeoutMs: { type: "number", minimum: 1 },
+  cwd: { type: "string", description: "Host-authorized placement selector; never resolved by Fabric" },
+  images: { type: "array", items: { type: "object", properties: { type: { const: "image" }, data: { type: "string" }, mimeType: { type: "string" } }, required: ["type", "data", "mimeType"], additionalProperties: false } },
+  systemPrompt: { type: "string" }
+});
+var runSchema = { type: "object", properties, required: ["task"], additionalProperties: false };
+var id = { type: "string", minLength: 1 };
+var object = (properties2, required = []) => ({ type: "object", properties: properties2, required, additionalProperties: false });
+function agentServiceDescriptors(capabilities = {}) {
+  const descriptors2 = [
+    { ...run, description: "Run one host-authorized Pi child and wait for its result or pause", inputSchema: runSchema },
+    { ...native("spawn"), description: "Admit one host-authorized Pi child and return its record", inputSchema: runSchema },
+    ...["wait", "status", "stop"].map((name) => ({ ...native(name), inputSchema: object({ id }, ["id"]) })),
+    { ...native("list"), description: "List only the authenticated caller's direct children", inputSchema: object({}) }
+  ];
+  if (capabilities.steer) descriptors2.push({ ...native("steer"), inputSchema: object({ id, message: { type: "string", minLength: 1 } }, ["id", "message"]) });
+  if (capabilities.compact) descriptors2.push({ ...native("compact"), inputSchema: object({ id, instructions: { type: "string" } }, ["id"]) });
+  if (capabilities.resume) descriptors2.push({ name: "resume", description: "Continue a paused, completed or failed direct child from its host checkpoint and wait for result or pause", risk: "agent", inputSchema: object({ id, task: { type: "string", minLength: 1 } }, ["id"]) });
+  return descriptors2;
+}
+var descriptors = agentServiceDescriptors({ steer: true, compact: true, resume: true });
+var normalize = actionArgNormalizer(() => descriptors);
+function agentServiceArgs(action, input) {
+  const descriptor = descriptors.find((entry) => entry.name === action);
+  if (!descriptor) throw new Error(`Unsupported hosted agents action: ${action}`);
+  const args = normalize(action, input);
+  if (!Value.Check(descriptor.inputSchema, args)) {
+    const reasons = [...Value.Errors(descriptor.inputSchema, args)].slice(0, 5).map((error) => `${error.instancePath}: ${error.message}`);
+    throw new Error(`Invalid hosted agents.${action} arguments: ${reasons.join("; ")}`);
+  }
+  return args;
+}
+function normalizeAgentServiceRequest(input) {
+  const args = agentServiceArgs("run", input);
+  const request = normalizeAgentRunRequest(args, { runner: "pi", timeoutMs: 0 });
+  if (args.images !== void 0) request.images = structuredClone(args.images);
+  if (args.systemPrompt !== void 0) request.systemPrompt = args.systemPrompt;
+  assertAgentTask(request);
+  return structuredClone(request);
+}
+
+// src/agents/service.ts
+var copy = (value) => structuredClone(value);
+var publicRecord = (record) => {
+  const keys = ["id", "rootId", "parentId", "depth", "generation", "name", "task", "status", "runner", "kernel", "cwd", "model", "thinking", "recursive", "startedAt", "updatedAt", "finishedAt", "currentTool", "turns", "toolCalls", "text", "value", "error", "usage", "sessionId"];
+  return copy(Object.fromEntries(keys.filter((key) => record[key] !== void 0).map((key) => [key, record[key]])));
+};
+var errorText = (error) => error instanceof Error ? error.message : String(error);
+var idle = () => ({ settled: true, result: void 0, resolve: void 0, release() {
+}, abortSignal: void 0, abortHandler: void 0 });
+var AgentService = class {
+  #options;
+  #entries = /* @__PURE__ */ new Map();
+  #admission;
+  #pending = /* @__PURE__ */ new Map();
+  #closing = new AbortController();
+  #close;
+  #suspend;
+  #suspended = false;
+  #sequence = 0;
+  #publication = Promise.resolve();
+  capabilities;
+  constructor(options) {
+    if (!options.rootId) throw new Error("Agent service requires a trusted rootId");
+    for (const [key, value] of Object.entries({ maxStarts: options.maxStarts ?? 8, maxDepth: options.maxDepth ?? 3, maxConcurrent: options.maxConcurrent ?? 4 })) {
+      if (!Number.isSafeInteger(value) || value < 1) throw new Error(`${key} must be a positive integer`);
+    }
+    this.#options = { ...options, port: options.port };
+    this.#admission = new AgentAdmission(options.maxConcurrent ?? 4, options.maxStarts ?? 8, options.maxDepth ?? 3);
+    this.capabilities = Object.freeze({ steer: Boolean(options.port.steer), compact: Boolean(options.port.compact), resume: Boolean(options.port.resume) });
+    if (options.snapshot) this.#restore(options.snapshot);
+  }
+  snapshot() {
+    return copy({
+      version: 1,
+      rootId: this.#options.rootId,
+      starts: this.#admission.starts,
+      sequence: this.#sequence,
+      records: [...this.#entries.values()].map(({ request, record }) => ({ request, record }))
+    });
+  }
+  async run(callerId, request, signal) {
+    const handle = await this.spawn(callerId, request, signal);
+    return this.wait(callerId, handle.id, signal);
+  }
+  async spawn(callerId, request, signal) {
+    return this.#start(callerId, normalizeAgentServiceRequest(request), void 0, signal);
+  }
+  async wait(callerId, id2, signal) {
+    await this.#authorize(callerId);
+    const entry = this.#child(callerId, id2);
+    const result = entry.lifecycle.result ?? Promise.resolve(copy(entry.record));
+    const record = await waitForAgent(result, signal);
+    await this.#authorize(callerId);
+    return publicRecord(record);
+  }
+  async status(callerId, id2) {
+    await this.#authorize(callerId);
+    return publicRecord(this.#child(callerId, id2).record);
+  }
+  async list(callerId) {
+    await this.#authorize(callerId);
+    return [...this.#entries.values()].filter((entry) => entry.record.parentId === callerId).map((entry) => publicRecord(entry.record));
+  }
+  async stop(callerId, id2) {
+    await this.#authorize(callerId);
+    const result = await this.#stop(this.#child(callerId, id2));
+    await this.#authorize(callerId);
+    return publicRecord(result);
+  }
+  async steer(callerId, id2, message) {
+    if (!this.#options.port.steer) throw new Error("Hosted agents.steer is unsupported");
+    if (!message.trim()) throw new Error("Steering message must not be empty");
+    return this.#control(callerId, id2, "steer", (request) => this.#options.port.steer({ ...request, message }));
+  }
+  async compact(callerId, id2, instructions) {
+    if (!this.#options.port.compact) throw new Error("Hosted agents.compact is unsupported");
+    return this.#control(callerId, id2, "compact", (request) => this.#options.port.compact({ ...request, ...instructions !== void 0 ? { instructions } : {} }));
+  }
+  async resume(callerId, id2, task, signal) {
+    if (!this.#options.port.resume) throw new Error("Hosted agents.resume is unsupported");
+    await this.#authorize(callerId);
+    const entry = this.#child(callerId, id2);
+    if (!["paused", "completed", "failed"].includes(entry.record.status) || !entry.lifecycle.settled || entry.resuming || entry.stopping) throw new Error("Only an idle paused, completed or failed agent can resume");
+    entry.resuming = true;
+    try {
+      const request = normalizeAgentServiceRequest({ ...entry.request, ...task !== void 0 ? { task } : {} });
+      await this.#start(callerId, request, entry, signal);
+      return await this.wait(callerId, id2, signal);
+    } finally {
+      entry.resuming = false;
+    }
+  }
+  /** Natural root completion waits for all background descendants without fencing live parents. */
+  async drain() {
+    for (; ; ) {
+      const work = [...this.#pending.values()];
+      for (const entry of this.#entries.values()) {
+        if (entry.lifecycle.result && entry.done) work.push(entry.done);
+      }
+      if (work.length === 0) return;
+      await Promise.allSettled(work);
+    }
+  }
+  /** Host-only graceful pause. The port, not the owner signal, quiesces participant effects. */
+  suspend() {
+    if (this.#suspend) return this.#suspend;
+    if (this.#closing.signal.aborted) return Promise.reject(new Error("Agent service is closed"));
+    if (!this.#options.port.pause && [...this.#entries.values()].some((entry) => !entry.lifecycle.settled)) {
+      return Promise.reject(new Error("Hosted agent suspension requires port.pause"));
+    }
+    this.#suspended = true;
+    for (const entry of this.#entries.values()) {
+      if (!entry.lifecycle.settled && !terminalAgentStatuses.has(entry.record.status)) entry.suspendRequested = true;
+    }
+    for (const controller of this.#pending.keys()) controller.abort();
+    this.#suspend = (async () => {
+      const roots = [...this.#entries.values()].filter((entry) => entry.record.parentId === this.#options.rootId);
+      const paused = await Promise.allSettled(roots.map((entry) => this.#pause(entry)));
+      await Promise.allSettled([...this.#pending.values()]);
+      const errors = paused.filter((result) => result.status === "rejected");
+      if (errors.length) throw new AggregateError(errors.map((result) => result.reason), "Agent suspension failed");
+      await this.drain();
+    })();
+    return this.#suspend;
+  }
+  async #pause(entry) {
+    const children = [...this.#entries.values()].filter((child) => child.record.parentId === entry.record.id);
+    const paused = await Promise.allSettled(children.map((child) => this.#pause(child)));
+    const errors = paused.filter((result) => result.status === "rejected").map((result) => result.reason);
+    if (errors.length) throw new AggregateError(errors, "Agent descendant suspension failed");
+    if (entry.executing && !entry.stopping) {
+      entry.pauseAck = Promise.resolve().then(async () => {
+        if (entry.executing && !entry.stopping) await this.#options.port.pause(this.#identity(entry));
+      });
+      try {
+        await entry.pauseAck;
+      } catch (error) {
+        throw new AggregateError([...errors, error], "Agent pause acknowledgment failed");
+      }
+    }
+    await entry.done;
+  }
+  close() {
+    if (this.#close) return this.#close;
+    this.#closing.abort();
+    for (const controller of this.#pending.keys()) controller.abort();
+    this.#close = (async () => {
+      const errors = [];
+      const stopped = await Promise.allSettled([...this.#entries.values()].map((entry) => this.#stop(entry, true)));
+      for (const result of stopped) if (result.status === "rejected") errors.push(result.reason);
+      await Promise.allSettled([...this.#pending.values()]);
+      if (errors.length) throw new AggregateError(errors, "Agent shutdown failed");
+    })();
+    return this.#close;
+  }
+  #start(callerId, request, previous, signal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted || this.#closing.signal.aborted || this.#suspended) controller.abort();
+    const operation = (async () => {
+      let release;
+      try {
+        await this.#authorize(callerId);
+        const depth = this.#depth(callerId);
+        if (controller.signal.aborted) throw new Error("Operation aborted");
+        if (depth > this.#admission.maxDepth) throw new Error(`Fabric agent depth limit reached (${this.#admission.maxDepth})`);
+        const id2 = previous?.record.id ?? crypto.randomUUID().replaceAll("-", "");
+        const generation = (previous?.record.generation ?? 0) + 1;
+        const prepare = { id: id2, generation, rootId: this.#options.rootId, parentId: callerId, depth, request: copy(request), signal: controller.signal };
+        const binding = await this.#options.port.prepare?.(prepare);
+        release = await this.#admission.acquire(callerId, controller.signal);
+        await this.#authorize(callerId);
+        this.#depth(callerId);
+        if (controller.signal.aborted || this.#closing.signal.aborted || previous?.stopping) throw new Error("Agent admission aborted");
+        this.#admission.admit(depth);
+        const now = Date.now();
+        const record = previous ? {
+          ...previous.record,
+          task: request.task,
+          status: "queued",
+          generation: previous.record.generation + 1,
+          text: "",
+          turns: 0,
+          toolCalls: 0,
+          updatedAt: now
+        } : {
+          id: id2,
+          rootId: this.#options.rootId,
+          parentId: callerId,
+          depth,
+          generation: 1,
+          name: (request.name ?? request.task.split("\n", 1)[0] ?? "Fabric agent").replace(/[\r\n\t]+/g, " ").trim().slice(0, 60) || "Fabric agent",
+          task: request.task,
+          status: "queued",
+          runner: "pi",
+          kernel: "typescript",
+          startedAt: now,
+          updatedAt: now,
+          turns: 0,
+          toolCalls: 0,
+          text: "",
+          usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 },
+          ...request.model ? { model: request.model } : {},
+          ...request.thinking ? { thinking: request.thinking } : {},
+          ...request.cwd !== void 0 ? { cwd: request.cwd } : {},
+          ...request.recursive !== void 0 ? { recursive: request.recursive } : {}
+        };
+        delete record.finishedAt;
+        delete record.error;
+        delete record.value;
+        delete record.currentTool;
+        const entry = previous ?? { request, record, lifecycle: idle(), controller };
+        entry.request = copy(request);
+        entry.record = record;
+        entry.controller = controller;
+        entry.lifecycle = createAgentLifecycle(release);
+        release = void 0;
+        this.#entries.set(record.id, entry);
+        this.#pending.delete(controller);
+        signal?.removeEventListener("abort", abort);
+        let acknowledge;
+        const admitted = new Promise((resolve) => {
+          acknowledge = resolve;
+        });
+        entry.done = this.#drive(entry, binding, Boolean(previous), acknowledge);
+        await admitted;
+        await this.#authorize(callerId);
+        return publicRecord(record);
+      } finally {
+        release?.();
+        signal?.removeEventListener("abort", abort);
+      }
+    })();
+    this.#pending.set(controller, operation);
+    void operation.finally(() => this.#pending.delete(controller)).catch(() => {
+    });
+    return operation;
+  }
+  async #drive(entry, binding, resume, admitted) {
+    const generation = entry.record.generation;
+    let timer;
+    let timeout = false;
+    let responded = false;
+    try {
+      await this.#publish("admitted", entry);
+      admitted();
+      await this.#authorize(entry.record.parentId);
+      if (entry.controller.signal.aborted) throw new Error("Agent start aborted");
+      entry.record.status = "running";
+      await this.#publish("running", entry);
+      await this.#authorize(entry.record.parentId);
+      if (entry.controller.signal.aborted) throw new Error("Agent start aborted");
+      const request = {
+        ...this.#identity(entry),
+        depth: entry.record.depth,
+        request: copy(entry.request),
+        signal: entry.controller.signal,
+        binding,
+        ...entry.record.checkpoint !== void 0 ? { checkpoint: copy(entry.record.checkpoint) } : {},
+        emit: async (event) => {
+          const assertCurrent = () => {
+            if (!entry.executing || entry.lifecycle.settled || entry.controller.signal.aborted || entry.record.generation !== generation || entry.record.status !== "running") throw new Error("Stale agent execution event");
+          };
+          assertCurrent();
+          if (event.type !== "checkpoint" && event.type !== "progress") throw new Error("Unsupported agent execution event");
+          const saved = copy(event);
+          await this.#publish(saved.type, entry, void 0, () => {
+            if (saved.type === "checkpoint") entry.record.checkpoint = saved.checkpoint;
+            else {
+              for (const key of ["text", "turns", "toolCalls", "currentTool", "usage"]) {
+                if (saved[key] !== void 0) Object.assign(entry.record, { [key]: saved[key] });
+              }
+            }
+          }, assertCurrent);
+        }
+      };
+      if (entry.request.timeoutMs) timer = setTimeout(() => {
+        if (entry.suspendRequested) return;
+        timeout = true;
+        void this.#stop(entry).catch(() => {
+        });
+      }, entry.request.timeoutMs);
+      const execute = resume ? this.#options.port.resume : this.#options.port.execute;
+      entry.executing = true;
+      let response;
+      try {
+        response = await execute.call(this.#options.port, request);
+      } finally {
+        entry.executing = false;
+      }
+      if (!["completed", "failed", "stopped", "timed_out", "paused"].includes(response.status)) throw new Error("Invalid agent execution response status");
+      await this.#authorize(entry.record.parentId, response.status === "paused" ? { checkpoint: true } : void 0);
+      if (entry.record.generation !== generation || entry.lifecycle.settled) throw new Error("Stale agent execution response");
+      this.#applyResponse(entry, response);
+      responded = true;
+    } catch (error) {
+      entry.record.status = "failed";
+      entry.record.error = errorText(error);
+    } finally {
+      admitted();
+      if (timer) clearTimeout(timer);
+      await Promise.allSettled([...entry.controls ?? [], ...entry.stopAck ? [entry.stopAck] : [], ...entry.pauseAck ? [entry.pauseAck] : []]);
+      if (entry.suspendRequested && !entry.controller.signal.aborted) {
+        entry.record.status = "paused";
+        delete entry.record.error;
+        delete entry.record.finishedAt;
+      }
+      if (entry.controller.signal.aborted) {
+        if (entry.stopReason === "close") {
+          if (!responded || !["completed", "failed"].includes(entry.record.status)) {
+            entry.record.status = "paused";
+            delete entry.record.error;
+          }
+        } else entry.record.status = timeout ? "timed_out" : "stopped";
+      }
+      try {
+        await this.#options.port.cleanup?.(this.#identity(entry));
+      } catch (error) {
+        entry.record.status = "failed";
+        entry.record.error = `Agent cleanup failed: ${errorText(error)}`;
+      }
+      validateAgentResult(entry.record, entry.request.schema);
+      delete entry.record.currentTool;
+      if (terminalAgentStatuses.has(entry.record.status)) entry.record.finishedAt = Date.now();
+      if (beginAgentSettlement(entry.lifecycle)) {
+        try {
+          await this.#publish("settled", entry);
+        } catch (error) {
+          entry.record.status = "failed";
+          entry.record.error = `Agent publication failed: ${errorText(error)}`;
+        }
+        finishAgentSettlement(entry.lifecycle, copy(entry.record));
+      }
+    }
+  }
+  #applyResponse(entry, response) {
+    entry.record.status = response.status;
+    for (const key of ["text", "value", "error", "usage", "checkpoint", "sessionId"]) {
+      if (response[key] !== void 0) Object.assign(entry.record, { [key]: copy(response[key]) });
+    }
+  }
+  #stop(entry, preservePaused = false) {
+    if (entry.stopping) return entry.stopping;
+    entry.stopReason = preservePaused ? "close" : "stop";
+    const work = (async () => {
+      const active = !entry.lifecycle.settled;
+      entry.controller.abort();
+      const descendants = [...this.#entries.values()].filter((child) => child.record.parentId === entry.record.id);
+      const operations = descendants.map((child) => this.#stop(child, preservePaused));
+      if (active && this.#options.port.stop) {
+        entry.stopAck = Promise.resolve().then(() => this.#options.port.stop(this.#identity(entry)));
+        operations.push(entry.stopAck);
+      }
+      if (entry.done) operations.push(entry.done);
+      const settled = await Promise.allSettled(operations);
+      if (entry.record.status === "paused" && !preservePaused) {
+        entry.record.status = "stopped";
+        entry.record.finishedAt = Date.now();
+        await this.#publish("settled", entry);
+      }
+      const errors = settled.filter((result) => result.status === "rejected");
+      if (errors.length) throw new AggregateError(errors.map((result) => result.reason), "Agent stop failed");
+      return publicRecord(entry.record);
+    })();
+    entry.stopping = work;
+    return work;
+  }
+  async #control(callerId, id2, control, invoke) {
+    await this.#authorize(callerId);
+    const entry = this.#child(callerId, id2);
+    if (entry.record.status !== "running" || entry.stopping) throw new Error("Agent is not running");
+    const generation = entry.record.generation;
+    const pending = Promise.resolve().then(async () => {
+      await this.#authorize(callerId);
+      if (entry.record.generation !== generation || entry.controller.signal.aborted || entry.lifecycle.settled) throw new Error("Stale agent control");
+      await invoke(this.#identity(entry));
+    });
+    (entry.controls ??= /* @__PURE__ */ new Set()).add(pending);
+    try {
+      await pending;
+    } finally {
+      entry.controls.delete(pending);
+    }
+    await this.#authorize(callerId);
+    if (entry.record.generation !== generation || entry.controller.signal.aborted) throw new Error("Stale agent control acknowledgment");
+    await this.#publish("control", entry, control);
+    return publicRecord(entry.record);
+  }
+  #identity(entry) {
+    const { id: id2, rootId, parentId, generation } = entry.record;
+    return { id: id2, rootId, parentId, generation };
+  }
+  async #authorize(callerId, boundary) {
+    if (callerId !== this.#options.rootId && !this.#entries.has(callerId)) throw new Error("Unknown agent caller");
+    if (this.#suspended && !boundary?.checkpoint) throw new Error("Agent service is paused");
+    await this.#options.assertAuthority?.(callerId, boundary);
+    if (this.#suspended && !boundary?.checkpoint) throw new Error("Agent service is paused");
+  }
+  #child(callerId, id2) {
+    const entry = this.#entries.get(id2);
+    if (!entry || entry.record.parentId !== callerId) throw new Error(`Unknown direct child agent: ${id2}`);
+    return entry;
+  }
+  #depth(callerId) {
+    if (this.#closing.signal.aborted) throw new Error("Agent service is closed");
+    if (this.#suspended) throw new Error("Agent service is paused");
+    if (callerId === this.#options.rootId) return 1;
+    const parent = this.#entries.get(callerId);
+    if (!parent || parent.record.status !== "running" || parent.stopping || parent.controller.signal.aborted || parent.request.recursive === false) throw new Error("Agent parent cannot admit children");
+    return parent.record.depth + 1;
+  }
+  async #publish(type, entry, control, update, assertCurrent) {
+    const boundary = type === "checkpoint" || type === "settled" ? { checkpoint: true } : void 0;
+    const generation = entry.record.generation;
+    await this.#authorize(entry.record.parentId, boundary);
+    const publication = this.#publication.then(async () => {
+      await this.#authorize(entry.record.parentId, boundary);
+      if (entry.record.generation !== generation) throw new Error("Stale agent publication");
+      assertCurrent?.();
+      update?.();
+      entry.record.updatedAt = Date.now();
+      const event = { version: 1, sequence: ++this.#sequence, type, record: copy(entry.record), ...control ? { control } : {} };
+      await this.#options.onEvent?.(event);
+    });
+    this.#publication = publication.catch(() => {
+    });
+    await publication;
+  }
+  #restore(snapshot) {
+    const saved = copy(snapshot);
+    const newRoot = this.#options.restorePolicy === "new-root";
+    if (newRoot && saved.rootId !== this.#options.rootId) {
+      const oldRoot = saved.rootId;
+      saved.rootId = this.#options.rootId;
+      for (const { record } of saved.records) {
+        if (record.rootId !== oldRoot) throw new Error("Invalid agent snapshot root");
+        record.rootId = saved.rootId;
+        if (record.parentId === oldRoot) record.parentId = saved.rootId;
+      }
+    }
+    if (saved.version !== 1 || saved.rootId !== this.#options.rootId || !Number.isSafeInteger(saved.starts) || saved.starts < 0 || !newRoot && saved.starts > this.#admission.maxStarts || !Number.isSafeInteger(saved.sequence) || saved.sequence < 0 || !Array.isArray(saved.records)) throw new Error("Invalid agent service snapshot");
+    let generations = 0;
+    for (const item of saved.records) {
+      const request = normalizeAgentServiceRequest(item.request);
+      const record = item.record;
+      if (!record.id || record.id === saved.rootId || this.#entries.has(record.id) || record.rootId !== saved.rootId || !Number.isSafeInteger(record.depth) || record.depth < 1 || record.depth > this.#admission.maxDepth || !Number.isSafeInteger(record.generation) || record.generation < 1 || !["queued", "running", "paused", ...terminalAgentStatuses].includes(record.status)) throw new Error("Invalid agent snapshot record");
+      generations += record.generation;
+      if (record.status === "running" || record.status === "queued") {
+        record.status = "paused";
+        delete record.finishedAt;
+      }
+      this.#entries.set(record.id, { request, record, lifecycle: idle(), controller: new AbortController() });
+    }
+    for (const { record } of this.#entries.values()) {
+      const parent = this.#entries.get(record.parentId);
+      if (record.parentId === saved.rootId ? record.depth !== 1 : !parent || parent.record.depth + 1 !== record.depth) throw new Error("Invalid agent snapshot lineage");
+    }
+    if (saved.starts > generations) throw new Error("Invalid agent snapshot admission count");
+    this.#admission.starts = newRoot ? 0 : saved.starts;
+    this.#sequence = saved.sequence;
+  }
+};
+
+// src/agents/service-provider.ts
+function createAgentServiceHandler(service, callerId) {
+  return async (action, input, signal) => {
+    const args = agentServiceArgs(action, input);
+    switch (action) {
+      case "run":
+        return service.run(callerId, args, signal);
+      case "spawn":
+        return service.spawn(callerId, args, signal);
+      case "wait":
+        return service.wait(callerId, args.id, signal);
+      case "status":
+        return service.status(callerId, args.id);
+      case "list":
+        return service.list(callerId);
+      case "stop":
+        return service.stop(callerId, args.id);
+      case "steer":
+        return service.steer(callerId, args.id, args.message);
+      case "compact":
+        return service.compact(callerId, args.id, args.instructions);
+      case "resume":
+        return service.resume(callerId, args.id, args.task, signal);
+      default:
+        throw new Error(`Unsupported hosted agents action: ${String(action)}`);
+    }
+  };
+}
+function createAgentServiceClient(dispatch, capabilities = {}) {
+  const record = (action, args, signal) => dispatch(action, args, signal);
+  return {
+    capabilities: Object.freeze({ ...capabilities }),
+    dispatch,
+    run: (request, signal) => record("run", request, signal),
+    spawn: (request, signal) => record("spawn", request, signal),
+    wait: (id2, signal) => record("wait", { id: id2 }, signal),
+    status: (id2) => record("status", { id: id2 }),
+    list: () => dispatch("list", {}),
+    stop: (id2) => record("stop", { id: id2 }),
+    steer: (id2, message) => record("steer", { id: id2, message }),
+    compact: (id2, instructions) => record("compact", { id: id2, ...instructions !== void 0 ? { instructions } : {} }),
+    resume: (id2, task, signal) => record("resume", { id: id2, ...task !== void 0 ? { task } : {} }, signal)
+  };
+}
+function createAgentsProvider(client) {
+  const descriptors2 = agentServiceDescriptors(client.capabilities);
+  const allowed = new Set(descriptors2.map((descriptor) => descriptor.name));
+  const validate = (action, args) => {
+    if (!allowed.has(action)) throw new Error(`Unsupported hosted agents action: ${action}`);
+    return agentServiceArgs(action, args);
+  };
+  return {
+    name: "agents",
+    description: "Fabric host-authorized Pi agents",
+    list: async () => structuredClone(descriptors2),
+    describe: async (name) => structuredClone(descriptors2.find((descriptor) => descriptor.name === name)),
+    prepareArguments: (action, args) => validate(action, args),
+    invoke: async (action, args, context) => client.dispatch(action, validate(action, args), context.signal)
+  };
+}
+
+// src/agents.ts
+var HOSTED_AGENTS_PROTOCOL_VERSION = 1;
+export {
+  AgentService,
+  HOSTED_AGENTS_PROTOCOL_VERSION,
+  agentServiceDescriptors,
+  createAgentServiceClient,
+  createAgentServiceHandler,
+  createAgentsProvider
+};
+//# sourceMappingURL=agents.js.map