grok-wr1now 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wr1now
+
+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,223 @@
+# grok-cli
+
+Agentic AI coding CLI powered by xAI/Grok — orchestration, memory, tools, and autonomous execution.
+
+## Quick Start
+
+**Prerequisites:** Node.js 20+, git
+
+```bash
+git clone https://github.com/wr1now/grok-cli.git
+cd grok-cli
+bash setup.sh
+```
+
+The setup script installs dependencies, builds, runs tests, and tells you next steps.
+
+```bash
+export XAI_API_KEY="your-key-here"  # get a key at https://console.x.ai
+
+# Interactive REPL (recommended)
+./grok -i
+
+# Direct execution
+./grok "explain this codebase"
+
+# Full pipeline (preflight → oversight → execution)
+./grok run "build a REST API"
+
+# Autonomous mode
+./grok run "refactor the auth module" --mode autonomous
+```
+
+## Global Install (optional)
+
+```bash
+npm link
+grok "your goal here"
+grok -i
+grok run "goal" --mode auto
+```
+
+## Execution Modes
+
+| Mode | Flag | Preflight | Oversight | Tools | Interaction |
+|---|---|---|---|---|---|
+| **Normal** | `--mode normal` | interactive | full | approval required | interactive |
+| **Fast** | `--mode fast` | skip | skip | safe auto-approved | minimal |
+| **Plan** | `--mode plan` | full | full | no execution | review only |
+| **Autonomous** | `--mode auto` | auto-answer | auto-proceed | non-destructive auto | result only |
+
+## Commands
+
+```bash
+# Execution
+grok "goal"                         # Direct execution
+grok run "goal"                     # Preflight → Oversight → Execute
+grok ask "question"                 # Quick answer, no tools
+grok architect "goal"               # Two-phase reasoning pipeline
+grok autopilot "goal"               # Agree on plan, execute uninterrupted
+
+# AI-Powered
+grok explain <file>[:<lines>]       # AI code explanation
+grok refactor <file>                # AI refactoring suggestions
+grok diff                           # AI diff summary + commit suggestion
+grok commit                         # AI-generated commit message
+grok pr                             # AI-generated PR description
+
+# Project
+grok init                           # Create .grok/ directory
+grok config                         # View/edit project config
+grok dashboard                      # Architecture + progress overview
+grok scan                           # Project structure analysis
+grok workspace                      # Multi-project workspace
+
+# Development
+grok test                           # Run tests
+grok lint                           # Typecheck
+grok deps                           # Dependency analysis
+grok git                            # Git summary
+grok security                       # Secret/env scanning
+grok search "query"                 # Full-text code search
+grok todo                           # Find TODOs in codebase
+grok benchmark [N]                  # Provider latency benchmark
+
+# Operations
+grok health                         # Provider + system health
+grok stats                          # Telemetry dashboard
+grok doctor                         # Comprehensive diagnostic
+grok eval                           # Execution metrics analysis
+grok history                        # Execution timeline
+grok export <target>                # Export data (report/decisions/memory/config)
+grok clean                          # Remove stale .grok/ data
+grok env                            # Full environment info
+grok migrate                        # Version migration check
+grok plugin                         # Plugin management
+grok trajectory                     # Competitor analysis
+grok autoresearch start             # Karpathy optimization loop
+grok daemon start                   # Background file watcher
+grok schedule list                  # Manage scheduled jobs
+grok version                        # Version info
+
+# Interactive
+grok -i                             # REPL with session presets, slash commands, streaming
+grok --resume-session-id <id> "goal" # Resume a persisted batch/stream session
+grok --help                         # Show all commands and flags
+```
+
+## Architecture
+
+```
+User Goal
+    │
+    ▼
+┌──────────────────────────────────────┐
+│  PREFLIGHT                           │
+│  Clarify → Competitive Analysis →    │
+│  Enhanced Strategy                   │
+└──────────────────────────────────────┘
+    │
+    ▼
+┌──────────────────────────────────────┐
+│  OVERSIGHT (metacognition)           │
+│  Coherence → Blind Spots → Reframe  │
+│  Verdict: proceed / adjust / abort   │
+└──────────────────────────────────────┘
+    │
+    ▼
+┌──────────────────────────────────────┐
+│  EXECUTION                           │
+│  Route → Plan → Tool Loop → Evaluate│
+└──────────────────────────────────────┘
+    │
+    ▼
+  Memory + Decision Log + Telemetry
+```
+
+## Built-in Tools
+
+| Tool | Tier | Description |
+|---|---|---|
+| `echo_text` | safe_read | Echo text back |
+| `read_file` | safe_read | Read file contents (byte-limited) |
+| `write_file` | safe_write | Write or append to file |
+| `edit_file` | safe_write | Search-and-replace editing |
+| `list_directory` | safe_read | List directory contents |
+| `run_command` | shell | Shell command execution |
+| `git_status` | safe_read | Git status |
+| `git_diff` | safe_read | Git diff |
+| `git_log` | safe_read | Git log |
+| `git_commit` | safe_write | Stage and commit |
+| `git_checkout` | safe_write | Branch switching |
+| `repo_map` | safe_read | Project structure map |
+| `grep_search` | safe_read | Regex content search |
+| `glob_find` | safe_read | File pattern matching |
+| `web_fetch` | network | HTTP client (SSRF-protected) |
+| `http_request` | network | Full HTTP requests (SSRF-protected) |
+| `web_search` | network | Web search |
+| `env_inspector` | safe_read | Environment variables (secrets redacted) |
+| `test_runner` | shell | Run test suites |
+| `lint_check` | shell | Run linters |
+
+See `grok health` for the full list of registered tools.
+
+## `.grok/` Directory
+
+```
+.grok/
+├── config/          # project.json, providers.json
+├── sessions/        # Session state
+├── conversations/   # Multi-turn history
+├── memory/          # Scoped records (session/project/semantic)
+├── policies/        # Policy bundles
+├── decision-logs/   # Audit trail
+├── oversight/       # Preflight + oversight results
+└── tools/           # Project tool definitions (.json)
+```
+
+Project-scoped durability is automatic when `projectRoot` is available:
+
+- Memory uses the built-in SQLite-backed store when supported, with JSON fallback otherwise
+- Decision logs persist to `.grok/decision-logs/`
+- `grok history`, `grok eval`, and `grok export` read persisted artifacts directly and do not require API auth
+- `--resume-session-id` restores both session metadata and persisted conversation context
+- REPL `/save`, normal exit, and `Ctrl+C` suspension all persist session state and conversation history
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `XAI_API_KEY` | xAI/Grok API key (primary) |
+| `XAI_OAUTH_BEARER` | OAuth bearer (alternative) |
+| `XAI_MODEL` | Override default model (e.g. `grok-3-mini`) |
+| `ANTHROPIC_API_KEY` | Anthropic adapter (optional) |
+| `OPENAI_API_KEY` | OpenAI adapter (optional) |
+
+## Development
+
+```bash
+npm run build       # Compile TypeScript
+npm run typecheck   # Type check only
+npm run test        # Build + run all tests
+npm run clean       # Remove dist/
+```
+
+## Experimental Features
+
+These are functional but not yet production-hardened:
+
+- `grok pilot-pro "goal"` — Full autonomous mega-loop (intel → strategy → build → validate)
+- `grok mcp start` — Expose tools via MCP server
+- Pilot Pro preset in REPL (`/preset pilot_pro`)
+
+## Security
+
+- All tool execution goes through an approval gate with configurable risk tiers
+- Destructive operations always require explicit user approval
+- Network tools block localhost, RFC 1918, link-local, and cloud metadata endpoints (SSRF protection)
+- Environment inspector redacts secrets by default
+- Dangerous execution modes require typing "yes" to confirm
+
+## License
+
+MIT

package/dist/accuracy/hallucination-reducer.d.ts

@@ -0,0 +1,28 @@
+import type { JsonObject } from "../model/contracts/common.js";
+import type { MetaAgentResponse } from "../autopilot-pro/meta-agent.js";
+export declare class HallucinationReducer {
+    private readonly accuracyThreshold;
+    /**
+     * Validates a MetaAgent response for hallucinations by scoring trace metrics and cross-referencing with competitive data.
+     * @param response The response from MetaAgent to validate.
+     * @param context Additional context for validation (e.g., query details).
+     * @returns True if the response is deemed factual and low-hallucination, false otherwise.
+     */
+    validateResponse(response: MetaAgentResponse, context: JsonObject): Promise<boolean>;
+    /**
+     * Cross-references the response content with competitor data to ensure factual consistency.
+     * @param response The MetaAgent response.
+     * @param competitors Analyzed competitor data.
+     * @param recommendations Competitive recommendations.
+     * @returns True if the response is consistent with facts.
+     */
+    private crossReferenceFactualAccuracy;
+    /**
+     * Checks if a specific claim is factual based on competitor data.
+     * @param claim The claim to verify.
+     * @param competitors Competitor analysis data.
+     * @param recommendations Recommendations list.
+     * @returns True if the claim is supported by data.
+     */
+    private isClaimFactual;
+}

package/dist/accuracy/hallucination-reducer.js

@@ -0,0 +1,59 @@
+import { getCompetitiveRecommendations, analyzeCompetitors, } from "../autoresearch/competitors.js";
+import { scoreTraceMetrics } from "../trace/trace-metrics.js"; // Assuming scoreTraceMetrics is defined elsewhere
+// ---------------------------------------------------------------------------
+// Hallucination Reducer — reduces hallucinations by validating MetaAgent responses
+// ---------------------------------------------------------------------------
+export class HallucinationReducer {
+    accuracyThreshold = 0.8; // Configurable threshold for factual accuracy
+    /**
+     * Validates a MetaAgent response for hallucinations by scoring trace metrics and cross-referencing with competitive data.
+     * @param response The response from MetaAgent to validate.
+     * @param context Additional context for validation (e.g., query details).
+     * @returns True if the response is deemed factual and low-hallucination, false otherwise.
+     */
+    async validateResponse(response, context) {
+        // Step 1: Score the trace metrics for reliability
+        const traceScore = await scoreTraceMetrics(response.trace);
+        if (traceScore < this.accuracyThreshold) {
+            return false; // Response is likely hallucinated based on trace
+        }
+        // Step 2: Cross-reference with competitor analysis for factual accuracy
+        const competitors = await analyzeCompetitors(context);
+        const recommendations = getCompetitiveRecommendations(context);
+        // Check if the response aligns with known competitive facts
+        return this.crossReferenceFactualAccuracy(response, competitors, recommendations);
+    }
+    /**
+     * Cross-references the response content with competitor data to ensure factual consistency.
+     * @param response The MetaAgent response.
+     * @param competitors Analyzed competitor data.
+     * @param recommendations Competitive recommendations.
+     * @returns True if the response is consistent with facts.
+     */
+    crossReferenceFactualAccuracy(response, competitors, // Assuming competitors is an array of competitor objects
+    recommendations) {
+        // Extract key facts or claims from the response (simplified: assume response has a 'claims' array)
+        const claims = response.claims || [];
+        // Verify each claim against competitors and recommendations
+        for (const claim of claims) {
+            if (!this.isClaimFactual(claim, competitors, recommendations)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Checks if a specific claim is factual based on competitor data.
+     * @param claim The claim to verify.
+     * @param competitors Competitor analysis data.
+     * @param recommendations Recommendations list.
+     * @returns True if the claim is supported by data.
+     */
+    isClaimFactual(claim, competitors, recommendations) {
+        // Simplified logic: Check if claim matches any competitor feature or recommendation
+        // In a real implementation, this could use NLP or keyword matching
+        const lowerClaim = claim.toLowerCase();
+        return (competitors.some(comp => comp.features.some((feat) => feat.toLowerCase().includes(lowerClaim))) ||
+            recommendations.some(rec => rec.toLowerCase().includes(lowerClaim)));
+    }
+}

package/dist/agents/dispatcher.d.ts

@@ -0,0 +1,70 @@
+import type { Identifier, ISO8601Timestamp, JsonObject, Result, StructuredError } from "../model/contracts/common.js";
+import type { WorkerBudget, WorkerClass, WorkerContract, WorkerResult, WorkerRole } from "../model/contracts/worker.js";
+import type { DelegationPolicy } from "../model/contracts/policy.js";
+import type { SemanticContextPack } from "../model/contracts/memory.js";
+export type DispatchErrorCode = "worker_class_not_enabled" | "parallel_limit_exceeded" | "budget_exceeded" | "invalid_worker_contract" | "worker_execution_failed" | "worker_timeout" | "human_approval_required" | "context_pack_missing";
+export interface DispatchError extends StructuredError {
+    readonly subsystem: "subagent-runtime";
+    readonly code: DispatchErrorCode;
+    readonly workerClass?: WorkerClass;
+    readonly actorId?: Identifier;
+}
+export type DispatchEventKind = "dispatch_requested" | "dispatch_approved" | "dispatch_denied" | "worker_started" | "worker_completed" | "worker_failed" | "worker_timeout" | "parallel_limit_checked";
+export interface DispatchEvent {
+    readonly kind: DispatchEventKind;
+    readonly timestamp: ISO8601Timestamp;
+    readonly actorId?: Identifier;
+    readonly workerClass?: WorkerClass;
+    readonly detail: JsonObject;
+}
+export interface DispatchEventSink {
+    emit(event: DispatchEvent): void;
+}
+/**
+ * Each worker type (focused subagent, mirrored terminal) provides a runtime.
+ * The dispatcher calls this after policy validation passes.
+ * Worker runtimes are responsible for their own execution lifecycle,
+ * including model calls and tool usage within their budget.
+ */
+export interface WorkerRuntime {
+    execute(contract: WorkerContract): Promise<WorkerResult>;
+}
+export interface WorkerApprovalRequest {
+    readonly actorId: Identifier;
+    readonly workerClass: WorkerClass;
+    readonly role: WorkerRole;
+    readonly objective: string;
+    readonly budget: WorkerBudget;
+}
+export interface WorkerApprovalResponse {
+    readonly actorId: Identifier;
+    readonly approved: boolean;
+    readonly decidedBy: Identifier;
+    readonly decidedAt: ISO8601Timestamp;
+    readonly rationale?: string;
+}
+export interface WorkerApprovalGate {
+    requestApproval(request: WorkerApprovalRequest): Promise<WorkerApprovalResponse>;
+}
+export interface SubagentDispatcher {
+    dispatch(contract: WorkerContract, policy: DelegationPolicy, contextPack?: SemanticContextPack): Promise<Result<WorkerResult, DispatchError>>;
+    activeWorkerCount(workerClass?: WorkerClass): number;
+}
+export declare class DefaultSubagentDispatcher implements SubagentDispatcher {
+    private readonly runtimes;
+    private readonly activeWorkers;
+    private readonly approvalGate;
+    private readonly sink;
+    constructor(approvalGate: WorkerApprovalGate, sink?: DispatchEventSink);
+    /**
+     * Register a runtime for a worker class.
+     * V1 typically registers only focused_subagent.
+     */
+    registerRuntime(workerClass: WorkerClass, runtime: WorkerRuntime): void;
+    dispatch(contract: WorkerContract, policy: DelegationPolicy, contextPack?: SemanticContextPack): Promise<Result<WorkerResult, DispatchError>>;
+    activeWorkerCount(workerClass?: WorkerClass): number;
+    private checkParallelLimits;
+    private requestHumanApproval;
+    private executeWithTimeout;
+    private buildError;
+}

package/dist/agents/dispatcher.js

@@ -0,0 +1,212 @@
+import { Ok, Err } from "../model/contracts/common.js";
+const NOOP_DISPATCH_SINK = { emit: () => { } };
+export class DefaultSubagentDispatcher {
+    runtimes = new Map();
+    activeWorkers = new Map();
+    approvalGate;
+    sink;
+    constructor(approvalGate, sink) {
+        this.approvalGate = approvalGate;
+        this.sink = sink ?? NOOP_DISPATCH_SINK;
+    }
+    /**
+     * Register a runtime for a worker class.
+     * V1 typically registers only focused_subagent.
+     */
+    registerRuntime(workerClass, runtime) {
+        this.runtimes.set(workerClass, runtime);
+    }
+    async dispatch(contract, policy, contextPack) {
+        const now = new Date().toISOString();
+        this.sink.emit({
+            kind: "dispatch_requested",
+            timestamp: now,
+            actorId: contract.actorId,
+            workerClass: contract.workerClass,
+            detail: {
+                role: contract.role,
+                objective: contract.objective,
+                hasContextPack: !!contextPack,
+            },
+        });
+        // 1. Validate worker contract.
+        if (!contract.actorId || !contract.objective) {
+            return Err(this.buildError("invalid_worker_contract", "Worker contract missing required fields (actorId or objective)", now, contract.workerClass, contract.actorId));
+        }
+        // 2. Worker class enabled check (Law 10).
+        if (!policy.enabledWorkerClasses.includes(contract.workerClass)) {
+            this.sink.emit({
+                kind: "dispatch_denied",
+                timestamp: now,
+                actorId: contract.actorId,
+                workerClass: contract.workerClass,
+                detail: {
+                    reason: "worker_class_not_enabled",
+                    enabledClasses: policy.enabledWorkerClasses,
+                },
+            });
+            return Err(this.buildError("worker_class_not_enabled", `Worker class '${contract.workerClass}' is not enabled in delegation policy`, now, contract.workerClass, contract.actorId));
+        }
+        // 3. Parallel limit check.
+        const parallelCheck = this.checkParallelLimits(contract.workerClass, policy, now);
+        if (!parallelCheck.ok)
+            return parallelCheck;
+        // 4. Context pack required for focused subagents (Law 10: only necessary context).
+        if (contract.workerClass === "focused_subagent" && !contextPack) {
+            return Err(this.buildError("context_pack_missing", "Focused subagents require a semantic context pack (Law 10: Delegation Discipline)", now, contract.workerClass, contract.actorId));
+        }
+        // 5. Human approval for mirrored workers (Law 20).
+        if (contract.workerClass === "mirrored_terminal_worker" &&
+            policy.requireHumanApprovalForMirroredWorkers) {
+            const approvalResult = await this.requestHumanApproval(contract, now);
+            if (!approvalResult.ok)
+                return approvalResult;
+        }
+        // 6. Resolve runtime.
+        const runtime = this.runtimes.get(contract.workerClass);
+        if (!runtime) {
+            return Err(this.buildError("invalid_worker_contract", `No runtime registered for worker class '${contract.workerClass}'`, now, contract.workerClass, contract.actorId));
+        }
+        // 7. Inject context pack into worker memory profile if provided.
+        const enrichedContract = contextPack
+            ? {
+                ...contract,
+                memoryProfile: {
+                    ...contract.memoryProfile,
+                    contextPack,
+                },
+            }
+            : contract;
+        // 8. Execute.
+        this.activeWorkers.set(contract.actorId, contract.workerClass);
+        this.sink.emit({
+            kind: "worker_started",
+            timestamp: new Date().toISOString(),
+            actorId: contract.actorId,
+            workerClass: contract.workerClass,
+            detail: {
+                role: contract.role,
+                budgetMaxTokens: contract.budget.maxTokens ?? null,
+                budgetMaxToolCalls: contract.budget.maxToolCalls ?? null,
+                budgetMaxRuntimeMs: contract.budget.maxRuntimeMs ?? null,
+            },
+        });
+        try {
+            const result = await this.executeWithTimeout(runtime, enrichedContract);
+            this.activeWorkers.delete(contract.actorId);
+            const eventKind = result.ok ? "worker_completed" : "worker_failed";
+            this.sink.emit({
+                kind: eventKind,
+                timestamp: new Date().toISOString(),
+                actorId: contract.actorId,
+                workerClass: contract.workerClass,
+                detail: {
+                    ok: result.ok,
+                    summary: result.summary,
+                    producedArtifacts: (result.producedArtifacts?.length ?? 0),
+                    escalatedMemoryWrites: (result.escalatedMemoryWrites?.length ?? 0),
+                    openQuestions: (result.openQuestions?.length ?? 0),
+                },
+            });
+            return Ok(result);
+        }
+        catch (err) {
+            this.activeWorkers.delete(contract.actorId);
+            const message = err instanceof Error ? err.message : String(err);
+            this.sink.emit({
+                kind: "worker_failed",
+                timestamp: new Date().toISOString(),
+                actorId: contract.actorId,
+                workerClass: contract.workerClass,
+                detail: { error: message },
+            });
+            return Err(this.buildError("worker_execution_failed", `Worker '${contract.actorId}' failed: ${message}`, new Date().toISOString(), contract.workerClass, contract.actorId));
+        }
+    }
+    activeWorkerCount(workerClass) {
+        if (workerClass === undefined)
+            return this.activeWorkers.size;
+        let count = 0;
+        for (const wc of this.activeWorkers.values()) {
+            if (wc === workerClass)
+                count++;
+        }
+        return count;
+    }
+    // ---- private ----
+    checkParallelLimits(workerClass, policy, now) {
+        this.sink.emit({
+            kind: "parallel_limit_checked",
+            timestamp: now,
+            workerClass,
+            detail: {
+                currentActive: this.activeWorkerCount(workerClass),
+            },
+        });
+        if (workerClass === "focused_subagent") {
+            const limit = policy.maxParallelFocusedSubagents;
+            if (limit !== undefined && this.activeWorkerCount("focused_subagent") >= limit) {
+                return Err(this.buildError("parallel_limit_exceeded", `Focused subagent parallel limit (${limit}) reached`, now, workerClass));
+            }
+        }
+        if (workerClass === "mirrored_terminal_worker") {
+            const limit = policy.maxParallelMirroredWorkers;
+            if (limit !== undefined && this.activeWorkerCount("mirrored_terminal_worker") >= limit) {
+                return Err(this.buildError("parallel_limit_exceeded", `Mirrored worker parallel limit (${limit}) reached`, now, workerClass));
+            }
+        }
+        return Ok(undefined);
+    }
+    async requestHumanApproval(contract, now) {
+        const response = await this.approvalGate.requestApproval({
+            actorId: contract.actorId,
+            workerClass: contract.workerClass,
+            role: contract.role,
+            objective: contract.objective,
+            budget: contract.budget,
+        });
+        if (!response.approved) {
+            this.sink.emit({
+                kind: "dispatch_denied",
+                timestamp: response.decidedAt,
+                actorId: contract.actorId,
+                workerClass: contract.workerClass,
+                detail: {
+                    reason: "human_approval_denied",
+                    decidedBy: response.decidedBy,
+                    rationale: response.rationale ?? null,
+                },
+            });
+            return Err(this.buildError("human_approval_required", `Mirrored worker dispatch denied by ${response.decidedBy}`, response.decidedAt, contract.workerClass, contract.actorId));
+        }
+        this.sink.emit({
+            kind: "dispatch_approved",
+            timestamp: response.decidedAt,
+            actorId: contract.actorId,
+            workerClass: contract.workerClass,
+            detail: { decidedBy: response.decidedBy },
+        });
+        return Ok(undefined);
+    }
+    async executeWithTimeout(runtime, contract) {
+        const timeoutMs = contract.budget.maxRuntimeMs ?? 120_000;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`Worker execution timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            runtime
+                .execute(contract)
+                .then((result) => {
+                clearTimeout(timer);
+                resolve(result);
+            })
+                .catch((err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+    }
+    buildError(code, message, timestamp, workerClass, actorId) {
+        return { code, message, subsystem: "subagent-runtime", timestamp, workerClass, actorId };
+    }
+}

package/dist/agents/focused-subagent.d.ts

@@ -0,0 +1,19 @@
+import type { WorkerContract, WorkerResult } from "../model/contracts/worker.js";
+import type { WorkerRuntime } from "./dispatcher.js";
+/**
+ * Delegate that provides actual LLM execution capability.
+ * When set, the subagent calls the LLM with its objective and context pack.
+ * When absent, the subagent returns a "prepared" result (plan-only mode).
+ */
+export interface FocusedSubagentDelegate {
+    executeGoal(objective: string, contextSummary: string, actorId: string): Promise<{
+        ok: boolean;
+        content: string;
+        latencyMs: number;
+    }>;
+}
+export declare class FocusedSubagentRuntime implements WorkerRuntime {
+    private readonly delegate?;
+    constructor(delegate?: FocusedSubagentDelegate);
+    execute(contract: WorkerContract): Promise<WorkerResult>;
+}