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

package/dist/harness.d.ts

@@ -13,6 +13,7 @@
  */
 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 { 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

package/dist/harness.js

@@ -13,6 +13,7 @@
  */
 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 { 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";
@@ -70,14 +71,26 @@ export function defaultCapabilities(options = {}) {
         ...(oauthService !== undefined ? { oauthService } : {}),
         ...(options.allowedMcpTransports !== undefined ? { allowedTransports: options.allowedMcpTransports } : {}),
     };
-    // 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 ?? {}),
+    };
+    const pooled = sharedServers === undefined && options.ownEnvironment !== true ? 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).

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.16",
   "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.16"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.87.1"