@wrongstack/plugin-sdk 0.308.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ECOSTACK TECHNOLOGY OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @wrongstack/plugin-sdk
+
+Authoring SDK for [WrongStack](../../README.md) plugins. Third-party plugin
+authors should depend on **this package only** — it exposes the plugin
+contract, the `definePlugin` helper, and the same audit-hardened runtime
+helpers the built-in plugins use.
+
+```bash
+npm install @wrongstack/plugin-sdk
+```
+
+## Minimal plugin
+
+```ts
+import { definePlugin } from '@wrongstack/plugin-sdk';
+
+export default definePlugin(
+  {
+    name: 'wstack-plugin-hello',
+    version: '1.0.0',
+    description: 'Greets the team',
+    capabilities: { tools: true },
+    defaultConfig: { greeting: 'hello' },
+  },
+  async (api, options) => {
+    api.tools.register({
+      name: 'hello_greet',
+      description: `Say ${options.greeting} to someone`,
+      inputSchema: {
+        type: 'object',
+        properties: { who: { type: 'string' } },
+        required: ['who'],
+      },
+      permission: 'auto',
+      riskTier: 'safe',
+      async execute(input) {
+        return { greeting: `${options.greeting}, ${input.who}!` };
+      },
+    });
+  },
+);
+```
+
+`definePlugin` injects the current `KERNEL_API_VERSION` for you. If you
+write the plugin object by hand instead, declare the contract version
+your plugin was built against:
+
+```ts
+import { KERNEL_API_VERSION } from '@wrongstack/plugin-sdk';
+
+export const plugin = {
+  name: 'wstack-plugin-hello',
+  apiVersion: '^0.1', // keep loading across additive host releases
+  // ...
+  async setup(api) {},
+};
+```
+
+## What's in the box
+
+| Import | Purpose |
+|---|---|
+| `definePlugin` | Typed authoring helper (infers options, injects `apiVersion`) |
+| `KERNEL_API_VERSION` | The host's plugin contract version |
+| `Plugin`, `PluginAPI`, `PluginCapabilities`, … | The full plugin contract types |
+| `HookEvent`, `HookOutcome`, `InProcessHook`, … | Lifecycle hook types (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `Stop`) |
+| `AgentExtension`, `ProviderRunnerWrapper`, … | Agent-loop extension point types |
+| `Tool`, `EventName`, `Config`, `ConfigStore` | Registry, event, and config types |
+| `@wrongstack/plugin-sdk/runtime` | Bounded collections, `releaseHandles`, sandboxed paths (`safePath`, `isInsideProject`), ReDoS guards (`withReDoSGuard`), safe runner spawning (`resolveRunnerCommand`, `runRunnerCommand`), optional-LLM helpers (`runOptionalPluginLlm`, `runOptionalPluginCouncil`) |
+
+## Versioning
+
+The SDK tracks the host's **plugin contract** (`KERNEL_API_VERSION`), not the
+host package version. Pin `apiVersion: '^0.1'` for additive compatibility;
+the host refuses plugins whose declared range no longer satisfies the kernel
+(see `docs/plugin-third-party.md` in the repository for the compatibility
+policy and release checklist).
+
+## Loading your plugin in WrongStack
+
+```bash
+# register an npm-installed package (installs into ~/.wrongstack/plugins,
+# scripts disabled by default for supply-chain safety)
+wstack plugin add wstack-plugin-hello --install
+
+# or point at local code during development
+wstack plugin add ./my-plugin          # writes { name, path } into config.plugins
+```
+
+External plugins run in-process with full host privileges. On first load the
+host pins a SHA-256 of your plugin's entry file
+(`~/.wrongstack/plugin-trust.json`); after an update, users re-confirm with
+`wstack plugin trust <name>`. See `docs/plugin-author-guide.md` for the full
+isolation and capability-enforcement model.

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @wrongstack/plugin-sdk — the authoring surface for WrongStack plugins.
+ *
+ * Third-party plugins should depend on THIS package (not on
+ * `@wrongstack/core` or `@wrongstack/plugins`) to compile against the
+ * plugin contract. It re-exports:
+ *
+ *   - `definePlugin` — ergonomic authoring helper that infers option types
+ *     and injects the current `apiVersion`,
+ *   - `KERNEL_API_VERSION` — the host contract version to pin against,
+ *   - every type a plugin's manifest, hooks, tools, and config schema need.
+ *
+ * Runtime helpers (bounded collections, safe process spawning, sandboxed
+ * paths, optional-LLM plumbing) live in `@wrongstack/plugin-sdk/runtime`.
+ *
+ * Versioning: the SDK follows the host's plugin contract
+ * (`KERNEL_API_VERSION`). Declare `apiVersion: '^0.1'` (or use
+ * `definePlugin`, which does it for you) so your plugin keeps loading
+ * across additive host releases.
+ */
+export { definePlugin, KERNEL_API_VERSION } from '@wrongstack/core/plugin';
+export type { JSONSchema, Plugin, PluginAPI, PluginCapabilities, PluginConfigFieldMetadata, PluginConfigFieldLifecycle, PluginDependency, PluginPipelines, PluginRuntime, } from '@wrongstack/core/types';
+export type { AnyHookOutcome, HookEvent, HookInput, HookInvocationContext, HookMatcher, HookOutcome, HookRegistrationOptions, InProcessHook, PreToolUseOutcome, } from '@wrongstack/core/types';
+export type { AfterIterationHook, AfterRunHook, AfterToolExecutionHook, AgentExtension, BeforeIterationHook, BeforeRunHook, BeforeToolExecutionHook, OnErrorHook, ProviderRunnerFn, ProviderRunnerWrapper, } from '@wrongstack/core/extension';
+export type { SystemPromptContributor } from '@wrongstack/core/types';
+export type { Tool, ToolCallContext } from '@wrongstack/core/types';
+export type { EventName, Listener } from '@wrongstack/core/kernel';
+export type { Config, ConfigStore, PluginConfig } from '@wrongstack/core/types';
+export type { Logger } from '@wrongstack/core/types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,7 @@
+// src/index.ts
+import { definePlugin, KERNEL_API_VERSION } from "@wrongstack/core/plugin";
+export {
+  KERNEL_API_VERSION,
+  definePlugin
+};
+//# sourceMappingURL=index.js.map

package/dist/runtime/bounded-map.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @wrongstack/plugins — bounded key/value cache.
+ *
+ * Several plugins memoise per-path or per-model work in a module-scope
+ * `Map` that is only ever cleared at teardown. In a short test that is
+ * invisible; in a long session over a large repository it is a slow leak —
+ * one entry per file touched, per branch resolved, per model seen — held
+ * for the lifetime of the process.
+ *
+ * `BoundedMap` is a drop-in replacement for those maps: same `get`/`set`/
+ * `delete`/`clear`/`size` surface, plus a hard entry cap with
+ * least-recently-used eviction and an optional per-entry TTL. Nothing
+ * about the call sites has to change beyond the constructor.
+ *
+ * Why LRU rather than insertion-order eviction: the access pattern for
+ * these caches is "a few hot paths, a long tail of cold ones". Evicting by
+ * insertion order throws away the hot entries first, which is exactly
+ * backwards; re-reading a hot entry should keep it.
+ */
+export interface BoundedMapOptions {
+    /** Hard cap on retained entries. Must be a safe integer >= 1. */
+    max: number;
+    /**
+     * Optional per-entry lifetime in ms. An entry older than this is treated
+     * as absent by `get`/`has` and dropped on access. Omit for no expiry.
+     */
+    ttlMs?: number | undefined;
+    /** Clock injection point — tests override this instead of faking timers. */
+    now?: (() => number) | undefined;
+}
+export declare class BoundedMap<K, V> {
+    private readonly map;
+    private readonly max;
+    private readonly ttlMs;
+    private readonly now;
+    /** Entries dropped to stay under `max`. Surfaced by plugin health(). */
+    private evictions;
+    constructor(options: BoundedMapOptions);
+    private expired;
+    get(key: K): V | undefined;
+    /**
+     * Read without promoting the key to most-recently-used. Use for
+     * diagnostics that must not perturb the eviction order.
+     */
+    peek(key: K): V | undefined;
+    has(key: K): boolean;
+    set(key: K, value: V): this;
+    delete(key: K): boolean;
+    clear(): void;
+    get size(): number;
+    /** How many entries have been dropped to respect `max`, since the last clear. */
+    get evictionCount(): number;
+    /** Drop every expired entry. Cheap enough to call from a status tool. */
+    prune(): number;
+    /** Live (non-expired) entries, coldest first. */
+    entries(): IterableIterator<[K, V]>;
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+}
+/**
+ * A `Set` with the same hard cap and LRU eviction as {@link BoundedMap}.
+ *
+ * Plugins use module-scope sets to remember "already reported" keys so a
+ * finding is surfaced once rather than on every scan. That set has to
+ * outlive a single scan, which is why it lives at module scope — but
+ * without a bound it grows one entry per distinct finding for the life of
+ * the process.
+ *
+ * Eviction means a very old key may eventually be reported a second time.
+ * That is the right trade: re-reporting a finding the user last saw
+ * thousands of findings ago is reasonable behaviour, whereas unbounded
+ * growth is not.
+ */
+export declare class BoundedSet<T> {
+    private readonly inner;
+    constructor(options: BoundedMapOptions);
+    has(value: T): boolean;
+    add(value: T): this;
+    delete(value: T): boolean;
+    clear(): void;
+    get size(): number;
+    /** How many entries have been dropped to respect `max`, since the last clear. */
+    get evictionCount(): number;
+    values(): IterableIterator<T>;
+    [Symbol.iterator](): IterableIterator<T>;
+}
+//# sourceMappingURL=bounded-map.d.ts.map

package/dist/runtime/credential-patterns.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @wrongstack/plugins — canonical credential-pattern table.
+ *
+ * Two plugins detect credentials, at different points in the pipeline:
+ *
+ *  - `secret-scanner` gates tool *input* and inspects tool *output*.
+ *  - `prompt-firewall` inspects the outgoing *provider request* (and the
+ *    response) so a credential sitting in context is not shipped to a
+ *    third party.
+ *
+ * They previously each carried their own pattern list. The lists drifted:
+ * one grew GitLab, npm, SendGrid and DigitalOcean coverage while the other
+ * did not, so which credentials were caught depended on which side of the
+ * pipeline they crossed. A credential is a credential — the two surfaces
+ * should never disagree about what one looks like.
+ *
+ * This module is the single source of truth. Adding a pattern here
+ * strengthens both surfaces at once.
+ *
+ * Style notes for new entries:
+ *  - Prefer explicit lookaround boundaries — `(?<![A-Za-z0-9])` /
+ *    `(?![A-Za-z0-9])` — over ``. `` is defined against word
+ *    characters, so it silently fails next to the `+`, `/` and `=` that
+ *    base64-shaped secrets routinely end with.
+ *  - Keep every group non-capturing (`(?:…)`). The combined regex maps a
+ *    capture-group index back to the pattern that fired; an inner group
+ *    shifts that mapping. `secret-scanner` compensates for user-supplied
+ *    patterns, but built-ins should not need it.
+ *  - Avoid unbounded `.*` lookarounds: these run on every provider
+ *    request, against the full context.
+ */
+/** One credential shape, with a stable machine-readable id. */
+export interface CredentialPattern {
+    /** Stable id, e.g. `github_pat`. Reported to users and in metrics. */
+    type: string;
+    /** Global-flagged matcher. */
+    regex: RegExp;
+}
+export declare const CREDENTIAL_PATTERNS: readonly CredentialPattern[];
+/** Fresh, independently-stateful copies (RegExp `lastIndex` is mutable). */
+export declare function cloneCredentialPatterns(): CredentialPattern[];
+//# sourceMappingURL=credential-patterns.d.ts.map

package/dist/runtime/h1-state.d.ts

@@ -0,0 +1,62 @@
+/**
+ * H1 idempotent state — single-slot plugin state with a registry of
+ * releasable handles that survives `setup()` reload cycles.
+ *
+ * The "H1 audit pattern" (per SAGE memory T-03) is documented across
+ * the plugin suite: a plugin's module-scope `state` object holds
+ * counters plus a `hookUnregister` (or `extensionUnregister`) slot;
+ * on reload, the slot MUST be released before a new one is stored.
+ * Every plugin implements this inline with subtle variations:
+ *
+ *   - some use `releaseHandle(state.hookUnregister)` (`accessibility-auditor`)
+ *   - some use `try { state.hookUnregister(); } catch {}` (`config-validator`)
+ *   - some use a single inline `if (state.hookUnregister) { … }` block
+ *
+ * The drift cost: in 4 plugins the prior handle was leaked on reload
+ * because the inline `if` check raced with the new registration.
+ * This helper centralises the contract.
+ *
+ * Contract:
+ *   `createH1State<T>(initial)` returns
+ *     {
+ *       state:    T,                    // the user's mutable state
+ *       register: (key, unregister) => void,
+ *       release:  (key) => void,
+ *       releaseAll: () => void,
+ *     }
+ *
+ * - `register(key, unregister)` releases any prior handle at `key`
+ *   before storing the new one.
+ * - `release(key)` is a no-op if no handle is registered.
+ * - `releaseAll()` releases every registered handle and clears the map.
+ * - A throwing unregister function is swallowed (best-effort), matching
+ *   the existing `releaseHandle` semantics at `runtime/handles.ts`.
+ *
+ * The state object itself is NOT reset by `releaseAll` — counter
+ * reset is the plugin's responsibility (it knows the semantics of its
+ * counters). This helper owns the handle lifecycle only.
+ */
+export type Unregister = () => void;
+export interface H1State<T> {
+    /** The plugin's mutable state. Owned by the caller; never reset by this helper. */
+    state: T;
+    /**
+     * Register an unregister function under `key`. Any prior handle at
+     * `key` is released first. Throwing unregister functions are
+     * swallowed.
+     */
+    register: (key: string, unregister: Unregister | null | undefined) => void;
+    /**
+     * Release the handle at `key` (if any). Idempotent. Throwing
+     * unregister functions are swallowed.
+     */
+    release: (key: string) => void;
+    /** Release every registered handle. Idempotent. */
+    releaseAll: () => void;
+    /** Number of currently registered handles. Observability for health()/status tools. */
+    size: () => number;
+    /** List the registered keys. Order is insertion order; useful for diagnostics. */
+    keys: () => string[];
+}
+export declare function createH1State<T>(initial: T): H1State<T>;
+//# sourceMappingURL=h1-state.d.ts.map

package/dist/runtime/handles.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @wrongstack/plugins — unregister-handle discipline.
+ *
+ * Plugins keep their hook/listener unregister functions in module-scope
+ * state, and every plugin's `setup()` is expected to be idempotent: calling
+ * it twice must not leave two live registrations. The house style calls
+ * this the "H1 pattern".
+ *
+ * The failure mode this helper exists to prevent is subtle and was present
+ * in ~15 plugins: `setup()` reset the handle with
+ *
+ * ```ts
+ * state.hookUnregister = null;   // WRONG
+ * ```
+ *
+ * which drops the only reference to the *previous* registration without
+ * calling it. The old hook stays live in the registry, unreachable, and
+ * fires alongside the new one — so counters double, warnings appear twice,
+ * and a gate can block on a stale closure holding the previous config.
+ *
+ * `releaseHandle` makes the correct spelling a one-liner with the same
+ * shape as the wrong one, so the two are hard to confuse:
+ *
+ * ```ts
+ * state.hookUnregister = releaseHandle(state.hookUnregister);
+ * ```
+ */
+/** An unregister function returned by `registerHook`/`onEvent`/etc. */
+export type Unregister = (() => void) | null | undefined;
+/**
+ * Invoke `off` if present, swallowing any error, and return `null` so the
+ * caller can assign the result straight back to the handle.
+ *
+ * Unregistering is best-effort by design: a handle whose owner has already
+ * been torn down may throw, and that must never prevent the rest of
+ * `setup()`/`teardown()` from running.
+ */
+export declare function releaseHandle(off: Unregister): null;
+/**
+ * Release several handles held on one state object, clearing each in place.
+ *
+ * @example
+ * releaseHandles(state, ['hookUnregister', 'postHookUnregister']);
+ */
+export declare function releaseHandles<S extends object, K extends keyof S>(state: S, keys: readonly K[]): void;
+//# sourceMappingURL=handles.d.ts.map

package/dist/runtime/index.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @wrongstack/plugins — Language-agnostic runtime helper.
+ *
+ * Plugins that need to invoke a build-time or test-time tool
+ * (TypeScript's `tsc`, Node's `vitest`, Python's `pytest`, Rust's
+ * `cargo`, Go's `go test`, etc.) share this module instead of
+ * re-implementing argv/sandbox/allowlist logic.
+ *
+ * Why one module instead of three plugin-local copies?
+ * - One audit surface for security-sensitive code: arg-splitting,
+ *   sandboxing, execFile-with-shell-false, maxBuffer, timeout.
+ * - Plugins stay focused on their domain (linters, type-checkers,
+ *   test runners); the runtime helper owns the cross-cutting concern.
+ * - New languages opt in by adding a `LanguageRuntime` entry; the
+ *   plugin layer keeps working unchanged.
+ *
+ * The public API is intentionally small:
+ *   - `LanguageRuntime`: declares which language a plugin targets.
+ *   - `resolveRunnerCommand(runtime, command, options)`: validate +
+ *     split a user-supplied command into a safe argv array.
+ *   - `sanitizeRunnerPath(value, options)`: reject paths outside
+ *     the project or that start with `-` (option smuggling).
+ *   - `runRunnerCommand(argv, options)`: spawn the resolved argv
+ *     with `shell:false`, capture stdout/stderr/code, and apply
+ *     timeout/abort.
+ *   - `probeRunner(runtime, argv, options)`: cheap availability check.
+ *
+ * Anything language-specific (flag tables, default commands,
+ * output parsing) stays in the plugin that owns that language.
+ */
+export { parseLlmJsonObject, runOptionalPluginCouncil, runOptionalPluginLlm, stripOuterMarkdownFence, type OptionalCouncilRequest, type OptionalLlmRequest, type OptionalLlmResult, } from './llm.js';
+export { BoundedMap, BoundedSet, type BoundedMapOptions } from './bounded-map.js';
+export { cloneCredentialPatterns, CREDENTIAL_PATTERNS, type CredentialPattern, } from './credential-patterns.js';
+export { UNSERIALIZABLE, safeJsonStringify } from './safe-json.js';
+export { releaseHandle, releaseHandles, type Unregister } from './handles.js';
+export { withReDoSGuard, guardedMatcher, type ReDoSResult, type ReDoSOptions, } from './redos-guard.js';
+export { safePath, isInsideProject, type SafePathOptions, } from './sandbox.js';
+export { createH1State, type H1State, } from './h1-state.js';
+export { clearLocalBinCache, findOnPath, resolveExecInvocation, resolveFirstNodeBin, resolveNodeBin, resolveWin32Command, type ExecInvocation, type ResolvedNodeBin, } from './local-bin.js';
+export type LanguageId = 'typescript' | 'javascript' | 'python' | 'go' | 'rust' | 'shell' | 'ruby' | 'java' | 'kotlin' | 'dotnet' | 'generic';
+export type PackageManagerId = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'pip' | 'poetry' | 'go' | 'cargo' | 'gem' | 'maven' | 'gradle' | 'dotnet' | 'none';
+export interface LanguageRuntime {
+    /** Stable identifier for diagnostics and logging. */
+    id: LanguageId;
+    /**
+     * Default package manager launcher if the plugin must spawn a tool
+     * (e.g. `npx vitest` or `cargo test`). `none` means the executable
+     * itself is invoked directly (no launcher).
+     */
+    packageManager: PackageManagerId;
+    /**
+     * Executable token that must appear as the second argv element when
+     * a launcher is used (e.g. `vitest` after `pnpm exec`, `test` after
+     * `cargo`). When `subcommands.length === 0` and the package manager
+     * has no subcommand step, this is also accepted as the head token.
+     */
+    executable: string;
+    /**
+     * Allowlisted flag values, in addition to positional arguments and
+     * file paths. `null` means "no flag allowlist enforced" — every
+     * leading-dash token is still rejected, but no flag whitelist applies.
+     */
+    allowedFlags: ReadonlySet<string> | null;
+    /**
+     * Optional list of subcommand tokens that may follow the launcher,
+     * e.g. `['exec']` for `pnpm exec tsc`. Empty array means the runner
+     * executable must appear immediately as the second token (e.g.
+     * `cargo test`, `go test`).
+     */
+    subcommands: readonly string[];
+    /**
+     * Default command spelling for `resolveRunnerCommand` when no
+     * custom command is supplied. Plugins can override via config.
+     */
+    defaultCommand: string;
+}
+export interface ResolvedCommand {
+    cmd: string;
+    args: readonly string[];
+    display: string;
+}
+export interface ResolveOptions {
+    /**
+     * Project root used to sandbox absolute executable paths. Defaults
+     * to `process.cwd()`. Absolute executable paths must resolve inside
+     * this directory; relative basenames must match `LanguageRuntime.executable`.
+     */
+    projectRoot?: string;
+}
+export interface RunOptions extends ResolveOptions {
+    cwd: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}
+export interface RunResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    /** True when the executable could not be spawned (ENOENT, EPERM, …). */
+    spawnError: boolean;
+}
+/**
+ * Validate `value` as a sandboxed path inside the project. Returns the
+ * canonical absolute path on success, `null` on rejection (empty,
+ * outside the project, leading-dash, or longer than 4096 bytes).
+ */
+export declare function sanitizeRunnerPath(value: string, options?: ResolveOptions): string | null;
+/**
+ * Resolve a user-supplied command string into an argv-style invocation
+ * using the language runtime's allowlist. Returns `null` if the command
+ * fails closed (unknown launcher, unknown subcommand, disallowed flag,
+ * metacharacters, leading-dash injection, absolute-path escape).
+ */
+export declare function resolveRunnerCommand(runtime: LanguageRuntime, command: string, options?: ResolveOptions): ResolvedCommand | null;
+/**
+ * Spawn the resolved argv with `shell:false`. Always uses
+ * `execFile` (no shell, argv), captures stdout/stderr with a hard
+ * `maxBuffer`, and respects `signal` + `timeoutMs`. Plugins can layer
+ * language-specific output parsing on top of `RunResult`.
+ */
+export declare function runRunnerCommand(argv: readonly string[], options: RunOptions): Promise<RunResult>;
+/**
+ * Cheap availability check. Calls the runner's `--version`-like command
+ * with a short timeout; returns true only when exit code is zero.
+ */
+export declare function probeRunner(runtime: LanguageRuntime, probeArg: string | undefined, options: RunOptions): Promise<boolean>;
+/**
+ * Check whether a file path is inside the project root. Uses
+ * `process.cwd()` as the project boundary. Returns `true` for valid
+ * paths inside the project, `false` for empty, too-long, outside,
+ * or absolute paths that escape.
+ *
+ * This is the canonical sandbox check that every file-mutating or
+ * file-reading plugin should call before touching a path supplied
+ * by tool input. It replaces 27 identical copies across plugins.
+ *
+ * Performance: caches `process.cwd()` per call to avoid redundant
+ * syscalls when checking multiple paths in the same tick.
+ */
+export declare function withinProject(p: string): boolean;
+/**
+ * Convenience: locate the runner binary on disk inside the project.
+ * Returns the absolute path or `null`.
+ */
+export declare function locateRunnerEntry(runtime: LanguageRuntime, projectRoot: string): string | null;
+export interface CollectOptions {
+    /** File extensions to include (e.g. ['.ts', '.tsx', '.js']). */
+    extensions: string[];
+    /** Directory names to skip entirely. Default skips node_modules, dist, .git, coverage. */
+    excludeDirs?: string[] | undefined;
+    /** Maximum recursion depth. Unlimited when omitted. */
+    maxDepth?: number | undefined;
+}
+/**
+ * Recursively collect files under `root` whose extension is in
+ * `opts.extensions`. Skips directories named in `opts.excludeDirs`
+ * (defaulting to node_modules, dist, .git, coverage) and limits depth
+ * when `opts.maxDepth` is set.
+ *
+ * Shared by 6+ plugin source-scan tools that previously duplicated
+ * this implementation identically.
+ *
+ * Determinism: returns files in sorted order (locale-aware) so
+ * scan results are reproducible across platforms and file systems.
+ */
+export declare function collectSourceFiles(root: string, opts: CollectOptions): string[];
+/**
+ * Async version of `collectSourceFiles` for non-blocking file collection.
+ * Uses `fs.promises` to avoid blocking the event loop on large directory trees.
+ *
+ * Performance: prefer this in hooks and tools that run on every write/edit
+ * (e.g., duplicate-code-detector) to keep the agent loop responsive during
+ * large scans.
+ */
+export declare function collectSourceFilesAsync(root: string, opts: CollectOptions): Promise<string[]>;
+/**
+ * Check whether `p` has one of the given extensions (case-insensitive).
+ * Replaces a 6-copy helper that was duplicated identically across
+ * source-scan plugins.
+ */
+export declare function matchesExtension(p: string, exts: string[]): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/llm.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Small, shared helpers for optional plugin LLM enrichment.
+ *
+ * The host-owned `api.llm` facade keeps provider credentials and routing out
+ * of plugins. These helpers standardise the other half of that contract:
+ * bounded prompts, cancellation, defensive response parsing, and an explicit
+ * deterministic fallback when no provider is wired or generation fails.
+ */
+import type { CouncilOption, PluginAPI, PluginLLMOptions } from '@wrongstack/core/types';
+export interface OptionalLlmResult<T> {
+    used: boolean;
+    value: T | null;
+    fallbackReason: 'not-requested' | 'unavailable' | 'cancelled' | 'provider-error' | 'invalid-response' | null;
+}
+export interface OptionalLlmRequest<T> {
+    requested: boolean;
+    prompt: string;
+    options?: PluginLLMOptions | undefined;
+    parse(text: string): T | null;
+    api: Pick<PluginAPI, 'llm' | 'log'>;
+    label: string;
+}
+export interface OptionalCouncilRequest<T> extends OptionalLlmRequest<T> {
+    context?: string | undefined;
+    profile?: string | undefined;
+    councilOptions?: readonly CouncilOption[] | undefined;
+}
+/** Remove one outer Markdown fence without modifying inner code fences. */
+export declare function stripOuterMarkdownFence(text: string): string;
+/** Parse a JSON object from a plain or fenced provider response. */
+export declare function parseLlmJsonObject(text: string): Record<string, unknown> | null;
+/**
+ * Run optional enrichment without turning a provider outage into a tool
+ * failure. Abort remains observable as a fallback reason and the caller's
+ * deterministic result remains authoritative.
+ */
+export declare function runOptionalPluginLlm<T>(request: OptionalLlmRequest<T>): Promise<OptionalLlmResult<T>>;
+/**
+ * Prefer the host Council for consequential analysis, then degrade through the
+ * same One Shot helper and finally the caller's deterministic result. Council
+ * outages therefore never turn an optional enrichment into a tool failure.
+ */
+export declare function runOptionalPluginCouncil<T>(request: OptionalCouncilRequest<T>): Promise<OptionalLlmResult<T>>;
+//# sourceMappingURL=llm.d.ts.map