@hachej/boring-agent 0.1.104 → 0.1.107

package/dist/shared/index.js

@@ -71,17 +71,17 @@ import {
   validateConfig,
   validateConsumptionGuards,
   validateTool
-} from "../chunk-JNEKOVMJ.js";
+} from "../chunk-6OANSUEI.js";
 import {
   SAFE_NATIVE_SESSION_ID,
+  compareSessionOrder,
   noopTelemetry,
   safeCapture
-} from "../chunk-4IQ4HHBG.js";
+} from "../chunk-7XAOVFSN.js";
 import {
   AGENT_NOT_IMPLEMENTED_UNTIL_T1,
-  AgentNotImplementedError,
-  sessionStreamPath
-} from "../chunk-WSQ5QNIY.js";
+  AgentNotImplementedError
+} from "../chunk-YTUZFKB3.js";
 import {
   AGENT_GATEWAY_ERROR_CODES,
   AgentGatewayError,
@@ -114,7 +114,7 @@ import {
   extractToolUiMetadata,
   isToolUiMetadata,
   sanitizeToolUiMetadata2 as sanitizeToolUiMetadata
-} from "../chunk-6DRHERVK.js";
+} from "../chunk-MVKXLMH3.js";
 import {
   safeRandomUUID
 } from "../chunk-YGRQ4Q5P.js";
@@ -127,7 +127,7 @@ import {
   ERROR_CODES,
   ErrorCode,
   ErrorLogFieldsSchema
-} from "../chunk-K25PK5EC.js";
+} from "../chunk-3JFPS2O6.js";
 export {
   AGENT_GATEWAY_ERROR_CODES,
   AGENT_KNOWLEDGE_FILESYSTEM_ID,
@@ -219,6 +219,7 @@ export {
   assertNoConsumptionCycle,
   assertValidTransition,
   assertWithinConsumptionDepth,
+  compareSessionOrder,
   createAgentAssetDigest,
   createAgentDefinitionDigest,
   createAgentDeploymentDigest,
@@ -240,7 +241,6 @@ export {
   safeRandomUUID,
   sandboxCredentialPayloadMetadataBytesV1,
   sanitizeToolUiMetadata,
-  sessionStreamPath,
   validateAgentDefinition,
   validateAgentDeployment,
   validateAgentTask,

package/dist/{types-B1xDlBSo.d.ts → types-B7-PN5jV.d.ts}

@@ -1,10 +1,11 @@
 import { FastifyRequest, FastifyPluginAsync } from 'fastify';
-import { C as ToolReadinessRequirement, v as TelemetrySink, s as AgentTool, D as AgentHarnessFactory } from './harness-Dcd08yKr.js';
-import { F as FileSearch, b as AgentSkillResource, c as WorkspaceAgentDirectRunInput, L as LeaseBoundWorkspaceAgent } from './file-search-qcD5zItr.js';
+import { C as ToolReadinessRequirement, w as TelemetrySink, s as AgentTool, D as AgentHarnessFactory } from './harness-Ct0e4RWc.js';
+import { F as FileSearch, b as AgentSkillResource, c as WorkspaceAgentDirectRunInput, L as LeaseBoundWorkspaceAgent } from './file-search-BGUHnW9o.js';
 import { b as Workspace, h as RuntimeFilesystemCapability, j as WorkspaceRuntimeContext, c as Sandbox } from './sandbox-BMhut3kh.js';
-import { b as AgentSessionRef, V as VerifiedAgentScopeClaim, i as AgentGatewayErrorDTO, x as JsonValue, a as AuthorizedAgentScope, A as AgentGateway, k as AgentScopeVerifier } from './errors-DH7C01Pm.js';
-import { C as ChatModelSelection } from './piChatEvent-iNSXiFQq.js';
+import { b as AgentSessionRef, V as VerifiedAgentScopeClaim, k as AgentGatewayErrorDTO, B as JsonValue, a as AuthorizedAgentScope, A as AgentGateway, m as AgentScopeVerifier, F as ResolveAgentAccess } from './errors-CEU4iujR.js';
+import { C as ChatModelSelection } from './piChatEvent-BUWIzw5l.js';
 import { RuntimeHostOperations, RuntimeFilesystemBinding as RuntimeFilesystemBinding$1 } from '@hachej/boring-bash/agent';
+import { BwrapArgsOptions } from '@hachej/boring-sandbox/providers/bwrap';
 import { CreateNodeWorkspaceOptions, BoringAgentRuntimePaths } from '@hachej/boring-sandbox/providers/node-workspace';
 import { PackageSource, ExtensionFactory } from '@mariozechner/pi-coding-agent';
 
@@ -86,11 +87,11 @@ interface ModelsRoutesOptions {
  *                     (fail closed) so hosts can enforce hard stops.
  *   recordUsage       once per native assistant message carrying usage.
  *                     `usageId` is a stable idempotency key.
- *   settleRun         when the run reaches a native terminal state and usage
- *                     was recorded (or it finished ok).
- *   releaseRun        when the run never produced billable usage: rejected
- *                     execution, cleared queue, cancel/abort, or error before
- *                     any usage arrived.
+ *   settleRun         when the run reaches a native terminal state and billable
+ *                     usage or an authoritative all-zero usage row was recorded.
+ *   releaseRun        when the run does not settle: rejected execution, cleared
+ *                     queue, cancel/abort, error before usage, or a fail-closed
+ *                     fallback charge.
  *
  * Every run terminates with exactly one settle or release from the
  * coordinator; sinks should still treat all four methods as idempotent
@@ -102,8 +103,8 @@ interface AgentMeteringSink {
     reserveRun(input: MeteringReserveInput): Promise<MeteringReservationResult>;
     /** Records the usage and returns the credit micros it was actually billed. The
      * coordinator counts a usage as billable from this charged amount (not raw provider
-     * fields), so a row that prices to 0 (e.g. cost-only usage when provider cost isn't
-     * trusted) doesn't make a free run settle. */
+     * fields). A complete, internally consistent all-zero report settles at zero;
+     * potentially billable usage priced to 0 retains fail-closed fallback. */
     recordUsage(input: MeteringUsageInput): Promise<MeteringUsageResult>;
     settleRun(input: MeteringSettleInput): Promise<void>;
     releaseRun(input: MeteringReleaseInput): Promise<void>;
@@ -239,6 +240,12 @@ declare class ReadyStatusTracker {
  * may inject an equivalent implementation with their Workspace + Sandbox pair.
  */
 interface AgentRuntimeHostOperations extends RuntimeHostOperations {
+    /**
+     * Agent legally depends on the provider package, so the injected builder is
+     * typed with the canonical options here rather than the narrowed slice
+     * boring-bash declares.
+     */
+    buildBwrapArgs(workspaceRoot: string, options?: BwrapArgsOptions): string[];
     createNodeWorkspace(root: string, options?: CreateNodeWorkspaceOptions): Workspace;
     getNodeWorkspaceHostRoot(workspace: Workspace): string | undefined;
     getBoringAgentRuntimePaths(workspaceRoot: string): BoringAgentRuntimePaths;
@@ -408,7 +415,8 @@ interface RuntimeModeAdapter {
     readonly readiness?: RuntimeModeReadinessHooks;
     readonly cachedBindingHealthCheck?: RuntimeCachedBindingHealthCheck;
     create(ctx: ModeContext): Promise<RuntimeBundle>;
-    getRuntimeLayoutRoot?(ctx: ModeContext): string;
+    /** Resolves the provider-owned workspace root in runtime coordinates. */
+    getRuntimeLayoutRoot(ctx: ModeContext): string;
     evictCachedRuntime?(ctx: {
         workspaceId: string;
     }): void | Promise<void>;
@@ -529,15 +537,26 @@ interface RuntimeFilesystemBindingOperations {
         path: string;
     }): never;
 }
+interface RuntimeFilesystemCatalogPresentation {
+    readonly visible?: boolean;
+    readonly label?: string;
+    readonly rootDir?: '.' | `/${string}`;
+}
 interface RuntimeFilesystemBinding {
     readonly filesystem: string;
     readonly access: 'readonly' | 'readwrite';
     readonly operations: RuntimeFilesystemBindingOperations;
+    /** User-facing catalog projection; internal routing continues to use filesystem. */
+    readonly catalog?: RuntimeFilesystemCatalogPresentation;
+    /** When present, only these addressed Agents receive this user-visible binding. */
+    readonly agentTypeIds?: readonly string[];
 }
 interface RuntimeBundle {
     runtimeContext?: WorkspaceRuntimeContext;
     /**
-     * Server-private host/storage root for host-side filesystem work. Do not use
+     * Server-private host/storage root for host-side filesystem work. Required
+     * when runtime-coordinate workspace resources have an explicit host mirror;
+     * absence means composition must not infer or project a host path. Do not use
      * this as the agent-visible cwd; Workspace.root remains the public runtime
      * namespace shown to tools/model.
      */
@@ -613,6 +632,11 @@ interface PiHarnessOptions {
     /** Reject an explicit unavailable/unknown model instead of silently falling back. */
     strictModelResolution?: boolean;
 }
+/** Pi harness options with the discovery flags resolved to definite booleans. */
+type ResolvedPiHarnessOptions = PiHarnessOptions & {
+    noContextFiles: boolean;
+    noSkills: boolean;
+};
 interface HotReloadablePiResources {
     additionalSkillPaths?: string[];
     packages?: PiPackageSource[];
@@ -648,7 +672,7 @@ interface AgentSkillResourceSnapshot {
     locateSkill(filePath: string): AgentSkillResource | undefined;
 }
 
-type AgentGatewayEffect = 'session.create' | 'session.rename' | 'session.delete' | 'session.prompt' | 'session.followup' | 'session.interrupt' | 'session.stop' | 'session.queue.clear' | 'agent.reload' | 'session.command.execute';
+type AgentGatewayEffect = 'session.create' | 'session.rename' | 'session.archive' | 'session.delete' | 'session.prompt' | 'session.followup' | 'session.interrupt' | 'session.stop' | 'session.queue.clear' | 'agent.reload' | 'session.command.execute';
 type AgentRequestTarget = {
     readonly kind: 'agent';
     readonly agentTypeId: string;
@@ -754,7 +778,23 @@ interface AgentInstructionFileRef {
     readonly path: string;
     readonly role: 'persona';
 }
-interface ConfiguredAgentHostAgentSpec {
+/**
+ * An authored instruction file as the fleet composer knows it: a canonical
+ * HOST absolute path, not yet addressed against any workspace.
+ *
+ * The two shapes are deliberately distinct. A multi-workspace host (the CLI
+ * hub, core) serves a DIFFERENT root per request, so composition cannot know
+ * which root a ref should be relative to; only the request can. The spec
+ * therefore carries sources, and `describe` publishes the subset that is
+ * reachable through the root actually being served (gh-1189).
+ */
+interface AgentInstructionSource {
+    /** Canonical absolute path on the host filesystem. */
+    readonly absolutePath: string;
+    readonly role: 'persona';
+}
+declare const DEFAULT_AGENT_TYPE_ID = "default";
+interface AgentHostAgentSpec {
     readonly agentTypeId: string;
     readonly definition: {
         readonly instructions: string;
@@ -775,8 +815,12 @@ interface ConfiguredAgentHostAgentSpec {
         /** Host path of the package's `knowledge/` folder. */
         readonly rootDir: string;
     };
-    /** Authored instruction sources behind `definition.instructions`. */
-    readonly instructionFiles?: readonly AgentInstructionFileRef[];
+    /**
+     * Authored instruction sources behind `definition.instructions`, as host
+     * absolute paths. Addressed against a served workspace root per request by
+     * `describe`, never at composition time.
+     */
+    readonly instructionSources?: readonly AgentInstructionSource[];
     readonly plugins?: readonly {
         /** Canonical app-preflighted plugin ID. */
         readonly name: string;
@@ -787,12 +831,12 @@ interface ConfiguredAgentHostAgentSpec {
         /** RESERVED / NOT ENFORCED. Per-turn token-limit enforcement is future work. */
         readonly maxTokensPerTurn?: number;
     };
+    /** Trusted host-owned provisioning grants; absent means no inherited resources. */
+    readonly provisioning?: {
+        readonly inheritSkillPaths?: boolean;
+    };
 }
-interface LegacyDefaultAgentHostSpec {
-    readonly agentTypeId: 'default';
-    readonly legacyDefault: true;
-}
-type AgentHostAgentSpec = ConfiguredAgentHostAgentSpec | LegacyDefaultAgentHostSpec;
+type ConfiguredAgentHostAgentSpec = AgentHostAgentSpec;
 /**
  * Server-only compiler output. App-specific validated handles may be attached,
  * but the Host revalidates the complete agent ID set before freezing it.
@@ -837,6 +881,12 @@ interface ResolvedAgentRuntimeScope {
     readonly sessionNamespace: string;
     readonly pi?: PiHarnessOptions;
     readonly extraTools?: readonly AgentTool[];
+    /** Joined trusted-plugin cleanup invoked after backend session deletion succeeds. */
+    readonly onSessionDelete?: (input: {
+        readonly workspaceScopeId: string;
+        readonly agentTypeId: string;
+        readonly sessionId: string;
+    }) => Promise<void>;
     readonly includeFilesystemTools?: boolean;
     readonly includeUploadTools?: boolean;
     readonly sessionDir?: string;
@@ -944,6 +994,8 @@ interface CreateAgentHostOptions {
     readonly fleetCompiler: AgentFleetCompiler;
     readonly hostId?: string;
     readonly scopeVerifier: AgentScopeVerifier;
+    /** Optional product-owned Seat/entitlement policy; omission preserves legacy fleet-wide access. */
+    readonly resolveAgentAccess?: ResolveAgentAccess;
     readonly runtimeModeAdapter: RuntimeModeAdapter;
     readonly runtimeHost?: AgentRuntimeHostOperations;
     readonly sessionRoot?: string;
@@ -986,4 +1038,4 @@ interface CreatedAgentHost {
     runWithWorkspaceAgent(input: AgentHostDispatcherRunInput, run: (binding: LeaseBoundWorkspaceAgent) => Promise<void>): Promise<void>;
 }
 
-export { type PiExtensionFactory as $, type AgentGatewayEffect as A, type BuiltinRuntimeModeId as B, type ConfiguredAgentHostAgentSpec as C, type AgentFleetCompiler as D, type AgentRequestTarget as E, type RuntimeFilesystemAccessDecision as F, type AgentHostDescription as G, type AgentHostDirectProjectionOptions as H, type AgentHostDispatcherRunInput as I, type AgentHostEnvironmentLease as J, type AgentHostHandle as K, type LegacyDefaultAgentHostSpec as L, type ModeContext as M, type MeteringReleaseInput as N, type MeteringReleaseReason as O, type ProvisionWorkspaceRuntimeOptions as P, type MeteringReservationResult as Q, type RuntimeModeAdapter as R, type MeteringReserveInput as S, type MeteringRunKind as T, type MeteringRunScope as U, type MeteringRunStatus as V, type WorkspaceProvisioningResult as W, type MeteringSettleInput as X, type MeteringUsage as Y, type MeteringUsageInput as Z, PI_PACKAGE_RESOURCE_FILTERS as _, type PiPackageSource as a, type PluginSkillSource as a0, type ResolvedEnvironmentScope as a1, type RuntimeFilesystemBindingOperations as a2, type RuntimeNodePackageSpec as a3, type RuntimeProvisioningContribution as a4, type RuntimePythonSpec as a5, type RuntimeTemplateContribution as a6, type WorkspaceProvisioningExecResult as a7, compactPiPackages as a8, mergePiPackageSources as a9, normalizeMeteringUsage as aa, piPackageSourceKey as ab, type RuntimeModeId as b, type AgentRuntimeHostOperations as c, type RuntimeBashStrategy as d, type RuntimeFilesystemStrategy as e, type WorkspaceProvisioningAdapter as f, type AgentInstructionFileRef as g, type AgentHostAgentSpec as h, type RuntimeBundle as i, type PiHarnessOptions as j, type AgentMeteringSink as k, type RuntimeFilesystemBinding as l, type CreatedAgentHost as m, type MeteringErrorLogger as n, ReadyStatusTracker as o, type CreateAgentHostOptions as p, type CompiledAgentHostAgentSpec as q, type AgentRequestLedger as r, type AgentEffectAdmission as s, type AuthorizedEnvironmentIntent as t, type AgentHostEnvironmentScope as u, type ResolvedAgentRuntimeScope as v, type AgentRequestKey as w, type AgentRequestLedgerPrepareResult as x, type AgentRequestFailure as y, type AgentRequestLedgerRecord as z };
+export { type MeteringUsageInput as $, type AgentGatewayEffect as A, type BuiltinRuntimeModeId as B, type ConfiguredAgentHostAgentSpec as C, type AgentRequestLedgerRecord as D, type AgentFleetCompiler as E, type AgentRequestTarget as F, type RuntimeFilesystemAccessDecision as G, type AgentHostDescription as H, type AgentHostDirectProjectionOptions as I, type AgentHostDispatcherRunInput as J, type AgentHostEnvironmentLease as K, type AgentHostHandle as L, type ModeContext as M, DEFAULT_AGENT_TYPE_ID as N, type MeteringErrorLogger as O, type ProvisionWorkspaceRuntimeOptions as P, type MeteringReleaseInput as Q, type RuntimeModeAdapter as R, type MeteringReleaseReason as S, type MeteringReservationResult as T, type MeteringReserveInput as U, type MeteringRunKind as V, type WorkspaceProvisioningResult as W, type MeteringRunScope as X, type MeteringRunStatus as Y, type MeteringSettleInput as Z, type MeteringUsage as _, type PiPackageSource as a, PI_PACKAGE_RESOURCE_FILTERS as a0, type PiExtensionFactory as a1, type PluginSkillSource as a2, type ResolvedEnvironmentScope as a3, type RuntimeFilesystemBindingOperations as a4, type RuntimeNodePackageSpec as a5, type RuntimeProvisioningContribution as a6, type RuntimePythonSpec as a7, type RuntimeTemplateContribution as a8, type WorkspaceProvisioningExecResult as a9, compactPiPackages as aa, mergePiPackageSources as ab, normalizeMeteringUsage as ac, piPackageSourceKey as ad, type RuntimeModeId as b, type AgentRuntimeHostOperations as c, type RuntimeBashStrategy as d, type RuntimeFilesystemStrategy as e, type WorkspaceProvisioningAdapter as f, type AgentInstructionSource as g, type AgentInstructionFileRef as h, type AgentHostAgentSpec as i, type RuntimeBundle as j, type PiHarnessOptions as k, type AgentMeteringSink as l, type RuntimeFilesystemBinding as m, type CreatedAgentHost as n, type ResolvedPiHarnessOptions as o, ReadyStatusTracker as p, type CreateAgentHostOptions as q, type CompiledAgentHostAgentSpec as r, type AgentRequestLedger as s, type AgentEffectAdmission as t, type AuthorizedEnvironmentIntent as u, type AgentHostEnvironmentScope as v, type ResolvedAgentRuntimeScope as w, type AgentRequestKey as x, type AgentRequestLedgerPrepareResult as y, type AgentRequestFailure as z };

package/docs/AGENT_GATEWAY_V0.md

@@ -33,16 +33,18 @@ Only the app-owned verifier returns identity facts, as
 `VerifiedAgentScopeClaim`. `AgentSessionRef` deliberately carries **no
 `hostId`** — session refs are `{ agentTypeId, sessionId }` and nothing else.
 
-## The 7 methods (+ close)
+## The 8 methods (+ close, plus optional authorization hook)
 
 ```ts
 interface AgentGateway {
+  authorizeAgentAccess?(input: { scope; agentTypeId; operation }): Promise<void>
   listAgents(input: ListAgentsInput): Promise<readonly AgentSummary[]>
   listSessions(input: AuthorizedAgentSessionQuery): Promise<AgentSessionPage>
   createSession(input: CreateAgentSessionInput): Promise<AgentSessionRef>
   connectSession(input: ConnectAgentSessionInput): Promise<AgentSessionConnection>
   readSessionState(input: ReadAgentSessionStateInput): Promise<AgentSessionStateSnapshot>
   renameSession(input: RenameAgentSessionInput): Promise<AgentSessionSummary>
+  setSessionArchived(input: SetAgentSessionArchivedInput): Promise<AgentSessionSummary>
   deleteSession(input: DeleteAgentSessionInput): Promise<void>
   close(): Promise<void>
 }
@@ -61,6 +63,7 @@ interface CreateAgentSessionInput    { scope; agentTypeId; requestId; title? }
 interface ConnectAgentSessionInput   { scope; ref; cursor? }
 interface ReadAgentSessionStateInput { scope; ref }
 interface RenameAgentSessionInput    { scope; ref; requestId; title }
+interface SetAgentSessionArchivedInput { scope; ref; requestId; archived }
 interface DeleteAgentSessionInput    { scope; ref; requestId }
 ```
 
@@ -97,10 +100,12 @@ shorthand. Prompts add `displayContent?`, `model?`, `thinkingLevel?`,
 
 ## Error codes
 
-Fourteen, exhaustive, order-stable, exported as both a const map and
+Seventeen, exhaustive, order-stable, exported as both a const map and
 `AGENT_GATEWAY_ERROR_CODES`:
 
 `AGENT_TYPE_UNKNOWN` · `AGENT_SESSION_NOT_FOUND` · `AGENT_SCOPE_DENIED` ·
+`AGENT_ENTITLEMENT_REQUIRED` · `AGENT_ACCESS_FORBIDDEN` ·
+`AGENT_ACCESS_POLICY_UNAVAILABLE` ·
 `AGENT_SESSION_REPLAY_GAP` · `AGENT_SESSION_CURSOR_AHEAD` ·
 `AGENT_SESSION_CURSOR_EXPIRED` · `AGENT_SESSION_CURSOR_INVALID` ·
 `AGENT_REQUEST_CONFLICT` · `AGENT_REQUEST_IN_PROGRESS` ·
@@ -152,3 +157,36 @@ rejected. Future internal/external host tiers belong to #905, not here.
 
 `scripts/check-alignment-invariants.mjs` enforces that nothing outside an
 allowlist calls it.
+
+## Private backend seam
+
+The session-runtime path below `EmbeddedAgentGateway` is the server-only
+`AgentHarnessBackend`. It is private to the `createAgentHost()` construction
+funnel: consumers still inject only `harnessFactory`, and there is no public
+backend factory or second session path.
+
+`AgentPromptPayload` is exposed from the shared chat barrel as a type only. Its
+“server-only” contract means browser schemas never accept the `requireIdle`
+selector.
+
+`PiSessionHarnessBackend` is the sole production implementation today. It
+adapts the unchanged `HarnessPiChatService` and owns the mapping from the
+workspace-scoped backend address and attribution context into the legacy Pi
+request context. The backend carries no credentials, membership authority, or
+model catalog. Reload and slash-command host effects continue to use the
+composition harness directly; they are host capabilities, not session-runtime
+operations.
+
+The Gateway request ledger is the only idempotency authority. A backend method
+may be invoked again after a crash only through a ledger-admitted request; the
+backend itself promises no deduplication. P1-B substitutes the adapter-private
+replay source below `HarnessPiChatService`, not this interface. Later operations
+may extend the interface only in their named slices (`resumePausedToolCall` in
+A3b and `markTurnInterrupted` in A4); neither is part of the current seam.
+
+CI pins the boundary in three directions: Agent Host production code cannot
+import a Pi runtime, only `harnessBackend/**` can reference the concrete Pi chat
+service, and Workspace/Core/CLI/playground consumers cannot name the private
+backend interface or module path. Retire the legacy `PiChatSessionService` when
+the legacy `core/createAgent` path is removed; it is intentionally not widened
+or migrated here.

package/docs/ERROR_CODES.md

@@ -45,7 +45,7 @@ All API failures must use the response envelope:
 | `AGENT_FLEET_MODEL_POLICY_UNCOMPILED` | Agent fleet configuration declares a model policy that the app fleet compiler did not resolve | 500 | configure app fleet compiler | error | stable (trusted API) |
 | `AGENT_FLEET_SEAT_PERSONA_INVALID` | `loadConfiguredAgentFleet` excluded a fleet.yaml seat because its persona package failed to materialize or compose | 500 | fix persona package/spec | error | stable (trusted API) |
 | `AGENT_FLEET_SEAT_SKILL_DIGEST_MISMATCH` | `loadConfiguredAgentFleet` excluded a fleet.yaml seat because a pinned skill's canonical content was unavailable or its digest drifted | 500 | run `pnpm write:skill-digests` or fix the skill file | error | stable (trusted API) |
-| `AGENT_FLEET_SEAT_INSTRUCTIONS_PATH_UNPUBLISHABLE` | `loadConfiguredAgentFleet` composed a fleet.yaml seat but withheld the link to its persona `instructions.md`. Usually because the host serves a workspace root that does not contain the personas tree (multi-workspace hosts resolve a root per request and pass `workspaceRoot: null`); rarely because the seat name is not a safe path segment | 500 | expected on multi-workspace hosts — the seat runs normally, only the Agent-details instruction link is withheld. On a single-root host, check that `workspaceRoot` is the root the `user` filesystem serves and contains `personasDir`. If the message names the seat, rename it to `[A-Za-z0-9][A-Za-z0-9._-]*` | warn | stable (trusted API) |
+| `AGENT_FLEET_SEAT_INSTRUCTIONS_PATH_UNPUBLISHABLE` | `GET /api/v1/agents/:agentTypeId/describe` withheld the link to a seat's persona `instructions.md` for THIS request. Usually because the workspace root serving the request does not contain the personas tree (the fleet is composed from a repository root while the request is served from somewhere else); also when the persona canonically resolves outside that root through a symlink, when the source no longer exists, or when the seat name is not a safe path segment. NOT an HTTP error: the describe call still returns 200 — the code is only logged as a warning while that link is omitted from the response | 200 (log-only) | expected whenever a request is served from a workspace the personas are outside of — the seat runs normally, only the Agent-details instruction link is withheld. Serve the request from a workspace that contains the personas tree to get the link. If the message names an unsafe composed path, rename the seat directory to `[A-Za-z0-9][A-Za-z0-9._-]*` | warn | stable (trusted API) |
 | `AGENT_FLEET_CONFIG_FILE_INVALID` | `loadConfiguredAgentFleet`'s fleet.yaml could not be read, parsed, or validated (whole-fleet failure, not per-seat) | 500 | fix `.agents/factory/fleet.yaml` | error | stable (trusted API) |
 | `AGENT_DEFINITION_ID_CONFLICT` | Multiple discovered plugin packages claim the same agent definition id, so every claimant is excluded | 500 | remove or rename conflicting definitions | error | stable (trusted API) |
 | `AGENT_DEFINITION_UNSEATED` | A discovered agent package is not named by the fleet roster and remains inert | 200 | seat it in class-B fleet config if activation is intended | info | stable (trusted API) |
@@ -98,6 +98,7 @@ All API failures must use the response envelope:
 | `ABORTED` | Request cancelled via `AbortSignal` | 499 | retry | warn | stable (public API) |
 | `PAYMENT_REQUIRED` | Billing/metering sink rejected the run (e.g. credits exhausted) | 402 | user-fix | warn | stable (public API) |
 | `MODEL_BUDGET_EXCEEDED` | Governance model budget for this user/model is exhausted | 402 | user-fix | warn | stable (public API) |
+| `MODEL_CONTEXT_WINDOW_EXCEEDED` | Provider rejects a model request because its conversation context is too large | 413 | compact/retry or start a smaller chat | warn | stable (public API) |
 | `METERING_UNSUPPORTED_COMMAND` | Slash-command execution is disabled because metering cannot yet reserve/settle that path | 409 | user-fix | warn | stable (public API) |
 | `SESSION_NOT_FOUND` | Session id does not exist | 404 | user-fix | warn | stable (public API) |
 | `SESSION_LOCKED` | Session currently locked by concurrent writer | 409 | retry | warn | stable (public API) |

package/docs/README.md

@@ -82,6 +82,7 @@ the agent ↔ workspace boundary is in
 
 **Contracts & operations**
 
+- [SESSION_IDENTITY](./SESSION_IDENTITY.md) — durable session stream key, owner attributes, and v1→v2 migration contract.
 - [ERROR_CODES](./ERROR_CODES.md) — the stable API error-code registry.
 - [CSP](./CSP.md) — Content-Security-Policy compatibility.
 - [ACCESSIBILITY](./ACCESSIBILITY.md) — a11y coverage and known gaps.

package/docs/SESSION_IDENTITY.md

@@ -0,0 +1,91 @@
+# Session stream identity
+
+This contract governs durable agent event-stream addressing. The code in
+`src/shared/events.ts` is authoritative when this document and the
+implementation disagree.
+
+## Durable key
+
+A session stream is keyed by `(workspaceScopeId, sessionId)`. Its path is:
+
+```text
+sessions/<enc(workspaceScopeId)>/<enc(sessionId)>
+```
+
+`enc` percent-encodes every byte outside `[A-Za-z0-9._-]`, using uppercase
+hex. Both fields are opaque, non-empty, well-formed Unicode strings; session
+ids need not be UUIDs.
+`sessionStreamPath(identity)` is the only constructor and
+`parseSessionStreamPath(path)` accepts only the canonical encoding.
+The value helpers are server-internal and are not exported from the package's
+shared public barrel; only the `SessionStreamIdentity` type is public there.
+
+The process-local Pi cache may still use a JSON tuple, but it is not a durable
+key. Gateway host maps use `(workspaceScopeId, agentTypeId, sessionId)`, and
+Pi transcript directories use their existing agent and workspace namespace.
+Neither grammar may be embedded into a durable stream path.
+
+When no event store is configured, legacy/headless callers may omit
+`workspaceId`. The service preserves their pre-durability JSON cache key and
+never constructs or validates a durable path. Once an event store is present,
+both identity fields are required and invalid identity or durable-read errors
+surface instead of being treated as a missing transcript.
+
+## Owner attributes
+
+`boring_event_stream_owners` stores one row for each addressed session stream:
+
+- `path` is the primary key.
+- `workspace_scope_id` and `session_id` repeat the durable identity and are
+  indexed together.
+- `agent_type_id` is required for newly opened channels but is an attribute,
+  not part of the stream key.
+- `auth_subject_id` is execution attribution, never ownership.
+- `seat_id` and `thread_id` are reserved nullable columns; A1 defines no
+  semantics or foreign keys for them.
+- `key_version` is `2` for streams created with this grammar and `1` for
+  migrated rows.
+
+There is deliberately no foreign key. SQLite foreign-key enforcement is not
+enabled on this connection; migration validation and store transactions enforce
+the relationship instead.
+
+`auth_subject_id` uses first-writer semantics: the first successful
+`createSessionStream` claim records it, and later opens do not replace it.
+This is attribution for the opening execution, not a durable authorization or
+ownership decision.
+
+## Schema v1 to v2
+
+Opening a v1 database runs one `BEGIN IMMEDIATE` migration. It preflights every
+old stream into `boring_event_stream_migration_v2` by parent `rowid`, raw
+`path`, and `typeof(path)`, validates unique targets, every parent's path and
+metadata, per-stream row counts and maximum sequence values, every owner row,
+and every child row before swapping paths across all three event tables.
+
+The collision rules are exhaustive:
+
+1. A single old row rekeys to its v2 path.
+2. For an empty-user row colliding with user-bearing rows, the empty-user row
+   wins and the others are quarantined.
+3. If several user-bearing rows collide without an empty-user row, all are
+   quarantined because their sequence spaces cannot be merged safely.
+4. Non-matching, malformed, or otherwise ambiguous old paths are quarantined.
+
+Legacy identities containing ill-formed Unicode are quarantined with reason
+`unencodable-identity`. Non-TEXT parent paths (including SQL `NULL`) use a
+rowid-safe quarantine destination; their raw original value/type remains in
+the manifest. No encoding failure aborts migration of the remaining rows.
+
+Ordinary quarantine destinations are `quarantine/v1/<enc(oldPath)>`; rowid-safe
+destinations cover values that cannot be encoded. Rows are never dropped. The
+swap is validated again before `schema_version` becomes `2`.
+Concurrent openers serialize on the immediate transaction, re-read the version
+under the lock, and only one migrates. A migrated owner has
+`agent_type_id = NULL` until the next legitimate channel open backfills it from
+the composition's explicit agent type.
+
+The migration is a rollback fence, not a reversible downgrade. Disable
+`BORING_CHAT_DURABLE_STREAM` before running an old binary; an old binary pointed
+at a v2 file refuses it with `EventStreamSchemaVersionError` rather than writing
+mixed path grammars.

package/docs/tools.md

@@ -93,6 +93,10 @@ resources declared in `package.json#pi` (`extensions`, `skills`, `prompts`, and
 place for tools/skills that should update without restarting the workspace
 server.
 
+## Optional trusted plugin tools
+
+App hosts may add tools through trusted Workspace server plugins. Disposable lease support is additive: the optional sandbox plugin supplies `sandbox` and `sandbox_bash` without changing canonical bash or file-tool schemas. Agent-authored plugin selection alone cannot grant that host authority.
+
 ## Runtime modes
 
 See [runtime.md](./runtime.md) for how tool execution is sandboxed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.1.104",
+  "version": "0.1.107",
   "type": "module",
   "license": "MIT",
   "description": "Pane-embeddable coding agent. Ships direct/local/vercel-sandbox execution modes behind one interface.",
@@ -69,7 +69,7 @@
     "docs"
   ],
   "dependencies": {
-    "@mariozechner/pi-coding-agent": "npm:@earendil-works/pi-coding-agent@0.80.7",
+    "@mariozechner/pi-coding-agent": "npm:@earendil-works/pi-coding-agent@0.84.3",
     "@modelcontextprotocol/sdk": "1.30.0",
     "@radix-ui/react-collapsible": "^1.1.20",
     "@radix-ui/react-dialog": "^1.1.23",
@@ -85,12 +85,12 @@
     "@streamdown/math": "^1.0.2",
     "@streamdown/mermaid": "^1.0.2",
     "@tanstack/react-query": "^5.101.4",
-    "ai": "^7.0.62",
+    "ai": "^7.0.68",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
     "diff": "^9.0.0",
-    "fastify": "^5.11.3",
+    "fastify": "^5.12.1",
     "lucide-react": "^1.31.0",
     "motion": "^13.1.0",
     "nanoid": "^6.0.0",
@@ -100,9 +100,9 @@
     "use-stick-to-bottom": "^1.1.6",
     "yaml": "^2.9.0",
     "zod": "^3.25.76",
-    "@hachej/boring-bash": "0.1.104",
-    "@hachej/boring-sandbox": "0.1.104",
-    "@hachej/boring-ui-kit": "0.1.104"
+    "@hachej/boring-bash": "0.1.107",
+    "@hachej/boring-sandbox": "0.1.107",
+    "@hachej/boring-ui-kit": "0.1.107"
   },
   "devDependencies": {
     "@vercel/sandbox": "3.0.0",
@@ -122,13 +122,14 @@
     "tsx": "^4.23.6",
     "typescript": "^6.0.3",
     "vite": "^8.2.1",
-    "vitest": "^4.1.9"
+    "@earendil-works/pi-ai": "0.84.3",
+    "vitest": "^4.1.11"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "tailwindcss": ">=3.4.0 || >=4.0.0",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.11"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -145,7 +146,7 @@
     }
   },
   "scripts": {
-    "build": "tsup && node ./scripts/build-front-css.mjs && pnpm run build:assert",
+    "build": "tsup && pnpm run build:assert",
     "build:dev": "{ [ -d '../ui/dist' ] || pnpm --filter @hachej/boring-ui-kit build; } && tsup --config tsup.dev.config.ts && node ./scripts/build-front-css.mjs",
     "build:assert": "node ./scripts/assert-build-artifacts.mjs",
     "dev": "tsx src/server/dev.ts",

package/dist/chunk-WSQ5QNIY.js

@@ -1,18 +0,0 @@
-// src/shared/events.ts
-var AGENT_NOT_IMPLEMENTED_UNTIL_T1 = "ERR_NOT_IMPLEMENTED_UNTIL_T1";
-function sessionStreamPath(sessionId) {
-  return `sessions/${sessionId}`;
-}
-var AgentNotImplementedError = class extends Error {
-  code = AGENT_NOT_IMPLEMENTED_UNTIL_T1;
-  constructor(message = "This agent capability is not implemented until T1.") {
-    super(message);
-    this.name = "AgentNotImplementedError";
-  }
-};
-
-export {
-  AGENT_NOT_IMPLEMENTED_UNTIL_T1,
-  sessionStreamPath,
-  AgentNotImplementedError
-};