pi-subagents 0.80.0 → 0.81.0

package/bundle/preflight.js

@@ -0,0 +1,425 @@
+import {
+  buildEffectiveSystemPrompt,
+  canPreferForkFromSnapshot,
+  resolveSubagentLaunchContext
+} from "./chunk-ARRKBB2B.js";
+import "./chunk-EYNJ6VL6.js";
+import {
+  loadConfig
+} from "./chunk-WSBNENFS.js";
+import {
+  nestedResultsPath,
+  processTerminalCandidatePath,
+  processTerminalPath,
+  resultFilePath
+} from "./chunk-VJHOELQP.js";
+import {
+  applyIntercomBridgeToAgent,
+  resolveIntercomBridge,
+  validateIntercomBridgeConfig
+} from "./chunk-ZP3HODFH.js";
+import {
+  AGENT_DEFINITION_PROJECTION_VERSION,
+  resolveLaunchBinding,
+  stableJsonDigest
+} from "./chunk-7F6RKT6W.js";
+import {
+  applyThinkingSuffix,
+  resolvePiLaunchToolPlan
+} from "./chunk-G5DKFLLI.js";
+import {
+  assertRequiredChildExtensionsAdmitted,
+  resolveRequiredChildExtensions
+} from "./chunk-CTPAE36Y.js";
+import {
+  getArtifactPaths,
+  getArtifactsDir
+} from "./chunk-3DC5KBVP.js";
+import {
+  assertClaudeCodeModelScope,
+  assertThinkingWithinCeiling,
+  discoverAgentSnapshot,
+  findBlockingAgentDiagnostic,
+  formatUnknownAgentError,
+  inheritsParentModel,
+  intersectThinkingCeilings,
+  isClaudeCodeAdapterId,
+  normalizeExtensionBindings,
+  normalizeSingleOutputOverride,
+  normalizeSkillInput,
+  projectScopeRequiresTrustMessage,
+  resolveAgentName,
+  resolveClaudeCodeOverride,
+  resolveEffectiveSubagentModel,
+  resolveEffectiveThinking,
+  resolveExecutionAgentScope,
+  resolveModelOrigin,
+  resolveModelScopesForAgent,
+  resolveModelSelection,
+  resolvePermissionRules,
+  resolveSingleOutputPath,
+  resolveSkillsWithFallback,
+  resolveStepBehavior,
+  unknownAgentDiagnosticContext
+} from "./chunk-ZBC44JJ3.js";
+import {
+  DIRS,
+  SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
+  TEMP_ROOT_DIR
+} from "./chunk-5LFLVSTM.js";
+import "./chunk-YFCK7H2S.js";
+import {
+  capabilityCeilingAgentRestrictionMessage,
+  intersectSubagentCapabilityCeilings
+} from "./chunk-Z7KVHQHL.js";
+
+// src/api/preflight.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+var SUBAGENT_LAUNCH_CONTRACT_VERSION = 3;
+var PREFLIGHT_ORCHESTRATOR_TARGET = "preflight";
+function claudeCodeFailureCode(message) {
+  if (message.includes("subagent model scope")) return "model_scope";
+  if (message.startsWith("Thinking level '")) return "thinking_ceiling";
+  return "unsupported_mode";
+}
+function packageVersion() {
+  const packagePath = path.resolve(path.dirname(fileURLToPath(new URL("../src/api/preflight.js", import.meta.url).href)), "..", "..", "package.json");
+  const parsed = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+  if (typeof parsed.version !== "string" || !parsed.version.trim()) {
+    throw new Error(`Invalid package version in '${packagePath}'.`);
+  }
+  return parsed.version;
+}
+function digestContract(contract) {
+  return stableJsonDigest(contract);
+}
+function normalizeAvailableModels(models) {
+  return (models ?? []).map((model) => ({ ...model, fullId: model.fullId ?? `${model.provider}/${model.id}` }));
+}
+function resolveLaunchContractContext(input, agent) {
+  return resolveSubagentLaunchContext({
+    explicitContext: input.context,
+    agentDefaultContext: agent.defaultContext,
+    defaultSubagentContext: loadConfig().defaultSubagentContext,
+    canUseImplicitFork: canPreferForkFromSnapshot({
+      parentSessionFile: input.parentSessionFile,
+      leafId: input.parentLeafId
+    })
+  });
+}
+function taskWorkspaceScopeAuthorityDiagnostic(task) {
+  if (!task) return void 0;
+  const text = task.replace(/\s+/g, " ").trim();
+  if (!text) return void 0;
+  const createsWorkspacePackage = /\b(?:add|create|introduce|make|set up)\b.{0,80}\b(?:new\s+)?(?:workspace\s+)?package\b/i.test(text) || /\b(?:new\s+)?package\b.{0,80}\b(?:workspace|monorepo)\b/i.test(text);
+  if (!createsWorkspacePackage) return void 0;
+  const packageOnlyAuthority = /\b(?:only|solely)\b.{0,40}\b(?:edit|change|modify|touch|write(?:\s+to)?)\b.{0,80}\b(?:package(?:\s+directory)?|packages\/[\w.-]+)\b/i.test(text) || /\b(?:do not|don't|must not)\b.{0,40}\b(?:edit|change|modify|touch|write(?:\s+to)?)\b.{0,80}\b(?:root|workspace|lockfile|metadata)\b/i.test(text) || /\bwithout\b.{0,40}\b(?:root|workspace|lockfile|metadata)\b.{0,40}\b(?:edit|change|modification|write)s?\b/i.test(text);
+  if (!packageOnlyAuthority) return void 0;
+  return {
+    code: "workspace_scope_authority",
+    severity: "warning",
+    message: "Task asks for a workspace package change while limiting authority to package-scope edits. New workspace packages often need root workspace metadata or lockfile changes, so confirm that authority before launch."
+  };
+}
+function candidateList(inputAgent, selected, all) {
+  return [...all.builtin, ...all.package, ...all.user, ...all.project].filter((agent) => Boolean(resolveAgentName(inputAgent, [agent]).agent)).map((agent) => ({
+    name: agent.name,
+    ...agent.localName ? { localName: agent.localName } : {},
+    ...agent.packageName ? { packageName: agent.packageName } : {},
+    source: agent.source,
+    filePath: agent.filePath,
+    ...agent.disabled === true ? { disabled: true } : {},
+    selected: Boolean(selected && agent.filePath === selected.filePath && agent.name === selected.name)
+  }));
+}
+async function resolveSubagentLaunchContract(input) {
+  const diagnostics = [];
+  const authorityDiagnostic = taskWorkspaceScopeAuthorityDiagnostic(input.task);
+  if (authorityDiagnostic) diagnostics.push(authorityDiagnostic);
+  const effectiveCwd = path.resolve(input.cwd);
+  try {
+    if (!fs.statSync(effectiveCwd).isDirectory()) {
+      return { ok: false, code: "invalid_cwd", message: `cwd '${effectiveCwd}' is not a directory.`, diagnostics };
+    }
+  } catch (error) {
+    const detail = error instanceof Error ? ` ${error.message}` : "";
+    return { ok: false, code: "invalid_cwd", message: `cwd '${effectiveCwd}' is not a directory.${detail}`, diagnostics };
+  }
+  if (input.context !== void 0 && input.context !== "fresh" && input.context !== "fork") {
+    return { ok: false, code: "unsupported_mode", message: `Unsupported context '${String(input.context)}'; expected 'fresh' or 'fork'.`, diagnostics };
+  }
+  if (input.artifactDir !== void 0 && input.artifactDir !== "project" && input.artifactDir !== "session" && input.artifactDir !== "temp") {
+    return { ok: false, code: "invalid_artifact_dir", message: `Unsupported artifactDir '${String(input.artifactDir)}'; expected 'project', 'session', or 'temp'.`, diagnostics };
+  }
+  const bridgeOverride = input.intercomBridge === void 0 ? void 0 : validateIntercomBridgeConfig({ value: input.intercomBridge, label: "intercomBridge" });
+  if (bridgeOverride && !bridgeOverride.ok) {
+    return { ok: false, code: "invalid_intercom_bridge", message: bridgeOverride.error, diagnostics };
+  }
+  if (input.orchestratorTarget !== void 0 && (typeof input.orchestratorTarget !== "string" || !input.orchestratorTarget.trim())) {
+    return { ok: false, code: "invalid_intercom_bridge", message: "orchestratorTarget must be a non-empty string when provided.", diagnostics };
+  }
+  const scope = resolveExecutionAgentScope(input.agentScope);
+  if (input.projectTrusted === false && scope === "project") {
+    const message = projectScopeRequiresTrustMessage(effectiveCwd);
+    return { ok: false, code: "restricted_agent", message, diagnostics: [...diagnostics, { code: "restricted_agent", severity: "error", message }] };
+  }
+  const parentProvider = input.preferredProvider ?? input.parentModel?.provider;
+  const discovery = discoverAgentSnapshot(effectiveCwd, scope, parentProvider, { includeChains: false, projectTrusted: input.projectTrusted });
+  const discovered = discovery.effective;
+  const resolvedAgent = resolveAgentName(input.agent, discovered.agents);
+  const ambiguousCandidates = resolvedAgent.error ? discovered.agents.filter((agent2) => resolveAgentName(input.agent, [agent2]).agent) : resolvedAgent.agent;
+  const invalidAgent = findBlockingAgentDiagnostic(input.agent, ambiguousCandidates, discovered.agentDiagnostics);
+  if (invalidAgent) {
+    const message = `Agent '${input.agent}' has invalid configuration: ${invalidAgent.error}`;
+    return { ok: false, code: "missing_agent", message, diagnostics: [{ code: "missing_agent", severity: "error", message }] };
+  }
+  if (resolvedAgent.error) {
+    return { ok: false, code: "ambiguous_agent", message: resolvedAgent.error, diagnostics };
+  }
+  if (!resolvedAgent.agent) {
+    return { ok: false, code: "missing_agent", message: formatUnknownAgentError(input.agent, unknownAgentDiagnosticContext(discovered)), diagnostics };
+  }
+  const definitionAgent = resolvedAgent.agent;
+  let extensionBindings;
+  try {
+    extensionBindings = normalizeExtensionBindings(input.extensionBindings)?.value;
+  } catch (error) {
+    return { ok: false, code: "invalid_extension_bindings", message: error instanceof Error ? error.message : String(error), diagnostics };
+  }
+  if (extensionBindings !== void 0 && (definitionAgent.runner?.type === "external-cli" || definitionAgent.runner?.type === "external-job")) {
+    return { ok: false, code: "unsupported_mode", message: `extensionBindings is not supported for runner.type='${definitionAgent.runner.type}'.`, diagnostics };
+  }
+  const context = resolveLaunchContractContext(input, definitionAgent);
+  if (context === "fork") {
+    diagnostics.push({ code: "host_required", severity: "host-required", message: "Exact fork session branching requires Pi host session snapshots." });
+  }
+  const bridge = resolveIntercomBridge({
+    config: loadConfig().intercomBridge,
+    ...bridgeOverride ? { override: bridgeOverride.value } : {},
+    context,
+    orchestratorTarget: input.orchestratorTarget ?? PREFLIGHT_ORCHESTRATOR_TARGET
+  });
+  if (bridge.active && bridge.interpolatesOrchestratorTarget && input.orchestratorTarget === void 0) {
+    diagnostics.push({ code: "host_required", severity: "host-required", message: "The intercomBridge instruction file names the supervisor session; supply orchestratorTarget to bind the exact child prompt." });
+  }
+  const agent = applyIntercomBridgeToAgent(definitionAgent, bridge);
+  const effectiveCapabilityCeiling = intersectSubagentCapabilityCeilings(input.capabilityCeiling, input.inheritedCapabilityCeiling);
+  const restrictionMessage = capabilityCeilingAgentRestrictionMessage(agent.name, effectiveCapabilityCeiling);
+  if (restrictionMessage) return { ok: false, code: "restricted_agent", message: restrictionMessage, diagnostics };
+  const runId = input.runId ?? "preflight";
+  const skillInput = normalizeSkillInput(input.skill);
+  const outputOverride = normalizeSingleOutputOverride(input.output, agent.output);
+  const behavior = resolveStepBehavior(agent, {
+    ...outputOverride !== void 0 ? { output: outputOverride } : {},
+    ...input.outputMode !== void 0 ? { outputMode: input.outputMode } : {},
+    ...skillInput !== void 0 ? { skills: skillInput } : {},
+    ...input.model !== void 0 ? { model: input.model } : {},
+    ...input.outputSchema !== void 0 ? { outputSchema: input.outputSchema } : {}
+  });
+  const requestedSkills = behavior.skills === false ? [] : behavior.skills;
+  const resolvedSkills = resolveSkillsWithFallback(
+    requestedSkills,
+    effectiveCwd,
+    effectiveCwd,
+    agent.skillPath,
+    agent.filePath ? path.dirname(agent.filePath) : effectiveCwd
+  );
+  if (resolvedSkills.missing.includes("pi-subagents")) {
+    return { ok: false, code: "missing_skill", message: "The pi-subagents orchestration skill is not child-injectable.", diagnostics };
+  }
+  if (resolvedSkills.missing.length > 0) diagnostics.push({ code: "missing_skill", severity: "error", message: `Missing skills: ${resolvedSkills.missing.join(", ")}` });
+  const externalRunner = agent.runner?.type === "external-cli" || agent.runner?.type === "external-job";
+  try {
+    assertRequiredChildExtensionsAdmitted([resolveRequiredChildExtensions(input.parentSessionId)], { agent: agent.name, runnerType: agent.runner?.type });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, code: "unsupported_mode", message, diagnostics };
+  }
+  if (externalRunner && behavior.outputSchema) {
+    return { ok: false, code: "unsupported_mode", message: `Agent '${agent.name}' uses runner.type='${agent.runner?.type}' and does not support: structured output.`, diagnostics };
+  }
+  const availableModels = normalizeAvailableModels(input.availableModels);
+  const preferredProvider = agent.modelProvider ?? input.preferredProvider ?? input.parentModel?.provider;
+  const modelScopes = resolveModelScopesForAgent(discovered.modelScope, agent.name, input.parentModel, input.scopedModelIds);
+  const modelOrigin = resolveModelOrigin({ explicitModel: input.model, agentModel: agent.model, parentModel: input.parentModel });
+  const primaryModel = externalRunner ? void 0 : resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, {
+    scope: modelScopes,
+    source: modelOrigin === "explicit" ? "explicit" : "inherited"
+  });
+  const effectiveThinkingConfig = input.thinking !== void 0 ? input.thinking : agent.thinking;
+  const thinkingCeiling = externalRunner ? void 0 : intersectThinkingCeilings(
+    discovered.maxThinking,
+    input.thinkingCeiling,
+    input.inheritedThinkingCeiling
+  );
+  const model = externalRunner ? void 0 : applyThinkingSuffix(resolveModelSelection(primaryModel, availableModels, preferredProvider, {
+    scope: modelScopes,
+    primaryModelFromParent: modelOrigin === "inherited" || inheritsParentModel(input.model, agent.model, input.parentModel),
+    origin: modelOrigin
+  }).model, effectiveThinkingConfig, input.thinking !== void 0);
+  if (!externalRunner) {
+    try {
+      assertThinkingWithinCeiling({ model, configThinking: effectiveThinkingConfig, ceiling: thinkingCeiling, agent: agent.name, runId });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      diagnostics.push({ code: "thinking_ceiling", severity: "error", message });
+      return { ok: false, code: "thinking_ceiling", message, diagnostics };
+    }
+  }
+  if (agent.runner?.type === "external-cli" && isClaudeCodeAdapterId(agent.runner.adapter)) {
+    try {
+      const override = resolveClaudeCodeOverride({
+        model: typeof input.model === "string" ? input.model : void 0,
+        agent,
+        thinking: typeof effectiveThinkingConfig === "string" ? effectiveThinkingConfig : void 0,
+        thinkingCeiling: intersectThinkingCeilings(discovered.maxThinking, input.thinkingCeiling, input.inheritedThinkingCeiling),
+        agentName: agent.name,
+        runId
+      });
+      assertClaudeCodeModelScope({ scopes: modelScopes, model: override?.model, agent: agent.name, runId });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const code = claudeCodeFailureCode(message);
+      diagnostics.push({ code, severity: "error", message });
+      return { ok: false, code, message, diagnostics };
+    }
+  }
+  let toolPlan;
+  const permissionRules = resolvePermissionRules(loadConfig().permissions, agent.permissions);
+  const fast = input.fast ?? agent.fast;
+  const requiredExtensions = externalRunner ? [] : resolveRequiredChildExtensions(input.parentSessionId);
+  try {
+    toolPlan = resolvePiLaunchToolPlan({
+      tools: agent.tools,
+      excludeTools: agent.excludeTools,
+      allowNestedSubagents: agent.allowNestedSubagents,
+      extensions: agent.extensions,
+      subagentOnlyExtensions: agent.subagentOnlyExtensions,
+      requiredExtensions,
+      mcpDirectTools: agent.mcpDirectTools,
+      cwd: effectiveCwd,
+      requireReadTool: resolvedSkills.resolved.length > 0,
+      structuredOutput: Boolean(behavior.outputSchema),
+      fast,
+      model,
+      capabilityCeiling: effectiveCapabilityCeiling,
+      agentName: agent.name,
+      permissionRules,
+      runtimeSnapshotHost: input.runtimeSnapshotHost
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    diagnostics.push({ code: "denied_required_tool", severity: "error", message });
+    return { ok: false, code: "denied_required_tool", message, diagnostics };
+  }
+  const artifactsEnabled = input.artifacts !== false;
+  const artifactsDir = artifactsEnabled ? getArtifactsDir(input.parentSessionFile ?? null, effectiveCwd, input.artifactDir) : void 0;
+  const artifactPaths = artifactsDir ? getArtifactPaths(artifactsDir, runId, agent.name, 0) : void 0;
+  const outputPath = resolveSingleOutputPath(behavior.output, effectiveCwd, effectiveCwd, artifactsDir ? path.join(artifactsDir, "outputs", runId) : void 0);
+  const sessionRoot = input.sessionDir ? path.join(path.resolve(input.sessionDir), runId) : input.sessionRoot ? path.join(path.resolve(input.sessionRoot), runId) : void 0;
+  const sessionDir = sessionRoot ? path.join(sessionRoot, "run-0") : void 0;
+  const lifecycleAsyncDir = input.nestedRootRunId ? path.join(TEMP_ROOT_DIR, "nested-subagent-runs", input.nestedRootRunId, runId) : path.join(DIRS.async, runId);
+  const lifecycleResultPath = input.nestedRootRunId ? nestedResultsPath(input.nestedRootRunId, runId) : resultFilePath(DIRS.results, runId);
+  if (!sessionDir) diagnostics.push({ code: "host_required", severity: "host-required", message: "No sessionRoot/sessionDir was supplied; exact child session paths require the Pi host session-root policy." });
+  if (!externalRunner && input.availableModels === void 0 && (input.model || agent.model || input.parentModel)) {
+    diagnostics.push({ code: "host_required", severity: "host-required", message: "No availableModels snapshot was supplied; model resolution may differ from the active Pi host registry." });
+  }
+  if (resolvedSkills.missing.length > 0) {
+    return { ok: false, code: "missing_skill", message: `Missing skills: ${resolvedSkills.missing.join(", ")}`, diagnostics };
+  }
+  const effectiveThinking = resolveEffectiveThinking(model, effectiveThinkingConfig);
+  const binding = resolveLaunchBinding({
+    agent,
+    task: input.task ?? "",
+    model,
+    ...fast !== void 0 ? { fast } : {},
+    ...effectiveThinking ? { thinking: effectiveThinking } : {},
+    systemPrompt: buildEffectiveSystemPrompt({ agent, resolvedSkills: resolvedSkills.resolved, cwd: effectiveCwd }),
+    skills: requestedSkills,
+    toolPlan,
+    ...outputPath ? { outputPath } : {},
+    outputMode: behavior.outputMode,
+    ...behavior.outputSchema ? { structuredOutputSchema: behavior.outputSchema } : {},
+    ...extensionBindings ? { extensionBindings } : {}
+  });
+  const candidates = candidateList(input.agent, agent, discovery.all);
+  const shadowedCandidates = candidates.filter((candidate) => !candidate.selected);
+  const contractBase = {
+    version: SUBAGENT_LAUNCH_CONTRACT_VERSION,
+    runId,
+    agent: {
+      name: agent.name,
+      ...agent.localName ? { localName: agent.localName } : {},
+      ...agent.packageName ? { packageName: agent.packageName } : {},
+      source: agent.source,
+      filePath: agent.filePath,
+      definitionProjectionVersion: AGENT_DEFINITION_PROJECTION_VERSION,
+      definitionDigest: binding.definitionDigest,
+      shadowedCandidates
+    },
+    context,
+    ...model ? { model } : {},
+    ...effectiveThinking ? { thinking: effectiveThinking } : {},
+    ...thinkingCeiling ? { thinkingCeiling } : {},
+    systemPromptMode: agent.systemPromptMode,
+    inheritProjectContext: agent.inheritProjectContext,
+    inheritGlobalContext: agent.inheritGlobalContext,
+    inheritSkills: agent.inheritSkills,
+    skills: {
+      requested: requestedSkills,
+      resolved: resolvedSkills.resolved.map((skill) => ({ name: skill.name, path: skill.path, source: skill.source })),
+      missing: resolvedSkills.missing
+    },
+    tools: {
+      requestedBuiltin: toolPlan.requestedBuiltinTools,
+      declaredBuiltin: toolPlan.declaredBuiltinTools,
+      ...toolPlan.excludeTools.length > 0 ? { excludeTools: toolPlan.excludeTools } : {},
+      effectiveAllowlist: toolPlan.effectiveToolAllowlist,
+      explicitAllowlist: toolPlan.explicitToolAllowlist,
+      requiredChildTools: toolPlan.requiredChildTools,
+      internalTools: toolPlan.internalTools,
+      mcp: toolPlan.effectiveMcpSelections,
+      effectiveMcpTools: toolPlan.effectiveMcpTools,
+      toolExtensionPaths: toolPlan.toolExtensionPaths,
+      runtimeExtensions: toolPlan.runtimeExtensions,
+      configuredExtensions: toolPlan.configuredExtensions,
+      requiredExtensionIds: toolPlan.requiredExtensions.map(({ id }) => id),
+      // Required paths are private launch authority; preflight exposes their safe IDs above.
+      extensionArgs: toolPlan.extensionArgs.filter((extensionPath) => !requiredExtensions.some(({ path: path2 }) => path2 === extensionPath)),
+      disableAmbientExtensions: toolPlan.disableAmbientExtensions,
+      fanoutAuthorized: toolPlan.fanoutAuthorized,
+      ...toolPlan.capabilityCeiling ? { capabilityCeiling: toolPlan.capabilityCeiling } : {},
+      ...toolPlan.capabilityAudit ? { capabilityAudit: toolPlan.capabilityAudit } : {}
+    },
+    intercomBridge: bridge.active && bridge.mode !== "off" ? { active: true, mode: bridge.mode } : { active: false, mode: bridge.mode },
+    roots: {
+      cwd: effectiveCwd,
+      ...sessionRoot ? { sessionRoot } : {},
+      ...sessionDir ? { sessionDir, sessionFile: path.join(sessionDir, "session.jsonl") } : {},
+      ...artifactsDir ? { artifactsDir } : {},
+      ...artifactPaths ? { artifactPaths } : {},
+      ...outputPath ? { outputPath } : {},
+      lifecycle: {
+        asyncDir: lifecycleAsyncDir,
+        resultPath: lifecycleResultPath,
+        statusPath: path.join(lifecycleAsyncDir, "status.json"),
+        eventsPath: path.join(lifecycleAsyncDir, "events.jsonl"),
+        processTerminalPath: processTerminalPath(lifecycleAsyncDir),
+        processTerminalCandidatePath: processTerminalCandidatePath(lifecycleAsyncDir)
+      }
+    },
+    protocol: {
+      lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
+      packageVersion: packageVersion()
+    },
+    diagnostics,
+    launchContractDigest: binding.launchContractDigest
+  };
+  return { ok: true, contract: { ...contractBase, digest: digestContract(contractBase) } };
+}
+export {
+  SUBAGENT_LAUNCH_CONTRACT_VERSION,
+  resolveSubagentLaunchContract
+};

package/bundle/project-panes.js

@@ -0,0 +1,28 @@
+import {
+  PROJECT_PANES_API_VERSION,
+  PROJECT_PANE_TRUST_STATUS,
+  closeProjectPane,
+  createProjectPaneManager,
+  focusProjectPane,
+  getProjectPaneStatus,
+  openProjectPane,
+  projectPaneBindingPath,
+  readProjectPaneBinding
+} from "./chunk-V2JWDB5U.js";
+import "./chunk-7J4ZXMY7.js";
+import "./chunk-3DC5KBVP.js";
+import "./chunk-ZBC44JJ3.js";
+import "./chunk-5LFLVSTM.js";
+import "./chunk-YFCK7H2S.js";
+import "./chunk-Z7KVHQHL.js";
+export {
+  PROJECT_PANES_API_VERSION,
+  PROJECT_PANE_TRUST_STATUS,
+  closeProjectPane,
+  createProjectPaneManager,
+  focusProjectPane,
+  getProjectPaneStatus,
+  openProjectPane,
+  projectPaneBindingPath,
+  readProjectPaneBinding
+};

package/bundle/required-child-extensions.js

@@ -0,0 +1,6 @@
+import {
+  registerRequiredChildExtensions
+} from "./chunk-CTPAE36Y.js";
+export {
+  registerRequiredChildExtensions
+};

package/bundle/shared-types.js

@@ -0,0 +1,8 @@
+import {
+  DEFAULT_FORK_PREAMBLE,
+  wrapForkTask
+} from "./chunk-5LFLVSTM.js";
+export {
+  DEFAULT_FORK_PREAMBLE,
+  wrapForkTask
+};

package/bundle/workflow-resources.js

@@ -0,0 +1,7 @@
+import {
+  registerWorkflowResource
+} from "./chunk-NF7IEKBH.js";
+import "./chunk-7F6RKT6W.js";
+export {
+  registerWorkflowResource
+};

package/docs/extension-api.md

@@ -353,6 +353,33 @@ Results:
 
 Live update events are bounded progress snapshots, not patches, so consumers should replace the prior snapshot rather than merge it as a delta. Structured delegation coalesces heartbeats whose delegation-visible progress and recent output are unchanged; a duration-only heartbeat therefore does not produce another update. The terminal response remains authoritative for the complete result, error, and final usage details.
 
+Both `:update` and terminal `:response` optionally include one bounded `providerDiagnostics` snapshot:
+
+```ts
+{
+  errorCount: number,
+  lastError?: {
+    kind: "rate_limited" | "transient_other" | "unknown",
+    message: string,
+    at: number,
+  },
+  retry?: {
+    phase: "backoff" | "in_flight",
+    attempt: number,
+    maxAttempts: number,
+    delayMs: number,
+    scheduledAt: number,
+  },
+}
+```
+
+- Coverage is **observed assistant-request errors and Pi retries**, not every provider-internal HTTP attempt. Healthy long reasoning does not invent diagnostics; absence means no observation, not proof that no internal retry happened.
+- `errorCount` increments once per failed assistant `message_end` (`stopReason: "error"`), including repeated identical errors and errors without an `errorMessage`. It does not count retry scheduling, tool failures, aborts, or compaction. The first error is reported immediately, even with no output or tokens and before Pi schedules any retry.
+- Only the failed message's `errorMessage` is classified, never assistant content or tool text. `rate_limited` requires explicit throttling evidence. Text that mentions quota or billing, or says credits, balance, or an account or usage limit is exhausted, is reported as `unknown`, even when it also carries throttling or transient wording, so account exhaustion never looks like transient throttling. Other Pi-recognized transient errors use `transient_other`; anything else uses `unknown`. This classification is observational and does not change Pi's retry policy or the delegation's status/error behavior.
+- `lastError.message` is a short fixed safe description, **not** the raw provider error/body. Raw diagnostics remain in existing child artifacts. No HTTP status or provider code is inferred or exposed here. `at` and `scheduledAt` are observation-time Unix timestamps in milliseconds.
+- `auto_retry_start` schedules `backoff`; `attempt` is the 1-based retry attempt, `maxAttempts` is Pi's retry budget, and `delayMs` is Pi's planned delay, **not** a claimed server `Retry-After`. The next `agent_start`/`turn_start` changes the phase to `in_flight`. `auto_retry_end` ends the sequence after success, exhaustion, or cancellation; it is not a backoff-finished event.
+- Cumulative error history survives recovery and unrelated replacement updates. `retry` is active-only and is absent from every terminal response, including cancellation and timeout. Historical errors alone do not turn a recovered completed result into a failure.
+
 Bounds:
 
 - Schemas are capped at 64 KiB; tasks and returned text/structured values are capped at 1 MiB, with smaller bounds on identity/configuration strings and a maximum `timeoutMs` of 2,147,483,647.

package/docs/observability.md

@@ -116,8 +116,8 @@ FleetView and the under-editor async widget are both enabled by default; set `as
 Default keys:
 
 - `↑`/`↓` or `j`/`k` — select a child
-- `Shift+K`/`Shift+J` — scroll one line
-- `PgUp`/`PgDn` — scroll one page
+- `K`/`J` (Shift+k / Shift+j) — scroll output one line
+- `PgUp`/`PgDn` — scroll output one body viewport page (structured headers stay pinned)
 - `x`/`Ctrl+O` — toggle tool details
 - `r` — refresh
 - `Esc` — close
@@ -126,6 +126,10 @@ Default keys:
 - `D` — stop a selected child's top-level async run after confirmation
 - `H` — open the selected active async child through the available Inspect plugin
 
+In fullscreen mode with Pi mouse reporting enabled, primary-click a visible roster row to select that child. Wheel or trackpad input over the output pane (including its pinned header) scrolls the same viewport as the keyboard. Owned wheel events stay inside the inspector, even at the top and bottom. New output follows the bottom until you scroll away; reaching the bottom resumes following. Steering/redo drafts and stop confirmation retain input ownership, and Prompt Audit blocks roster clicks. Footer shortcuts remain text hints, not buttons.
+
+In regular (non-fullscreen) mode, the terminal retains mouse scrolling and scrollback ownership; internal-pane wheel scrolling and roster clicking are not promised. Use the keyboard controls above to navigate clipped inspector output in either mode. The extension does not enable terminal mouse tracking.
+
 Set `fleetKeybindings` in the extension config to replace inspector-level keys when a terminal intercepts keys such as `PgUp`, `PgDn`, `Home`, or `End`. Prompt modes keep fixed keys such as `Esc`, `Enter`, `Tab`, and stop-confirmation `Y`/`N`.
 
 Enter and `H` use the available Inspect plugin. Inside tmux, this includes the bundled tmux plugin: it splits the focused window, runs the inspector pane there, and records a binding, so `status` and `close` are available and ordinary tmux keys such as the prefix keep working in the pane. On macOS with Ghostty 1.3+ (TERM_PROGRAM=ghostty), this includes the other bundled open-only plugin using Ghostty's preview AppleScript API; status and close are unavailable because no binding is written. In a child-specific inspector, type ordinary guidance and press Enter to send it through the acknowledged steer channel; `steer <message>`, `status`, and `stop` remain available as explicit controls. The bundled Herdr plugin uses Herdr 0.7.5+.

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "pi-subagents",
-  "version": "0.80.0",
+  "version": "0.81.0",
   "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -61,72 +61,72 @@
   "exports": {
     ".": {
       "types": "./index.d.ts",
-      "default": "./index.js"
+      "default": "./bundle/index.js"
     },
     "./background-work": {
       "types": "./src/api/background-work.d.ts",
-      "default": "./src/api/background-work.js"
+      "default": "./bundle/background-work.js"
     },
     "./external-job-provider": {
       "types": "./src/api/external-job-provider.d.ts",
-      "default": "./src/api/external-job-provider.js"
+      "default": "./bundle/external-job-provider.js"
     },
     "./external-runs": {
       "types": "./src/api/external-runs.d.ts",
-      "default": "./src/api/external-runs.js"
+      "default": "./bundle/external-runs.js"
     },
     "./agents": {
       "types": "./src/api/agents.d.ts",
-      "default": "./src/api/agents.js"
+      "default": "./bundle/agents.js"
     },
     "./inspectors": {
       "types": "./src/api/inspectors.d.ts",
-      "default": "./src/api/inspectors.js"
+      "default": "./bundle/inspectors.js"
     },
     "./delegation": {
       "types": "./src/api/delegation.d.ts",
-      "default": "./src/api/delegation.js"
+      "default": "./bundle/delegation.js"
     },
     "./capability-ceiling": {
       "types": "./src/api/capability-ceiling.d.ts",
-      "default": "./src/api/capability-ceiling.js"
+      "default": "./bundle/capability-ceiling.js"
     },
     "./workflow-resources": {
       "types": "./src/api/workflow-resources.d.ts",
-      "default": "./src/api/workflow-resources.js"
+      "default": "./bundle/workflow-resources.js"
     },
     "./required-child-extensions": {
       "types": "./src/api/required-child-extensions.d.ts",
-      "default": "./src/api/required-child-extensions.js"
+      "default": "./bundle/required-child-extensions.js"
     },
     "./preflight": {
       "types": "./src/api/preflight.d.ts",
-      "default": "./src/api/preflight.js"
+      "default": "./bundle/preflight.js"
     },
     "./control-channel": {
       "types": "./src/api/control-channel.d.ts",
-      "default": "./src/api/control-channel.js"
+      "default": "./bundle/control-channel.js"
     },
     "./intercom-bridge": {
       "types": "./src/api/intercom-bridge.d.ts",
-      "default": "./src/api/intercom-bridge.js"
+      "default": "./bundle/intercom-bridge.js"
     },
     "./child-tool-plan": {
       "types": "./src/api/child-tool-plan.d.ts",
-      "default": "./src/api/child-tool-plan.js"
+      "default": "./bundle/child-tool-plan.js"
     },
     "./shared-types": {
       "types": "./src/api/shared-types.d.ts",
-      "default": "./src/api/shared-types.js"
+      "default": "./bundle/shared-types.js"
     },
     "./project-panes": {
       "types": "./src/api/project-panes.d.ts",
-      "default": "./src/api/project-panes.js"
+      "default": "./bundle/project-panes.js"
     }
   },
   "pi": {
     "extensions": [
-      "./index.js"
+      "./bundle/index.js"
     ],
     "skills": [
       "./skills"

package/src/agents/frontmatter.d.ts

@@ -1,6 +1,8 @@
 /**
  * Normalize a simple-scalar frontmatter list from comma-separated or block-list syntax.
  * Only the standard `- item` marker is removed; ordinary hyphenated values stay intact.
+ * A trailing ` #...` comment is dropped from unquoted `- item` lines. Single-line values are left
+ * alone because parseFrontmatter has already removed their quotes, so `"notes #1.md"` must survive.
  */
 export declare function parseFrontmatterList(raw: string | undefined): string[] | undefined;
 /**