opencode-dux 1.0.0

package/dist/utils/agent-variant.d.ts

@@ -0,0 +1,63 @@
+import { type PluginConfig } from '../config';
+/**
+ * Normalizes an agent name by trimming whitespace and removing the optional @ prefix.
+ *
+ * @param agentName - The agent name to normalize (e.g., "@oracle" or "oracle")
+ * @returns The normalized agent name without @ prefix and trimmed of whitespace
+ *
+ * @example
+ * normalizeAgentName("@oracle") // returns "oracle"
+ * normalizeAgentName("  explore  ") // returns "explore"
+ */
+export declare function normalizeAgentName(agentName: string): string;
+/**
+ * Resolves the variant configuration for a specific agent.
+ *
+ * Looks up the agent's variant in the plugin configuration. Returns undefined if:
+ * - No config is provided
+ * - The agent has no variant configured
+ * - The variant is not a string
+ * - The variant is empty or whitespace-only
+ *
+ * @param config - The plugin configuration object
+ * @param agentName - The name of the agent (with or without @ prefix)
+ * @returns The trimmed variant string, or undefined if no valid variant is found
+ *
+ * @example
+ * resolveAgentVariant(config, "@oracle") // returns "high" if configured
+ */
+export declare function resolveAgentVariant(config: PluginConfig | undefined, agentName: string): string | undefined;
+/**
+ * Resolve a runtime-provided agent name to an internal agent name.
+ *
+ * Supports:
+ * - internal names (e.g. "oracle")
+ * - @-prefixed names (e.g. "@oracle")
+ * - displayName aliases (e.g. "advisor" -> "oracle")
+ */
+export declare function resolveRuntimeAgentName(config: PluginConfig | undefined, agentName: string): string;
+export type DisplayNameMentionRewriter = (text: string) => string;
+export declare function createDisplayNameMentionRewriter(config: PluginConfig | undefined): DisplayNameMentionRewriter;
+/**
+ * Rewrites user-facing display-name mentions (e.g. @advisor) into internal
+ * agent mentions (e.g. @oracle) for runtime routing.
+ */
+export declare function rewriteDisplayNameMentions(config: PluginConfig | undefined, text: string): string;
+/**
+ * Applies a variant to a request body if the body doesn't already have one.
+ *
+ * This function will NOT override an existing variant in the body. If no variant
+ * is provided or the body already has a variant, the original body is returned.
+ *
+ * @template T - The type of the body object, must have an optional variant property
+ * @param variant - The variant string to apply (or undefined)
+ * @param body - The request body object
+ * @returns The body with the variant applied (new object) or the original body unchanged
+ *
+ * @example
+ * applyAgentVariant("high", { agent: "oracle" }) // returns { agent: "oracle", variant: "high" }
+ * applyAgentVariant("high", { agent: "oracle", variant: "low" }) // returns original body with variant: "low"
+ */
+export declare function applyAgentVariant<T extends {
+    variant?: string;
+}>(variant: string | undefined, body: T): T;

package/dist/utils/compat.d.ts

@@ -0,0 +1,30 @@
+import type { ChildProcess } from 'node:child_process';
+export declare const isBun: boolean;
+export interface CrossSpawnResult {
+    proc: ChildProcess;
+    /** Collects all stdout into a string */
+    stdout: () => Promise<string>;
+    /** Collects all stderr into a string */
+    stderr: () => Promise<string>;
+    /** Resolves when process exits with exit code */
+    exited: Promise<number>;
+    /** Kill the process */
+    kill: (signal?: NodeJS.Signals | number) => boolean;
+    /** Current exit code or null if running */
+    get exitCode(): number | null;
+}
+/**
+ * Cross-runtime spawn that works in both Bun and Node.js.
+ * API mimics Bun.spawn but uses node:child_process internally.
+ */
+export declare function crossSpawn(command: string[], options?: {
+    stdout?: 'pipe' | 'inherit' | 'ignore';
+    stderr?: 'pipe' | 'inherit' | 'ignore';
+    stdin?: 'pipe' | 'inherit' | 'ignore';
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+}): CrossSpawnResult;
+/**
+ * Cross-runtime file write that works in both Bun and Node.js.
+ */
+export declare function crossWrite(path: string, data: ArrayBuffer | Buffer | string): Promise<void>;

package/dist/utils/env.d.ts

@@ -0,0 +1 @@
+export declare function getEnv(name: string): string | undefined;

package/dist/utils/index.d.ts

@@ -0,0 +1,9 @@
+export * from './agent-variant';
+export * from './env';
+export * from './internal-initiator';
+export { getLogDir, initLogger, log, resetLogger } from './logger';
+export * from './polling';
+export * from './session';
+export * from './session-manager';
+export * from './task';
+export { extractZip } from './zip-extractor';

package/dist/utils/internal-initiator.d.ts

@@ -0,0 +1,6 @@
+export declare const SLIM_INTERNAL_INITIATOR_MARKER = "<!-- SLIM_INTERNAL_INITIATOR -->";
+export declare function createInternalAgentTextPart(text: string): {
+    type: 'text';
+    text: string;
+};
+export declare function hasInternalInitiatorMarker(part: unknown): boolean;

package/dist/utils/logger.d.ts

@@ -0,0 +1,8 @@
+declare function getLogDir(): string;
+export declare function initLogger(sessionId: string): void;
+/** @internal Reset logger state for testing */
+export declare function resetLogger(): void;
+/** @internal Wait for queued log writes in tests. */
+export declare function flushLoggerForTesting(): Promise<void>;
+export { getLogDir };
+export declare function log(message: string, data?: unknown): void;

package/dist/utils/polling.d.ts

@@ -0,0 +1,21 @@
+export interface PollOptions {
+    pollInterval?: number;
+    maxPollTime?: number;
+    stableThreshold?: number;
+    signal?: AbortSignal;
+}
+export interface PollResult<T> {
+    success: boolean;
+    data?: T;
+    timedOut?: boolean;
+    aborted?: boolean;
+}
+/**
+ * Generic polling utility that waits for a condition to be met.
+ * Returns when the condition is satisfied or timeout/abort occurs.
+ */
+export declare function pollUntilStable<T>(fetchFn: () => Promise<T>, isStable: (current: T, previous: T | null, stableCount: number) => boolean, opts?: PollOptions): Promise<PollResult<T>>;
+/**
+ * Simple delay utility
+ */
+export declare function delay(ms: number): Promise<void>;

package/dist/utils/session-manager.d.ts

@@ -0,0 +1,55 @@
+import type { AgentName } from '../config';
+export interface ContextFile {
+    path: string;
+    lineCount: number;
+    lineNumbers?: number[];
+    lastReadAt: number;
+}
+export interface RememberedTaskSession {
+    alias: string;
+    taskId: string;
+    agentType: AgentName;
+    label: string;
+    contextFiles: ContextFile[];
+    createdAt: number;
+    lastUsedAt: number;
+}
+interface SessionManagerOptions {
+    readContextMinLines?: number;
+    readContextMaxFiles?: number;
+}
+export declare function deriveTaskSessionLabel(input: {
+    description?: string;
+    prompt?: string;
+    agentType: AgentName;
+}): string;
+export declare class SessionManager {
+    private readonly maxSessionsPerAgent;
+    private readonly readContextMinLines;
+    private readonly readContextMaxFiles;
+    private readonly sessionsByParent;
+    private readonly nextAliasIndexByParent;
+    private orderCounter;
+    constructor(maxSessionsPerAgent: number, options?: SessionManagerOptions);
+    remember(input: {
+        parentSessionId: string;
+        taskId: string;
+        agentType: AgentName;
+        label: string;
+    }): RememberedTaskSession;
+    markUsed(parentSessionId: string, agentType: AgentName, key: string): void;
+    resolve(parentSessionId: string, agentType: AgentName, key: string): RememberedTaskSession | undefined;
+    drop(parentSessionId: string, agentType: AgentName, key: string): void;
+    dropTask(taskId: string): void;
+    taskIds(): Set<string>;
+    addContext(taskId: string, files: ContextFile[]): void;
+    clearParent(parentSessionId: string): void;
+    formatForPrompt(parentSessionId: string): string | undefined;
+    private getAgentGroup;
+    private setAgentGroup;
+    private nextAlias;
+    private trimGroup;
+    private trimContextFiles;
+    private nextOrder;
+}
+export {};

package/dist/utils/session.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared session utilities for background managers.
+ */
+import type { PluginInput } from '@opencode-ai/plugin';
+type OpencodeClient = PluginInput['client'];
+type SessionPromptBody = NonNullable<Parameters<OpencodeClient['session']['prompt']>[0]['body']>;
+/** Multimodal / text parts accepted by `session.prompt` */
+export type PromptBodyPart = SessionPromptBody['parts'][number];
+/** Prompt body including optional variant (supported by the host at runtime). */
+export type PromptBody = SessionPromptBody & {
+    variant?: string;
+};
+/**
+ * Extract the short model label from a "provider/model" string.
+ * E.g. "openai/gpt-5.4-mini" → "gpt-5.4-mini"
+ */
+export declare function shortModelLabel(model: string): string;
+/**
+ * Parse a model reference string into provider and model IDs.
+ * @param model - Model string in format "provider/model"
+ * @returns Object with providerID and modelID, or null if invalid
+ */
+export declare function parseModelReference(model: string): {
+    providerID: string;
+    modelID: string;
+} | null;
+/**
+ * OpenCode stores pasted / attached screenshots as {@link FilePart} (`type: "file"`,
+ * `mime` starting with `image/`), not as `type: "image"`. Some stacks still emit
+ * legacy `image` parts - accept both.
+ *
+ * @see https://github.com/anomalyco/opencode/blob/dev/packages/opencode/src/session/message-v2.ts
+ */
+export declare function isForwardableImagePart(part: Record<string, unknown>): boolean;
+/**
+ * Non-text parts (e.g. images) from the latest user message in a session.
+ * Used when forwarding multimodal context to delegated agents such as @interpreter.
+ */
+export declare function extractLatestUserImageParts(client: OpencodeClient, sessionId: string, directory: string): Promise<PromptBodyPart[]>;
+/**
+ * Stored {@link FilePart} rows include `sessionID` / `messageID` / etc. Child
+ * `session.prompt` expects {@link FilePartInput}-shaped drafts (`type`, `mime`,
+ * `url`, optional `filename`). Some attachments omit `url` but provide
+ * `source.path` - resolve that to a `file:` URL when possible.
+ */
+export declare function normalizeImagePartsForChildPrompt(parts: PromptBodyPart[], workspaceDirectory?: string): PromptBodyPart[];
+/**
+ * Send a prompt to a session with optional timeout.
+ * If timeout is exceeded, the session is aborted and an error is thrown.
+ * @param client - OpenCode client instance
+ * @param args - Arguments for session.prompt()
+ * @param timeoutMs - Timeout in milliseconds (0 = no timeout)
+ * @throws Error if timeout is exceeded
+ */
+export declare function promptWithTimeout(client: OpencodeClient, args: Parameters<OpencodeClient['session']['prompt']>[0], timeoutMs: number): Promise<void>;
+/**
+ * Result of extracting session content.
+ * `empty` is true when the assistant produced zero text content -
+ * the provider returned an empty response (e.g. rate-limited silently).
+ */
+export interface SessionExtractionResult {
+    text: string;
+    empty: boolean;
+}
+/**
+ * Extract the result text from a session.
+ * Collects all assistant messages and concatenates their text parts.
+ * @param client - OpenCode client instance
+ * @param sessionId - Session ID to extract from
+ * @param options - Optional: `includeReasoning` (default true) controls whether
+ *                  reasoning/chain-of-thought parts are included;
+ *                  `directory` scopes workspace for `session.messages` (child sessions).
+ * @returns Object with extracted text and an `empty` flag for zero-content detection
+ */
+export declare function extractSessionResult(client: OpencodeClient, sessionId: string, options?: {
+    includeReasoning?: boolean;
+    directory?: string;
+}): Promise<SessionExtractionResult>;
+/**
+ * After `session.prompt`, optionally wait for a terminal session status.
+ * Returns immediately when per-session status is unavailable (common for some hosts),
+ * so we never block the orchestrator on a mismatched status API.
+ */
+export declare function waitUntilSessionIdle(client: OpencodeClient, sessionId: string, workspaceDirectory: string): Promise<void>;
+/**
+ * After `session.prompt`, wait for idle then read assistant text. Retries if the
+ * message store lags; falls back to including reasoning parts if text is still empty.
+ */
+export declare function extractAssistantTextAfterPrompt(client: OpencodeClient, sessionId: string, workspaceDirectory: string): Promise<SessionExtractionResult>;
+export {};

package/dist/utils/subagent-depth.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tracks subagent spawn depth to prevent excessive nesting.
+ *
+ * Depth 0 = root session (user's main conversation)
+ * Depth 1 = agent spawned by root (e.g., explorer)
+ * Depth 2 = agent spawned by depth-1 agent
+ * Depth 3 = agent spawned by depth-2 agent (max depth by default)
+ *
+ * When max depth is exceeded, the spawn is blocked.
+ */
+export declare class SubagentDepthTracker {
+    private depthBySession;
+    private readonly _maxDepth;
+    constructor(maxDepth?: number);
+    /** Maximum allowed depth. */
+    get maxDepth(): number;
+    /**
+     * Get the current depth of a session.
+     * Root sessions (not tracked) have depth 0.
+     */
+    getDepth(sessionId: string): number;
+    /**
+     * Register a child session and check if the spawn is allowed.
+     * @returns true if allowed, false if max depth exceeded
+     */
+    registerChild(parentSessionId: string, childSessionId: string): boolean;
+    /**
+     * Clean up session tracking when a session is deleted.
+     */
+    cleanup(sessionId: string): void;
+    /**
+     * Clean up all tracking data.
+     */
+    cleanupAll(): void;
+}

package/dist/utils/system-collapse.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Collapse a system message array into a single element by joining all
+ * entries with double-newline separators. Mutates the array in-place so
+ * that callers holding a reference to the original array see the change.
+ */
+export declare function collapseSystemInPlace(system: string[]): void;

package/dist/utils/task.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Parse Task tool output to recover a session/task ID for resumption.
+ */
+export declare function parseTaskIdFromTaskOutput(output: string): string | undefined;

package/dist/utils/zip-extractor.d.ts

@@ -0,0 +1 @@
+export declare function extractZip(archivePath: string, destDir: string): Promise<void>;

package/index.ts

@@ -0,0 +1 @@
+export { default } from './src/index';