opencode-swarm 7.16.0 → 7.17.1

package/README.md

@@ -36,7 +36,7 @@ Most AI coding tools let one model write code and ask that same model whether th
 - 🔒 **Gated pipeline** — code never ships without reviewer + test engineer approval
 - 🔄 **Phase completion gates** — completion-verify and drift verifier gates enforced before phase completion
 - 🔁 **Resumable sessions** — all state saved to `.swarm/`; pick up any project any day
-- 🌐 **20 languages** — TypeScript, Python, Go, Rust, Java, Kotlin, C/C++, C#, Ruby, Swift, Dart, PHP, JavaScript, CSS, Bash, PowerShell, INI, Regex
+- 🌐 **20 languages** — TypeScript, Python, Go, Rust, Java, Kotlin, C/C++, C#, Ruby, Swift, Dart, PHP, JavaScript, CSS, Bash, PowerShell, INI, Regex (extending: see [docs/adding-a-language.md](docs/adding-a-language.md))
 - 🛡️ **Built-in security** — SAST, secrets scanning, dependency audit per task
 - 🆓 **Free tier** — works with OpenCode Zen's free model roster
 - ⚙️ **Fully configurable** — override any agent's model, disable agents, tune guardrails

package/dist/agents/index.d.ts

@@ -1,6 +1,7 @@
 import type { AgentConfig as SDKAgentConfig } from '@opencode-ai/sdk';
 import { type PluginConfig } from '../config';
 import { type AgentDefinition } from './architect';
+import { type ProjectContext } from './template';
 export type { AgentDefinition } from './architect';
 /**
  * Strip the user-defined swarm prefix from an agent name to get the base
@@ -41,7 +42,7 @@ export declare function getSwarmAgents(): Record<string, {
 /**
  * Create all agent definitions with configuration applied
  */
-export declare function createAgents(config?: PluginConfig): AgentDefinition[];
+export declare function createAgents(config?: PluginConfig, projectContext?: ProjectContext): AgentDefinition[];
 /**
  * Resolve the set of generated agent names that should be marked as primary
  * for OpenCode's session-default-agent resolution.
@@ -73,7 +74,7 @@ export declare function resolvePrimaryAgentNames(agentNames: string[], defaultAg
 /**
  * Get agent configurations formatted for the OpenCode SDK.
  */
-export declare function getAgentConfigs(config?: PluginConfig, directory?: string, sessionId?: string): Record<string, SDKAgentConfig>;
+export declare function getAgentConfigs(config?: PluginConfig, directory?: string, sessionId?: string, projectContext?: ProjectContext): Record<string, SDKAgentConfig>;
 export { createArchitectAgent } from './architect';
 export { createCoderAgent } from './coder';
 export { DOMAIN_EXPERT_COUNCIL_PROMPT, GENERALIST_COUNCIL_PROMPT, SKEPTIC_COUNCIL_PROMPT, } from './council-prompts';

package/dist/agents/project-context.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Build a `ProjectContext` for agent prompt template substitution.
+ *
+ * Called from `src/index.ts:initializeOpenCodeSwarm` immediately before
+ * `getAgentConfigs(...)` (Phase 4b of the language-agnostic plugin work).
+ * Wrapped in `withTimeout(2000ms)` by the caller; on timeout or any
+ * failure, the caller falls open to `emptyProjectContext()` per
+ * Invariant 1 (plugin init bounded + fail-open).
+ *
+ * Imported lazily by the caller via `await import('./agents/project-context')`
+ * to keep the dispatch import graph off the synchronous init prelude.
+ *
+ * Invariant 1 budget — Phase 4b NOTE:
+ * This module DOES NOT spawn subprocesses on the session-init critical
+ * path. The full `LanguageBackend.selectTestFramework` /
+ * `selectBuildCommand` hooks call `isCommandAvailable` (which spawns
+ * `where`/`which` and can take 200–500ms per call on Windows). Even with
+ * the 2000ms `withTimeout` wrapper, multiple sequential spawns
+ * (typically 3–5 per buildProjectContext call) easily push `server()`
+ * past the 400ms Invariant 1 deadline asserted by
+ * `scripts/repro-704.mjs:TIMING_DEADLINE_MS`.
+ *
+ * The architect prompt's `TEST_CMD` / `BUILD_CMD` / `LINT_CMD` values are
+ * HINTS for the LLM. If the user doesn't have the named binary installed,
+ * the actual test-runner / build-runner tool will surface a clear error
+ * at invocation time — there is no correctness regression from skipping
+ * the PATH probe at session init.
+ */
+import { pickBackend, pickedProfiles } from '../lang/dispatch';
+import { type ProjectContext } from './template';
+/**
+ * Wall-clock budget for the session-init language-backend resolution step.
+ * Caller (`src/index.ts:initializeOpenCodeSwarm`) wraps `buildProjectContext`
+ * in `withTimeout(LANG_BACKEND_DETECTION_TIMEOUT_MS)`. Exceeding the budget
+ * fails open with `null` so the manifest still returns to the OpenCode
+ * plugin host (Invariant 1).
+ */
+export declare const LANG_BACKEND_DETECTION_TIMEOUT_MS = 300;
+declare const _internals: {
+    pickBackend: typeof pickBackend;
+    pickedProfiles: typeof pickedProfiles;
+};
+export { _internals };
+/**
+ * Resolve the `ProjectContext` for `directory`. Uses `pickBackend` to find
+ * the dominant language, then queries the backend's PROFILE DATA (not its
+ * spawn-bearing hooks) for build/test/lint commands. Calls the optional
+ * `selectFramework` and `selectEntryPoints` hooks because those are
+ * filesystem-only (no spawn) per the backend purity invariant.
+ *
+ * Per-backend constraint blocks (coder/test/reviewer) come from
+ * `backend.prompts` — pure data.
+ *
+ * Returns `null` (caller substitutes `emptyProjectContext()`) when no
+ * backend is detected — the architect's existing DISCOVER mode handles
+ * the resulting `unresolved` sentinel placeholders.
+ */
+export declare function buildProjectContext(directory: string): Promise<ProjectContext | null>;

package/dist/agents/template.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Agent prompt template renderer.
+ *
+ * Replaces `{{KEY}}` placeholders in agent prompt strings with values from
+ * a `ProjectContext` resolved at session-init time. Strict by design:
+ * unknown placeholders raise (caught at build time by
+ * `tests/unit/agents/template-substitution.test.ts`), so a typo never
+ * leaks to the model.
+ *
+ * Phase 4b of language-agnostic plugin work. Pinned call site is
+ * `src/index.ts:initializeOpenCodeSwarm` immediately before
+ * `getAgentConfigs(...)` — see the `withTimeout(2000ms)` wrapping there
+ * to honor invariant 1 (plugin init bounded + fail-open).
+ */
+/**
+ * Variables available for substitution into agent prompts. Every prompt's
+ * `{{KEY}}` placeholders must be a key of this interface; the renderer
+ * rejects unknown placeholders. New variables go here AND in
+ * `buildProjectContext` in `src/index.ts`.
+ */
+export interface ProjectContext {
+    PROJECT_LANGUAGE: string;
+    PROJECT_FRAMEWORK: string;
+    BUILD_CMD: string;
+    TEST_CMD: string;
+    LINT_CMD: string;
+    ENTRY_POINTS: string;
+    /**
+     * Per-language coder constraint bullets (already escaped for inclusion
+     * in a TypeScript template literal — see `escapeForTemplate`).
+     */
+    CODER_CONSTRAINTS: string;
+    /** Per-language test-writing constraint bullets. */
+    TEST_CONSTRAINTS: string;
+    /** Per-language reviewer-checklist bullets. */
+    REVIEWER_CHECKLIST: string;
+    /**
+     * When backend detection finds multiple equal-tier languages, this is
+     * a comma-separated list of the runner-up language ids; empty string
+     * when only one language is detected.
+     */
+    PROJECT_CONTEXT_SECONDARY_LANGUAGES: string;
+}
+/**
+ * Sentinel substituted into placeholders when the backend cannot resolve
+ * a value (no manifest, binary missing, detection timed out). The
+ * architect prompt's existing DISCOVER mode handles this — same contract
+ * as today, but the trigger is now a literal sentinel string rather than
+ * a templating leak.
+ */
+export declare const UNRESOLVED = "unresolved (run /swarm preflight)";
+/** Empty `ProjectContext` — used by fail-open paths and tests. */
+export declare function emptyProjectContext(): ProjectContext;
+/**
+ * Escape a string for safe inclusion inside a TypeScript template literal.
+ * Specifically:
+ *   - Backticks `` ` `` become `` \` `` (otherwise terminate the literal).
+ *   - `${` becomes `\${` (otherwise begins an interpolation).
+ *   - Backslashes are preserved as-is (template literals don't double-escape
+ *     them when read at runtime — only at parse time, which we're past).
+ *
+ * See `.claude/skills/engineering-conventions/SKILL.md` "Agent prompt
+ * strings — escaping pitfalls" for context. Profile-author-supplied
+ * constraint strings (e.g. `LanguageProfile.prompts.coderConstraints`)
+ * routinely contain backticks (when describing code idioms like `bun:test`).
+ * The renderer auto-escapes them so a profile author can't accidentally
+ * break agent compilation.
+ */
+export declare function escapeForTemplate(s: string): string;
+/**
+ * Render `prompt` with `vars`. Replaces every `{{KEY}}` whose KEY is a
+ * documented `ProjectContext` field. Unknown placeholders raise.
+ *
+ * The renderer is intentionally simple — single-pass, no nesting, no
+ * conditionals, no loops. Agent prompts that need conditional sections
+ * should pre-compute a string variable in `buildProjectContext` and
+ * substitute it as a single placeholder.
+ */
+export declare function renderPrompt(prompt: string, vars: ProjectContext): string;
+/**
+ * Convert an array of constraint strings into a bulleted block ready for
+ * inclusion in an agent prompt via `{{CODER_CONSTRAINTS}}` etc.
+ * Each item is escaped for template-literal safety.
+ */
+export declare function bulletList(items: readonly string[]): string;

package/dist/build/discovery.d.ts

@@ -1,4 +1,5 @@
 import { tool } from '@opencode-ai/plugin';
+import { bunSpawnSync } from '../utils/bun-compat';
 export interface BuildCommand {
     ecosystem: string;
     command: string;
@@ -16,10 +17,6 @@ export interface BuildDiscoveryOptions {
     scope?: 'changed' | 'all';
     changedFiles?: string[];
 }
-/**
- * Check if a command exists on PATH
- * Uses 'where' on Windows, 'which' on Unix
- */
 export declare function isCommandAvailable(command: string): boolean;
 /**
  * Discover build commands using language profiles (primary detection path)
@@ -30,6 +27,7 @@ export declare const _internals: {
     discoverBuildCommands: typeof discoverBuildCommands;
     clearToolchainCache: typeof clearToolchainCache;
     getEcosystems: typeof getEcosystems;
+    spawnSyncImpl: typeof bunSpawnSync;
 };
 export declare function discoverBuildCommandsFromProfiles(workingDir: string): Promise<BuildDiscoveryResult>;
 /**