@gakim-digital/dexter-bridge 0.5.21 → 0.11.0

package/src/harnessTools.js

@@ -0,0 +1,548 @@
+import crypto from 'node:crypto';
+import http from 'node:http';
+import {
+  applyOutcomeWorkspaceUpdates,
+  collectOutcomeWorkspaceChanges,
+  markOutcomeWorkspaceSynchronized,
+} from './outcomeWorkspace.js';
+
+export const HARNESS_TOOL_NAMES = [
+  'progress_update',
+  'workspace_inspect',
+  'workspace_sync',
+  'shell_run',
+  'preview_control',
+  'browser_control',
+  'data_inspect',
+  'verification_run',
+];
+const EMPTY_SCHEMA = {
+  type: 'object',
+  properties: {},
+  additionalProperties: false,
+};
+
+export const HARNESS_TOOL_DEFINITIONS = [
+  {
+    name: 'progress_update',
+    description:
+      'Tell the user what you are doing and why it matters in one or two natural first-person sentences. Call this before the first inspection or edit and again at every meaningful product phase change, but never delay the product work to produce it. Interpret the request in your own words; never quote or truncate it, expose tool or file names, or begin with "Finished:".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message: {
+          type: 'string',
+          minLength: 1,
+          maxLength: 500,
+        },
+      },
+      required: ['message'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'workspace_inspect',
+    description: 'Inspect the current isolated project workspace.',
+    inputSchema: EMPTY_SCHEMA,
+  },
+  {
+    name: 'workspace_sync',
+    description:
+      'Synchronize the current isolated workspace to the protected InstaWebAI build workspace. Call this before previewing or verifying.',
+    inputSchema: EMPTY_SCHEMA,
+  },
+  {
+    name: 'shell_run',
+    description:
+      'Run a project command in InstaWebAI’s isolated build workspace. Use this for package installation, code generation, tests, builds, and other project commands. Edit source with native file tools; do not put source, patches, or heredocs in this command.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        command: {
+          type: 'string',
+          minLength: 1,
+          maxLength: 8_192,
+        },
+        cwd: {
+          type: 'string',
+          pattern: '^(?:\\.|[A-Za-z0-9][A-Za-z0-9._-]*(?:/[A-Za-z0-9][A-Za-z0-9._-]*)*)$',
+          maxLength: 500,
+          default: '.',
+        },
+        timeoutMs: {
+          type: 'integer',
+          minimum: 1_000,
+          maximum: 600_000,
+          default: 300_000,
+        },
+      },
+      required: ['command'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'preview_control',
+    description: 'Start, restart, or inspect the server-managed development preview for the current workspace.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['start', 'restart', 'status'],
+        },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'browser_control',
+    description:
+      'Use an isolated browser against the current development preview. Prefer batch for consecutive interactions so the final semantic snapshot is returned in one tool call.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['open', 'snapshot', 'click', 'fill', 'select', 'press', 'batch', 'close'],
+        },
+        path: { type: 'string', maxLength: 1_000 },
+        selector: { type: 'string', maxLength: 1_000 },
+        value: { type: 'string', maxLength: 10_000 },
+        key: { type: 'string', maxLength: 80 },
+        actions: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 25,
+          items: {
+            type: 'object',
+            properties: {
+              action: {
+                type: 'string',
+                enum: ['open', 'snapshot', 'click', 'fill', 'select', 'press'],
+              },
+              path: { type: 'string', maxLength: 1_000 },
+              selector: { type: 'string', maxLength: 1_000 },
+              value: { type: 'string', maxLength: 10_000 },
+              key: { type: 'string', maxLength: 80 },
+            },
+            required: ['action'],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'data_inspect',
+    description:
+      'Inspect the application data contract or list redacted development records. This tool is read-only and never exposes database credentials or sensitive field values.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['overview', 'list_records'],
+        },
+        entityId: { type: 'string', maxLength: 180 },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 50 },
+        offset: { type: 'integer', minimum: 0, maximum: 100000, default: 0 },
+        search: { type: 'string', maxLength: 500, default: '' },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'verification_run',
+    description:
+      'Synchronize the workspace, then run InstaWebAI deterministic and browser verification. Use fast for focused workflow checks and visual for broader browser and presentation review.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        level: { type: 'string', enum: ['fast', 'visual'] },
+        workflowIds: {
+          type: 'array',
+          items: { type: 'string', maxLength: 180 },
+          maxItems: 20,
+          default: [],
+        },
+      },
+      required: ['level'],
+      additionalProperties: false,
+    },
+  },
+];
+
+const TOOL_BY_NAME = new Map(HARNESS_TOOL_DEFINITIONS.map((definition) => [definition.name, definition]));
+const REMOTE_TOOLS = new Set([
+  'progress_update',
+  'workspace_inspect',
+  'workspace_sync',
+  'shell_run',
+  'preview_control',
+  'browser_control',
+  'data_inspect',
+  'verification_run',
+]);
+const AUTO_SYNC_TOOLS = new Set(['shell_run', 'preview_control', 'browser_control', 'verification_run']);
+const FATAL_INFRASTRUCTURE_ERROR_CODES = new Set([
+  'APP_BUILD_WORKER_UNAVAILABLE',
+  'APP_BUILD_WORKER_TIMEOUT',
+  'APP_BUILD_WORKER_SANDBOX_UNAVAILABLE',
+  'APP_DATABASE_CONFIGURATION_INVALID',
+  'APP_DATABASE_PROVISIONER_UNAVAILABLE',
+  'APP_DATABASE_PROVISIONING_FAILED',
+  'APP_DATABASE_RECEIPT_REQUIRED',
+  'APP_DATABASE_RECEIPT_INVALID',
+  'APP_PREVIEW_DATABASE_MIGRATION_FAILED',
+  'APP_PREVIEW_DEPENDENCY_PLATFORM_MISMATCH',
+  'APP_PREVIEW_INFRASTRUCTURE_FAILED',
+  'APP_PREVIEW_PORT_EXHAUSTED',
+  'APP_PREVIEW_PORT_RANGE_INVALID',
+  'APP_PREVIEW_START_TIMEOUT',
+  'APP_RUNTIME_ORCHESTRATOR_FAILED',
+  'APP_RUNTIME_ORCHESTRATOR_TIMEOUT',
+  'APP_VERIFICATION_INFRASTRUCTURE_UNAVAILABLE',
+  'APP_VISUAL_CRITIC_UNAVAILABLE',
+  'APP_VISUAL_REVIEW_UNAVAILABLE',
+]);
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function toolError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+function toolActivityMessage(name, args, phase) {
+  const active = phase === 'started' || phase === 'running';
+  const failed = phase === 'failed';
+  if (name === 'shell_run') {
+    const command = String(args?.command || '')
+      .replace(/\s+/g, ' ')
+      .trim();
+    if (/^(?:npm|pnpm|yarn|bun)\s+(?:install|add|remove|uninstall|ci)\b/i.test(command)) {
+      return failed
+        ? 'Could not install project dependencies'
+        : active
+          ? 'Installing project dependencies'
+          : 'Finished installing project dependencies';
+    }
+    if (/\b(?:build|check|lint|test|typecheck|validate)\b/i.test(command)) {
+      return `${failed ? 'Could not finish' : active ? 'Running' : 'Finished'} ${command.slice(0, 180)}`;
+    }
+    return failed
+      ? 'The project command failed'
+      : active
+        ? 'Running a project command'
+        : 'Finished the project command';
+  }
+  if (name === 'preview_control') {
+    return failed ? 'The live preview could not start' : active ? 'Starting the live preview' : 'Live preview is ready';
+  }
+  if (name === 'browser_control') {
+    return failed
+      ? 'The browser check failed'
+      : active
+        ? 'Testing the app in the browser'
+        : 'Finished checking the app in the browser';
+  }
+  if (name === 'data_inspect') {
+    return failed
+      ? 'Could not inspect application data'
+      : active
+        ? 'Inspecting application data'
+        : 'Finished inspecting application data';
+  }
+  if (name === 'workspace_inspect') {
+    return failed
+      ? 'Could not read the current project state'
+      : active
+        ? 'Reading the current project state'
+        : 'Finished reading the project state';
+  }
+  if (name === 'workspace_sync') {
+    return failed ? 'Could not save source changes' : active ? 'Saving source changes' : 'Saved source changes';
+  }
+  if (name === 'verification_run') {
+    return failed
+      ? 'The application check failed'
+      : active
+        ? 'Checking the application'
+        : 'Finished checking the application';
+  }
+  return failed ? `${name} failed` : active ? `Using ${name}` : `Finished ${name}`;
+}
+
+export function isFatalHarnessInfrastructureError(error) {
+  return Boolean(error?.code && FATAL_INFRASTRUCTURE_ERROR_CODES.has(error.code));
+}
+
+function validateArguments(name, value) {
+  if (!TOOL_BY_NAME.has(name)) {
+    throw toolError('APP_HARNESS_TOOL_UNKNOWN', `Unknown harness tool: ${name}`);
+  }
+  if (!isRecord(value)) {
+    throw toolError('APP_HARNESS_TOOL_INPUT_INVALID', 'Harness tool arguments must be an object.');
+  }
+  return value;
+}
+
+function normalizeRemoteResult(response, name, callId) {
+  const toolResult = response?.toolResult;
+  if (!toolResult || toolResult.callId !== callId || toolResult.name !== name) {
+    throw toolError('APP_HARNESS_TOOL_RESULT_MISSING', `InstaWebAI did not return a valid result for ${name}.`);
+  }
+  if (!toolResult.ok) {
+    throw toolError(
+      toolResult.error?.code || 'APP_HARNESS_TOOL_FAILED',
+      toolResult.error?.message || `${name} failed.`,
+    );
+  }
+  return toolResult.result;
+}
+
+export function createHarnessToolRuntime({ assignment, materialized, send, trace, onActivity } = {}) {
+  const requestedToolNames = Array.isArray(assignment?.toolProtocol?.tools)
+    ? assignment.toolProtocol.tools
+    : HARNESS_TOOL_NAMES;
+  const allowedToolNames = new Set(requestedToolNames.filter((name) => TOOL_BY_NAME.has(name)));
+  const definitions = HARNESS_TOOL_DEFINITIONS.filter((definition) => allowedToolNames.has(definition.name));
+  let server = null;
+  let gateway = null;
+  let latestSourceHash = null;
+  let closed = false;
+  let callSequence = 0;
+  let serial = Promise.resolve();
+  let fatalInfrastructureError = null;
+  let resolveFatalInfrastructure;
+  const fatalInfrastructure = new Promise((resolve) => {
+    resolveFatalInfrastructure = resolve;
+  });
+  const initialOriginals = new Map(materialized.originals);
+
+  async function remoteCall(name, args) {
+    const callId = `harness_tool_${Date.now()}_${++callSequence}_${crypto.randomUUID()}`;
+    const reportActivity = (phase) => {
+      if (name === 'progress_update') return;
+      try {
+        void Promise.resolve(
+          onActivity?.({
+            kind: 'tool_active',
+            name,
+            phase,
+            message: toolActivityMessage(name, args, phase),
+            occurredAt: new Date().toISOString(),
+          }),
+        ).catch(() => undefined);
+      } catch {
+        // Observability must never interrupt a tool call.
+      }
+    };
+    reportActivity('started');
+    const heartbeat = setInterval(() => reportActivity('running'), 15_000);
+    heartbeat.unref?.();
+    try {
+      const response = await send('tool_call', {
+        callId,
+        name,
+        arguments: args,
+      });
+      const result = normalizeRemoteResult(response, name, callId);
+      reportActivity('completed');
+      return result;
+    } catch (error) {
+      reportActivity('failed');
+      if (!fatalInfrastructureError && isFatalHarnessInfrastructureError(error)) {
+        fatalInfrastructureError = error;
+        resolveFatalInfrastructure(error);
+      }
+      throw error;
+    } finally {
+      clearInterval(heartbeat);
+    }
+  }
+
+  async function synchronize() {
+    if (materialized.direct) {
+      const result = await remoteCall('workspace_inspect', {});
+      latestSourceHash =
+        typeof result?.sourceHash === 'string' && result.sourceHash ? result.sourceHash : latestSourceHash;
+      return {
+        ...result,
+        synchronized: true,
+        changed: false,
+        changedFiles: [],
+        synchronizedFiles: [],
+      };
+    }
+    const files = collectOutcomeWorkspaceChanges(assignment, materialized);
+    collectOutcomeWorkspaceChanges(assignment, {
+      ...materialized,
+      originals: initialOriginals,
+    });
+    const result = await remoteCall('workspace_sync', { files });
+    markOutcomeWorkspaceSynchronized(materialized, files);
+    latestSourceHash =
+      typeof result?.sourceHash === 'string' && result.sourceHash ? result.sourceHash : latestSourceHash;
+    return {
+      ...result,
+      synchronizedFiles: files.map((file) => file.path),
+    };
+  }
+
+  async function invokeUnsafe(name, rawArguments = {}) {
+    if (closed) {
+      throw toolError('APP_HARNESS_TOOL_RUNTIME_CLOSED', 'The harness tool runtime is closed.');
+    }
+    if (!allowedToolNames.has(name)) {
+      throw toolError('APP_HARNESS_TOOL_UNKNOWN', `Unavailable harness tool: ${name}`);
+    }
+    const args = validateArguments(name, rawArguments);
+    if (name === 'workspace_sync') return synchronize();
+    if (
+      !materialized.direct &&
+      allowedToolNames.has('workspace_sync') &&
+      AUTO_SYNC_TOOLS.has(name) &&
+      (latestSourceHash === null || collectOutcomeWorkspaceChanges(assignment, materialized).length > 0)
+    ) {
+      await synchronize();
+    }
+    if (REMOTE_TOOLS.has(name)) {
+      const result = await remoteCall(name, args);
+      if (name === 'shell_run') {
+        if (!materialized.direct) {
+          applyOutcomeWorkspaceUpdates(materialized, result?.workspaceUpdates);
+        }
+        latestSourceHash =
+          typeof result?.sourceHash === 'string' && result.sourceHash ? result.sourceHash : latestSourceHash;
+        const { workspaceUpdates = [], ...publicResult } = result || {};
+        return {
+          ...publicResult,
+          synchronizedFiles: workspaceUpdates.map((file) => file.path),
+        };
+      }
+      return result;
+    }
+    throw toolError('APP_HARNESS_TOOL_UNKNOWN', `Unknown harness tool: ${name}`);
+  }
+
+  function invoke(name, args = {}) {
+    const operation = serial.then(() => invokeUnsafe(name, args));
+    serial = operation.catch(() => undefined);
+    return operation;
+  }
+
+  async function startGateway() {
+    if (gateway) return gateway;
+    const token = crypto.randomBytes(32).toString('base64url');
+    server = http.createServer((request, response) => {
+      const fail = (status, code, message) => {
+        response.writeHead(status, { 'content-type': 'application/json' });
+        response.end(JSON.stringify({ ok: false, error: { code, message } }));
+      };
+      if (request.method !== 'POST' || request.url !== '/tool') {
+        fail(404, 'APP_HARNESS_GATEWAY_NOT_FOUND', 'Harness tool endpoint not found.');
+        return;
+      }
+      if (request.headers.authorization !== `Bearer ${token}`) {
+        fail(401, 'APP_HARNESS_GATEWAY_UNAUTHORIZED', 'Invalid harness tool token.');
+        return;
+      }
+      let body = '';
+      request.on('data', (chunk) => {
+        body += chunk.toString('utf8');
+        if (body.length > 64 * 1024) request.destroy();
+      });
+      request.on('end', async () => {
+        try {
+          const payload = JSON.parse(body || '{}');
+          const result = await invoke(String(payload.name || ''), payload.arguments || {});
+          response.writeHead(200, { 'content-type': 'application/json' });
+          response.end(JSON.stringify({ ok: true, result }));
+        } catch (error) {
+          trace?.warn?.('harness_tool_failed', {
+            name: (() => {
+              try {
+                return JSON.parse(body || '{}')?.name || null;
+              } catch {
+                return null;
+              }
+            })(),
+            code: error?.code,
+            message: error?.message,
+          });
+          fail(
+            Number(error?.statusCode) || 400,
+            error?.code || 'APP_HARNESS_TOOL_FAILED',
+            error?.message || 'Harness tool failed.',
+          );
+        }
+      });
+    });
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address !== 'object') {
+      throw new Error('Harness tool gateway did not bind to a local port.');
+    }
+    gateway = {
+      url: `http://127.0.0.1:${address.port}/tool`,
+      token,
+    };
+    return gateway;
+  }
+
+  async function close({ waitForPending = true } = {}) {
+    closed = true;
+    if (waitForPending) await serial.catch(() => undefined);
+    if (!server) return;
+    if (!waitForPending) server.closeAllConnections?.();
+    await new Promise((resolve) => server.close(() => resolve()));
+    server = null;
+  }
+
+  return {
+    definitions,
+    toolNames: definitions.map((definition) => definition.name),
+    invoke,
+    startGateway,
+    synchronize,
+    inspect: () => remoteCall('workspace_inspect', {}),
+    sourceHash: () => latestSourceHash,
+    hasPendingChanges: () =>
+      !materialized.direct && collectOutcomeWorkspaceChanges(assignment, materialized).length > 0,
+    directWorkspace: materialized.direct === true,
+    fatalInfrastructureError: () => fatalInfrastructureError,
+    waitForFatalInfrastructure: () => fatalInfrastructure,
+    close,
+  };
+}
+
+export function codexDynamicToolSpecs(definitions = HARNESS_TOOL_DEFINITIONS) {
+  return definitions.map((tool) => ({
+    type: 'function',
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    deferLoading: false,
+  }));
+}
+
+export function codexDynamicToolResult(result, success = true) {
+  return {
+    success,
+    contentItems: [
+      {
+        type: 'inputText',
+        text: JSON.stringify(result),
+      },
+    ],
+  };
+}

package/src/logger.js

@@ -7,7 +7,7 @@ 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,
+  /((?:api[-_]?key|token|secret|password|state)=)[^&\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);