zenox 0.1.0

package/README.md

@@ -0,0 +1,122 @@
+# zenox
+
+OpenCode plugin for intelligent agent orchestration with specialized subagents and parallel background tasks.
+
+## Features
+
+- **4 Specialized Subagents**: Explorer, Librarian, Oracle, UI-Planner
+- **Background Tasks**: Parallel agent execution for comprehensive research
+- **Auto-Loaded MCP Servers**: exa, grep_app, sequential-thinking
+- **Smart Orchestration**: Automatically teaches Build/Plan agents how to delegate
+- **Portable**: Install on any machine via opencode.json
+
+## Installation
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["zenox@0.1.0"]
+}
+```
+
+Restart OpenCode and the plugin is ready to use.
+
+## Agents
+
+### @explorer
+Fast codebase search specialist.
+- "Where is X implemented?"
+- "Find all files containing Y"
+- Pattern matching and locating implementations
+
+**Model**: `anthropic/claude-haiku-4-5`
+
+### @librarian
+Open-source research agent.
+- "How does library X work?"
+- "Show me implementation examples"
+- Finding official documentation
+
+**Model**: `anthropic/claude-sonnet-4-5`
+
+### @oracle
+Strategic technical advisor.
+- Architecture decisions
+- Code review and debugging strategy
+- Technical trade-offs analysis
+
+**Model**: `openai/gpt-5.2-high`
+
+### @ui-planner
+Designer-turned-developer.
+- Beautiful UI/UX implementation
+- Frontend aesthetics and animations
+- Visual design without mockups
+
+**Model**: `google/gemini-3-pro-high`
+
+## Background Tasks
+
+For parallel research, use background tasks instead of sequential agents:
+
+```
+// Launch parallel research (all run simultaneously)
+background_task(agent="explorer", description="Find auth code", prompt="...")
+background_task(agent="explorer", description="Find db layer", prompt="...")
+background_task(agent="librarian", description="Best practices", prompt="...")
+
+// Continue working while they run...
+// [NOTIFICATION: All background tasks complete!]
+
+// Retrieve results
+background_output(task_id="bg_abc123")
+```
+
+### When to Use
+
+| Scenario | Use Background Tasks |
+|----------|---------------------|
+| Comprehensive exploration | YES - fire 3-4 agents in parallel |
+| Codebase + external docs | YES - explore + librarian in parallel |
+| Result A needed before B | NO - use sequential Task |
+
+## Configuration (Optional)
+
+Create `~/.config/opencode/zenox.json` or `.opencode/zenox.json`:
+
+```json
+{
+  "agents": {
+    "explorer": { "model": "anthropic/claude-sonnet-4" },
+    "oracle": { "model": "openai/gpt-4o" }
+  },
+  "disabled_agents": [],
+  "disabled_mcps": []
+}
+```
+
+## Auto-Loaded MCP Servers
+
+| MCP Server | Description |
+|------------|-------------|
+| `exa` | Web search, code context, URL crawling |
+| `grep_app` | GitHub code search across millions of repos |
+| `sequential-thinking` | Structured reasoning for complex problems |
+
+## Development
+
+```bash
+bun install
+bun run build
+bun run typecheck
+```
+
+## Credits
+
+- **[OpenCode](https://opencode.ai)** — The CLI tool this plugin extends
+- **[oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode)** by YeonGyu Kim — Inspiration for orchestration patterns
+
+## License
+
+MIT

package/dist/agents/explorer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const explorerAgent: AgentConfig;

package/dist/agents/index.d.ts

@@ -0,0 +1,5 @@
+export { explorerAgent } from "./explorer";
+export { librarianAgent } from "./librarian";
+export { oracleAgent } from "./oracle";
+export { uiPlannerAgent } from "./ui-planner";
+export type { BuiltinAgentName, AgentOverrideConfig, AgentOverrides } from "./types";

package/dist/agents/librarian.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const librarianAgent: AgentConfig;

package/dist/agents/oracle.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const oracleAgent: AgentConfig;

package/dist/agents/types.d.ts

@@ -0,0 +1,7 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export type AgentFactory = (model?: string) => AgentConfig;
+export type BuiltinAgentName = "explorer" | "librarian" | "oracle" | "ui-planner";
+export type AgentOverrideConfig = Partial<AgentConfig> & {
+    prompt_append?: string;
+};
+export type AgentOverrides = Partial<Record<BuiltinAgentName, AgentOverrideConfig>>;

package/dist/agents/ui-planner.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const uiPlannerAgent: AgentConfig;

package/dist/background/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Background Task System
+ *
+ * Provides parallel agent execution via fire-and-forget background sessions.
+ */
+export { BackgroundManager } from "./manager";
+export { createBackgroundTools, type BackgroundTools } from "./tools";
+export type { BackgroundTask, TaskStatus, LaunchInput, CompletionNotification, } from "./types";

package/dist/background/manager.d.ts

@@ -0,0 +1,28 @@
+/**
+ * BackgroundManager - Minimal background task orchestration
+ *
+ * Handles:
+ * - Launching background agent sessions (fire-and-forget)
+ * - Tracking task status
+ * - Detecting completion via session.idle events
+ * - Generating completion notifications
+ */
+import type { OpencodeClient } from "@opencode-ai/sdk";
+import type { BackgroundTask, LaunchInput, CompletionNotification } from "./types";
+export declare class BackgroundManager {
+    private tasks;
+    private mainSessionID;
+    setMainSession(sessionID: string): void;
+    getMainSession(): string | undefined;
+    private generateTaskId;
+    launch(client: OpencodeClient, input: LaunchInput): Promise<BackgroundTask>;
+    getTask(taskId: string): BackgroundTask | undefined;
+    findTaskBySessionID(sessionID: string): BackgroundTask | undefined;
+    getOutput(client: OpencodeClient, taskId: string): Promise<string | undefined>;
+    cancel(client: OpencodeClient, taskId: string): Promise<boolean>;
+    handleSessionIdle(sessionID: string): CompletionNotification | null;
+    getCompletionStatus(): CompletionNotification;
+    listActiveTasks(): BackgroundTask[];
+    listAllTasks(): BackgroundTask[];
+    clearCompleted(): void;
+}

package/dist/background/tools.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Background Task Tools
+ *
+ * Three tools for background task management:
+ * - background_task: Launch a background agent
+ * - background_output: Get result from completed task
+ * - background_cancel: Cancel a running task
+ */
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { OpencodeClient } from "@opencode-ai/sdk";
+import type { BackgroundManager } from "./manager";
+export type BackgroundTools = {
+    [key: string]: ToolDefinition;
+};
+export declare function createBackgroundTools(manager: BackgroundManager, client: OpencodeClient): BackgroundTools;

package/dist/background/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Background Task System Types
+ * Minimal interfaces for fire-and-forget parallel agent execution
+ */
+export type TaskStatus = "running" | "completed" | "failed" | "cancelled";
+export interface BackgroundTask {
+    id: string;
+    sessionID: string;
+    agent: string;
+    description: string;
+    prompt: string;
+    status: TaskStatus;
+    startedAt: Date;
+    completedAt?: Date;
+    error?: string;
+}
+export interface LaunchInput {
+    agent: string;
+    prompt: string;
+    description: string;
+    parentSessionID: string;
+}
+export interface CompletionNotification {
+    allComplete: boolean;
+    message: string;
+    completedTasks: BackgroundTask[];
+    runningCount: number;
+}

package/dist/config/index.d.ts

@@ -0,0 +1,2 @@
+export { ZenoxConfigSchema, AgentNameSchema, AgentOverrideConfigSchema, AgentOverridesSchema, type ZenoxConfig, type AgentName, type AgentOverrideConfig, type AgentOverrides, } from "./schema";
+export { loadPluginConfig } from "./loader";

package/dist/config/loader.d.ts

@@ -0,0 +1,6 @@
+import { type ZenoxConfig } from "./schema";
+/**
+ * Load plugin configuration from user and project paths
+ * Project config takes priority over user config
+ */
+export declare function loadPluginConfig(projectDirectory: string): ZenoxConfig;

package/dist/config/schema.d.ts

@@ -0,0 +1,179 @@
+import { z } from "zod";
+/**
+ * Agent names that can be configured
+ */
+export declare const AgentNameSchema: z.ZodEnum<["explorer", "librarian", "oracle", "ui-planner"]>;
+export type AgentName = z.infer<typeof AgentNameSchema>;
+/**
+ * Configuration for overriding an agent's settings
+ * Only model override is supported - keeps it simple
+ */
+export declare const AgentOverrideConfigSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    model?: string | undefined;
+}, {
+    model?: string | undefined;
+}>;
+export type AgentOverrideConfig = z.infer<typeof AgentOverrideConfigSchema>;
+/**
+ * Agent overrides mapping
+ */
+export declare const AgentOverridesSchema: z.ZodObject<{
+    explorer: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        model?: string | undefined;
+    }, {
+        model?: string | undefined;
+    }>>;
+    librarian: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        model?: string | undefined;
+    }, {
+        model?: string | undefined;
+    }>>;
+    oracle: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        model?: string | undefined;
+    }, {
+        model?: string | undefined;
+    }>>;
+    "ui-planner": z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        model?: string | undefined;
+    }, {
+        model?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    explorer?: {
+        model?: string | undefined;
+    } | undefined;
+    librarian?: {
+        model?: string | undefined;
+    } | undefined;
+    oracle?: {
+        model?: string | undefined;
+    } | undefined;
+    "ui-planner"?: {
+        model?: string | undefined;
+    } | undefined;
+}, {
+    explorer?: {
+        model?: string | undefined;
+    } | undefined;
+    librarian?: {
+        model?: string | undefined;
+    } | undefined;
+    oracle?: {
+        model?: string | undefined;
+    } | undefined;
+    "ui-planner"?: {
+        model?: string | undefined;
+    } | undefined;
+}>;
+export type AgentOverrides = z.infer<typeof AgentOverridesSchema>;
+/**
+ * Main configuration schema for zenox
+ */
+export declare const ZenoxConfigSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    agents: z.ZodOptional<z.ZodObject<{
+        explorer: z.ZodOptional<z.ZodObject<{
+            model: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            model?: string | undefined;
+        }, {
+            model?: string | undefined;
+        }>>;
+        librarian: z.ZodOptional<z.ZodObject<{
+            model: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            model?: string | undefined;
+        }, {
+            model?: string | undefined;
+        }>>;
+        oracle: z.ZodOptional<z.ZodObject<{
+            model: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            model?: string | undefined;
+        }, {
+            model?: string | undefined;
+        }>>;
+        "ui-planner": z.ZodOptional<z.ZodObject<{
+            model: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            model?: string | undefined;
+        }, {
+            model?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        explorer?: {
+            model?: string | undefined;
+        } | undefined;
+        librarian?: {
+            model?: string | undefined;
+        } | undefined;
+        oracle?: {
+            model?: string | undefined;
+        } | undefined;
+        "ui-planner"?: {
+            model?: string | undefined;
+        } | undefined;
+    }, {
+        explorer?: {
+            model?: string | undefined;
+        } | undefined;
+        librarian?: {
+            model?: string | undefined;
+        } | undefined;
+        oracle?: {
+            model?: string | undefined;
+        } | undefined;
+        "ui-planner"?: {
+            model?: string | undefined;
+        } | undefined;
+    }>>;
+    disabled_agents: z.ZodOptional<z.ZodArray<z.ZodEnum<["explorer", "librarian", "oracle", "ui-planner"]>, "many">>;
+    disabled_mcps: z.ZodOptional<z.ZodArray<z.ZodEnum<["exa", "grep_app", "sequential-thinking"]>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    $schema?: string | undefined;
+    agents?: {
+        explorer?: {
+            model?: string | undefined;
+        } | undefined;
+        librarian?: {
+            model?: string | undefined;
+        } | undefined;
+        oracle?: {
+            model?: string | undefined;
+        } | undefined;
+        "ui-planner"?: {
+            model?: string | undefined;
+        } | undefined;
+    } | undefined;
+    disabled_agents?: ("explorer" | "librarian" | "oracle" | "ui-planner")[] | undefined;
+    disabled_mcps?: ("exa" | "grep_app" | "sequential-thinking")[] | undefined;
+}, {
+    $schema?: string | undefined;
+    agents?: {
+        explorer?: {
+            model?: string | undefined;
+        } | undefined;
+        librarian?: {
+            model?: string | undefined;
+        } | undefined;
+        oracle?: {
+            model?: string | undefined;
+        } | undefined;
+        "ui-planner"?: {
+            model?: string | undefined;
+        } | undefined;
+    } | undefined;
+    disabled_agents?: ("explorer" | "librarian" | "oracle" | "ui-planner")[] | undefined;
+    disabled_mcps?: ("exa" | "grep_app" | "sequential-thinking")[] | undefined;
+}>;
+export type ZenoxConfig = z.infer<typeof ZenoxConfigSchema>;

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * zenox - OpenCode Plugin for Intelligent Agent Orchestration
+ *
+ * This plugin provides:
+ * 1. Specialized subagents: explorer, librarian, oracle, ui-planner
+ * 2. Orchestration injection into Build/Plan agents for smart delegation
+ * 3. Auto-loaded MCP servers: exa, grep_app, sequential-thinking
+ * 4. Background task system for parallel agent execution
+ * 5. Optional configuration via zenox.json for model/MCP overrides
+ */
+import type { Plugin } from "@opencode-ai/plugin";
+declare const ZenoxPlugin: Plugin;
+export default ZenoxPlugin;
+export type { BuiltinAgentName, AgentOverrideConfig, AgentOverrides, } from "./agents";
+export type { ZenoxConfig, AgentName, } from "./config";
+export type { McpName } from "./mcp";
+export type { BackgroundTask, TaskStatus } from "./background";