@gakim-digital/dexter-bridge 0.5.0

package/src/logger.js

@@ -0,0 +1,183 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { defaultConfigDir } from './config.js';
+
+const SECRET_PATTERNS = [
+  /\b(dcpp|dcpd)_[A-Za-z0-9_-]+/g,
+  /(Authorization:\s*Bearer\s+)[A-Za-z0-9._-]+/gi,
+  /("?(?:apiKey|deviceToken|pairingToken|pairingCode|authorization|secret|password|token)"?\s*[:=]\s*")([^"]+)/gi,
+  /((?:api[-_]?key|token|secret|password)=)[^&\s]+/gi,
+];
+const MAX_LOG_BYTES = Math.max(256_000, Number(process.env.DEXTER_BRIDGE_MAX_LOG_BYTES) || 5_000_000);
+const MAX_ROTATED_LOGS = Math.max(1, Number(process.env.DEXTER_BRIDGE_MAX_ROTATED_LOGS) || 4);
+const DUPLICATE_WINDOW_MS = Math.max(1_000, Number(process.env.DEXTER_BRIDGE_LOG_DEDUPE_MS) || 30_000);
+
+function safeRunId(value) {
+  return String(value || 'unknown')
+    .replace(/[^a-z0-9._-]+/gi, '-')
+    .slice(0, 120) || 'unknown';
+}
+
+export function redact(value) {
+  let text = typeof value === 'string' ? value : JSON.stringify(value);
+  if (text === undefined || text === null) text = '';
+  for (const pattern of SECRET_PATTERNS) {
+    text = text.replace(pattern, (match, prefix) => `${prefix || ''}[redacted]`);
+  }
+  return text;
+}
+
+export function clip(value, max = 2000) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}...[truncated ${text.length - max} chars]`;
+}
+
+function ensureLogDir(logDir) {
+  const dir = logDir || process.env.DEXTER_BRIDGE_LOG_DIR || path.join(defaultConfigDir(), 'logs');
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+  } catch {
+    const fallback = path.join(os.tmpdir(), 'dexter-bridge', 'logs');
+    fs.mkdirSync(fallback, { recursive: true, mode: 0o700 });
+    return fallback;
+  }
+}
+
+function safeMeta(meta) {
+  if (!meta || typeof meta !== 'object') return meta;
+  try {
+    return JSON.parse(redact(JSON.stringify(meta)));
+  } catch {
+    return { value: redact(String(meta)) };
+  }
+}
+
+function callMirror(mirror, level, event, meta) {
+  if (typeof mirror !== 'function') return;
+  try {
+    if (mirror.length >= 3) {
+      mirror(level, event, meta);
+      return;
+    }
+    mirror(`${level.toUpperCase()} ${event}${meta ? ` ${clip(safeMeta(meta), 1200)}` : ''}`);
+  } catch {
+    // Logging should never affect a companion run.
+  }
+}
+
+function rotateLogFile(filePath, maxLogBytes, maxRotatedLogs) {
+  try {
+    const size = fs.statSync(filePath).size;
+    if (size < maxLogBytes) return;
+    for (let index = maxRotatedLogs; index >= 1; index -= 1) {
+      const source = index === 1 ? filePath : `${filePath}.${index - 1}`;
+      const target = `${filePath}.${index}`;
+      if (!fs.existsSync(source)) continue;
+      if (index === maxRotatedLogs && fs.existsSync(target)) fs.unlinkSync(target);
+      fs.renameSync(source, target);
+    }
+  } catch {
+    // Rotation is best-effort and must never affect a run.
+  }
+}
+
+export function createRunLogger({
+  runId,
+  logDir,
+  mirror,
+  maxLogBytes = MAX_LOG_BYTES,
+  maxRotatedLogs = MAX_ROTATED_LOGS,
+  duplicateWindowMs = DUPLICATE_WINDOW_MS,
+} = {}) {
+  const dir = ensureLogDir(logDir);
+  const filePath = path.join(dir, `run-${safeRunId(runId)}.jsonl`);
+  const recent = new Map();
+  const rotationBytes = Math.max(1, Number(maxLogBytes) || MAX_LOG_BYTES);
+  const rotationCount = Math.max(1, Number(maxRotatedLogs) || MAX_ROTATED_LOGS);
+  const dedupeWindow = Math.max(0, Number(duplicateWindowMs) || 0);
+
+  function write(level, event, meta = {}) {
+    const safe = safeMeta(meta);
+    const fingerprint = `${level}:${event}:${JSON.stringify(safe)}`;
+    const now = Date.now();
+    const prior = recent.get(fingerprint);
+    if (prior && now - prior < dedupeWindow) return;
+    recent.set(fingerprint, now);
+    if (recent.size > 200) {
+      for (const [key, at] of recent) {
+        if (now - at > dedupeWindow) recent.delete(key);
+      }
+    }
+    const entry = {
+      ts: new Date().toISOString(),
+      level,
+      event,
+      pid: process.pid,
+      runId: runId || null,
+      ...safe,
+    };
+    try {
+      rotateLogFile(filePath, rotationBytes, rotationCount);
+      fs.appendFileSync(filePath, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+      fs.chmodSync(filePath, 0o600);
+    } catch {
+      // Logging should never affect a companion run.
+    }
+    callMirror(mirror, level, event, entry);
+  }
+
+  return {
+    filePath,
+    info: (event, meta) => write('info', event, meta),
+    warn: (event, meta) => write('warn', event, meta),
+    error: (event, meta) => write('error', event, meta),
+  };
+}
+
+export function errorMeta(error) {
+  return {
+    name: error?.name,
+    message: error?.message || String(error || ''),
+    code: error?.code,
+    status: error?.status,
+    stack: error?.stack ? clip(error.stack, 5000) : undefined,
+  };
+}
+
+export function summarizeToolResult(toolResult) {
+  if (!toolResult || typeof toolResult !== 'object') return null;
+  const result = toolResult.result && typeof toolResult.result === 'object' ? toolResult.result : {};
+  const error = toolResult.error && typeof toolResult.error === 'object' ? toolResult.error : null;
+  return {
+    ok: toolResult.ok === true,
+    errorCode: error?.code,
+    errorMessage: error?.message ? clip(error.message, 500) : undefined,
+    editedCount: typeof result.editedCount === 'number' ? result.editedCount : undefined,
+    targetNodeId: typeof result.targetNodeId === 'string' ? result.targetNodeId : undefined,
+    selectedNodeId: typeof result.selectedNodeId === 'string' ? result.selectedNodeId : undefined,
+    resultKeys: result && typeof result === 'object' ? Object.keys(result).slice(0, 20) : [],
+  };
+}
+
+export function summarizePayload(payload) {
+  if (!payload || typeof payload !== 'object') return payload;
+  const value = payload;
+  return {
+    keys: Object.keys(value).slice(0, 30),
+    message: typeof value.message === 'string' ? clip(value.message, 500) : undefined,
+    type: typeof value.type === 'string' ? value.type : undefined,
+    tool: typeof value.tool === 'string' ? value.tool : typeof value.name === 'string' ? value.name : undefined,
+    callId: typeof value.callId === 'string' ? value.callId : undefined,
+    hasArgs: Boolean(value.args && typeof value.args === 'object'),
+    tokenUsage: value.tokenUsage && typeof value.tokenUsage === 'object' ? value.tokenUsage : undefined,
+  };
+}
+
+export function logLocationHint(logDir) {
+  const dir = logDir || process.env.DEXTER_BRIDGE_LOG_DIR || path.join(defaultConfigDir(), 'logs');
+  const home = os.homedir();
+  return dir.startsWith(home) ? dir.replace(home, '~') : dir;
+}

package/src/protocol.js

@@ -0,0 +1,190 @@
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function shortText(value, max = 360) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value ?? '');
+  return text.length > max ? `${text.slice(0, max)}...[truncated ${text.length - max} chars]` : text;
+}
+
+function compactSchema(schema, depth = 0) {
+  if (!isRecord(schema) || depth > 4) return schema;
+  const result = {};
+  for (const key of ['type', 'enum', 'required', 'additionalProperties']) {
+    if (schema[key] !== undefined) result[key] = schema[key];
+  }
+  if (isRecord(schema.properties)) {
+    result.properties = Object.fromEntries(
+      Object.entries(schema.properties)
+        .slice(0, 40)
+        .map(([key, value]) => [key, compactSchema(value, depth + 1)]),
+    );
+  }
+  if (schema.items !== undefined) result.items = compactSchema(schema.items, depth + 1);
+  return result;
+}
+
+function compactModelTurnContent(content) {
+  if (!Array.isArray(content)) return content;
+  return content.map((part) => {
+    if (!isRecord(part) || part.type !== 'image') return part;
+    return {
+      type: 'image',
+      mimeType: part.mimeType,
+      url: part.url,
+      omittedBase64Bytes: typeof part.base64 === 'string' ? part.base64.length : undefined,
+    };
+  });
+}
+
+export function clipText(value, max = 12000) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\n...[truncated ${text.length - max} chars]`;
+}
+
+export function extractJsonObject(text) {
+  const input = String(text || '').trim();
+  if (!input) throw new Error('Agent returned an empty response.');
+  try {
+    return JSON.parse(input);
+  } catch {
+    // Some local CLIs still wrap structured output in a JSON code fence.
+  }
+  const fenced = input.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+  if (fenced) return JSON.parse(fenced[1]);
+  const start = input.indexOf('{');
+  const end = input.lastIndexOf('}');
+  if (start >= 0 && end > start) return JSON.parse(input.slice(start, end + 1));
+  throw new Error('Agent response did not contain a JSON object.');
+}
+
+export function compactToolCatalog(tools = []) {
+  return tools
+    .filter(isRecord)
+    .slice(0, 40)
+    .map((tool) => ({
+      name: typeof tool.name === 'string' ? tool.name : '',
+      description: shortText(tool.description || '', 360),
+      parameters: compactSchema(tool.parameters),
+    }))
+    .filter((tool) => tool.name);
+}
+
+export function buildModelTurnPrompt(modelTurn = {}) {
+  const messages = Array.isArray(modelTurn.messages)
+    ? modelTurn.messages.slice(-64).map((message) => ({
+      role: message?.role,
+      content: compactModelTurnContent(message?.content),
+      toolCalls: message?.toolCalls,
+      toolCallId: message?.toolCallId,
+    }))
+    : [];
+  const tools = compactToolCatalog(Array.isArray(modelTurn.tools) ? modelTurn.tools : []);
+  return [
+    'You are the model engine for Dexter. The server owns the agent loop and executes all tools.',
+    'Return exactly one JSON object and no markdown.',
+    'Allowed response:',
+    '{"text":"optional assistant text","toolCalls":[{"id":"stable-id","name":"toolName","arguments":"{\\"key\\":\\"value\\"}"}],"finishReason":"tool_calls|stop|length"}',
+    'Each toolCalls[].arguments value must be a JSON-encoded string whose decoded value is an object.',
+    'Use only tools listed below. Do not claim a tool executed; only request it.',
+    'When the task is complete, return toolCalls:[] and finishReason:"stop".',
+    '',
+    `Messages:\n${JSON.stringify(messages)}`,
+    '',
+    `Tools:\n${JSON.stringify(tools)}`,
+  ].join('\n');
+}
+
+export function modelTurnOutputSchema(modelTurn = {}) {
+  const tools = compactToolCatalog(Array.isArray(modelTurn.tools) ? modelTurn.tools : []);
+  const toolNames = tools.map((tool) => tool.name);
+  return {
+    type: 'object',
+    properties: {
+      text: { type: 'string' },
+      toolCalls: {
+        type: 'array',
+        maxItems: toolNames.length ? 12 : 0,
+        items: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            name: toolNames.length
+              ? { type: 'string', enum: toolNames }
+              : { type: 'string' },
+            // Structured Outputs requires every object schema to declare
+            // additionalProperties:false. Tool argument shapes differ per
+            // selected tool, so encode them at this boundary and validate the
+            // decoded object before returning the completion to Dexter.
+            arguments: { type: 'string' },
+          },
+          required: ['id', 'name', 'arguments'],
+          additionalProperties: false,
+        },
+      },
+      finishReason: {
+        type: 'string',
+        enum: ['tool_calls', 'stop', 'length'],
+      },
+    },
+    required: ['text', 'toolCalls', 'finishReason'],
+    additionalProperties: false,
+  };
+}
+
+export function normalizeModelTurnCompletion(raw, fallbackModel = 'local-companion') {
+  if (!isRecord(raw)) throw new Error('Model turn completion must be a JSON object.');
+  if (raw.type || raw.tool || raw.name || raw.calls) {
+    throw new Error('Legacy local-agent decisions are not supported by Dexter Companion v4.');
+  }
+  const toolCalls = Array.isArray(raw.toolCalls)
+    ? raw.toolCalls.slice(0, 12).map((call, index) => {
+      if (!isRecord(call) || typeof call.name !== 'string' || !call.name.trim()) {
+        throw new Error(`Model turn tool call ${index + 1} is missing a name.`);
+      }
+      let toolArguments = call.arguments;
+      if (typeof toolArguments === 'string') {
+        try {
+          toolArguments = JSON.parse(toolArguments);
+        } catch {
+          throw new Error(`Model turn tool call ${index + 1} arguments must contain valid JSON.`);
+        }
+      }
+      if (toolArguments !== undefined && !isRecord(toolArguments)) {
+        throw new Error(`Model turn tool call ${index + 1} arguments must decode to an object.`);
+      }
+      return {
+        id: typeof call.id === 'string' && call.id.trim() ? call.id.slice(0, 160) : `local_tool_${index + 1}`,
+        name: call.name.trim().slice(0, 120),
+        arguments: toolArguments || {},
+      };
+    })
+    : [];
+  const finishReason = raw.finishReason === 'tool_calls'
+    || raw.finishReason === 'stop'
+    || raw.finishReason === 'length'
+    ? raw.finishReason
+    : toolCalls.length
+      ? 'tool_calls'
+      : 'stop';
+  return {
+    text: typeof raw.text === 'string' ? raw.text : '',
+    toolCalls,
+    finishReason,
+    model: typeof raw.model === 'string' && raw.model.trim()
+      ? raw.model.trim().slice(0, 160)
+      : fallbackModel,
+  };
+}
+
+export function runSummary(run) {
+  return {
+    runId: run?.runId,
+    kind: run?.kind,
+    model: run?.model,
+    protocol: run?.protocol?.version,
+    step: run?.modelTurn?.step,
+    toolCount: Array.isArray(run?.modelTurn?.tools) ? run.modelTurn.tools.length : 0,
+  };
+}