@pikiloom/kernel 0.1.2 → 0.1.3

package/README.md

@@ -250,7 +250,28 @@ add an IM channel or your own UI.
 | `Catalog` | `NoopCatalog` | model/effort/tool/skill discovery for composers |
 | `InteractionHandler` | `DeferToTerminalInteractionHandler` | programmatic HITL answers (`AutoCancelInteractionHandler` for one-shots) |
 
-**Plugins** contribute per-session tools (`tools()`) and/or augment snapshots (`decorateSnapshot()`).
+**Plugins** are the registration unit for everything ONE capability adds to a session —
+register many, composed deterministically (and dynamically via `loom.registerPlugin(...)`):
+
+```ts
+interface Plugin {
+  id: string;
+  tools?(opts: { agent; workdir }): McpServerSpec[];                          // MCP servers
+  promptFragment?(opts: { agent; workdir; isFirstTurn }): string | null;       // how-to-use / behavior prompt
+  contributeSpawn?(opts: { agent; workdir; mode: 'run'|'tui'; sessionId?; model? }): SpawnContribution | null; // { env?, extraArgs?, configOverrides? }
+  decorateSnapshot?(snapshot): UniversalSnapshot;
+}
+```
+
+The kernel merges contributions per spawn — **never mutating global `process.env`** — in order
+`[ModelResolver → ToolProvider.env → plugins (registration order)]`, so a plugin can override
+the resolver (e.g. point an agent's `ANTHROPIC_BASE_URL` at a local proxy). `promptFragment`s are
+appended to the `SystemPromptBuilder` base and delivered via each agent's native mechanism. This
+is how a capability registers its tools **and** their usage prompt **and** any env/flags in one
+place — and how a model-traffic interceptor injects a redirect on both the `run()` and `tui()`
+rails without the kernel knowing anything about it. (The singular `ModelResolver` /
+`SystemPromptBuilder` ports remain the one authoritative model-credential / base-prompt source;
+plugins are the composable per-capability layer on top.)
 
 ---
 
@@ -264,7 +285,7 @@ Main entry `@pikiloom/kernel` re-exports everything. Subpaths: `@pikiloom/kernel
 - Surfaces: `WebSurface`, `CliSurface`
 - Ports/defaults: `FsSessionStore`, `NullModelResolver`, `NoopToolProvider`, `PassthroughSystemPromptBuilder`, `AutoCancelInteractionHandler`, `DeferToTerminalInteractionHandler`, `NoopCatalog`, `defaultBaseDir`
 - Protocol: `UniversalSnapshot`, `diffSnapshot`, `applySnapshotPatch`, `emptySnapshot`, `PROTOCOL_VERSION`, all wire/`Client*`/`Server*` message types
-- Types: `AgentDriver`, `AgentTurnInput`, `DriverContext`, `DriverEvent`, `DriverResult`, `LoomIO`, `PromptInput`, `Surface`, `Plugin`, `SessionStore`, `ModelResolver`, `ToolProvider`, `SystemPromptBuilder`, `InteractionHandler`, `Catalog`, …
+- Types: `AgentDriver`, `AgentTurnInput`, `DriverContext`, `DriverEvent`, `DriverResult`, `LoomIO`, `PromptInput`, `Surface`, `Plugin`, `SpawnContribution`, `SessionStore`, `ModelResolver`, `ToolProvider`, `SystemPromptBuilder`, `InteractionHandler`, `Catalog`, …
 
 ---
 

package/dist/contracts/surface.d.ts

@@ -65,11 +65,28 @@ export interface Surface {
     start(io: LoomIO, host?: TuiHost): Promise<void>;
     stop(): Promise<void>;
 }
+export interface SpawnContribution {
+    env?: Record<string, string>;
+    extraArgs?: string[];
+    configOverrides?: string[];
+}
 export interface Plugin {
     readonly id: string;
     tools?(opts: {
         agent: string;
         workdir: string;
     }): McpServerSpec[] | Promise<McpServerSpec[]>;
+    promptFragment?(opts: {
+        agent: string;
+        workdir: string;
+        isFirstTurn: boolean;
+    }): string | null | undefined | Promise<string | null | undefined>;
+    contributeSpawn?(opts: {
+        agent: string;
+        workdir: string;
+        mode: 'run' | 'tui';
+        sessionId?: string | null;
+        model?: string | null;
+    }): SpawnContribution | null | undefined | Promise<SpawnContribution | null | undefined>;
     decorateSnapshot?(snapshot: UniversalSnapshot): UniversalSnapshot;
 }

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { PtyBridge, ptyAvailable, type PtyExit, type PtyOpenOpts } from './runti
 export { attachTui, type AttachTuiOptions } from './runtime/tui.js';
 export type { AgentDriver, AgentTurnInput, DriverContext, DriverEvent, DriverResult, SteerFn, McpServerSpec, TuiInput, TuiSpec, } from './contracts/driver.js';
 export type { SessionStore, CoreSessionRecord, ModelResolver, ModelInjection, ToolProvider, SystemPromptBuilder, InteractionHandler, Catalog, } from './contracts/ports.js';
-export type { LoomIO, PromptInput, Surface, SurfaceCapabilities, Plugin, } from './contracts/surface.js';
+export type { LoomIO, PromptInput, Surface, SurfaceCapabilities, Plugin, SpawnContribution, } from './contracts/surface.js';
 export { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemPromptBuilder, AutoCancelInteractionHandler, DeferToTerminalInteractionHandler, NoopCatalog, defaultBaseDir, } from './ports/defaults.js';
 export { EchoDriver } from './drivers/echo.js';
 export { ClaudeDriver } from './drivers/claude.js';

package/dist/runtime/hub.d.ts

@@ -49,6 +49,9 @@ export declare class Hub implements LoomIO {
     private queueView;
     private publishQueued;
     private collectTools;
+    private mergeSpawn;
+    private pluginSpawn;
+    private composeSystemPrompt;
     private onRunnerUpdate;
     stop(sessionKey: string): boolean;
     steer(taskId: string, prompt: string, attachments?: string[]): Promise<boolean>;

package/dist/runtime/hub.js

@@ -45,7 +45,11 @@ export class Hub {
             throw new Error(`Driver "${agent}" does not support TUI mode`);
         const workdir = opts.workdir || this.deps.workdir;
         const injection = await this.deps.modelResolver.resolve(agent, { model: opts.model, profileId: null }).catch(() => null);
-        return driver.tui({ workdir, model: injection?.model ?? opts.model ?? null, sessionId: opts.sessionId ?? null, env: injection?.env });
+        const model = injection?.model ?? opts.model ?? null;
+        // Same merge as run(), so the raw-PTY rail also gets plugin env/args (e.g. a hijack redirect).
+        const pluginParts = await this.pluginSpawn(agent, workdir, 'tui', opts.sessionId ?? null, model);
+        const spawn = this.mergeSpawn([{ env: injection?.env, extraArgs: injection?.extraArgs }, ...pluginParts]);
+        return driver.tui({ workdir, model, sessionId: opts.sessionId ?? null, env: spawn.env, extraArgs: spawn.extraArgs });
     }
     async prompt(input) {
         const agent = (input.agent || this.deps.defaultAgent || '').trim();
@@ -98,20 +102,28 @@ export class Hub {
         // prior turn's native session id and any refreshed credentials/tools.
         const rec = await this.deps.sessionStore.get(agent, sessionId);
         const injection = await this.deps.modelResolver.resolve(agent, { model: input.model, profileId: null }).catch(() => null);
-        const tools = await this.collectTools(agent, workdir, workspacePath);
         const model = injection?.model ?? input.model ?? null;
         const effort = input.effort ?? null;
-        const systemPrompt = this.deps.systemPromptBuilder.compose({ agent, base: this.deps.systemPromptBase, isFirstTurn: !preExisted });
+        const tools = await this.collectTools(agent, workdir, workspacePath);
+        const pluginParts = await this.pluginSpawn(agent, workdir, 'run', sessionId, model);
+        // precedence: ModelResolver (model/creds) -> ToolProvider.env -> plugins (last, so a
+        // model-traffic hijack plugin can override the resolver's base URL).
+        const spawn = this.mergeSpawn([
+            { env: injection?.env, extraArgs: injection?.extraArgs, configOverrides: injection?.configOverrides },
+            { env: tools.env },
+            ...pluginParts,
+        ]);
+        const systemPrompt = await this.composeSystemPrompt(agent, workdir, !preExisted);
         const turnInput = {
             prompt: input.prompt,
             attachments: input.attachments,
             sessionId: rec?.nativeSessionId || (input.sessionKey ? sessionId : null),
             workdir,
             model, effort, systemPrompt,
-            env: injection?.env,
-            extraArgs: injection?.extraArgs, // BYOK flags from the ModelResolver
-            configOverrides: injection?.configOverrides, // codex BYOK -c routing
-            extraMcpServers: tools,
+            env: spawn.env,
+            extraArgs: spawn.extraArgs,
+            configOverrides: spawn.configOverrides,
+            extraMcpServers: tools.servers,
         };
         runner.run(driver, turnInput, input.prompt, model, effort)
             .then(async (result) => {
@@ -154,11 +166,16 @@ export class Hub {
         if (entry?.runner)
             this.onRunnerUpdate(sessionKey, entry.runner.snapshot, entry.runner.currentSeq);
     }
+    // MCP servers (ToolProvider + each plugin) PLUS the ToolProvider's session env (previously
+    // dropped) — surfaced so the spawn env merge can apply it.
     async collectTools(agent, workdir, workspacePath) {
-        const out = [];
+        const servers = [];
+        let env;
         try {
             const base = await this.deps.toolProvider.provideForSession({ agent, workdir, workspacePath });
-            out.push(...base.servers);
+            servers.push(...base.servers);
+            if (base.env && Object.keys(base.env).length)
+                env = base.env;
         }
         catch (e) {
             this.deps.log?.(`[hub] toolProvider failed: ${e?.message || e}`);
@@ -167,14 +184,71 @@ export class Hub {
             if (!plugin.tools)
                 continue;
             try {
-                out.push(...(await plugin.tools({ agent, workdir })));
+                servers.push(...(await plugin.tools({ agent, workdir })));
             }
             catch (e) {
                 this.deps.log?.(`[hub] plugin ${plugin.id} tools failed: ${e?.message || e}`);
             }
         }
+        return { servers, env };
+    }
+    // Merge ordered spawn contributions: env keys later-wins, extraArgs/configOverrides concatenate.
+    // Callers order parts [ModelResolver, ToolProvider.env, ...plugins] so a plugin (e.g. a model-
+    // traffic hijack) can override the resolver's base URL. Never touches global process.env.
+    mergeSpawn(parts) {
+        let env;
+        const extraArgs = [];
+        const configOverrides = [];
+        for (const p of parts) {
+            if (!p)
+                continue;
+            if (p.env && Object.keys(p.env).length)
+                env = { ...(env || {}), ...p.env };
+            if (p.extraArgs?.length)
+                extraArgs.push(...p.extraArgs);
+            if (p.configOverrides?.length)
+                configOverrides.push(...p.configOverrides);
+        }
+        return { env, extraArgs: extraArgs.length ? extraArgs : undefined, configOverrides: configOverrides.length ? configOverrides : undefined };
+    }
+    async pluginSpawn(agent, workdir, mode, sessionId, model) {
+        const out = [];
+        for (const plugin of this.deps.plugins) {
+            if (!plugin.contributeSpawn)
+                continue;
+            try {
+                const c = await plugin.contributeSpawn({ agent, workdir, mode, sessionId, model });
+                if (c)
+                    out.push(c);
+            }
+            catch (e) {
+                this.deps.log?.(`[hub] plugin ${plugin.id} contributeSpawn failed: ${e?.message || e}`);
+            }
+        }
         return out;
     }
+    // Final system/developer prompt = the singular SystemPromptBuilder base + each plugin's
+    // promptFragment (in registration order), joined. Delivered via AgentTurnInput.systemPrompt,
+    // which each driver applies its own way (claude --append-system-prompt / codex / gemini).
+    async composeSystemPrompt(agent, workdir, isFirstTurn) {
+        const parts = [];
+        const base = this.deps.systemPromptBuilder.compose({ agent, base: this.deps.systemPromptBase, isFirstTurn });
+        if (base && base.trim())
+            parts.push(base);
+        for (const plugin of this.deps.plugins) {
+            if (!plugin.promptFragment)
+                continue;
+            try {
+                const f = await plugin.promptFragment({ agent, workdir, isFirstTurn });
+                if (f && f.trim())
+                    parts.push(f);
+            }
+            catch (e) {
+                this.deps.log?.(`[hub] plugin ${plugin.id} promptFragment failed: ${e?.message || e}`);
+            }
+        }
+        return parts.length ? parts.join('\n\n') : undefined;
+    }
     onRunnerUpdate(sessionKey, snapshot, _seq) {
         const entry = this.sessions.get(sessionKey);
         if (!entry)

package/dist/runtime/loom.d.ts

@@ -28,6 +28,7 @@ export interface LoomConfig {
 export interface Loom {
     readonly io: LoomIO;
     registerDriver(driver: AgentDriver): void;
+    registerPlugin(plugin: Plugin): void;
     start(): Promise<void>;
     stop(): Promise<void>;
     status(): {

package/dist/runtime/loom.js

@@ -10,6 +10,8 @@ export function createLoom(config = {}) {
     for (const d of config.drivers || [])
         drivers.set(d.id, d);
     const defaultAgent = config.defaultAgent || config.drivers?.[0]?.id || 'echo';
+    // Held as a live reference so registerPlugin() mutates the same array the Hub iterates.
+    const plugins = [...(config.plugins || [])];
     const hub = new Hub({
         drivers,
         defaultAgent,
@@ -21,7 +23,7 @@ export function createLoom(config = {}) {
         catalog: config.catalog || new NoopCatalog(),
         interactionHandler: config.interactionHandler || new DeferToTerminalInteractionHandler(),
         serialPerSession: config.serialPerSession,
-        plugins: config.plugins || [],
+        plugins,
         systemPromptBase: config.systemPromptBase,
         log,
     });
@@ -36,6 +38,7 @@ export function createLoom(config = {}) {
     return {
         io: hub,
         registerDriver(driver) { drivers.set(driver.id, driver); },
+        registerPlugin(plugin) { plugins.push(plugin); },
         async start() {
             if (started)
                 return;

package/llms.txt

@@ -86,7 +86,9 @@ Write a driver: implement `AgentDriver { id; capabilities?; run(input, ctx); tui
 ## Surfaces & Ports
 
 - Surface (上层, binds LoomIO): built-in `WebSurface` (ws host, wire protocol), `CliSurface`. Implement `Surface { id; capabilities?; start(io, host?); stop() }` for an IM channel.
-- Plugin: `{ id; tools?({agent,workdir}); decorateSnapshot?(snapshot) }`.
+- Plugin = the registration unit for everything ONE capability adds to a session (register via `createLoom({plugins})` or `loom.registerPlugin(p)`):
+  `{ id; tools?({agent,workdir})=>McpServerSpec[]; promptFragment?({agent,workdir,isFirstTurn})=>string|null; contributeSpawn?({agent,workdir,mode:'run'|'tui',sessionId?,model?})=>SpawnContribution|null; decorateSnapshot?(snap) }`.
+  `SpawnContribution = { env?; extraArgs?; configOverrides? }`. Kernel merges per-spawn (NEVER touches global process.env), order `[ModelResolver → ToolProvider.env → plugins]` (plugin overrides resolver — e.g. a hijack redirecting `ANTHROPIC_BASE_URL` to a local proxy, applied on BOTH run() and tui()). `promptFragment`s append to the SystemPromptBuilder base. So tools + their usage-prompt + env/flags register in ONE place. The singular ModelResolver/SystemPromptBuilder remain the authoritative model-cred/base-prompt source; plugins are the composable layer on top.
 - Ports (defaults in parens): SessionStore (FsSessionStore), ModelResolver (NullModelResolver = native login; override for BYOK), ToolProvider (NoopToolProvider), SystemPromptBuilder (PassthroughSystemPromptBuilder), Catalog (NoopCatalog), InteractionHandler (DeferToTerminalInteractionHandler; AutoCancelInteractionHandler for one-shots). `defaultBaseDir(ns)`.
 
 ## Gotchas (read before using)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikiloom/kernel",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Heterogeneous coding agents (Claude / Codex / Gemini / ACP) -> an interaction-friendly, accumulating session snapshot + control handle, over pluggable surfaces (IM, Web, tunnel, TUI). The reusable core pikiloom itself is built on.",
   "type": "module",
   "license": "MIT",