@khorsheed/dsh-capability-catalog 0.1.95

package/lib/types/index.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Capability catalog host service: a Typert Remote over the running skill and
+ * tool registries. It projects `ctx.skills.snapshot()` into catalog rows,
+ * attributes `ctx.tools.schemas()` to a channel (mcp prefix / official
+ * whitelist / baseline-diff), loads per-skill detail on demand, writes
+ * declared credentials, and adds skills into the managed root. The browser
+ * half binds through the generated `capabilityCatalog` Remote namespace.
+ *
+ * Zero host edits: everything rides existing official services (`ctx.skills`,
+ * `ctx.tools`, `ctx.credentials`) through `ctx.get`, degrading silently when a
+ * capability is absent.
+ * @module @khorsheed/dsh-capability-catalog
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { CapabilityCatalogSnapshot, CatalogAddSkillRequest, CatalogAddSkillResult, CatalogCredentialSetRequest, CatalogDeleteSkillResult, CatalogMcpServerConfig, CatalogMcpSnapshot, CatalogMcpTool, CatalogModeFace, CatalogSkillDetail, CatalogSkillFileRead, CatalogDirSkillInfo, CatalogPresetScopeStatus, CatalogPresetOption, CatalogPresetScopeSetRequest, CatalogPresetScopeAdoptRequest, CatalogPresetScopeEditResult } from './types.ts';
+export { TOOL_ORIGIN, setToolOrigin, toolOrigin } from './tool-origin.ts';
+export type { ToolOrigin } from './tool-origin.ts';
+export type { CapabilityCatalogSnapshot, CatalogJsonValue, CatalogSkillRow, CatalogToolRow, CatalogMcpServerRow, CatalogChannelSummary, CatalogSkillDetail, CatalogSkillFileRead, CatalogCredentialState, CatalogAddSkillRequest, CatalogAddSkillResult, CatalogDeleteSkillResult, CatalogCredentialSetRequest, CatalogPresetScopeStatus, CatalogScopedSkillRow, CatalogScopedPresetRow, CatalogPresetOption, CatalogModeFace, CatalogPresetScopeSetRequest, CatalogPresetScopeAdoptRequest, CatalogPresetScopeEditResult, } from './types.ts';
+export { resolveSkillNameFromContent } from './import.ts';
+export { resolvePresetScope } from './preset-scope.ts';
+export type { PresetRosterSlice, PresetRosterRow, ResolvedPresetScope } from './preset-scope.ts';
+export { modeOptions, readModeFaces } from './modes.ts';
+export { ScopedSkillDelivery, scopedSkillsRoot, scanManagedSkills, managedSkillFrom, parsePresetScopeFrontmatter, defaultSkillRoots, detectConflicts, SCOPED_PROVIDER_NAME, MANAGED_SKILL_RANK, } from './scoped-delivery.ts';
+export { adoptManagedSkill, releaseManagedSkill, setManagedPresetScope, withPresetScope, findSkillSource, managedLocation, isDirectory, } from './scoped-edits.ts';
+export type { ScopedEditResult, SkillSource, ManagedSkillLocation } from './scoped-edits.ts';
+export type { ManagedSkill, ScopedDeliveryDeps, ScopedDeliveryRegistry, ScopedDeliveryStatus, ScopedPresetStatus, ScopedSkillStatus, } from './scoped-delivery.ts';
+export { canonicalCapabilities, canonicalJson, capsTag, hashOf, hashSkillBody, CAPS_TAG_PREFIX, } from './capabilities.ts';
+export type { CanonicalCapabilities, CanonicalMcpServer, CanonicalSkill, CanonicalTool, } from './capabilities.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        capabilityCatalog: CapabilityCatalogService;
+    }
+}
+/** The remote namespace name (matches the generated remote-client type). */
+export declare const REMOTE_NS = "capabilityCatalog";
+/**
+ * Capability catalog Remote service.
+ * @module @khorsheed/dsh-capability-catalog
+ */
+export declare class CapabilityCatalogService extends TypertRemoteService {
+    config: {
+        mcp?: unknown;
+    };
+    static inject: never[];
+    static Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+        mcp: import("@deepseek-ai/schemastery").default<any, any>;
+    }>, Schemastery.ObjectT<{
+        mcp: import("@deepseek-ai/schemastery").default<any, any>;
+    }>>;
+    private baseline;
+    private readonly appearedAfterApply;
+    private readonly mcp;
+    /** The live `ctx.tools` (traceable proxy) captured from the tools inject. */
+    private mcpToolsRegistry;
+    /** Registered MCP tool disposers, keyed by model-facing public name. */
+    private readonly mcpToolDisposers;
+    /** Preset-scoped delivery of the plugin's own managed skill root. */
+    private scoped;
+    /** The workspace the catalog was last asked about, for project-root conflict checks. */
+    private observedWorkdir;
+    constructor(ctx: Context, config: {
+        mcp?: unknown;
+    });
+    /** The preset-scoped delivery's current state, for the settings surface. */
+    presetScopeStatus(): Promise<CatalogPresetScopeStatus>;
+    /** Every preset the roster supplies, for the scope picker. */
+    presetScopeRoster(): Promise<readonly CatalogPresetOption[]>;
+    /**
+     * Every mode's capability face in ONE call, for the cross-mode comparison
+     * view ("which modes load this tool/skill?").
+     *
+     * This is the expensive verb of the pair: a mode whose standing scope has not
+     * been composed yet is MOUNTED by its read (see modes.ts — there is no cheap
+     * honest source, because a composition file names plugins, not the tools and
+     * skills those plugins register). The browser therefore calls it only when a
+     * human chooses to compare modes, never on opening the section.
+     *
+     * A mode that cannot be read keeps its row with `unavailable` set rather than
+     * an empty face, so the comparison never claims that a broken mode loads
+     * nothing. `preset` on a face is always the id that was asked for: a read
+     * that silently degraded to the global layer is reported as unavailable, not
+     * as that mode's face.
+     * @param workdir - optional cwd for project-scoped skill roots.
+     */
+    modeFaces(workdir?: string): Promise<readonly CatalogModeFace[]>;
+    /** The roster rows, or [] when this composition mounts no agent-preset service. */
+    private rosterRows;
+    /** Declare which presets one managed skill is delivered to. */
+    presetScopeSet(request: CatalogPresetScopeSetRequest): Promise<CatalogPresetScopeEditResult>;
+    /** Move an installed skill into the managed root with a preset scope. */
+    presetScopeAdopt(request: CatalogPresetScopeAdoptRequest): Promise<CatalogPresetScopeEditResult>;
+    /** Move a managed skill back to the user skill root (the recovery direction). */
+    presetScopeRelease(name: string): Promise<CatalogPresetScopeEditResult>;
+    /** Re-deliver after a write; a delivery that is absent is not an error. */
+    private reconcileScoped;
+    /** Record tools that appeared after the apply-time baseline (reads the live
+     * registry each time, so a change event never sees a stale/undefined ref). */
+    private markNewTools;
+    /** The managed skills root under `$DSH_HOME`. */
+    private dshHome;
+    /**
+     * The standing skill view scope of ONE preset. In the web bundle the
+     * host-global skill-filesystem provider is mounted under each agent
+     * preset's standing scope, so a host-global snapshot sees only runtime
+     * skills; reading at the preset's scope surfaces the official/plugin/user
+     * skills the model actually sees. When the presets service is absent the
+     * catalog degrades to the global layer alone.
+     *
+     * `presetId` names WHICH preset — the deployment default when omitted, the
+     * way every reader before `snapshotFor` behaved. The roster's scope face
+     * (0.1.5's `standingKeyFor`, rc.1's leased `acquireScope`) has always taken
+     * an id; the catalog simply never passed one, so "the capability face of
+     * preset X" was unaskable and a condition declaring `preset: X` could only
+     * be believed.
+     *
+     * `strict` is the listing/fingerprint split — see
+     * {@link resolvePresetScope}, which owns the policy.
+     * @param presetId - the preset to read, or undefined for the default.
+     * @param strict - throw instead of degrading when the roster cannot answer.
+     */
+    private catalogScope;
+    /** Release a scope lease, logging rather than failing the read it followed. */
+    private releaseScope;
+    /** The optional agent-preset roster (absent in a rosterless composition). */
+    private agentPresets;
+    /** Register the model-facing `list_capabilities` tool (optional; called from the
+     * tools inject so the registry is guaranteed present). */
+    private registerListTool;
+    snapshot(workdir?: string): Promise<CapabilityCatalogSnapshot>;
+    /**
+     * The capability face of ONE mode as a LISTING — {@link snapshot} scoped to a
+     * named preset, for the settings surface's mode picker.
+     *
+     * The LISTING/FINGERPRINT split matters here the way it does everywhere else:
+     * a viewer wants rows as fast as the registries can produce them, not every
+     * skill body loaded and digested. Asking for a preset's IDENTITY is
+     * {@link snapshotFor}. Like every scope resolution, this MOUNTS a preset
+     * nothing has composed yet.
+     *
+     * Degrades like {@link snapshot}: a preset whose standing scope refuses
+     * answers with the global layer and NO `preset` stamp, which is how a caller
+     * tells "this mode" from "the fallback" and says so.
+     * @param presetId - the mode to read, or undefined for the deployment default.
+     * @param workdir - optional cwd for project-scoped skill roots.
+     */
+    snapshotAt(presetId?: string, workdir?: string): Promise<CapabilityCatalogSnapshot>;
+    /**
+     * The capability face of ONE preset, with its {@link hashOf} digest.
+     *
+     * This is the fingerprint verb: every skill body is loaded (so the rows
+     * carry `bodySha`) and `sha` is stamped, which is what makes the answer an
+     * identity rather than a listing. `presetId` omitted reads the deployment
+     * default — the same face `snapshot` reads, now hashable.
+     *
+     * Degrades like every other verb: without a skills registry the answer is
+     * an empty face with the hash of an empty face, not a throw. Note that a
+     * preset nobody has composed yet is MOUNTED by the read (the roster's
+     * single-flight standing mount), so asking is not free.
+     * @param presetId - the preset to fingerprint, or undefined for the default.
+     * @param workdir - optional cwd for project-scoped skill roots.
+     */
+    snapshotFor(presetId?: string, workdir?: string): Promise<CapabilityCatalogSnapshot>;
+    /**
+     * Shared body of {@link snapshot} and {@link snapshotFor}. The scope is
+     * resolved ONCE — three resolutions of a mounting preset would race the
+     * roster's single-flight for no reason — and `fingerprint` makes the
+     * resolution strict.
+     */
+    private collect;
+    detail(name: string, workdir?: string, presetId?: string): Promise<CatalogSkillDetail | undefined>;
+    readSkillFile(name: string, filePath: string, workdir?: string, presetId?: string): Promise<CatalogSkillFileRead | undefined>;
+    /** One managed skill's definition, for management reads outside its scope. */
+    private managedDefinition;
+    listDirSkills(dirPath: string): Promise<readonly CatalogDirSkillInfo[]>;
+    setCredential(request: CatalogCredentialSetRequest): Promise<boolean>;
+    addSkill(request: CatalogAddSkillRequest): Promise<CatalogAddSkillResult>;
+    deleteSkill(name: string, workdir?: string, presetId?: string): Promise<CatalogDeleteSkillResult>;
+    pickDirectory(): Promise<string | null>;
+    mcpList(): Promise<readonly CatalogMcpServerConfig[]>;
+    mcpAdd(config: CatalogMcpServerConfig): Promise<boolean>;
+    mcpRemove(serverName: string): Promise<boolean>;
+    mcpSetEnabled(serverName: string, enabled: boolean): Promise<void>;
+    mcpSetCredential(ref: string, value: string): Promise<boolean>;
+    mcpSetToolEnabled(serverName: string, tool: string, enabled: boolean): Promise<void>;
+    mcpDiscover(serverName: string): Promise<readonly CatalogMcpTool[]>;
+    mcpSnapshot(): Promise<CatalogMcpSnapshot>;
+    /** The visible tool schemas in the standing scope (the set the model sees),
+     * or the global layer when no preset standing key resolves. Skills already
+     * enumerate through the same scope; tools must use it too so the
+     * settings reader sees the official/plugin/MCP tools the model actually has. */
+    private toolSchemasIn;
+    /** tool name → author-declared origin, read via `ctx.tools.get(name)` so the
+     * `Symbol.for('dsh.tool.origin')` tag on the retained definition survives (the
+     * system-prompt assembly strips it, but `get()` returns the full definition). */
+    private toolOriginsMap;
+    /** MCP server names from live `mcp__`-prefixed tools (prefix-derived baseline). */
+    private mcpServerNamesIn;
+    /**
+     * Reconcile which discovered MCP tools are registered on `ctx.tools` so the
+     * model can call them. `mcpToolsRegistry` is the traceable `ctx.tools` proxy,
+     * so `register` is always invoked as a MEMBER call (`reconcile` calls
+     * `registry.register(...)`) — extracting it to a standalone variable loses the
+     * `this.ctx` binding and breaks the disposal effect.
+     */
+    private syncRegisteredMcpTools;
+    /** Re-sync registered MCP tools after any MCP store mutation. */
+    private afterMcpMutation;
+    /** Refill the persisted MCP tools' descriptions/parameters by re-connecting the
+     * enabled servers at boot (the persisted `mcp` block stores only name+enabled to
+     * keep settings.yaml small). Async: boot is not blocked; each server's errors are
+     * contained, and registration is re-synced once the descriptions are back. */
+    private reconnectEnabledMcp;
+}
+export default CapabilityCatalogService;
+//# sourceMappingURL=index.d.ts.map