@cleocode/adapters 2026.4.58 → 2026.4.59

package/dist/providers/openai-sdk/tracing.js

@@ -0,0 +1,157 @@
+/**
+ * OpenAI Agents SDK trace processor that writes spans to conduit.db.
+ *
+ * `CleoConduitTraceProcessor` implements the SDK `TracingProcessor` interface.
+ * On every span end it serialises the span and writes a structured event to
+ * conduit.db via the shared `conduit-trace-writer` transport layer.
+ *
+ * Tracing is on by default for all OpenAI SDK spawns. Set
+ * `options.tracingDisabled = true` in `SpawnContext.options` to opt out when
+ * conduit is unavailable.
+ *
+ * @task T582
+ */
+import { writeSpanBatchToConduit } from '../shared/conduit-trace-writer.js';
+// ---------------------------------------------------------------------------
+// Processor
+// ---------------------------------------------------------------------------
+/**
+ * CLEO trace processor that persists OpenAI Agents SDK spans to conduit.db.
+ *
+ * Implements the `TracingProcessor` interface from `@openai/agents-core`.
+ * Each `onSpanEnd` call extracts span metadata and enqueues a write to
+ * conduit via the shared `conduit-trace-writer` module. Writes are
+ * fire-and-forget — failures are logged but never propagated to the caller.
+ *
+ * @remarks
+ * `onTraceEnd` performs a batch flush of any buffered spans. Individual
+ * `onSpanEnd` calls also write immediately so spans are not lost if the run
+ * is interrupted.
+ *
+ * @example
+ * ```typescript
+ * import { addTraceProcessor } from '@openai/agents';
+ * import { CleoConduitTraceProcessor } from './tracing.js';
+ *
+ * const processor = new CleoConduitTraceProcessor('T582');
+ * addTraceProcessor(processor);
+ * ```
+ */
+export class CleoConduitTraceProcessor {
+    /** CLEO task ID included in every span event for correlation. */
+    taskId;
+    /** Pending span events buffered within the current trace. */
+    pendingEvents = [];
+    /**
+     * @param taskId - CLEO task ID to attach to every written span.
+     */
+    constructor(taskId) {
+        this.taskId = taskId;
+    }
+    /**
+     * Called when a new trace starts. Resets the pending event buffer.
+     *
+     * @param _trace - The trace that just started (unused).
+     */
+    async onTraceStart(_trace) {
+        this.pendingEvents = [];
+    }
+    /**
+     * Called when a trace ends. Flushes all pending span events to conduit.
+     *
+     * @param _trace - The trace that just ended (unused — spans were captured via `onSpanEnd`).
+     */
+    async onTraceEnd(_trace) {
+        if (this.pendingEvents.length > 0) {
+            await writeSpanBatchToConduit(this.pendingEvents);
+            this.pendingEvents = [];
+        }
+    }
+    /**
+     * Called when a new span starts. No-op — we capture on end to have full timing.
+     *
+     * @param _span - The span that just started (unused).
+     */
+    async onSpanStart(_span) {
+        // Capture on end so startedAt / endedAt are both populated.
+    }
+    /**
+     * Called when a span ends. Serialises and writes the span to conduit.
+     *
+     * @param span - The completed span from the SDK.
+     */
+    async onSpanEnd(span) {
+        const event = this.extractSpanEvent(span);
+        if (event) {
+            this.pendingEvents.push(event);
+            // Also write immediately to survive partial run interruptions.
+            await writeSpanBatchToConduit([event]);
+        }
+    }
+    /**
+     * Called during graceful shutdown. Flushes any remaining pending events.
+     *
+     * @param _timeout - Shutdown timeout in milliseconds (unused).
+     */
+    async shutdown(_timeout) {
+        if (this.pendingEvents.length > 0) {
+            await writeSpanBatchToConduit(this.pendingEvents);
+            this.pendingEvents = [];
+        }
+    }
+    /**
+     * Force-flush all pending span events to conduit immediately.
+     */
+    async forceFlush() {
+        if (this.pendingEvents.length > 0) {
+            await writeSpanBatchToConduit(this.pendingEvents);
+            this.pendingEvents = [];
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Extract a {@link ConduitSpanEvent} from an SDK span, or `null` if the
+     * span cannot be meaningfully serialised.
+     *
+     * @param span - The SDK span to serialise.
+     * @returns A conduit span event or `null`.
+     */
+    extractSpanEvent(span) {
+        const spanId = span.spanId ?? `span-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`;
+        // Guard against malformed/empty spans (e.g. in unit tests with minimal mocks).
+        if (!span.spanData)
+            return null;
+        const data = span.spanData;
+        const spanType = data.type;
+        // Extract agent name from span data shape based on type.
+        let agentName = 'unknown';
+        let handoffTarget;
+        if (data.type === 'agent') {
+            agentName = data.name;
+        }
+        else if (data.type === 'handoff') {
+            agentName = data.from_agent ?? 'unknown';
+            handoffTarget = data.to_agent ?? undefined;
+        }
+        else if (data.type === 'function') {
+            agentName = data.name;
+        }
+        const startTime = span.startedAt ?? new Date().toISOString();
+        const endTime = span.endedAt ?? new Date().toISOString();
+        return {
+            spanId,
+            taskId: this.taskId,
+            agentName,
+            spanType,
+            startTime,
+            endTime,
+            handoffTarget,
+            metadata: {
+                rawSpanData: data,
+            },
+        };
+    }
+}
+//# sourceMappingURL=tracing.js.map

package/dist/providers/openai-sdk/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../../src/providers/openai-sdk/tracing.ts"],"names":[],"mappings":"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"}

package/dist/providers/opencode/adapter.js

@@ -0,0 +1,166 @@
+/**
+ * OpenCode Adapter
+ *
+ * Main CLEOProviderAdapter implementation for OpenCode AI coding assistant.
+ * Provides spawn, hooks, and install capabilities for CLEO integration.
+ *
+ * @task T5240
+ */
+import { exec } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { OpenCodeHookProvider } from './hooks.js';
+import { OpenCodeInstallProvider } from './install.js';
+import { OpenCodeSpawnProvider } from './spawn.js';
+const execAsync = promisify(exec);
+/**
+ * CLEO provider adapter for OpenCode AI coding assistant.
+ *
+ * Bridges CLEO's adapter system with OpenCode's native capabilities:
+ * - Hooks: Maps OpenCode events (session.start, tool.complete, etc.) to CAAMP events
+ * - Spawn: Launches subagent processes via the `opencode` CLI
+ * - Install: Ensures AGENTS.md references for CLEO instruction files
+ *
+ * @remarks
+ * OpenCode is the second-most feature-complete adapter after Claude Code,
+ * supporting 10 canonical events through its JavaScript plugin system,
+ * subagent spawning via the `opencode run` CLI command, and instruction
+ * file management via AGENTS.md. It uniquely supports PreModel via the
+ * `chat.params` event, which allows pre-inference parameter injection.
+ */
+export class OpenCodeAdapter {
+    /** Unique provider identifier. */
+    id = 'opencode';
+    /** Human-readable provider name. */
+    name = 'OpenCode';
+    /** Adapter version string. */
+    version = '1.0.0';
+    /** Declared capabilities for this provider. */
+    capabilities = {
+        supportsHooks: true,
+        // 10/16 canonical events — derived from getProviderHookProfile('opencode') in CAAMP 1.9.1.
+        // PostToolUseFailure, SubagentStart, SubagentStop, Notification, ConfigChange are
+        // not supported by OpenCode's plugin system.
+        supportedHookEvents: [
+            'SessionStart',
+            'SessionEnd',
+            'PromptSubmit',
+            'ResponseComplete',
+            'PreToolUse',
+            'PostToolUse',
+            'PermissionRequest',
+            'PreModel',
+            'PreCompact',
+            'PostCompact',
+        ],
+        supportsSpawn: true,
+        supportsInstall: true,
+        supportsInstructionFiles: true,
+        instructionFilePattern: 'AGENTS.md',
+        supportsContextMonitor: false,
+        supportsStatusline: false,
+        supportsProviderPaths: true,
+        supportsTransport: false,
+        supportsTaskSync: false,
+    };
+    /** Hook provider for CAAMP event mapping via OpenCode's plugin system. */
+    hooks;
+    /** Spawn provider for launching subagent processes via `opencode run`. */
+    spawn;
+    /** Install provider for managing AGENTS.md instruction files. */
+    install;
+    /** Project directory this adapter was initialized with, or null. */
+    projectDir = null;
+    /** Whether {@link initialize} has been called. */
+    initialized = false;
+    constructor() {
+        this.hooks = new OpenCodeHookProvider();
+        this.spawn = new OpenCodeSpawnProvider();
+        this.install = new OpenCodeInstallProvider();
+    }
+    /**
+     * Initialize the adapter for a given project directory.
+     *
+     * Validates the environment by checking for the OpenCode CLI
+     * and OpenCode configuration directory.
+     *
+     * @param projectDir - Root directory of the project
+     */
+    async initialize(projectDir) {
+        this.projectDir = projectDir;
+        this.initialized = true;
+    }
+    /**
+     * Dispose the adapter and clean up resources.
+     *
+     * Unregisters hooks and releases any tracked state.
+     */
+    async dispose() {
+        if (this.hooks.isRegistered()) {
+            await this.hooks.unregisterNativeHooks();
+        }
+        this.initialized = false;
+        this.projectDir = null;
+    }
+    /**
+     * Run a health check to verify OpenCode is accessible.
+     *
+     * Checks:
+     * 1. Adapter has been initialized
+     * 2. OpenCode CLI is available in PATH
+     * 3. .opencode/ configuration directory exists in the project
+     *
+     * @returns Health status with details about each check
+     */
+    async healthCheck() {
+        const details = {};
+        if (!this.initialized) {
+            return {
+                healthy: false,
+                provider: this.id,
+                details: { error: 'Adapter not initialized' },
+            };
+        }
+        // Check OpenCode CLI availability
+        let cliAvailable = false;
+        try {
+            const { stdout } = await execAsync('which opencode');
+            cliAvailable = stdout.trim().length > 0;
+            details.cliPath = stdout.trim();
+        }
+        catch {
+            details.cliAvailable = false;
+        }
+        // Check for OpenCode config directory in the project
+        if (this.projectDir) {
+            const openCodeConfigDir = join(this.projectDir, '.opencode');
+            const configExists = existsSync(openCodeConfigDir);
+            details.configDirExists = configExists;
+        }
+        // Check for OPENCODE_VERSION env var
+        const versionEnvSet = process.env.OPENCODE_VERSION !== undefined;
+        details.versionEnvSet = versionEnvSet;
+        // Healthy if CLI is available (primary requirement)
+        const healthy = cliAvailable;
+        details.cliAvailable = cliAvailable;
+        return {
+            healthy,
+            provider: this.id,
+            details,
+        };
+    }
+    /**
+     * Check whether the adapter has been initialized.
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Get the project directory this adapter was initialized with.
+     */
+    getProjectDir() {
+        return this.projectDir;
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/providers/opencode/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/providers/opencode/adapter.ts"],"names":[],"mappings":"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"}

package/dist/providers/opencode/hooks.js

@@ -0,0 +1,206 @@
+/**
+ * OpenCode Hook Provider
+ *
+ * Maps OpenCode's native hook events to CAAMP canonical hook events.
+ * OpenCode supports 10 of 16 canonical events through its plugin system.
+ *
+ * Event translation uses CAAMP normalizer APIs:
+ * - `toCanonical(nativeName, 'opencode')` for runtime event name resolution
+ * - `getSupportedEvents('opencode')` to enumerate supported canonical events
+ * - `getProviderHookProfile('opencode')` for the full provider profile
+ *
+ * OpenCode uses a JavaScript plugin system with event-prefixed names
+ * (e.g. `event:session.created`) for some hooks and bare names for others.
+ * The map is derived from `getProviderHookProfile('opencode').mappings` in
+ * CAAMP 1.9.1. PostToolUseFailure, SubagentStart, SubagentStop, Notification,
+ * and ConfigChange are not supported by OpenCode.
+ *
+ * @task T164
+ * @epic T134
+ */
+/** CAAMP provider identifier for OpenCode. */
+const PROVIDER_ID = 'opencode';
+/**
+ * Fallback map from OpenCode native event names to CAAMP canonical names.
+ *
+ * Derived from `getProviderHookProfile('opencode').mappings` in CAAMP 1.9.1.
+ * Covers all 10 supported events. PostToolUseFailure, SubagentStart,
+ * SubagentStop, Notification, and ConfigChange are not supported by OpenCode
+ * and are absent from this map.
+ *
+ * OpenCode uses dot-delimited and event-prefixed names (e.g. "event:session.created")
+ * while CAAMP canonical names are PascalCase (e.g. "SessionStart").
+ */
+const OPENCODE_EVENT_MAP = {
+    // CAAMP: toNative('SessionStart',       'opencode') = 'event:session.created'
+    'event:session.created': 'SessionStart',
+    // CAAMP: toNative('SessionEnd',         'opencode') = 'event:session.deleted'
+    'event:session.deleted': 'SessionEnd',
+    // CAAMP: toNative('PromptSubmit',       'opencode') = 'chat.message'
+    'chat.message': 'PromptSubmit',
+    // CAAMP: toNative('ResponseComplete',   'opencode') = 'event:session.idle'
+    'event:session.idle': 'ResponseComplete',
+    // CAAMP: toNative('PreToolUse',         'opencode') = 'tool.execute.before'
+    'tool.execute.before': 'PreToolUse',
+    // CAAMP: toNative('PostToolUse',        'opencode') = 'tool.execute.after'
+    'tool.execute.after': 'PostToolUse',
+    // CAAMP: toNative('PermissionRequest',  'opencode') = 'permission.ask'
+    'permission.ask': 'PermissionRequest',
+    // CAAMP: toNative('PreModel',           'opencode') = 'chat.params'
+    'chat.params': 'PreModel',
+    // CAAMP: toNative('PreCompact',         'opencode') = 'experimental.session.compacting'
+    'experimental.session.compacting': 'PreCompact',
+    // CAAMP: toNative('PostCompact',        'opencode') = 'event:session.compacted'
+    'event:session.compacted': 'PostCompact',
+};
+/**
+ * Hook provider for OpenCode.
+ *
+ * OpenCode registers hooks via its JavaScript plugin system at
+ * `.opencode/plugins/`. Supported handler type: plugin (JavaScript).
+ *
+ * Event mapping is based on `getProviderHookProfile('opencode')` from
+ * CAAMP 1.9.1. Async accessors (`getSupportedCanonicalEvents`,
+ * `getProviderProfile`) call CAAMP directly when available.
+ *
+ * Since hooks are registered through the plugin system (managed by the install
+ * provider), `registerNativeHooks` and `unregisterNativeHooks` track registration
+ * state without performing filesystem operations.
+ *
+ * @remarks
+ * OpenCode uses dot-delimited and `event:`-prefixed event names
+ * (e.g. `event:session.created`, `tool.execute.before`) which differ
+ * significantly from the PascalCase CAAMP canonical names. The static
+ * event map covers all 10 supported events. Async CAAMP accessors
+ * (`getSupportedCanonicalEvents`, `getProviderProfile`, `toNativeEvent`)
+ * call the normalizer directly when available and fall back to the static map.
+ *
+ * @task T164
+ * @epic T134
+ */
+export class OpenCodeHookProvider {
+    /** Whether hooks have been registered for the current session. */
+    registered = false;
+    /**
+     * Map an OpenCode native event name to a CAAMP canonical hook event name.
+     *
+     * Looks up the native event name in the map derived from
+     * `getProviderHookProfile('opencode').mappings` (CAAMP 1.9.1).
+     * Returns null for unsupported events (PostToolUseFailure, SubagentStart,
+     * SubagentStop, Notification, ConfigChange).
+     *
+     * @param providerEvent - OpenCode native event (e.g. "event:session.created", "tool.execute.before")
+     * @returns CAAMP canonical event name, or null if unmapped
+     * @task T164
+     */
+    mapProviderEvent(providerEvent) {
+        return OPENCODE_EVENT_MAP[providerEvent] ?? null;
+    }
+    /**
+     * Register native hooks for a project.
+     *
+     * For OpenCode, hooks are registered via the plugin system
+     * (`.opencode/plugins/`), managed by the install provider.
+     * This method marks hooks as registered without performing filesystem operations.
+     *
+     * Iterating supported events is handled at install time using
+     * `getSupportedCanonicalEvents()` to enumerate all 10 supported hooks.
+     *
+     * @param _projectDir - Project directory (unused; config manages registration)
+     * @task T164
+     */
+    async registerNativeHooks(_projectDir) {
+        this.registered = true;
+    }
+    /**
+     * Unregister native hooks.
+     *
+     * For OpenCode, this is a no-op since hooks are managed through the plugin
+     * system. Unregistration happens via the install provider's uninstall method.
+     *
+     * @task T164
+     */
+    async unregisterNativeHooks() {
+        this.registered = false;
+    }
+    /**
+     * Check whether hooks have been registered via `registerNativeHooks`.
+     */
+    isRegistered() {
+        return this.registered;
+    }
+    /**
+     * Get the native→canonical event mapping for introspection and debugging.
+     *
+     * Returns the map derived from `getProviderHookProfile('opencode').mappings`
+     * (CAAMP 1.9.1). Use `getSupportedCanonicalEvents()` to enumerate canonical
+     * names via live CAAMP APIs.
+     *
+     * @returns Immutable record of native event name → canonical event name
+     */
+    getEventMap() {
+        return { ...OPENCODE_EVENT_MAP };
+    }
+    /**
+     * Enumerate supported canonical events via CAAMP's `getSupportedEvents()`.
+     *
+     * Calls `getSupportedEvents('opencode')` from the CAAMP normalizer to get the
+     * authoritative list. OpenCode supports 10 of 16 canonical events via its
+     * plugin system. Falls back to the values of the static event map when
+     * CAAMP is unavailable at runtime.
+     *
+     * @returns Array of CAAMP canonical event names supported by OpenCode
+     * @task T164
+     */
+    async getSupportedCanonicalEvents() {
+        try {
+            const { getSupportedEvents } = await import('@cleocode/caamp');
+            return getSupportedEvents(PROVIDER_ID);
+        }
+        catch {
+            return [...new Set(Object.values(OPENCODE_EVENT_MAP))];
+        }
+    }
+    /**
+     * Retrieve the full provider hook profile from CAAMP.
+     *
+     * Calls `getProviderHookProfile('opencode')` from the CAAMP normalizer to
+     * get the complete profile: hook system type (`plugin`), config path
+     * (`.opencode/plugins/`), handler types, and all event mappings.
+     * Returns null when CAAMP is unavailable at runtime.
+     *
+     * @returns Provider hook profile or null if CAAMP is unavailable
+     * @task T164
+     */
+    async getProviderProfile() {
+        try {
+            const { getProviderHookProfile } = await import('@cleocode/caamp');
+            return getProviderHookProfile(PROVIDER_ID) ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Translate a CAAMP canonical event to its OpenCode native name via CAAMP.
+     *
+     * Calls `toNative(canonical, 'opencode')` from the CAAMP normalizer.
+     * Returns null for unsupported events or when CAAMP is unavailable.
+     *
+     * @param canonical - CAAMP canonical event name (e.g. "PreToolUse")
+     * @returns OpenCode native event name or null
+     * @task T164
+     */
+    async toNativeEvent(canonical) {
+        try {
+            const { toNative } = await import('@cleocode/caamp');
+            return toNative(canonical, PROVIDER_ID);
+        }
+        catch {
+            // Invert the static map as fallback
+            const entry = Object.entries(OPENCODE_EVENT_MAP).find(([, v]) => v === canonical);
+            return entry?.[0] ?? null;
+        }
+    }
+}
+//# sourceMappingURL=hooks.js.map

package/dist/providers/opencode/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../../src/providers/opencode/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,8CAA8C;AAC9C,MAAM,WAAW,GAAG,UAAmB,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,kBAAkB,GAA2B;IACjD,8EAA8E;IAC9E,uBAAuB,EAAE,cAAc;IACvC,8EAA8E;IAC9E,uBAAuB,EAAE,YAAY;IACrC,qEAAqE;IACrE,cAAc,EAAE,cAAc;IAC9B,2EAA2E;IAC3E,oBAAoB,EAAE,kBAAkB;IACxC,4EAA4E;IAC5E,qBAAqB,EAAE,YAAY;IACnC,2EAA2E;IAC3E,oBAAoB,EAAE,aAAa;IACnC,uEAAuE;IACvE,gBAAgB,EAAE,mBAAmB;IACrC,oEAAoE;IACpE,aAAa,EAAE,UAAU;IACzB,wFAAwF;IACxF,iCAAiC,EAAE,YAAY;IAC/C,gFAAgF;IAChF,yBAAyB,EAAE,aAAa;CACzC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,oBAAoB;IAC/B,kEAAkE;IAC1D,UAAU,GAAG,KAAK,CAAC;IAE3B;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,aAAqB;QACpC,OAAO,kBAAkB,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC;IACnD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,mBAAmB,CAAC,WAAmB;QAC3C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACzB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,qBAAqB;QACzB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;;;;;;;OAQG;IACH,WAAW;QACT,OAAO,EAAE,GAAG,kBAAkB,EAAE,CAAC;IACnC,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,2BAA2B;QAC/B,IAAI,CAAC;YACH,MAAM,EAAE,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;YAC/D,OAAO,kBAAkB,CAAC,WAAW,CAAa,CAAC;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,kBAAkB;QACtB,IAAI,CAAC;YACH,MAAM,EAAE,sBAAsB,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;YACnE,OAAO,sBAAsB,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,aAAa,CAAC,SAAiB;QACnC,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;YACrD,OAAO,QAAQ,CAAC,SAA2C,EAAE,WAAW,CAAC,CAAC;QAC5E,CAAC;QAAC,MAAM,CAAC;YACP,oCAAoC;YACpC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;YAClF,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QAC5B,CAAC;IACH,CAAC;CACF"}

package/dist/providers/opencode/index.js

@@ -0,0 +1,37 @@
+/**
+ * @packageDocumentation
+ *
+ * CLEO provider adapter for OpenCode AI coding assistant.
+ * Default export is the adapter class for dynamic loading by AdapterManager.
+ *
+ * @task T5240
+ */
+import { OpenCodeAdapter } from './adapter.js';
+export { OpenCodeAdapter } from './adapter.js';
+export { OpenCodeHookProvider } from './hooks.js';
+export { OpenCodeInstallProvider } from './install.js';
+export { OpenCodeSpawnProvider } from './spawn.js';
+export default OpenCodeAdapter;
+/**
+ * Factory function for creating adapter instances.
+ * Used by AdapterManager's dynamic import fallback.
+ *
+ * @remarks
+ * This is the primary entry point for dynamic adapter loading.
+ * AdapterManager calls this function when it resolves the opencode
+ * provider via its import-based discovery mechanism.
+ *
+ * @returns A new {@link OpenCodeAdapter} instance ready for initialization
+ *
+ * @example
+ * ```typescript
+ * import { createAdapter } from '@cleocode/adapters/providers/opencode';
+ *
+ * const adapter = createAdapter();
+ * await adapter.initialize('/path/to/project');
+ * ```
+ */
+export function createAdapter() {
+    return new OpenCodeAdapter();
+}
+//# sourceMappingURL=index.js.map

package/dist/providers/opencode/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/providers/opencode/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD,eAAe,eAAe,CAAC;AAE/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,eAAe,EAAE,CAAC;AAC/B,CAAC"}