operon-agents 0.1.0-alpha.15 → 0.1.0-alpha.17

package/dist/app-server/protocol.d.ts

@@ -204,7 +204,7 @@ export interface SessionInvokeResult {
  * This list stays explicit, one entry per reachable operation: it is a security boundary, so a
  * new capability operation should have to be named here to become remotely callable.
  */
-export declare const INVOKABLE_METHODS: readonly ["setModel", "setThinking", "setPermissionMode", "goal.create", "goal.snapshot", "goal.pause", "goal.resume", "goal.cancel", "goal.changeBudget", "plan.setEnabled", "plan.data", "compaction.request", "compaction.pending", "compaction.cancel", "skills.listSkills", "skills.activateSkill", "plugins.summaries", "plugins.info", "plugins.installSummary", "plugins.setEnabled", "plugins.setMcpServerEnabled", "plugins.remove", "plugins.reload", "background.list", "background.readOutput", "background.readOutputDelta", "background.stop", "background.detach", "background.listSubagents", "background.reconcileSubagents", "background.listWorkflows", "background.getWorkflow", "runCommand", "getRecords", "getContextBreakdown", "mcp.list", "mcp.listTools", "mcp.reconnect"];
+export declare const INVOKABLE_METHODS: readonly ["setModel", "setThinking", "setPermissionMode", "goal.create", "goal.snapshot", "goal.pause", "goal.resume", "goal.cancel", "goal.changeBudget", "plan.setEnabled", "plan.data", "compaction.request", "compaction.pending", "compaction.cancel", "skills.listSkills", "skills.activateSkill", "plugins.summaries", "plugins.info", "plugins.installSummary", "plugins.setEnabled", "plugins.setMcpServerEnabled", "plugins.remove", "plugins.reload", "background.list", "background.readOutput", "background.readOutputDelta", "background.stop", "background.detach", "background.listSubagents", "background.reconcileSubagents", "background.listWorkflows", "background.getWorkflow", "runCommand", "getRecords", "getAuditRecords", "getContextBreakdown", "mcp.list", "mcp.listTools", "mcp.reconnect"];
 export type InvokableMethod = (typeof INVOKABLE_METHODS)[number];
 /** `session/event` — an AgentEvent verbatim (already carries `sessionId` + `address`). */
 export type SessionEventParams = AgentEvent;

package/dist/app-server/protocol.js

@@ -95,8 +95,9 @@ export const INVOKABLE_METHODS = [
     // slash commands — the serializable control surface for extensions (cron et al.):
     // per-feature cron RPCs are gone with the capability, /cron rides this instead.
     "runCommand",
-    // conversation log
+    // conversation log, and the audit shard beside it
     "getRecords",
+    "getAuditRecords",
     // context introspection
     "getContextBreakdown",
     // mcp

package/dist/extensions/runtime.d.ts

@@ -83,8 +83,8 @@ export declare class ExtensionRuntime {
     /** Runs one extension's `session` and files its scope. Failure ⇒ skipped, contributions undone. */
     private setupExtension;
     /**
-     * Durable audit trail: replay needs "tool X only exists after record N" to reconstruct the
-     * capability timeline. Rides the `custom` record type — audit-only, ignored by reducers.
+     * Durable audit trail of when this extension joined or left the session — written to the
+     * session's audit shard, which nothing replays from.
      */
     private logChange;
     listTools(): readonly Tool[];

package/dist/extensions/runtime.js

@@ -1,5 +1,5 @@
 import { ServiceUnavailableError, isProbeProperty } from "./services.js";
-import { tagToolSource } from "operon-agents-core";
+import { appendAudit, tagToolSource } from "operon-agents-core";
 /** Decision points block the loop, so they get room to do real work (network, subprocess). */
 const DECISION_TIMEOUT_MS = 30_000;
 /** Observers must not become latency: a slow one is dropped, not waited on. */
@@ -162,8 +162,8 @@ export class ExtensionRuntime {
         }
     }
     /**
-     * Durable audit trail: replay needs "tool X only exists after record N" to reconstruct the
-     * capability timeline. Rides the `custom` record type — audit-only, ignored by reducers.
+     * Durable audit trail of when this extension joined or left the session — written to the
+     * session's audit shard, which nothing replays from.
      */
     async logChange(kind) {
         const extensionId = this.id;
@@ -171,7 +171,7 @@ export class ExtensionRuntime {
         if (!store)
             return;
         try {
-            await store.appendRecord({ type: "custom", name: `extensions.${kind}`, data: { extensionId } });
+            await appendAudit(store, { type: "custom", name: `extensions.${kind}`, data: { extensionId } });
         }
         catch (error) {
             await this.warn(extensionId, `failed to journal extension ${kind}: ${messageOf(error)}`);
@@ -697,7 +697,7 @@ export class ExtensionRuntime {
         return this.revocable(extensionId, {
             steer: (content, options) => runtime.enqueue(extensionId, content, "steering", options?.metadata),
             followUp: (content, options) => runtime.enqueue(extensionId, content, "follow_up", options?.metadata),
-            // Journaled by the engine into the main conversation as `extension:<id>:<name>`, and seen
+            // Written by the engine to the session's audit shard as `extension:<id>:<name>`, and seen
             // by `records()` straight away.
             record: (name, data) => {
                 const session = runtime.session;

package/dist/harness.d.ts

@@ -11,8 +11,9 @@
  * low-level "assemble it yourself / stateless server" path, import from
  * `operon-agents/core` instead.
  */
-import { type AgentEvent, type EventPublicationMode, type TelemetryService, type AgentEventListener, type AgentInput, SessionProjection, type SessionSnapshot, type SnapshotOptions, type DirectoryEntry, type ProjectionObservation, type ProjectionListener, type ApprovalRequest, type ApprovalResponse, type Capability, type InterruptAnswer, type ChatModel, ListenerSink, type PermissionManagerOptions, type PermissionMode, type PendingRunInterrupt, type QuestionRequest, type QuestionResult, type Responder, type RunHandle, type RunResult, type SessionStore, type SessionHandle, type SessionSummary, type ListSessionsFilter, type OpenSessionOptions, type DeleteSessionOptions, type ThinkingLevel, type Tool, type SteerMessage, type SteerOptions, type SteerOrigin, type SteerReceipt, Agent, Runner, Session, McpOAuthService, SkillRegistry, type HookDef, type McpServerConfig, type McpTransportKind, type PluginManager, type ApprovalRequestOptions, type Environment, type EnvironmentFactory, type SessionRepository, type ResolvedAgentProfile, type SubagentProvider } from "operon-agents-core";
+import { type AgentEvent, type EventPublicationMode, type TelemetryService, type AgentEventListener, type AgentInput, SessionProjection, type SessionSnapshot, type SnapshotOptions, type DirectoryEntry, type ProjectionObservation, type ProjectionListener, type ApprovalRequest, type ApprovalResponse, type Capability, type InterruptAnswer, type ChatModel, ListenerSink, type PermissionManagerOptions, type PermissionMode, type PendingRunInterrupt, type QuestionRequest, type QuestionResult, type Responder, type RunHandle, type RunResult, type SessionStore, type SessionHandle, type SessionSummary, type ListSessionsFilter, type OpenSessionOptions, type DeleteSessionOptions, type ThinkingLevel, type Tool, type SteerMessage, type SteerOptions, type SteerOrigin, type SteerReceipt, Agent, Runner, Session, McpOAuthService, SkillRegistry, type HookDef, type McpServerConfig, type McpTransportKind, type McpCredentialProvider, type PluginManager, type ApprovalRequestOptions, type Environment, type EnvironmentFactory, type SessionRepository, type ResolvedAgentProfile, type SubagentProvider } from "operon-agents-core";
 import type { SkillsService, CompactionService, BackgroundManager, McpServersHandle, GoalStore, PlanMode, Logger, ModelRuntime, TracingProcessor } from "operon-agents-core";
+import { type WorkspaceMcpPool } from "./workspace-mcp.ts";
 import { HarnessExtensionManager, ServiceRegistry, type ExtensionDefinition, type ServiceOptions } from "./extensions/index.ts";
 import { type CommandResult, type TodoItem } from "operon-agents-core";
 export type ApprovalHandler = (request: ApprovalRequest, options?: ApprovalRequestOptions) => Promise<ApprovalResponse> | ApprovalResponse;
@@ -60,6 +61,19 @@ export interface DefaultCapabilitiesOptions {
      * session's wins for this session only. Built, connected and shut down with the session.
      */
     readonly sessionMcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Share MCP connections per DIRECTORY instead of building them per session: every server this
+     * bundle would otherwise connect for the session — `mcpServers`, the plugins', and `servers`
+     * here (the directory's own, e.g. its `mcp.json`) — is borrowed from `pool` under `workDir`, so
+     * the sessions open in one directory run one set. `sessionMcpServers` stay the session's own,
+     * layered over it. Ignored when `shared.mcpServers` is set (a process-wide set already covers
+     * every directory) and for a session on its own environment. See {@link WorkspaceMcpPool}.
+     */
+    readonly workspaceMcp?: {
+        readonly pool: WorkspaceMcpPool;
+        readonly workDir: string;
+        readonly servers?: Record<string, McpServerConfig>;
+    };
     /**
      * Installed-plugin manager. When set, the framework self-drives the plugin's contributions into
      * this capability set: its skills (merged into the skills capability), its MCP servers (merged
@@ -93,6 +107,17 @@ export interface DefaultCapabilitiesOptions {
      * to run is the host's statement, not the kernel's.
      */
     readonly allowedMcpTransports?: readonly McpTransportKind[];
+    /** Credentials the host hands out per connect for this session's http MCP servers. See
+     *  `McpCredentialProvider`. */
+    readonly mcpCredentials?: McpCredentialProvider;
+    /**
+     * The session belongs to one tenant among many (a managed host's default): nothing the process
+     * shares reaches it — no process-wide MCP set, skill scan, OAuth service or directory pool —
+     * MCP runs over http only, and no server may read its token from the process environment.
+     * Each is refused rather than skipped where skipping would hide a misconfiguration. See
+     * docs/server-profile.md.
+     */
+    readonly strictIsolation?: boolean;
 }
 /**
  * The standard coding-agent capability bundle (goal / plan / todo / skills /
@@ -286,6 +311,11 @@ export interface SessionCapabilityContext {
     /** The session brought its own environment (`{ environment }` on this open): harness-shared objects
      *  derived from the harness's environment (the skill scan) do not apply to it. */
     readonly ownEnvironment: boolean;
+    /** {@link OpenSessionOptionsBase.mcpCredentials} for this open. */
+    readonly mcpCredentials?: McpCredentialProvider;
+    /** {@link OpenSessionOptionsBase.strictIsolation} for this open. A custom factory owns honouring
+     *  it the way `defaultCapabilities` does. */
+    readonly strictIsolation: boolean;
 }
 /**
  * Options common to every way of opening a session.
@@ -313,6 +343,16 @@ interface OpenSessionOptionsBase<TContext = unknown> {
      * shared one for this session; a custom factory can decide otherwise.
      */
     readonly mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Where this session's http MCP servers get their credentials, asked on every connect: the
+     * seam a host builds a per-user vault on. Not persisted — a resume passes it again.
+     */
+    readonly mcpCredentials?: McpCredentialProvider;
+    /**
+     * This session is one tenant's among many: see `DefaultCapabilitiesOptions.strictIsolation`.
+     * A managed host's worker sets it on every open unless it runs single-tenant.
+     */
+    readonly strictIsolation?: boolean;
     /**
      * Per-session argument for each registered extension, by extension id — handed to that
      * extension's `session(api, ctx)` as `ctx.params`. A value of `false` skips the extension for
@@ -587,6 +627,7 @@ export declare class HarnessSession<TContext = unknown> {
     /** PROBE tier: absent without an MCP capability. */
     get mcp(): McpServersHandle | undefined;
     getRecords(...args: Parameters<Session["getRecords"]>): ReturnType<Session["getRecords"]>;
+    getAuditRecords(): ReturnType<Session["getAuditRecords"]>;
     getContextBreakdown(): ReturnType<Session["getContextBreakdown"]>;
     /** Where this session's tools run. A host uses it to run a command in the same place the agent
      *  does — one shell, one filesystem, one working directory. */
@@ -675,6 +716,12 @@ export declare class Harness<TContext = unknown> {
     /** The extension whose `harness` is running right now — its `createSession` must refuse. */
     private runningCreate;
     constructor(options: HarnessOptions<TContext>);
+    /**
+     * Which session-facing parts the `harness` hook built for the whole process — what a
+     * multi-tenant host must not have, since every session on the process would share them.
+     * Infrastructure (repository, logger, model runtime) is not listed: sharing it is the point.
+     */
+    processSharedParts(): Promise<readonly ("mcpServers" | "oauthService" | "skillRegistry")[]>;
     /** The session repository, once the `harness` hook has had its say. */
     private repository;
     /** The fallback repository, built once so two opens share one in-memory store. */

package/dist/harness.js

@@ -11,8 +11,9 @@
  * low-level "assemble it yourself / stateless server" path, import from
  * `operon-agents/core` instead.
  */
-import { readLog, SessionProjection, ListenerSink, agentEventFromRecord, newAgentEventId, Agent, buildAgentFromProfile, INTERRUPTION_STATE_KEY, flattenPendingInterrupts, parseInterruptionState, Runner, Session, emptyUsage, isGuardrailTripwireError, askUserQuestionTool, backgroundCapability, compactionCapability, filesystemTools, goalCapability, LocalEnvironment, McpOAuthService, MemorySessionRepository, SessionRepositoryNotFoundError, planCapability, skillsCapability, SkillRegistry, mcpServersCapability, pluginsCapability, userHooksCapability, taskCapability, workflowCapability, DEFAULT_AGENT_PROFILES, DEFAULT_AGENT_PROFILE_NAME, DEFAULT_SUBAGENT_NAMES, profileSubagentProvider, DEFAULT_ADDRESS, envLogger, noopLogger, } from "operon-agents-core";
+import { readSessionTails, SessionProjection, ListenerSink, agentEventFromRecord, newAgentEventId, Agent, buildAgentFromProfile, INTERRUPTION_STATE_KEY, flattenPendingInterrupts, parseInterruptionState, Runner, Session, emptyUsage, isGuardrailTripwireError, askUserQuestionTool, backgroundCapability, compactionCapability, filesystemTools, goalCapability, LocalEnvironment, McpOAuthService, MemorySessionRepository, SessionRepositoryNotFoundError, planCapability, skillsCapability, SkillRegistry, mcpServersCapability, pluginsCapability, userHooksCapability, taskCapability, workflowCapability, DEFAULT_AGENT_PROFILES, DEFAULT_AGENT_PROFILE_NAME, DEFAULT_SUBAGENT_NAMES, profileSubagentProvider, DEFAULT_ADDRESS, envLogger, noopLogger, } from "operon-agents-core";
 import { mkdirSync } from "node:fs";
+import { workspaceMcpCapability } from "./workspace-mcp.js";
 import { join } from "node:path";
 import { extensionCapability, extensionRuntimeOf, extensionsCapability, HarnessExtensionManager, ServiceRegistry, stageDefinition } from "./extensions/index.js";
 import { createExtensionCommandRegistry } from "operon-agents-core";
@@ -41,9 +42,15 @@ const EXTENSION_PARAMS_STATE_KEY = "extensions:params";
 export function defaultCapabilities(options = {}) {
     const manager = options.pluginManager ?? options.shared?.pluginManager;
     // A session on its own environment ignores the process-wide registry: it was scanned elsewhere.
-    const sharedSkills = options.ownEnvironment === true ? undefined : options.shared?.skillRegistry;
-    const sharedServers = options.ownEnvironment === true ? undefined : options.shared?.mcpServers;
-    const oauthService = options.oauthService ?? options.shared?.oauthService;
+    const strict = options.strictIsolation === true;
+    // A session on its own environment, or one tenant among many, gets nothing the process shares.
+    const isolated = strict || options.ownEnvironment === true;
+    const sharedSkills = isolated ? undefined : options.shared?.skillRegistry;
+    const sharedServers = isolated ? undefined : options.shared?.mcpServers;
+    const oauthService = options.oauthService ?? (strict ? undefined : options.shared?.oauthService);
+    const allowedMcpTransports = strict
+        ? (options.allowedMcpTransports ?? ["http", "stdio"]).filter((kind) => kind === "http")
+        : options.allowedMcpTransports;
     // Shared registry so the plugin session-start injector can render a skill the skills capability
     // loaded (its roots include the plugin skill dirs below). A process-wide registry is scanned
     // once for every session; a session-level one is scanned here.
@@ -68,16 +75,37 @@ export function defaultCapabilities(options = {}) {
     const sessionMcp = options.sessionMcpServers ?? {};
     const mcpOptions = {
         ...(oauthService !== undefined ? { oauthService } : {}),
-        ...(options.allowedMcpTransports !== undefined ? { allowedTransports: options.allowedMcpTransports } : {}),
+        ...(allowedMcpTransports !== undefined ? { allowedTransports: allowedMcpTransports } : {}),
+        ...(options.mcpCredentials !== undefined ? { credentials: options.mcpCredentials } : {}),
     };
-    // With process-shared connections, the capability is a VIEW over them and `configs` is this
-    // session's overlay. Without, everything this session sees is its own — session servers last,
-    // so the same name still resolves to the session's.
-    const mcpConfigs = sharedServers !== undefined
-        ? sessionMcp
-        : { ...(options.mcpServers ?? {}), ...(manager?.mcpServerConfigs() ?? {}), ...sessionMcp };
-    if (sharedServers !== undefined || Object.keys(mcpConfigs).length > 0) {
-        capabilities.push(mcpServersCapability(mcpConfigs, { ...mcpOptions, ...(sharedServers !== undefined ? { sharedServers } : {}) }));
+    // Everything this session would connect that is not private to it: the directory's servers
+    // last, so they win over a same-named plugin server the way they did as a session overlay.
+    const shareable = {
+        ...(options.mcpServers ?? {}),
+        ...(manager?.mcpServerConfigs() ?? {}),
+        ...(options.workspaceMcp?.servers ?? {}),
+    };
+    if (strict) {
+        // The process environment has no tenant boundary: a token read from it is every tenant's.
+        for (const [name, config] of Object.entries({ ...shareable, ...sessionMcp })) {
+            if (config.bearerTokenEnvVar !== undefined) {
+                throw new Error(`MCP server "${name}" reads its token from the process environment (bearerTokenEnvVar), which every tenant on this host shares; hand it out per session with mcpCredentials instead.`);
+            }
+        }
+    }
+    const pooled = sharedServers === undefined && !isolated ? options.workspaceMcp : undefined;
+    if (pooled !== undefined && Object.keys(shareable).length > 0) {
+        // Borrowed per directory: the capability views the pool's set, `sessionMcp` is its overlay.
+        capabilities.push(workspaceMcpCapability({ pool: pooled.pool, workDir: pooled.workDir, servers: shareable, overlay: sessionMcp, overlayOptions: mcpOptions }));
+    }
+    else {
+        // With process-shared connections, the capability is a VIEW over them and `configs` is this
+        // session's overlay. Without, everything this session sees is its own — session servers last,
+        // so the same name still resolves to the session's.
+        const mcpConfigs = sharedServers !== undefined ? sessionMcp : { ...shareable, ...sessionMcp };
+        if (sharedServers !== undefined || Object.keys(mcpConfigs).length > 0) {
+            capabilities.push(mcpServersCapability(mcpConfigs, { ...mcpOptions, ...(sharedServers !== undefined ? { sharedServers } : {}) }));
+        }
     }
     // Plugins: load the manager + render the plugin's session-start skill from the shared registry
     // (skills opens before this, so by injection time the registry holds the plugin skills).
@@ -685,6 +713,9 @@ export class HarnessSession {
     getRecords(...args) {
         return this.core.getRecords(...args);
     }
+    getAuditRecords() {
+        return this.core.getAuditRecords();
+    }
     // ── context introspection — where the model's window is spent, as of the last turn ──
     getContextBreakdown() {
         return this.core.getContextBreakdown();
@@ -907,6 +938,22 @@ export class Harness {
         // Surfaced to whoever opens a session; never an unhandled rejection on its own.
         this.sharedReady.catch(() => undefined);
     }
+    /**
+     * Which session-facing parts the `harness` hook built for the whole process — what a
+     * multi-tenant host must not have, since every session on the process would share them.
+     * Infrastructure (repository, logger, model runtime) is not listed: sharing it is the point.
+     */
+    async processSharedParts() {
+        await this.sharedReady;
+        const parts = [];
+        if (this.parts.mcpServers !== undefined)
+            parts.push("mcpServers");
+        if (this.parts.oauthService !== undefined)
+            parts.push("oauthService");
+        if (this.parts.skillRegistry !== undefined)
+            parts.push("skillRegistry");
+        return parts;
+    }
     /** The session repository, once the `harness` hook has had its say. */
     async repository() {
         await this.sharedReady;
@@ -1366,7 +1413,17 @@ export class Harness {
     }
     /** Resolve the capability set for one session — the `session` hook, called fresh every time. */
     async resolveCapabilities(ctx, params = {}) {
-        const base = this.options.session !== undefined ? await this.options.session(ctx) : defaultCapabilities({ shared: this.parts });
+        // A session on its own environment (a sandbox) does not get the process's MCP connections or
+        // skill scan: both describe the HARNESS's machine, not the one this session's tools run on.
+        const base = this.options.session !== undefined
+            ? await this.options.session(ctx)
+            : defaultCapabilities({
+                shared: this.parts,
+                ownEnvironment: ctx.ownEnvironment,
+                strictIsolation: ctx.strictIsolation,
+                ...(ctx.mcpServers !== undefined ? { sessionMcpServers: ctx.mcpServers } : {}),
+                ...(ctx.mcpCredentials !== undefined ? { mcpCredentials: ctx.mcpCredentials } : {}),
+            });
         // Every definition registered on this harness: by value (`extensions`, harness halves
         // included — their per-session `session` is mounted here like any other), then from files.
         const extensions = [...this.valueDefs.values(), ...(this.extensions?.sessionDefinitions() ?? [])];
@@ -1446,12 +1503,13 @@ export class Harness {
             // Environment: this call's override → the harness's default → a LocalEnvironment at the
             // session's own workDir. The session only OPERATES a caller-supplied environment.
             const environment = opts.environment ?? this.parts.environment ?? new LocalEnvironment(workDir);
-            // ONE open-time log read, shared: the projection seeds from it, and Session.open
-            // receives it as `preloadedLog` so its capability restore + context pre-build fold the
-            // same records — same IO, and the same `Message` objects (no second parsed copy).
+            // ONE open-time log read, shared: every shard from its newest checkpoint on (each
+            // checkpoint carries the history and lifecycle before it). The projection seeds from it,
+            // and Session.open receives it as `preloadedLog` so its capability restore + context
+            // pre-build fold the same records — same IO, and the same `Message` objects.
             // Attach still happens BEFORE Session.open: no events flow yet, so the seed cannot
             // race the subscription, and anything capabilities emit during open is already folded.
-            let preloadedLog = await readLog(store);
+            let preloadedLog = await readSessionTails(store);
             // A fresh session has an empty log; anything else is a reopen. Telemetry is the only reader.
             const resumed = preloadedLog.length > 0;
             projection = await SessionProjection.attach({ id, store, events }, preloadedLog);
@@ -1465,7 +1523,9 @@ export class Harness {
                 sessionId: id,
                 workDir,
                 ownEnvironment: opts.environment !== undefined,
+                strictIsolation: opts.strictIsolation === true,
                 ...(opts.mcpServers !== undefined ? { mcpServers: opts.mcpServers } : {}),
+                ...(opts.mcpCredentials !== undefined ? { mcpCredentials: opts.mcpCredentials } : {}),
             }, params);
             // Everything the session runs on, by value. The repository owns the store's lifetime.
             core = await Session.open({
@@ -1582,7 +1642,7 @@ export class Harness {
 export async function closeOrphanedTurns(sessionId, store) {
     if ((await store.getState(INTERRUPTION_STATE_KEY)) !== null)
         return [];
-    const projection = await SessionProjection.attach({ id: sessionId, store, events: new ListenerSink() }, await readLog(store));
+    const projection = await SessionProjection.attach({ id: sessionId, store, events: new ListenerSink() }, await readSessionTails(store));
     const records = await closeOrphanedProjectionFrames(sessionId, store, projection);
     const events = [];
     for (const record of records) {

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export * from "./extensions/index.ts";
 export * from "./cron/index.ts";
 export * from "./providers.ts";
 export * from "./local.ts";
+export * from "./workspace-mcp.ts";
 export * from "operon-agents-core";
 export * as llm from "operon-agents-core/llm";
 export * as mcp from "operon-agents-core/mcp";

package/dist/index.js

@@ -20,6 +20,8 @@ export * from "./cron/index.js";
 export * from "./providers.js";
 // Deployment composition roots: local vs server injection presets (Invariant 7 — no engine "mode").
 export * from "./local.js";
+// Per-directory MCP sharing for hosts that open many sessions in one folder (a desktop app).
+export * from "./workspace-mcp.js";
 // The curated core engine, re-exported for convenience; `operon-agents/core` is the dedicated
 // primitives entrypoint.
 export * from "operon-agents-core";

package/dist/workspace-mcp.d.ts

@@ -0,0 +1,62 @@
+import { type Capability, type McpServerConfig, type McpServersCapabilityOptions, type McpServersHandle } from "operon-agents-core";
+/** How long a directory's connections outlive its last session by default: five minutes. */
+export declare const DEFAULT_WORKSPACE_MCP_IDLE_MS: number;
+export interface WorkspaceMcpPoolOptions extends Omit<McpServersCapabilityOptions, "sharedServers"> {
+    /**
+     * How long a directory's connections stay up after the last session using them closes, in ms.
+     * A session opened there within the window reuses them. `0` closes them at once. Defaults to
+     * {@link DEFAULT_WORKSPACE_MCP_IDLE_MS}.
+     */
+    readonly idleMs?: number;
+}
+/** One session's hold on a directory's connections. `release` is idempotent. */
+export interface WorkspaceMcpLease {
+    readonly servers: McpServersHandle;
+    release(): Promise<void>;
+}
+export declare class WorkspaceMcpPool {
+    private readonly options;
+    /** The generation a NEW borrow in each directory gets. */
+    private readonly current;
+    /** Every generation not yet shut down — current ones and retired ones still on loan. */
+    private readonly live;
+    private closing;
+    constructor(options?: WorkspaceMcpPoolOptions);
+    /** Directories whose connections are currently up (on loan or idling). */
+    get size(): number;
+    /**
+     * Borrow the connections for `workDir`, building them if this directory has none for exactly
+     * these `configs`. Resolves once they have connected — fault-isolated, so a server that failed
+     * is a status on the handle, never a rejection. Rejects for what `createMcpServers` refuses
+     * up front (a transport this host does not run), before anything is built.
+     */
+    acquire(workDir: string, configs: Record<string, McpServerConfig>): Promise<WorkspaceMcpLease>;
+    /** Shut every directory's connections down, on loan or not. Later borrows throw. Idempotent. */
+    close(): Promise<void>;
+    /** The last lease came back: close a retired generation now, a current one after the grace. */
+    private idle;
+    private shutdown;
+    private assertOpen;
+}
+export interface WorkspaceMcpCapabilityOptions {
+    readonly pool: WorkspaceMcpPool;
+    /** The session's working directory — the key the connections are shared under. */
+    readonly workDir: string;
+    /** The servers every session in `workDir` shares. */
+    readonly servers: Record<string, McpServerConfig>;
+    /** The session's own servers, layered over the shared ones (same name: the session's wins). */
+    readonly overlay?: Record<string, McpServerConfig>;
+    /**
+     * Options for the overlay's connections; the pooled ones were configured on the pool. Its
+     * `allowedTransports` is enforced on BOTH — the host's statement of what it runs does not get
+     * weaker because a server happens to be shared.
+     */
+    readonly overlayOptions?: Omit<McpServersCapabilityOptions, "sharedServers">;
+}
+/**
+ * The `mcp` capability over a directory's pooled connections: borrows them at `openSession`,
+ * gives them back at `closeSession` (session close or detach alike). In between it is exactly
+ * `mcpServersCapability` viewing a shared set — same tools, same `session.mcp`, same overlay.
+ */
+export declare function workspaceMcpCapability(options: WorkspaceMcpCapabilityOptions): Capability;
+//# sourceMappingURL=workspace-mcp.d.ts.map

package/dist/workspace-mcp.js

@@ -0,0 +1,222 @@
+/**
+ * MCP connections shared by every session opened in the same directory.
+ *
+ * A desktop host keeps one process up all day and opens many conversations in one project at
+ * once. Each of them used to connect the project's MCP servers again — an stdio server is a child
+ * process, so N chats in one folder meant N copies of every server. The pool keys one set of
+ * connections by the directory's real path and lends it to each session that opens there.
+ *
+ * This is deliberately NOT a lifetime tier of the engine (that was the workspace `Scope`, removed
+ * for the rules it cost). Core still knows two lifetimes, the process and the session; the pool
+ * is a host-side object the session hook hands to `defaultCapabilities`, and the MCP capability
+ * borrows from it at `openSession` and gives back at `closeSession`. Because the borrowing lives
+ * inside the capability's own open/close, a failed open undoes it like everything else the
+ * session opened — no hold is taken anywhere the session cannot see.
+ *
+ * Lifetime of one directory's set, a "generation":
+ *  - built on the first borrow, connected once; concurrent borrows share that one connect;
+ *  - kept while any session holds it, then for `idleMs` more, so closing the last chat and
+ *    starting the next one does not respawn every server;
+ *  - replaced, not mutated, when a borrow arrives with a different configuration (an edited
+ *    `mcp.json`, a plugin enabled): new sessions get a new generation, the sessions already
+ *    holding the old one keep it, and it closes when the last of them gives it back.
+ *
+ * Sharing is the point, so it is total: two sessions in one directory drive the SAME server.
+ * One with state of its own (a browser) is therefore shared state between them; a reconnect or an
+ * OAuth sign-in in one session is seen by all. A server that must be private belongs in the
+ * session's own `mcpServers`, which are layered over the shared set and never pooled.
+ */
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { createMcpServers, mcpServersCapability, McpTransportNotPermittedError, } from "operon-agents-core";
+/** How long a directory's connections outlive its last session by default: five minutes. */
+export const DEFAULT_WORKSPACE_MCP_IDLE_MS = 5 * 60_000;
+export class WorkspaceMcpPool {
+    options;
+    /** The generation a NEW borrow in each directory gets. */
+    current = new Map();
+    /** Every generation not yet shut down — current ones and retired ones still on loan. */
+    live = new Set();
+    closing;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Directories whose connections are currently up (on loan or idling). */
+    get size() {
+        return this.current.size;
+    }
+    /**
+     * Borrow the connections for `workDir`, building them if this directory has none for exactly
+     * these `configs`. Resolves once they have connected — fault-isolated, so a server that failed
+     * is a status on the handle, never a rejection. Rejects for what `createMcpServers` refuses
+     * up front (a transport this host does not run), before anything is built.
+     */
+    async acquire(workDir, configs) {
+        this.assertOpen();
+        const key = await canonicalDir(workDir);
+        this.assertOpen();
+        const fingerprint = fingerprintOf(configs);
+        let generation = this.current.get(key);
+        if (generation !== undefined && generation.fingerprint !== fingerprint) {
+            this.current.delete(key);
+            if (generation.leases === 0)
+                void this.shutdown(generation);
+            generation = undefined;
+        }
+        if (generation === undefined) {
+            const { idleMs: _idleMs, ...serverOptions } = this.options;
+            const servers = createMcpServers(configs, serverOptions);
+            // Pooled connections belong to no session: their failures reach each borrower through
+            // `onStatusChange`, which the MCP capability subscribes to when it opens.
+            generation = { key, fingerprint, servers, ready: servers.connect({ sessionId: "" }), leases: 0 };
+            this.current.set(key, generation);
+            this.live.add(generation);
+        }
+        const held = generation;
+        held.leases += 1;
+        if (held.idle !== undefined) {
+            clearTimeout(held.idle);
+            held.idle = undefined;
+        }
+        let released = false;
+        const release = async () => {
+            if (released)
+                return;
+            released = true;
+            held.leases -= 1;
+            if (held.leases === 0)
+                await this.idle(held);
+        };
+        try {
+            await held.ready;
+        }
+        catch (error) {
+            await release();
+            throw error;
+        }
+        return { servers: held.servers, release };
+    }
+    /** Shut every directory's connections down, on loan or not. Later borrows throw. Idempotent. */
+    close() {
+        this.closing ??= (async () => {
+            this.current.clear();
+            await Promise.allSettled([...this.live].map((generation) => this.shutdown(generation)));
+        })();
+        return this.closing;
+    }
+    /** The last lease came back: close a retired generation now, a current one after the grace. */
+    async idle(generation) {
+        const idleMs = this.options.idleMs ?? DEFAULT_WORKSPACE_MCP_IDLE_MS;
+        if (this.current.get(generation.key) !== generation || idleMs <= 0) {
+            if (this.current.get(generation.key) === generation)
+                this.current.delete(generation.key);
+            await this.shutdown(generation);
+            return;
+        }
+        generation.idle = setTimeout(() => {
+            generation.idle = undefined;
+            if (generation.leases !== 0 || this.current.get(generation.key) !== generation)
+                return;
+            this.current.delete(generation.key);
+            void this.shutdown(generation);
+        }, idleMs);
+        // An idling set must not be what keeps the process alive.
+        generation.idle.unref?.();
+    }
+    shutdown(generation) {
+        if (generation.idle !== undefined) {
+            clearTimeout(generation.idle);
+            generation.idle = undefined;
+        }
+        this.live.delete(generation);
+        generation.closed ??= generation.ready.catch(() => undefined).then(() => generation.servers.shutdown());
+        return generation.closed;
+    }
+    assertOpen() {
+        if (this.closing !== undefined)
+            throw new Error("WorkspaceMcpPool is closed");
+    }
+}
+/**
+ * The `mcp` capability over a directory's pooled connections: borrows them at `openSession`,
+ * gives them back at `closeSession` (session close or detach alike). In between it is exactly
+ * `mcpServersCapability` viewing a shared set — same tools, same `session.mcp`, same overlay.
+ */
+export function workspaceMcpCapability(options) {
+    const allowed = options.overlayOptions?.allowedTransports;
+    if (allowed !== undefined) {
+        for (const [name, config] of Object.entries(options.servers)) {
+            if (config.enabled !== false && !allowed.includes(config.transport)) {
+                throw new McpTransportNotPermittedError(name, config.transport, allowed);
+            }
+        }
+    }
+    let lease;
+    /** The borrowed set while a lease is held; the view below is empty without one. */
+    let bound;
+    const view = {
+        list: () => bound?.list() ?? [],
+        listTools: async (name) => (bound !== undefined ? bound.listTools(name) : []),
+        reconnect: async (name) => {
+            if (bound === undefined)
+                throw new Error(`Unknown MCP server: ${name}`);
+            await bound.reconnect(name);
+        },
+        onStatusChange: (listener) => bound?.onStatusChange(listener) ?? (() => { }),
+        toolProviders: () => bound?.toolProviders() ?? [],
+        // The pool connects and shuts down; a viewer does neither.
+        connect: async () => { },
+        shutdown: async () => { },
+    };
+    const inner = mcpServersCapability(options.overlay ?? {}, { ...(options.overlayOptions ?? {}), sharedServers: view });
+    const giveBack = async () => {
+        const held = lease;
+        lease = undefined;
+        bound = undefined;
+        await held?.release();
+    };
+    return {
+        name: inner.name,
+        contract: inner.contract,
+        ...(inner.toolProviders !== undefined ? { toolProviders: inner.toolProviders } : {}),
+        get service() {
+            return inner.service;
+        },
+        openSession: async (ctx) => {
+            lease = await options.pool.acquire(options.workDir, options.servers);
+            bound = lease.servers;
+            try {
+                await inner.openSession?.(ctx);
+            }
+            catch (error) {
+                await giveBack();
+                throw error;
+            }
+        },
+        closeSession: async (reason) => {
+            try {
+                await inner.closeSession?.(reason);
+            }
+            finally {
+                await giveBack();
+            }
+        },
+    };
+}
+/** The directory's real path, so `./proj`, `/tmp/proj` and a symlink to it share one set. */
+async function canonicalDir(workDir) {
+    const absolute = resolve(workDir);
+    try {
+        return await realpath(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+/** Order-independent identity of a configuration: same servers, same settings, same string. */
+function fingerprintOf(configs) {
+    return JSON.stringify(configs, (_key, value) => value !== null && typeof value === "object" && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : value);
+}
+//# sourceMappingURL=workspace-mcp.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "operon-agents",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.17",
   "description": "Public SDK entrypoint for building agents.",
   "type": "module",
   "engines": {
@@ -74,7 +74,7 @@
     "zod": "^4.4.3",
     "smol-toml": "^1.6.1",
     "@earendil-works/pi-ai": "0.87.1",
-    "operon-agents-core": "0.1.0-alpha.15"
+    "operon-agents-core": "0.1.0-alpha.17"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.87.1"