@gakim-digital/dexter-bridge 0.5.21 → 0.11.0

package/src/providers/codexStructuredOutput.js

@@ -1,7 +1,67 @@
+import { createHash } from 'node:crypto';
+import { jsonrepair } from 'jsonrepair';
+import {
+  assertOutcomeResponseContract,
+  normalizeStructuredResponseContract,
+  STRUCTURED_RESPONSE_CONTRACTS,
+} from '../protocol.js';
+
+export { STRUCTURED_RESPONSE_CONTRACTS } from '../protocol.js';
+
 function isRecord(value) {
   return value && typeof value === 'object' && !Array.isArray(value);
 }
 
+const CODEX_TRANSPORT_ERROR_CODES = new Set([
+  'CODEX_STRUCTURED_OUTPUT_MALFORMED',
+  'CODEX_STRUCTURED_OUTPUT_INVALID',
+  'CODEX_TOOL_ARGUMENTS_TRANSPORT_INVALID',
+  'CODEX_TOOL_ARGUMENTS_MALFORMED',
+  'CODEX_TOOL_ARGUMENTS_NOT_OBJECT',
+  'APP_HARNESS_RESULT_INVALID',
+]);
+
+function sha256(value) {
+  return createHash('sha256')
+    .update(String(value || ''))
+    .digest('hex');
+}
+
+function diagnosticPreview(value, limit = 1_000) {
+  return String(value || '')
+    .slice(0, limit)
+    .replace(
+      /((?:api[-_]?key|authorization|bearer|secret|password|token|credential)(?:\\?"?\s*[:=]\s*\\?"?))[^,}\n"]+/gi,
+      '$1[redacted]',
+    );
+}
+
+function transportError(code, message, details = {}) {
+  return Object.assign(new Error(message), {
+    code,
+    retryable: true,
+    codexTransportRecoverable: true,
+    ...details,
+  });
+}
+
+function parseJsonObject(source) {
+  try {
+    return JSON.parse(source);
+  } catch (cause) {
+    const trimmed = String(source || '').trim();
+    const completeContainer =
+      (trimmed.startsWith('{') && trimmed.endsWith('}'))
+      || (trimmed.startsWith('[') && trimmed.endsWith(']'));
+    if (!completeContainer) throw cause;
+    try {
+      return JSON.parse(jsonrepair(trimmed));
+    } catch {
+      throw cause;
+    }
+  }
+}
+
 function finiteInteger(value) {
   const parsed = Number(value);
   return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined;
@@ -36,7 +96,7 @@ function toolNames(outputSchema) {
  * tool catalog remains in the prompt and the server validates decoded arguments
  * before execution.
  */
-export function codexTransportOutputSchema(outputSchema) {
+export function codexTransportOutputSchema(outputSchema, { toolName, requireSingleToolCall = false } = {}) {
   if (!isRecord(outputSchema)) {
     throw new Error('Codex model turn requires an output schema.');
   }
@@ -47,7 +107,8 @@ export function codexTransportOutputSchema(outputSchema) {
     throw new Error('Codex model turn output schema is missing its response envelope.');
   }
 
-  const names = toolNames(outputSchema);
+  const availableNames = toolNames(outputSchema);
+  const names = typeof toolName === 'string' && availableNames.includes(toolName) ? [toolName] : availableNames;
   const minItems = finiteInteger(sourceToolCalls.minItems);
   const maxItems = finiteInteger(sourceToolCalls.maxItems);
   const finishReasonEnum = Array.isArray(sourceFinishReason.enum)
@@ -60,8 +121,12 @@ export function codexTransportOutputSchema(outputSchema) {
       text: { type: 'string' },
       toolCalls: {
         type: 'array',
-        ...(minItems === undefined ? {} : { minItems }),
-        ...(maxItems === undefined ? {} : { maxItems }),
+        ...(requireSingleToolCall
+          ? { minItems: 1, maxItems: 1 }
+          : {
+              ...(minItems === undefined ? {} : { minItems }),
+              ...(maxItems === undefined ? {} : { maxItems }),
+            }),
         items: {
           type: 'object',
           properties: {
@@ -82,9 +147,11 @@ export function codexTransportOutputSchema(outputSchema) {
       },
       finishReason: {
         type: 'string',
-        enum: finishReasonEnum.length
-          ? finishReasonEnum
-          : ['tool_calls', 'stop', 'length'],
+        enum: requireSingleToolCall
+          ? ['tool_calls']
+          : finishReasonEnum.length
+            ? finishReasonEnum
+            : ['tool_calls', 'stop', 'length'],
       },
     },
     required: ['text', 'toolCalls', 'finishReason'],
@@ -92,6 +159,22 @@ export function codexTransportOutputSchema(outputSchema) {
   };
 }
 
+export function codexStructuredOutputSchema(
+  outputSchema,
+  {
+    responseContract = STRUCTURED_RESPONSE_CONTRACTS.MODEL_TURN,
+    toolName,
+    requireSingleToolCall = false,
+  } = {},
+) {
+  return normalizeStructuredResponseContract(responseContract) === STRUCTURED_RESPONSE_CONTRACTS.OUTCOME
+    ? assertOutcomeResponseContract(responseContract, outputSchema)
+    : codexTransportOutputSchema(outputSchema, {
+        toolName,
+        requireSingleToolCall,
+      });
+}
+
 export function codexTransportPrompt(prompt) {
   return [
     String(prompt || ''),
@@ -99,36 +182,137 @@ export function codexTransportPrompt(prompt) {
     'Codex structured-output transport:',
     'In the final JSON response, encode each toolCalls[].arguments value as a JSON string.',
     'The decoded string must be one JSON object matching the exact selected tool schema in the Tools catalog.',
+    'Keep large code mutations bounded: prefer one cohesive file per tool call and continue remaining files in later model turns.',
     'Do not omit the id, name, arguments, text, toolCalls, or finishReason fields.',
   ].join('\n');
 }
 
+export function codexStructuredOutputPrompt(
+  prompt,
+  responseContract = STRUCTURED_RESPONSE_CONTRACTS.MODEL_TURN,
+) {
+  return normalizeStructuredResponseContract(responseContract) === STRUCTURED_RESPONSE_CONTRACTS.OUTCOME
+    ? String(prompt || '')
+    : codexTransportPrompt(prompt);
+}
+
+export function codexTransportCorrectionPrompt(error) {
+  const callNumber = Number.isInteger(error?.toolCallIndex) ? error.toolCallIndex + 1 : 1;
+  const toolName = typeof error?.toolName === 'string' && error.toolName ? ` for the "${error.toolName}" tool` : '';
+  return [
+    'Transport correction only.',
+    `Your previous structured response was rejected before any tool executed because tool call ${callNumber}${toolName} could not be decoded.`,
+    ...(typeof error?.parseMessage === 'string' && error.parseMessage ? [`Parser error: ${error.parseMessage}`] : []),
+    'Regenerate only the same intended tool call. Do not redesign, reread files, source images, or choose a different action.',
+    'If the intended call contains source code, return one cohesive file mutation only; later files can be sent in later model turns.',
+    'Return exactly one JSON response object with text:"", one toolCalls item, and finishReason:"tool_calls".',
+    'toolCalls[0].arguments must be a JSON string produced by JSON.stringify on one argument object.',
+    'Escape every quote, backslash, newline, and control character inside that string. Do not use markdown or commentary.',
+  ].join('\n');
+}
+
+export function codexStructuredOutputCorrectionPrompt(
+  error,
+  responseContract = STRUCTURED_RESPONSE_CONTRACTS.MODEL_TURN,
+) {
+  if (normalizeStructuredResponseContract(responseContract) !== STRUCTURED_RESPONSE_CONTRACTS.OUTCOME) {
+    return codexTransportCorrectionPrompt(error);
+  }
+  return [
+    'Transport correction only.',
+    'Your previous harness outcome response could not be decoded.',
+    ...(typeof error?.parseMessage === 'string' && error.parseMessage
+      ? [`Parser error: ${error.parseMessage}`]
+      : []),
+    'Continue from the existing workspace. Do not redesign or repeat completed work.',
+    'Return exactly one JSON outcome object with status, summary, checks, and blockedReason.',
+    'Do not use markdown or a model-turn toolCalls envelope.',
+  ].join('\n');
+}
+
+export function isCodexTransportRecoverableError(error) {
+  return Boolean(error?.codexTransportRecoverable === true || CODEX_TRANSPORT_ERROR_CODES.has(error?.code));
+}
+
+export function codexTransportErrorDiagnostics(error) {
+  return {
+    code: error?.code,
+    toolCallIndex: error?.toolCallIndex,
+    toolName: error?.toolName,
+    argumentsLength: error?.argumentsLength,
+    argumentsSha256: error?.argumentsSha256,
+    argumentsPreview: error?.argumentsPreview,
+    outputLength: error?.outputLength,
+    outputSha256: error?.outputSha256,
+    outputPreview: error?.outputPreview,
+    parseMessage: error?.parseMessage,
+  };
+}
+
 export function decodeCodexTransportOutput(text) {
+  const source = String(text || '').trim();
+  const outputDiagnostics = {
+    outputLength: source.length,
+    outputSha256: sha256(source),
+    outputPreview: diagnosticPreview(source),
+  };
   let parsed;
   try {
-    parsed = JSON.parse(String(text || '').trim());
-  } catch {
-    throw new Error('Codex returned malformed structured output.');
+    parsed = parseJsonObject(source);
+  } catch (cause) {
+    throw transportError('CODEX_STRUCTURED_OUTPUT_MALFORMED', 'Codex returned malformed structured output.', {
+      ...outputDiagnostics,
+      parseMessage: cause instanceof Error ? cause.message.slice(0, 500) : undefined,
+    });
   }
   if (!isRecord(parsed) || !Array.isArray(parsed.toolCalls)) {
-    throw new Error('Codex returned an invalid model-turn response envelope.');
+    throw transportError(
+      'CODEX_STRUCTURED_OUTPUT_INVALID',
+      'Codex returned an invalid model-turn response envelope.',
+      outputDiagnostics,
+    );
   }
 
   const toolCalls = parsed.toolCalls.map((call, index) => {
     if (!isRecord(call) || typeof call.arguments !== 'string') {
-      throw new Error(
+      throw transportError(
+        'CODEX_TOOL_ARGUMENTS_TRANSPORT_INVALID',
         `Codex tool call ${index + 1} did not use the JSON-string arguments transport.`,
+        {
+          ...outputDiagnostics,
+          toolCallIndex: index,
+          toolName: isRecord(call) ? call.name : undefined,
+        },
       );
     }
 
+    const argumentDiagnostics = {
+      ...outputDiagnostics,
+      toolCallIndex: index,
+      toolName: typeof call.name === 'string' ? call.name : undefined,
+      argumentsLength: call.arguments.length,
+      argumentsSha256: sha256(call.arguments),
+      argumentsPreview: diagnosticPreview(call.arguments),
+    };
     let args;
     try {
-      args = JSON.parse(call.arguments);
-    } catch {
-      throw new Error(`Codex tool call ${index + 1} contained malformed JSON arguments.`);
+      args = parseJsonObject(call.arguments);
+    } catch (cause) {
+      throw transportError(
+        'CODEX_TOOL_ARGUMENTS_MALFORMED',
+        `Codex tool call ${index + 1} contained malformed JSON arguments.`,
+        {
+          ...argumentDiagnostics,
+          parseMessage: cause instanceof Error ? cause.message.slice(0, 500) : undefined,
+        },
+      );
     }
     if (!isRecord(args)) {
-      throw new Error(`Codex tool call ${index + 1} arguments must decode to an object.`);
+      throw transportError(
+        'CODEX_TOOL_ARGUMENTS_NOT_OBJECT',
+        `Codex tool call ${index + 1} arguments must decode to an object.`,
+        argumentDiagnostics,
+      );
     }
     return {
       ...call,
@@ -141,3 +325,46 @@ export function decodeCodexTransportOutput(text) {
     toolCalls,
   });
 }
+
+export function decodeCodexStructuredOutput(
+  text,
+  responseContract = STRUCTURED_RESPONSE_CONTRACTS.MODEL_TURN,
+) {
+  if (normalizeStructuredResponseContract(responseContract) !== STRUCTURED_RESPONSE_CONTRACTS.OUTCOME) {
+    return decodeCodexTransportOutput(text);
+  }
+  const source = String(text || '').trim();
+  const outputDiagnostics = {
+    outputLength: source.length,
+    outputSha256: sha256(source),
+    outputPreview: diagnosticPreview(source),
+  };
+  let parsed;
+  try {
+    parsed = parseJsonObject(source);
+  } catch (cause) {
+    throw transportError(
+      'APP_HARNESS_RESULT_INVALID',
+      'Codex returned malformed harness outcome JSON.',
+      {
+        ...outputDiagnostics,
+        parseMessage:
+          cause instanceof Error ? cause.message.slice(0, 500) : undefined,
+      },
+    );
+  }
+  if (
+    !isRecord(parsed)
+    || typeof parsed.status !== 'string'
+    || typeof parsed.summary !== 'string'
+    || !Array.isArray(parsed.checks)
+    || !Object.prototype.hasOwnProperty.call(parsed, 'blockedReason')
+  ) {
+    throw transportError(
+      'APP_HARNESS_RESULT_INVALID',
+      'Codex returned an invalid harness outcome response.',
+      outputDiagnostics,
+    );
+  }
+  return JSON.stringify(parsed);
+}

package/src/providers/directByok.js

@@ -0,0 +1,197 @@
+import { streamText } from 'ai';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createDeepSeek } from '@ai-sdk/deepseek';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { createXai } from '@ai-sdk/xai';
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { normalizeCompanionTokenUsage } from '../agentOutput.js';
+
+const PROVIDERS = new Set([
+  'openai',
+  'anthropic',
+  'google',
+  'openrouter',
+  'deepseek',
+  'xai',
+  'openai-compatible',
+]);
+
+function text(value, maximum = 4096) {
+  return typeof value === 'string' && value.trim()
+    ? value.trim().slice(0, maximum)
+    : '';
+}
+
+function normalizeBaseUrl(value) {
+  const raw = text(value, 2048);
+  if (!raw) return undefined;
+  const parsed = new URL(raw);
+  const hostname = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  const loopback =
+    hostname === 'localhost'
+    || hostname === 'localhost.'
+    || hostname === '127.0.0.1'
+    || hostname === '::1';
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new Error('Local provider URLs cannot contain credentials, query strings, or fragments.');
+  }
+  if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && loopback)) {
+    throw new Error('Local provider URLs must use HTTPS, except for loopback development endpoints.');
+  }
+  return parsed.toString().replace(/\/+$/, '');
+}
+
+function languageModel(credentials, model) {
+  const provider = text(credentials?.provider, 80).toLowerCase();
+  const apiKey = text(credentials?.apiKey, 8192);
+  const baseURL = normalizeBaseUrl(credentials?.baseURL);
+  if (!PROVIDERS.has(provider)) {
+    throw new Error(`Unsupported local BYOK provider "${provider || 'unknown'}".`);
+  }
+  if (!apiKey) throw new Error('The local BYOK profile has no API key.');
+  if (!text(model, 255)) throw new Error('The local BYOK profile has no model.');
+
+  switch (provider) {
+    case 'openai':
+      return createOpenAI({ apiKey, ...(baseURL ? { baseURL } : {}) }).chat(model);
+    case 'anthropic':
+      return createAnthropic({ apiKey, ...(baseURL ? { baseURL } : {}) }).messages(model);
+    case 'google':
+      return createGoogleGenerativeAI({ apiKey, ...(baseURL ? { baseURL } : {}) }).chat(model);
+    case 'openrouter':
+      return createOpenRouter({
+        apiKey,
+        appName: 'InstaWebAI',
+        compatibility: 'strict',
+      }).chat(model);
+    case 'deepseek':
+      return createDeepSeek({ apiKey, ...(baseURL ? { baseURL } : {}) }).chat(model);
+    case 'xai':
+      return createXai({ apiKey, ...(baseURL ? { baseURL } : {}) }).chat(model);
+    case 'openai-compatible':
+      if (!baseURL) throw new Error('OpenAI-compatible local BYOK profiles require a base URL.');
+      return createOpenAICompatible({
+        name: 'instawebai-local-byok',
+        apiKey,
+        baseURL,
+      }).chatModel(model);
+    default:
+      throw new Error(`Unsupported local BYOK provider "${provider}".`);
+  }
+}
+
+export function createDirectByokAdapter({
+  profile,
+  credentials,
+  trace,
+} = {}) {
+  if (!profile?.id) throw new Error('A local BYOK runtime profile is required.');
+  const activeTurns = new Map();
+
+  async function runModelTurn({
+    runId,
+    sessionId,
+    prompt,
+    model,
+    timeoutMs = 180_000,
+    maxDurationMs = 15 * 60_000,
+    onProgress,
+  } = {}) {
+    const turnId = sessionId || runId;
+    if (!turnId) throw new Error('Local BYOK model turn requires a session id.');
+    if (activeTurns.has(turnId)) throw new Error('Local BYOK model turn is already active.');
+    const abortController = new AbortController();
+    let deadlineReached = false;
+    const timer = setTimeout(() => {
+      deadlineReached = true;
+      abortController.abort();
+    }, maxDurationMs);
+    timer.unref?.();
+    activeTurns.set(turnId, abortController);
+    try {
+      const selectedModel = text(model, 255) || profile.models?.[0]?.invocationName || profile.models?.[0]?.id;
+      onProgress?.({
+        kind: 'turn_started',
+        provider: `local-byok:${credentials.provider}`,
+        occurredAt: new Date().toISOString(),
+      });
+      const result = streamText({
+        model: languageModel(credentials, selectedModel),
+        prompt: String(prompt || ''),
+        maxOutputTokens: 6_000,
+        abortSignal: abortController.signal,
+        onChunk({ chunk }) {
+          const type = String(chunk?.type || '');
+          onProgress?.({
+            kind: /reasoning/i.test(type) ? 'reasoning_delta' : 'output_delta',
+            provider: `local-byok:${credentials.provider}`,
+            occurredAt: new Date().toISOString(),
+          });
+        },
+      });
+      const [resultText, usage, response] = await Promise.all([
+        result.text,
+        result.usage,
+        result.response,
+      ]);
+      return {
+        text: resultText || '',
+        model: response?.modelId || selectedModel,
+        tokenUsage: normalizeCompanionTokenUsage(usage || {}),
+        usageAvailable: Boolean(usage),
+        usageSource: `local-byok:${credentials.provider}`,
+        usageAccuracy: 'reported',
+      };
+    } catch (error) {
+      if (deadlineReached) {
+        throw Object.assign(
+          new Error(`The model turn exceeded the ${maxDurationMs}ms safety limit.`),
+          {
+            code: 'APP_AGENT_TURN_HARD_TIMEOUT',
+            retryable: true,
+          },
+        );
+      }
+      if (abortController.signal.aborted) {
+        throw Object.assign(new Error('Local BYOK model turn was cancelled.'), {
+          code: 'RUN_CANCELLED',
+        });
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+      activeTurns.delete(turnId);
+      trace?.info?.('local_byok_turn_closed', {
+        profileId: profile.id,
+        sessionId: turnId,
+      });
+    }
+  }
+
+  async function cancel(sessionId) {
+    activeTurns.get(sessionId)?.abort();
+  }
+
+  function close() {
+    for (const controller of activeTurns.values()) controller.abort();
+    activeTurns.clear();
+  }
+
+  return {
+    id: profile.id,
+    driverKind: 'direct-byok',
+    label: profile.label || 'Local API key',
+    detect: async () => ({
+      ok: true,
+      installed: true,
+      signedIn: Boolean(credentials?.apiKey),
+      agent: 'direct-byok',
+    }),
+    models: async () => profile.models || [],
+    runModelTurn,
+    cancel,
+    close,
+  };
+}

package/src/providers/index.js

@@ -1,4 +1,7 @@
 import { createCodexAppServerAdapter } from './codexAppServer.js';
+import { createDirectByokAdapter } from './directByok.js';
+import { createOpenCodeAdapter } from './openCode.js';
+import { createAcpAdapter } from './acp.js';
 
 /**
  * Local agent adapters.
@@ -22,23 +25,46 @@ import { createCodexAppServerAdapter } from './codexAppServer.js';
  * @property {Promise<{ok:boolean}>} completed Resolves when sign-in finishes.
  *
  * @typedef {Object} LocalAgentAdapter
- * @property {'codex'|'cursor'|'claude-api'} id
+ * @property {string} id
  * @property {() => Promise<ProviderStatus>} detect
  * @property {(() => Promise<AuthChallenge>)=} authenticate
  * @property {() => Promise<Array<object>>} models
- * @property {(input: object) => Promise<{text: string, tokenUsage?: object}>} runModelTurn
+ * @property {(input: object & {responseContract?: 'model-turn'}) => Promise<{text: string, tokenUsage?: object}>} runModelTurn
+ * @property {((input: object & {responseContract: 'outcome', outputSchema: object}) => Promise<{text: string, tokenUsage?: object}>)=} runOutcome
  * @property {(sessionId: string) => Promise<void>} cancel
  * @property {(() => Promise<void>)=} logout
  */
 
-export const ADAPTER_FACTORIES = {
-  codex: createCodexAppServerAdapter,
+export const DRIVER_FACTORIES = {
+  'codex-app-server': (profile, options) =>
+    createCodexAppServerAdapter(options),
+  'direct-byok': (profile, options) =>
+    createDirectByokAdapter({
+      ...options,
+      profile,
+      credentials: options.credentials || profile.credentials,
+    }),
+  opencode: (profile, options) =>
+    createOpenCodeAdapter({ ...options, profile }),
+  acp: (profile, options) =>
+    createAcpAdapter({ ...options, profile }),
 };
 
 /**
  * Returns an adapter for the agent, or null when the agent has no adapter.
  */
-export function createLocalAgentAdapter(agent, options = {}) {
-  if (agent === 'codex') return createCodexAppServerAdapter(options);
-  return null;
+export function createLocalAgentAdapter(profileOrAgent, options = {}) {
+  const profile =
+    typeof profileOrAgent === 'string'
+      ? profileOrAgent === 'codex'
+        ? { id: 'codex:default', driver: 'codex-app-server' }
+        : null
+      : profileOrAgent;
+  if (!profile?.driver) return null;
+  const factory = DRIVER_FACTORIES[profile.driver];
+  if (!factory) return null;
+  const adapter = factory(profile, options);
+  if (adapter && !adapter.driverKind) adapter.driverKind = profile.driver;
+  if (adapter && profile.id) adapter.profileId = profile.id;
+  return adapter;
 }