dsh-pstack 0.0.0-stage → 0.1.0

package/dist/assets/skills/why/references/sources/sentry.md

@@ -0,0 +1,66 @@
+# Sentry Error History
+
+## How to search it
+
+Use the Sentry MCP.
+
+1. **Orient.** If you don't know the project slug and organization:
+
+   ```
+   find_organizations
+   find_projects
+   ```
+
+2. **Search for issues related to the target.**
+
+   ```
+   search_issues (natural language, e.g., "errors in PaymentService timeout", "unhandled exceptions in uploadFile")
+   ```
+
+   Build queries from the exception class names the target handles, its function or class name, the error message strings it checks for, and its file path.
+
+3. **Narrow by release and time window.**
+
+   ```
+   search_issue_events (filter by release, time, environment, trace ID, tags)
+   get_issue_tag_values (for an issue, see distribution across versions, users, environments)
+   ```
+
+   For a suspected issue, check **first seen** and **last seen** (does the stop line up with the target's ship date?), the **affected releases** (which saw it, and which was the fix?), and the **frequency trajectory** (did it spike, then get resolved?).
+
+4. **Pull the full event for context.**
+
+   ```
+   get_sentry_resource (pass a Sentry URL or type+ID)
+   ```
+
+   Does the stack trace pass through the target code? Do the tags and breadcrumbs match the conditions the target defends against?
+
+5. **Check releases that landed near the target.**
+
+   ```
+   find_releases (around the commit date of the target)
+   ```
+
+   Cross-reference release version with the PR's merge date.
+
+6. **Use Seer sparingly.**
+
+   ```
+   analyze_issue_with_seer
+   ```
+
+   Seer's AI root-cause analyses are a hypothesis generator. Treat them as inference, not authoritative. The actual events and stack traces are the primary evidence.
+
+## What to return
+
+For each relevant issue:
+- Issue ID and title
+- Project and organization
+- First seen / last seen timestamps
+- Event count (and sampling rate if known)
+- Affected releases
+- A representative stack trace snippet showing relevance to the target (verbatim excerpt, not summary)
+- First/last-seen correlation with the target's ship date
+- Link to the issue
+- Any author comments or resolution notes

package/dist/assets/skills/why/references/sources/slack.md

@@ -0,0 +1,17 @@
+# Slack Conversations
+
+## How to search it
+
+Slack MCP tools vary. Check which Slack MCP is available and inspect its tool schema first. It may require `mcp_auth`. If authentication fails, stop and report the gap.
+
+1. **Author-bounded search.** Messages from the PR author around the PR merge date. Limits scope dramatically and often hits gold.
+3. **PR URL search.** Slack often links PRs when they're reviewed or discussed. Search for the PR URL (or just `/pull/<number>`).
+4. **Error string search.** If the code handles a specific error, search for the error string. Incident threads often surface.
+
+## Common pitfalls
+
+- **Channel archaeology limits.** Very old messages may be gone due to retention policies. If you can't find anything before a certain date, note the retention cliff.
+- **Unsearched DMs.** Many decisions happen in DMs that aren't searchable. You'll miss them. That's a known limitation.
+- **Speculative jokes as "decisions."** Slack is casual. "Lol just do the thing" isn't a decision, even if it preceded the commit. Look for considered discussion.
+- **Context collapse in single messages.** Without the thread, a single message often reads differently than in context. Always fetch threads.
+- **Auth failures.** If the MCP isn't authenticated, stop. Don't make up findings. Report that Slack wasn't searchable.

package/dist/assets/skills/why/references/synthesizer-prompt.md

@@ -0,0 +1,129 @@
+# Synthesizer Prompt Template
+
+Fill in the placeholders.
+
+---
+
+You are answering a "why" question about a piece of code by synthesizing findings from investigators who searched different historical sources (source control, issue / ticket tracker, long-form documents, real-time team chat, infrastructure observability, error / exception tracking, product analytics warehouse, and code comments). Produce a confidence-weighted, evidence-cited narrative that says honestly what the evidence supports, and just as honestly what it doesn't.
+
+## The Question
+
+> {QUESTION}
+
+## The Code Anchor
+
+**Target files:** {FILES_WITH_LINE_RANGES}
+
+**Key symbols:** {SYMBOLS}
+
+## Investigator Findings
+
+{ALL_INVESTIGATOR_FINDINGS}
+
+## Sources That Weren't Searched
+
+{SKIPPED_SOURCES_WITH_REASONS}
+
+## Epistemics Framework
+
+You MUST follow `references/epistemics.md`. Read it in full before writing. The key rules:
+
+1. Every claim must sit in one tier: **Direct**, **Supported**, **Inferred**, **Speculative**, **Unknown**. The tier sets its section and its phrasing.
+2. Every Direct/Supported claim must have a citation (PR #, ticket ID, doc URL, chat permalink, commit hash, or file:line).
+3. Inferred and Speculative claims must use hedged language ("appears to", "likely", "suggests", "one possibility is").
+4. Never cite code as evidence for its own intent.
+5. Document gaps. Don't fill them with plausible-sounding guesses.
+6. Treat a hypothesis embedded in the user's question as a candidate, not a conclusion. Check it independently.
+
+## Instructions
+
+1. **Read all investigator findings** and weigh the evidence yourself. Investigators gathered raw evidence, not conclusions.
+2. **Merge overlaps.** When several investigators cite the same PR, ticket, or doc, give it one authoritative reference.
+3. **Surface contradictions.** When two items disagree, show both. Don't pick one.
+4. **Calibrate each claim.** Find its evidence and tier. Direct: cite it and state it plainly. Inferred: hedge it and show the inference. Speculative: mark it. No evidence: put it in the gaps.
+5. **Verify citations by spot-checking.** If you're uncertain a cited item exists or says what the investigator claims, check it by reading the codebase or calling MCP tools. Don't propagate errors. Do not write files, commit, or modify external state.
+6. **Don't overreach.** The user will act on this. Leave an open question open rather than fill it with a confident guess.
+
+## Output Format
+
+Write for the user, in this exact structure:
+
+---
+
+### The Question
+
+Restate the user's question in one or two sentences.
+
+### The Code in Question
+
+File paths, line ranges, key symbols. Two or three lines to orient a cold reader.
+
+### What We Found
+
+Claims with textual evidence, each quoted or paraphrased and cited precisely:
+
+- **[Direct]** {Claim}. Source: [PR #123](url) / ticket ID / file:line. {Brief quote or paraphrase.}
+- **[Supported]** {Claim}. Evidence: {list of items and what each contributes}.
+
+`[Direct]` is single-source, explicit evidence. `[Supported]` is multiple indirect items converging on a conclusion.
+
+### What We Can Reasonably Infer
+
+Claims stated nowhere but well-supported by indirect evidence. Each bullet must make the inference chain visible ("Given A and B, it's likely that C") and must use hedged language ("appears to", "likely", "suggests", "is consistent with"):
+
+- **[Inferred]** {Hedged claim}. Reasoning: {the specific evidence and the inference step}.
+
+Skip this section if there's nothing to infer.
+
+### Competing Hypotheses
+
+If the evidence fits multiple stories, present each. Don't force a winner the record doesn't support. For each hypothesis:
+
+- **Hypothesis:** {one-sentence statement}
+- **Evidence for:** {specific items}
+- **Evidence against or missing:** {what would need to be true but isn't, or what counter-signals exist}
+
+Skip this section if there's a single clear answer.
+
+### What We Don't Know
+
+Specific gaps: "We searched the issue tracker for [query1], [query2], [query3] and found no issue discussing the rate-limit threshold", not "We don't know why." Include:
+
+- Questions that went unanswered
+- Searches that returned nothing
+- Sources that were unavailable, and why (such as a missing real-time team chat MCP)
+- People who would likely know but whom you can't ask
+
+### Sources Consulted
+
+What was actually searched, so the user can judge coverage and redirect:
+
+- **Source control history**: {file paths}, {number of commits reviewed}, PRs #{numbers}, and code comments searched. Or "Not searched. This should not happen because git and `gh` are always expected."
+- **Issue / ticket tracker**: {ticket IDs and keyword searches}. Or "Not searched. No matching MCP available in this environment."
+- **Long-form documents**: {page titles and search queries}. Or "Not searched. No matching MCP available in this environment."
+- **Real-time team chat**: {channels searched, date ranges, queries}. Or "Not searched. No matching MCP available in this environment."
+- **Infrastructure observability**: {dashboards, monitors, metrics, logs, traces, or incidents searched}. Or "Not searched. No matching MCP available in this environment."
+- **Error / exception tracking**: {issues, events, or releases searched}. Or "Not searched. No matching MCP available in this environment."
+- **Product analytics warehouse**: {fully-qualified tables queried, the time windows, and the numeric summaries (counts, percentiles, first/last-seen timestamps) that bore on the question}. Or "Not searched. No matching MCP available in this environment."
+
+### Confidence Summary
+
+One or two sentences on overall confidence, e.g.:
+
+> "The core rationale (A) is well-supported by direct PR and ticket evidence. The specific threshold value (100) is inferred from the surrounding context but not explicitly documented. The question of whether this was driven by a customer request could not be answered. No relevant issue tracker or long-form doc content surfaced, and real-time team chat search was unavailable."
+
+---
+
+## Quality Check Before Returning
+
+Revise if any item fails:
+
+1. Does every claim in "What We Found" have a citation? If not, add one or move it to "Inferred" or "Hypotheses."
+2. Is the phrasing tier-appropriate? (Direct claims can use "because". Inferred claims cannot.)
+3. Did you surface every contradiction you noticed, or quietly pick one?
+4. Does "What We Don't Know" name specific gaps? If it's empty or missing, be suspicious. Historical investigations almost always have gaps.
+5. Did you check any hypothesis embedded in the question against the evidence rather than rubber-stamp it?
+6. Did you cite code as evidence for its own intent? Remove it. Code is mechanics, not motivation.
+7. Is the tone calibrated? A confident-sounding answer on weak evidence is the exact failure this skill exists to prevent.
+
+The value of this output is its honesty, not its authority. A reader who takes it to the original author, an engineering lead, or a product manager should know what's known, what's inferred, and what's missing, so they can ask the right follow-up questions. Optimize for being useful, not for looking decisive.

package/dist/cordis.patch.yml

@@ -0,0 +1,20 @@
+# dsh-pstack bundle patch.
+#
+# Two rows, both installed by this package:
+#   - `pstack` mounts the bundled skill provider. Every pstack skill becomes a
+#     normal DSH skill: model-invocable skills reach the catalog, user-invocable
+#     skills reach the `/` menu.
+#   - `pstack-subagent` mounts the `pstack_subagent` tool, the DSH replacement
+#     for Cursor's `Task` tool. It resolves pstack role lines from
+#     `~/.dsh/pstack-models.md` and delegates through `ctx.subagents`.
+#
+# The `pstack` row requires `ctx.skills`, which `@deepseek-ai/dsh-base` provides.
+# The `pstack-subagent` row requires `ctx.tools` and `ctx.subagents`, also in
+# base-backed profiles. Installing this bundle into a profile that lacks them
+# leaves the rows pending, exactly like any other dependency-driven plugin.
+- insert:
+    - id: pstack
+      name: "dsh-pstack"
+
+    - id: pstack-subagent
+      name: "dsh-pstack/subagent"

package/dist/index.d.mts

@@ -0,0 +1,16 @@
+import "@deepseek-ai/dsh-skill";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/provider.d.ts
+export declare const name = "pstack";
+interface Config {
+  /** Extra skill directories to serve in addition to the bundled set. */
+  readonly extraSkillDirectories?: string[];
+}
+export declare const inject: string[];
+export declare function apply(ctx: Context, config?: Config): void;
+/** Absolute root of the generated skill tree, exported for doctor checks. */
+export declare const skillsRoot: string;
+export declare const skillsRootUrl: import("node:url").URL;
+//#endregion
+export type { Config };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,172 @@
+import { n as SKILLS_ROOT, r as SKILLS_ROOT_URL } from "./paths-Bbai4CaT.mjs";
+import { readFileSync, readdirSync } from "node:fs";
+import { BUNDLED_SKILL_RANK } from "@deepseek-ai/dsh-skill";
+//#region src/frontmatter.ts
+const DELIMITER = "---";
+function unquote(value) {
+	const trimmed = value.trim();
+	if (trimmed.length >= 2) {
+		const first = trimmed[0];
+		const last = trimmed[trimmed.length - 1];
+		if (first === "\"" && last === "\"" || first === "'" && last === "'") {
+			const inner = trimmed.slice(1, -1);
+			return first === "\"" ? inner.replace(/\\"/g, "\"").replace(/\\n/g, "\n").replace(/\\\\/g, "\\") : inner.replace(/''/g, "'");
+		}
+	}
+	return trimmed;
+}
+function parseFrontmatter(source) {
+	const normalized = source.replace(/\r\n/g, "\n");
+	const lines = normalized.split("\n");
+	if (lines[0]?.trim() !== DELIMITER) return {
+		data: {},
+		body: normalized
+	};
+	let end = -1;
+	for (let index = 1; index < lines.length; index += 1) if (lines[index]?.trim() === DELIMITER) {
+		end = index;
+		break;
+	}
+	if (end === -1) return {
+		data: {},
+		body: normalized
+	};
+	const data = {};
+	let index = 1;
+	while (index < end) {
+		const line = lines[index] ?? "";
+		const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+		if (!match) {
+			index += 1;
+			continue;
+		}
+		const key = match[1];
+		const rawValue = match[2] ?? "";
+		index += 1;
+		if (rawValue === ">" || rawValue === ">-" || rawValue === "|" || rawValue === "|-") {
+			const folded = rawValue.startsWith(">");
+			const collected = [];
+			while (index < end) {
+				const next = lines[index] ?? "";
+				if (next.trim() !== "" && !/^\s/.test(next)) break;
+				collected.push(next.replace(/^\s{1,4}/, ""));
+				index += 1;
+			}
+			data[key] = folded ? collected.join(" ").replace(/\s+/g, " ").trim() : collected.join("\n").replace(/\n+$/, "");
+			continue;
+		}
+		if (rawValue === "") {
+			const collected = [];
+			while (index < end) {
+				const next = lines[index] ?? "";
+				if (next.trim() !== "" && !/^\s/.test(next)) break;
+				collected.push(next.trim());
+				index += 1;
+			}
+			data[key] = collected.join(" ").trim();
+			continue;
+		}
+		data[key] = unquote(rawValue);
+	}
+	return {
+		data,
+		body: lines.slice(end + 1).join("\n").replace(/^\n+/, "")
+	};
+}
+//#endregion
+//#region src/provider.ts
+/**
+* Bundled pstack skill provider.
+*
+* One provider hosts every pstack skill so the catalog stays one entry per
+* skill and the package ships as a single installable bundle. The provider is
+* immutable: `assets/skills/` is generated at build time, so discovery always
+* completes with the same list.
+*/
+const PROVIDER_NAME = "pstack";
+function text(value) {
+	return (value ?? "").trim();
+}
+/**
+* Parse one generated SKILL.md into the catalog entry the provider serves.
+* Generated files always carry `name` and `description`; a hand-edit that
+* removes them fails loudly instead of silently dropping the skill.
+*/
+function toEntry(directory, source) {
+	const { data } = parseFrontmatter(source);
+	if (!text(data.name) || !text(data.description)) throw new Error(`pstack skill "${directory}" is missing name or description frontmatter`);
+	return {
+		name: text(data.name),
+		description: text(data.description),
+		modelInvocable: data["disable-model-invocation"] !== "true",
+		userInvocable: data["user-invocable"] !== "false",
+		directory
+	};
+}
+function resourceBase(directory) {
+	return {
+		kind: "directory",
+		path: `${SKILLS_ROOT}${directory}/`
+	};
+}
+function toCandidate(entry) {
+	return {
+		name: entry.name,
+		description: entry.description,
+		invocation: {
+			modelInvocable: entry.modelInvocable,
+			userInvocable: entry.userInvocable
+		},
+		provider: PROVIDER_NAME,
+		source: "bundled",
+		rank: BUNDLED_SKILL_RANK,
+		resourceBase: resourceBase(entry.directory),
+		locator: entry.directory,
+		path: `${SKILLS_ROOT}${entry.directory}/SKILL.md`
+	};
+}
+function createProvider(options) {
+	const read = options.read ?? ((directory) => readFileSync(`${SKILLS_ROOT}${directory}/SKILL.md`, "utf8"));
+	const entries = options.directories.map((directory) => toEntry(directory, read(directory)));
+	const byName = new Map(entries.map((entry) => [entry.name, entry]));
+	const load = (entry) => {
+		const { body } = parseFrontmatter(read(entry.directory));
+		return {
+			name: entry.name,
+			description: entry.description,
+			invocation: {
+				modelInvocable: entry.modelInvocable,
+				userInvocable: entry.userInvocable
+			},
+			provider: PROVIDER_NAME,
+			source: "bundled",
+			resourceBase: resourceBase(entry.directory),
+			path: `${SKILLS_ROOT}${entry.directory}/SKILL.md`,
+			content: body
+		};
+	};
+	return {
+		name: PROVIDER_NAME,
+		list: async () => entries.map(toCandidate),
+		get: async (candidate) => {
+			const entry = byName.get(candidate.name);
+			return entry ? load(entry) : void 0;
+		}
+	};
+}
+const name = "pstack";
+const inject = ["skills"];
+function listBundledSkillDirectories() {
+	return readdirSync(SKILLS_ROOT, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
+function apply(ctx, config = {}) {
+	const directories = [.../* @__PURE__ */ new Set([...listBundledSkillDirectories(), ...config.extraSkillDirectories ?? []])];
+	ctx.skills.registerProvider(() => createProvider({ directories }));
+}
+/** Absolute root of the generated skill tree, exported for doctor checks. */
+const skillsRoot = SKILLS_ROOT;
+const skillsRootUrl = SKILLS_ROOT_URL;
+//#endregion
+export { apply, inject, name, skillsRoot, skillsRootUrl };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/frontmatter.ts","../src/provider.ts"],"sourcesContent":["/**\n * The pstack SKILL.md frontmatter subset: plain scalars, quoted scalars, and\n * folded or literal block scalars. Kept dependency-free so the plugin can be\n * imported at boot before any optional parser is available.\n */\n\nexport interface Frontmatter {\n  data: Record<string, string>;\n  body: string;\n}\n\nconst DELIMITER = \"---\";\n\nfunction unquote(value: string): string {\n  const trimmed = value.trim();\n  if (trimmed.length >= 2) {\n    const first = trimmed[0];\n    const last = trimmed[trimmed.length - 1];\n    if ((first === '\"' && last === '\"') || (first === \"'\" && last === \"'\")) {\n      const inner = trimmed.slice(1, -1);\n      return first === '\"'\n        ? inner.replace(/\\\\\"/g, '\"').replace(/\\\\n/g, \"\\n\").replace(/\\\\\\\\/g, \"\\\\\")\n        : inner.replace(/''/g, \"'\");\n    }\n  }\n  return trimmed;\n}\n\nexport function parseFrontmatter(source: string): Frontmatter {\n  const normalized = source.replace(/\\r\\n/g, \"\\n\");\n  const lines = normalized.split(\"\\n\");\n  if (lines[0]?.trim() !== DELIMITER) return { data: {}, body: normalized };\n\n  let end = -1;\n  for (let index = 1; index < lines.length; index += 1) {\n    if (lines[index]?.trim() === DELIMITER) {\n      end = index;\n      break;\n    }\n  }\n  if (end === -1) return { data: {}, body: normalized };\n\n  const data: Record<string, string> = {};\n  let index = 1;\n  while (index < end) {\n    const line = lines[index] ?? \"\";\n    const match = /^([A-Za-z0-9_-]+):\\s*(.*)$/.exec(line);\n    if (!match) {\n      index += 1;\n      continue;\n    }\n    const key = match[1]!;\n    const rawValue = match[2] ?? \"\";\n    index += 1;\n\n    if (rawValue === \">\" || rawValue === \">-\" || rawValue === \"|\" || rawValue === \"|-\") {\n      const folded = rawValue.startsWith(\">\");\n      const collected: string[] = [];\n      while (index < end) {\n        const next = lines[index] ?? \"\";\n        if (next.trim() !== \"\" && !/^\\s/.test(next)) break;\n        collected.push(next.replace(/^\\s{1,4}/, \"\"));\n        index += 1;\n      }\n      data[key] = folded\n        ? collected.join(\" \").replace(/\\s+/g, \" \").trim()\n        : collected.join(\"\\n\").replace(/\\n+$/, \"\");\n      continue;\n    }\n\n    if (rawValue === \"\") {\n      const collected: string[] = [];\n      while (index < end) {\n        const next = lines[index] ?? \"\";\n        if (next.trim() !== \"\" && !/^\\s/.test(next)) break;\n        collected.push(next.trim());\n        index += 1;\n      }\n      data[key] = collected.join(\" \").trim();\n      continue;\n    }\n\n    data[key] = unquote(rawValue);\n  }\n\n  return {\n    data,\n    body: lines\n      .slice(end + 1)\n      .join(\"\\n\")\n      .replace(/^\\n+/, \"\"),\n  };\n}\n","/**\n * Bundled pstack skill provider.\n *\n * One provider hosts every pstack skill so the catalog stays one entry per\n * skill and the package ships as a single installable bundle. The provider is\n * immutable: `assets/skills/` is generated at build time, so discovery always\n * completes with the same list.\n */\nimport { readdirSync, readFileSync } from \"node:fs\";\nimport type { Context } from \"@deepseek-ai/cordis\";\nimport {\n  BUNDLED_SKILL_RANK,\n  type SkillCandidate,\n  type SkillDefinition,\n  type SkillProvider,\n} from \"@deepseek-ai/dsh-skill\";\nimport { parseFrontmatter } from \"./frontmatter.ts\";\nimport { SKILLS_ROOT, SKILLS_ROOT_URL } from \"./paths.ts\";\n\nexport interface PstackSkillEntry {\n  readonly name: string;\n  readonly description: string;\n  readonly modelInvocable: boolean;\n  readonly userInvocable: boolean;\n  readonly directory: string;\n}\n\nexport const PROVIDER_NAME = \"pstack\";\n\nfunction text(value: string | undefined): string {\n  return (value ?? \"\").trim();\n}\n\n/**\n * Parse one generated SKILL.md into the catalog entry the provider serves.\n * Generated files always carry `name` and `description`; a hand-edit that\n * removes them fails loudly instead of silently dropping the skill.\n */\nexport function toEntry(directory: string, source: string): PstackSkillEntry {\n  const { data } = parseFrontmatter(source);\n  if (!text(data.name) || !text(data.description)) {\n    throw new Error(`pstack skill \"${directory}\" is missing name or description frontmatter`);\n  }\n  return {\n    name: text(data.name),\n    description: text(data.description),\n    modelInvocable: data[\"disable-model-invocation\"] !== \"true\",\n    userInvocable: data[\"user-invocable\"] !== \"false\",\n    directory,\n  };\n}\n\nfunction resourceBase(directory: string) {\n  return { kind: \"directory\" as const, path: `${SKILLS_ROOT}${directory}/` };\n}\n\nexport function toCandidate(entry: PstackSkillEntry): SkillCandidate {\n  return {\n    name: entry.name,\n    description: entry.description,\n    invocation: { modelInvocable: entry.modelInvocable, userInvocable: entry.userInvocable },\n    provider: PROVIDER_NAME,\n    source: \"bundled\",\n    rank: BUNDLED_SKILL_RANK,\n    resourceBase: resourceBase(entry.directory),\n    locator: entry.directory,\n    path: `${SKILLS_ROOT}${entry.directory}/SKILL.md`,\n  };\n}\n\nexport interface PstackProviderOptions {\n  /** Directory names to serve. The build passes the generated list. */\n  readonly directories: readonly string[];\n  /** Reads one skill body. Tests override it to avoid touching the package. */\n  readonly read?: (directory: string) => string;\n}\n\nexport function createProvider(options: PstackProviderOptions): SkillProvider {\n  const read =\n    options.read ??\n    ((directory: string) => readFileSync(`${SKILLS_ROOT}${directory}/SKILL.md`, \"utf8\"));\n  const entries = options.directories.map((directory) => toEntry(directory, read(directory)));\n  const byName = new Map(entries.map((entry) => [entry.name, entry]));\n\n  const load = (entry: PstackSkillEntry): SkillDefinition => {\n    const { body } = parseFrontmatter(read(entry.directory));\n    return {\n      name: entry.name,\n      description: entry.description,\n      invocation: { modelInvocable: entry.modelInvocable, userInvocable: entry.userInvocable },\n      provider: PROVIDER_NAME,\n      source: \"bundled\",\n      resourceBase: resourceBase(entry.directory),\n      path: `${SKILLS_ROOT}${entry.directory}/SKILL.md`,\n      content: body,\n    };\n  };\n\n  return {\n    name: PROVIDER_NAME,\n    list: async () => entries.map(toCandidate),\n    get: async (candidate) => {\n      const entry = byName.get(candidate.name);\n      return entry ? load(entry) : undefined;\n    },\n  };\n}\n\nexport const name = \"pstack\";\n\nexport interface Config {\n  /** Extra skill directories to serve in addition to the bundled set. */\n  readonly extraSkillDirectories?: string[];\n}\n\nexport const inject = [\"skills\"];\n\nexport function listBundledSkillDirectories(): string[] {\n  return readdirSync(SKILLS_ROOT, { withFileTypes: true })\n    .filter((entry) => entry.isDirectory())\n    .map((entry) => entry.name)\n    .sort();\n}\n\nexport function apply(ctx: Context, config: Config = {}): void {\n  const directories = [\n    ...new Set([...listBundledSkillDirectories(), ...(config.extraSkillDirectories ?? [])]),\n  ];\n  ctx.skills.registerProvider(() => createProvider({ directories }));\n}\n\n/** Absolute root of the generated skill tree, exported for doctor checks. */\nexport const skillsRoot = SKILLS_ROOT;\nexport const skillsRootUrl = SKILLS_ROOT_URL;\n"],"mappings":"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"}

package/dist/paths-Bbai4CaT.mjs

@@ -0,0 +1,16 @@
+import { fileURLToPath } from "node:url";
+//#region src/paths.ts
+/**
+* Locate one pstack skill directory inside this package.
+*
+* The provider registers candidates from an explicit file list, so this helper
+* resolves the directory the built entry point and the tests share.
+*/
+const SKILLS_ROOT_URL = new URL("../assets/skills/", import.meta.url);
+const AGENTS_ROOT_URL = new URL("../assets/agents/", import.meta.url);
+const SKILLS_ROOT = fileURLToPath(SKILLS_ROOT_URL);
+const AGENTS_ROOT = fileURLToPath(AGENTS_ROOT_URL);
+//#endregion
+export { SKILLS_ROOT as n, SKILLS_ROOT_URL as r, AGENTS_ROOT as t };
+
+//# sourceMappingURL=paths-Bbai4CaT.mjs.map

package/dist/paths-Bbai4CaT.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths-Bbai4CaT.mjs","names":[],"sources":["../src/paths.ts"],"sourcesContent":["/**\n * Locate one pstack skill directory inside this package.\n *\n * The provider registers candidates from an explicit file list, so this helper\n * resolves the directory the built entry point and the tests share.\n */\nimport { fileURLToPath } from \"node:url\";\n\nexport const SKILLS_ROOT_URL = new URL(\"../assets/skills/\", import.meta.url);\nexport const AGENTS_ROOT_URL = new URL(\"../assets/agents/\", import.meta.url);\nexport const SKILLS_ROOT = fileURLToPath(SKILLS_ROOT_URL);\nexport const AGENTS_ROOT = fileURLToPath(AGENTS_ROOT_URL);\n"],"mappings":";;;;;;;;AAQA,MAAa,kBAAkB,IAAI,IAAI,qBAAqB,YAAY,GAAG;AAC3E,MAAa,kBAAkB,IAAI,IAAI,qBAAqB,YAAY,GAAG;AAC3E,MAAa,cAAc,cAAc,eAAe;AACxD,MAAa,cAAc,cAAc,eAAe"}

package/dist/subagent.d.mts

@@ -0,0 +1,130 @@
+import { ContentBlock, ReasoningEffortId } from "@deepseek-ai/dsh-llm";
+import { Context } from "@deepseek-ai/cordis";
+import { Agent } from "@deepseek-ai/dsh-agent";
+//#region src/roles.d.ts
+/**
+ * pstack role resolution.
+ *
+ * `~/.dsh/pstack-models.md` holds one role per line. The tool resolves a role
+ * into a child LLM route at call time, so edits apply to the next delegation
+ * without restarting the harness.
+ *
+ * Parsing never throws. A typo in one line must not break delegation, but it
+ * must also not disappear: `parseModelConfigWithIssues` collects `issues` and
+ * the parser keeps them so a caller can report the line that is wrong.
+ */
+interface Route {
+  readonly provider: string;
+  readonly model: string;
+  readonly reasoningEffort?: string;
+}
+//#endregion
+//#region src/subagent.d.ts
+export declare const name = "pstack-subagent";
+export declare const inject: string[];
+declare const AGENT_KINDS: readonly ["poteto-agent", "comment-sicko", "general"];
+export type AgentKind = (typeof AGENT_KINDS)[number];
+export interface Config {
+  /** Tool name exposed to the model. */
+  readonly toolName?: string;
+  /** Subagent provider registered on `ctx.subagents`. */
+  readonly provider?: string;
+  /** Default agent kind when the model omits `agent`. */
+  readonly defaultAgent?: AgentKind;
+}
+export declare function stripFrontmatter(source: string): string;
+export declare function readAgentInstructions(kind: AgentKind): Promise<string>;
+/**
+ * Build the child prompt. A pstack delegate must read `poteto-mode` first, and
+ * the parent normally passes its absolute path. When the parent omits it, this
+ * fallback keeps the delegate from drifting into general-purpose style.
+ */
+export declare function composePrompt(input: {
+  readonly kind: AgentKind;
+  readonly description: string;
+  readonly prompt: string;
+  readonly agentInstructions: string;
+  readonly potetoModePath?: string;
+}): string;
+export interface RoleResolution {
+  readonly route: Route | undefined;
+  /** Human-readable notes to append to the tool reply: issues, near misses. */
+  readonly notes: readonly string[];
+}
+/**
+ * Resolve the `role` argument against the shipped role table, explaining a miss
+ * instead of swallowing it.
+ *
+ * A missing file is normal. A configured-but-unmatched role is not: it means a
+ * skill and `~/.dsh/pstack-models.md` disagree, and the child would silently run
+ * on the parent route. The tool reply says so, so the parent can fix the file or
+ * report the miss rather than believing the route applied.
+ */
+export declare function resolveRoleArg(role: string | undefined): Promise<RoleResolution>;
+export interface PstackToolDeps {
+  readonly start: (input: {
+    readonly parent: Agent;
+    readonly label: string;
+    readonly prompt: ContentBlock[];
+    readonly signal: AbortSignal;
+    readonly route: Route | undefined;
+    readonly cwd: string | undefined;
+  }) => Promise<{
+    readonly childId: string;
+  }>;
+  readonly loadAgent: (kind: AgentKind) => Promise<string>;
+  /**
+   * Resolve the `role` argument. The notes explain a miss so the reply can name
+   * it; an empty list means the route applied as written, or there was no role.
+   */
+  readonly loadRole: (role: string | undefined) => Promise<RoleResolution>;
+  readonly potetoModePath?: string;
+  readonly defaultAgent?: AgentKind;
+  readonly toolName?: string;
+}
+/**
+ * Turn a resolved role into the `agentOptions` a child activation carries.
+ *
+ * This is the only place a `Route` becomes a provider request. Keeping it a
+ * pure function lets a test assert the exact options without starting a child,
+ * which is where a role-to-route bug would otherwise stay invisible until a
+ * live delegation picked the wrong model.
+ */
+export declare function routeToAgentOptions(route: Route | undefined): {
+  provider: string;
+  model: string;
+  reasoningEffort?: ReasoningEffortId;
+} | undefined;
+/** Tool definition over injected dependencies; `apply` supplies the runtime. */
+export declare function createPstackTool(deps: PstackToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/**
+ * Build the provider-facing activation request for one child.
+ *
+ * A role is resolved once, at delegation time, into concrete provider options.
+ * The child inherits the parent route when the role is absent or resolves to
+ * `inherit-parent`, which is why the field is omitted rather than set to a
+ * placeholder.
+ */
+export declare function buildActivationRequest(input: {
+  readonly parent: Agent;
+  readonly prompt: ContentBlock[];
+  readonly route: Route | undefined;
+  readonly cwd: string | undefined;
+}): {
+  parent: Agent;
+  prompt: ContentBlock[];
+  cwd?: string;
+  agentOptions?: {
+    provider: string;
+    model: string;
+    reasoningEffort?: ReasoningEffortId;
+  };
+};
+/**
+ * Mount the tool. `ctx.subagents` owns child lifecycle; this row only supplies
+ * the pstack-specific shape (agent preambles and role routes) on top.
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+//#endregion
+export {};
+//# sourceMappingURL=subagent.d.mts.map