@bridge_gpt/mcp-server 0.1.17 → 0.2.1

package/build/agent-capabilities/runner.js

@@ -0,0 +1,56 @@
+/**
+ * Non-throwing probe runner. For each selected agent it builds a probe context,
+ * filters probes by `--only` and per-agent applicability, applies the skip-gate
+ * (binary absent, or an `env`-auth agent whose credential is unset → skip BEFORE
+ * spawning), runs each probe catching any throw as `fail`, and cleans up temp dirs.
+ */
+import { resolveAgentSpec } from "../agent-registry.js";
+import { createProbeContext } from "./probe-context.js";
+import { ALL_PROBES } from "./probes.js";
+import { AGENT_AUTH, } from "./types.js";
+/** Apply the skip-gate, then run the probe (catching throws as `fail`). */
+async function runOneProbe(deps, agentName, probe, ctx) {
+    if (probe.spawnsAgent) {
+        if (ctx.resolvedBinary === null) {
+            return { status: "skip", detail: `${ctx.agent.command} not on PATH — see binary-resolves` };
+        }
+        const auth = AGENT_AUTH[agentName];
+        if (auth.kind === "env") {
+            const value = deps.env[auth.varName];
+            if (!value || value.length === 0) {
+                return { status: "skip", detail: `${auth.varName} not set — set it to run this probe` };
+            }
+        }
+        // interactive auth (claude) cannot be verified from env — run and report the outcome.
+    }
+    try {
+        return await probe.run(ctx);
+    }
+    catch (err) {
+        return { status: "fail", detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+export async function collectCapabilityResults(deps, options) {
+    const records = [];
+    for (const agentName of options.agents) {
+        const agent = resolveAgentSpec(agentName);
+        if (!agent)
+            continue; // defensive: agent names are validated by the CLI parser
+        const applicable = ALL_PROBES.filter((p) => p.appliesTo.includes(agentName) && (!options.only || options.only.includes(p.id)));
+        const { ctx, cleanup } = await createProbeContext(deps, agent, options.timeoutMs);
+        try {
+            for (const probe of applicable) {
+                const result = await runOneProbe(deps, agentName, probe, ctx);
+                records.push({ agent: agentName, probeId: probe.id, title: probe.title, result });
+            }
+        }
+        finally {
+            await cleanup();
+        }
+    }
+    return { records };
+}
+/** True when any probe failed or hung — drives the nonzero CLI exit code. */
+export function hasFailureOrHang(collection) {
+    return collection.records.some((r) => r.result.status === "fail" || r.result.status === "hang");
+}

package/build/agent-capabilities/types.js

@@ -0,0 +1,10 @@
+/** Per-agent auth requirement used by the runner's skip-gate and the reporter. */
+export const AGENT_AUTH = {
+    claude: {
+        kind: "interactive",
+        note: "Claude Code authenticates via keychain/OAuth — cannot be verified from the environment.",
+    },
+    "cursor-agent": { kind: "env", varName: "CURSOR_API_KEY" },
+};
+/** Default hard timeout per headless probe run (ms). The cursor `-p` hang bug is version-sensitive. */
+export const DEFAULT_PROBE_TIMEOUT_MS = 90_000;

package/build/agent-launchers/claude.js

@@ -1,15 +1,17 @@
 /**
- * The v1 `claude` agent launcher (BAPI-327).
+ * The `claude` agent launcher (BAPI-327, generalized in BAPI-351).
  *
  * Resolves the `claude` binary against the *baked schedule-time PATH* (not the
- * ambient process default), builds the locked
- * `/full-automation --scheduled-at <T> --idea-file <abs> [--auto-approve]`
- * prompt, and emits `{ exe, args: ["-p", prompt] }`. Claude Code has no
+ * ambient process default) and builds the scheduled-run invocation by delegating
+ * to the shared `renderScheduledPrompt` renderer (no hard-coded `/full-automation`
+ * prompt). It emits `{ exe, args: ["-p", prompt] }`. Claude Code has no
  * working-directory flag, so the cwd is always set by the scheduler unit — this
- * adapter must never add a cwd argument to the invocation.
+ * adapter must never add a working-directory argument to the invocation.
  */
 import { pathApiForPlatform } from "../scheduler-backends/types.js";
 import { posixShellQuote, windowsCmdQuote } from "../scheduler-backends/escaping.js";
+import { renderScheduledPrompt } from "../scheduled-prompt.js";
+import { quotePromptToken } from "../scheduled-prompt.js";
 /**
  * Resolve a bare command to an absolute path using the platform PATH-probe,
  * forcing the baked PATH so the schedule resolves the same binary the user had
@@ -40,24 +42,30 @@ export async function resolveCommandOnPath(command, envPath, deps) {
     return pathApi.normalize(candidate);
 }
 /**
- * Quote the idea-file path so it survives as a single `/full-automation`
- * argument even when it contains spaces or markup-significant characters
- * (`&`, `<`, `>`, …) that would otherwise be split or mangled when the slash
- * command is parsed. Only an embedded double quote needs escaping; the same
- * absolute path is additionally baked into `BRIDGE_GPT_IDEA_FILE` by every
- * backend as a robust environment fallback.
+ * Backward-compatibility shim for callers that quoted an idea-file path for a
+ * `/full-automation` prompt. Generalized prompt-token quoting now lives in
+ * `quotePromptToken`; this preserves the original quote semantics (always wrap in
+ * double quotes, escape embedded quotes) for any remaining path callers.
  */
 export function quoteIdeaFileForPrompt(ideaFile) {
     return `"${ideaFile.replace(/"/g, '\\"')}"`;
 }
+/** Re-export the generalized token quoter so launcher consumers have one import. */
+export { quotePromptToken };
 /**
- * Build the exact full-automation prompt. `--auto-approve` is appended by
- * default; it is omitted only when the caller selected `--no-auto-approve`.
+ * Build the scheduled-run prompt for the Claude launcher by delegating to the
+ * shared renderer. Exposed for focused unit testing of the launcher wiring.
  */
 export function buildClaudePrompt(input) {
-    const base = `/full-automation --scheduled-at ${input.runAtIso} ` +
-        `--idea-file ${quoteIdeaFileForPrompt(input.ideaFile)}`;
-    return input.autoApprove ? `${base} --auto-approve` : base;
+    return renderScheduledPrompt({
+        scheduleId: input.scheduleId,
+        scheduledAt: input.runAtIso,
+        autoApprove: input.autoApprove,
+        commandName: input.commandName,
+        args: input.args,
+        commandBody: input.commandBody,
+        schema: input.schema,
+    });
 }
 const CLAUDE_CAPABILITY = {
     name: "claude",
@@ -65,7 +73,7 @@ const CLAUDE_CAPABILITY = {
     supportsCwdFlag: false,
     promptFlag: "-p",
 };
-/** Create the v1 Claude agent launcher. */
+/** Create the Claude agent launcher. */
 export function createClaudeLauncher() {
     return {
         capability: CLAUDE_CAPABILITY,

package/build/agent-launchers/cursor.js

@@ -0,0 +1,65 @@
+/**
+ * The `cursor-agent` agent launcher (BAPI-351).
+ *
+ * A near-mirror of the Claude launcher: it resolves the `cursor-agent` binary
+ * against the baked schedule-time PATH and builds the scheduled-run prompt via
+ * the shared `renderScheduledPrompt` renderer (so the drift gate and command body
+ * are identical across agents). A local spike confirmed cursor-agent resolves the
+ * same `.claude/commands` catalog and exits cleanly in headless mode.
+ *
+ * Cursor differences vs. Claude:
+ *  - headless invocation needs `--output-format text`, `--trust`, and a
+ *    `--workspace <repoPath>` flag (Cursor's working-directory flag), with the
+ *    prompt as the final positional token;
+ *  - headless auth is via the `CURSOR_API_KEY` environment variable. This adapter
+ *    never reads or prints that value — auth readiness is a prerequisite check.
+ */
+import { posixShellQuote, windowsCmdQuote } from "../scheduler-backends/escaping.js";
+import { renderScheduledPrompt } from "../scheduled-prompt.js";
+import { resolveCommandOnPath } from "./claude.js";
+/** Build the scheduled-run prompt for the Cursor launcher via the shared renderer. */
+export function buildCursorPrompt(input) {
+    return renderScheduledPrompt({
+        scheduleId: input.scheduleId,
+        scheduledAt: input.runAtIso,
+        autoApprove: input.autoApprove,
+        commandName: input.commandName,
+        args: input.args,
+        commandBody: input.commandBody,
+        schema: input.schema,
+    });
+}
+const CURSOR_CAPABILITY = {
+    name: "cursor-agent",
+    command: "cursor-agent",
+    supportsCwdFlag: true,
+    promptFlag: "-p",
+};
+/** Create the cursor-agent launcher. */
+export function createCursorLauncher() {
+    return {
+        capability: CURSOR_CAPABILITY,
+        resolveBinary(envPath, deps) {
+            return resolveCommandOnPath("cursor-agent", envPath, deps);
+        },
+        buildInvocation(exe, input) {
+            const prompt = buildCursorPrompt(input);
+            // Cursor takes the working directory via --workspace and the prompt as the
+            // final positional token; CURSOR_API_KEY (auth) is never placed in argv.
+            const args = [
+                CURSOR_CAPABILITY.promptFlag,
+                "--output-format",
+                "text",
+                "--trust",
+                "--workspace",
+                input.repoPath,
+                prompt,
+            ];
+            return { exe, args, prompt };
+        },
+        formatInvocationLine(invocation, platform) {
+            const quote = platform === "win32" ? windowsCmdQuote : posixShellQuote;
+            return [invocation.exe, ...invocation.args].map((part) => quote(part)).join(" ");
+        },
+    };
+}

package/build/agent-launchers/index.js

@@ -1,17 +1,32 @@
 /**
- * Agent-launcher registry (BAPI-327). v1 ships only `claude`; the lookup returns
- * `null` for every other name so the CLI can reject unsupported agents with a
- * clear message rather than silently falling back.
+ * Agent-launcher registry (BAPI-327, extended in BAPI-351).
+ *
+ * Maps a launcher name to its adapter. BAPI-351 added `cursor-agent` beside the
+ * default `claude`; the lookup returns `null` for every other name so the CLI can
+ * reject unsupported agents with a clear message rather than silently falling
+ * back. The supported names are kept aligned with `AgentName` from
+ * `agent-registry.ts` to avoid registry drift.
  */
 import { createClaudeLauncher } from "./claude.js";
+import { createCursorLauncher } from "./cursor.js";
 export { createClaudeLauncher } from "./claude.js";
+export { createCursorLauncher } from "./cursor.js";
 const CLAUDE_LAUNCHER = createClaudeLauncher();
-/** Return the launcher for a name, or `null` when unsupported in v1. */
+const CURSOR_LAUNCHER = createCursorLauncher();
+/** All supported launcher names, in deterministic order (claude first/default). */
+const LAUNCHER_NAMES = ["claude", "cursor-agent"];
+/** Return the launcher for a name, or `null` when unsupported. */
 export function getAgentLauncher(name) {
-    return name === "claude" ? CLAUDE_LAUNCHER : null;
+    switch (name) {
+        case "claude":
+            return CLAUDE_LAUNCHER;
+        case "cursor-agent":
+            return CURSOR_LAUNCHER;
+        default:
+            return null;
+    }
 }
-/** Comma-separated list of valid agent-launcher names (just `claude` in v1). */
+/** Comma-separated list of valid agent-launcher names (`claude, cursor-agent`). */
 export function formatValidAgentLauncherNames() {
-    const names = ["claude"];
-    return names.join(", ");
+    return LAUNCHER_NAMES.join(", ");
 }

package/build/agent-registry.js

@@ -11,6 +11,19 @@
  * `start-tickets.ts` / `start-tickets-prereqs.ts` / `doctor.ts`) so every other
  * module can import it without risking a circular dependency.
  */
+/**
+ * Conservative allowlist pattern for any model alias before it can reach shell
+ * construction. Mirrors the backend `_MODEL_ALIAS_PATTERN` in jira_api.py.
+ */
+export const MODEL_ALIAS_PATTERN = /^[A-Za-z0-9._:-]+$/;
+/** True only when `value` is a non-empty string matching the alias pattern. */
+export function isValidModelAlias(value) {
+    return typeof value === "string" && value.length > 0 && MODEL_ALIAS_PATTERN.test(value);
+}
+/** Type guard: true only for the three known tier names. */
+export function isModelTier(value) {
+    return value === "cheap" || value === "basic" || value === "premium";
+}
 /**
  * The registry: the ONLY place mapping an agent name to its command/spec. Seeded
  * with exactly `claude` (default) and `cursor-agent`. `as const satisfies` keeps
@@ -28,6 +41,12 @@ export const AGENT_REGISTRY = {
             win32: "npm install -g @anthropic-ai/claude-code",
         },
         authNote: "Claude Code authenticates interactively on first run — follow its login/auth prompt if asked.",
+        supportsModelOverride: true,
+        modelFlag: "--model",
+        // Claude family aliases float to the latest release and never drift, so they
+        // can be validated against a static allowlist.
+        tierModels: { cheap: "haiku", basic: "sonnet", premium: "opus" },
+        staticModelAliasAllowlist: ["haiku", "sonnet", "opus"],
     },
     "cursor-agent": {
         name: "cursor-agent",
@@ -39,6 +58,24 @@ export const AGENT_REGISTRY = {
             win32: "irm 'https://cursor.com/install?win32=true' | iex",
         },
         authNote: "Run cursor-agent login to authenticate; doctor checks PATH presence only, not login state.",
+        supportsModelOverride: true,
+        modelFlag: "--model",
+        // NOTE: Cursor model strings are version-sensitive and DRIFT between
+        // releases — unlike claude's stable family aliases. The ids are not even
+        // internally consistent across versions (Cursor advertises Sonnet/Opus 4.6
+        // as `claude-4.6-sonnet-…`/`claude-4.6-opus-…` but Opus 4.7/4.8 as
+        // `claude-opus-4-7-…`/`claude-opus-4-8-…`), so these defaults WILL go stale.
+        // There is therefore NO staticModelAliasAllowlist here; any resolved cursor
+        // alias is validated non-interactively at runtime (against
+        // `cursor-agent --list-models`) before injection, and an unadvertised id
+        // fail-opens to the cursor default. To pin a current id without a release,
+        // use the per-repo `difficulty_model_tier_overrides` config.
+        // Last verified against `cursor-agent --list-models` on 2026-06-15.
+        tierModels: {
+            cheap: "auto",
+            basic: "claude-4.6-sonnet-medium",
+            premium: "claude-opus-4-8-thinking-high",
+        },
     },
 };
 /** The default agent used when `--agent` is omitted. */
@@ -66,3 +103,34 @@ export function resolveAgentSpec(name) {
 export function formatValidAgentNames() {
     return listAgentNames().join(", ");
 }
+/**
+ * Resolve the concrete model alias to inject for a given agent + tier, applying
+ * an optional per-repo override. Pure and dependency-free: it never spawns a
+ * subprocess and never imports from `start-tickets.ts`.
+ *
+ * Returns `null` (meaning "omit `--model`, use the agent default") when:
+ *  - the agent does not support a model override,
+ *  - no tier is provided,
+ *  - the resolved candidate fails the alias-pattern validation, or
+ *  - the agent has a `staticModelAliasAllowlist` and the candidate is not in it.
+ *
+ * A non-empty override for the selected tier takes precedence over the registry
+ * default. For agents without a static allowlist (e.g. cursor-agent), the caller
+ * is still responsible for live-validating the returned alias before injection.
+ */
+export function resolveModelAlias(agent, tier, overrides) {
+    if (!agent.supportsModelOverride)
+        return null;
+    if (!tier)
+        return null;
+    const override = overrides?.[tier];
+    const candidate = typeof override === "string" && override.trim().length > 0
+        ? override.trim()
+        : agent.tierModels[tier];
+    if (typeof candidate !== "string" || !isValidModelAlias(candidate))
+        return null;
+    if (agent.staticModelAliasAllowlist && !agent.staticModelAliasAllowlist.includes(candidate)) {
+        return null;
+    }
+    return candidate;
+}

package/build/agents.generated.js

@@ -8,6 +8,6 @@ export const AGENTS = {
             "model": "opus",
             "color": "blue"
         },
-        "body": "\nYou are an elite software engineering project manager and technical analyst with deep expertise in codebase archaeology and Jira ticket crafting. You excel at understanding complex codebases, identifying relevant existing code, and translating problem descriptions into precisely-scoped, actionable Jira tickets that engineers can pick up and execute with minimal ambiguity.\n\n## Your Mission\n\nGiven a problem description from the user, you will:\n1. Conduct thorough codebase research to understand the existing architecture, patterns, and relevant code\n2. Write a structured Jira ticket as a new markdown file that references specific files, functions, and patterns from the codebase\n\n## Phase 1: Deep Codebase Research\n\nThis is the most critical phase. You MUST spend significant time here before writing anything. Do NOT rush this phase.\n\n### Research Protocol\n\n1. **Understand the Problem Space**: Re-read the user's problem description carefully. Identify the domain, the affected areas, and the type of change needed (new feature, bug fix, refactor, enhancement).\n\n2. **Map the Relevant Architecture**: \n   - Search for files, modules, and directories related to the problem domain\n   - Read the key source files thoroughly — do not skim\n   - Trace code paths: how does data flow through the relevant parts of the system?\n   - Identify controller -> helper -> service -> model chains if applicable\n\n3. **Identify Extension Points**:\n   - What existing code can be reused or extended?\n   - What patterns does the codebase already use for similar functionality?\n   - Are there helper functions, utilities, or base classes that should be leveraged?\n   - Are there configuration files, metadata definitions, or templates that need modification?\n\n4. **Identify Constraints**:\n   - What conventions does the project follow? (Check CLAUDE.md, README, existing patterns)\n   - What testing patterns are used?\n   - Are there ES5 limitations, specific framework patterns, or platform constraints?\n\n5. **Catalog Your Findings**: Keep mental notes of every relevant file path, function name, pattern, and architectural decision you discover. You will reference these in the ticket.\n\n### Research Depth Guidelines\n- Read at least 5-15 relevant source files in full, more if the problem is complex\n- Follow import chains to understand dependencies\n- Check test files to understand expected behaviors and testing patterns\n- Review configuration and metadata files if relevant\n- Search for TODO comments, known limitations, or related existing issues in the code\n\n## Phase 2: Write the Jira Ticket\n\nAfter completing research, create a new markdown file with the ticket. Use the naming convention `tickets/TICKET-<short-descriptive-name>.md`. If the `tickets/` directory does not exist, create it.\n\n### Ticket Structure\n\nThe markdown file MUST contain exactly these sections:\n\n```markdown\n# [Concise Title Describing the Task]\n\n## Summary\n\n[2-4 sentences describing what this task is about, why it matters, and the high-level approach. Be specific — reference the actual system components involved.]\n\n## Requirements\n\n[Numbered list of specific, actionable requirements. Each requirement should be a clear unit of work.]\n\n1. **[Requirement Title]**: [Description of what needs to be done.]\n   - *Relevant code*: `path/to/file.js` — `functionName()` [brief note on how this code relates]\n   - *Relevant code*: `path/to/other/file.js` — [brief note]\n\n2. **[Requirement Title]**: [Description]\n   - *Relevant code*: ...\n\n[Continue for all requirements]\n\n## Acceptance Criteria\n\n[Checklist format using markdown checkboxes. Each criterion is a testable, verifiable condition.]\n\n- [ ] [Specific, testable criterion]\n- [ ] [Another criterion]\n- [ ] [Continue as needed]\n```\n\n### Writing Guidelines\n\n**Summary**:\n- Be concrete, not abstract. Name the actual components, cartridges, or subsystems involved.\n- State the \"why\" — what problem does this solve or what value does it add?\n- Mention the general technical approach if it's clear from the research.\n\n**Requirements**:\n- Each requirement should represent a logical unit of work\n- Order requirements in a logical implementation sequence when possible\n- ALWAYS cite relevant existing files and functions when they exist. Use exact file paths relative to the project root.\n- Explain HOW the existing code relates: \"extend this function\", \"follow this pattern\", \"reuse this helper\", \"modify this configuration\"\n- If a requirement involves creating new files, suggest where they should live based on existing project structure conventions\n- Be specific about what needs to change vs. what needs to be created new\n- Include requirements for tests, documentation, and configuration/metadata changes if applicable\n\n**Acceptance Criteria**:\n- Every criterion must be independently verifiable\n- Cover functional requirements, edge cases, testing, and non-functional requirements\n- Include criteria for backwards compatibility if relevant\n- Include criteria for test coverage\n- Use checkbox format (`- [ ]`) so engineers can track progress\n\n## Quality Standards\n\n- **No vague language**: Replace \"should handle errors properly\" with \"should catch LLM provider timeouts and return a normalized error response with errorType 'TimeoutError'\"\n- **No assumptions without evidence**: Only reference code you actually read during research. If you're unsure about something, say so explicitly in the ticket.\n- **Appropriate scope**: The ticket should represent a coherent, deliverable unit of work. If the problem is too large, note that it may need to be broken into sub-tasks, but still write the parent ticket.\n- **Developer empathy**: Write as if the developer picking this up has general project knowledge but hasn't recently worked on this specific area. Give them enough context to get started quickly.\n\n## Important Reminders\n\n- Do NOT skip or abbreviate the research phase. The quality of the ticket depends entirely on the depth of your codebase understanding.\n- Do NOT make up file paths or function names. Only reference code you have actually found and read.\n- DO create the markdown file — do not just output the content to the chat. Write it to disk.\n- If the project has specific conventions (from CLAUDE.md or similar), ensure your ticket's requirements align with those conventions.\n"
+        "body": "\nYou are an elite software engineering project manager and technical analyst with deep expertise in codebase archaeology and Jira ticket crafting. You excel at understanding complex codebases, identifying relevant existing code, and translating problem descriptions into precisely-scoped, actionable Jira tickets that engineers can pick up and execute with minimal ambiguity.\n\n## Your Mission\n\nGiven a problem description from the user, you will:\n1. Conduct thorough codebase research to understand the existing architecture, patterns, and relevant code\n2. Write a structured Jira ticket as a new markdown file that references specific files, functions, and patterns from the codebase\n\n## Phase 1: Deep Codebase Research\n\nThis is the most critical phase. You MUST spend significant time here before writing anything. Do NOT rush this phase.\n\n### Research Protocol\n\n1. **Understand the Problem Space**: Re-read the user's problem description carefully. Identify the domain, the affected areas, and the type of change needed (new feature, bug fix, refactor, enhancement).\n\n2. **Map the Relevant Architecture**: \n   - Search for files, modules, and directories related to the problem domain\n   - Read the key source files thoroughly — do not skim\n   - Trace code paths: how does data flow through the relevant parts of the system?\n   - Identify controller -> helper -> service -> model chains if applicable\n\n3. **Identify Extension Points**:\n   - What existing code can be reused or extended?\n   - What patterns does the codebase already use for similar functionality?\n   - Are there helper functions, utilities, or base classes that should be leveraged?\n   - Are there configuration files, metadata definitions, or templates that need modification?\n\n4. **Identify Constraints**:\n   - What conventions does the project follow? (Check CLAUDE.md, README, existing patterns)\n   - What testing patterns are used?\n   - Are there ES5 limitations, specific framework patterns, or platform constraints?\n\n5. **Catalog Your Findings**: Keep mental notes of every relevant file path, function name, pattern, and architectural decision you discover. You will reference these in the ticket.\n\n### Research Depth Guidelines\n- Read at least 5-15 relevant source files in full, more if the problem is complex\n- Follow import chains to understand dependencies\n- Check test files to understand expected behaviors and testing patterns\n- Review configuration and metadata files if relevant\n- Search for TODO comments, known limitations, or related existing issues in the code\n\n## Phase 2: Write the Jira Ticket\n\nAfter completing research, create a new markdown file with the ticket. Use the naming convention `tickets/TICKET-<short-descriptive-name>.md`. If the `tickets/` directory does not exist, create it.\n\n### Ticket Structure\n\nThe markdown file MUST contain exactly these sections:\n\n```markdown\n# [Concise Title Describing the Task]\n\n## Summary\n\n[2-4 sentences describing what this task is about, why it matters, and the high-level approach. Be specific — reference the actual system components involved.]\n\n## Requirements\n\n[Numbered list of specific, actionable requirements. Each requirement should be a clear unit of work.]\n\n1. **[Requirement Title]**: [Description of what needs to be done.]\n   - *Relevant code*: `path/to/file.js` — `functionName()` [brief note on how this code relates]\n   - *Relevant code*: `path/to/other/file.js` — [brief note]\n\n2. **[Requirement Title]**: [Description]\n   - *Relevant code*: ...\n\n[Continue for all requirements]\n\n## Acceptance Criteria\n\n[Bullet list. Each criterion is a testable, verifiable condition.]\n\n- [Specific, testable criterion]\n- [Another criterion]\n- [Continue as needed]\n```\n\n### Writing Guidelines\n\n**Summary**:\n- Be concrete, not abstract. Name the actual components, cartridges, or subsystems involved.\n- State the \"why\" — what problem does this solve or what value does it add?\n- Mention the general technical approach if it's clear from the research.\n\n**Requirements**:\n- Each requirement should represent a logical unit of work\n- Order requirements in a logical implementation sequence when possible\n- ALWAYS cite relevant existing files and functions when they exist. Use exact file paths relative to the project root.\n- Explain HOW the existing code relates: \"extend this function\", \"follow this pattern\", \"reuse this helper\", \"modify this configuration\"\n- If a requirement involves creating new files, suggest where they should live based on existing project structure conventions\n- Be specific about what needs to change vs. what needs to be created new\n- Include requirements for tests, documentation, and configuration/metadata changes if applicable\n\n**Acceptance Criteria**:\n- Every criterion must be independently verifiable\n- Cover functional requirements, edge cases, testing, and non-functional requirements\n- Include criteria for backwards compatibility if relevant\n- Include criteria for test coverage\n- Use plain `-` bullets (Jira's ADF has no native checkbox, so `- [ ]` renders as literal text)\n\n### Output Formatting (Jira upload)\n\nThe ticket is uploaded to Jira, which converts the Markdown to Atlassian Document Format (ADF) and hard-caps the description at **32,767 characters**. Keep the output clean and within budget:\n\n- **Length**: aim for under ~30,000 characters. If the scope genuinely needs more, split into a parent ticket plus sub-tickets rather than one oversized ticket.\n- **Acceptance Criteria**: plain `-` bullets, not `- [ ]` (ADF has no native checkbox).\n- **No images**: do not embed images or use relative image links.\n- **No empty headings**: every heading must have text on its line.\n- **Placeholders**: prefer `{placeholder}` over `<placeholder>`.\n\n## Quality Standards\n\n- **No vague language**: Replace \"should handle errors properly\" with \"should catch LLM provider timeouts and return a normalized error response with errorType 'TimeoutError'\"\n- **No assumptions without evidence**: Only reference code you actually read during research. If you're unsure about something, say so explicitly in the ticket.\n- **Appropriate scope**: The ticket should represent a coherent, deliverable unit of work. If the problem is too large, note that it may need to be broken into sub-tasks, but still write the parent ticket.\n- **Developer empathy**: Write as if the developer picking this up has general project knowledge but hasn't recently worked on this specific area. Give them enough context to get started quickly.\n\n## Important Reminders\n\n- Do NOT skip or abbreviate the research phase. The quality of the ticket depends entirely on the depth of your codebase understanding.\n- Do NOT make up file paths or function names. Only reference code you have actually found and read.\n- DO create the markdown file — do not just output the content to the chat. Write it to disk.\n- If the project has specific conventions (from CLAUDE.md or similar), ensure your ticket's requirements align with those conventions.\n"
     }
 };

package/build/brainstorm-files.js

@@ -0,0 +1,89 @@
+// ---------------------------------------------------------------------------
+// brainstorm-files
+// ---------------------------------------------------------------------------
+// Pure, side-effect-free helpers for naming and writing brainstorm result
+// files. Extracted from ``index.ts`` so they can be unit-tested directly —
+// ``index.ts`` self-executes its CLI/server at module top level and therefore
+// cannot be imported from a test. ``index.ts`` imports these as the single
+// source of truth (no logic is duplicated there).
+import { writeFile, mkdir } from "fs/promises";
+import path from "path";
+/**
+ * Lowercase, strip non-alphanumeric runs, collapse to single hyphens, cap to
+ * ``maxLength`` characters, and trim a trailing hyphen. Shared generic helper
+ * (also used for deep-research query slugs in ``index.ts``).
+ */
+export function slugify(text, maxLength = 60) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .slice(0, maxLength)
+        .replace(/-$/, "");
+}
+export function sanitizeProviderForFilename(provider) {
+    // Defensive: allow letters/digits/hyphen/underscore only; collapse runs and
+    // trim trailing punctuation. Falls back to "provider" for an empty result.
+    const cleaned = provider
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return cleaned || "provider";
+}
+/**
+ * Build the on-disk filename for one brainstorm result row.
+ *
+ * When the original task ``subject`` is available and slugifies to a non-empty
+ * string, use a human-readable semantic name:
+ *   ``{slugified-subject}-{short_brainstorm_id}-{provider}.md``
+ * where ``short_brainstorm_id`` is the first 8 chars of the brainstorm UUID
+ * (enough for practical uniqueness / idempotent overwrite on re-runs).
+ *
+ * The UUID-only pattern ``{brainstorm_id}-{provider}.md`` is the intentional
+ * backward-compatible fallback, used only when no subject is provided, the
+ * subject is whitespace-only, or ``slugify(subject)`` returns an empty string
+ * (e.g. punctuation-only). This keeps callers without a subject — notably the
+ * ``get_brainstorm`` retrieval path, whose result envelope does not echo
+ * ``task_description`` — safe and unchanged.
+ */
+export function buildBrainstormResultFilename(envelope, row, subject) {
+    const providerSegment = sanitizeProviderForFilename(row.provider);
+    const subjectSlug = subject ? slugify(subject) : "";
+    const shortId = envelope.brainstorm_id.slice(0, 8);
+    if (subjectSlug) {
+        return `${subjectSlug}-${shortId}-${providerSegment}.md`;
+    }
+    return `${envelope.brainstorm_id}-${providerSegment}.md`;
+}
+/**
+ * Write each brainstorm result row's markdown into ``dir`` using
+ * ``buildBrainstormResultFilename`` for the name. ``index.ts`` wraps this with
+ * the resolved ``BAPI_DOCS_DIR/brainstorm`` directory.
+ *
+ * Behavior is fail-open: rows without markdown are skipped, the directory is
+ * created recursively, markdown is written as UTF-8, and per-row write failures
+ * are swallowed so saving never blocks the tool response.
+ */
+export async function saveBrainstormResultsToDir(envelope, dir, subject) {
+    const savedPaths = [];
+    for (const row of envelope.results) {
+        const markdown = row.markdown;
+        if (!markdown) {
+            continue;
+        }
+        const filename = buildBrainstormResultFilename(envelope, row, subject);
+        const filePath = path.join(dir, filename);
+        try {
+            await mkdir(dir, { recursive: true });
+            await writeFile(filePath, markdown, "utf-8");
+            savedPaths.push(filePath);
+        }
+        catch {
+            // Skip rows that fail to write — never block the response.
+        }
+    }
+    return savedPaths;
+}