better-opencode-async-agents 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Changed
+- **Improved fork context display format**: Role labels changed from `[USER]`/`[ASSISTANT]` to `User:`/`Agent:` for better readability
+- **Tool call parameter preview**: Forked context now shows tool parameters (up to 200 chars) instead of just tool names
+
+### Breaking Changes
+- **BREAKING** Renamed all tools from `background_*` to `superagents_*`:
+  - `background_task` → `superagents_task`
+  - `background_output` → `superagents_output`
+  - `background_cancel` → `superagents_cancel`
+  - `background_list` → `superagents_list`
+  - `background_clear` → `superagents_clear`
+
+## [0.3.0] - 2026-01-23
+
+### Breaking Changes
+- **Changed Task ID format**: Task IDs have changed from `bg_*` format to session ID format (`ses_*`).
+- **Removed `id` from `BackgroundTask`**: The `id` field has been removed. Use `sessionID` instead to identify tasks.
+- **Invalidated old task IDs**: Task IDs from previous versions are no longer valid and cannot be used with `background_output` or `background_task`.
+- **Changed notification message format**: Notifications now use emoji + bold pattern (e.g., `✓ **Background task completed**`) instead of bracket format (e.g., `[BACKGROUND TASK COMPLETED]`).
+- **Removed preview section from resume notifications**: Resume completion notifications no longer include a response preview.
+
+### Added
+- **Persistent Task Metadata**: Task metadata is now persisted to disk at `~/.opencode/plugins/opencode-superagents/tasks.json`.
+- **Durable Tasks**: Tasks now survive plugin restarts and can be resumed indefinitely as long as the session exists in OpenCode.
+- **GitHub-style short IDs**: Task IDs now display in short format (e.g., `ses_41e08091` instead of full `ses_41e080918ffeyhQtX6E4vERe4O`). All tools accept both short and full IDs.
+- **Prefix matching for task IDs**: You can now use any unique prefix to reference a task (e.g., `ses_41e0` if it uniquely identifies a task).
+- **`fork` parameter for `background_task` tool to inherit parent conversation context**
+- **Context processing utilities for token counting and tool result truncation**
+- **`(forked)` indicator in task listings**
+- **Fork preamble injection for context-aware child agents**
+
+### Changed
+- **`background_clear` behavior**: The `background_clear` tool now only clears the in-memory task cache. It no longer deletes task metadata from disk storage.
+- **Simplified launch message**: Removed redundant "Use `background_output` with task_id=..." instruction from launch messages.
+- **Cleaner toast notifications**: Toast titles now use emoji format (e.g., `✓ Task completed` instead of `Background Task COMPLETED`).
+- **Resume count display**: Resume notifications only show count for 2nd+ resumes (e.g., `✓ **Resume #2 completed**`).
+
+### Migration
+Users must update any code or external systems referencing `task.id` to use `task.sessionID`.
+Existing tasks created in previous versions cannot be resumed or retrieved.
+
+Short IDs are now accepted but full IDs still work, so no migration is required for task references.
+
+```typescript
+// Before
+const taskId = task.id;
+
+// After
+const sessionID = task.sessionID;
+```
+
+## [2.0.0] - 2026-01-22
+
+### Breaking Changes
+- **Removed** `background_resume` tool - use `background_task(resume: id, prompt: msg)` instead
+- **Removed** `background_block` tool - use `background_output(task_id: id, block: true)` instead
+
+### Changed
+- `background_task` now supports resume mode with optional `resume` parameter for continuing existing tasks
+- `background_output` now supports optional `block` and `timeout` parameters for blocking mode
+- `background_list` shows `(resumed)` indicator for tasks that have been resumed
+
+### Migration
+```typescript
+// Resume: Before
+background_resume(task_id: 'abc123', message: 'continue working on this')
+// Resume: After
+background_task(resume: 'abc123', prompt: 'continue working on this')
+
+// Block: Before
+background_block(task_ids: ['abc123'], timeout: 60000)  // timeout in ms
+// Block: After
+background_output(task_id: 'abc123', block: true, timeout: 60)  // timeout in seconds
+```
+
+## [0.1.1] - 2026-01-20
+
+### Fixed
+- Corrected npm package name in README badges and installation instructions
+- Fixed GitHub repository links throughout documentation
+- Added bugs and homepage URLs to package.json
+
+## [0.1.0] - 2026-01-19
+
+### Added
+- Initial release of @paulp-o/opencode-background-agent
+- `background_task` tool for launching async agent tasks
+- `background_output` tool for retrieving task results
+- `background_cancel` tool for cancelling running tasks
+- `background_list` tool for listing all tasks
+- `background_clear` tool for clearing all tasks
+- Real-time progress tracking with toast notifications
+- Automatic task completion notifications
+- npm release system with conventional commits

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 paulpark
+
+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,67 @@
+# Better OpenCode Async Agents
+
+[![npm version](https://img.shields.io/npm/v/better-opencode-async-agents)](https://www.npmjs.com/package/better-opencode-async-agents)
+[![license](https://img.shields.io/npm/l/better-opencode-async-agents)](https://github.com/mainsoft-2024/better-opencode-async-agents/blob/main/LICENSE)
+
+An unopinionated, **Non-Blocking(optional), Async** Background agent plugin for OpenCode, **same as (or better than) that of Claude Code!**
+
+## Configuration
+
+Add the plugin to your `opencode.json(c)`:
+
+```json
+{
+  "plugin": ["better-opencode-async-agents"]
+}
+```
+
+## Features
+
+- **Async Task Execution**: Run long-running agent tasks in parallel without blocking
+- **Real-time Progress Tracking**: Live updates with spinner animations and tool call counts
+- **Toast Notifications**: Visual status updates directly in your OpenCode UI
+- **Automatic Completion Notifications**: Get notified when tasks finish (success/error/cancelled)
+- **Batch Task Management**: Track multiple tasks as a batch with progress indicators
+- **Result Retrieval**: Block or non-blocking result fetching with configurable timeouts
+- **Session Integration**: Tasks automatically clean up when parent sessions change or are deleted
+
+## Tools Provided
+
+- **`superagents_task(description: string, prompt: string, agent: string)`**: Launch async background agent tasks
+- **`superagents_output(task_id: string, block: boolean, timeout?: number)`**: Get task results (blocking/non-blocking)
+- **`superagents_cancel(task_id: string)`**: Cancel running tasks
+- **`superagents_resume(task_id: string, message: string, block?: boolean, timeout?: number)`**: Resume a completed task with a follow-up message for multi-turn conversations
+- **`superagents_list(status?: "running" | "completed" | "error" | "cancelled")`**: List all tasks with status filter
+- **`superagents_clear()`**: Abort and clear all tasks
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Build the project
+bun run build
+
+# Run tests
+bun test
+
+# Run linter
+bun run lint
+
+# Type check
+bun run typecheck
+
+# Format code
+bun run format
+```
+
+## License
+
+MIT
+
+---
+
+## Support
+
+For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/mainsoft-2024/better-opencode-async-agents).

package/dist/constants.d.ts

@@ -0,0 +1,11 @@
+export declare const COMPLETION_DISPLAY_DURATION = 10000;
+export declare const SPINNER_FRAMES: string[];
+export declare const STORAGE_DIR: string;
+export declare const TASKS_FILE: string;
+/** Maximum tokens to include in forked context (leaves room for response) */
+export declare const FORK_MAX_TOKENS = 100000;
+/** Maximum characters per tool result before truncation */
+export declare const FORK_TOOL_RESULT_LIMIT = 1500;
+/** Maximum characters for tool parameters preview in forked context */
+export declare const FORK_TOOL_PARAMS_LIMIT = 200;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AACjD,eAAO,MAAM,cAAc,UAAqD,CAAC;AAoCjF,eAAO,MAAM,WAAW,QAA+D,CAAC;AACxF,eAAO,MAAM,UAAU,QAA8B,CAAC;AAMtD,6EAA6E;AAC7E,eAAO,MAAM,eAAe,SAAS,CAAC;AAEtC,2DAA2D;AAC3D,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,MAAM,CAAC"}

package/dist/fork/index.d.ts

@@ -0,0 +1,37 @@
+export interface SessionMessage {
+    info?: {
+        role?: string;
+    };
+    parts?: Array<{
+        type?: string;
+        text?: string;
+        tool?: string;
+        state?: {
+            input?: Record<string, unknown>;
+        };
+        name?: string;
+        id?: string;
+        input?: Record<string, unknown>;
+    }>;
+}
+export interface ProcessingStats {
+    originalCount: number;
+    finalCount: number;
+    totalTokens: number;
+    truncatedResults: number;
+    removedMessages: number;
+}
+export declare function countMessageTokens(message: SessionMessage): number;
+export declare function truncateToolResult(text: string, limit?: number): {
+    text: string;
+    wasTruncated: boolean;
+};
+export declare function processMessagesForFork(messages: SessionMessage[], maxTokens?: number): {
+    messages: SessionMessage[];
+    stats: ProcessingStats;
+};
+/**
+ * Formats processed messages into a context string for injection.
+ */
+export declare function formatMessagesAsContext(messages: SessionMessage[]): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/fork/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fork/index.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzB,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QAEd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE;YAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,CAAC;QAE5C,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACjC,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;CACzB;AAUD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAQlE;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAA+B,GACrC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAWzC;AA4BD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,cAAc,EAAE,EAC1B,SAAS,GAAE,MAAwB,GAClC;IAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,CAuCxD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,MAAM,CA0C1E"}

package/dist/helpers.d.ts

@@ -0,0 +1,33 @@
+import type { BackgroundTask, BackgroundTaskStatus } from "./types";
+/**
+ * Centralized task status setter. Always use this to change task status.
+ * - Sets task.status
+ * - Sets task.completedAt for terminal statuses
+ * - Optionally sets task.error
+ * - Auto-persists if persistFn is provided
+ */
+export declare function setTaskStatus(task: BackgroundTask, status: BackgroundTaskStatus, options?: {
+    error?: string;
+    persistFn?: (task: BackgroundTask) => void;
+}): void;
+/**
+ * Converts a full session ID to a short display ID (GitHub-style).
+ * Example: ses_41e080918ffeyhQtX6E4vERe4O → ses_41e08091
+ */
+export declare function shortId(sessionId: string): string;
+export declare function formatDuration(startStr: string, endStr?: string): string;
+export declare function truncateText(text: string, maxLength: number): string;
+export declare function getStatusIcon(status: BackgroundTaskStatus): string;
+export declare function formatTaskStatus(task: BackgroundTask): string;
+interface TaskMessage {
+    info?: {
+        role?: string;
+    };
+    parts?: Array<{
+        type?: string;
+        text?: string;
+    }>;
+}
+export declare function formatTaskResult(task: BackgroundTask, getMessages: (sessionID: string) => Promise<TaskMessage[]>): Promise<string>;
+export {};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAMpE;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,oBAAoB,EAC5B,OAAO,CAAC,EAAE;IACR,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;CAC5C,GACA,IAAI,CAeN;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAexE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAalE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CA8B7D;AAGD,UAAU,WAAW;IACnB,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzB,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,GACzD,OAAO,CAAC,MAAM,CAAC,CA8CjB"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { Hooks, PluginInput } from "@opencode-ai/plugin";
+export type { BackgroundTask, BackgroundTaskStatus, TaskProgress, LaunchInput } from "./types";
+/**
+ * OpenCode Background Agent Plugin
+ *
+ * Provides tools for launching and managing asynchronous background tasks
+ * that run in separate sessions while the main conversation continues.
+ */
+export default function plugin(ctx: PluginInput): Promise<Hooks>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAW9D,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI/F;;;;;GAKG;AACH,wBAA8B,MAAM,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAerE"}