opencode-hive 1.3.6 → 1.4.3

package/README.md

@@ -24,7 +24,7 @@ npm install opencode-hive
 
 1. Create `.opencode/mcp-servers.json` using the template:
    - From this repo: `packages/opencode-hive/templates/mcp-servers.json`
-   - Or from npm: `node_modules/opencode-hive/templates/mcp-servers.json`
+   - Or from the installed npm package: `node_modules/opencode-hive/templates/mcp-servers.json`
 2. Set `EXA_API_KEY` to enable `websearch_exa` (optional).
 3. Restart OpenCode.
 
@@ -34,7 +34,7 @@ This enables tools like `grep_app_searchGitHub`, `context7_query-docs`, `websear
 
 1. **Create Feature** — `hive_feature_create("dark-mode")`
 2. **Write Plan** — AI generates structured plan
-3. **Review** — You review in VS Code, add comments
+3. **Review** — Optional `vscode-hive` companion for overview/plan review and comments
 4. **Approve** — `hive_plan_approve()`
 5. **Execute** — Tasks run in isolated git worktrees
 6. **Ship** — Clean commits, full audit trail
@@ -43,6 +43,17 @@ This enables tools like `grep_app_searchGitHub`, `context7_query-docs`, `websear
 
 During planning, "don't execute" means "don't implement" (no code edits, no worktrees). Read-only exploration is explicitly allowed and encouraged, both via local tools and by delegating to Scout.
 
+When delegation is warranted, synthesize the task before handing it off: name the file paths or search target, state the expected result, and say what done looks like. Workers do not inherit planner context.
+
+For execution work, treat worker output as evidence to inspect, not proof to trust blindly. OpenCode is the supported execution harness in `1.4.0`; if you use `vscode-hive`, treat it as a review/sidebar companion. Read changed files yourself and run the shared verification commands on the main branch before claiming the batch is complete.
+
+\`hive_network_query\` is an optional lookup, not a default step. There is no startup lookup: first orient on the live request and live repo state. planning, orchestration, and review roles get network access first. live-file verification still required even when network results look relevant.
+
+### Local skill and model use cases
+
+- **Local skill experiments:** keep a skill in `<project>/.opencode/skills/<id>/SKILL.md` or `<project>/.claude/skills/<id>/SKILL.md` and add it to `skills` or `autoLoadSkills` for that repo only.
+- **Local model tuning:** set per-agent models or variants in `<project>/.hive/agent-hive.json` when you want a repository-specific routing setup without changing your global OpenCode defaults.
+
 #### Canonical Delegation Threshold
 
 - Delegate to Scout when you cannot name the file path upfront, expect to inspect 2+ files, or the question is open-ended ("how/where does X work?").
@@ -106,22 +117,40 @@ When using Dynamic Context Pruning (DCP), use a Hive-safe config in `~/.config/o
   - `strategies.supersedeWrites.enabled: false`
   - `strategies.purgeErrors.enabled: false`
 
-For local plugin testing, keep OpenCode plugin entry as `"opencode-hive"` (not `"opencode-hive@latest"`).
+For normal usage, set the OpenCode plugin entry to `"opencode-hive@latest"`. Keep `"opencode-hive"` only for local contributor testing with a symlinked checkout.
+
+#### OpenCode alignment: honest hook contract and bounded recovery
 
-#### Compaction recovery and session re-anchoring
+Agent Hive aligns to the OpenCode surfaces that exist today. It does **not** depend on a first-class upstream Hive orchestration API, a native checkpoint API, or a hidden todo-sync surface.
 
-OpenCode can compact long sessions. When that happens mid-orchestration or mid-task, Hive needs the session to recover its role and task boundaries without re-reading the whole repository.
+At the current plugin/runtime layer, Hive relies on these supported hooks:
 
-The plugin now persists durable session metadata and uses it during `experimental.session.compacting` to rebuild a compact re-anchor prompt.
+- `event`
+- `config`
+- `chat.message`
+- `experimental.chat.messages.transform`
+- `tool.execute.before`
 
-Where:
+That contract matters because some older wording implied deeper integration than OpenCode currently exposes. The recovery path in this branch is hook-timed and file-backed, not storage-level magic.
+
+Todo ownership is intentionally modest:
+
+- OpenCode todos remain **session-scoped** and **replace-all**.
+- Hive does not add a new upstream todo API.
+- This plugin does not expose a derived projected-todo field or stale refresh hints as part of its runtime contract.
+- Worker and subagent sessions still follow normal OpenCode limits; they should not be described as independently syncing Hive task state.
+- `.hive` remains the durable source of truth for plan/task/worktree state.
+
+Compaction recovery uses durable Hive artifacts instead of transcript dumps:
 
 - Global session state is written to `.hive/sessions.json`.
 - Feature-local mirrors are written to `.hive/features/<feature>/sessions.json`.
 - Session classification distinguishes `primary`, `subagent`, `task-worker`, and `unknown`.
-- Primary and subagent recovery can replay the stored user directive once after compaction.
-- Task-worker recovery uses the strict re-anchor plus one bounded worker-specific synthetic replay after compaction.
-- The task-worker replay can reference `.hive/features/<feature>/tasks/<task>/worker-prompt.md`.
+- Primary and subagent recovery can replay the stored user directive once after compaction, with `directiveRecoveryState` enforcing the one-replay-then-escalate contract.
+- Task-worker recovery does **not** replay the whole user directive. Workers re-read `worker-prompt.md` and continue the current task from the existing worktree state.
+- Recovery uses durable session metadata plus `worker-prompt.md` instead of an extra checkpoint artifact, idle child-session replay, or parent-scoped task rehydration.
+
+In practice, the durable task-level recovery surface is the semantic `.hive` artifact set for that task, with `worker-prompt.md` plus bound feature/task/session metadata as the re-entry surface. Hive does **not** persist raw transcript dumps as its recovery contract.
 
 Task-worker recovery is intentionally strict:
 
@@ -135,15 +164,20 @@ Task-worker recovery is intentionally strict:
 - do not use orchestration tools unless the worker prompt explicitly says so
 - continue from the last known point
 
-This split is deliberate: primary and subagent sessions replay the stored user directive once after compaction, while task-workers also receive one worker-specific synthetic replay after compaction that restates the active task identity and worker boundaries.
+This split is deliberate: primary and subagent sessions replay the stored user directive once after compaction, while task workers recover from their own bounded task contract instead of relying on parent-session replay.
 
 Manual tasks follow the same DAG model as plan-backed tasks:
 
 - `hive_task_create()` stores manual tasks with explicit `dependsOn` metadata instead of inferring sequential order.
+- manual tasks are append-only.
+- intermediate insertion requires plan amendment.
+- dependencies on unfinished work require plan amendment.
 - Structured manual-task fields such as `goal`, `description`, `acceptanceCriteria`, `files`, and `references` are turned into worker-facing `spec.md` content.
 - If review feedback changes downstream sequencing or scope, update `plan.md` and run `hive_tasks_sync({ refreshPending: true })` so pending plan tasks pick up the new `dependsOn` graph and regenerated specs.
 
-This recovery path applies to the built-in `forager-worker` and custom agents derived from it, because they are the sessions most likely to be compacted mid-implementation.
+This recovery path applies to the built-in `forager-worker`, the runtime-only `hive-helper` bounded hard-task operational assistant, and custom agents derived from `forager-worker`. `hive-helper` handles merge recovery, state clarification, interrupted-state wrap-up, and safe manual-follow-up assistance while staying inside the current approved DAG boundary. It may summarize observable state, including `helperStatus`, and create safe append-only manual tasks, but it may never update plan-backed task state and must escalate DAG-changing requests for plan amendment. For the issue-72 style "task 3 is locally testable but task 4 has not started" situation, ask Helper to clarify the locally testable state and wrap-up surface first; ask it to create a safe manual follow-up only when the work can append after the current DAG; if you think you need `3b` / `3c` inserted before later plan-backed work, amend `plan.md` instead. `hive-helper` is intentionally OpenCode runtime-only in v1, not a custom base agent, and it does not appear in `.github/agents/` or `packages/vscode-hive/src/generators/`.
+
+`hive-helper` also remains not a network consumer. It benefits indirectly from better upstream planning/orchestration/review decisions, but it does not call `hive_network_query` itself.
 
 ## Prompt Budgeting & Observability
 
@@ -194,7 +228,27 @@ Description.
 
 ## Configuration
 
-Hive uses a config file at `~/.config/opencode/agent_hive.json`. You can customize agent models, variants, disable skills, and disable MCP servers.
+Hive reads config from these locations, in order:
+
+1. `<project>/.hive/agent-hive.json` (preferred)
+2. `<project>/.opencode/agent_hive.json` (legacy fallback, used only when the new file is missing)
+3. `~/.config/opencode/agent_hive.json` (global fallback)
+
+If `.hive/agent-hive.json` exists but is invalid JSON or an invalid shape, Hive warns, skips the legacy project file, and falls back to the global config and defaults.
+
+You can customize agent models, variants, disable skills, and disable MCP servers.
+
+### Project-local config example
+
+Create `.hive/agent-hive.json`:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/tctinh/agent-hive/main/packages/opencode-hive/schema/agent_hive.schema.json",
+  "agentMode": "unified",
+  "disableSkills": []
+}
+```
 
 ### Disable Skills or MCPs
 
@@ -298,6 +352,7 @@ Skill IDs must be safe directory names (no `/`, `\`, `..`, or `.`). Missing or i
 |-------|------------------------|
 | `hive-master` | `parallel-exploration` |
 | `forager-worker` | `test-driven-development`, `verification-before-completion` |
+| `hive-helper` | (none) |
 | `scout-researcher` | (none) |
 | `architect-planner` | `parallel-exploration` |
 | `swarm-orchestrator` | (none) |
@@ -355,6 +410,10 @@ Define plugin-only custom subagents with `customAgents`. Freshly initialized `ag
 - `baseAgent`: one of `forager-worker` or `hygienic-reviewer`
 - `description`: delegation guidance injected into primary planner/orchestrator prompts
 
+`hive-helper` is not a custom base agent. In v1 it stays runtime-only for isolated merge recovery and does not appear in `.github/agents/` and does not appear in `packages/vscode-hive/src/generators/`.
+
+It is also not a network consumer; planning, orchestration, and review roles get network access first.
+
 Published example (validated by `src/e2e/custom-agent-docs-example.test.ts`):
 
 ```json
@@ -422,7 +481,7 @@ Override models for specific agents:
 
 ## Pair with VS Code
 
-For the full experience, install [vscode-hive](https://marketplace.visualstudio.com/items?itemName=tctinh.vscode-hive) to review plans inline with comments.
+For the full OpenCode-first workflow, install [vscode-hive](https://marketplace.visualstudio.com/items?itemName=tctinh.vscode-hive) as an optional review/sidebar companion for inline comments and approvals.
 
 ## License
 

package/dist/hive-core/src/services/configService.d.ts

@@ -1,18 +1,23 @@
 import type { AgentModelConfig, HiveConfig, ResolvedCustomAgentConfig } from '../types.js';
 import type { SandboxConfig } from './dockerSandboxService.js';
 /**
- * ConfigService manages user config at ~/.config/opencode/agent_hive.json
+ * ConfigService manages Agent Hive config with read precedence:
+ * 1. <project>/.hive/agent-hive.json (preferred when present and valid)
+ * 2. <project>/.opencode/agent_hive.json (legacy fallback during migration)
+ * 3. ~/.config/opencode/agent_hive.json (fallback)
  *
- * This is USER config (not project-scoped):
- * - VSCode extension reads/writes this
- * - OpenCode plugin reads this to enable features
- * - Agent does NOT have tools to access this
+ * Writes remain global-only at ~/.config/opencode/agent_hive.json.
  */
 export declare class ConfigService {
     private configPath;
+    private projectConfigPath?;
+    private legacyProjectConfigPath?;
     private cachedConfig;
     private cachedCustomAgentConfigs;
-    constructor();
+    private activeReadSourceType;
+    private activeReadPath;
+    private lastFallbackWarning;
+    constructor(projectRoot?: string);
     /**
      * Get config path
      */
@@ -21,6 +26,16 @@ export declare class ConfigService {
      * Get the full config, merged with defaults.
      */
     get(): HiveConfig;
+    getActiveReadSourceType(): 'project' | 'global';
+    getActiveReadPath(): string;
+    getLastFallbackWarning(): {
+        message: string;
+        sourceType: 'project' | 'global';
+        sourcePath: string;
+        fallbackType: 'global' | 'defaults';
+        fallbackPath?: string;
+        reason: 'parse_error' | 'validation_error' | 'read_error';
+    } | null;
     /**
      * Update config (partial merge).
      */
@@ -75,4 +90,11 @@ export declare class ConfigService {
     getHookCadence(hookName: string, options?: {
         safetyCritical?: boolean;
     }): number;
+    private readStoredConfig;
+    private mergeWithDefaults;
+    private createProjectFallbackWarning;
+    private isValidStoredConfig;
+    private isStringArray;
+    private isValidAgentConfigDeclaration;
+    private isHookCadenceRecord;
 }

package/dist/hive-core/src/services/contextService.d.ts

@@ -1,5 +1,5 @@
-import type { ContextFile } from '../types.js';
-export type { ContextFile };
+import type { ContextFile, ContextRole } from '../types.js';
+export type { ContextFile, ContextRole };
 export declare const RESERVED_OVERVIEW_CONTEXT = "overview";
 export declare class ContextService {
     private projectRoot;
@@ -9,6 +9,8 @@ export declare class ContextService {
     list(featureName: string): ContextFile[];
     getOverview(featureName: string): ContextFile | null;
     listExecutionContext(featureName: string): ContextFile[];
+    listAgentsMdSyncContext(featureName: string): ContextFile[];
+    listNetworkContext(featureName: string): ContextFile[];
     delete(featureName: string, fileName: string): boolean;
     compile(featureName: string): string;
     archive(featureName: string): {
@@ -22,4 +24,5 @@ export declare class ContextService {
         newest?: string;
     };
     private normalizeFileName;
+    private classifyContextName;
 }

package/dist/hive-core/src/services/index.d.ts

@@ -6,6 +6,7 @@ export { SubtaskService } from './subtaskService.js';
 export { WorktreeService, createWorktreeService } from './worktreeService.js';
 export type { WorktreeInfo, DiffResult, ApplyResult, CommitResult, MergeResult, WorktreeConfig } from './worktreeService.js';
 export { ContextService } from './contextService.js';
+export { NetworkService } from './networkService.js';
 export { ReviewService } from './reviewService.js';
 export { SessionService } from './sessionService.js';
 export { ConfigService } from './configService.js';

package/dist/hive-core/src/services/networkService.d.ts

@@ -0,0 +1,25 @@
+export interface NetworkQueryOptions {
+    currentFeature?: string;
+    query: string;
+    maxFeatures: number;
+    maxSnippetsPerFeature: number;
+    maxSnippetChars: number;
+}
+export interface NetworkQueryResult {
+    feature: string;
+    sourceType: 'plan' | 'context';
+    sourceName: string;
+    path: string;
+    updatedAt: string;
+    snippet: string;
+}
+export declare class NetworkService {
+    private readonly projectRoot;
+    private readonly contextService;
+    constructor(projectRoot: string);
+    query(options: NetworkQueryOptions): NetworkQueryResult[];
+    private collectMatches;
+    private matchPlan;
+    private matchContext;
+    private resolveDirectoryName;
+}

package/dist/hive-core/src/services/taskService.d.ts

@@ -113,6 +113,7 @@ export declare class TaskService {
     private listFolders;
     private deleteTask;
     private getNextOrder;
+    private validateManualTaskDependsOn;
     private parseTasksFromPlan;
     createSubtask(featureName: string, taskFolder: string, name: string, type?: SubtaskType): Subtask;
     updateSubtask(featureName: string, taskFolder: string, subtaskId: string, status: TaskStatusType): Subtask;

package/dist/hive-core/src/services/worktreeService.d.ts

@@ -22,12 +22,23 @@ export interface CommitResult {
     sha: string;
     message?: string;
 }
+export interface MergeOptions {
+    preserveConflicts?: boolean;
+    cleanup?: 'none' | 'worktree' | 'worktree+branch';
+}
 export interface MergeResult {
     success: boolean;
     merged: boolean;
+    strategy: 'merge' | 'squash' | 'rebase';
     sha?: string;
-    filesChanged?: string[];
-    conflicts?: string[];
+    filesChanged: string[];
+    conflicts: string[];
+    conflictState: 'none' | 'aborted' | 'preserved';
+    cleanup: {
+        worktreeRemoved: boolean;
+        branchDeleted: boolean;
+        pruned: boolean;
+    };
     error?: string;
 }
 export interface WorktreeConfig {
@@ -50,7 +61,11 @@ export declare class WorktreeService {
     revertDiff(feature: string, step: string, baseBranch?: string): Promise<ApplyResult>;
     private parseFilesFromDiff;
     revertFromSavedDiff(diffPath: string): Promise<ApplyResult>;
-    remove(feature: string, step: string, deleteBranch?: boolean): Promise<void>;
+    remove(feature: string, step: string, deleteBranch?: boolean): Promise<{
+        worktreeRemoved: boolean;
+        branchDeleted: boolean;
+        pruned: boolean;
+    }>;
     list(feature?: string): Promise<WorktreeInfo[]>;
     cleanup(feature?: string): Promise<{
         removed: string[];
@@ -59,8 +74,9 @@ export declare class WorktreeService {
     checkConflicts(feature: string, step: string, baseBranch?: string): Promise<string[]>;
     checkConflictsFromSavedDiff(diffPath: string, reverse?: boolean): Promise<string[]>;
     commitChanges(feature: string, step: string, message?: string): Promise<CommitResult>;
-    merge(feature: string, step: string, strategy?: "merge" | "squash" | "rebase", message?: string): Promise<MergeResult>;
+    merge(feature: string, step: string, strategy?: "merge" | "squash" | "rebase", message?: string, options?: MergeOptions): Promise<MergeResult>;
     hasUncommittedChanges(feature: string, step: string): Promise<boolean>;
     private parseConflictsFromError;
+    private getActiveConflictFiles;
 }
 export declare function createWorktreeService(projectDir: string): WorktreeService;

package/dist/hive-core/src/types.d.ts

@@ -127,12 +127,18 @@ export interface FeatureInfo {
     commentCount: number;
     reviewCounts: ReviewCounts;
 }
+export type ContextRole = 'human' | 'scratchpad' | 'operational' | 'durable';
 export interface ContextFile {
     name: string;
     content: string;
     updatedAt: string;
+    role: ContextRole;
+    includeInExecution: boolean;
+    includeInAgentsMdSync: boolean;
+    includeInNetwork: boolean;
 }
 export type SessionKind = 'primary' | 'subagent' | 'task-worker' | 'unknown';
+export type DirectiveRecoveryState = 'available' | 'consumed' | 'escalated';
 export interface SessionInfo {
     sessionId: string;
     featureName?: string;
@@ -142,6 +148,7 @@ export interface SessionInfo {
     sessionKind?: SessionKind;
     workerPromptPath?: string;
     directivePrompt?: string;
+    directiveRecoveryState?: DirectiveRecoveryState;
     replayDirectivePending?: boolean;
     startedAt: string;
     lastActiveAt: string;
@@ -174,11 +181,11 @@ export interface AgentModelConfig {
     /** Variant key for model reasoning/effort level (e.g., 'low', 'medium', 'high', 'max') */
     variant?: string;
 }
-export declare const BUILT_IN_AGENT_NAMES: readonly ["hive-master", "architect-planner", "swarm-orchestrator", "scout-researcher", "forager-worker", "hygienic-reviewer"];
+export declare const BUILT_IN_AGENT_NAMES: readonly ["hive-master", "architect-planner", "swarm-orchestrator", "scout-researcher", "forager-worker", "hive-helper", "hygienic-reviewer"];
 export type BuiltInAgentName = (typeof BUILT_IN_AGENT_NAMES)[number];
 export declare const CUSTOM_AGENT_BASES: readonly ["forager-worker", "hygienic-reviewer"];
 export type CustomAgentBase = (typeof CUSTOM_AGENT_BASES)[number];
-export declare const CUSTOM_AGENT_RESERVED_NAMES: readonly ["hive-master", "architect-planner", "swarm-orchestrator", "scout-researcher", "forager-worker", "hygienic-reviewer", "hive", "architect", "swarm", "scout", "forager", "hygienic", "receiver", "build", "plan", "code"];
+export declare const CUSTOM_AGENT_RESERVED_NAMES: readonly ["hive-master", "architect-planner", "swarm-orchestrator", "scout-researcher", "forager-worker", "hive-helper", "hygienic-reviewer", "hive", "architect", "swarm", "scout", "forager", "hygienic", "receiver", "build", "plan", "code"];
 export interface CustomAgentConfig {
     baseAgent: CustomAgentBase;
     description: string;
@@ -216,6 +223,8 @@ export interface HiveConfig {
         'scout-researcher'?: AgentModelConfig;
         /** Forager Worker */
         'forager-worker'?: AgentModelConfig;
+        /** Hive Helper */
+        'hive-helper'?: AgentModelConfig;
         /** Hygienic Reviewer */
         'hygienic-reviewer'?: AgentModelConfig;
     };
@@ -236,6 +245,7 @@ export declare const DEFAULT_AGENT_MODELS: {
     readonly 'swarm-orchestrator': "github-copilot/claude-opus-4.5";
     readonly 'scout-researcher': "zai-coding-plan/glm-4.7";
     readonly 'forager-worker': "github-copilot/gpt-5.2-codex";
+    readonly 'hive-helper': "github-copilot/gpt-5.2-codex";
     readonly 'hygienic-reviewer': "github-copilot/gpt-5.2-codex";
 };
 export declare const DEFAULT_HIVE_CONFIG: HiveConfig;