@doingdev/opencode-claude-manager-plugin 0.1.0 → 0.1.5

package/README.md

@@ -56,6 +56,16 @@ If you are testing locally, point OpenCode at the local package or plugin file u
 - `claude_manager_runs` - inspect persisted manager run records
 - `claude_manager_cleanup_run` - explicitly remove worktrees created for a prior manager run
 
+## Plugin-provided agents and commands
+
+When the plugin loads successfully, it also injects config entries through the OpenCode plugin `config` hook.
+
+- Primary agent: `claude-manager`
+- Subagent: `claude-manager-research`
+- Commands: `/claude-metadata`, `/claude-run`, `/claude-sessions`
+
+These are added to OpenCode config at runtime by the plugin, so they do not require separate manual `opencode.json` entries.
+
 ## Quick Start
 
 Typical flow inside OpenCode:
@@ -88,6 +98,24 @@ The compiled plugin output is written to `dist/`.
 
 This package is configured for the npm scope `@doingdev`.
 
+This repository uses npm trusted publishing with GitHub Actions OIDC, so you do not need an `NPM_TOKEN` secret once npm is configured correctly.
+
+Before the first automated publish, configure npm trusted publishing for `@doingdev/opencode-claude-manager-plugin` on npmjs.com:
+
+1. Open the package settings on npmjs.com.
+2. Go to the `Trusted Publisher` section.
+3. Choose `GitHub Actions`.
+4. Set the GitHub owner/user to your account or org.
+5. Set the repository name.
+6. Set the workflow filename to `publish.yml`.
+7. Leave the environment name empty unless you later add a GitHub Actions environment back to the workflow.
+
+Notes for trusted publishing:
+
+- npm trusted publishing requires GitHub-hosted runners.
+- npm recommends Node `22.14.0+` with npm CLI `11.5.1+`; the workflows use Node `24`.
+- Provenance is generated automatically by npm for trusted publishes from public GitHub repositories.
+
 Release flow:
 
 ```bash
@@ -98,10 +126,14 @@ npm run lint
 npm run typecheck
 npm run test
 npm run build
-npm publish --access public
 ```
 
-You can also publish through the GitHub Actions workflow after creating a GitHub release and configuring the `NPM_TOKEN` secret.
+Then publish from GitHub by either:
+
+- creating a GitHub Release, or
+- running the `Publish` workflow manually from the Actions tab
+
+After trusted publishing is working, you can tighten npm package security by disabling token-based publishing for the package in npm settings.
 
 ## Limitations
 

package/dist/index.d.ts

@@ -1,13 +1,4 @@
 import type { Plugin } from '@opencode-ai/plugin';
-export { ClaudeAgentSdkAdapter } from './claude/claude-agent-sdk-adapter.js';
-export { ClaudeSessionService } from './claude/claude-session.service.js';
-export { ManagerOrchestrator } from './manager/manager-orchestrator.js';
-export { TaskPlanner } from './manager/task-planner.js';
-export { ClaudeMetadataService } from './metadata/claude-metadata.service.js';
-export { RepoClaudeConfigReader } from './metadata/repo-claude-config-reader.js';
-export { getOrCreatePluginServices } from './plugin/service-factory.js';
-export { FileRunStateStore } from './state/file-run-state-store.js';
-export { WorktreeCoordinator } from './worktree/worktree-coordinator.js';
 import { ClaudeManagerPlugin } from './plugin/claude-manager.plugin.js';
 export type { ClaudeCapabilitySnapshot, ClaudeMetadataSnapshot, ClaudeSessionRunResult, ClaudeSessionSummary, ClaudeSessionTranscriptMessage, ManagerRunRecord, ManagerRunResult, ManagerTaskRequest, ManagerPromptRegistry, RunClaudeSessionInput, } from './types/contracts.js';
 export { ClaudeManagerPlugin };

package/dist/index.js

@@ -1,12 +1,3 @@
-export { ClaudeAgentSdkAdapter } from './claude/claude-agent-sdk-adapter.js';
-export { ClaudeSessionService } from './claude/claude-session.service.js';
-export { ManagerOrchestrator } from './manager/manager-orchestrator.js';
-export { TaskPlanner } from './manager/task-planner.js';
-export { ClaudeMetadataService } from './metadata/claude-metadata.service.js';
-export { RepoClaudeConfigReader } from './metadata/repo-claude-config-reader.js';
-export { getOrCreatePluginServices } from './plugin/service-factory.js';
-export { FileRunStateStore } from './state/file-run-state-store.js';
-export { WorktreeCoordinator } from './worktree/worktree-coordinator.js';
 import { ClaudeManagerPlugin } from './plugin/claude-manager.plugin.js';
 export { ClaudeManagerPlugin };
 export const plugin = ClaudeManagerPlugin;

package/dist/manager/manager-orchestrator.d.ts

@@ -3,16 +3,18 @@ import type { FileRunStateStore } from '../state/file-run-state-store.js';
 import type { ManagerRunRecord, ManagerRunResult, ManagerTaskRequest } from '../types/contracts.js';
 import type { WorktreeCoordinator } from '../worktree/worktree-coordinator.js';
 import type { TaskPlanner } from './task-planner.js';
+export type ManagerRunProgressHandler = (run: ManagerRunRecord) => void | Promise<void>;
 export declare class ManagerOrchestrator {
     private readonly sessionService;
     private readonly stateStore;
     private readonly worktreeCoordinator;
     private readonly taskPlanner;
     constructor(sessionService: ClaudeSessionService, stateStore: FileRunStateStore, worktreeCoordinator: WorktreeCoordinator, taskPlanner: TaskPlanner);
-    run(request: ManagerTaskRequest): Promise<ManagerRunResult>;
+    run(request: ManagerTaskRequest, onProgress?: ManagerRunProgressHandler): Promise<ManagerRunResult>;
     listRuns(cwd: string): Promise<ManagerRunRecord[]>;
     getRun(cwd: string, runId: string): Promise<ManagerRunRecord | null>;
     cleanupRunWorktrees(cwd: string, runId: string): Promise<ManagerRunRecord | null>;
     private executePlan;
     private patchSession;
+    private updateRunAndNotify;
 }

package/dist/manager/manager-orchestrator.js

@@ -11,7 +11,7 @@ export class ManagerOrchestrator {
         this.worktreeCoordinator = worktreeCoordinator;
         this.taskPlanner = taskPlanner;
     }
-    async run(request) {
+    async run(request, onProgress) {
         const mode = request.mode ?? 'auto';
         const maxSubagents = Math.max(1, request.maxSubagents ?? 3);
         const useWorktrees = request.useWorktrees ?? maxSubagents > 1;
@@ -44,6 +44,7 @@ export class ManagerOrchestrator {
             sessions: plannedAssignments.map(({ plan, assignment }) => createManagedSessionRecord(plan, assignment.cwd, assignment)),
         };
         await this.stateStore.saveRun(runRecord);
+        await onProgress?.(runRecord);
         const canRunInParallel = plannedAssignments.every(({ assignment }) => assignment.mode === 'git-worktree');
         const settledResults = canRunInParallel
             ? await Promise.allSettled(plannedAssignments.map(({ plan, assignment }) => this.executePlan({
@@ -52,6 +53,7 @@ export class ManagerOrchestrator {
                 plan,
                 assignment,
                 includeProjectSettings,
+                onProgress,
             })))
             : await runSequentially(plannedAssignments.map(({ plan, assignment }) => () => this.executePlan({
                 request,
@@ -59,14 +61,15 @@ export class ManagerOrchestrator {
                 plan,
                 assignment,
                 includeProjectSettings,
+                onProgress,
             })));
         const failedResult = settledResults.find((result) => result.status === 'rejected');
-        const finalRun = await this.stateStore.updateRun(request.cwd, runId, (currentRun) => ({
+        const finalRun = await this.updateRunAndNotify(request.cwd, runId, (currentRun) => ({
             ...currentRun,
             status: failedResult ? 'failed' : 'completed',
             updatedAt: new Date().toISOString(),
             finalSummary: summarizeRun(currentRun.sessions),
-        }));
+        }), onProgress);
         return { run: finalRun };
     }
     listRuns(cwd) {
@@ -94,11 +97,11 @@ export class ManagerOrchestrator {
         return run;
     }
     async executePlan(input) {
-        const { request, runId, plan, assignment, includeProjectSettings } = input;
+        const { request, runId, plan, assignment, includeProjectSettings, onProgress, } = input;
         await this.patchSession(request.cwd, runId, plan.id, (session) => ({
             ...session,
             status: 'running',
-        }));
+        }), onProgress);
         try {
             const sessionResult = await this.sessionService.runTask({
                 cwd: assignment.cwd,
@@ -112,7 +115,7 @@ export class ManagerOrchestrator {
                     ...session,
                     claudeSessionId: event.sessionId ?? session.claudeSessionId,
                     events: [...session.events, compactEvent(event)],
-                }));
+                }), onProgress);
             });
             await this.patchSession(request.cwd, runId, plan.id, (session) => ({
                 ...session,
@@ -121,23 +124,28 @@ export class ManagerOrchestrator {
                 finalText: sessionResult.finalText,
                 turns: sessionResult.turns,
                 totalCostUsd: sessionResult.totalCostUsd,
-            }));
+            }), onProgress);
         }
         catch (error) {
             await this.patchSession(request.cwd, runId, plan.id, (session) => ({
                 ...session,
                 status: 'failed',
                 error: error instanceof Error ? error.message : String(error),
-            }));
+            }), onProgress);
             throw error;
         }
     }
-    async patchSession(cwd, runId, sessionId, update) {
-        await this.stateStore.updateRun(cwd, runId, (run) => ({
+    async patchSession(cwd, runId, sessionId, update, onProgress) {
+        await this.updateRunAndNotify(cwd, runId, (run) => ({
             ...run,
             updatedAt: new Date().toISOString(),
             sessions: run.sessions.map((session) => session.id === sessionId ? update(session) : session),
-        }));
+        }), onProgress);
+    }
+    async updateRunAndNotify(cwd, runId, update, onProgress) {
+        const updatedRun = await this.stateStore.updateRun(cwd, runId, update);
+        await onProgress?.(updatedRun);
+        return updatedRun;
     }
 }
 function createManagedSessionRecord(plan, cwd, assignment) {

package/dist/plugin/claude-manager.plugin.js

@@ -1,8 +1,97 @@
 import { tool } from '@opencode-ai/plugin';
+import { managerPromptRegistry } from '../prompts/registry.js';
 import { getOrCreatePluginServices } from './service-factory.js';
+const MANAGER_TOOL_IDS = [
+    'claude_manager_run',
+    'claude_manager_metadata',
+    'claude_manager_sessions',
+    'claude_manager_runs',
+    'claude_manager_cleanup_run',
+];
 export const ClaudeManagerPlugin = async ({ worktree }) => {
     const services = getOrCreatePluginServices(worktree);
     return {
+        config: async (config) => {
+            config.agent ??= {};
+            config.command ??= {};
+            config.permission ??= {};
+            const globalPermissions = config.permission;
+            const managerPermissions = {
+                claude_manager_run: 'allow',
+                claude_manager_metadata: 'allow',
+                claude_manager_sessions: 'allow',
+                claude_manager_runs: 'allow',
+                claude_manager_cleanup_run: 'allow',
+            };
+            const researchPermissions = {
+                claude_manager_run: 'deny',
+                claude_manager_metadata: 'allow',
+                claude_manager_sessions: 'allow',
+                claude_manager_runs: 'allow',
+                claude_manager_cleanup_run: 'deny',
+            };
+            for (const toolId of MANAGER_TOOL_IDS) {
+                globalPermissions[toolId] ??= 'deny';
+            }
+            config.agent['claude-manager'] ??= {
+                description: 'Primary agent that manages Claude Code sessions through the bundled plugin tools.',
+                mode: 'primary',
+                color: 'accent',
+                permission: managerPermissions,
+                prompt: [
+                    managerPromptRegistry.managerSystemPrompt,
+                    'When Claude Code delegation is useful, prefer the claude_manager_run tool instead of simulating the work yourself.',
+                    'Use claude_manager_metadata to inspect available Claude commands, skills, and hooks before making assumptions.',
+                    'Use claude_manager_sessions and claude_manager_runs to inspect prior work before starting a new Claude session.',
+                ].join(' '),
+            };
+            config.agent['claude-manager-research'] ??= {
+                description: 'Subagent that inspects Claude metadata, prior sessions, and manager runs without changing repository state.',
+                mode: 'subagent',
+                color: 'info',
+                permission: researchPermissions,
+                prompt: [
+                    managerPromptRegistry.subagentSystemPrompt,
+                    'Focus on inspection and summarization.',
+                    'Prefer claude_manager_metadata, claude_manager_sessions, and claude_manager_runs over guesswork.',
+                ].join(' '),
+            };
+            config.command['claude-metadata'] ??= {
+                description: 'Inspect bundled Claude commands, skills, hooks, and agents.',
+                agent: 'claude-manager-research',
+                subtask: true,
+                template: [
+                    'Use claude_manager_metadata to inspect the current repository.',
+                    'Summarize Claude commands, skills, hooks, discovered agents, and important config files.',
+                ].join(' '),
+            };
+            config.command['claude-run'] ??= {
+                description: 'Delegate a task to Claude Code through the manager plugin.',
+                agent: 'claude-manager',
+                subtask: true,
+                template: [
+                    'Call claude_manager_run immediately for the following task:',
+                    '$ARGUMENTS',
+                    'Avoid planning narration before the tool call. After it completes, return a concise result summary.',
+                ].join('\n\n'),
+            };
+            config.command['claude-sessions'] ??= {
+                description: 'Inspect Claude session history and manager run records.',
+                agent: 'claude-manager-research',
+                subtask: true,
+                template: [
+                    'Use claude_manager_sessions and claude_manager_runs to inspect recent Claude activity for this repository.',
+                    'If the user provided extra arguments, use them to focus the inspection:',
+                    '$ARGUMENTS',
+                ].join('\n\n'),
+            };
+        },
+        'command.execute.before': async (input, output) => {
+            const commandText = buildCommandText(input.command, input.arguments);
+            if (commandText) {
+                output.parts = rewriteCommandParts(output.parts, commandText);
+            }
+        },
         tool: {
             claude_manager_run: tool({
                 description: 'Delegate a task to Claude Code with optional subagents and worktrees.',
@@ -20,6 +109,7 @@ export const ClaudeManagerPlugin = async ({ worktree }) => {
                         task: args.task,
                         mode: args.mode,
                     });
+                    let lastProgressSignature = '';
                     const result = await services.manager.run({
                         cwd: args.cwd ?? context.worktree,
                         task: args.task,
@@ -28,6 +118,14 @@ export const ClaudeManagerPlugin = async ({ worktree }) => {
                         useWorktrees: args.useWorktrees,
                         includeProjectSettings: args.includeProjectSettings,
                         model: args.model,
+                    }, async (run) => {
+                        const progressView = buildRunProgressView(run);
+                        const signature = JSON.stringify(progressView);
+                        if (signature === lastProgressSignature) {
+                            return;
+                        }
+                        lastProgressSignature = signature;
+                        context.metadata(progressView);
                     });
                     return JSON.stringify(result.run, null, 2);
                 },
@@ -100,3 +198,112 @@ export const ClaudeManagerPlugin = async ({ worktree }) => {
 function annotateToolRun(context, title, metadata) {
     context.metadata({ title, metadata });
 }
+function buildCommandText(command, rawArguments) {
+    const argumentsText = rawArguments.trim();
+    if (command === 'claude-run') {
+        return [
+            'Call `claude_manager_run` immediately.',
+            argumentsText
+                ? `Task: ${argumentsText}`
+                : 'Task: Inspect the current repository and wait for follow-up instructions.',
+            'Do not add planning text before the tool call. After it completes, give a short result summary.',
+        ].join('\n\n');
+    }
+    if (command === 'claude-metadata') {
+        return [
+            'Call `claude_manager_metadata` immediately for the current repository.',
+            argumentsText ? `Focus: ${argumentsText}` : '',
+            'Then summarize the discovered Claude commands, skills, hooks, agents, and config files briefly.',
+        ]
+            .filter(Boolean)
+            .join('\n\n');
+    }
+    if (command === 'claude-sessions') {
+        return [
+            'Call `claude_manager_sessions` and `claude_manager_runs` immediately for the current repository.',
+            argumentsText ? `Focus: ${argumentsText}` : '',
+            'Then summarize the most relevant recent Claude activity briefly.',
+        ]
+            .filter(Boolean)
+            .join('\n\n');
+    }
+    return null;
+}
+function rewriteCommandParts(parts, text) {
+    let hasRewrittenText = false;
+    const rewrittenParts = parts.map((part) => {
+        if (part.type !== 'text' || hasRewrittenText) {
+            return part;
+        }
+        hasRewrittenText = true;
+        return {
+            ...part,
+            text,
+        };
+    });
+    return rewrittenParts;
+}
+function buildRunProgressView(run) {
+    const completed = run.sessions.filter((session) => session.status === 'completed').length;
+    const failed = run.sessions.filter((session) => session.status === 'failed').length;
+    const running = run.sessions.filter((session) => session.status === 'running').length;
+    const pending = run.sessions.filter((session) => session.status === 'pending').length;
+    const total = run.sessions.length;
+    return {
+        title: buildRunProgressTitle(run, { completed, failed, running, total }),
+        metadata: {
+            runId: run.id,
+            status: run.status,
+            progress: `${completed}/${total} completed`,
+            active: running,
+            pending,
+            failed,
+            sessions: run.sessions.map(formatSessionActivity),
+        },
+    };
+}
+function buildRunProgressTitle(run, counts) {
+    const suffix = `(${counts.completed}/${counts.total} complete` +
+        (counts.running > 0 ? `, ${counts.running} active` : '') +
+        (counts.failed > 0 ? `, ${counts.failed} failed` : '') +
+        ')';
+    if (run.status === 'completed') {
+        return `Claude manager completed ${suffix}`;
+    }
+    if (run.status === 'failed') {
+        return `Claude manager failed ${suffix}`;
+    }
+    if (counts.running > 0) {
+        return `Claude manager running ${suffix}`;
+    }
+    return `Claude manager queued ${suffix}`;
+}
+function formatSessionActivity(session) {
+    const parts = [session.title, session.status];
+    if (session.claudeSessionId) {
+        parts.push(session.claudeSessionId);
+    }
+    const latestEvent = findLatestDisplayEvent(session.events);
+    if (latestEvent) {
+        parts.push(`${latestEvent.type}: ${truncateForDisplay(latestEvent.text, 120)}`);
+    }
+    else if (session.finalText) {
+        parts.push(truncateForDisplay(session.finalText, 120));
+    }
+    else if (session.error) {
+        parts.push(truncateForDisplay(session.error, 120));
+    }
+    return parts.join(' | ');
+}
+function findLatestDisplayEvent(events) {
+    return [...events]
+        .reverse()
+        .find((event) => event.type !== 'partial' && Boolean(event.text.trim()));
+}
+function truncateForDisplay(text, maxLength) {
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    if (normalized.length <= maxLength) {
+        return normalized;
+    }
+    return `${normalized.slice(0, maxLength - 3)}...`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doingdev/opencode-claude-manager-plugin",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "OpenCode plugin that orchestrates Claude Code sessions.",
   "keywords": [
     "opencode",
@@ -30,7 +30,8 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "eslint .",
     "format": "prettier --write .",
-    "test": "vitest run"
+    "test": "vitest run",
+    "release": "npm run build && npm version patch && npm publish"
   },
   "engines": {
     "node": ">=22.0.0"