@the-open-engine/zeroshot 6.38.0 → 6.39.0

package/src/agent/guidance-queue.ts

@@ -0,0 +1,166 @@
+import ledgerSequence = require('../ledger-sequence');
+
+const GUIDANCE_BLOCK_START = '<<GUIDANCE_QUEUE_START>>';
+const GUIDANCE_BLOCK_END = '<<GUIDANCE_QUEUE_END>>';
+const { compareMessageSequences } = ledgerSequence;
+
+interface GuidanceContent {
+  text?: string;
+  data?: unknown;
+}
+
+interface GuidanceMessage {
+  sequence?: string;
+  timestamp?: number;
+  sender?: string;
+  topic?: string;
+  receiver?: string;
+  target_agent_id?: string;
+  content?: GuidanceContent;
+}
+
+interface GuidanceFormatOptions {
+  orderBySequence?: boolean;
+}
+
+interface GuidanceMailboxQuery {
+  cluster_id: string;
+  target_agent_id: string;
+  afterId: string | undefined;
+  throughId: string | undefined;
+  lastDeliveredAt: number | null | undefined;
+  limit: number | undefined;
+}
+
+interface GuidanceMessageBus {
+  queryGuidanceMailbox(query: GuidanceMailboxQuery): GuidanceMessage[];
+}
+
+interface CollectQueuedGuidanceOptions {
+  messageBus?: GuidanceMessageBus | null;
+  clusterId?: string | null;
+  agentId?: string | null;
+  afterId?: string;
+  throughId?: string;
+  lastDeliveredAt?: number | null;
+  limit?: number;
+}
+
+interface QueuedGuidance {
+  messages: GuidanceMessage[];
+  latestSequence: string | null | undefined;
+  latestTimestamp: number | null | undefined;
+  guidanceBlock: string;
+}
+
+function formatGuidanceMessage(message: GuidanceMessage): string {
+  const timestamp =
+    typeof message.timestamp === 'number' && Number.isFinite(message.timestamp)
+      ? new Date(message.timestamp).toISOString()
+      : new Date().toISOString();
+  const sender = message.sender || 'unknown';
+  const topic = message.topic || 'GUIDANCE';
+  const target = message.receiver || message.target_agent_id;
+  const targetSuffix = target ? ` -> ${target}` : '';
+
+  let formatted = `[${timestamp}] ${sender} (${topic}${targetSuffix})\n`;
+  if (message.content?.text) {
+    formatted += `${message.content.text}\n`;
+  }
+  if (message.content?.data) {
+    formatted += `${JSON.stringify(message.content.data, null, 2)}\n`;
+  }
+
+  return formatted.trimEnd();
+}
+
+function orderGuidanceMessages(
+  messages: GuidanceMessage[],
+  orderBySequence: boolean
+): GuidanceMessage[] {
+  return messages.slice().sort((left, right) => {
+    if (orderBySequence) {
+      return compareMessageSequences(left.sequence || '0', right.sequence || '0');
+    }
+    return (left.timestamp || 0) - (right.timestamp || 0);
+  });
+}
+
+function formatGuidanceBlock(
+  messages: GuidanceMessage[] | null | undefined,
+  { orderBySequence = false }: GuidanceFormatOptions = {}
+): string {
+  if (!Array.isArray(messages) || messages.length === 0) return '';
+
+  const ordered = orderGuidanceMessages(messages, orderBySequence);
+
+  let block = '## Guidance (Queued)\n\n';
+  block += `${GUIDANCE_BLOCK_START}\n`;
+
+  ordered.forEach((message, index) => {
+    block += `${formatGuidanceMessage(message)}\n`;
+    if (index < ordered.length - 1) {
+      block += '\n';
+    }
+  });
+
+  block += `\n${GUIDANCE_BLOCK_END}\n\n`;
+  return block;
+}
+
+function emptyQueuedGuidance(): QueuedGuidance {
+  return { messages: [], latestSequence: null, latestTimestamp: null, guidanceBlock: '' };
+}
+
+function collectQueuedGuidance({
+  messageBus,
+  clusterId,
+  agentId,
+  afterId,
+  throughId,
+  lastDeliveredAt,
+  limit,
+}: CollectQueuedGuidanceOptions): QueuedGuidance {
+  if (!messageBus) {
+    throw new Error('collectQueuedGuidance: messageBus is required');
+  }
+  if (!clusterId) {
+    throw new Error('collectQueuedGuidance: clusterId is required');
+  }
+  if (!agentId) {
+    throw new Error('collectQueuedGuidance: agentId is required');
+  }
+
+  const messages = messageBus.queryGuidanceMailbox({
+    cluster_id: clusterId,
+    target_agent_id: agentId,
+    afterId,
+    throughId,
+    lastDeliveredAt,
+    limit,
+  });
+
+  if (!messages.length) {
+    return emptyQueuedGuidance();
+  }
+
+  const sequenceBounded = afterId !== undefined || throughId !== undefined;
+  const ordered = orderGuidanceMessages(messages, sequenceBounded);
+  const latestMessage = ordered.at(-1);
+  if (!latestMessage) {
+    return emptyQueuedGuidance();
+  }
+
+  const latestSequence = latestMessage.sequence;
+  const latestTimestamp = latestMessage.timestamp;
+  const guidanceBlock = formatGuidanceBlock(ordered, { orderBySequence: sequenceBounded });
+
+  return { messages: ordered, latestSequence, latestTimestamp, guidanceBlock };
+}
+
+export = {
+  GUIDANCE_BLOCK_START,
+  GUIDANCE_BLOCK_END,
+  formatGuidanceBlock,
+  collectQueuedGuidance,
+};

package/src/agent/output-extraction-error-detail.js

@@ -0,0 +1,45 @@
+"use strict";
+const node_crypto_1 = require("node:crypto");
+const MAX_CLI_ERROR_BYTES = 4096;
+const CLI_ERROR_TRUNCATION_SUFFIX = '… [truncated]';
+function truncateUtf8(text, maxBytes = MAX_CLI_ERROR_BYTES) {
+    if (Buffer.byteLength(text) <= maxBytes)
+        return text;
+    const suffixBytes = Buffer.byteLength(CLI_ERROR_TRUNCATION_SUFFIX);
+    const contentBudget = Math.max(0, maxBytes - suffixBytes);
+    let bytes = 0;
+    let truncated = '';
+    for (const character of text) {
+        const characterBytes = Buffer.byteLength(character);
+        if (bytes + characterBytes > contentBudget)
+            break;
+        truncated += character;
+        bytes += characterBytes;
+    }
+    return `${truncated}${CLI_ERROR_TRUNCATION_SUFFIX}`;
+}
+function primitiveErrorText(value) {
+    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+        ? String(value)
+        : '';
+}
+function cliErrorDetail(value, fallback) {
+    const candidate = Array.isArray(value)
+        ? value
+            .map(primitiveErrorText)
+            .filter((message) => message.trim())
+            .join('; ')
+        : primitiveErrorText(value);
+    const raw = candidate.trim() ? candidate : fallback;
+    return {
+        error: truncateUtf8(raw.trim()),
+        diagnostic: {
+            byteLength: Buffer.byteLength(raw),
+            sha256: (0, node_crypto_1.createHash)('sha256').update(raw).digest('hex'),
+        },
+    };
+}
+module.exports = {
+    MAX_CLI_ERROR_BYTES,
+    cliErrorDetail,
+};

package/src/agent/output-extraction-error-detail.ts

@@ -0,0 +1,49 @@
+import { createHash } from 'node:crypto';
+import type { CliErrorDetail } from './output-extraction-types';
+
+const MAX_CLI_ERROR_BYTES = 4096;
+const CLI_ERROR_TRUNCATION_SUFFIX = '… [truncated]';
+
+function truncateUtf8(text: string, maxBytes = MAX_CLI_ERROR_BYTES): string {
+  if (Buffer.byteLength(text) <= maxBytes) return text;
+
+  const suffixBytes = Buffer.byteLength(CLI_ERROR_TRUNCATION_SUFFIX);
+  const contentBudget = Math.max(0, maxBytes - suffixBytes);
+  let bytes = 0;
+  let truncated = '';
+  for (const character of text) {
+    const characterBytes = Buffer.byteLength(character);
+    if (bytes + characterBytes > contentBudget) break;
+    truncated += character;
+    bytes += characterBytes;
+  }
+  return `${truncated}${CLI_ERROR_TRUNCATION_SUFFIX}`;
+}
+
+function primitiveErrorText(value: unknown): string {
+  return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+    ? String(value)
+    : '';
+}
+
+function cliErrorDetail(value: unknown, fallback: string): CliErrorDetail {
+  const candidate = Array.isArray(value)
+    ? value
+        .map(primitiveErrorText)
+        .filter((message) => message.trim())
+        .join('; ')
+    : primitiveErrorText(value);
+  const raw = candidate.trim() ? candidate : fallback;
+  return {
+    error: truncateUtf8(raw.trim()),
+    diagnostic: {
+      byteLength: Buffer.byteLength(raw),
+      sha256: createHash('sha256').update(raw).digest('hex'),
+    },
+  };
+}
+
+export = {
+  MAX_CLI_ERROR_BYTES,
+  cliErrorDetail,
+};

package/src/agent/output-extraction-failures.js

@@ -0,0 +1,125 @@
+"use strict";
+const errorDetail = require("./output-extraction-error-detail");
+const jsonExtraction = require("./output-extraction-json");
+const piExtraction = require("./output-extraction-pi");
+const { MAX_CLI_ERROR_BYTES, cliErrorDetail } = errorDetail;
+const { isObjectRecord, parseJsonRecordLine } = jsonExtraction;
+const { extractSettledPiFailure } = piExtraction;
+function firstTruthyValue(...values) {
+    for (const value of values) {
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+function recordField(value, field) {
+    return isObjectRecord(value) ? value[field] : undefined;
+}
+function nestedRecordField(value, parent, field) {
+    return recordField(recordField(value, parent), field);
+}
+function claudeFailureFromObject(value) {
+    if (value.type !== 'result')
+        return null;
+    if (value.is_error === true) {
+        const errors = value.errors;
+        const source = Array.isArray(errors) ? errors : firstTruthyValue(value.error, value.result);
+        return { ...cliErrorDetail(source, 'Unknown CLI error'), provider: 'claude' };
+    }
+    if (value.subtype !== 'error')
+        return null;
+    return {
+        ...cliErrorDetail(firstTruthyValue(value.error, value.result), 'CLI returned error'),
+        provider: 'claude',
+    };
+}
+function codexFailureFromObject(value) {
+    if (value.type !== 'turn.failed')
+        return null;
+    const source = firstTruthyValue(nestedRecordField(value, 'error', 'message'), nestedRecordField(value, 'error', 'code'), value.error);
+    return { ...cliErrorDetail(source, 'Turn failed'), provider: 'codex' };
+}
+function geminiFailureFromObject(value) {
+    const failure = (value.type === 'result' && value.status === 'error') ||
+        (value.type === 'error' && value.severity === 'error');
+    if (!failure)
+        return null;
+    const source = firstTruthyValue(nestedRecordField(value, 'error', 'message'), value.message);
+    return { ...cliErrorDetail(source, 'Gemini CLI error'), provider: 'gemini' };
+}
+function opencodeFailureFromObject(value) {
+    if (value.type !== 'session.error' && value.type !== 'error')
+        return null;
+    const error = value.error;
+    const source = firstTruthyValue(recordField(recordField(error, 'data'), 'message'), recordField(error, 'message'), recordField(error, 'name'));
+    return { ...cliErrorDetail(source, 'Session error'), provider: 'opencode' };
+}
+function failureFromProviderObject(value, providerName) {
+    if (!isObjectRecord(value))
+        return null;
+    if (providerName === 'claude')
+        return claudeFailureFromObject(value);
+    if (providerName === 'codex')
+        return codexFailureFromObject(value);
+    if (providerName === 'gemini')
+        return geminiFailureFromObject(value);
+    if (providerName === 'opencode')
+        return opencodeFailureFromObject(value);
+    return null;
+}
+function vertexModelFromResult(parsed, useVertex) {
+    if (parsed.type !== 'result' ||
+        parsed.is_error !== true ||
+        parsed.api_error_status !== 404 ||
+        typeof parsed.result !== 'string') {
+        return null;
+    }
+    const model = /model\s+\(([^)]+)\)/.exec(parsed.result)?.[1];
+    const explicitVertexSignal = parsed.result.includes('vertex deployment');
+    const configuredVertexFallback = useVertex && parsed.result.includes('may not exist or you may not have access');
+    return model && (explicitVertexSignal || configuredVertexFallback) ? { model } : null;
+}
+function extractClaudeVertexModelError(output, { useVertex = false } = {}) {
+    if (!output || typeof output !== 'string')
+        return null;
+    for (const line of output.split('\n')) {
+        const parsed = parseJsonRecordLine(line);
+        if (parsed === null)
+            continue;
+        const failure = vertexModelFromResult(parsed, useVertex);
+        if (failure)
+            return failure;
+    }
+    return null;
+}
+function extractCliFailure(output, providerName = 'claude') {
+    if (providerName === 'pi') {
+        const lines = typeof output === 'string' ? output.split('\n') : [];
+        return extractSettledPiFailure(lines);
+    }
+    if (!output || typeof output !== 'string')
+        return null;
+    const lines = output.split('\n');
+    if (providerName === 'codex')
+        lines.reverse();
+    for (const line of lines) {
+        const parsed = parseJsonRecordLine(line);
+        if (parsed === null)
+            continue;
+        const failure = failureFromProviderObject(parsed, providerName);
+        if (failure)
+            return failure;
+    }
+    return null;
+}
+function extractCliError(output, providerName = 'claude') {
+    const failure = extractCliFailure(output, providerName);
+    return failure ? { error: failure.error, provider: failure.provider } : null;
+}
+module.exports = {
+    MAX_CLI_ERROR_BYTES,
+    cliErrorDetail,
+    extractClaudeVertexModelError,
+    extractCliError,
+    extractCliFailure,
+};

package/src/agent/output-extraction-failures.ts

@@ -0,0 +1,149 @@
+import errorDetail = require('./output-extraction-error-detail');
+import jsonExtraction = require('./output-extraction-json');
+import piExtraction = require('./output-extraction-pi');
+import type {
+  CliError,
+  CliFailure,
+  JsonRecord,
+  VertexModelFailure,
+} from './output-extraction-types';
+
+const { MAX_CLI_ERROR_BYTES, cliErrorDetail } = errorDetail;
+const { isObjectRecord, parseJsonRecordLine } = jsonExtraction;
+const { extractSettledPiFailure } = piExtraction;
+
+function firstTruthyValue(...values: readonly unknown[]): unknown {
+  for (const value of values) {
+    if (value) return value;
+  }
+  return undefined;
+}
+
+function recordField(value: unknown, field: string): unknown {
+  return isObjectRecord(value) ? value[field] : undefined;
+}
+
+function nestedRecordField(value: unknown, parent: string, field: string): unknown {
+  return recordField(recordField(value, parent), field);
+}
+
+function claudeFailureFromObject(value: JsonRecord): CliFailure | null {
+  if (value.type !== 'result') return null;
+  if (value.is_error === true) {
+    const errors = value.errors;
+    const source = Array.isArray(errors) ? errors : firstTruthyValue(value.error, value.result);
+    return { ...cliErrorDetail(source, 'Unknown CLI error'), provider: 'claude' };
+  }
+  if (value.subtype !== 'error') return null;
+  return {
+    ...cliErrorDetail(firstTruthyValue(value.error, value.result), 'CLI returned error'),
+    provider: 'claude',
+  };
+}
+
+function codexFailureFromObject(value: JsonRecord): CliFailure | null {
+  if (value.type !== 'turn.failed') return null;
+  const source = firstTruthyValue(
+    nestedRecordField(value, 'error', 'message'),
+    nestedRecordField(value, 'error', 'code'),
+    value.error
+  );
+  return { ...cliErrorDetail(source, 'Turn failed'), provider: 'codex' };
+}
+
+function geminiFailureFromObject(value: JsonRecord): CliFailure | null {
+  const failure =
+    (value.type === 'result' && value.status === 'error') ||
+    (value.type === 'error' && value.severity === 'error');
+  if (!failure) return null;
+  const source = firstTruthyValue(nestedRecordField(value, 'error', 'message'), value.message);
+  return { ...cliErrorDetail(source, 'Gemini CLI error'), provider: 'gemini' };
+}
+
+function opencodeFailureFromObject(value: JsonRecord): CliFailure | null {
+  if (value.type !== 'session.error' && value.type !== 'error') return null;
+  const error = value.error;
+  const source = firstTruthyValue(
+    recordField(recordField(error, 'data'), 'message'),
+    recordField(error, 'message'),
+    recordField(error, 'name')
+  );
+  return { ...cliErrorDetail(source, 'Session error'), provider: 'opencode' };
+}
+
+function failureFromProviderObject(value: unknown, providerName: string): CliFailure | null {
+  if (!isObjectRecord(value)) return null;
+  if (providerName === 'claude') return claudeFailureFromObject(value);
+  if (providerName === 'codex') return codexFailureFromObject(value);
+  if (providerName === 'gemini') return geminiFailureFromObject(value);
+  if (providerName === 'opencode') return opencodeFailureFromObject(value);
+  return null;
+}
+
+interface VertexOptions {
+  useVertex?: boolean;
+}
+
+function vertexModelFromResult(parsed: JsonRecord, useVertex: boolean): VertexModelFailure | null {
+  if (
+    parsed.type !== 'result' ||
+    parsed.is_error !== true ||
+    parsed.api_error_status !== 404 ||
+    typeof parsed.result !== 'string'
+  ) {
+    return null;
+  }
+
+  const model = /model\s+\(([^)]+)\)/.exec(parsed.result)?.[1];
+  const explicitVertexSignal = parsed.result.includes('vertex deployment');
+  const configuredVertexFallback =
+    useVertex && parsed.result.includes('may not exist or you may not have access');
+  return model && (explicitVertexSignal || configuredVertexFallback) ? { model } : null;
+}
+
+function extractClaudeVertexModelError(
+  output: unknown,
+  { useVertex = false }: VertexOptions = {}
+): VertexModelFailure | null {
+  if (!output || typeof output !== 'string') return null;
+  for (const line of output.split('\n')) {
+    const parsed = parseJsonRecordLine(line);
+    if (parsed === null) continue;
+    const failure = vertexModelFromResult(parsed, useVertex);
+    if (failure) return failure;
+  }
+  return null;
+}
+
+function extractCliFailure(output: unknown, providerName = 'claude'): CliFailure | null {
+  if (providerName === 'pi') {
+    const lines = typeof output === 'string' ? output.split('\n') : [];
+    return extractSettledPiFailure(lines);
+  }
+  if (!output || typeof output !== 'string') return null;
+
+  const lines = output.split('\n');
+  if (providerName === 'codex') lines.reverse();
+
+  for (const line of lines) {
+    const parsed = parseJsonRecordLine(line);
+    if (parsed === null) continue;
+    const failure = failureFromProviderObject(parsed, providerName);
+    if (failure) return failure;
+  }
+
+  return null;
+}
+
+function extractCliError(output: unknown, providerName = 'claude'): CliError | null {
+  const failure = extractCliFailure(output, providerName);
+  return failure ? { error: failure.error, provider: failure.provider } : null;
+}
+
+export = {
+  MAX_CLI_ERROR_BYTES,
+  cliErrorDetail,
+  extractClaudeVertexModelError,
+  extractCliError,
+  extractCliFailure,
+};