@orc-brain/core 1.0.0

package/dist/plugins/host.d.ts

@@ -0,0 +1,39 @@
+/**
+ * PluginHost implementation (spec 003 §R1, §R4, §R6): the narrow, safe facade
+ * a plugin gets at `init`. Every callback a plugin registers is exception-
+ * isolated (§N2) and every subscription is tracked so `system.close()` can
+ * detach plugins before the store closes.
+ */
+import type { ExternalRef, ExternalTask, Goal, PluginHost } from "@orc-brain/shared";
+import type { Store } from "../store/index.js";
+import type { AuditSink } from "../safety/index.js";
+import type { EventBus } from "../eventBus.js";
+import type { SecretStore } from "./secrets.js";
+/** Feature-flow entrypoint injected by the composition root (spec 003 §R4). */
+export type CreateFeatureGoalFn = (projectId: string, input: {
+    objective: string;
+    title?: string;
+    external_ref?: ExternalRef | null;
+}) => Goal;
+/** Dependencies for {@link createPluginHost}. */
+export interface PluginHostDeps {
+    pluginName: string;
+    settings: Record<string, unknown>;
+    store: Store;
+    bus: EventBus;
+    audit: AuditSink;
+    secrets: SecretStore;
+    createFeatureGoal: CreateFeatureGoalFn;
+    log?: (msg: string) => void;
+    /** Registers an unsubscribe so the registry can detach the plugin (§N2). */
+    trackUnsubscribe: (unsubscribe: () => void) => void;
+}
+/** Builds the goal title/objective from an external task (spec 003 §R4). */
+export declare function externalTaskToFeatureInput(task: ExternalTask): {
+    title: string;
+    objective: string;
+    external_ref: ExternalRef;
+};
+/** Constructs the host handed to one plugin's `init` (spec 003 §R1). */
+export declare function createPluginHost(deps: PluginHostDeps): PluginHost;
+//# sourceMappingURL=host.d.ts.map

package/dist/plugins/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/plugins/host.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,UAAU,EAIX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,+EAA+E;AAC/E,MAAM,MAAM,mBAAmB,GAAG,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;IACL,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CACnC,KACE,IAAI,CAAC;AAEV,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,QAAQ,CAAC;IACd,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,WAAW,CAAC;IACrB,iBAAiB,EAAE,mBAAmB,CAAC;IACvC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,4EAA4E;IAC5E,gBAAgB,EAAE,CAAC,WAAW,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACrD;AAED,4EAA4E;AAC5E,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,YAAY,GAAG;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,WAAW,CAAC;CAC3B,CAsBA;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CAiFjE"}

package/dist/plugins/host.js

@@ -0,0 +1,109 @@
+/**
+ * PluginHost implementation (spec 003 §R1, §R4, §R6): the narrow, safe facade
+ * a plugin gets at `init`. Every callback a plugin registers is exception-
+ * isolated (§N2) and every subscription is tracked so `system.close()` can
+ * detach plugins before the store closes.
+ */
+import { redactString, redactValue } from "../safety/redact.js";
+/** Builds the goal title/objective from an external task (spec 003 §R4). */
+export function externalTaskToFeatureInput(task) {
+    const titleLine = `${task.identifier}: ${task.title}`;
+    // Same truncation limit as the feature flow (spec 002 §R4).
+    const title = titleLine.length > 80 ? titleLine.slice(0, 77) + "…" : titleLine;
+    const objective = [
+        titleLine,
+        "",
+        ...(task.description.trim() ? [task.description.trim(), ""] : []),
+        `Origin: ${task.url}`,
+    ].join("\n");
+    return {
+        title,
+        objective,
+        external_ref: {
+            provider: task.provider,
+            id: task.id,
+            identifier: task.identifier,
+            url: task.url,
+            title: task.title,
+        },
+    };
+}
+/** Constructs the host handed to one plugin's `init` (spec 003 §R1). */
+export function createPluginHost(deps) {
+    const actor = `plugin:${deps.pluginName}`;
+    const log = deps.log ?? ((msg) => console.log(msg));
+    const audit = (action, detail) => {
+        deps.audit.record({
+            ts: new Date().toISOString(),
+            actor,
+            run_id: null,
+            task_id: null,
+            session_id: null,
+            kind: "plugin",
+            tool_name: null,
+            tool_input_hash: null,
+            tool_input: null,
+            decision: null,
+            rule_id: null,
+            detail: redactValue({ action, detail: detail ?? null }),
+        });
+    };
+    return {
+        log: (msg) => log(`[${actor}] ${redactString(msg)}`),
+        audit,
+        reportSync: (action, info) => {
+            audit(action, {
+                ref: info.ref ?? null,
+                ok: info.ok,
+                detail: info.detail ?? null,
+                run_id: info.run_id ?? null,
+            });
+            deps.bus.publish({
+                run_id: info.run_id ?? null,
+                type: "plugin.sync",
+                payload: {
+                    plugin: deps.pluginName,
+                    action,
+                    ...(info.ref ? { ref: info.ref } : {}),
+                    ok: info.ok,
+                    ...(info.detail ? { detail: redactString(info.detail) } : {}),
+                },
+            });
+        },
+        getSecret: (key) => deps.secrets.get(key),
+        settings: deps.settings,
+        subscribe: (fn) => {
+            // A plugin callback must never break bus delivery or the dispatcher
+            // (§N2). The bus already isolates subscriber exceptions; this keeps the
+            // guarantee even if that ever changes, and scopes the error to the actor.
+            const unsubscribe = deps.bus.subscribe((event) => {
+                try {
+                    fn(event);
+                }
+                catch (err) {
+                    audit("subscriber_error", {
+                        event_type: event.type,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            });
+            deps.trackUnsubscribe(unsubscribe);
+            return unsubscribe;
+        },
+        listProjects: async () => deps.store.listProjects(),
+        getGoal: async (id) => deps.store.getGoal(id),
+        getRun: async (id) => deps.store.getRun(id),
+        listScopesByGoal: async (goalId) => deps.store.listScopesByGoal(goalId),
+        createGoalFromExternalTask: async (projectId, task) => {
+            const input = externalTaskToFeatureInput(task);
+            const goal = deps.createFeatureGoal(projectId, input);
+            audit("goal_imported", {
+                goal_id: goal.id,
+                project_id: projectId,
+                ref: input.external_ref,
+            });
+            return goal;
+        },
+    };
+}
+//# sourceMappingURL=host.js.map

package/dist/plugins/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/plugins/host.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AA2BhE,4EAA4E;AAC5E,MAAM,UAAU,0BAA0B,CAAC,IAAkB;IAK3D,MAAM,SAAS,GAAG,GAAG,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;IACtD,4DAA4D;IAC5D,MAAM,KAAK,GACT,SAAS,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACnE,MAAM,SAAS,GAAG;QAChB,SAAS;QACT,EAAE;QACF,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACjE,WAAW,IAAI,CAAC,GAAG,EAAE;KACtB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,OAAO;QACL,KAAK;QACL,SAAS;QACT,YAAY,EAAE;YACZ,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB;KACF,CAAC;AACJ,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,gBAAgB,CAAC,IAAoB;IACnD,MAAM,KAAK,GAAG,UAAU,IAAI,CAAC,UAAU,EAAE,CAAC;IAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAE5D,MAAM,KAAK,GAAG,CAAC,MAAc,EAAE,MAAgB,EAAQ,EAAE;QACvD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;YAChB,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,KAAK;YACL,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,IAAI;YACb,UAAU,EAAE,IAAI;YAChB,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,IAAI;YACf,eAAe,EAAE,IAAI;YACrB,UAAU,EAAE,IAAI;YAChB,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,IAAI,EAAE,CAAC;SACxD,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,OAAO;QACL,GAAG,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,KAAK,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5D,KAAK;QACL,UAAU,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE;YAC3B,KAAK,CAAC,MAAM,EAAE;gBACZ,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,IAAI;gBACrB,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;gBAC3B,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;aAC5B,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;gBACf,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;gBAC3B,IAAI,EAAE,aAAa;gBACnB,OAAO,EAAE;oBACP,MAAM,EAAE,IAAI,CAAC,UAAU;oBACvB,MAAM;oBACN,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACtC,EAAE,EAAE,IAAI,CAAC,EAAE;oBACX,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC9D;aACF,CAAC,CAAC;QACL,CAAC;QACD,SAAS,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;QACjD,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE;YAChB,oEAAoE;YACpE,wEAAwE;YACxE,0EAA0E;YAC1E,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;gBAC/C,IAAI,CAAC;oBACH,EAAE,CAAC,KAAK,CAAC,CAAC;gBACZ,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,KAAK,CAAC,kBAAkB,EAAE;wBACxB,UAAU,EAAE,KAAK,CAAC,IAAI;wBACtB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;qBACxD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;YACnC,OAAO,WAAW,CAAC;QACrB,CAAC;QACD,YAAY,EAAE,KAAK,IAAwB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE;QACvE,OAAO,EAAE,KAAK,EAAE,EAAU,EAAwB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3E,MAAM,EAAE,KAAK,EAAE,EAAU,EAAuB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QACxE,gBAAgB,EAAE,KAAK,EAAE,MAAc,EAAoB,EAAE,CAC3D,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC;QACrC,0BAA0B,EAAE,KAAK,EAC/B,SAAiB,EACjB,IAAkB,EACH,EAAE;YACjB,MAAM,KAAK,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC;YAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,iBAAiB,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;YACtD,KAAK,CAAC,eAAe,EAAE;gBACrB,OAAO,EAAE,IAAI,CAAC,EAAE;gBAChB,UAAU,EAAE,SAAS;gBACrB,GAAG,EAAE,KAAK,CAAC,YAAY;aACxB,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/plugins/registry.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Plugin registry + loader (spec 003 §R3): reads `<stateDir>/plugins.json`,
+ * dynamically imports each declared module (absolute path or builtin alias),
+ * validates its manifest, and initializes it with a {@link PluginHost}. A
+ * malformed file or a plugin that throws on import/init is contained — it is
+ * marked `status: "error"` and the orchestrator boots regardless (§N2).
+ * Nothing loads unless the operator wrote it into `plugins.json` (§11 trust
+ * model). Tests inject fake modules via `pluginModules` — no dynamic import.
+ */
+import { type ExternalTask, type Goal, type OrcPluginModule, type PluginStatus, type TaskProvider } from "@orc-brain/shared";
+import type { Store } from "../store/index.js";
+import type { AuditSink } from "../safety/index.js";
+import type { EventBus } from "../eventBus.js";
+import type { SecretStore } from "./secrets.js";
+import { type CreateFeatureGoalFn } from "./host.js";
+/** Dependencies for {@link PluginRegistry}. */
+export interface PluginRegistryDeps {
+    store: Store;
+    bus: EventBus;
+    audit: AuditSink;
+    secrets: SecretStore;
+    createFeatureGoal: CreateFeatureGoalFn;
+    /** Path to the declarations file; missing file means no plugins. */
+    pluginsFile: string;
+    /** Injectable modules keyed by declaration name (tests; spec 003 §R3). */
+    modules?: Record<string, OrcPluginModule>;
+    log?: (msg: string) => void;
+}
+/** Loads, tracks, and exposes declared plugins (spec 003 §R3). */
+export declare class PluginRegistry {
+    private readonly deps;
+    /** Resolves when every declared plugin has loaded or errored. */
+    readonly ready: Promise<void>;
+    private readonly entries;
+    private readonly log;
+    constructor(deps: PluginRegistryDeps);
+    /** Audits a registry-level (not per-plugin) failure and logs it. */
+    private fileError;
+    /** Parses `plugins.json`; a malformed file yields no plugins, not a crash. */
+    private readDeclarations;
+    /** Resolves a declaration to a plugin module (injected → builtin → path). */
+    private resolveModule;
+    private loadAll;
+    /** Imports, validates, and initializes one enabled plugin (spec 003 §R3). */
+    private loadOne;
+    /** Load status of every declared plugin (`GET /api/plugins`, §R3). */
+    list(): PluginStatus[];
+    private activeEntry;
+    /** The named plugin's task provider, when active and capable (§R3, §R7). */
+    getTaskProvider(name: string): TaskProvider | null;
+    /** Active plugins exposing the `task-provider` capability (§R7). */
+    listTaskProviders(): Array<{
+        name: string;
+        capabilities: string[];
+    }>;
+    /** True when a declared plugin key exists (for the secrets route, §R8). */
+    has(name: string): boolean;
+    /**
+     * Imports an external task as a goal through the plugin's own host (so the
+     * audit actor is the plugin), then fires the plugin's `onTaskImported` hook
+     * fire-and-forget (spec 003 §R7, §R12 import comment).
+     */
+    importTask(name: string, task: ExternalTask, projectId: string): Promise<Goal>;
+    /**
+     * Detaches every plugin: unsubscribes bus listeners synchronously (so no
+     * late callback touches a closed store) and fires `close` hooks
+     * fire-and-forget (spec 003 §R3; called from `system.close()`).
+     */
+    closeAll(): void;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/plugins/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/plugins/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,IAAI,EAET,KAAK,eAAe,EAGpB,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAmBvE,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,QAAQ,CAAC;IACd,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,WAAW,CAAC;IACrB,iBAAiB,EAAE,mBAAmB,CAAC;IACvC,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC1C,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,kEAAkE;AAClE,qBAAa,cAAc;IAMb,OAAO,CAAC,QAAQ,CAAC,IAAI;IALjC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwB;gBAEf,IAAI,EAAE,kBAAkB;IAQrD,oEAAoE;IACpE,OAAO,CAAC,SAAS;IAkBjB,8EAA8E;IAC9E,OAAO,CAAC,gBAAgB;IA0CxB,6EAA6E;YAC/D,aAAa;YAmBb,OAAO;IA4BrB,6EAA6E;YAC/D,OAAO;IAoDrB,sEAAsE;IACtE,IAAI,IAAI,YAAY,EAAE;IAWtB,OAAO,CAAC,WAAW;IAOnB,4EAA4E;IAC5E,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IASlD,oEAAoE;IACpE,iBAAiB,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAcpE,2EAA2E;IAC3E,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;;;OAIG;IACG,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC;IAkBhB;;;;OAIG;IACH,QAAQ,IAAI,IAAI;CAajB"}

package/dist/plugins/registry.js

@@ -0,0 +1,269 @@
+/**
+ * Plugin registry + loader (spec 003 §R3): reads `<stateDir>/plugins.json`,
+ * dynamically imports each declared module (absolute path or builtin alias),
+ * validates its manifest, and initializes it with a {@link PluginHost}. A
+ * malformed file or a plugin that throws on import/init is contained — it is
+ * marked `status: "error"` and the orchestrator boots regardless (§N2).
+ * Nothing loads unless the operator wrote it into `plugins.json` (§11 trust
+ * model). Tests inject fake modules via `pluginModules` — no dynamic import.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { pathToFileURL } from "node:url";
+import { PLUGIN_API_VERSION, } from "@orc-brain/shared";
+import { registerStrippedEnvKeys } from "../spawnEnv.js";
+import { registerSecretValue } from "../safety/redact.js";
+import { createPluginHost } from "./host.js";
+/** Builtin aliases resolvable without an absolute path (spec 003 §R3, §R13). */
+const BUILTIN_SPECIFIERS = {
+    linear: "@orc-brain/plugin-linear",
+};
+const KEBAB_RE = /^[a-z][a-z0-9-]*$/;
+/** Loads, tracks, and exposes declared plugins (spec 003 §R3). */
+export class PluginRegistry {
+    deps;
+    /** Resolves when every declared plugin has loaded or errored. */
+    ready;
+    entries = [];
+    log;
+    constructor(deps) {
+        this.deps = deps;
+        this.log = deps.log ?? ((msg) => console.warn(msg));
+        this.ready = this.loadAll().catch((err) => {
+            // loadAll contains per-plugin errors; this catches only file-level ones.
+            this.fileError(err instanceof Error ? err.message : String(err));
+        });
+    }
+    /** Audits a registry-level (not per-plugin) failure and logs it. */
+    fileError(message) {
+        this.log(`orc: plugins.json error — ${message}`);
+        this.deps.audit.record({
+            ts: new Date().toISOString(),
+            actor: "plugin-registry",
+            run_id: null,
+            task_id: null,
+            session_id: null,
+            kind: "plugin",
+            tool_name: null,
+            tool_input_hash: null,
+            tool_input: null,
+            decision: null,
+            rule_id: null,
+            detail: { action: "load_error", message },
+        });
+    }
+    /** Parses `plugins.json`; a malformed file yields no plugins, not a crash. */
+    readDeclarations() {
+        if (!existsSync(this.deps.pluginsFile))
+            return [];
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(this.deps.pluginsFile, "utf8"));
+        }
+        catch (err) {
+            this.fileError(`not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+            return [];
+        }
+        const list = parsed?.plugins;
+        if (!Array.isArray(list)) {
+            this.fileError(`expected { "plugins": [...] }`);
+            return [];
+        }
+        const out = [];
+        for (const raw of list) {
+            const d = raw;
+            if (typeof d?.name !== "string" ||
+                typeof d?.specifier !== "string" ||
+                typeof d?.enabled !== "boolean") {
+                this.fileError(`invalid entry ${JSON.stringify(raw)} — need { name, specifier, enabled }`);
+                continue;
+            }
+            out.push({
+                name: d.name,
+                specifier: d.specifier,
+                enabled: d.enabled,
+                settings: d.settings && typeof d.settings === "object"
+                    ? d.settings
+                    : undefined,
+            });
+        }
+        return out;
+    }
+    /** Resolves a declaration to a plugin module (injected → builtin → path). */
+    async resolveModule(decl) {
+        const injected = this.deps.modules?.[decl.name];
+        if (injected)
+            return injected;
+        const builtin = BUILTIN_SPECIFIERS[decl.specifier];
+        if (builtin)
+            return (await import(builtin));
+        if (!isAbsolute(decl.specifier)) {
+            throw new Error(`specifier must be an absolute path or a builtin alias (${Object.keys(BUILTIN_SPECIFIERS).join(", ")}), got "${decl.specifier}"`);
+        }
+        return (await import(pathToFileURL(decl.specifier).href));
+    }
+    async loadAll() {
+        const seen = new Set();
+        for (const decl of this.readDeclarations()) {
+            const entry = {
+                decl,
+                plugin: null,
+                host: null,
+                status: "error",
+                unsubscribes: [],
+            };
+            this.entries.push(entry);
+            if (!KEBAB_RE.test(decl.name)) {
+                entry.error = `plugin name must be kebab-case, got "${decl.name}"`;
+            }
+            else if (seen.has(decl.name)) {
+                entry.error = `duplicate plugin name "${decl.name}"`;
+            }
+            else if (!decl.enabled) {
+                seen.add(decl.name);
+                entry.status = "disabled";
+            }
+            else {
+                seen.add(decl.name);
+                await this.loadOne(entry);
+            }
+            if (entry.error) {
+                this.fileError(`plugin "${decl.name}": ${entry.error}`);
+            }
+        }
+    }
+    /** Imports, validates, and initializes one enabled plugin (spec 003 §R3). */
+    async loadOne(entry) {
+        const { decl } = entry;
+        try {
+            const module = await this.resolveModule(decl);
+            if (typeof module.default !== "function") {
+                throw new Error("module has no default-export plugin factory");
+            }
+            const plugin = module.default(decl.settings ?? {});
+            const manifest = plugin?.manifest;
+            if (!manifest || typeof manifest.name !== "string") {
+                throw new Error("plugin has no manifest");
+            }
+            if (manifest.apiVersion !== PLUGIN_API_VERSION) {
+                throw new Error(`plugin apiVersion ${manifest.apiVersion} does not match host ${PLUGIN_API_VERSION}`);
+            }
+            if (manifest.name !== decl.name) {
+                throw new Error(`manifest name "${manifest.name}" does not match declared name "${decl.name}"`);
+            }
+            // Secret hygiene before init (spec 003 §R5): declared keys never reach
+            // worker envs, and their current values are redacted everywhere.
+            for (const key of manifest.secrets ?? []) {
+                registerStrippedEnvKeys([key]);
+                const value = this.deps.secrets.get(key);
+                if (value)
+                    registerSecretValue(value);
+            }
+            const host = createPluginHost({
+                pluginName: manifest.name,
+                settings: decl.settings ?? {},
+                store: this.deps.store,
+                bus: this.deps.bus,
+                audit: this.deps.audit,
+                secrets: this.deps.secrets,
+                createFeatureGoal: this.deps.createFeatureGoal,
+                log: this.log,
+                trackUnsubscribe: (fn) => entry.unsubscribes.push(fn),
+            });
+            await plugin.init(host);
+            entry.plugin = plugin;
+            entry.host = host;
+            entry.status = "active";
+        }
+        catch (err) {
+            // A broken plugin must never take the orchestrator down (§N2).
+            for (const unsubscribe of entry.unsubscribes.splice(0))
+                unsubscribe();
+            entry.error = err instanceof Error ? err.message : String(err);
+            entry.status = "error";
+        }
+    }
+    /** Load status of every declared plugin (`GET /api/plugins`, §R3). */
+    list() {
+        return this.entries.map((e) => ({
+            name: e.decl.name,
+            version: e.plugin?.manifest.version ?? null,
+            capabilities: e.plugin?.manifest.capabilities ?? [],
+            enabled: e.decl.enabled,
+            status: e.status,
+            ...(e.error ? { error: e.error } : {}),
+        }));
+    }
+    activeEntry(name) {
+        return (this.entries.find((e) => e.decl.name === name && e.status === "active") ??
+            null);
+    }
+    /** The named plugin's task provider, when active and capable (§R3, §R7). */
+    getTaskProvider(name) {
+        const entry = this.activeEntry(name);
+        if (!entry?.plugin?.taskProvider)
+            return null;
+        if (!entry.plugin.manifest.capabilities.includes("task-provider")) {
+            return null;
+        }
+        return entry.plugin.taskProvider;
+    }
+    /** Active plugins exposing the `task-provider` capability (§R7). */
+    listTaskProviders() {
+        return this.entries
+            .filter((e) => e.status === "active" &&
+            e.plugin?.taskProvider &&
+            e.plugin.manifest.capabilities.includes("task-provider"))
+            .map((e) => ({
+            name: e.decl.name,
+            capabilities: e.plugin.manifest.capabilities,
+        }));
+    }
+    /** True when a declared plugin key exists (for the secrets route, §R8). */
+    has(name) {
+        return this.entries.some((e) => e.decl.name === name);
+    }
+    /**
+     * Imports an external task as a goal through the plugin's own host (so the
+     * audit actor is the plugin), then fires the plugin's `onTaskImported` hook
+     * fire-and-forget (spec 003 §R7, §R12 import comment).
+     */
+    async importTask(name, task, projectId) {
+        const entry = this.activeEntry(name);
+        if (!entry?.host)
+            throw new Error(`plugin "${name}" is not active`);
+        const goal = await entry.host.createGoalFromExternalTask(projectId, task);
+        const hook = entry.plugin?.onTaskImported?.bind(entry.plugin);
+        if (hook) {
+            void Promise.resolve()
+                .then(() => hook(task, goal))
+                .catch((err) => {
+                entry.host?.audit("on_task_imported_error", {
+                    goal_id: goal.id,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }
+        return goal;
+    }
+    /**
+     * Detaches every plugin: unsubscribes bus listeners synchronously (so no
+     * late callback touches a closed store) and fires `close` hooks
+     * fire-and-forget (spec 003 §R3; called from `system.close()`).
+     */
+    closeAll() {
+        for (const entry of this.entries) {
+            for (const unsubscribe of entry.unsubscribes.splice(0))
+                unsubscribe();
+            const close = entry.plugin?.close?.bind(entry.plugin);
+            if (close) {
+                void Promise.resolve()
+                    .then(() => close())
+                    .catch(() => {
+                    // Shutdown best-effort; the process is going away.
+                });
+            }
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/plugins/registry.js.map

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

package/dist/plugins/secrets.d.ts

@@ -0,0 +1,30 @@
+/**
+ * File-based plugin secret store (spec 003 §R5): `<stateDir>/secrets.json`,
+ * mode 0600. This is the only credential home in orc-brain — model-provider
+ * keys stay banned (they are stripped/refused elsewhere); this store exists
+ * for plugin (non-model) secrets like `LINEAR_API_KEY`. Resolution order for
+ * reads: secrets file, then `process.env` fallback. Values never appear in
+ * `listKeys`, logs, or errors.
+ */
+/** Reads/writes `<stateDir>/secrets.json` with 0600 enforcement (§R5). */
+export declare class SecretStore {
+    private readonly env;
+    readonly path: string;
+    private warned;
+    constructor(stateDir: string, env?: NodeJS.ProcessEnv);
+    /**
+     * A pre-existing file that is group/world-readable is refused — reads
+     * ignore it and writes throw until the operator fixes the mode (§R5,
+     * spec 003 §8 edge cases).
+     */
+    private insecureMode;
+    private readFile;
+    private writeFile;
+    /** Secrets file first, then `process.env[key]` fallback (§R5). */
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+    unset(key: string): void;
+    /** Key names present in the file (never values). Env fallbacks not listed. */
+    listKeys(): string[];
+}
+//# sourceMappingURL=secrets.d.ts.map

package/dist/plugins/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../src/plugins/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH,0EAA0E;AAC1E,qBAAa,WAAW;IAMpB,OAAO,CAAC,QAAQ,CAAC,GAAG;IALtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,MAAM,CAAS;gBAGrB,QAAQ,EAAE,MAAM,EACC,GAAG,oBAAc;IAKpC;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,QAAQ;IAqBhB,OAAO,CAAC,SAAS;IAQjB,kEAAkE;IAClE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIpC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAerC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAWxB,8EAA8E;IAC9E,QAAQ,IAAI,MAAM,EAAE;CAGrB"}

package/dist/plugins/secrets.js

@@ -0,0 +1,99 @@
+/**
+ * File-based plugin secret store (spec 003 §R5): `<stateDir>/secrets.json`,
+ * mode 0600. This is the only credential home in orc-brain — model-provider
+ * keys stay banned (they are stripped/refused elsewhere); this store exists
+ * for plugin (non-model) secrets like `LINEAR_API_KEY`. Resolution order for
+ * reads: secrets file, then `process.env` fallback. Values never appear in
+ * `listKeys`, logs, or errors.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+/** Env-style secret key names: SCREAMING_SNAKE_CASE. */
+const KEY_RE = /^[A-Z][A-Z0-9_]*$/;
+/** Reads/writes `<stateDir>/secrets.json` with 0600 enforcement (§R5). */
+export class SecretStore {
+    env;
+    path;
+    warned = false;
+    constructor(stateDir, env = process.env) {
+        this.env = env;
+        this.path = join(stateDir, "secrets.json");
+    }
+    /**
+     * A pre-existing file that is group/world-readable is refused — reads
+     * ignore it and writes throw until the operator fixes the mode (§R5,
+     * spec 003 §8 edge cases).
+     */
+    insecureMode() {
+        if (!existsSync(this.path))
+            return false;
+        if (process.platform === "win32")
+            return false; // no POSIX modes
+        const mode = statSync(this.path).mode & 0o777;
+        if ((mode & 0o077) === 0)
+            return false;
+        if (!this.warned) {
+            this.warned = true;
+            console.warn(`orc: refusing ${this.path} — mode ${mode.toString(8)} is group/world-readable; run: chmod 600 ${this.path}`);
+        }
+        return true;
+    }
+    readFile() {
+        if (!existsSync(this.path) || this.insecureMode())
+            return {};
+        try {
+            const parsed = JSON.parse(readFileSync(this.path, "utf8"));
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                return {};
+            }
+            const out = {};
+            for (const [k, v] of Object.entries(parsed)) {
+                if (typeof v === "string")
+                    out[k] = v;
+            }
+            return out;
+        }
+        catch {
+            if (!this.warned) {
+                this.warned = true;
+                console.warn(`orc: ${this.path} is not valid JSON; treating as empty`);
+            }
+            return {};
+        }
+    }
+    writeFile(secrets) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, JSON.stringify(secrets, null, 2) + "\n", {
+            mode: 0o600,
+        });
+        chmodSync(this.path, 0o600); // `mode` only applies on creation
+    }
+    /** Secrets file first, then `process.env[key]` fallback (§R5). */
+    get(key) {
+        return this.readFile()[key] ?? this.env[key];
+    }
+    set(key, value) {
+        if (!KEY_RE.test(key)) {
+            throw new Error(`secret key must be SCREAMING_SNAKE_CASE (e.g. LINEAR_API_KEY), got "${key}"`);
+        }
+        if (!value)
+            throw new Error("secret value must be non-empty");
+        if (this.insecureMode()) {
+            throw new Error(`refusing to write ${this.path}: file is group/world-readable — run: chmod 600 ${this.path}`);
+        }
+        this.writeFile({ ...this.readFile(), [key]: value });
+    }
+    unset(key) {
+        if (this.insecureMode()) {
+            throw new Error(`refusing to write ${this.path}: file is group/world-readable — run: chmod 600 ${this.path}`);
+        }
+        const secrets = this.readFile();
+        delete secrets[key];
+        this.writeFile(secrets);
+    }
+    /** Key names present in the file (never values). Env fallbacks not listed. */
+    listKeys() {
+        return Object.keys(this.readFile()).sort();
+    }
+}
+//# sourceMappingURL=secrets.js.map