@hachej/boring-agent 0.1.104 → 0.1.105

package/dist/{chunk-BTYOMR7W.js → chunk-LFN45QDZ.js}

@@ -7,7 +7,7 @@ import {
   readConfiguredDefaultModel,
   registerConfiguredModelProviders,
   withPiHarnessDefaults
-} from "./chunk-I7KFNGB4.js";
+} from "./chunk-F2OJI2LX.js";
 import {
   AGENT_KNOWLEDGE_FILESYSTEM_ID,
   AgentDefinitionValidationError,
@@ -2824,7 +2824,7 @@ async function createConfiguredAgentHostAgentSpec(input) {
     ...plugin.config === void 0 ? {} : { config: frozenJson(plugin.config) }
   }));
   const preferredModel = nonEmpty(policy.preferredModel);
-  const instructionFiles = policy.instructionFiles?.length ? Object.freeze(policy.instructionFiles.map((file) => Object.freeze({ ...file }))) : void 0;
+  const instructionSources = policy.instructionSources?.length ? Object.freeze(policy.instructionSources.map((source) => Object.freeze({ ...source }))) : void 0;
   return Object.freeze({
     agentTypeId: input.source.agentTypeId,
     definition: Object.freeze({
@@ -2834,24 +2834,75 @@ async function createConfiguredAgentHostAgentSpec(input) {
       ...input.source.definitionDigest === void 0 ? {} : { digest: input.source.definitionDigest }
     }),
     ...input.source.knowledgeDir === void 0 ? {} : { knowledge: Object.freeze({ rootDir: input.source.knowledgeDir }) },
-    ...instructionFiles ? { instructionFiles } : {},
+    ...instructionSources ? { instructionSources } : {},
     ...plugins?.length ? { plugins: Object.freeze(plugins) } : {},
     ...preferredModel ? { model: Object.freeze({ preferred: preferredModel }) } : {}
   });
 }
 
 // src/server/agentDefinition/loadConfiguredAgentFleet.ts
-import { lstat as lstat3, readFile as readFile3, realpath as realpath4 } from "node:fs/promises";
-import { basename as basename2, isAbsolute as isAbsolute5, relative as relative6, resolve as resolve4, sep as sep5 } from "node:path";
+import { lstat as lstat3, readFile as readFile3, realpath as realpath5 } from "node:fs/promises";
+import { basename as basename2, resolve as resolve5 } from "node:path";
 import { parse as parseYaml } from "yaml";
 
+// src/server/agentDefinition/instructionFileRefs.ts
+import { realpath as realpath4 } from "node:fs/promises";
+import { isAbsolute as isAbsolute5, relative as relative6, resolve as resolve4, sep as sep5 } from "node:path";
+
 // src/server/agent-host/types.ts
 var AGENT_USER_FILESYSTEM_ID = "user";
 
-// src/server/agentDefinition/loadConfiguredAgentFleet.ts
+// src/server/agentDefinition/instructionFileRefs.ts
+function isCanonicalPathInside(root, target) {
+  const fromRoot = relative6(root, target);
+  return fromRoot === "" || fromRoot !== ".." && !fromRoot.startsWith(`..${sep5}`) && !isAbsolute5(fromRoot);
+}
 function isPublishableWorkspacePath(value) {
   return value.length > 0 && !value.includes("\0") && !value.includes("\\") && !value.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(value) && !/%(?:2e|2f|5c)/i.test(value) && !/^[A-Za-z][A-Za-z0-9+.-]*:/.test(value) && !value.split("/").some((segment) => segment === "" || segment === "." || segment === "..");
 }
+async function resolveAgentInstructionFileRefs(input) {
+  const sources = input.sources ?? [];
+  if (sources.length === 0) return Object.freeze({ refs: Object.freeze([]), withheld: Object.freeze([]) });
+  const canonicalWorkspaceRoot = typeof input.workspaceRoot === "string" && input.workspaceRoot.trim() ? await realpath4(resolve4(input.workspaceRoot)).catch(() => null) : null;
+  const refs = [];
+  const withheld = [];
+  for (const source of sources) {
+    if (canonicalWorkspaceRoot === null) {
+      withheld.push({
+        code: ErrorCode.enum.AGENT_FLEET_SEAT_INSTRUCTIONS_PATH_UNPUBLISHABLE,
+        absolutePath: source.absolutePath,
+        message: `this request resolves no readable workspace root, so persona instructions have no "${AGENT_USER_FILESYSTEM_ID}" path to be addressed against`
+      });
+      continue;
+    }
+    const canonicalSource = await realpath4(resolve4(source.absolutePath)).catch(() => null);
+    if (canonicalSource === null || !isCanonicalPathInside(canonicalWorkspaceRoot, canonicalSource)) {
+      withheld.push({
+        code: ErrorCode.enum.AGENT_FLEET_SEAT_INSTRUCTIONS_PATH_UNPUBLISHABLE,
+        absolutePath: source.absolutePath,
+        message: `instruction source resolves outside the workspace root that the "${AGENT_USER_FILESYSTEM_ID}" filesystem serves for this request`
+      });
+      continue;
+    }
+    const path = relative6(canonicalWorkspaceRoot, canonicalSource).split(sep5).join("/");
+    if (!isPublishableWorkspacePath(path)) {
+      withheld.push({
+        code: ErrorCode.enum.AGENT_FLEET_SEAT_INSTRUCTIONS_PATH_UNPUBLISHABLE,
+        absolutePath: source.absolutePath,
+        message: `instruction source composes an unsafe workspace-relative path (${JSON.stringify(path)})`
+      });
+      continue;
+    }
+    refs.push(Object.freeze({
+      filesystem: AGENT_USER_FILESYSTEM_ID,
+      path,
+      role: source.role
+    }));
+  }
+  return Object.freeze({ refs: Object.freeze(refs), withheld: Object.freeze(withheld) });
+}
+
+// src/server/agentDefinition/loadConfiguredAgentFleet.ts
 var FleetConfigError = class extends Error {
   code;
   field;
@@ -2862,10 +2913,6 @@ var FleetConfigError = class extends Error {
     this.field = input.field;
   }
 };
-function isCanonicalPathInside(root, target) {
-  const fromRoot = relative6(root, target);
-  return fromRoot === "" || fromRoot !== ".." && !fromRoot.startsWith(`..${sep5}`) && !isAbsolute5(fromRoot);
-}
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -2974,13 +3021,13 @@ function resolveSeatModel(tier, env, modelTierCandidates) {
   return void 0;
 }
 async function readVerifiedSkillContent(root, reference, skill) {
-  const rootTarget = await realpath4(root);
-  let candidate = resolve4(rootTarget, reference);
+  const rootTarget = await realpath5(root);
+  let candidate = resolve5(rootTarget, reference);
   const candidateStat = await lstat3(candidate);
-  if (candidateStat.isDirectory()) candidate = resolve4(candidate, "SKILL.md");
+  if (candidateStat.isDirectory()) candidate = resolve5(candidate, "SKILL.md");
   const fileStat = await lstat3(candidate);
   if (!fileStat.isFile() || fileStat.isSymbolicLink()) throw new Error("skill source is not a regular file");
-  const target = await realpath4(candidate);
+  const target = await realpath5(candidate);
   if (!isCanonicalPathInside(rootTarget, target)) throw new Error("skill source resolves outside its admitted root");
   const content = await readFile3(target, "utf8");
   if (await sha256(content) !== skill.digest) throw new Error("skill digest mismatch");
@@ -3012,7 +3059,6 @@ async function loadConfiguredAgentFleet(options) {
     seatTiers = Object.freeze({});
   }
   validateSeatTierCandidates(seatTiers, modelTierCandidates, options.fleetConfigPath, options.policyPath);
-  const canonicalWorkspaceRoot = options.workspaceRoot === null ? null : await realpath4(resolve4(options.workspaceRoot)).catch(() => null);
   const agents = [];
   const diagnostics = [];
   const packagesByDefinitionId = /* @__PURE__ */ new Map();
@@ -3054,7 +3100,7 @@ async function loadConfiguredAgentFleet(options) {
       if (conflictedDefinitionIds.has(binding.agentTypeId)) continue;
       const descriptor = descriptors[0];
       if (!descriptor || !descriptor.preflight.ok) throw new Error(`seat "${binding.seat}" has no valid discovered agent package`);
-      const personaSource = await realpath4(resolve4(descriptor.rootDir));
+      const personaSource = await realpath5(resolve5(descriptor.rootDir));
       const source = await materializeAgentDirectory({
         directory: personaSource,
         expectedAgentTypeId: binding.agentTypeId,
@@ -3092,29 +3138,15 @@ async function loadConfiguredAgentFleet(options) {
         instructionAppendices.push({ name: appendixName, digest: skill.digest, content });
       }
       const preferredModel = resolveSeatModel(seatTiers[binding.seat], env, modelTierCandidates);
-      let instructionFiles;
-      const personaIsInsideWorkspace = canonicalWorkspaceRoot !== null && isCanonicalPathInside(canonicalWorkspaceRoot, personaSource);
-      const publishedInstructionPath = canonicalWorkspaceRoot === null ? "" : relative6(canonicalWorkspaceRoot, resolve4(personaSource, "instructions.md")).split(sep5).join("/");
-      const unpublishableReason = options.workspaceRoot === null ? `this host resolves a workspace root per request, so persona instructions have no single "${AGENT_USER_FILESYSTEM_ID}" path to be addressed against` : canonicalWorkspaceRoot === null || !personaIsInsideWorkspace ? `persona source for seat ${JSON.stringify(binding.seat)} resolves outside the workspace root ${JSON.stringify(options.workspaceRoot)} that the "${AGENT_USER_FILESYSTEM_ID}" filesystem serves` : !isPublishableWorkspacePath(publishedInstructionPath) ? `seat "${binding.seat}" composes an unsafe workspace-relative path (${JSON.stringify(publishedInstructionPath)})` : void 0;
-      if (unpublishableReason) {
-        diagnostics.push({
-          seat: binding.seat,
-          agentTypeId: binding.agentTypeId,
-          code: ErrorCode.enum.AGENT_FLEET_SEAT_INSTRUCTIONS_PATH_UNPUBLISHABLE,
-          message: `${unpublishableReason}; its persona instructions will not be linkable`
-        });
-      } else {
-        instructionFiles = [{
-          filesystem: AGENT_USER_FILESYSTEM_ID,
-          path: publishedInstructionPath,
-          role: "persona"
-        }];
-      }
+      const instructionSources = [{
+        absolutePath: resolve5(personaSource, "instructions.md"),
+        role: "persona"
+      }];
       const spec = await createConfiguredAgentHostAgentSpec({
         source,
         policy: {
           instructionAppendices,
-          ...instructionFiles ? { instructionFiles } : {},
+          instructionSources,
           ...preferredModel ? { preferredModel } : {}
         }
       });
@@ -3134,7 +3166,7 @@ async function loadConfiguredAgentFleet(options) {
 }
 
 // src/server/agentDefinition/resolveDefaultAgentFleet.ts
-import { resolve as resolve5 } from "node:path";
+import { resolve as resolve6 } from "node:path";
 import { createLogger } from "@hachej/boring-bash/server";
 var logger = createLogger("agent-fleet-loader");
 var LEGACY_DEFAULT_AGENT_FLEET = Object.freeze([
@@ -3148,15 +3180,13 @@ async function resolveDefaultAgentFleet(options) {
     if (!options.discoveredPackages) throw new Error("agent package discovery descriptors were not injected by the boot layer");
     const { agents: configuredAgents, diagnostics } = await loadConfiguredAgentFleet({
       discoveredPackages: options.discoveredPackages,
-      workspaceRoot: options.workspaceRoot,
-      fleetConfigPath: resolve5(root, ".agents", "factory", "fleet.yaml"),
-      policyPath: resolve5(root, ".agents", "factory", "policy.yaml"),
-      skillsRoot: resolve5(root, ".agents", "skills"),
+      fleetConfigPath: resolve6(root, ".agents", "factory", "fleet.yaml"),
+      policyPath: resolve6(root, ".agents", "factory", "policy.yaml"),
+      skillsRoot: resolve6(root, ".agents", "skills"),
       env
     });
     for (const diagnostic of diagnostics) {
-      const excluded = diagnostic.code !== ErrorCode.enum.AGENT_FLEET_SEAT_INSTRUCTIONS_PATH_UNPUBLISHABLE;
-      logger.warn(excluded ? "fleet package excluded or inert" : "fleet seat instructions not linkable", {
+      logger.warn("fleet package excluded or inert", {
         seat: diagnostic.seat,
         agentTypeId: diagnostic.agentTypeId,
         code: diagnostic.code,
@@ -4256,13 +4286,13 @@ function resultTool(result) {
   };
 }
 function deferred() {
-  let resolve9;
+  let resolve10;
   let reject;
   const promise = new Promise((res, rej) => {
-    resolve9 = res;
+    resolve10 = res;
     reject = rej;
   });
-  return { promise, resolve: resolve9, reject };
+  return { promise, resolve: resolve10, reject };
 }
 function errorTool(error) {
   const safe = safeError(error);
@@ -4676,7 +4706,7 @@ function isSqliteBusy(error) {
   return (code === "SQLITE_BUSY" || code === "ERR_SQLITE_ERROR") && /busy|lock/i.test(error.message);
 }
 function delay(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 function clampLimit(value, defaultValue, maxValue) {
   if (value === void 0) return defaultValue;
@@ -5893,6 +5923,11 @@ function normalizeMeteringUsage(value) {
     }
   };
 }
+function isExplicitCompleteZeroUsage(value) {
+  if (!isRecord4(value) || !isRecord4(value.cost)) return false;
+  const hasOwnZeroFields = (record, fields) => fields.every((field) => Object.prototype.hasOwnProperty.call(record, field) && record[field] === 0);
+  return hasOwnZeroFields(value, ["input", "output", "cacheRead", "cacheWrite", "totalTokens"]) && hasOwnZeroFields(value.cost, ["input", "output", "cacheRead", "cacheWrite", "total"]);
+}
 var PiChatMeteringCoordinator = class {
   sessions = /* @__PURE__ */ new Map();
   inflightOps = /* @__PURE__ */ new Set();
@@ -6160,13 +6195,18 @@ var PiChatMeteringCoordinator = class {
   }
   recordAssistantUsage(state, message, opts = {}) {
     if (!isRecord4(message) || message.role !== "assistant") return;
+    if (!Object.prototype.hasOwnProperty.call(message, "usage")) return;
+    const explicitCompleteZero = isExplicitCompleteZeroUsage(message.usage);
     const usage = normalizeMeteringUsage(message.usage);
-    if (!usage) return;
     const run2 = state.active ?? state.pendingPrompts[0];
     if (!run2 || run2.terminal) {
       this.logError("assistant usage arrived with no reserved run; usage not metered", { messageRole: "assistant" });
       return;
     }
+    if (!usage) {
+      run2.allUsageReportsExplicitZero = false;
+      return;
+    }
     const messageId = typeof message.id === "string" && message.id.length > 0 ? message.id : void 0;
     if (messageId) {
       if (run2.recordedMessageIds.has(messageId)) return;
@@ -6178,6 +6218,7 @@ var PiChatMeteringCoordinator = class {
       run2.lastIdlessUsageKey = signature;
     }
     run2.usageCount += 1;
+    if (!explicitCompleteZero) run2.allUsageReportsExplicitZero = false;
     const model = typeof message.model === "string" && message.model.length > 0 ? message.model : void 0;
     const provider = typeof message.provider === "string" && message.provider.length > 0 ? message.provider : void 0;
     const stopReason = typeof message.stopReason === "string" ? message.stopReason : void 0;
@@ -6196,9 +6237,9 @@ var PiChatMeteringCoordinator = class {
             stopReason
           });
           if (result.billedMicros > 0) run2.billableUsageCount += 1;
+          if (explicitCompleteZero) run2.persistedExplicitZeroUsageCount += 1;
         } catch (error) {
-          const couldBill = usage.input + usage.output + usage.cacheRead + usage.cacheWrite > 0 || usage.cost.total > 0;
-          if (couldBill) run2.usageWriteFailed = true;
+          if (!explicitCompleteZero) run2.usageWriteFailed = true;
           throw error;
         }
       },
@@ -6222,6 +6263,8 @@ var PiChatMeteringCoordinator = class {
       reservationId: void 0,
       instanceId: this.runInstances += 1,
       usageCount: 0,
+      allUsageReportsExplicitZero: true,
+      persistedExplicitZeroUsageCount: 0,
       billableUsageCount: 0,
       recordedMessageIds: /* @__PURE__ */ new Set(),
       lastIdlessUsageKey: void 0,
@@ -6268,8 +6311,10 @@ var PiChatMeteringCoordinator = class {
         if (run2.billableUsageCount > 0) {
           return this.sink.settleRun({ ...run2.scope, reservationId: run2.reservationId, status });
         }
-        const didPaidWork = status === "ok" && !run2.userStopped;
-        if (didPaidWork) {
+        if (status === "ok" && !run2.userStopped && run2.usageCount > 0 && run2.allUsageReportsExplicitZero && run2.persistedExplicitZeroUsageCount === run2.usageCount) {
+          return this.sink.settleRun({ ...run2.scope, reservationId: run2.reservationId, status });
+        }
+        if (status === "ok" && !run2.userStopped) {
           return this.sink.releaseRun({ ...run2.scope, reservationId: run2.reservationId, reason: "fallback-hold-charge" });
         }
         return this.sink.releaseRun({
@@ -6372,11 +6417,11 @@ function bindingDisposedError() {
   });
 }
 function deferred2() {
-  let resolve9;
+  let resolve10;
   const promise = new Promise((nextResolve) => {
-    resolve9 = () => nextResolve();
+    resolve10 = () => nextResolve();
   });
-  return { promise, resolve: resolve9 };
+  return { promise, resolve: resolve10 };
 }
 
 // src/server/codedError.ts
@@ -7254,13 +7299,13 @@ function promptCancelledError() {
   });
 }
 function deferred3() {
-  let resolve9;
+  let resolve10;
   let reject;
   const promise = new Promise((nextResolve, nextReject) => {
-    resolve9 = nextResolve;
+    resolve10 = nextResolve;
     reject = nextReject;
   });
-  return { promise, resolve: resolve9, reject };
+  return { promise, resolve: resolve10, reject };
 }
 function rejectedReasons(results) {
   return results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
@@ -7789,10 +7834,17 @@ var AgentSessionInventory = class {
   compiledById;
   resolveAgentRuntimeScope;
   stores = /* @__PURE__ */ new Map();
-  async list(agentTypeId, scope, claim) {
+  /**
+   * Lists a seat's sessions. `options` is threaded straight into the store so a
+   * bounded page reads a bounded number of transcripts: an unbounded call makes
+   * the store stream and parse EVERY native transcript it holds (see
+   * `summarizeNativeTranscript`, whose result is intentionally never cached),
+   * which is what made a per-seat boot listing cost tens of seconds (#1338).
+   */
+  async list(agentTypeId, scope, claim, options) {
     const resolved = await this.resolveStore(agentTypeId, scope, claim);
     if (!resolved) return [];
-    return await resolved.store.list({ workspaceId: claim.workspaceScopeId });
+    return await resolved.store.list({ workspaceId: claim.workspaceScopeId }, options);
   }
   async resolveSessionRuntime(agentTypeId, scope, claim, sessionId) {
     const resolved = await this.resolveStore(agentTypeId, scope, claim);
@@ -7985,7 +8037,7 @@ async function buildAgentComposition(input) {
     sessionNamespace: configuredNamespace,
     sessionDir: runtimeScope.sessionDir ?? factoryInput.sessionDir
   }) : async (factoryInput) => {
-    const { createPiCodingAgentHarness } = await import("./createHarness-POZ4AXCZ.js");
+    const { createPiCodingAgentHarness } = await import("./createHarness-GMBZZPTN.js");
     return createPiCodingAgentHarness({
       ...factoryInput,
       pi,
@@ -8059,7 +8111,7 @@ var AgentSessionEventQueue = class {
         const event = this.pending.shift();
         if (event) return { done: false, value: event };
         if (this.ended) return { done: true, value: void 0 };
-        return await new Promise((resolve9) => this.waiters.push(resolve9));
+        return await new Promise((resolve10) => this.waiters.push(resolve10));
       },
       return: async () => {
         this.close();
@@ -8248,20 +8300,27 @@ var EmbeddedAgentGateway = class {
     if (input.agentTypeId && !this.runtime.compiledById.has(input.agentTypeId)) {
       throw new AgentGatewayError(AgentGatewayErrorCode.AGENT_TYPE_UNKNOWN, "agent type is not available");
     }
-    const cursor = input.cursor ? this.decodeCursor(input.cursor, claim.workspaceScopeId, input.agentTypeId, normalizedLimit) : void 0;
+    const cursor = input.cursor ? this.decodeCursor(input.cursor, claim.workspaceScopeId, input.agentTypeId, normalizedLimit) : { depth: 0, after: void 0 };
     const agents = input.agentTypeId ? [input.agentTypeId] : [...this.runtime.compiledById.keys()];
+    const perAgentLimit = cursor.depth + normalizedLimit + 1;
     const rows = [];
     for (const agentTypeId of agents) {
-      const listed = await this.runtime.listSessionSummaries(agentTypeId, input.scope, claim);
+      const listed = await this.runtime.listSessionSummaries(agentTypeId, input.scope, claim, { limit: perAgentLimit });
       for (const item of listed) {
         const ref = { agentTypeId, sessionId: item.id };
         rows.push(summaryFromLegacy(ref, item, this.runtime.activity.get(claim.workspaceScopeId, ref)));
       }
     }
     rows.sort(compareSessions);
-    const eligible = cursor ? rows.filter((row) => isAfterCursor(row, cursor)) : rows;
+    const eligible = cursor.after ? rows.filter((row) => isAfterCursor(row, cursor.after)) : rows;
     const sessions = eligible.slice(0, normalizedLimit);
-    const nextCursor = eligible.length > sessions.length && sessions.length > 0 ? this.encodeCursor(claim.workspaceScopeId, input.agentTypeId, normalizedLimit, sessions.at(-1)) : void 0;
+    const nextCursor = eligible.length > sessions.length && sessions.length > 0 ? this.encodeCursor(
+      claim.workspaceScopeId,
+      input.agentTypeId,
+      normalizedLimit,
+      cursor.depth + sessions.length,
+      sessions.at(-1)
+    ) : void 0;
     return { sessions, ...nextCursor ? { nextCursor } : {} };
   }
   async createSession(input) {
@@ -8804,8 +8863,8 @@ var EmbeddedAgentGateway = class {
     const key = agentSessionKey(workspaceScopeId, ref);
     const previous = this.writerTails.get(key) ?? Promise.resolve();
     let release;
-    const current = new Promise((resolve9) => {
-      release = resolve9;
+    const current = new Promise((resolve10) => {
+      release = resolve10;
     });
     const tail = previous.then(() => current);
     this.writerTails.set(key, tail);
@@ -8817,11 +8876,12 @@ var EmbeddedAgentGateway = class {
       if (this.writerTails.get(key) === tail) this.writerTails.delete(key);
     }
   }
-  encodeCursor(workspaceScopeId, agentTypeId, limit, last) {
+  encodeCursor(workspaceScopeId, agentTypeId, limit, depth, last) {
     const payload = JSON.stringify({
       workspaceScopeId,
       agentTypeId: agentTypeId ?? null,
       limit,
+      depth,
       updatedAt: last.updatedAt,
       lastAgentTypeId: last.ref.agentTypeId,
       sessionId: last.ref.sessionId
@@ -8837,11 +8897,14 @@ var EmbeddedAgentGateway = class {
       const expected = createHash6("sha256").update(`${this.cursorSecret}:${encoded}`).digest("base64url");
       if (signature !== expected) throw new Error("signature");
       const decoded = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
-      if (decoded.workspaceScopeId !== workspaceScopeId || decoded.agentTypeId !== (agentTypeId ?? null) || decoded.limit !== limit || typeof decoded.updatedAt !== "number" || typeof decoded.lastAgentTypeId !== "string" || typeof decoded.sessionId !== "string") throw new Error("binding");
+      if (decoded.workspaceScopeId !== workspaceScopeId || decoded.agentTypeId !== (agentTypeId ?? null) || decoded.limit !== limit || typeof decoded.depth !== "number" || !Number.isInteger(decoded.depth) || decoded.depth < 0 || typeof decoded.updatedAt !== "number" || typeof decoded.lastAgentTypeId !== "string" || typeof decoded.sessionId !== "string") throw new Error("binding");
       return {
-        updatedAt: decoded.updatedAt,
-        agentTypeId: decoded.lastAgentTypeId,
-        sessionId: decoded.sessionId
+        depth: decoded.depth,
+        after: {
+          updatedAt: decoded.updatedAt,
+          agentTypeId: decoded.lastAgentTypeId,
+          sessionId: decoded.sessionId
+        }
       };
     } catch {
       throw new AgentGatewayError(AgentGatewayErrorCode.AGENT_SESSION_CURSOR_INVALID, "session cursor is invalid");
@@ -8863,7 +8926,7 @@ function closedError() {
   return new AgentGatewayError(AgentGatewayErrorCode.AGENT_GATEWAY_CLOSED, "agent host is closing");
 }
 function delay2(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 var EnvironmentLeaseManager = class {
   constructor(adapter) {
@@ -9295,7 +9358,7 @@ function sessionChangesRoutes(app, opts, done) {
 }
 
 // src/server/http/routes/skills.ts
-import { dirname as dirname6, isAbsolute as isAbsolute6, relative as relative7, resolve as resolve6, sep as sep6 } from "node:path";
+import { dirname as dirname6, isAbsolute as isAbsolute6, relative as relative7, resolve as resolve7, sep as sep6 } from "node:path";
 import {
   DefaultPackageManager,
   getAgentDir,
@@ -9304,12 +9367,12 @@ import {
 var CACHE_TTL_MS = 3e4;
 function provisionedWorkspaceRoots(additionalSkillPaths) {
   const userSkillsSuffix = `${sep6}.agents${sep6}skills`;
-  return additionalSkillPaths.map((skillPath) => resolve6(skillPath)).filter((skillPath) => skillPath.endsWith(userSkillsSuffix)).map((skillPath) => dirname6(dirname6(skillPath)));
+  return additionalSkillPaths.map((skillPath) => resolve7(skillPath)).filter((skillPath) => skillPath.endsWith(userSkillsSuffix)).map((skillPath) => dirname6(dirname6(skillPath)));
 }
 function pathForWorkspaceEditor(workspace, filePath, additionalSkillPaths = []) {
   const roots = [workspace.root, ...provisionedWorkspaceRoots(additionalSkillPaths)];
   for (const root of roots) {
-    const pathWithinWorkspace = relative7(resolve6(root), resolve6(filePath));
+    const pathWithinWorkspace = relative7(resolve7(root), resolve7(filePath));
     if (pathWithinWorkspace === "" || pathWithinWorkspace === ".." || pathWithinWorkspace.startsWith(`..${sep6}`) || isAbsolute6(pathWithinWorkspace)) {
       continue;
     }
@@ -9535,7 +9598,7 @@ function createAgentHostRuntimeCapabilityProjection(input) {
     );
     return { scope, claim, resolved };
   };
-  const resolve9 = async (request, agentTypeId, sessionId) => {
+  const resolve10 = async (request, agentTypeId, sessionId) => {
     if (sessionId) {
       const { scope: scope2 } = await authorize(request);
       const pinned = await gateway.resolveHostSessionBinding(scope2, { agentTypeId, sessionId });
@@ -9557,7 +9620,7 @@ function createAgentHostRuntimeCapabilityProjection(input) {
       }
     },
     async resolveBinding({ request, agentTypeId, sessionId }) {
-      const { claim, binding } = await resolve9(request, agentTypeId, sessionId);
+      const { claim, binding } = await resolve10(request, agentTypeId, sessionId);
       const skillResourceSnapshotPromise = binding.scope.getSkillResourceSnapshot?.({
         scope: claim,
         sessionId,
@@ -9621,7 +9684,7 @@ function createAgentHostRuntimeCapabilityProjection(input) {
       };
     },
     async describeAgent({ request, agentTypeId }) {
-      const { claim } = await authorizeAgentAccess(request, agentTypeId);
+      const { claim, resolved } = await authorizeAgentAccess(request, agentTypeId);
       const spec = runtime.compiledById.get(agentTypeId);
       if (!spec) {
         throw new AgentGatewayError(AgentGatewayErrorCode.AGENT_TYPE_UNKNOWN, "agent type is not available");
@@ -9632,28 +9695,39 @@ function createAgentHostRuntimeCapabilityProjection(input) {
         const refs = mcpGrants.getMcpServerRefs(agentTypeId) ?? [];
         if (refs.length > 0) {
           const listed = await mcpGrants.store.listGrants(claim.workspaceScopeId);
-          const resolved = resolveAgentMcpGrants({
+          const resolved2 = resolveAgentMcpGrants({
             workspaceId: claim.workspaceScopeId,
             agentTypeId,
             mcpServerRefs: refs,
             grants: listed.grants,
             catalog: mcpGrants.catalog
           });
-          mcpServers = resolved.connectors.map((connector) => ({
+          mcpServers = resolved2.connectors.map((connector) => ({
             id: connector.connectorId,
             tools: connector.allowedTools
           }));
         }
       }
+      const { refs: instructionFiles, withheld } = legacy ? { refs: [], withheld: [] } : await resolveAgentInstructionFileRefs({
+        sources: spec.instructionSources,
+        workspaceRoot: resolved.environment.workspaceRoot
+      });
+      for (const entry of withheld) {
+        request.log?.warn?.({
+          agentTypeId,
+          code: entry.code,
+          workspaceScopeId: claim.workspaceScopeId
+        }, `${entry.message}; its persona instructions are not linkable here`);
+      }
       return {
         agentTypeId,
         model: legacy ? null : spec.model?.preferred ?? null,
-        instructionFiles: legacy ? [] : spec.instructionFiles ?? [],
+        instructionFiles,
         mcpServers
       };
     },
     async executeCommand({ request, agentTypeId, requestId, sessionId, name, args }) {
-      const { scope, binding } = await resolve9(request, agentTypeId, sessionId);
+      const { scope, binding } = await resolve10(request, agentTypeId, sessionId);
       if (!binding.composition.harness.executeSlashCommand) {
         throw new AgentGatewayError(
           AgentGatewayErrorCode.AGENT_COMMAND_INVALID_STATE,
@@ -9854,7 +9928,7 @@ function createAgentHostRuntimeCapabilityRoutes(projection) {
   return async (app) => {
     app.setErrorHandler((error, _request, reply) => sendError(reply, error));
     const cache = /* @__PURE__ */ new WeakMap();
-    const resolve9 = (request, agentTypeId, sessionId) => {
+    const resolve10 = (request, agentTypeId, sessionId) => {
       let entries = cache.get(request);
       if (!entries) {
         entries = /* @__PURE__ */ new Map();
@@ -9873,40 +9947,40 @@ function createAgentHostRuntimeCapabilityRoutes(projection) {
       path: "/api/v1/agents/:agentTypeId/models",
       filterModels: projection.filterModels,
       authorizeRequest: async (request) => {
-        await resolve9(request, agentId(request));
+        await resolve10(request, agentId(request));
       }
     });
     await app.register(skillsRoutes, {
       path: "/api/v1/agents/:agentTypeId/skills",
       authorizeRequest: async (request) => {
-        await resolve9(request, agentId(request));
+        await resolve10(request, agentId(request));
       },
-      getWorkspace: async (request) => (await resolve9(request, agentId(request))).workspace,
+      getWorkspace: async (request) => (await resolve10(request, agentId(request))).workspace,
       getAdditionalSkillPaths: async (request) => [
-        ...(await resolve9(request, agentId(request))).additionalSkillPaths ?? [],
-        ...(await resolve9(request, agentId(request))).pi?.additionalSkillPaths ?? []
+        ...(await resolve10(request, agentId(request))).additionalSkillPaths ?? [],
+        ...(await resolve10(request, agentId(request))).pi?.additionalSkillPaths ?? []
       ],
-      getPiPackages: async (request) => (await resolve9(request, agentId(request))).pi?.packages,
-      getNoSkills: async (request) => (await resolve9(request, agentId(request))).pi?.noSkills,
-      getSkillResourceSnapshot: async (request) => (await resolve9(request, agentId(request))).skillResourceSnapshot
+      getPiPackages: async (request) => (await resolve10(request, agentId(request))).pi?.packages,
+      getNoSkills: async (request) => (await resolve10(request, agentId(request))).pi?.noSkills,
+      getSkillResourceSnapshot: async (request) => (await resolve10(request, agentId(request))).skillResourceSnapshot
     });
     await app.register(catalogRoutes, {
       path: "/api/v1/agents/:agentTypeId/tools",
       authorizeRequest: async (request) => {
-        await resolve9(request, agentId(request));
+        await resolve10(request, agentId(request));
       },
-      getTools: async (request) => [...(await resolve9(request, agentId(request))).tools]
+      getTools: async (request) => [...(await resolve10(request, agentId(request))).tools]
     });
     await app.register(systemPromptRoutes, {
       path: "/api/v1/agents/:agentTypeId/sessions/:sessionId/system-prompt",
       sessionIdParam: "sessionId",
       authorizeRequest: async (request) => {
         const value = request.params;
-        await resolve9(request, value.agentTypeId, value.sessionId);
+        await resolve10(request, value.agentTypeId, value.sessionId);
       },
       getHarness: async (request) => {
         const value = request.params;
-        return (await resolve9(request, value.agentTypeId, value.sessionId)).harness;
+        return (await resolve10(request, value.agentTypeId, value.sessionId)).harness;
       }
     });
     await app.register(sessionChangesRoutes, {
@@ -9915,11 +9989,11 @@ function createAgentHostRuntimeCapabilityRoutes(projection) {
       tracker: projection.sessionChangesTracker,
       authorizeRequest: async (request) => {
         const value = request.params;
-        await resolve9(request, value.agentTypeId, value.sessionId);
+        await resolve10(request, value.agentTypeId, value.sessionId);
       },
       resolveScope: async (request, sessionId) => {
         const value = request.params;
-        const binding = await resolve9(request, value.agentTypeId, sessionId);
+        const binding = await resolve10(request, value.agentTypeId, sessionId);
         return {
           workspaceScopeId: binding.runContext.workspaceId,
           agentTypeId: value.agentTypeId,
@@ -9930,9 +10004,9 @@ function createAgentHostRuntimeCapabilityRoutes(projection) {
     await app.register(readyStatusRoutes, {
       path: "/api/v1/agents/:agentTypeId/ready-status",
       authorizeRequest: async (request) => {
-        await resolve9(request, agentId(request));
+        await resolve10(request, agentId(request));
       },
-      getTracker: async (request) => (await resolve9(request, agentId(request))).readyTracker,
+      getTracker: async (request) => (await resolve10(request, agentId(request))).readyTracker,
       registerStreamClose: projection.registerSubscription
     });
     app.get("/api/v1/agents/:agentTypeId/describe", async (request, reply) => {
@@ -9953,7 +10027,7 @@ function createAgentHostRuntimeCapabilityRoutes(projection) {
       try {
         const query = request.query;
         const sessionId = typeof query.sessionId === "string" && query.sessionId.trim() ? query.sessionId.trim() : "default";
-        const binding = await resolve9(
+        const binding = await resolve10(
           request,
           value.agentTypeId,
           typeof query.sessionId === "string" && query.sessionId.trim() ? sessionId : void 0
@@ -11027,12 +11101,12 @@ async function runWithWorkspaceAgentLease(input) {
   const operations = /* @__PURE__ */ new Set();
   const cleanups = /* @__PURE__ */ new Set();
   let signalDrain;
-  const drainRequested = new Promise((resolve9) => {
-    signalDrain = resolve9;
+  const drainRequested = new Promise((resolve10) => {
+    signalDrain = resolve10;
   });
   let signalRevocation;
-  const revocation = new Promise((resolve9) => {
-    signalRevocation = resolve9;
+  const revocation = new Promise((resolve10) => {
+    signalRevocation = resolve10;
   });
   let drainDeadline;
   const registerCleanup = (cleanup) => {
@@ -11087,8 +11161,8 @@ async function runWithWorkspaceAgentLease(input) {
         const remainingMs = Math.max(0, drainDeadline - Date.now());
         const outcome = await Promise.race([
           Promise.allSettled(pending).then((results) => ({ kind: "settled", results })),
-          new Promise((resolve9) => {
-            setTimeout(() => resolve9({ kind: "expired" }), remainingMs);
+          new Promise((resolve10) => {
+            setTimeout(() => resolve10({ kind: "expired" }), remainingMs);
           })
         ]);
         if (outcome.kind === "expired") break;
@@ -11370,9 +11444,9 @@ function createRuntime(options, compiledAgents) {
     },
     activity,
     shutdownGraceMs: graceMs,
-    listSessionSummaries(agentTypeId, scope, claim) {
+    listSessionSummaries(agentTypeId, scope, claim, options2) {
       runtime.assertOpen();
-      return inventory.list(agentTypeId, scope, claim);
+      return inventory.list(agentTypeId, scope, claim, options2);
     },
     isDraining: () => draining,
     assertOpen() {
@@ -11550,8 +11624,8 @@ function createRuntime(options, compiledAgents) {
         if (work.length === 0) return;
         const completed = await Promise.race([
           Promise.allSettled(work).then((results) => ({ completed: true, results })),
-          new Promise((resolve9) => {
-            setTimeout(() => resolve9({ completed: false }), graceMs);
+          new Promise((resolve10) => {
+            setTimeout(() => resolve10({ completed: false }), graceMs);
           })
         ]);
         if (completed.completed) {
@@ -11594,8 +11668,8 @@ function createRuntime(options, compiledAgents) {
       runtime.assertOpen();
       let resolveEffect;
       let rejectEffect;
-      const effect = new Promise((resolve9, reject) => {
-        resolveEffect = resolve9;
+      const effect = new Promise((resolve10, reject) => {
+        resolveEffect = resolve10;
         rejectEffect = reject;
       });
       finiteEffects.set(effect, key);
@@ -11611,8 +11685,8 @@ function createRuntime(options, compiledAgents) {
     async runBindingOperation(bindingKey, operation) {
       const previous = bindingOperationTails.get(bindingKey) ?? Promise.resolve();
       let release;
-      const current = new Promise((resolve9) => {
-        release = resolve9;
+      const current = new Promise((resolve10) => {
+        release = resolve10;
       });
       const tail = previous.then(() => current);
       bindingOperationTails.set(bindingKey, tail);
@@ -11643,7 +11717,7 @@ function createRuntime(options, compiledAgents) {
         ));
         const bindingCleanupResult = await Promise.race([
           bindingCleanup.then((results) => ({ completed: true, results })),
-          new Promise((resolve9) => setTimeout(() => resolve9({ completed: false }), graceMs))
+          new Promise((resolve10) => setTimeout(() => resolve10({ completed: false }), graceMs))
         ]);
         if (bindingCleanupResult.completed) {
           const failed = bindingCleanupResult.results.find(
@@ -11659,7 +11733,7 @@ function createRuntime(options, compiledAgents) {
         try {
           await Promise.race([
             options.runtimeModeAdapter.dispose?.() ?? Promise.resolve(),
-            new Promise((resolve9) => setTimeout(resolve9, graceMs))
+            new Promise((resolve10) => setTimeout(resolve10, graceMs))
           ]);
         } catch (error) {
           firstError ??= error;
@@ -11924,7 +11998,7 @@ async function registerAgentHostEnvironmentRoutes(app, options) {
 
 // src/server/harness/pi-coding-agent/pluginLoader.ts
 import { readdir as readdir4, stat as stat6, readFile as readFile5 } from "node:fs/promises";
-import { join as join8, extname, resolve as resolve7, sep as sep7, relative as relative8 } from "node:path";
+import { join as join8, extname, resolve as resolve8, sep as sep7, relative as relative8 } from "node:path";
 import { homedir } from "node:os";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 var VALID_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".mjs"]);
@@ -11994,8 +12068,8 @@ async function loadNpmPlugin(pkgDir, importFn) {
   if (!await fileExists(pkgJsonPath)) return [];
   const pkgJson = JSON.parse(await readFile5(pkgJsonPath, "utf-8"));
   const main = pkgJson.main ?? "index.js";
-  const resolvedMain = resolve7(pkgDir, main);
-  const resolvedPkgDir = resolve7(pkgDir);
+  const resolvedMain = resolve8(pkgDir, main);
+  const resolvedPkgDir = resolve8(pkgDir);
   if (resolvedMain !== resolvedPkgDir && !resolvedMain.startsWith(resolvedPkgDir + sep7)) {
     return [];
   }
@@ -12134,9 +12208,9 @@ function withRuntimeEnvContributions(runtimeBundle, baseContext, contributions,
 // src/server/piResourceDigest.ts
 import { createHash as createHash7 } from "node:crypto";
 import { constants as constants3 } from "node:fs";
-import { lstat as lstat4, open as open2, opendir, realpath as realpath5, stat as statPath } from "node:fs/promises";
+import { lstat as lstat4, open as open2, opendir, realpath as realpath6, stat as statPath } from "node:fs/promises";
 import { homedir as homedir2 } from "node:os";
-import { dirname as dirname8, isAbsolute as isAbsolute7, join as join9, parse, relative as relative9, resolve as resolve8, sep as sep8 } from "node:path";
+import { dirname as dirname8, isAbsolute as isAbsolute7, join as join9, parse, relative as relative9, resolve as resolve9, sep as sep8 } from "node:path";
 import { fileURLToPath as fileURLToPath7 } from "node:url";
 import { DefaultPackageManager as DefaultPackageManager2, getAgentDir as getAgentDir2, loadProjectContextFiles } from "@mariozechner/pi-coding-agent";
 var DEFAULT_PI_RESOURCE_DIGEST_LIMITS = Object.freeze({
@@ -12334,11 +12408,11 @@ function resolvePiPath(input, baseDir) {
   let normalized = input.trim();
   if (normalized === "~") normalized = homedir2();
   else if (normalized.startsWith("~/") || process.platform === "win32" && normalized.startsWith("~\\")) {
-    normalized = resolve8(homedir2(), normalized.slice(2));
+    normalized = resolve9(homedir2(), normalized.slice(2));
   } else if (/^file:\/\//.test(normalized)) {
     normalized = fileURLToPath7(normalized);
   }
-  return isAbsolute7(normalized) ? resolve8(normalized) : resolve8(baseDir, normalized);
+  return isAbsolute7(normalized) ? resolve9(normalized) : resolve9(baseDir, normalized);
 }
 async function findContainingArtifactRoot(path, authorizedRoots) {
   let current = dirname8(path);
@@ -12346,7 +12420,7 @@ async function findContainingArtifactRoot(path, authorizedRoots) {
   if (!boundary) throw stableError(ErrorCode.enum.PATH_ESCAPE, 403, `Pi resource path is outside authorized roots: ${path}`);
   while (isContained(current, boundary)) {
     try {
-      const packageStat = await lstat4(resolve8(current, "package.json"));
+      const packageStat = await lstat4(resolve9(current, "package.json"));
       if (packageStat.isSymbolicLink()) {
         throw stableError(ErrorCode.enum.PATH_SYMLINK_ESCAPE, 403, `Pi resource package manifest cannot be a symlink: ${current}`);
       }
@@ -12360,7 +12434,7 @@ async function findContainingArtifactRoot(path, authorizedRoots) {
   return dirname8(path);
 }
 async function hashLocalResource(state, path, logicalPath, depth) {
-  const absolutePath = resolve8(path);
+  const absolutePath = resolve9(path);
   await assertContainedWithoutSymlinks(absolutePath, state.authorizedRoots);
   if (depth > state.limits.maxDepth) {
     throw limitError(`Pi resource tree exceeds maximum depth ${state.limits.maxDepth}`);
@@ -12384,7 +12458,7 @@ async function hashLocalResource(state, path, logicalPath, depth) {
   }
   if (stat7.isDirectory()) {
     frameString(state.hash, "directory", logicalPath);
-    const openedTarget = await realpath5(absolutePath);
+    const openedTarget = await realpath6(absolutePath);
     if (!mostSpecificContainingRoot(openedTarget, state.authorizedRoots)) {
       throw stableError(ErrorCode.enum.PATH_SYMLINK_ESCAPE, 403, `Pi resource resolves outside authorized roots: ${absolutePath}`);
     }
@@ -12403,12 +12477,12 @@ async function hashLocalResource(state, path, logicalPath, depth) {
       frameString(state.hash, "entry-name", entry.name);
       await hashLocalResource(
         state,
-        resolve8(openedTarget, entry.name),
+        resolve9(openedTarget, entry.name),
         logicalPath === "." ? entry.name : `${logicalPath}/${entry.name}`,
         depth + 1
       );
     }
-    const afterTarget = await realpath5(absolutePath);
+    const afterTarget = await realpath6(absolutePath);
     if (afterTarget !== openedTarget) throw changedError(absolutePath);
     assertSameFile(stat7, await statPath(afterTarget), absolutePath);
     return;
@@ -12428,7 +12502,7 @@ async function hashLocalResource(state, path, logicalPath, depth) {
   try {
     const opened = await handle.stat();
     assertSameFile(stat7, opened, absolutePath);
-    const openedTarget = await realpath5(absolutePath);
+    const openedTarget = await realpath6(absolutePath);
     if (!mostSpecificContainingRoot(openedTarget, state.authorizedRoots)) {
       throw stableError(ErrorCode.enum.PATH_SYMLINK_ESCAPE, 403, `Pi resource resolves outside authorized roots: ${absolutePath}`);
     }
@@ -12443,7 +12517,7 @@ async function hashLocalResource(state, path, logicalPath, depth) {
     }
     const after = await handle.stat();
     assertSameFile(opened, after, absolutePath);
-    const afterTarget = await realpath5(absolutePath);
+    const afterTarget = await realpath6(absolutePath);
     if (afterTarget !== openedTarget) throw changedError(absolutePath);
     assertSameFile(after, await statPath(afterTarget), absolutePath);
     state.bytes += offset;
@@ -12459,12 +12533,12 @@ async function assertContainedWithoutSymlinks(path, roots) {
   if (!root) {
     throw stableError(ErrorCode.enum.PATH_ESCAPE, 403, `Pi resource path is outside authorized roots: ${path}`);
   }
-  const absolutePath = resolve8(path);
+  const absolutePath = resolve9(path);
   const pathRoot = parse(absolutePath).root;
   const segments = relative9(pathRoot, absolutePath).split(sep8).filter(Boolean);
   let current = pathRoot;
   for (const segment of segments) {
-    current = resolve8(current, segment);
+    current = resolve9(current, segment);
     try {
       if ((await lstat4(current)).isSymbolicLink()) {
         throw stableError(ErrorCode.enum.PATH_SYMLINK_ESCAPE, 403, `Pi resource symlinks are not allowed: ${current}`);
@@ -12479,7 +12553,7 @@ function mostSpecificContainingRoot(path, roots) {
   return roots.filter((root) => isContained(path, root)).sort((left, right) => right.length - left.length)[0];
 }
 function isContained(path, root) {
-  const value = relative9(resolve8(root), resolve8(path));
+  const value = relative9(resolve9(root), resolve9(path));
   return value === "" || value !== ".." && !value.startsWith(`..${sep8}`) && !isAbsolute7(value);
 }
 function frameString(hash, tag, value) {
@@ -13572,6 +13646,7 @@ export {
   materializeAgentDirectory,
   TrustedAgentCompositionError,
   createConfiguredAgentHostAgentSpec,
+  resolveAgentInstructionFileRefs,
   FleetConfigError,
   loadConfiguredAgentFleet,
   LEGACY_DEFAULT_AGENT_FLEET,