@spinabot/brigade 0.1.1 → 1.0.0

package/dist/agents/extensions/registry.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Brigade extension registry — the recorder + dispatcher behind the seam.
+ *
+ * A module registers through the `BrigadeExtensionContext` this produces; every
+ * call is RECORDED here (not run live), because Brigade's gateway is per-turn:
+ *   - agent-level registrations (tools/hooks/commands/model-providers) are replayed
+ *     into EVERY Pi session via `toPiExtensionFactory()` (handed to
+ *     `DefaultResourceLoader({ extensionFactories })`);
+ *   - product-level registrations (channels/voice/media/integrations/services/
+ *     http-routes/gateway-methods) are exposed to the gateway, which starts /
+ *     mounts them ONCE at boot.
+ *
+ * Product registrations dedupe by id (last wins) so re-running modules is safe.
+ */
+import type { ExtensionFactory } from "@mariozechner/pi-coding-agent";
+import type { BrigadeConfig } from "../../config/io.js";
+import type { AnyBrigadeTool } from "../tools/types.js";
+import { type BrigadeHookName, type HookFireResult } from "./hook-runner.js";
+import type { BrigadeExtensionContext, ChannelAdapter, ChannelCommand, GatewayMethodHandler, HttpRoute, Integration, MediaGenProvider, ProviderAuthMethodRegistration, Service, SpeechProvider, TranscriptionProvider } from "./types.js";
+/** Per-load context Brigade supplies to each module's `register(b)`. */
+export interface RegistryContextMeta {
+    agentId: string;
+    workspaceDir: string;
+    cwd: string;
+    config: BrigadeConfig;
+    /** This module's validated config block (see `BrigadeExtensionContext.moduleConfig`). */
+    moduleConfig?: unknown;
+}
+export declare class BrigadeExtensionRegistry {
+    private readonly toolRegs;
+    private readonly hookRegs;
+    private readonly commandRegs;
+    private readonly modelProviderRegs;
+    private readonly providerAuthMethodRegs;
+    private readonly channelMap;
+    private readonly channelCommandMap;
+    private readonly speechMap;
+    private readonly transcriptionMap;
+    private readonly mediaGenMap;
+    private readonly memoryMap;
+    private readonly memoryEmbeddingMap;
+    private readonly contextEngineMap;
+    private readonly compactionProviderMap;
+    private readonly agentHarnessMap;
+    private readonly webSearchMap;
+    private readonly webFetchMap;
+    private readonly integrationMap;
+    private readonly serviceMap;
+    private readonly httpRouteMap;
+    private readonly gatewayMethodMap;
+    /** Modules that successfully registered — the loader fills this (used for reload). */
+    readonly loadedModules: import("./types.js").BrigadeModule[];
+    /** Build the recording context a module's `register(b)` writes into. */
+    context(meta: RegistryContextMeta): BrigadeExtensionContext;
+    get channels(): ChannelAdapter[];
+    get channelCommands(): ChannelCommand[];
+    get speechProviders(): SpeechProvider[];
+    get transcriptionProviders(): TranscriptionProvider[];
+    get mediaGenProviders(): MediaGenProvider[];
+    get memoryCapabilities(): import("./types.js").MemoryCapability[];
+    get memoryEmbeddingProviders(): import("./types.js").MemoryEmbeddingProvider[];
+    get contextEngines(): import("./types.js").ContextEngineCapability[];
+    get compactionProviders(): import("./types.js").CompactionProvider[];
+    get agentHarnesses(): import("./types.js").AgentHarness[];
+    get webSearchProviders(): import("./types.js").WebSearchProvider[];
+    get webFetchProviders(): import("./types.js").WebFetchProvider[];
+    /**
+     * Resolve the active web-search provider for the agent loop.
+     *
+     *   1. If `tools.web.search.provider` is pinned in config, return that
+     *      provider — if missing or not-yet-configured, return `null` (the
+     *      pin is honored verbatim; we don't silently fall back).
+     *   2. Otherwise sort by `autoDetectOrder` ascending and return the
+     *      first provider whose `isConfigured(cfg, env)` returns true.
+     *   3. If none are credentialed, fall back to the first provider with
+     *      `requiresCredential === false` (e.g. DuckDuckGo HTML scrape).
+     *   4. Otherwise `null` — no search provider is reachable.
+     *
+     * Same shape (parallel function) for `resolveActiveWebFetchProvider`.
+     */
+    resolveActiveWebSearchProvider(cfg: BrigadeConfig, env?: NodeJS.ProcessEnv): import("./types.js").WebSearchProvider | null;
+    /**
+     * Error-time fallback chain for `web_search` — the ordered list of
+     * providers the tool may try when the active provider THROWS (rate
+     * limit, anti-bot block, network failure). Production incident: the
+     * default provider 429'd on a weekly quota and, with no fallback, the
+     * agent lost web search entirely.
+     *
+     *   - Operator pin (`tools.web.search.provider`) → `[]`. A pin is
+     *     honored verbatim; we never silently reroute around it.
+     *   - Allow/deny filtered, exactly like the default resolver.
+     *   - GENERAL-PURPOSE tier only (`autoDetectOrder <= 100`): the
+     *     specialised keyless providers above 100 (wikipedia, arxiv,
+     *     github, …) answer a different question — falling back to them
+     *     for a general query would return junk with a 200 face.
+     *   - Configured providers only. Keyless DDG self-reports configured,
+     *     so the chain always ends at a zero-config rung unless the
+     *     operator denied it.
+     */
+    listWebSearchFallbackChain(cfg: BrigadeConfig, env?: NodeJS.ProcessEnv): import("./types.js").WebSearchProvider[];
+    /**
+     * Look up a web-search provider by id, respecting the operator's
+     * allow/deny lists. Returns null when the id is unknown OR is gated
+     * out by config. Used for per-call `provider` overrides on
+     * `web_search`.
+     */
+    lookupWebSearchProviderById(id: string, cfg: BrigadeConfig): import("./types.js").WebSearchProvider | null;
+    resolveActiveWebFetchProvider(cfg: BrigadeConfig, env?: NodeJS.ProcessEnv): import("./types.js").WebFetchProvider | null;
+    /**
+     * Resolve the active slot-selected capability for a given slot key.
+     * `extensions.slots.<slot>` in `brigade.json` names the active plugin id;
+     * when unset, returns `undefined` (Brigade's built-in path takes over).
+     *
+     *   const memory = registry.resolveSlot("memory", cfg, registry.memoryCapabilities);
+     *
+     * Generic so any slot uses the same lookup shape.
+     */
+    resolveSlot<T extends {
+        id: string;
+    }>(slotName: "memory" | "contextEngine" | "compaction" | "agentHarness", cfg: BrigadeConfig, candidates: ReadonlyArray<T>): T | undefined;
+    get integrations(): Integration[];
+    get services(): Service[];
+    get httpRoutes(): HttpRoute[];
+    get gatewayMethods(): GatewayMethodHandler[];
+    /**
+     * Recorded provider auth methods, optionally filtered to a single provider.
+     * Order = registration order — that's the order onboarding/resolution should
+     * try methods in (first viable wins). Today this is shape-only — the
+     * consumer-side resolver lands when the first OAuth provider plugin ships.
+     */
+    providerAuthMethods(providerName?: string): ProviderAuthMethodRegistration[];
+    /**
+     * Eligible tool objects (passes the per-tool `check_fn` gate).
+     *
+     * When `opts.toolset` is supplied (e.g. `"minimal" | "coding" | "messaging"
+     * | "full"`), the result is additionally filtered to tools whose recorded
+     * `toolset` either matches that string, is `"*"` (universal opt-in), or is
+     * `undefined` (no profile declared — always included so legacy / un-tagged
+     * tools never disappear behind a profile switch). Unset / empty `toolset`
+     * disables the filter — the tool list returns as if the knob weren't there
+     * (full surface), which is the desired default for `agents.defaults.toolset`
+     * being absent from `brigade.json`.
+     */
+    eligibleTools(opts?: {
+        toolset?: string;
+    }): AnyBrigadeTool[];
+    /** Names of eligible tools — feed into `enabledToolNames` so the unknown-tool guard allows them. */
+    toolNames(opts?: {
+        toolset?: string;
+    }): string[];
+    /**
+     * Fire a Brigade-native hook event through the 4-pattern runner. The pattern
+     * is looked up by name from `HOOK_PATTERNS` (telemetry/modifying/claiming/
+     * sync) — callers pass the payload and get back the merged outcome.
+     *
+     *   const claim = await registry.fireHook("inbound_claim", { channel, msg });
+     *   if (claim.handled) return; // a plugin owns this inbound
+     *
+     * Returns `{ handlerCount }` plus pattern-specific fields:
+     *   - claiming → `{ handled, by? }` (handler index 0-based that claimed)
+     *   - modifying → `{ modifications }` (merged payload patch)
+     *   - void / sync → just the count
+     */
+    fireHook<T = unknown>(name: BrigadeHookName, payload: T): Promise<HookFireResult>;
+    /** Recorded hooks sorted by priority (higher first); ties keep registration order. */
+    private sortedHooks;
+    /**
+     * Replay the recorded agent-level registrations into a Pi session. Hand the
+     * result to `new DefaultResourceLoader({ extensionFactories: [factory] })`
+     * (and remember to `await loader.reload()` — Brigade passes the loader in, so
+     * `createAgentSession` won't reload it itself).
+     *
+     * `opts.toolset` mirrors `eligibleTools()` — when supplied, tools whose
+     * `toolset` doesn't match (and isn't `"*"` / unset) are NOT registered into
+     * Pi. The same value must be threaded into both `toolNames(opts)` (for the
+     * unknown-tool guard's allowlist) and the factory so the two views agree.
+     */
+    toPiExtensionFactory(opts?: {
+        toolset?: string;
+        agentId?: string;
+        sessionKey?: string;
+    }): ExtensionFactory;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/agents/extensions/registry.d.ts.map

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