feat(appkit): plugin infrastructure — attachContext lifecycle + PluginContext mediator

Third layer: the substrate every downstream PR relies on. No user-
facing API changes here; the surface for this PR is the mediator
pattern, lifecycle semantics, and factory stamping.

### Split Plugin construction from context binding

`Plugin` constructors become pure — no `CacheManager.getInstanceSync()`,
no `TelemetryManager.getProvider()`, no `PluginContext` wiring inside
`constructor()`. That work moves to a new lifecycle method:

```ts
interface BasePlugin {
  attachContext?(deps: {
    context?: unknown;
    telemetryConfig?: TelemetryOptions;
  }): void;
}
```

`createApp` calls `attachContext()` on every plugin after all
constructors have run, before `setup()`. This lets factories return
`PluginData` tuples at module scope without pulling core services into
the import graph — a prerequisite for later PRs that construct agent
definitions before `createApp`.

### PluginContext mediator

`packages/appkit/src/core/plugin-context.ts` — new class that mediates
all inter-plugin communication:

- **Route buffering**: `addRoute()` / `addMiddleware()` buffer until
  the server plugin calls `registerAsRouteTarget()`, then flush via
  `addExtension()`. Eliminates plugin-ordering fragility.
- **ToolProvider registry**: `registerToolProvider(name, plugin)` +
  live `getToolProviders()`. Typed discovery of tool-exposing plugins.
- **User-scoped tool execution**: `executeTool(req, pluginName,
  localName, args, signal?)` resolves the provider, wraps in
  `asUser(req)` for OBO, opens a telemetry span, applies a 30s
  timeout, dispatches, returns.
- **Lifecycle hooks**: `onLifecycle('setup:complete' | 'server:ready'
  | 'shutdown', cb)` + `emitLifecycle(event)`. Callback errors don't
  block siblings.

### `toPlugin` stamps `pluginName`

`packages/appkit/src/plugin/to-plugin.ts` — the factory now attaches a
read-only `pluginName` property to the returned function. Later PRs'
`fromPlugin(factory)` reads it to identify which plugin a factory
refers to without needing to construct an instance. `NamedPluginFactory`
type exported for consumers who want to type-constrain factories.

### Server plugin defers start to `setup:complete`

`ServerPlugin.setup()` no longer calls `extendRoutes()` synchronously.
It subscribes to the `setup:complete` lifecycle event via
`PluginContext` and starts the HTTP server there. This ensures that
any deferred-phase plugin (agents plugin in a later PR) has had a
chance to register routes via `PluginContext.addRoute()` before the
server binds. Removes the `plugins` field from `ServerConfig` (routes
are now discovered via the context, not a config snapshot).

### Test plan

- 25 new PluginContext tests (route buffering, tool provider registry,
  executeTool paths, lifecycle hooks, plugin metadata)
- Updated AppKit lifecycle tests to inject `context` instead of
  `plugins`
- Full appkit vitest suite: 1237 tests passing
- Typecheck clean across all 8 workspace projects

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

Author: MarioCadenas

packages/appkit/src/core/appkit.ts

@@ -13,14 +13,18 @@ import { ServiceContext } from "../context";
 import { ResourceRegistry, ResourceType } from "../registry";
 import type { TelemetryConfig } from "../telemetry";
 import { TelemetryManager } from "../telemetry";
+import { isToolProvider, PluginContext } from "./plugin-context";
 
 export class AppKit<TPlugins extends InputPluginMap> {
   #pluginInstances: Record<string, BasePlugin> = {};
   #setupPromises: Promise<void>[] = [];
+  #context: PluginContext;
 
   private constructor(config: { plugins: TPlugins }) {
     const { plugins, ...globalConfig } = config;
 
+    this.#context = new PluginContext();
+
     const pluginEntries = Object.entries(plugins);
 
     const corePlugins = pluginEntries.filter(([_, p]) => {
@@ -35,20 +39,24 @@ export class AppKit<TPlugins extends InputPluginMap> {
 
     for (const [name, pluginData] of corePlugins) {
       if (pluginData) {
-        this.createAndRegisterPlugin(globalConfig, name, pluginData);
+        this.createAndRegisterPlugin(globalConfig, name, pluginData, {
+          context: this.#context,
+        });
       }
     }
 
     for (const [name, pluginData] of normalPlugins) {
       if (pluginData) {
-        this.createAndRegisterPlugin(globalConfig, name, pluginData);
+        this.createAndRegisterPlugin(globalConfig, name, pluginData, {
+          context: this.#context,
+        });
       }
     }
 
     for (const [name, pluginData] of deferredPlugins) {
       if (pluginData) {
         this.createAndRegisterPlugin(globalConfig, name, pluginData, {
-          plugins: this.#pluginInstances,
+          context: this.#context,
         });
       }
     }
@@ -70,8 +78,20 @@ export class AppKit<TPlugins extends InputPluginMap> {
     };
     const pluginInstance = new Plugin(baseConfig);
 
+    if (typeof pluginInstance.attachContext === "function") {
+      pluginInstance.attachContext({
+        context: this.#context,
+        telemetryConfig: baseConfig.telemetry,
+      });
+    }
+
     this.#pluginInstances[name] = pluginInstance;
 
+    this.#context.registerPlugin(name, pluginInstance);
+    if (isToolProvider(pluginInstance)) {
+      this.#context.registerToolProvider(name, pluginInstance);
+    }
+
     this.#setupPromises.push(pluginInstance.setup());
 
     const self = this;
@@ -199,6 +219,7 @@ export class AppKit<TPlugins extends InputPluginMap> {
     const instance = new AppKit(mergedConfig);
 
     await Promise.all(instance.#setupPromises);
+    await instance.#context.emitLifecycle("setup:complete");
 
     return instance as unknown as PluginMap<T>;
   }

packages/appkit/src/core/plugin-context.ts

@@ -0,0 +1,287 @@
+import type express from "express";
+import type { BasePlugin, ToolProvider } from "shared";
+import { createLogger } from "../logging/logger";
+import { TelemetryManager } from "../telemetry";
+
+const logger = createLogger("plugin-context");
+
+interface BufferedRoute {
+  method: string;
+  path: string;
+  handlers: express.RequestHandler[];
+}
+
+interface RouteTarget {
+  addExtension(fn: (app: express.Application) => void): void;
+}
+
+interface ToolProviderEntry {
+  plugin: BasePlugin & ToolProvider;
+  name: string;
+}
+
+type LifecycleEvent = "setup:complete" | "server:ready" | "shutdown";
+
+/**
+ * Mediator for inter-plugin communication.
+ *
+ * Created by AppKit core and passed to every plugin. Plugins request
+ * capabilities from the context instead of holding direct references
+ * to sibling plugin instances.
+ *
+ * Capabilities:
+ * - Route mounting with buffering (order-independent)
+ * - Typed ToolProvider registry (live, not snapshot-based)
+ * - User-scoped tool execution with automatic telemetry
+ * - Lifecycle hooks for plugin coordination
+ */
+export class PluginContext {
+  private routeBuffer: BufferedRoute[] = [];
+  private routeTarget: RouteTarget | null = null;
+  private toolProviders = new Map<string, ToolProviderEntry>();
+  private plugins = new Map<string, BasePlugin>();
+  private lifecycleHooks = new Map<
+    LifecycleEvent,
+    Set<() => void | Promise<void>>
+  >();
+  private telemetry = TelemetryManager.getProvider("plugin-context");
+
+  /**
+   * Register a route on the root Express application.
+   *
+   * If a route target (server plugin) has registered, the route is applied
+   * immediately. Otherwise it is buffered and flushed when a route target
+   * becomes available.
+   */
+  addRoute(
+    method: string,
+    path: string,
+    ...handlers: express.RequestHandler[]
+  ): void {
+    if (this.routeTarget) {
+      this.applyRoute({ method, path, handlers });
+    } else {
+      this.routeBuffer.push({ method, path, handlers });
+    }
+  }
+
+  /**
+   * Register middleware on the root Express application.
+   *
+   * Same buffering semantics as `addRoute`.
+   */
+  addMiddleware(path: string, ...handlers: express.RequestHandler[]): void {
+    if (this.routeTarget) {
+      this.applyMiddleware(path, handlers);
+    } else {
+      this.routeBuffer.push({ method: "use", path, handlers });
+    }
+  }
+
+  /**
+   * Called by the server plugin to opt in as the route target.
+   * Flushes all buffered routes via the server's `addExtension`.
+   */
+  registerAsRouteTarget(target: RouteTarget): void {
+    this.routeTarget = target;
+
+    for (const route of this.routeBuffer) {
+      if (route.method === "use") {
+        this.applyMiddleware(route.path, route.handlers);
+      } else {
+        this.applyRoute(route);
+      }
+    }
+    this.routeBuffer = [];
+  }
+
+  /**
+   * Register a plugin that implements the ToolProvider interface.
+   * Called by AppKit core after constructing each plugin.
+   */
+  registerToolProvider(name: string, plugin: BasePlugin & ToolProvider): void {
+    this.toolProviders.set(name, { plugin, name });
+  }
+
+  /**
+   * Register a plugin instance.
+   * Called by AppKit core after constructing each plugin.
+   */
+  registerPlugin(name: string, instance: BasePlugin): void {
+    this.plugins.set(name, instance);
+  }
+
+  /**
+   * Returns all registered plugin instances keyed by name.
+   * Used by the server plugin for route injection, client config,
+   * and shutdown coordination.
+   */
+  getPlugins(): Map<string, BasePlugin> {
+    return this.plugins;
+  }
+
+  /**
+   * Returns all registered ToolProvider plugins.
+   * Always returns the current set — not a frozen snapshot.
+   */
+  getToolProviders(): Array<{ name: string; provider: ToolProvider }> {
+    return Array.from(this.toolProviders.values()).map((entry) => ({
+      name: entry.name,
+      provider: entry.plugin,
+    }));
+  }
+
+  /**
+   * Execute a tool on a ToolProvider plugin with automatic user scoping
+   * and telemetry.
+   *
+   * The context:
+   * 1. Resolves the plugin by name
+   * 2. Calls `asUser(req)` for user-scoped execution
+   * 3. Wraps the call in a telemetry span with a 30s timeout
+   */
+  async executeTool(
+    req: express.Request,
+    pluginName: string,
+    toolName: string,
+    args: unknown,
+    signal?: AbortSignal,
+  ): Promise<unknown> {
+    const entry = this.toolProviders.get(pluginName);
+    if (!entry) {
+      throw new Error(
+        `PluginContext: unknown plugin "${pluginName}". Available: ${Array.from(this.toolProviders.keys()).join(", ")}`,
+      );
+    }
+
+    const tracer = this.telemetry.getTracer();
+    const operationName = `executeTool:${pluginName}.${toolName}`;
+
+    return tracer.startActiveSpan(operationName, async (span) => {
+      const timeout = 30_000;
+      const timeoutSignal = AbortSignal.timeout(timeout);
+      const combinedSignal = signal
+        ? AbortSignal.any([signal, timeoutSignal])
+        : timeoutSignal;
+
+      try {
+        const userPlugin = (entry.plugin as any).asUser(req);
+        const result = await (userPlugin as ToolProvider).executeAgentTool(
+          toolName,
+          args,
+          combinedSignal,
+        );
+        span.setStatus({ code: 0 });
+        return result;
+      } catch (error) {
+        span.setStatus({
+          code: 2,
+          message:
+            error instanceof Error ? error.message : "Tool execution failed",
+        });
+        span.recordException(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+        throw error;
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * Register a lifecycle hook callback.
+   */
+  onLifecycle(event: LifecycleEvent, fn: () => void | Promise<void>): void {
+    let hooks = this.lifecycleHooks.get(event);
+    if (!hooks) {
+      hooks = new Set();
+      this.lifecycleHooks.set(event, hooks);
+    }
+    hooks.add(fn);
+  }
+
+  /**
+   * Emit a lifecycle event, calling all registered callbacks.
+   * Errors in individual callbacks are logged but do not prevent
+   * other callbacks from running.
+   *
+   * @internal Called by AppKit core only.
+   */
+  async emitLifecycle(event: LifecycleEvent): Promise<void> {
+    const hooks = this.lifecycleHooks.get(event);
+    if (!hooks) return;
+
+    if (
+      event === "setup:complete" &&
+      this.routeBuffer.length > 0 &&
+      !this.routeTarget
+    ) {
+      logger.warn(
+        "%d buffered routes were never applied — no server plugin registered as route target",
+        this.routeBuffer.length,
+      );
+    }
+
+    for (const fn of hooks) {
+      try {
+        await fn();
+      } catch (error) {
+        logger.error("Lifecycle hook '%s' failed: %O", event, error);
+      }
+    }
+  }
+
+  /**
+   * Returns all registered plugin names.
+   */
+  getPluginNames(): string[] {
+    return Array.from(this.plugins.keys());
+  }
+
+  /**
+   * Check if a plugin with the given name is registered.
+   */
+  hasPlugin(name: string): boolean {
+    return this.plugins.has(name);
+  }
+
+  private applyRoute(route: BufferedRoute): void {
+    if (!this.routeTarget) return;
+    this.routeTarget.addExtension((app) => {
+      const method = route.method.toLowerCase() as keyof express.Application;
+      if (typeof app[method] === "function") {
+        (app[method] as (...a: unknown[]) => void)(
+          route.path,
+          ...route.handlers,
+        );
+      }
+    });
+  }
+
+  private applyMiddleware(
+    path: string,
+    handlers: express.RequestHandler[],
+  ): void {
+    if (!this.routeTarget) return;
+    this.routeTarget.addExtension((app) => {
+      app.use(path, ...handlers);
+    });
+  }
+}
+
+/**
+ * Type guard: checks whether a plugin implements the ToolProvider interface.
+ */
+export function isToolProvider(
+  plugin: unknown,
+): plugin is BasePlugin & ToolProvider {
+  return (
+    typeof plugin === "object" &&
+    plugin !== null &&
+    "getAgentTools" in plugin &&
+    typeof (plugin as ToolProvider).getAgentTools === "function" &&
+    "executeAgentTool" in plugin &&
+    typeof (plugin as ToolProvider).executeAgentTool === "function"
+  );
+}