operon-agents 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/index.d.ts

@@ -14,11 +14,14 @@
 export * from "./harness.ts";
 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";
 export * as protocol from "operon-agents-core/protocol";
 export * as tools from "operon-agents-core/tools";
 export * as tracing from "operon-agents-core/tracing";
+export * as telemetry from "./telemetry.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -16,8 +16,12 @@ export * from "./harness.js";
 // Core supplies the primitives they are built on (Capability / LoopHooks / ToolFilter / Injector).
 export * from "./extensions/index.js";
 export * from "./cron/index.js";
+// Model providers the host configures (a self-hosted endpoint, a gateway) — see providers.ts.
+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";
@@ -26,4 +30,5 @@ export * as mcp from "operon-agents-core/mcp";
 export * as protocol from "operon-agents-core/protocol";
 export * as tools from "operon-agents-core/tools";
 export * as tracing from "operon-agents-core/tracing";
+export * as telemetry from "./telemetry.js";
 //# sourceMappingURL=index.js.map

package/dist/internal.d.ts

@@ -6,4 +6,5 @@
  * No stability guarantees — prefer the main `operon-agents` surface.
  */
 export * from "operon-agents-core/internal";
+export { setHarnessCloseTimeoutsForTest } from "./harness.ts";
 //# sourceMappingURL=internal.d.ts.map

package/dist/internal.js

@@ -6,4 +6,5 @@
  * No stability guarantees — prefer the main `operon-agents` surface.
  */
 export * from "operon-agents-core/internal";
+export { setHarnessCloseTimeoutsForTest } from "./harness.js";
 //# sourceMappingURL=internal.js.map

package/dist/local.d.ts

@@ -1,24 +1,41 @@
-import { type HookDef, type McpServerConfig, type PluginManager } from "operon-agents-core";
-import { type CreateSessionOptions, type Harness, type HarnessOptions, type HarnessSession } from "./harness.ts";
+import type { ModelRuntime } from "operon-agents-core";
+import { type HookDef, type Logger, type McpServerConfig, type PluginManager } from "operon-agents-core";
+import { type Harness, type HarnessOptions } from "./harness.ts";
 export interface LocalDeploymentOptions<TContext = unknown> extends HarnessOptions<TContext> {
     /**
      * App home root — sessions (`<homeDir>/sessions`), MCP creds, logs, and disk-discovered agent
      * profiles all live under it. Defaults to `~/.agents`. (`homeDir` is a local-deployment concept;
-     * the harness itself only knows `repository`.)
+     * the harness itself only knows `HarnessParts.sessionRepository`.)
      */
     readonly homeDir?: string;
-    /** Workspace MCP servers to expose. */
+    /** MCP servers to expose, shared by every session of the harness. */
     readonly mcpServers?: Record<string, McpServerConfig>;
-    /** Installed-plugin manager, if any. */
+    /** Installed-plugin manager, if any. Loaded once here, then handed out as `HarnessParts.pluginManager`. */
     readonly pluginManager?: PluginManager;
     /** Shell hooks from config (`config.hooks`), projected as HookDefs. */
     readonly hooks?: readonly HookDef[];
     /** Discover agent profiles from disk (`<homeDir>/agents` + `<cwd>/.agents/agents`). Default true. */
     readonly loadDiskProfiles?: boolean;
+    /** Diagnostics logger. Defaults to a rotating file under `<homeDir>/logs`. */
+    readonly logger?: Logger;
+    /** Context budget for the default compaction capability. */
+    readonly maxContextTokens?: number;
+    /**
+     * The model runtime this harness resolves providers through. Pass the same one the host used to
+     * build its `ChatModel` (see `createModelRuntimeFromConfig`) when a model lives on a configured
+     * endpoint — otherwise the two registries disagree about what exists. Omitted, the harness builds
+     * one from `<homeDir>/providers.toml` itself.
+     */
+    readonly modelRuntime?: ModelRuntime;
+    /** Skip reading `<homeDir>/providers.toml` entirely. Ignored when `modelRuntime` is given. */
+    readonly loadConfiguredProviders?: boolean;
 }
-/** Build `HarnessOptions` wired for a local, single-machine deployment. */
+/** Build `HarnessOptions` wired for a local, single-environment deployment. */
 export declare function localHarnessOptions<TContext>(options: LocalDeploymentOptions<TContext>): Promise<HarnessOptions<TContext>>;
+/**
+ * The local entry point: one harness per process, one `createSession()` per conversation on it.
+ * Its `close()` closes those sessions and then the harness scope — the cron timer, the workspace
+ * MCP connections and the rotating log handle all live there, so nothing else tears them down.
+ */
 export declare function createLocalHarness<TContext = unknown>(options: LocalDeploymentOptions<TContext>): Promise<Harness<TContext>>;
-/** Convenience: a local harness with one session opened and ready to `prompt()`. */
-export declare function createLocalSession<TContext = unknown>(options: LocalDeploymentOptions<TContext>, session?: CreateSessionOptions<TContext>): Promise<HarnessSession<TContext>>;
 //# sourceMappingURL=local.d.ts.map

package/dist/local.js

@@ -1,58 +1,128 @@
 /**
- * The local composition root — every convention a single-machine, single-operator app runs on,
- * bundled in one place: disk sessions under `<homeDir>/sessions`, the local machine, a rotating
+ * The local composition root — every convention a single-environment, single-operator app runs on,
+ * bundled in one place: disk sessions under `<homeDir>/sessions`, the local environment, a rotating
  * file log, file-backed MCP credentials, disk-discovered agent profiles, and the cron extension.
  *
- * There is deliberately no server counterpart. A hosted deployment injects its own repository,
- * machine, logger and credential store, and those choices belong to the host — a preset that
- * bundled them saved three lines while forcing one `McpOAuthService` (and therefore one
- * credential store, which has no tenant dimension) to be shared across every session in the
- * process. Servers call `createHarness` directly; see `examples/managed-agents`.
- *
- * There is still no "mode" inside the engine (Architecture Invariant 7): this file only picks
- * backends, and returns a plain `Harness` nothing downstream can distinguish.
+ * It is a PRESET: pure data in (`LocalDeploymentOptions`), the three composition hooks out.
+ * The `harness` hook registers the process-lived objects on the harness scope; the `session`
+ * hook builds each session's capability set. A hosted deployment writes its own preset the same
+ * way (see `examples/managed-agents`) — there is still no "mode" inside the engine
+ * (Architecture Invariant 7): this file only picks backends, and returns plain `HarnessOptions`
+ * nothing downstream can distinguish.
  */
 import { homedir } from "node:os";
 import { cronExtension } from "./cron/index.js";
-import { join } from "node:path";
-import { DiskSessionRepository, McpOAuthService, RotatingFileSink, loadAgentProfiles, resolveGlobalLogPath, sinkLogger, } from "operon-agents-core";
+import { createModelRuntimeFromConfig } from "./providers.js";
+import { join, resolve } from "node:path";
+import { DiskSessionRepository, LocalEnvironment, McpOAuthService, RotatingFileSink, SkillRegistry, createMcpServers, loadSkillRoots, loadAgentProfiles, resolveGlobalLogPath, sinkLogger, } from "operon-agents-core";
 import { createHarness, defaultCapabilities, } from "./harness.js";
-/** Build `HarnessOptions` wired for a local, single-machine deployment. */
+/** Build `HarnessOptions` wired for a local, single-environment deployment. */
 export async function localHarnessOptions(options) {
-    const homeDir = options.homeDir ?? join(homedir(), ".agents");
-    // MCP OAuth credentials on local disk (0600) — the local default backend (`<homeDir>/credentials/mcp`).
-    const oauthService = new McpOAuthService({ homeDir });
-    // Diagnostics roll on disk under <homeDir>/logs.
-    const logger = options.logger ?? sinkLogger(new RotatingFileSink({ path: resolveGlobalLogPath({ homeDir }) }));
+    const { homeDir: home, mcpServers, pluginManager, hooks, loadDiskProfiles, logger, maxContextTokens, modelRuntime, loadConfiguredProviders, harness, session, extensions, ...engine } = options;
+    // Filled by the `harness` half below, read by the `session` half — one process, one set.
+    let sharedParts = {};
+    // Set when the shared skill scan ran through a LocalEnvironment at the default workDir (the host
+    // named no environment): that catalog only describes sessions rooted there.
+    let sharedSkillsWorkDir;
+    const homeDir = home ?? join(homedir(), ".agents");
     // Agent profiles come from disk here; the server preset supplies them externally instead.
     const extraSubagentProfiles = options.extraSubagentProfiles ??
-        ((options.loadDiskProfiles ?? true)
+        ((loadDiskProfiles ?? true)
             ? await loadAgentProfiles({ homeDir, cwd: options.workDir ?? process.cwd() })
             : undefined);
+    // Installed plugins are read ONCE per process, not per session: the manager is a harness-tier
+    // object, and `session.plugins.reload()` is the explicit refresh.
+    if (pluginManager !== undefined)
+        await pluginManager.load();
+    // Configured endpoints are resolved once per harness, not per session: the registry is a
+    // harness-tier object, and a session only ever reads it.
+    const runtime = modelRuntime ??
+        ((loadConfiguredProviders ?? true)
+            ? await createModelRuntimeFromConfig({ homeDir })
+            : undefined);
     return {
-        ...options,
-        // Disk sessions under <homeDir>/sessions; an injected repository still wins. The machine defaults to local.
-        repository: options.repository ?? new DiskSessionRepository(homeDir),
-        logger,
+        ...engine,
         ...(extraSubagentProfiles !== undefined ? { extraSubagentProfiles } : {}),
-        capabilities: options.capabilities ??
-            (() => defaultCapabilities({
-                ...(options.maxContextTokens !== undefined ? { maxContextTokens: options.maxContextTokens } : {}),
-                ...(options.mcpServers !== undefined ? { mcpServers: options.mcpServers } : {}),
-                ...(options.pluginManager !== undefined ? { pluginManager: options.pluginManager } : {}),
-                ...(options.hooks !== undefined ? { hooks: options.hooks } : {}),
+        harness: async () => {
+            // Disk sessions under <homeDir>/sessions; diagnostics roll on disk under <homeDir>/logs.
+            // The MCP connections, the skill scan and the OAuth store are process-wide: one set for
+            // every session this harness opens, built once, here.
+            const oauthService = new McpOAuthService({ homeDir });
+            const configs = { ...(mcpServers ?? {}), ...(pluginManager?.mcpServerConfigs() ?? {}) };
+            let servers;
+            if (Object.keys(configs).length > 0) {
+                servers = createMcpServers(configs, { oauthService });
+                // The set has no session and no event sink of its own: failures surface through
+                // `onStatusChange`, which each session subscribes to when it views it.
+                await servers.connect({ sessionId: "" });
+            }
+            const fromHost = await harness?.();
+            // Skills follow the EXECUTION environment, not the host's disk: the catalog the model sees
+            // must be the one whose scripts its Bash can reach. A host that named an environment above
+            // is scanned through it; an environment FACTORY (one per session) has no single filesystem
+            // to scan, so there is no shared registry then and each session scans through its own.
+            //
+            // A host that named none gets NO harness-wide environment: each session runs in a
+            // LocalEnvironment at its own workDir (the harness's fallback). The shared scan then goes
+            // through the default workDir and is reused only by sessions rooted there.
+            const hostEnvironment = fromHost?.environment;
+            const defaultWorkDir = resolve(options.workDir ?? process.cwd());
+            const scanEnvironment = hostEnvironment ?? new LocalEnvironment(defaultWorkDir);
+            let skillRegistry = fromHost?.skillRegistry;
+            if (skillRegistry === undefined && typeof scanEnvironment !== "function") {
+                skillRegistry = new SkillRegistry();
+                await loadSkillRoots(scanEnvironment, skillRegistry, {
+                    ...(pluginManager !== undefined ? { roots: pluginManager.skillRoots(), includeDefaultRoots: true } : {}),
+                });
+                if (hostEnvironment === undefined)
+                    sharedSkillsWorkDir = defaultWorkDir;
+            }
+            sharedParts = {
+                sessionRepository: new DiskSessionRepository(homeDir),
+                logger: logger ?? sinkLogger(new RotatingFileSink({ path: resolveGlobalLogPath({ homeDir }) })),
                 oauthService,
+                ...(hostEnvironment !== undefined ? { environment: hostEnvironment } : {}),
+                ...(servers !== undefined ? { mcpServers: servers } : {}),
+                ...(skillRegistry !== undefined ? { skillRegistry } : {}),
+                ...(pluginManager !== undefined ? { pluginManager } : {}),
+                // What `ExtensionHost.registerProvider` mutates, and where a session's model is looked up.
+                ...(runtime !== undefined ? { modelRuntime: runtime } : {}),
+                ...fromHost,
+                close: async () => {
+                    await fromHost?.close?.();
+                    await servers?.shutdown();
+                },
+            };
+            return sharedParts;
+        },
+        session: session ??
+            ((ctx) => defaultCapabilities({
+                shared: sessionSharedParts(sharedParts, sharedSkillsWorkDir, ctx.workDir),
+                ownEnvironment: ctx.ownEnvironment,
+                // `createSession({ mcpServers })` — layered over the process-shared connections.
+                ...(ctx.mcpServers !== undefined ? { sessionMcpServers: ctx.mcpServers } : {}),
+                ...(maxContextTokens !== undefined ? { maxContextTokens } : {}),
+                ...(pluginManager !== undefined ? { pluginManager } : {}),
+                ...(hooks !== undefined ? { hooks } : {}),
             })),
         // Cron rides the extension channel now: LOCAL deployments attach it, the server profile
         // simply doesn't — Invariant 7 ("cron is local-only") is structural, not an option to pass.
-        extensions: [cronExtension(), ...(options.extensions ?? [])],
+        extensions: [cronExtension(), ...(extensions ?? [])],
     };
 }
+/**
+ * The local entry point: one harness per process, one `createSession()` per conversation on it.
+ * Its `close()` closes those sessions and then the harness scope — the cron timer, the workspace
+ * MCP connections and the rotating log handle all live there, so nothing else tears them down.
+ */
 export async function createLocalHarness(options) {
     return createHarness(await localHarnessOptions(options));
 }
-/** Convenience: a local harness with one session opened and ready to `prompt()`. */
-export async function createLocalSession(options, session = {}) {
-    return (await createLocalHarness(options)).createSession(session);
+/** The shared parts a session may reuse: all of them, less a skill catalog scanned for another workDir. */
+function sessionSharedParts(parts, skillsWorkDir, workDir) {
+    if (skillsWorkDir === undefined || resolve(workDir) === skillsWorkDir)
+        return parts;
+    const { skillRegistry: _skillRegistry, ...rest } = parts;
+    return rest;
 }
 //# sourceMappingURL=local.js.map

package/dist/providers.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Model providers configured by the host, as opposed to the ones the engine ships with.
+ *
+ * The built-in catalog knows every major provider, but each of those is a fixed list at a fixed
+ * URL. A self-hosted endpoint — vLLM, Ollama, LiteLLM, a gateway, a proxy in front of a vendor —
+ * is neither: its address is local knowledge, and which models it serves is a question only that
+ * endpoint can answer. So a provider here is a URL plus how to authenticate, and its model list is
+ * fetched from the endpoint (`GET {baseUrl}/models`, the OpenAI-compatible shape every one of them
+ * speaks) rather than declared.
+ *
+ * The file is `<homeDir>/providers.toml`, so every local host — the TUI, the app server, a script
+ * that builds its own harness — sees the same providers without each inventing a config format.
+ * Nothing else in the framework reads it: this is the provider registry, not a general config.
+ *
+ * ```toml
+ * # A self-hosted endpoint. Models come from GET http://localhost:8000/v1/models.
+ * [providers.local]
+ * base_url = "http://localhost:8000/v1"
+ * api_key_env = "LOCAL_API_KEY"      # optional; omit for a keyless server
+ * context_window = 128000            # the default applied to every model it reports
+ *
+ * # Per-model facts the endpoint does not report.
+ * [providers.local.models."qwen3-coder"]
+ * name = "Qwen3 Coder"
+ * context_window = 256000
+ * reasoning = true
+ *
+ * # A provider whose models are declared rather than fetched.
+ * [providers.corp]
+ * base_url = "https://llm.corp.internal/v1"
+ * api_key_env = "CORP_API_KEY"
+ * fetch_models = false
+ * [providers.corp.models."gpt-4o-mini"]
+ * context_window = 128000
+ * ```
+ */
+import { z } from "zod";
+import { type Api, type ModelRuntime } from "operon-agents-core";
+/** The wire dialects a configured endpoint can speak. Almost everything speaks the first. */
+export declare const PROVIDER_APIS: readonly ["openai-completions", "openai-responses", "anthropic-messages"];
+export type ProviderApi = (typeof PROVIDER_APIS)[number];
+declare const ProviderEntrySchema: z.ZodObject<{
+    base_url: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    api: z.ZodDefault<z.ZodEnum<{
+        "openai-completions": "openai-completions";
+        "openai-responses": "openai-responses";
+        "anthropic-messages": "anthropic-messages";
+    }>>;
+    api_key_env: z.ZodOptional<z.ZodString>;
+    api_key: z.ZodOptional<z.ZodString>;
+    fetch_models: z.ZodDefault<z.ZodBoolean>;
+    context_window: z.ZodDefault<z.ZodNumber>;
+    max_output_tokens: z.ZodDefault<z.ZodNumber>;
+    reasoning: z.ZodDefault<z.ZodBoolean>;
+    vision: z.ZodDefault<z.ZodBoolean>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    models: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        context_window: z.ZodOptional<z.ZodNumber>;
+        max_output_tokens: z.ZodOptional<z.ZodNumber>;
+        reasoning: z.ZodOptional<z.ZodBoolean>;
+        vision: z.ZodOptional<z.ZodBoolean>;
+        api: z.ZodOptional<z.ZodEnum<{
+            "openai-completions": "openai-completions";
+            "openai-responses": "openai-responses";
+            "anthropic-messages": "anthropic-messages";
+        }>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const ProvidersFileSchema: z.ZodObject<{
+    providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        base_url: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        api: z.ZodDefault<z.ZodEnum<{
+            "openai-completions": "openai-completions";
+            "openai-responses": "openai-responses";
+            "anthropic-messages": "anthropic-messages";
+        }>>;
+        api_key_env: z.ZodOptional<z.ZodString>;
+        api_key: z.ZodOptional<z.ZodString>;
+        fetch_models: z.ZodDefault<z.ZodBoolean>;
+        context_window: z.ZodDefault<z.ZodNumber>;
+        max_output_tokens: z.ZodDefault<z.ZodNumber>;
+        reasoning: z.ZodDefault<z.ZodBoolean>;
+        vision: z.ZodDefault<z.ZodBoolean>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        models: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            context_window: z.ZodOptional<z.ZodNumber>;
+            max_output_tokens: z.ZodOptional<z.ZodNumber>;
+            reasoning: z.ZodOptional<z.ZodBoolean>;
+            vision: z.ZodOptional<z.ZodBoolean>;
+            api: z.ZodOptional<z.ZodEnum<{
+                "openai-completions": "openai-completions";
+                "openai-responses": "openai-responses";
+                "anthropic-messages": "anthropic-messages";
+            }>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ProviderEntry = z.infer<typeof ProviderEntrySchema>;
+export type ProvidersFile = z.infer<typeof ProvidersFileSchema>;
+export interface LoadedProviders {
+    readonly providers: Readonly<Record<string, ProviderEntry>>;
+    /** Problems that did not stop the load: a malformed entry, an unreadable file. */
+    readonly warnings: readonly string[];
+}
+export declare function providersConfigPath(homeDir: string): string;
+/**
+ * Read `<homeDir>/providers.toml`. A missing file is the normal case and yields no providers; a
+ * malformed one yields none plus a warning, because refusing to start over a config file the host
+ * may not even use would be worse than running with the built-in providers alone.
+ */
+export declare function loadProviderConfigs(homeDir: string): Promise<LoadedProviders>;
+/** The model ids an OpenAI-compatible `/models` response lists, in the order the endpoint gave. */
+export declare function parseModelsResponse(body: unknown): readonly string[];
+/**
+ * Turn one config entry into a provider the engine can stream through. Its model list starts at
+ * whatever the config declared and is replaced by the endpoint's on the first refresh.
+ */
+export declare function providerFromConfig(providerId: string, entry: ProviderEntry): import("@earendil-works/pi-ai").Provider<Api>;
+export interface ModelRuntimeFromConfigOptions {
+    readonly homeDir: string;
+    /**
+     * Ask each configured endpoint for its models. Default true. With it off the runtime carries
+     * only what the config declared, which is what an offline start wants.
+     */
+    readonly refresh?: boolean;
+    /** Per-endpoint budget for the model-list fetch. Default 5s: a dead endpoint must not hang startup. */
+    readonly refreshTimeoutMs?: number;
+    readonly onWarning?: (message: string) => void;
+}
+/**
+ * One model runtime carrying the engine's built-in providers plus everything in
+ * `<homeDir>/providers.toml`, with each configured endpoint asked what it serves.
+ *
+ * Hand the same runtime to `defineModel({ provider, model, runtime })` and to
+ * `createLocalHarness({ modelRuntime })`, so the model a host resolves and the models its sessions
+ * can switch to come from one registry.
+ */
+export declare function createModelRuntimeFromConfig(options: ModelRuntimeFromConfigOptions): Promise<ModelRuntime>;
+export {};
+//# sourceMappingURL=providers.d.ts.map