@mknightzzz/stw 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mknightz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+# stw
+
+**Spec-to-Workers** (pronounced "stew") — a CLI orchestrator that turns markdown specs into reviewed, merge-ready code changes using AI agents.
+
+You write a spec (or describe an idea), STW decomposes it into isolated tasks, routes each to an AI worker, validates the output, and produces a merge request with all changes.
+
+## How it works
+
+```
+spec.md ──> planner ──> task graph ──> workers ──> review ──> MR
+                          T1 ──────> worker ──> validate ──┐
+                          T2 ──────> worker ──> validate ──┤
+                          T3 (dep: T1) ─> worker ─> validate ┘
+```
+
+1. **Ingest** — validates your spec and creates a run
+2. **Plan** — an AI planner decomposes the spec into a task graph with scopes, dependencies, and acceptance checks
+3. **Run** — workers execute tasks in dependency order, each in an isolated git worktree
+4. **Review** — mechanical checks (tests, typecheck, scope) + optional LLM review
+5. **Retry** — failed tasks get diagnostic context and retry with tier escalation
+6. **Merge** — completed work is pushed and synced as a GitLab/GitHub MR
+
+## Quick start
+
+### 1. Install
+
+```bash
+npm install -g stw
+```
+
+### 2. Prerequisites
+
+STW needs an API provider for AI models and (optionally) an agentic backend for complex tasks.
+
+**API provider** (required): An OpenAI-compatible API endpoint. [OpenRouter](https://openrouter.ai) works out of the box and gives access to multiple model families.
+
+**Agentic backend** (optional, recommended): Either [OpenCode](https://github.com/opencode-ai/opencode) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code) for tasks that need iterative exploration (read-edit-test loops).
+
+### 3. Initialize
+
+```bash
+cd your-repo
+stw init
+```
+
+This creates `.stw/config.yml` with model routing, budget limits, and backend settings. Default preset is `minimax` (balanced cost/quality). Other presets: `glm5` (budget), `anthropic` (premium), `mixed` (multi-provider).
+
+Set your API key:
+```bash
+export OPENROUTER_API_KEY="sk-or-..."
+```
+
+### 4. Check readiness
+
+```bash
+stw doctor
+```
+
+Verifies: API keys are set, agentic backends are installed, config is valid.
+
+### 5. Create a spec
+
+Write a markdown spec describing what you want built:
+
+```markdown
+# Spec: Add rate limiting to API endpoints
+
+## Objective
+Add configurable rate limiting to all public API endpoints.
+
+## Requirements
+
+### T1: Rate limiter middleware
+Create a rate limiting middleware in src/middleware/rate-limit.ts.
+- Accept requests-per-minute and burst-size as parameters
+- Use a sliding window algorithm
+- Return 429 with Retry-After header when exceeded
+
+### T2: Apply middleware to routes
+Wire the rate limiter into src/routes/api.ts for all public endpoints.
+- Default: 60 requests/minute, burst of 10
+- Make limits configurable via environment variables
+
+## Constraints
+- No external dependencies (use in-memory store)
+- Must not break existing tests
+```
+
+Save it as `specs/rate-limiting.md`.
+
+### 6. Run
+
+```bash
+# Ingest the spec and create a run
+stw ingest specs/rate-limiting.md
+
+# Auto-plan tasks (or provide your own task graph)
+stw plan-auto <run-id>
+
+# Execute all tasks
+stw run <run-id>
+
+# Check progress
+stw progress <run-id>
+
+# Push to GitLab/GitHub
+stw merge <run-id>
+```
+
+Or use the shortcut that does ingest + plan + run in one command:
+
+```bash
+stw go "add rate limiting to API endpoints" --spec specs/rate-limiting.md
+```
+
+Or skip the spec entirely — just describe what you want:
+
+```bash
+stw go "add dark mode toggle to the settings page"
+```
+
+STW generates a structured spec from your rough idea, plans tasks, and executes them.
+
+## Configuration
+
+STW uses `.stw/config.yml` in your repo root. Key sections:
+
+```yaml
+# API providers — where to send model requests
+providers:
+  openrouter:
+    api_key_env: OPENROUTER_API_KEY        # env var name (not the key itself)
+    base_url: https://openrouter.ai/api/v1
+    models:
+      strong: anthropic/claude-sonnet-4     # for planning, review, complex tasks
+      medium: openai/gpt-4.1-mini          # for moderate tasks
+      cheap: google/gemini-2.5-flash       # for mechanical/simple tasks
+
+# How tasks are routed to providers
+routing_policy:
+  require_plan_approval: true              # require human approval before execution
+  provider_preferences:
+    strong: [openrouter]
+    medium: [openrouter]
+    cheap: [openrouter]
+
+# Execution defaults
+defaults:
+  max_retries: 2                           # retries per task before escalation
+  max_concurrent_workers: 2                # parallel task execution
+  task_timeout_minutes: 30
+  api_timeout_seconds: 120
+  execution_mode: agentic                  # 'agentic' or 'conservative'
+
+  # Agentic backend config (for iterative task execution)
+  agentic:
+    default_backend: opencode              # 'opencode' or 'claude-code'
+    backends:
+      opencode:
+        command: opencode                  # path to opencode binary
+      claude-code:
+        command: claude                    # path to claude binary
+
+# Optional: per-run budget limits
+budget:
+  max_run_usd: 5.00
+  warn_at_usd: 3.00
+```
+
+### Model tiers
+
+STW routes tasks to models based on complexity:
+
+| Tier | Use case | Example models |
+|------|----------|----------------|
+| **cheap** | Mechanical refactors, simple edits | gemini-2.5-flash, minimax-m2.5 |
+| **medium** | Moderate reasoning, test writing | gpt-4.1-mini, minimax-m2.7 |
+| **strong** | Planning, review, complex logic | claude-sonnet-4, kimi-k2.5 |
+
+The planner assigns tiers automatically. If a task fails, STW escalates to the next tier and retries.
+
+## Architecture
+
+```
+src/
+  cli.ts              # Command-line interface (commander.js)
+  planner.ts          # AI planner — decomposes specs into task graphs
+  planner-prompt.ts   # Planner prompt construction + import graph
+  task-executor.ts    # Task execution pipeline (worker → review → retry)
+  worker-runner.ts    # Worker dispatch (single-call API or agentic subprocess)
+  task-review.ts      # Mechanical review + LLM review phase
+  validation.ts       # Acceptance check execution (tests, typecheck)
+  router.ts           # Model tier routing with escalation
+  provider.ts         # OpenAI-compatible API client
+  agentic-runtime.ts  # Agentic backend subprocess management
+  parallel.ts         # Parallel task execution + merge-back
+  scope.ts            # Scope enforcement (which files a task can touch)
+  cost.ts             # Cost tracking and budget enforcement
+  config.ts           # Config loading and validation
+  git-utils.ts        # Git operations (worktrees, diffs, merges)
+
+tests/               # 1100+ tests (vitest)
+specs/                # Spec files (input)
+.stw/                 # Runtime state (runs, tasks, artifacts)
+  config.yml          # Project configuration
+  runs/               # Per-run state and artifacts
+    <run-id>/
+      manifest.json   # Run metadata
+      tasks/
+        T1/           # Per-task artifacts
+          status.json
+          diff.patch
+          worker_prompt.md
+          response.json
+```
+
+## CLI commands
+
+| Command | Description |
+|---------|-------------|
+| `stw init` | Initialize repo with `.stw/config.yml` |
+| `stw idea <description>` | Generate a spec from a rough idea |
+| `stw ingest <spec>` | Validate spec and create a run |
+| `stw plan-auto <run-id>` | AI-generate task graph from spec |
+| `stw run <run-id>` | Execute all tasks in dependency order |
+| `stw go <spec>` | Ingest + plan + run in one command |
+| `stw progress <run-id>` | Show run progress and task status |
+| `stw status <run-id>` | Detailed run/task status |
+| `stw retry <run-id> <task-id>` | Retry a failed/escalated task |
+| `stw resume <run-id>` | Resume from last checkpoint |
+| `stw stop <run-id>` | Pause a running run |
+| `stw continue <run-id>` | Resume a paused run |
+| `stw merge <run-id>` | Push and create MR |
+| `stw doctor` | Check local readiness |
+| `stw cleanup [run-id]` | Clean up old runs/worktrees |
+| `stw logs <run-id>` | View structured logs |
+
+## How tasks execute
+
+Each task runs in an isolated git worktree branched from the run branch:
+
+1. **Worktree created** — fresh copy of the codebase
+2. **Dependencies installed** — `npm ci` if `package-lock.json` exists
+3. **Worker executes** — either a single API call (fast, cheap) or an agentic session (iterative, higher quality)
+4. **Scope enforced** — worker output is checked against declared scope files
+5. **Acceptance checks run** — tests, typecheck, linter (configured per task)
+6. **LLM review** (optional) — a reviewer model checks the diff
+7. **On failure** — diagnostic context is captured, task retries with the previous attempt's errors
+8. **On exhausted retries** — tier escalates (cheap → medium → strong), or task is marked escalated for human review
+9. **On success** — changes merge back to the run branch
+
+## Troubleshooting
+
+**"No models configured for requested tier"** — Your `.stw/config.yml` is missing model entries for the tier the planner assigned. Add models to your provider's `models` section or adjust the preset.
+
+**"Planner received null content"** — The planner model returned empty output. This happens with some reasoning models when `max_tokens` is too low. Try a different model or increase `api_timeout_seconds`.
+
+**Task keeps escalating** — Check `.stw/runs/<run-id>/tasks/<task-id>/diagnostic.json` for the failure reason. Common causes: acceptance checks reference non-existent files, scope is too narrow (missing caller files), or the spec is ambiguous.
+
+**"Agentic backend failed"** — The agentic backend (opencode/claude) crashed or timed out. Run `stw doctor` to verify it's installed. Check `agentic_transcript.txt` in the task directory for details.
+
+**Budget exceeded** — Run `stw progress <run-id>` to see cost breakdown. Adjust `budget.max_run_usd` in config or use `stw continue <run-id>` to resume with remaining budget.
+
+## Development
+
+```bash
+git clone https://gitlab.com/mygelknightz/mamarracho.git stw
+cd stw
+npm install
+npm test          # run all tests
+npm run lint      # eslint + tsc
+npm run build     # compile TypeScript
+```
+
+## License
+
+MIT

package/dist/agentic-fallback.d.ts

@@ -0,0 +1,3 @@
+import type { StwConfig, Task } from './types.js';
+export declare function shouldFallbackToAgentic(task: Task, config: StwConfig): boolean;
+export declare function buildAgenticFallbackTask(task: Task, config: StwConfig): Task;

package/dist/agentic-fallback.js

@@ -0,0 +1,32 @@
+export function shouldFallbackToAgentic(task, config) {
+    // If already agentic, no need to fallback
+    if (task.planner_metadata?.execution_mode === 'agentic') {
+        return false;
+    }
+    const fallback = config.defaults.agentic_fallback;
+    if (!fallback?.enabled) {
+        return false;
+    }
+    // If task_types is empty or undefined, all task types are eligible
+    // Only filter if task_types is explicitly provided with items
+    if (fallback.task_types && fallback.task_types.length > 0 && !fallback.task_types.includes(task.task_type)) {
+        return false;
+    }
+    // Filter by risk levels if specified
+    if (fallback.risk_levels && fallback.risk_levels.length > 0 && !fallback.risk_levels.includes(task.risk)) {
+        return false;
+    }
+    return true;
+}
+export function buildAgenticFallbackTask(task, config) {
+    return {
+        ...task,
+        planner_metadata: {
+            ...task.planner_metadata,
+            execution_mode: 'agentic',
+            agentic_backend: task.planner_metadata?.agentic_backend ?? config.defaults.agentic?.default_backend,
+            fallback_to_single_call: true,
+        },
+    };
+}
+//# sourceMappingURL=agentic-fallback.js.map

package/dist/agentic-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentic-fallback.js","sourceRoot":"","sources":["../src/agentic-fallback.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,uBAAuB,CAAC,IAAU,EAAE,MAAiB;IACnE,0CAA0C;IAC1C,IAAI,IAAI,CAAC,gBAAgB,EAAE,cAAc,KAAK,SAAS,EAAE,CAAC;QACxD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAClD,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mEAAmE;IACnE,8DAA8D;IAC9D,IAAI,QAAQ,CAAC,UAAU,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3G,OAAO,KAAK,CAAC;IACf,CAAC;IAED,qCAAqC;IACrC,IAAI,QAAQ,CAAC,WAAW,IAAI,QAAQ,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACzG,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,IAAU,EAAE,MAAiB;IACpE,OAAO;QACL,GAAG,IAAI;QACP,gBAAgB,EAAE;YAChB,GAAG,IAAI,CAAC,gBAAgB;YACxB,cAAc,EAAE,SAAS;YACzB,eAAe,EAAE,IAAI,CAAC,gBAAgB,EAAE,eAAe,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,eAAe;YACnG,uBAAuB,EAAE,IAAI;SAC9B;KACF,CAAC;AACJ,CAAC"}

package/dist/agentic-prompt.d.ts

@@ -0,0 +1,2 @@
+import { type BuildWorkerPromptOptions } from './prompt-builder.js';
+export declare function buildAgenticPrompt(options: BuildWorkerPromptOptions): string;

package/dist/agentic-prompt.js

@@ -0,0 +1,68 @@
+import { join } from 'node:path';
+import { writeAtomic } from './storage.js';
+import { buildRetryContext, gatherTaskContext, getSpecContext, renderContextFiles, renderList, withResolvedQuestionAnswers, } from './prompt-builder.js';
+export function buildAgenticPrompt(options) {
+    const resolvedOptions = withResolvedQuestionAnswers(options);
+    const contextFiles = gatherTaskContext(resolvedOptions.repoRoot, resolvedOptions.task.scope.files);
+    const prompt = renderAgenticPrompt(resolvedOptions, contextFiles);
+    writeAtomic(join(resolvedOptions.taskDir, 'agentic_prompt.md'), prompt + '\n');
+    return prompt;
+}
+function renderAgenticPrompt(options, contextFiles) {
+    const specContext = getSpecContext(options.repoRoot, options.task.spec_path, options.task.id);
+    const specSection = specContext ? ['', '## Spec Context', '', specContext] : [];
+    const questionAnswers = options.questionAnswers
+        ? Object.entries(options.questionAnswers)
+            .map(([questionNumber, answer]) => [Number(questionNumber), answer])
+            .sort((left, right) => left[0] - right[0])
+        : [];
+    const persistedAnswers = questionAnswers.length > 0
+        ? [
+            '',
+            '## Persisted Human Answers',
+            'The following answers have been provided to previous questions:',
+            ...questionAnswers.map(([num, answer]) => `- Question ${num}: ${answer}`),
+        ]
+        : [];
+    const retryContext = options.retryReason
+        ? ['', buildRetryContext(options.taskDir, options.retryReason, options.retryContextLevel ?? 'full')]
+        : [];
+    return [
+        'You are the worker for one Spec-to-Workers task running in agentic mode.',
+        `Task ID: ${options.task.id}`,
+        `Task Description: ${options.task.description}`,
+        '',
+        'You are executing directly inside the task worktree.',
+        'Edit files in place only within the declared task scope.',
+        'Do not return a structured JSON file-response artifact.',
+        'Your job is to mutate the worktree directly and leave the final state ready for validation.',
+        '',
+        'Allowed file scope:',
+        renderList(options.task.scope.files),
+        '',
+        'Prohibited areas:',
+        '- Any file not explicitly listed in the allowed file scope',
+        '- Supporting context files included below are read-only unless they are also in scope',
+        '',
+        'Success conditions:',
+        '- The resulting worktree changes stay within declared scope',
+        '- Acceptance checks should pass after your edits',
+        '- Leave the worktree in a reviewable state',
+        '',
+        'Code conventions:',
+        '- TypeScript with ESM modules: use .js extensions in relative imports (e.g., import { foo } from "./bar.js")',
+        '- Follow the patterns shown in the repository context files below',
+        '',
+        'Acceptance checks:',
+        renderList(options.task.acceptance_checks),
+        ...retryContext,
+        ...persistedAnswers,
+        ...specSection,
+        '',
+        'Repository context:',
+        renderContextFiles(contextFiles),
+    ]
+        .flat()
+        .join('\n');
+}
+//# sourceMappingURL=agentic-prompt.js.map

package/dist/agentic-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentic-prompt.js","sourceRoot":"","sources":["../src/agentic-prompt.ts"],"names":[],"mappings":"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"}

package/dist/agentic-runtime.d.ts

@@ -0,0 +1,48 @@
+import type { AgenticBackend, AgenticBackendConfig } from './agentic-types.js';
+import type { ActionableFailureClass, ExecutionObservabilityMode, StwConfig, Task } from './types.js';
+export interface AgenticRunArtifact {
+    schema_version: 1;
+    task_id: string;
+    backend: AgenticBackend;
+    command: string[];
+    transcript_path: string;
+    summary_path: string;
+    changed_files: string[];
+    acceptance_checks_executed: boolean;
+    fallback_used: boolean;
+    exit_code: number;
+    model?: string;
+    execution_mode: ExecutionObservabilityMode;
+    failure_class?: ActionableFailureClass;
+}
+export declare function buildAgenticCommand(backend: AgenticBackend, prompt: string, promptPath: string, commandOverride?: string[], modelOverride?: string): string[];
+export declare function formatBackendTranscript(backend: AgenticBackend, transcript: string, backendConfig?: AgenticBackendConfig): string;
+export declare function getTaskExecutionObservabilityMode(task: Task): ExecutionObservabilityMode;
+export declare function persistAgenticArtifacts(taskDir: string, input: {
+    task: Task;
+    backend: AgenticBackend;
+    command: string[];
+    transcript: string;
+    changedFiles: string[];
+    exitCode: number;
+    model?: string;
+    failureClass?: ActionableFailureClass;
+}): void;
+export declare function listChangedFiles(output: string, toRelativePath: (filePath: string) => string): string[];
+export declare function resolveAgenticTierSelection(task: Task, config: StwConfig): {
+    backend: AgenticBackend;
+    model?: string;
+};
+export interface AgenticUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cost_usd: number;
+    steps: number;
+}
+/**
+ * Parses JSONL output from an agentic backend (opencode --format json or claude-code --output-format json)
+ * and sums token usage and cost from all step_finish events.
+ *
+ * Returns null if no step_finish events are found (e.g. plain text output).
+ */
+export declare function parseAgenticUsage(output: string): AgenticUsage | null;

package/dist/agentic-runtime.js

@@ -0,0 +1,149 @@
+import { join } from 'node:path';
+import { writeAtomic, writeJson } from './storage.js';
+export function buildAgenticCommand(backend, prompt, promptPath, commandOverride, modelOverride) {
+    if (backend === 'opencode') {
+        const base = commandOverride && commandOverride.length > 0 ? [commandOverride[0] ?? 'opencode'] : ['opencode'];
+        if (modelOverride && !base.includes('-m') && !base.includes('--model')) {
+            base.push('-m', modelOverride);
+        }
+        base.push('run', '--format', 'json');
+        return [...base, 'Follow the attached task contract exactly.', '-f', promptPath];
+    }
+    const claudeBase = commandOverride && commandOverride.length > 0 ? [...commandOverride] : ['claude'];
+    if (modelOverride && !claudeBase.includes('--model')) {
+        claudeBase.push('--model', modelOverride);
+    }
+    if (!claudeBase.includes('-p')) {
+        claudeBase.push('-p');
+    }
+    // Restrict Claude Code to safe tools only (no Agent spawning inside worker tasks)
+    if (!claudeBase.includes('--allowedTools')) {
+        claudeBase.push('--allowedTools', 'Edit,Write,Read,Bash,Glob,Grep');
+    }
+    // Request JSON output for structured transcript parsing
+    if (!claudeBase.includes('--output-format')) {
+        claudeBase.push('--output-format', 'json');
+    }
+    if (commandOverride && commandOverride.length > 0) {
+        return [...claudeBase, prompt];
+    }
+    switch (backend) {
+        case 'claude-code':
+            return [...claudeBase, prompt];
+    }
+}
+export function formatBackendTranscript(backend, transcript, backendConfig) {
+    const defaultFormat = backend === 'opencode' ? 'jsonl' : 'plain';
+    const format = backendConfig?.transcript_format ?? defaultFormat;
+    const header = backend === 'opencode'
+        ? format === 'jsonl'
+            ? '[opencode transcript: jsonl]'
+            : '[opencode transcript]'
+        : format === 'jsonl'
+            ? '[claude-code transcript: jsonl]'
+            : '[claude-code transcript]';
+    return `${header}\n${transcript}`.trim() + '\n';
+}
+export function getTaskExecutionObservabilityMode(task) {
+    if (task.planner_metadata?.execution_mode === 'agentic') {
+        return task.planner_metadata?.fallback_to_single_call === true ? 'fallback_to_agentic' : 'direct_agentic';
+    }
+    return 'conservative_only';
+}
+export function persistAgenticArtifacts(taskDir, input) {
+    const transcriptPath = join(taskDir, 'agentic_transcript.txt');
+    const summaryPath = join(taskDir, 'agentic_summary.json');
+    const executionMode = getTaskExecutionObservabilityMode(input.task);
+    writeAtomic(transcriptPath, input.transcript);
+    const summary = {
+        schema_version: 1,
+        task_id: input.task.id,
+        backend: input.backend,
+        command: input.command,
+        changed_files: input.changedFiles,
+        acceptance_checks_executed: false,
+        fallback_used: input.task.planner_metadata?.fallback_to_single_call === true,
+        transcript_preview: input.transcript.slice(0, 500),
+        execution_mode: executionMode,
+        failure_class: input.failureClass,
+    };
+    writeJson(summaryPath, summary);
+    const artifact = {
+        schema_version: 1,
+        task_id: input.task.id,
+        backend: input.backend,
+        command: input.command,
+        transcript_path: transcriptPath,
+        summary_path: summaryPath,
+        changed_files: input.changedFiles,
+        acceptance_checks_executed: false,
+        fallback_used: input.task.planner_metadata?.fallback_to_single_call === true,
+        exit_code: input.exitCode,
+        model: input.model,
+        execution_mode: executionMode,
+        failure_class: input.failureClass,
+    };
+    writeJson(join(taskDir, 'agentic_run.json'), artifact);
+}
+export function listChangedFiles(output, toRelativePath) {
+    return output
+        .split('\n')
+        .filter((line) => line.trim().length > 0)
+        .map((line) => line.slice(3).trim())
+        .map((filePath) => toRelativePath(filePath));
+}
+export function resolveAgenticTierSelection(task, config) {
+    const tierSelection = config.defaults.agentic?.tiers?.[task.model_tier];
+    const backend = task.planner_metadata?.agentic_backend ?? tierSelection?.backend ?? config.defaults.agentic?.default_backend;
+    if (!backend) {
+        throw new Error('Agentic execution requested but no agentic backend is configured on planner_metadata, defaults.agentic.tiers, or defaults.agentic.default_backend');
+    }
+    const model = tierSelection?.backend === backend ? tierSelection.model : undefined;
+    return { backend, model };
+}
+/**
+ * Parses JSONL output from an agentic backend (opencode --format json or claude-code --output-format json)
+ * and sums token usage and cost from all step_finish events.
+ *
+ * Returns null if no step_finish events are found (e.g. plain text output).
+ */
+export function parseAgenticUsage(output) {
+    let totalInput = 0;
+    let totalOutput = 0;
+    let totalCost = 0;
+    let steps = 0;
+    for (const line of output.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const event = JSON.parse(trimmed);
+            // opencode step_finish events
+            if (event.type === 'step_finish' && event.part) {
+                totalInput += event.part.tokens?.input ?? 0;
+                totalOutput += event.part.tokens?.output ?? 0;
+                totalCost += event.part.cost ?? 0;
+                steps++;
+            }
+            // Claude Code final result (single JSON object with result.usage)
+            if (event.result?.usage) {
+                totalInput += event.result.usage.input_tokens ?? 0;
+                totalOutput += event.result.usage.output_tokens ?? 0;
+                totalCost += event.result.cost_usd ?? 0;
+                steps++;
+            }
+        }
+        catch {
+            // Skip non-JSON lines
+        }
+    }
+    if (steps === 0)
+        return null;
+    return {
+        input_tokens: totalInput,
+        output_tokens: totalOutput,
+        cost_usd: totalCost,
+        steps,
+    };
+}
+//# sourceMappingURL=agentic-runtime.js.map

package/dist/agentic-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentic-runtime.js","sourceRoot":"","sources":["../src/agentic-runtime.ts"],"names":[],"mappings":"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"}

package/dist/agentic-types.d.ts

@@ -0,0 +1,37 @@
+import type { ModelTier, RiskLevel } from './types.js';
+export declare const AGENTIC_BACKENDS: readonly ["opencode", "claude-code"];
+export type AgenticBackend = (typeof AGENTIC_BACKENDS)[number];
+export interface AgenticFallbackConfig {
+    enabled?: boolean;
+    task_types?: string[];
+    risk_levels?: RiskLevel[];
+}
+export interface AgenticBackendConfig {
+    enabled?: boolean;
+    command?: string[];
+    transcript_format?: 'plain' | 'jsonl';
+}
+export interface AgenticConfig {
+    default_backend?: AgenticBackend;
+    backends?: Partial<Record<AgenticBackend, AgenticBackendConfig>>;
+    tiers?: Partial<Record<ModelTier, {
+        backend: AgenticBackend;
+        model?: string;
+    }>>;
+}
+export interface AgenticBackendResolution {
+    backend: AgenticBackend;
+    available: boolean;
+    command: string;
+    commandSource: 'default' | 'config';
+    configPath: string | null;
+    configPathSource: 'config' | 'default' | 'none';
+    resolvedConfigPath: string | null;
+    configExists: boolean | null;
+    installHint: string;
+    error?: string;
+}
+export interface AgenticRuntimeRequirement {
+    backend: AgenticBackend;
+    context?: string;
+}

package/dist/agentic-types.js

@@ -0,0 +1,2 @@
+export const AGENTIC_BACKENDS = ['opencode', 'claude-code'];
+//# sourceMappingURL=agentic-types.js.map