dsh-pstack 0.2.0-beta.1 → 0.2.0-beta.3

package/dist/host-contract-CUPSpeNk.d.mts

@@ -0,0 +1,22 @@
+import { Agent, AgentOptions, AgentRegistry } from "@deepseek-ai/dsh-agent";
+import { JobId, JobRegistry } from "@deepseek-ai/dsh-jobs";
+import { LlmRuntime } from "@deepseek-ai/dsh-llm";
+import { SessionId } from "@deepseek-ai/dsh-session";
+import { SkillDefinition, SkillInvocationPolicy, SkillProvider, SkillProviderControl, SkillResourceBase } from "@deepseek-ai/dsh-skill";
+import { SubagentCapabilities, SubagentRuntime } from "@deepseek-ai/dsh-subagent";
+import "@deepseek-ai/dsh-system-prompt";
+import { JsonSchemaNode, ToolDefinition, ToolRuntime } from "@deepseek-ai/dsh-tools";
+import { WorkingDirectoryService } from "@deepseek-ai/dsh-working-directory";
+/** The slice of `ctx.agents` used to reach a child this tool has just started. */
+type AgentsHost = Pick<AgentRegistry, "get">;
+/** The slice of `ctx.llm` used to resolve routes and advertised efforts. */
+type LlmHost = Pick<LlmRuntime, "listProviders" | "listModels" | "resolveModelInfo" | "resolveCallConfig">;
+/** The slice of `ctx.subagents` this plugin drives. */
+type SubagentsHost = Pick<SubagentRuntime, "list" | "getProvider" | "resolveMaxDepth" | "startActivation">;
+/** The slice of `ctx.tools` this plugin registers against. */
+type ToolsHost = Pick<ToolRuntime, "register" | "get" | "schemas">;
+/** The slice of `ctx.jobs` a background script run needs. */
+type JobsHost = Pick<JobRegistry, "start" | "get">;
+/** The slice of `ctx.workingDirectory` a run needs to find the session directory. */
+type WorkingDirectoryHost = Pick<WorkingDirectoryService, "ensure">;
+export { ToolsHost as _, JobsHost as a, SessionId as c, SkillProvider as d, SkillProviderControl as f, ToolDefinition as g, SubagentsHost as h, JobId as i, SkillDefinition as l, SubagentCapabilities as m, AgentOptions as n, JsonSchemaNode as o, SkillResourceBase as p, AgentsHost as r, LlmHost as s, Agent as t, SkillInvocationPolicy as u, WorkingDirectoryHost as v };

package/dist/index.d.mts

@@ -1,118 +1,46 @@
-//#region src/provider.d.ts
+import { _ as ToolsHost, d as SkillProvider, f as SkillProviderControl, u as SkillInvocationPolicy } from "./host-contract-CUPSpeNk.mjs";
+import { LoadSkillResult, SkillResourceResult, SkillsHost, TOOL_NAME, createPstackSkillTool, readSkillResource, renderLoadedSkill } from "./skill.mjs";
 /**
- * The bundled pstack skill provider: one provider over the 55 generated skills
- * that ship inside this package.
- *
- * The provider contract below mirrors `@deepseek-ai/dsh-skill` 0.2.1-rc.3, which
- * was read through the host Inspect provider (`Service.listService` with
- * `service: "skills"`) and the installed type declarations. It is restated here
- * as a structural contract instead of imported so the plugin keeps zero runtime
- * imports from the host packages: a workspace-directory bundle is linked from
- * its checkout, where `@deepseek-ai/*` is not resolvable.
+ * Package-internal resource locations.
  *
- * Design constraints this module enforces, from the port design document §8.1:
+ * Every shipped resource is read from `dist/` and nowhere else. The bundler writes the
+ * public entries at `dist/*.mjs` and shared helper chunks under `dist/internal/`, the
+ * pstack build writes `dist/pstack/`, and the packaging step writes `dist/skills/`.
  *
- * - The catalog is built once from the package assets and never watched. A
- *   package update is the refresh boundary.
- * - A malformed bundled skill fails the whole index instead of disappearing
- *   from the catalog, so a broken asset is a startup error rather than a skill
- *   users silently cannot see.
- * - `get()` only accepts a locator this provider produced. Directory names are
- *   never joined from caller input.
- */
-/**
- * Standard precedence rank for packaged skill providers, re-exported by
- * `@deepseek-ai/dsh-skill` as `BUNDLED_SKILL_RANK`. Restated to keep the package
- * dependency-free; a mismatch only changes which provider wins a name collision.
+ * `PACKAGE_ROOT` therefore sits either one level above this module (an entry bundle in
+ * `dist/`) or two (a helper chunk in `dist/internal/`). Both layouts are known, so the
+ * directory name decides instead of probing for `dist` first and falling back.
  */
-export declare const BUNDLED_SKILL_RANK = 600;
-/** Default provider name used when the row does not override it. */
-export declare const DEFAULT_PROVIDER_NAME = "pstack";
-/** Origin bucket for a skill contribution. */
-type SkillSource = "project-dsh" | "project-agents" | "runtime" | "user-dsh" | "user-agents" | "custom" | "bundled" | (string & {});
-/** Optional provider-specific base used by loaded skill bodies to resolve relative resources. */
-type SkillResourceBase = {
-  readonly kind: "directory";
+/** Absolute path of the package root. */
+export declare const PACKAGE_ROOT: string;
+/** Absolute path of the generated pstack tree. */
+export declare const PORT_ROOT: string;
+/** Absolute path of the ported pstack skill directories. */
+export declare const SKILLS_ROOT: string;
+/** Absolute path of the vendored skill directories (`skills/vendored` at pack time). */
+export declare const VENDORED_SKILLS_ROOT: string;
+/** Absolute path of the skills authored in this repository. */
+export declare const AUTHORED_SKILLS_ROOT: string;
+/** Absolute path of the shipped harness mapping document. */
+export declare const HARNESS_DOC_PATH: string;
+/** One skill root the provider loads, labelled for collision errors. */
+interface SkillRoot {
   readonly path: string;
-} | {
-  readonly kind: "url";
-  readonly url: string;
-} | {
-  readonly kind: "opaque";
-  readonly description: string;
-};
-/** Invocation controls shared by skill discovery consumers. */
-interface SkillInvocationPolicy {
-  /** Whether model-facing catalogs and loaders include this skill. */
-  readonly modelInvocable: boolean;
-  /** Whether human-facing command catalogs and loaders include this skill. */
-  readonly userInvocable: boolean;
-}
-/** Invocation-neutral skill metadata returned by `ctx.skills.list()`. */
-interface SkillSummary {
-  /** Absolute instruction file path. */
-  readonly path?: string;
-  /** Kebab-case identifier used to address the skill. */
-  readonly name: string;
-  /** Short routing description shown by discovery consumers. */
-  readonly description: string;
-  /** Optional extra routing guidance. */
-  readonly whenToUse?: string;
-  /** Resolved model and user invocation controls. */
-  readonly invocation: SkillInvocationPolicy;
-  /** Discovery source that produced this skill. */
-  readonly source: SkillSource;
-  /** Provider that owns this skill body. */
-  readonly provider: string;
-  /** Provider-specific base for relative resources. */
-  readonly resourceBase?: SkillResourceBase;
-}
-/** Provider catalog entry used by the registry to merge and later load skills. */
-interface SkillCandidate extends SkillSummary {
-  /** Lower ranks win duplicate skill names. */
-  readonly rank: number;
-  /** Opaque provider-owned handle passed back to `provider.get()`. */
-  readonly locator: unknown;
-  /** Parsed optional metadata object from provider-specific skill frontmatter. */
-  readonly metadata?: Readonly<Record<string, unknown>>;
-}
-/** Complete parsed skill definition, including the body loaded by `ctx.skills.get()`. */
-interface SkillDefinition extends SkillSummary {
-  /** Markdown instruction body after frontmatter removal. */
-  readonly content: string;
-  /** Parsed optional metadata object from frontmatter. */
-  readonly metadata?: Readonly<Record<string, unknown>>;
-}
-/** Caller context used for cwd-sensitive and abortable provider work. */
-interface SkillLookupOptions {
-  /** Workspace selector for the current lookup. */
-  readonly cwd?: string | undefined;
-  /** Abort discovery or loading work for the current caller. */
-  readonly signal?: AbortSignal | undefined;
-}
-/** Registration-scoped lifecycle capability handed to a provider factory. */
-interface SkillProviderControl {
-  /** Aborts when registration fails or the exact provider registration is disposed. */
-  readonly signal: AbortSignal;
-  /** Invalidate completed catalogs and notify consumers. */
-  readonly invalidate: () => void;
-}
-/** Provider interface for one source of skills. */
-interface SkillProvider {
-  /** Unique provider name in the `ctx.skills` registry. */
-  readonly name: string;
-  /** List available skill candidates for the current lookup context. */
-  readonly list: (options: SkillLookupOptions) => Promise<readonly SkillCandidate[]>;
-  /** Load a complete skill body for a previously listed candidate. */
-  readonly get: (candidate: SkillCandidate, options: SkillLookupOptions) => Promise<SkillDefinition | undefined>;
+  readonly label: string;
 }
+/** Every skill root, in load order. Recursive discovery handles each root's nesting. */
+export declare const SKILL_ROOTS: readonly SkillRoot[];
+/** Standard precedence rank for packaged skill providers. */
+export declare const BUNDLED_SKILL_RANK = 600;
+/** Default provider name. */
+export declare const DEFAULT_PROVIDER_NAME = "pstack";
 /** One validated on-disk bundled skill. */
 interface BundledSkill {
   readonly name: string;
   readonly description: string;
   readonly whenToUse?: string;
   readonly invocation: SkillInvocationPolicy;
-  /** Absolute skill directory; the candidate resource base. */
+  /** Absolute skill directory; also the resource base. */
   readonly directory: string;
   /** Absolute `SKILL.md` path. */
   readonly instructionFile: string;
@@ -124,155 +52,38 @@ export declare class BundledSkillError extends Error {
   constructor(message: string);
 }
 /**
- * Read and validate every bundled skill below one directory.
+ * Read and validate every bundled skill under every root.
  *
- * This is the startup check: it runs before the provider registers, so a missing
- * `SKILL.md`, an invalid frontmatter block, or a name that disagrees with its
- * directory fails plugin activation with a path-qualified message instead of
- * dropping a skill from the catalog.
- *
- * @param skillsRoot - absolute path of the directory holding the skill directories.
- * @returns validated skills keyed by absolute skill directory, sorted by name.
- * @throws {BundledSkillError} when the tree or any skill in it is malformed.
+ * A skill name may appear in only one root; a duplicate is a packaging mistake, so it
+ * fails activation rather than letting one silently shadow the other. A root that does
+ * not exist is skipped, but an empty merged catalog fails.
  */
-export declare function loadBundledSkillIndex(skillsRoot: string): BundledSkillIndex;
+export declare function loadBundledSkillIndexes(roots: readonly SkillRoot[]): BundledSkillIndex;
 /**
  * Build the provider over an already validated index.
  *
- * @param index - result of {@link loadBundledSkillIndex}.
- * @param providerName - registry name for this provider.
- * @returns a read-only provider whose catalog never changes until the package does.
+ * The catalog is sorted by name so two installs present the same order, and it never
+ * changes until the package does.
  */
 export declare function createPstackSkillProvider(index: BundledSkillIndex, providerName?: string): SkillProvider;
-/**
- * Load the index and build the provider in one step, failing on a malformed tree.
- *
- * `apply()` uses this exact function, so the startup failure path and the
- * provider used in tests are the same code.
- *
- * @param skillsRoot - absolute path of the bundled skill root.
- * @param providerName - registry name for this provider.
- * @returns the provider over the validated index.
- */
-export declare function createPstackSkillProviderFromRoot(skillsRoot: string, providerName?: string): SkillProvider;
-//#endregion
-//#region src/paths.d.ts
-/**
- * Package-internal resource locations.
- *
- * The provider reads generated assets in place instead of copying them into a
- * user-visible skills directory, so every path here is resolved from this
- * module's own location. The modules run from `src/` in a checkout and from the
- * bundled `dist/index.mjs` in an installed package; both sit one directory below
- * the package root, so the same expression holds in both cases.
- */
-/** Absolute path of the package root: the repository in a checkout, the install directory after packing. */
-export declare const PACKAGE_ROOT: string;
-/** Absolute path of the generated, committed assets directory. */
-export declare const ASSETS_ROOT: string;
-/** Absolute path of the directory holding the 55 bundled skill directories. */
-export declare const SKILLS_ROOT: string;
-/** Absolute path of the generated harness mapping document. */
-export declare const HARNESS_DOC_PATH: string;
-//#endregion
-//#region src/frontmatter.d.ts
-/**
- * Frontmatter parsing for pstack skills and agents.
- *
- * This is a deliberately small YAML subset, not YAML. It reads the shapes the
- * upstream files use: plain scalars, single and double quotes, folded (`>` and
- * `>-`) and literal (`|` and `|-`) blocks, comments, and blank lines. Nesting
- * and multi-document streams are rejected rather than half-supported.
- */
-export interface Frontmatter {
-  readonly data: Readonly<Record<string, string>>;
-  readonly body: string;
-}
-export interface SkillFrontmatter {
-  readonly name: string;
-  readonly description: string;
-  readonly disableModelInvocation: boolean;
-  readonly userInvocable: boolean;
-  readonly whenToUse?: string;
-}
-export interface AgentFrontmatter {
-  readonly name: string;
-  readonly description: string;
-}
-export interface DroppedFrontmatterField {
-  readonly file: string;
-  readonly field: string;
-  readonly value: string;
-}
-export declare const SKILL_CONSUMED_FIELDS: readonly ["name", "description", "disable-model-invocation", "user-invocable", "whenToUse"];
-export declare const SKILL_DROPPED_FIELDS: readonly ["icon", "color", "paths"];
-export declare const AGENT_CONSUMED_FIELDS: readonly ["name", "description"];
-export declare const AGENT_DROPPED_FIELDS: readonly ["is_background"];
-export declare const MAX_SKILL_NAME_LENGTH = 64;
-export declare class FrontmatterError extends Error {
-  constructor(message: string);
-}
-export declare function parseFrontmatter(source: string): Frontmatter;
-export declare function validateSkillFrontmatter(data: Readonly<Record<string, string>>, source: string): SkillFrontmatter;
-export declare function validateAgentFrontmatter(data: Readonly<Record<string, string>>, source: string): AgentFrontmatter;
-export declare function serializeSkillFrontmatter(data: SkillFrontmatter): string;
-export declare function serializeAgentFrontmatter(data: AgentFrontmatter): string;
-export declare function skillDroppedFields(data: Readonly<Record<string, string>>, source: string): readonly DroppedFrontmatterField[];
-export declare function agentDroppedFields(data: Readonly<Record<string, string>>, source: string): readonly DroppedFrontmatterField[];
-//#endregion
-//#region src/index.d.ts
-/** Plugin name used by Loader diagnostics for this row. */
+/** Cordis row name, used by Loader diagnostics. */
 export declare const name = "pstack";
-/** The provider needs the skill registry and nothing else. */
+/** The row needs the skill registry and the tool registry. */
 export declare const inject: string[];
-/** Row configuration. Every field is optional; an omitted `config` is valid. */
-export interface PstackConfig {
-  /** Registry name for the provider; change it when two rows must coexist. */
-  readonly providerName?: string;
-}
-interface StandardSchemaIssue {
-  readonly message: string;
-  readonly path?: readonly (string | number)[];
-}
-type StandardSchemaResult = {
-  readonly value: PstackConfig;
-  readonly issues?: undefined;
-} | {
-  readonly issues: readonly StandardSchemaIssue[];
-};
-/**
- * Minimal Standard Schema validator for this plugin's row config.
- *
- * Cordis validates `apply()`'s second argument with `Config["~standard"]` and
- * substitutes the returned `value`, so an omitted row `config` resolves to the
- * documented defaults without a schemastery dependency.
- */
-export declare const Config: {
-  "~standard": {
-    version: number;
-    vendor: string;
-    validate(value: unknown): StandardSchemaResult;
-  };
-};
 /** The slice of the Cordis context this plugin requires. */
 export interface PstackSkillHost {
-  readonly skills: {
+  readonly skills: SkillsHost & {
     registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void;
   };
+  readonly tools: ToolsHost;
+  /** Optional-service read for `systemPrompt`; absent is fine. */
+  get?(name: string): unknown;
 }
 /**
- * Register the bundled pstack skill provider.
- *
- * The bundled tree is validated before the provider registers, so a malformed
- * `SKILL.md` fails plugin activation with a path-qualified error instead of
- * removing one skill from the catalog. Nothing is copied out of the package and
- * nothing is watched: reinstalling the package is the refresh boundary.
+ * Register the bundled pstack skill provider and the trusted loader.
  *
- * @param ctx - host context carrying the skill registry.
- * @param config - validated row config.
- * @throws {import("./provider.ts").BundledSkillError} when the bundled tree is malformed.
+ * @param ctx - host context carrying the skill and tool registries.
+ * @throws {import("./internal/skill-provider.ts").BundledSkillError} when the tree is malformed.
  */
-export declare function apply(ctx: PstackSkillHost, config?: PstackConfig): void;
-//#endregion
-export type { BundledSkill, BundledSkillIndex, SkillCandidate, SkillDefinition, SkillInvocationPolicy, SkillLookupOptions, SkillProvider, SkillProviderControl, SkillResourceBase, SkillSource, SkillSummary };
-//# sourceMappingURL=index.d.mts.map
+export declare function apply(ctx: PstackSkillHost): void;
+export { type LoadSkillResult, TOOL_NAME as PSTACK_SKILL_TOOL_NAME, type SkillResourceResult, type SkillRoot, createPstackSkillTool, readSkillResource, renderLoadedSkill };