@qodo/sdk 0.13.4 → 2.0.0-next.0

package/dist/skills/manager.browser.js

@@ -0,0 +1,159 @@
+/**
+ * `SkillsManager` — browser stub.
+ *
+ * The Node version walks the filesystem to discover `SKILL.md` files,
+ * which is fundamentally Node-only. In the browser there is no
+ * filesystem, no `node_modules`, no `~/.qodo/skills`. Rather than
+ * polyfill, the stub throws a clear error directing the consumer to
+ * either:
+ *
+ *   1. Not configure `ClientOptions.skills` in browser code paths
+ *      (the field is optional; omitting it leaves the SDK behaving
+ *      exactly as today).
+ *   2. If skills are needed, run discovery server-side and ship the
+ *      pre-built catalog through their own data plane.
+ *
+ * The Node version of this file is `manager.ts`; the swap is wired via
+ * the `browser` field in `package.json`.
+ */
+const BROWSER_ERROR_MESSAGE = 'SkillsManager requires Node-only APIs (node:fs / node:path / node:os) and is not ' +
+    'supported in the browser bundle. Omit ClientOptions.skills in browser code paths, ' +
+    'or run skill discovery server-side and ship the catalog via your own data plane.';
+export class SkillsManager {
+    constructor(_config) {
+        // Construction succeeds so consumers can hold an instance for type
+        // narrowing; the first method call surfaces the error.
+    }
+    discover() {
+        return Promise.reject(new Error(BROWSER_ERROR_MESSAGE));
+    }
+    forwardEvents(_events) {
+        // no-op — the manager is inert in the browser stub
+    }
+    get isReady() {
+        return false;
+    }
+    get currentSnapshot() {
+        return null;
+    }
+    get defaultActivate() {
+        return undefined;
+    }
+    get indexCharBudget() {
+        return undefined;
+    }
+    get embedder() {
+        return undefined;
+    }
+    get activationConfig() {
+        return undefined;
+    }
+    list(_opts) {
+        return Promise.reject(new Error(BROWSER_ERROR_MESSAGE));
+    }
+    get(_specifier) {
+        return Promise.reject(new Error(BROWSER_ERROR_MESSAGE));
+    }
+    resolveOrThrow(_specifiers) {
+        return Promise.reject(new Error(BROWSER_ERROR_MESSAGE));
+    }
+    // ---------------------------------------------------------------------
+    // Trust / activation surfaces. Inert in the browser stub; the shapes
+    // exist so consumer type imports compile across environments.
+    // ---------------------------------------------------------------------
+    isTrusted(_skill) {
+        return false;
+    }
+    get requiresCapsResolved() {
+        return { maxDepth: 3, maxTransitive: 8, maxTransitiveTokens: 50 * 1024 };
+    }
+    getActiveSkills() {
+        return [];
+    }
+    markActive(_fqn) {
+        return false;
+    }
+    deactivate(_fqn) {
+        return false;
+    }
+    resetActive() {
+        // no-op — the browser stub has no active state
+    }
+    get internalActiveFqns() {
+        // Returning a fresh empty set keeps the cross-environment shape
+        // identical; mutations here are inert because the stub doesn't
+        // back any of the active-state methods with shared state.
+        return new Set();
+    }
+    // ---------------------------------------------------------------------
+    // Hot reload surface. All no-ops in the browser stub.
+    // ---------------------------------------------------------------------
+    startWatching() {
+        return Promise.resolve();
+    }
+    stopWatching() {
+        // no-op
+    }
+    dispose() {
+        // no-op
+    }
+    get catalogEpoch() {
+        return 0;
+    }
+    onRebuild(_listener) {
+        return () => { };
+    }
+    rebuildNow() {
+        return Promise.reject(new Error(BROWSER_ERROR_MESSAGE));
+    }
+}
+export class SkillNotFoundError extends Error {
+    specifier;
+    constructor(specifier) {
+        super(`Skill not found: ${specifier}`);
+        this.name = 'SkillNotFoundError';
+        this.specifier = specifier;
+    }
+}
+export class SkillAmbiguousPinError extends Error {
+    specifier;
+    candidates;
+    constructor(specifier, candidates) {
+        super(`Skill pin "${specifier}" is ambiguous — multiple vendors ship a skill ` +
+            `of that name: ${candidates.join(', ')}. Pin with a full ` +
+            '`vendor/name` specifier to disambiguate.');
+        this.name = 'SkillAmbiguousPinError';
+        this.specifier = specifier;
+        this.candidates = candidates;
+    }
+}
+export class SkillsBudgetExceededError extends Error {
+    omittedSkills;
+    hardCap;
+    constructor(omittedSkills, hardCap) {
+        super(`caller-pinned skills exceeded the slim-index hard cap (${hardCap} chars). ` +
+            `Omitted: ${omittedSkills.join(', ')}. Reduce the pin list or raise ` +
+            '`SkillsConfig.indexCharBudget`.');
+        this.name = 'SkillsBudgetExceededError';
+        this.omittedSkills = omittedSkills;
+        this.hardCap = hardCap;
+    }
+}
+/**
+ * Mirrors the Node-side `QodoSkillError`. Thrown by the activation
+ * pipeline when caller-pin resolution fails (trust violation, cap
+ * breach, cycle, unresolved dep). The browser stub doesn't run the
+ * pipeline, but the class shape is exposed so consumer `catch (err
+ * instanceof QodoSkillError)` blocks compile in both environments.
+ */
+export class QodoSkillError extends Error {
+    skill;
+    reason;
+    constructor(skill, reason, message) {
+        super(message);
+        this.name = 'QodoSkillError';
+        this.skill = skill;
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=manager.browser.js.map

package/dist/skills/manager.browser.js.map

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

package/dist/skills/manager.d.ts

@@ -0,0 +1,362 @@
+/**
+ * `SkillsManager`.
+ *
+ * Walks every configured source, parses + validates each `SKILL.md`, then
+ * builds an in-memory catalog keyed by fully-qualified
+ * `<vendor>/<name>@<version>` with shadowing.
+ *
+ * Construction is synchronous and cheap (validate config, store). The
+ * `discover()` method does the disk IO; it's idempotent — subsequent
+ * calls return the same already-built catalog. Public lookups via
+ * `list()` / `get()` await discovery completion implicitly.
+ *
+ * Invariants:
+ *   - Catalog is built once per discovery; hot reload reruns discovery
+ *     to produce a fresh snapshot.
+ *   - Trust tier is derived from source type only; consumer-supplied
+ *     `trustedSources` is used to elevate third-party sources.
+ *   - Per-skill `min_sdk_version` exclusion lands here.
+ */
+import { type WalkerEnv } from './sources/index.js';
+import type { SourceWalkResult } from './sources/index.js';
+import type { ParsedSkill, SkillEvent, SkillSource, SkillsConfig } from './types.js';
+/**
+ * Lookup options for `SkillsManager.get`. Both fields optional — without
+ * a version pin the manager returns the latest version of the matched
+ * skill.
+ */
+export interface SkillGetOptions {
+    readonly includeAllVersions?: boolean;
+}
+/**
+ * Snapshot of catalog state for tests / introspection. Stable across
+ * discovery completion; the manager never mutates the array after
+ * `discover()` resolves.
+ */
+export interface CatalogSnapshot {
+    readonly skills: readonly ParsedSkill[];
+    /** Source-by-source breakdown — useful for the slim-index source attribution. */
+    readonly bySource: readonly SourceWalkResult[];
+    /** Path-keyed map of skills that were dropped during catalog construction. */
+    readonly excluded: readonly {
+        readonly source: SkillSource;
+        readonly path: string;
+        readonly reason: string;
+    }[];
+    /**
+     * Monotonically-increasing counter bumped on every successful build.
+     * Starts at `1` after the initial `discover()`; each watcher-triggered
+     * rebuild increments by one. Body caches can key by `(fqn, epoch)` to
+     * evict stale entries without race-y read locks.
+     */
+    readonly epoch: number;
+}
+/**
+ * Resolved `requires:` cap configuration with defaults filled in. Each
+ * cap is read by `SkillsManager` consumers (the MCP server's `get_skill`
+ * resolver, the `TaskClient` caller-pin activation path) to enforce the
+ * depth / breadth / token caps uniformly.
+ */
+export interface ResolvedRequiresCaps {
+    readonly maxDepth: number;
+    readonly maxTransitive: number;
+    readonly maxTransitiveTokens: number;
+}
+export declare class SkillsManager {
+    private readonly config;
+    private readonly env;
+    private readonly emit;
+    private readonly trustedSourceIdentities;
+    private readonly requiresCaps;
+    /**
+     * Per-client active-skill set. Populated by caller-pin activation
+     * (`TaskClient`) and by LLM-driven `get_skill` calls (the MCP server,
+     * via `markLoaded`). Cleared by `resetActive()`.
+     *
+     * SDK 2.0 has no per-task AsyncLocalStorage env-scope (the design that
+     * shipped on SDK 1.x's `EnvironmentServices`); active-state lives on
+     * the manager, scoped to the client lifetime. Concurrent dispatches
+     * against the same client observe a merged set — documented in the
+     * architectural-translation note. `disconnect()` calls
+     * `skillsMcpServer.dispose()` which calls `resetActive()` (transitively
+     * through the existing `activeFqns` clear), so a fresh `connect()`
+     * starts cold.
+     */
+    private readonly activeFqns;
+    private discoverPromise;
+    private snapshot;
+    /**
+     * Active `fs.watch` handles keyed by the absolute directory path
+     * being watched. Populated by `startWatching()`, cleared by
+     * `stopWatching()` / `dispose()`.
+     */
+    private watchers;
+    /** Pending watcher-triggered rebuild timer, debounced. */
+    private rebuildTimer;
+    /** Promise that resolves with the next rebuilt snapshot, if a rebuild is in-flight. */
+    private rebuildPromise;
+    /** Optional listener fired after every successful rebuild — used by tests / consumers. */
+    private rebuildListeners;
+    private epoch;
+    /**
+     * In-flight `startWatching()` promise. Concurrent calls await the
+     * same promise so the install pass is serialised — defends against
+     * the watcher-duplication race when auto-start + manual start fire
+     * close together.
+     */
+    private startWatchingPromise;
+    /**
+     * Marks that a watcher event arrived while a rebuild was already
+     * in flight. The current rebuild's `.then` re-schedules so the late
+     * change isn't dropped.
+     */
+    private pendingRebuild;
+    constructor(config: SkillsConfig, env?: WalkerEnv);
+    /**
+     * Forward a renderer-produced event batch to the configured sink.
+     * Used by `TaskClient`'s skills injection helpers — the renderer is
+     * pure and returns events as data; the manager owns the sink wiring
+     * so consumers see one consistent emission surface.
+     */
+    forwardEvents(events: readonly SkillEvent[]): void;
+    /**
+     * Walk every configured source, parse + validate, build the FQN-keyed
+     * catalog. Idempotent — concurrent calls share one in-flight promise.
+     */
+    discover(): Promise<CatalogSnapshot>;
+    /** Resolved `true` once `discover()` has completed at least once. */
+    get isReady(): boolean;
+    /** Synchronous snapshot accessor. Returns `null` until `discover()` resolves. */
+    get currentSnapshot(): CatalogSnapshot | null;
+    /**
+     * Constructor-supplied default `activate` set. `TaskClient` reads this
+     * when the per-call `opts.skills` is `undefined`. Returned read-only;
+     * `[]` and `undefined` are distinct (`[]` = explicit empty, `undefined`
+     * = "no default set").
+     */
+    get defaultActivate(): readonly string[] | undefined;
+    /**
+     * Constructor-supplied `indexCharBudget`. `TaskClient` forwards this
+     * to `renderSlimIndex()` so consumers can tighten the model-visible
+     * block below the 8000-char default. `undefined` means "renderer
+     * picks the default".
+     */
+    get indexCharBudget(): number | undefined;
+    /**
+     * Constructor-supplied `!command` preprocessing config.
+     * `undefined` means "default disabled" — the MCP server's `get_skill`
+     * handler short-circuits when this is `undefined` or `mode: 'disabled'`.
+     */
+    get preprocessingConfig(): SkillsConfig['preprocessing'] | undefined;
+    /**
+     * Constructor-supplied embedder, if any. `undefined` means
+     * "no pre-filter; rely on render-side truncation".
+     */
+    get embedder(): SkillsConfig['embedder'] | undefined;
+    /**
+     * Constructor-supplied embedding-pre-filter tuning. `undefined` means
+     * "use documented defaults" (`topK: 8`, `minScore: 0.35`).
+     */
+    get activationConfig(): SkillsConfig['activation'] | undefined;
+    /**
+     * List every catalog entry. Awaits discovery on first call. Returns
+     * latest-version-only by default; pass `{ includeAllVersions: true }`
+     * to surface every version recorded during discovery.
+     */
+    list(opts?: SkillGetOptions): Promise<readonly ParsedSkill[]>;
+    /**
+     * Resolve a skill specifier (`name`, `vendor/name`, or `vendor/name@version`)
+     * to a `ParsedSkill` or `null` if no match.
+     *
+     * - Bare name: returns the latest-version match of any vendor; if multiple
+     *   vendors ship a skill of that name, the highest-precedence source wins.
+     * - `vendor/name`: latest version of that vendor's skill.
+     * - `vendor/name@version`: exact pin.
+     */
+    get(specifier: string): Promise<ParsedSkill | null>;
+    /**
+     * Verify every name in `specifiers` resolves. Throws on the first
+     * unresolved entry — the SDK uses this from the wire boundary to fail
+     * loud on caller-pinned activation per `skills-activation.md` §2.
+     */
+    resolveOrThrow(specifiers: readonly string[]): Promise<readonly ParsedSkill[]>;
+    /**
+     * Whether `skill` is trusted enough to honor its declarative affordances
+     * (`allowed-tools`, `disable-model-invocation: false`, `hooks`). True for
+     * the `'trusted'` / `'operator'` tiers; for `'third-party'` true iff the
+     * skill's source identity is in `trustedSources`.
+     */
+    isTrusted(skill: ParsedSkill): boolean;
+    /**
+     * Resolved `requires:` caps with defaults filled in. Read by the
+     * activation pipeline (`TaskClient` caller-pin + `QodoSkillsMcpServer.get_skill`).
+     */
+    get requiresCapsResolved(): ResolvedRequiresCaps;
+    /**
+     * Snapshot of currently active skill FQNs. The active set is union of
+     * (a) caller-pinned skills the SDK injected for the latest dispatch and
+     * (b) skills the model loaded via `qodo-skills.get_skill`. Returned
+     * sorted for stable test output.
+     */
+    getActiveSkills(): readonly string[];
+    /**
+     * Mark a skill FQN as active. Idempotent — re-marking emits no extra
+     * event. Returns `true` iff the FQN was newly added (i.e., this is a
+     * fresh activation, not a cache hit).
+     *
+     * The caller is responsible for emitting `sdk.skill.activated` — the
+     * event carries `source: 'caller' | 'llm'` which only the caller knows.
+     * `markActive` just owns the set membership.
+     */
+    markActive(fqn: string): boolean;
+    /**
+     * Remove a skill FQN from the active set. Returns `true` iff it was
+     * present. Used by `QodoSkillsMcpServer.dispose` and (rarely) by
+     * consumers programmatically rolling back activation.
+     */
+    deactivate(fqn: string): boolean;
+    /**
+     * Clear the active set entirely. Called by `QodoSkillsMcpServer.dispose`
+     * on `disconnect()` so the next `connect()` starts cold.
+     */
+    resetActive(): void;
+    /**
+     * Begin watching every configured local source directory for SKILL.md
+     * changes. Idempotent — calling twice has no extra effect.
+     *
+     * Requires `discover()` to have completed; the watcher targets only
+     * directories already known to be on disk. New top-level source dirs
+     * appearing post-startup are NOT auto-watched (operators would
+     * typically `stopWatching()` + reconfigure + start a new client).
+     *
+     * `package` and `bundled` sources are intentionally NOT watched —
+     * those ship with the application code and shouldn't churn at
+     * runtime. Watching them would expose tampering surface without
+     * meaningful upside.
+     *
+     * Default behavior is determined by `SkillsConfig.watch`:
+     * `undefined`/`false` ⇒ no-op; `true` ⇒ start watching after the first
+     * `discover()` resolves.
+     */
+    startWatching(): Promise<void>;
+    private doStartWatching;
+    /**
+     * Tear down every active watcher and cancel any pending debounce
+     * timer. Safe to call multiple times. Called automatically by
+     * `dispose()`.
+     */
+    stopWatching(): void;
+    /**
+     * Tear down the manager — equivalent to `stopWatching()`. Provided as
+     * a parallel to `QodoSkillsMcpServer.dispose()` so consumer code can
+     * call both in a uniform shutdown sequence.
+     */
+    dispose(): void;
+    /** Current catalog epoch counter. `0` before the first `discover()`. */
+    get catalogEpoch(): number;
+    /**
+     * Subscribe to rebuild events. The listener fires after every
+     * successful watcher-triggered rebuild (NOT on the initial discover).
+     * Returns an unsubscribe function. Used primarily by tests.
+     */
+    onRebuild(listener: (snapshot: CatalogSnapshot) => void): () => void;
+    /**
+     * Trigger an out-of-band rebuild. Test seam — production code goes
+     * through the debounced watcher path. The rebuild is in-flight
+     * already if another rebuild is queued; returns the same in-flight
+     * promise to avoid double-rebuild races.
+     */
+    rebuildNow(): Promise<CatalogSnapshot>;
+    private installWatcher;
+    private scheduleRebuild;
+    private doRebuild;
+    private diffAndEmit;
+    /**
+     * Walk every configured source + parse + validate + assemble the
+     * catalog. Pure with respect to `this.snapshot` — the caller decides
+     * how to publish the returned snapshot (initial discover stamps the
+     * epoch; rebuild diffs against the prior snapshot first).
+     */
+    private buildCatalog;
+    /**
+     * Locate + apply the lockfile per `SkillsConfig.lockfile`. When
+     * `'off'`, returns immediately. When `'discover'`, searches the
+     * configured CWD; when an explicit `{ path }`, loads it directly.
+     *
+     * Validation outcomes:
+     *
+     *   - All entries match → return silently.
+     *   - At least one drifts → emit `sdk.skill.lock_drift` per offender + throw.
+     *   - At least one unreachable → emit `sdk.skill.lock_unreachable` + throw.
+     *
+     * Throws `LockfileValidationError` so the wire boundary fails loud
+     * rather than serving a divergent catalog.
+     */
+    private applyLockfile;
+    private resolveSourcesList;
+    private parseAndValidate;
+    /**
+     * Inspect the skill body for `[label](path)` and `get_skill_file("path")`
+     * references; emit:
+     *
+     *   - `sdk.skill.error severity: 'warning'` when the referenced file
+     *     doesn't exist under the skill directory.
+     *   - `sdk.skill.error severity: 'warning'` when a reference has depth
+     *     greater than 1 (e.g. `scripts/helpers/foo.py`). Authors who
+     *     intentionally nest files can ignore this warning.
+     *
+     * The check is best-effort: any `fs.stat` failure other than ENOENT is
+     * silently ignored so a transient filesystem error doesn't poison
+     * discovery.
+     */
+    private auditBodyReferences;
+    private emitEvent;
+}
+/**
+ * Thrown by `SkillsManager.resolveOrThrow` when a caller-pinned specifier
+ * doesn't match anything in the catalog. The wire boundary (TaskClient
+ * startWithAgent / startWithGraph) re-throws these so consumers see a
+ * loud failure per `skills-activation.md` §2.
+ */
+export declare class SkillNotFoundError extends Error {
+    readonly specifier: string;
+    constructor(specifier: string);
+}
+/**
+ * Thrown when a bare-name caller pin matches multiple skills under
+ * different vendors (`acme/code-review` and `local/code-review` both
+ * shipping `name: code-review`). The first-match-wins behavior silently
+ * picked one, which could change at runtime depending on source order.
+ * Force the caller to disambiguate with a `vendor/name` pin.
+ */
+export declare class SkillAmbiguousPinError extends Error {
+    readonly specifier: string;
+    readonly candidates: readonly string[];
+    constructor(specifier: string, candidates: readonly string[]);
+}
+/**
+ * Thrown when caller-pinned skills cannot fit inside the slim-index
+ * hard cap (`2 × charBudget`, floored at `charBudget + 4096`). Pinning
+ * is a "must include" contract — silently dropping pins would make the
+ * model behave as if the caller never pinned them; throwing forces the
+ * caller to fix the pin list or raise the budget.
+ */
+export declare class SkillsBudgetExceededError extends Error {
+    readonly omittedSkills: readonly string[];
+    readonly hardCap: number;
+    constructor(omittedSkills: readonly string[], hardCap: number);
+}
+/**
+ * Thrown when caller-pinned activation can't proceed because of a
+ * `requires:` chain failure — trust violation, depth/breadth/token cap
+ * breach, cycle, or unresolved dependency. The `kind` discriminator
+ * carries the specific reason. Caller-pin
+ * activation is an authoritative contract; failure must be loud rather
+ * than silently dropping the affected skill.
+ */
+export declare class QodoSkillError extends Error {
+    readonly skill: string;
+    readonly reason: 'requires_trust_violation' | 'requires_cap_exceeded' | 'requires_cycle' | 'requires_unresolved' | 'not_found';
+    constructor(skill: string, reason: QodoSkillError['reason'], message: string);
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/skills/manager.d.ts.map

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