@grackle-ai/plugin-sdk 0.95.0

package/README.md

@@ -0,0 +1,92 @@
+# @grackle-ai/plugin-sdk
+
+Plugin contract and loader for Grackle. Defines the `GracklePlugin` interface that all plugins implement, the `PluginContext` they receive, and the `loadPlugins()` function that topologically sorts, initializes, and collects contributions from plugins.
+
+## GracklePlugin
+
+A plugin contributes server capabilities through five extension points:
+
+```typescript
+import type { GracklePlugin } from "@grackle-ai/plugin-sdk";
+
+const myPlugin: GracklePlugin = {
+  name: "my-plugin",
+  dependencies: ["core"], // loaded after "core"
+
+  grpcHandlers: (ctx) => [
+    { service: MyProtoService, handlers: { listItems, createItem } },
+  ],
+
+  reconciliationPhases: (ctx) => [
+    { name: "my-phase", execute: async () => { /* runs every tick */ } },
+  ],
+
+  mcpTools: (ctx) => [
+    { name: "my_tool", group: "my", description: "...", /* ... */ },
+  ],
+
+  eventSubscribers: (ctx) => {
+    const unsub = ctx.subscribe((event) => {
+      if (event.type === "task.created") { /* react */ }
+    });
+    return [{ dispose: unsub }];
+  },
+
+  initialize: async (ctx) => {
+    ctx.logger.info("my-plugin initialized");
+  },
+
+  shutdown: async () => {
+    // clean up external connections
+  },
+};
+```
+
+## PluginContext
+
+Plugins receive a thin runtime context. Database stores are accessed via direct package imports (e.g., `import { taskStore } from "@grackle-ai/database"`), not through the context.
+
+```typescript
+interface PluginContext {
+  subscribe: (cb: (event: GrackleEvent) => void) => () => void;
+  emit: (type: GrackleEventType, payload: Record<string, unknown>) => GrackleEvent;
+  logger: Logger;        // pino structured logger
+  config: ServerConfig;  // ports, host, grackleHome, apiKey, etc.
+}
+```
+
+## loadPlugins()
+
+Loads an array of plugins in dependency order:
+
+1. Validates no duplicate names or missing dependencies
+2. Topological sort (Kahn's algorithm) on declared `dependencies`
+3. Calls `initialize()` in dependency-first order
+4. Collects all contributions (gRPC handlers, phases, tools, subscribers)
+5. Returns a `LoadedPlugins` object with aggregated contributions and a `shutdown()` function
+
+```typescript
+import { loadPlugins } from "@grackle-ai/plugin-sdk";
+
+const result = await loadPlugins([corePlugin, orchestrationPlugin], ctx);
+
+// Use contributions
+for (const reg of result.serviceRegistrations) {
+  collector.addHandlers(reg.service, reg.handlers);
+}
+const manager = new ReconciliationManager(result.reconciliationPhases);
+
+// On server shutdown
+await result.shutdown(); // disposes subscribers, then calls plugin.shutdown() in reverse order
+```
+
+## Extension Points
+
+| Method | What it contributes | Consumed by |
+|---|---|---|
+| `grpcHandlers` | `ServiceRegistration[]` — proto service + handler pairs | `ServiceCollector` |
+| `reconciliationPhases` | `ReconciliationPhase[]` — named async phases | `ReconciliationManager` |
+| `mcpTools` | `PluginToolDefinition[]` — MCP tool definitions | `ToolRegistry` |
+| `eventSubscribers` | `Disposable[]` — event bus subscriptions | Server shutdown |
+| `initialize` | Async startup hook (e.g., connect to Neo4j) | Plugin loader |
+| `shutdown` | Async teardown hook | Plugin loader (reverse order) |

package/dist/context.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Plugin context types — the runtime environment provided to plugins.
+ *
+ * Stores (taskStore, sessionStore, etc.) are accessed via direct package
+ * imports from `@grackle-ai/database`, not through the context. The context
+ * provides only runtime-dynamic infrastructure: event bus, logger, and config.
+ *
+ * @module
+ */
+import type { Logger } from "pino";
+/** A resource that can be disposed to clean up subscriptions and state. */
+export interface Disposable {
+    /** Release all resources (unsubscribe callbacks, clear dedup maps, etc.). */
+    dispose(): void;
+}
+/** Resolved server configuration available to plugins. */
+export interface ServerConfig {
+    /** gRPC server port. */
+    grpcPort: number;
+    /** Web UI + WebSocket port. */
+    webPort: number;
+    /** MCP server port. */
+    mcpPort: number;
+    /** PowerLine server port. */
+    powerlinePort: number;
+    /** Bind address for all servers. */
+    host: string;
+    /** Grackle home directory (databases, API key, logs). */
+    grackleHome: string;
+    /** Loaded API key for authenticated requests. */
+    apiKey: string;
+    /** Override agent working directory (GRACKLE_WORKING_DIRECTORY). */
+    workingDirectory?: string;
+    /** Worktree base path (GRACKLE_WORKTREE_BASE). */
+    worktreeBase?: string;
+    /** Docker host for host mapping (GRACKLE_DOCKER_HOST). */
+    dockerHost?: string;
+}
+/** Event types emitted by the domain event bus. */
+export type GrackleEventType = "task.created" | "task.updated" | "task.started" | "task.completed" | "task.deleted" | "task.reparented" | "workspace.created" | "workspace.archived" | "workspace.updated" | "persona.created" | "persona.updated" | "persona.deleted" | "finding.posted" | "environment.added" | "environment.removed" | "environment.changed" | "environment.provision_progress" | "token.changed" | "credential.providers_changed" | "setting.changed" | "schedule.created" | "schedule.updated" | "schedule.deleted" | "schedule.fired" | "notification.escalated";
+/** A domain event from the event bus. */
+export interface GrackleEvent {
+    /** ULID — chronologically sortable unique identifier. */
+    id: string;
+    /** Dot-notation event type (e.g. "task.created"). */
+    type: GrackleEventType;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    /** Domain-specific payload. */
+    payload: Record<string, unknown>;
+}
+/**
+ * Runtime context provided to plugins.
+ *
+ * Stores (taskStore, sessionStore, etc.) are accessed via direct package
+ * imports — not injected through the context. This keeps the contract surface
+ * minimal and avoids coupling plugins to a fat DI interface.
+ */
+export interface PluginContext {
+    /** Subscribe to all domain events. Returns an unsubscribe function. */
+    subscribe: (cb: (event: GrackleEvent) => void) => () => void;
+    /** Emit a domain event. */
+    emit: (type: GrackleEventType, payload: Record<string, unknown>) => GrackleEvent;
+    /** Structured logger (pino). */
+    logger: Logger;
+    /** Resolved server configuration. */
+    config: ServerConfig;
+}
+/** Factory function that creates a subscriber and returns a Disposable for cleanup. */
+export type SubscriberFactory = (ctx: PluginContext) => Disposable;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,mDAAmD;AACnD,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,cAAc,GACd,iBAAiB,GACjB,mBAAmB,GACnB,oBAAoB,GACpB,mBAAmB,GACnB,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,gBAAgB,GAChB,mBAAmB,GACnB,qBAAqB,GACrB,qBAAqB,GACrB,gCAAgC,GAChC,eAAe,GACf,8BAA8B,GAC9B,iBAAiB,GACjB,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,gBAAgB,GAChB,wBAAwB,CAAC;AAE7B,yCAAyC;AACzC,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,IAAI,EAAE,gBAAgB,CAAC;IACvB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAC7D,2BAA2B;IAC3B,IAAI,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,YAAY,CAAC;IACjF,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,uFAAuF;AACvF,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,UAAU,CAAC"}

package/dist/context.js

@@ -0,0 +1,11 @@
+/**
+ * Plugin context types — the runtime environment provided to plugins.
+ *
+ * Stores (taskStore, sessionStore, etc.) are accessed via direct package
+ * imports from `@grackle-ai/database`, not through the context. The context
+ * provides only runtime-dynamic infrastructure: event bus, logger, and config.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { Disposable, ServerConfig, GrackleEventType, GrackleEvent, PluginContext, SubscriberFactory, } from "./context.js";
+export type { GracklePlugin, ServiceRegistration, ReconciliationPhase, PluginToolDefinition, } from "./plugin.js";
+export type { LoadedPlugins } from "./loader.js";
+export { loadPlugins } from "./loader.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAGrB,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { loadPlugins } from "./loader.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/loader.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Plugin loader — topological sort, initialization, and contribution collection.
+ *
+ * @module
+ */
+import type { GracklePlugin, ReconciliationPhase, ServiceRegistration, PluginToolDefinition } from "./plugin.js";
+import type { PluginContext, Disposable } from "./context.js";
+/** Aggregated contributions from all loaded plugins. */
+export interface LoadedPlugins {
+    /** All gRPC service registrations, in plugin load order. */
+    serviceRegistrations: ServiceRegistration[];
+    /** All reconciliation phases, in plugin load order. */
+    reconciliationPhases: ReconciliationPhase[];
+    /** All MCP tool definitions, in plugin load order. */
+    mcpTools: PluginToolDefinition[];
+    /** All subscriber disposables (for shutdown). */
+    subscriberDisposables: Disposable[];
+    /** Dispose all subscribers, then shutdown plugins in reverse initialization order. */
+    shutdown: () => Promise<void>;
+}
+/**
+ * Load, sort, initialize, and collect contributions from plugins.
+ *
+ * 1. Validate: no duplicate names, no missing dependencies
+ * 2. Topological sort on declared dependencies (error on cycles)
+ * 3. Call `initialize()` in dependency order
+ * 4. Collect grpcHandlers, reconciliationPhases, mcpTools, eventSubscribers
+ * 5. Return aggregated contributions + a shutdown function
+ *
+ * @param plugins - Unordered array of plugins to load.
+ * @param ctx - Runtime context provided to each plugin.
+ * @returns Aggregated contributions and a shutdown function.
+ */
+export declare function loadPlugins(plugins: GracklePlugin[], ctx: PluginContext): Promise<LoadedPlugins>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE9D,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,oBAAoB,EAAE,mBAAmB,EAAE,CAAC;IAC5C,uDAAuD;IACvD,oBAAoB,EAAE,mBAAmB,EAAE,CAAC;IAC5C,sDAAsD;IACtD,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,iDAAiD;IACjD,qBAAqB,EAAE,UAAU,EAAE,CAAC;IACpC,sFAAsF;IACtF,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,aAAa,EAAE,EACxB,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,aAAa,CAAC,CA6HxB"}

package/dist/loader.js

@@ -0,0 +1,190 @@
+/**
+ * Plugin loader — topological sort, initialization, and contribution collection.
+ *
+ * @module
+ */
+/**
+ * Load, sort, initialize, and collect contributions from plugins.
+ *
+ * 1. Validate: no duplicate names, no missing dependencies
+ * 2. Topological sort on declared dependencies (error on cycles)
+ * 3. Call `initialize()` in dependency order
+ * 4. Collect grpcHandlers, reconciliationPhases, mcpTools, eventSubscribers
+ * 5. Return aggregated contributions + a shutdown function
+ *
+ * @param plugins - Unordered array of plugins to load.
+ * @param ctx - Runtime context provided to each plugin.
+ * @returns Aggregated contributions and a shutdown function.
+ */
+export async function loadPlugins(plugins, ctx) {
+    // 1. Validate
+    const byName = new Map();
+    for (const plugin of plugins) {
+        if (byName.has(plugin.name)) {
+            throw new Error(`Duplicate plugin name: "${plugin.name}"`);
+        }
+        byName.set(plugin.name, plugin);
+    }
+    for (const plugin of plugins) {
+        for (const dep of plugin.dependencies ?? []) {
+            if (!byName.has(dep)) {
+                throw new Error(`Plugin "${plugin.name}" depends on "${dep}" which was not provided`);
+            }
+        }
+    }
+    // 2. Topological sort (Kahn's algorithm)
+    const sorted = topologicalSort(plugins);
+    // 3. Initialize in dependency order (clean up on failure)
+    const initialized = [];
+    try {
+        for (const plugin of sorted) {
+            if (plugin.initialize) {
+                await plugin.initialize(ctx);
+            }
+            initialized.push(plugin);
+        }
+    }
+    catch (err) {
+        // Shutdown already-initialized plugins in reverse order before re-throwing
+        for (let i = initialized.length - 1; i >= 0; i--) {
+            const plugin = initialized[i];
+            if (plugin.shutdown) {
+                try {
+                    await plugin.shutdown();
+                }
+                catch (shutdownErr) {
+                    ctx.logger.error({ err: shutdownErr, plugin: plugin.name }, "Plugin '%s' shutdown failed during initialization rollback", plugin.name);
+                }
+            }
+        }
+        throw err;
+    }
+    // 4. Collect contributions (roll back on failure)
+    const serviceRegistrations = [];
+    const reconciliationPhases = [];
+    const mcpTools = [];
+    const subscriberDisposables = [];
+    try {
+        for (const plugin of sorted) {
+            if (plugin.grpcHandlers) {
+                serviceRegistrations.push(...plugin.grpcHandlers(ctx));
+            }
+            if (plugin.reconciliationPhases) {
+                reconciliationPhases.push(...plugin.reconciliationPhases(ctx));
+            }
+            if (plugin.mcpTools) {
+                mcpTools.push(...plugin.mcpTools(ctx));
+            }
+            if (plugin.eventSubscribers) {
+                subscriberDisposables.push(...plugin.eventSubscribers(ctx));
+            }
+        }
+    }
+    catch (err) {
+        // Dispose any subscribers already collected, then shutdown initialized plugins
+        for (const disposable of subscriberDisposables) {
+            try {
+                disposable.dispose();
+            }
+            catch { /* best-effort */ }
+        }
+        for (let i = initialized.length - 1; i >= 0; i--) {
+            const plugin = initialized[i];
+            if (plugin.shutdown) {
+                try {
+                    await plugin.shutdown();
+                }
+                catch (shutdownErr) {
+                    ctx.logger.error({ err: shutdownErr, plugin: plugin.name }, "Plugin '%s' shutdown failed during contribution rollback", plugin.name);
+                }
+            }
+        }
+        throw err;
+    }
+    // 5. Build shutdown function (reverse order, catch errors)
+    const shutdown = async () => {
+        // Dispose subscribers first
+        for (const disposable of subscriberDisposables) {
+            try {
+                disposable.dispose();
+            }
+            catch (err) {
+                ctx.logger.warn({ err }, "Subscriber dispose failed during shutdown");
+            }
+        }
+        // Shutdown plugins in reverse initialization order
+        for (let i = initialized.length - 1; i >= 0; i--) {
+            const plugin = initialized[i];
+            if (plugin.shutdown) {
+                try {
+                    await plugin.shutdown();
+                }
+                catch (err) {
+                    ctx.logger.error({ err, plugin: plugin.name }, "Plugin '%s' shutdown failed", plugin.name);
+                }
+            }
+        }
+    };
+    return {
+        serviceRegistrations,
+        reconciliationPhases,
+        mcpTools,
+        subscriberDisposables,
+        shutdown,
+    };
+}
+/**
+ * Topological sort using Kahn's algorithm.
+ *
+ * @param plugins - Plugins with optional `dependencies` arrays.
+ * @returns Plugins in dependency-first order.
+ * @throws If a cycle is detected.
+ */
+function topologicalSort(plugins) {
+    const byName = new Map();
+    const inDegree = new Map();
+    const dependents = new Map();
+    // Initialize
+    for (const plugin of plugins) {
+        byName.set(plugin.name, plugin);
+        inDegree.set(plugin.name, 0);
+        dependents.set(plugin.name, []);
+    }
+    // Build edges: dependency → dependent (deduplicate to avoid inflated inDegree)
+    for (const plugin of plugins) {
+        const uniqueDeps = [...new Set(plugin.dependencies ?? [])];
+        for (const dep of uniqueDeps) {
+            dependents.get(dep).push(plugin.name);
+            inDegree.set(plugin.name, inDegree.get(plugin.name) + 1);
+        }
+    }
+    // Seed queue with zero in-degree nodes
+    const queue = [];
+    for (const [name, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(name);
+        }
+    }
+    // Process
+    const sorted = [];
+    while (queue.length > 0) {
+        const name = queue.shift();
+        sorted.push(byName.get(name));
+        for (const dependent of dependents.get(name)) {
+            const newDegree = inDegree.get(dependent) - 1;
+            inDegree.set(dependent, newDegree);
+            if (newDegree === 0) {
+                queue.push(dependent);
+            }
+        }
+    }
+    if (sorted.length !== plugins.length) {
+        // Find the cycle for a descriptive error message
+        const remaining = plugins
+            .filter((p) => !sorted.some((s) => s.name === p.name))
+            .map((p) => p.name);
+        throw new Error(`Dependency cycle detected among plugins: ${remaining.join(", ")}`);
+    }
+    return sorted;
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"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"}

package/dist/plugin.d.ts

@@ -0,0 +1,81 @@
+/**
+ * GracklePlugin interface — the universal plugin contract.
+ *
+ * A plugin contributes server capabilities through five extension points:
+ * gRPC handlers, reconciliation phases, MCP tools, event subscribers,
+ * and lifecycle hooks.
+ *
+ * @module
+ */
+import type { DescService } from "@bufbuild/protobuf";
+import type { PluginContext, Disposable } from "./context.js";
+/** A set of gRPC handler methods contributed to a ConnectRPC service. */
+export interface ServiceRegistration {
+    /** The proto service definition (e.g., grackle.Grackle). */
+    service: DescService;
+    /**
+     * Handler method implementations.
+     *
+     * Uses `any` because handler functions have concrete parameter types that
+     * are not assignable to `(...args: unknown[]) => unknown` due to contravariance.
+     */
+    handlers: Record<string, (...args: any[]) => any>;
+}
+/** A named async phase that runs during each reconciliation tick. */
+export interface ReconciliationPhase {
+    /** Short name for logging (e.g. "cron", "dispatch"). */
+    name: string;
+    /** Execute the phase. Errors are caught by the manager. */
+    execute: () => Promise<void>;
+}
+/**
+ * Declarative MCP tool definition contributed by a plugin.
+ *
+ * Intentionally uses `unknown` for schema/handler types to avoid depending
+ * on `@grackle-ai/mcp`. The server maps these to concrete ToolDefinition
+ * objects when registering with the MCP tool registry.
+ */
+export interface PluginToolDefinition {
+    /** Unique tool name (snake_case by convention). */
+    name: string;
+    /** Logical group for filtering (e.g. "task", "session"). */
+    group: string;
+    /** Human-readable description. */
+    description: string;
+    /** Zod schema for input validation. */
+    inputSchema: unknown;
+    /** The gRPC method this tool calls. */
+    rpcMethod: string;
+    /** Whether this tool mutates state. */
+    mutating: boolean;
+    /** Optional MCP tool annotations. */
+    annotations?: Record<string, unknown>;
+    /** Handler function invoked when the tool is called. */
+    handler: (args: unknown, client: unknown, authContext?: unknown) => Promise<unknown>;
+}
+/**
+ * A Grackle plugin that contributes server capabilities.
+ *
+ * Plugins are loaded by {@link loadPlugins} in topological order based on
+ * declared dependencies. Each plugin can contribute gRPC handlers,
+ * reconciliation phases, MCP tools, and event subscribers.
+ */
+export interface GracklePlugin {
+    /** Unique identifier (e.g., "core", "orchestration", "my-linear-sync"). */
+    name: string;
+    /** Plugins this one requires. The loader topologically sorts on this. */
+    dependencies?: string[];
+    /** gRPC handler groups to register on ConnectRPC services. */
+    grpcHandlers?: (ctx: PluginContext) => ServiceRegistration[];
+    /** Reconciliation phases to run on each tick. */
+    reconciliationPhases?: (ctx: PluginContext) => ReconciliationPhase[];
+    /** MCP tool definitions to register. */
+    mcpTools?: (ctx: PluginContext) => PluginToolDefinition[];
+    /** Event subscribers to wire up. Returns disposables for shutdown. */
+    eventSubscribers?: (ctx: PluginContext) => Disposable[];
+    /** Called after dependency plugins are initialized, in dependency order. */
+    initialize?: (ctx: PluginContext) => Promise<void>;
+    /** Called on graceful shutdown, in reverse load order. */
+    shutdown?: () => Promise<void>;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE9D,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,OAAO,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IAEH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC;CACnD;AAED,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,WAAW,EAAE,OAAO,CAAC;IACrB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,wDAAwD;IACxD,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACtF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,mBAAmB,EAAE,CAAC;IAC7D,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,mBAAmB,EAAE,CAAC;IACrE,wCAAwC;IACxC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,oBAAoB,EAAE,CAAC;IAC1D,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,UAAU,EAAE,CAAC;IAExD,4EAA4E;IAC5E,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC"}

package/dist/plugin.js

@@ -0,0 +1,11 @@
+/**
+ * GracklePlugin interface — the universal plugin contract.
+ *
+ * A plugin contributes server capabilities through five extension points:
+ * gRPC handlers, reconciliation phases, MCP tools, event subscribers,
+ * and lifecycle hooks.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.57.7"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@grackle-ai/plugin-sdk",
+  "version": "0.95.0",
+  "description": "Plugin contract and loader for Grackle — defines GracklePlugin, PluginContext, and loadPlugins()",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nick-pape/grackle.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "keywords": [
+    "grackle",
+    "plugin",
+    "sdk"
+  ],
+  "homepage": "https://github.com/nick-pape/grackle#readme",
+  "bugs": {
+    "url": "https://github.com/nick-pape/grackle/issues"
+  },
+  "engines": {
+    "node": ">=22.0.0 <24.0.0"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/"
+  ],
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.11.0",
+    "pino": "~9.6.0"
+  },
+  "devDependencies": {
+    "@rushstack/heft": "1.2.7",
+    "@types/node": "^22.0.0",
+    "vitest": "^3.2.1",
+    "@grackle-ai/heft-rig": "0.0.1"
+  },
+  "scripts": {
+    "build": "heft build --clean",
+    "test": "vitest run",
+    "clean": "heft clean",
+    "_phase:build": "heft run --only build -- --clean",
+    "_phase:test": "vitest run"
+  }
+}