@cleocode/adapters 2026.4.91 → 2026.4.94

package/src/providers/openai-sdk/spawn.ts

@@ -1,27 +1,33 @@
 /**
- * OpenAI Agents SDK spawn provider.
+ * OpenAI SDK spawn provider — Vercel AI SDK edition.
+ *
+ * Implements `AdapterSpawnProvider` using the Vercel AI SDK
+ * (`ai` v6 + `@ai-sdk/openai`) instead of the legacy `@openai/agents`. CLEO
+ * retains its own orchestration (handoff topology, guardrails, tracing); the
+ * SDK is strictly the LLM bridge.
  *
- * Implements `AdapterSpawnProvider` using the `@openai/agents` SDK runner.
  * Unlike the Claude Code provider (detached fire-and-forget), this provider
- * awaits the run and returns `status: 'completed'` or `status: 'failed'`
- * so the orchestrator receives rich output immediately.
+ * awaits the run and returns `status: 'completed'` or `status: 'failed'` so
+ * the orchestrator receives rich output immediately.
  *
  * Key features:
  * - Tier-based model selection (lead → gpt-4.1, worker → gpt-4.1-mini)
- * - Handoff topology built from `SpawnContext.options.handoffs`
- * - CLEO path ACL guardrails applied at input stage
+ * - Handoff topology built from `SpawnContext.options.handoffs` (CLEO-native)
+ * - CLEO path ACL guardrails evaluated before the model call
  * - Default-on tracing via `CleoConduitTraceProcessor`
  * - CANT prompt enrichment (best-effort, same as Claude Code provider)
  *
- * @task T582
+ * @task T582 (original)
+ * @task T933 (SDK consolidation — Vercel AI SDK migration)
+ * @see ADR-052 — SDK consolidation decision
  */
 
 import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
 import { getErrorMessage } from '@cleocode/contracts';
-import { addTraceProcessor, OpenAIProvider, Runner, setTracingDisabled } from '@openai/agents';
 import { mapSdkRunOutcome } from '../shared/sdk-result-mapper.js';
-import { buildDefaultGuardrails } from './guardrails.js';
-import { buildAgentTopology } from './handoff.js';
+import { buildDefaultGuardrails, evaluateGuardrails } from './guardrails.js';
+import { buildAgentTopology, type CleoAgent } from './handoff.js';
+import type { CleoSpan, CleoTraceProcessor } from './tracing.js';
 import { CleoConduitTraceProcessor } from './tracing.js';
 
 // ---------------------------------------------------------------------------
@@ -68,7 +74,7 @@ export interface OpenAiSdkSpawnOptions {
 
   /**
    * Tool name allowlist. Tools not in this list are documented but not enforced
-   * (enforcement is structural via the `tools` array on the Agent).
+   * (enforcement is structural via CLEO orchestration).
    *
    * @defaultValue `[]` (all tools allowed)
    */
@@ -94,23 +100,88 @@ export interface OpenAiSdkSpawnOptions {
 const MODEL_LEAD = 'gpt-4.1';
 const MODEL_WORKER = 'gpt-4.1-mini';
 
+// ---------------------------------------------------------------------------
+// Trace processor registry (module-scoped)
+// ---------------------------------------------------------------------------
+
+/** Registered trace processors that receive span events across the module. */
+const registeredProcessors: CleoTraceProcessor[] = [];
+
+/** Module-level flag that disables span dispatch globally. */
+let tracingGlobalDisabled = false;
+
+/**
+ * Register a CLEO trace processor. Mirrors `addTraceProcessor` from the
+ * legacy `@openai/agents` surface so existing consumers continue to work.
+ *
+ * @param processor - Processor to register.
+ */
+export function registerTraceProcessor(processor: CleoTraceProcessor): void {
+  registeredProcessors.push(processor);
+}
+
+/**
+ * Remove a previously registered trace processor.
+ *
+ * @param processor - Processor to remove.
+ */
+export function unregisterTraceProcessor(processor: CleoTraceProcessor): void {
+  const idx = registeredProcessors.indexOf(processor);
+  if (idx >= 0) {
+    registeredProcessors.splice(idx, 1);
+  }
+}
+
+/**
+ * Enable or disable global tracing. Equivalent to `setTracingDisabled` from
+ * the legacy `@openai/agents` surface.
+ *
+ * @param disabled - When true, no spans are emitted.
+ */
+export function setTracingDisabled(disabled: boolean): void {
+  tracingGlobalDisabled = disabled;
+}
+
+/**
+ * Dispatch a span to every registered trace processor, subject to the global
+ * `tracingGlobalDisabled` flag.
+ *
+ * @param span - Span event to dispatch.
+ */
+async function emitSpan(span: CleoSpan): Promise<void> {
+  if (tracingGlobalDisabled) return;
+  for (const processor of registeredProcessors) {
+    try {
+      await processor.onSpanEnd(span);
+    } catch {
+      // Tracing failures must never break a run.
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Provider
 // ---------------------------------------------------------------------------
 
 /**
- * Spawn provider for the OpenAI Agents SDK.
+ * Spawn provider for the Vercel AI SDK (OpenAI flavour).
  *
- * Spawns SDK-backed agent runs for a given `SpawnContext`. The run is
- * awaited synchronously and the result mapped to a `SpawnResult` with
- * `status: 'completed'` or `status: 'failed'`. In-flight runs are tracked
- * by instance ID so `listRunning()` and `terminate()` work correctly.
+ * Spawns SDK-backed agent runs for a given `SpawnContext`. The run is awaited
+ * synchronously and the result mapped to a `SpawnResult` with
+ * `status: 'completed'` or `status: 'failed'`. In-flight runs are tracked by
+ * instance ID so `listRunning()` and `terminate()` work correctly.
  *
  * @remarks
- * The provider creates a fresh `Runner` per spawn so that `RunConfig`
- * settings do not bleed across parallel spawns. Trace processors are
- * registered globally via `addTraceProcessor` and removed by disabling
- * tracing when the option is set.
+ * Handoff topology is resolved by this provider, not the SDK. When the entry
+ * agent is a lead with workers, the provider:
+ *
+ *   1. Runs the lead agent's `generateText` with the enriched prompt.
+ *   2. For each worker listed in handoffs, runs a sequential `generateText`
+ *      using the worker's archetype model, passing the lead's output as the
+ *      worker prompt. Results are concatenated.
+ *
+ * This preserves the visible behaviour of the legacy `@openai/agents` runner
+ * while keeping CLEO as the orchestration owner.
  *
  * @example
  * ```typescript
@@ -139,7 +210,7 @@ export class OpenAiSdkSpawnProvider implements AdapterSpawnProvider {
   }
 
   /**
-   * Spawn a subagent via the OpenAI Agents SDK runner.
+   * Spawn a subagent via the Vercel AI SDK.
    *
    * Awaits the run to completion and returns a fully-resolved `SpawnResult`.
    *
@@ -184,38 +255,45 @@ export class OpenAiSdkSpawnProvider implements AdapterSpawnProvider {
       });
 
       // Register trace processor globally (default-on).
-      // The SDK uses global processor registration via addTraceProcessor().
       let traceProcessor: CleoConduitTraceProcessor | undefined;
+      const previousTracingDisabled = tracingGlobalDisabled;
       if (!opts.tracingDisabled) {
         traceProcessor = new CleoConduitTraceProcessor(context.taskId);
-        addTraceProcessor(traceProcessor);
+        registerTraceProcessor(traceProcessor);
+        setTracingDisabled(false);
       } else {
         setTracingDisabled(true);
       }
 
-      // Build OpenAI model provider and runner.
-      const modelProvider = new OpenAIProvider();
-      const runner = new Runner({ modelProvider });
-
-      // Run the agent — no extra options needed beyond what is set on the runner.
-      const runResult = await runner.run(agent, finalPrompt);
-
-      // Restore tracing state if we disabled it for this spawn.
-      if (opts.tracingDisabled) {
-        setTracingDisabled(false);
+      try {
+        // Evaluate guardrails before any model call. A tripped guardrail
+        // aborts the run with a structured failure.
+        const guardResult = await evaluateGuardrails(agent.inputGuardrails ?? [], finalPrompt);
+        if (guardResult.tripwireTriggered) {
+          this.runningInstances.delete(instanceId);
+          return mapSdkRunOutcome(instanceId, context.taskId, 'openai-sdk', startTime, {
+            finalOutput: '',
+            succeeded: false,
+            errorMessage: `guardrail tripped: ${JSON.stringify(guardResult.outputInfo)}`,
+          });
+        }
+
+        // Run the lead/worker topology.
+        const runOutput = await runAgentTopology(agent, finalPrompt, emitSpan);
+
+        this.runningInstances.delete(instanceId);
+
+        return mapSdkRunOutcome(instanceId, context.taskId, 'openai-sdk', startTime, {
+          finalOutput: runOutput,
+          succeeded: true,
+        });
+      } finally {
+        // Restore previous tracing state and unregister this run's processor.
+        if (traceProcessor) {
+          unregisterTraceProcessor(traceProcessor);
+        }
+        setTracingDisabled(previousTracingDisabled);
       }
-
-      const finalOutput =
-        typeof runResult.finalOutput === 'string'
-          ? runResult.finalOutput
-          : JSON.stringify(runResult.finalOutput);
-
-      this.runningInstances.delete(instanceId);
-
-      return mapSdkRunOutcome(instanceId, context.taskId, 'openai-sdk', startTime, {
-        finalOutput,
-        succeeded: true,
-      });
     } catch (error: unknown) {
       this.runningInstances.delete(instanceId);
 
@@ -245,9 +323,9 @@ export class OpenAiSdkSpawnProvider implements AdapterSpawnProvider {
   /**
    * Terminate a running spawn by instance ID.
    *
-   * The OpenAI SDK runner does not support external termination of in-flight
-   * runs; this method removes the instance from the tracking set so it will
-   * no longer appear in `listRunning()`.
+   * The Vercel AI SDK does not support external termination of in-flight
+   * requests; this method removes the instance from the tracking set so it
+   * will no longer appear in `listRunning()`.
    *
    * @param instanceId - ID of the spawn instance to terminate.
    */
@@ -298,3 +376,90 @@ export class OpenAiSdkSpawnProvider implements AdapterSpawnProvider {
     return tier === 'worker' ? MODEL_WORKER : MODEL_LEAD;
   }
 }
+
+// ---------------------------------------------------------------------------
+// Topology runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a CLEO agent topology against the Vercel AI SDK.
+ *
+ * Runs the entry agent via `generateText`. When the entry agent declares
+ * handoffs, each worker is executed sequentially with the lead's output as
+ * input and the concatenated result returned.
+ *
+ * @param agent - Entry agent descriptor.
+ * @param userPrompt - Enriched user prompt.
+ * @param emit - Span emitter invoked after every agent run.
+ * @returns Concatenated assistant output.
+ */
+async function runAgentTopology(
+  agent: CleoAgent,
+  userPrompt: string,
+  emit: (span: CleoSpan) => Promise<void>,
+): Promise<string> {
+  const { createOpenAI } = await import('@ai-sdk/openai');
+  const { generateText } = await import('ai');
+
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    throw new Error('OPENAI_API_KEY is not set — OpenAI SDK provider cannot run');
+  }
+
+  const openai = createOpenAI({ apiKey });
+
+  // Run the entry agent.
+  const startedAt = new Date().toISOString();
+  const leadResult = await generateText({
+    model: openai(agent.model),
+    system: agent.instructions,
+    prompt: userPrompt,
+  });
+  const leadText = (leadResult.text ?? '').trim();
+  const leadEnd = new Date().toISOString();
+
+  await emit({
+    spanId: `${agent.name}-${Date.now()}`,
+    startedAt,
+    endedAt: leadEnd,
+    spanData: { type: 'agent', name: agent.name },
+  });
+
+  // When there are no handoffs, return the lead output directly.
+  const workers = agent.handoffs ?? [];
+  if (workers.length === 0) {
+    return leadText;
+  }
+
+  // Sequential handoff execution. Each worker receives the lead output as
+  // input, and the concatenated worker outputs become the final run output.
+  const workerOutputs: string[] = [];
+  for (const worker of workers) {
+    const handoffStart = new Date().toISOString();
+    await emit({
+      spanId: `handoff-${agent.name}-${worker.name}-${Date.now()}`,
+      startedAt: handoffStart,
+      endedAt: handoffStart,
+      spanData: { type: 'handoff', from_agent: agent.name, to_agent: worker.name },
+    });
+
+    const workerStart = new Date().toISOString();
+    const workerResult = await generateText({
+      model: openai(worker.model),
+      system: worker.instructions,
+      prompt: leadText,
+    });
+    const workerEnd = new Date().toISOString();
+
+    await emit({
+      spanId: `${worker.name}-${Date.now()}`,
+      startedAt: workerStart,
+      endedAt: workerEnd,
+      spanData: { type: 'agent', name: worker.name },
+    });
+
+    workerOutputs.push(`[${worker.name}] ${(workerResult.text ?? '').trim()}`);
+  }
+
+  return [leadText, ...workerOutputs].join('\n\n');
+}

package/src/providers/openai-sdk/tracing.ts

@@ -1,32 +1,115 @@
 /**
- * OpenAI Agents SDK trace processor that writes spans to conduit.db.
+ * CLEO 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.
+ * `CleoConduitTraceProcessor` implements a CLEO-native tracing processor
+ * interface that records spans emitted by the OpenAI SDK adapter. Post T933
+ * (ADR-052 — Vercel AI SDK consolidation) the processor no longer implements
+ * `@openai/agents` type surfaces; instead it consumes `CleoSpan` events
+ * produced by `OpenAiSdkSpawnProvider` during a run.
  *
  * 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
+ * @task T582 (original)
+ * @task T933 (SDK consolidation — provider-neutral rewrite)
  */
 
-import type { Span, SpanData, Trace, TracingProcessor } from '@openai/agents';
 import type { ConduitSpanEvent } from '../shared/conduit-trace-writer.js';
 import { writeSpanBatchToConduit } from '../shared/conduit-trace-writer.js';
 
+// ---------------------------------------------------------------------------
+// CLEO-native span shape
+// ---------------------------------------------------------------------------
+
+/** Span category emitted by the OpenAI SDK adapter. */
+export type CleoSpanKind = 'agent' | 'handoff' | 'function' | 'model' | 'custom';
+
+/**
+ * CLEO-native span payload produced by the OpenAI SDK adapter.
+ *
+ * @remarks
+ * Intentionally mirrors the subset of `@openai/agents` span data CLEO
+ * actually consumed, rebuilt as a provider-neutral record.
+ */
+export interface CleoSpan {
+  /** Deterministic span identifier. */
+  spanId: string;
+  /** ISO timestamp when the span started. */
+  startedAt?: string;
+  /** ISO timestamp when the span ended. */
+  endedAt?: string;
+  /** Structured span data (type discriminates payload shape). */
+  spanData?: CleoSpanData;
+}
+
+/** Agent-kind span payload. */
+export interface CleoAgentSpanData {
+  type: 'agent';
+  name: string;
+}
+
+/** Handoff-kind span payload (agent delegation). */
+export interface CleoHandoffSpanData {
+  type: 'handoff';
+  from_agent?: string;
+  to_agent?: string;
+}
+
+/** Function-kind span payload (tool invocation). */
+export interface CleoFunctionSpanData {
+  type: 'function';
+  name: string;
+}
+
+/** Catch-all for future span kinds. */
+export interface CleoGenericSpanData {
+  type: Exclude<CleoSpanKind, 'agent' | 'handoff' | 'function'>;
+  [key: string]: unknown;
+}
+
+/** Tagged union of all span payloads. */
+export type CleoSpanData =
+  | CleoAgentSpanData
+  | CleoHandoffSpanData
+  | CleoFunctionSpanData
+  | CleoGenericSpanData;
+
+/** CLEO-native trace envelope — currently opaque to the processor. */
+export interface CleoTrace {
+  /** Trace identifier. */
+  traceId?: string;
+  /** Free-form metadata. */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * CLEO-native trace processor contract.
+ *
+ * @remarks
+ * Replaces `TracingProcessor` from `@openai/agents`. The shape is compatible
+ * with the legacy interface so downstream consumers can continue to invoke
+ * the same methods.
+ */
+export interface CleoTraceProcessor {
+  onTraceStart(trace: CleoTrace): Promise<void>;
+  onTraceEnd(trace: CleoTrace): Promise<void>;
+  onSpanStart(span: CleoSpan): Promise<void>;
+  onSpanEnd(span: CleoSpan): Promise<void>;
+  shutdown(timeout?: number): Promise<void>;
+  forceFlush(): Promise<void>;
+}
+
 // ---------------------------------------------------------------------------
 // Processor
 // ---------------------------------------------------------------------------
 
 /**
- * CLEO trace processor that persists OpenAI Agents SDK spans to conduit.db.
+ * CLEO trace processor that persists OpenAI SDK adapter 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.
+ * 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
@@ -35,14 +118,14 @@ import { writeSpanBatchToConduit } from '../shared/conduit-trace-writer.js';
  *
  * @example
  * ```typescript
- * import { addTraceProcessor } from '@openai/agents';
+ * import { registerTraceProcessor } from './spawn.js';
  * import { CleoConduitTraceProcessor } from './tracing.js';
  *
  * const processor = new CleoConduitTraceProcessor('T582');
- * addTraceProcessor(processor);
+ * registerTraceProcessor(processor);
  * ```
  */
-export class CleoConduitTraceProcessor implements TracingProcessor {
+export class CleoConduitTraceProcessor implements CleoTraceProcessor {
   /** CLEO task ID included in every span event for correlation. */
   private readonly taskId: string;
 
@@ -61,7 +144,7 @@ export class CleoConduitTraceProcessor implements TracingProcessor {
    *
    * @param _trace - The trace that just started (unused).
    */
-  async onTraceStart(_trace: Trace): Promise<void> {
+  async onTraceStart(_trace: CleoTrace): Promise<void> {
     this.pendingEvents = [];
   }
 
@@ -70,7 +153,7 @@ export class CleoConduitTraceProcessor implements TracingProcessor {
    *
    * @param _trace - The trace that just ended (unused — spans were captured via `onSpanEnd`).
    */
-  async onTraceEnd(_trace: Trace): Promise<void> {
+  async onTraceEnd(_trace: CleoTrace): Promise<void> {
     if (this.pendingEvents.length > 0) {
       await writeSpanBatchToConduit(this.pendingEvents);
       this.pendingEvents = [];
@@ -82,16 +165,16 @@ export class CleoConduitTraceProcessor implements TracingProcessor {
    *
    * @param _span - The span that just started (unused).
    */
-  async onSpanStart(_span: Span<SpanData>): Promise<void> {
+  async onSpanStart(_span: CleoSpan): Promise<void> {
     // 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.
+   * @param span - The completed span from the adapter.
    */
-  async onSpanEnd(span: Span<SpanData>): Promise<void> {
+  async onSpanEnd(span: CleoSpan): Promise<void> {
     const event = this.extractSpanEvent(span);
     if (event) {
       this.pendingEvents.push(event);
@@ -127,13 +210,13 @@ export class CleoConduitTraceProcessor implements TracingProcessor {
   // ---------------------------------------------------------------------------
 
   /**
-   * Extract a {@link ConduitSpanEvent} from an SDK span, or `null` if the
+   * Extract a {@link ConduitSpanEvent} from an adapter span, or `null` if the
    * span cannot be meaningfully serialised.
    *
-   * @param span - The SDK span to serialise.
+   * @param span - The adapter span to serialise.
    * @returns A conduit span event or `null`.
    */
-  private extractSpanEvent(span: Span<SpanData>): ConduitSpanEvent | null {
+  private extractSpanEvent(span: CleoSpan): ConduitSpanEvent | null {
     const spanId =
       span.spanId ?? `span-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`;
 

package/src/providers/opencode/install.ts

@@ -10,9 +10,17 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+import { getCleoTemplatesTildePath } from '../shared/paths.js';
 
-/** Lines that should appear in AGENTS.md to reference CLEO. */
-const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
+/**
+ * Lines that should appear in AGENTS.md to reference CLEO.
+ * The CLEO-INJECTION.md path is resolved dynamically to support non-default
+ * XDG / OS installation locations (T916).
+ */
+const INSTRUCTION_REFERENCES = [
+  `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`,
+  '@.cleo/memory-bridge.md',
+];
 
 /**
  * Install provider for OpenCode.

package/src/providers/opencode/spawn.ts

@@ -16,6 +16,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
+import { getCleoTemplatesTildePath } from '../shared/paths.js';
 
 const execAsync = promisify(exec);
 
@@ -95,7 +96,7 @@ async function ensureSubagentDefinition(
       'You are a CLEO subagent executing a delegated task.',
       'Follow the CLEO protocol and complete the assigned work.',
       '',
-      '@~/.cleo/templates/CLEO-INJECTION.md',
+      `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`,
     ].join('\n');
 
   const content = buildOpenCodeAgentMarkdown(description, instructions);

package/src/providers/pi/install.ts

@@ -19,9 +19,17 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+import { getCleoTemplatesTildePath } from '../shared/paths.js';
 
-/** Lines that should appear in AGENTS.md to reference CLEO. */
-const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
+/**
+ * Lines that should appear in AGENTS.md to reference CLEO.
+ * The CLEO-INJECTION.md path is resolved dynamically to support non-default
+ * XDG / OS installation locations (T916).
+ */
+const INSTRUCTION_REFERENCES = [
+  `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`,
+  '@.cleo/memory-bridge.md',
+];
 
 /**
  * Resolve the Pi global state root directory.

package/src/providers/shared/paths.ts

@@ -0,0 +1,79 @@
+/**
+ * Path utilities for adapter install providers.
+ *
+ * These helpers mirror the equivalent functions in `@cleocode/core/paths`
+ * but are duplicated here to avoid a circular dependency
+ * (`@cleocode/core` → `@cleocode/adapters` → `@cleocode/core`).
+ *
+ * @remarks
+ * Keep the implementation in sync with `getCleoTemplatesTildePath` in
+ * `packages/core/src/paths.ts` if the logic ever changes.
+ *
+ * @task T916
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Resolve the XDG / OS-appropriate global CLEO data directory.
+ *
+ * Respects `CLEO_HOME` env var; otherwise uses the platform default:
+ * - Linux:   `~/.local/share/cleo`
+ * - macOS:   `~/Library/Application Support/cleo`
+ * - Windows: `%LOCALAPPDATA%\cleo\Data` (approximate)
+ *
+ * @returns Absolute path to the CLEO data directory
+ *
+ * @internal
+ */
+function getAdapterCleoHome(): string {
+  if (process.env['CLEO_HOME']) {
+    return process.env['CLEO_HOME'];
+  }
+  const home = homedir();
+  if (process.platform === 'darwin') {
+    return join(home, 'Library', 'Application Support', 'cleo');
+  }
+  if (process.platform === 'win32') {
+    const localAppData = process.env['LOCALAPPDATA'];
+    if (localAppData) {
+      return join(localAppData, 'cleo', 'Data');
+    }
+    return join(home, 'AppData', 'Local', 'cleo', 'Data');
+  }
+  // Linux / XDG
+  const xdgData = process.env['XDG_DATA_HOME'];
+  if (xdgData) {
+    return join(xdgData, 'cleo');
+  }
+  return join(home, '.local', 'share', 'cleo');
+}
+
+/**
+ * Get the CLEO templates directory as a tilde-prefixed path for use in
+ * `@` references (AGENTS.md, CLAUDE.md, etc.). Cross-platform: replaces
+ * the user's home directory with `~` so the reference works when loaded
+ * by LLM providers that resolve `~` at runtime.
+ *
+ * @returns Tilde-prefixed path like `"~/.local/share/cleo/templates"` on Linux,
+ *   `"~/Library/Application Support/cleo/templates"` on macOS, etc.
+ *
+ * @example
+ * ```typescript
+ * const ref = `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`;
+ * // "@~/.local/share/cleo/templates/CLEO-INJECTION.md"  (Linux)
+ * ```
+ *
+ * @task T916
+ */
+export function getCleoTemplatesTildePath(): string {
+  const absPath = join(getAdapterCleoHome(), 'templates');
+  const home = homedir();
+  if (absPath.startsWith(home)) {
+    // Always use forward slash after tilde for cross-platform @-reference resolution
+    const relative = absPath.slice(home.length).replace(/\\/g, '/');
+    return `~${relative}`;
+  }
+  return absPath;
+}