@kingsoftcloud/agentkit-harness-node 0.0.0-stage → 0.0.2

package/src/native/result-stream.mjs

@@ -0,0 +1,63 @@
+import { FINAL_SUBMISSION_TOOL, RESULT_DELIVERY_POLICY } from '@kingsoftcloud/agentkit-harness-core';
+
+/** Decode only a top-level answer string. Nested artifact strings never become prose.
+ * This is a linear, non-authoritative display projection; the complete call is
+ * independently parsed and validated before it can become a committed result. */
+export function answerStringDecoder() {
+  let depth = 0, role = null, key = '', keyExpected = false, selected = null;
+  let escaped = false, unicode = null, invalid = false;
+  return delta => {
+    let output = '';
+    const character = value => { if (role === 'answer') output += value;else if (role === 'key') key += value; };
+    for (const ch of delta) {
+      if (invalid) break;
+      if (role !== null) {
+        if (unicode !== null) {
+          if (!/^[0-9a-f]$/i.test(ch)) { invalid = true;break; }
+          unicode += ch;
+          if (unicode.length === 4) { character(String.fromCharCode(parseInt(unicode, 16)));unicode = null; }
+        } else if (escaped) {
+          escaped = false;
+          if (ch === 'u') unicode = '';
+          else {
+            const escapes = { '"': '"', '\\': '\\', '/': '/', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t' };
+            if (!Object.hasOwn(escapes, ch)) { invalid = true;break; }
+            character(escapes[ch]);
+          }
+        } else if (ch === '\\') escaped = true;
+        else if (ch === '"') { if (role === 'key') { selected = key;keyExpected = false; }role = null; }
+        else if (ch.charCodeAt(0) < 32) { invalid = true;break; }
+        else character(ch);
+      } else if (ch === '"') {
+        role = depth === 1 && keyExpected ? 'key' : depth === 1 && selected === 'answer' ? 'answer' : 'other';key = '';
+      } else if (ch === '{' || ch === '[') { depth++;if (depth === 1) keyExpected = true; }
+      else if (ch === '}' || ch === ']') depth--;
+      else if (ch === ',' && depth === 1) { keyExpected = true;selected = null; }
+    }
+    return output;
+  };
+}
+
+/** Suppress the internal envelope while preserving its text answer as live prose. */
+export function finalResultDisplay(configuration) {
+  if (configuration?.deliveryScopePolicy !== RESULT_DELIVERY_POLICY) return record => [record];
+  const tools = new Map(), known = new Set(configuration.tools.map(tool => tool.name));
+  return record => {
+    const { event } = record;
+    if (event.kind !== 'tool_delta') return [record];
+    const index = event.metadata.index;
+    let state = tools.get(index);
+    if (!state) { state = { name: '', pending: [], decode: answerStringDecoder() };tools.set(index, state); }
+    if (event.metadata.name) state.name = event.metadata.name;
+    state.pending.push(record);
+    if (!state.name) return [];
+    if (state.name === FINAL_SUBMISSION_TOOL) {
+      return state.pending.splice(0).flatMap(item => {
+        const text = state.decode(item.event.text);
+        return text ? [{ time: item.time, event: { kind: 'text', text } }] : [];
+      });
+    }
+    // A partial or unknown name is not yet a displayable bound tool.
+    return known.has(state.name) ? state.pending.splice(0) : [];
+  };
+}

package/src/native/ruff-ast.mjs

@@ -0,0 +1,95 @@
+// Decoder for the pinned Ruff WASM Rust Debug AST, not a Python parser.
+// Python grammar and literal decoding happen in Rust. Unknown wire syntax
+// fails closed; the caller checks the exact parser version in its worker.
+export function decodeRuffAst(text) {
+  let at = 0;
+  const fail = () => { throw Error('unsupported_ruff_ast_encoding'); };
+  const space = () => { while (/\s/.test(text[at] ?? '') && at < text.length) at++; };
+  const take = char => { space(); if (text[at++] !== char) fail(); };
+  function string() {
+    take('"'); let result = '';
+    while (at < text.length) {
+      const char = text[at++];
+      if (char === '"') return result;
+      if (char !== '\\') { result += char; continue; }
+      const escaped = text[at++], simple = { '"': '"', '\\': '\\', n: '\n', r: '\r', t: '\t', '0': '\0' };
+      if (Object.hasOwn(simple, escaped)) { result += simple[escaped]; continue; }
+      const match = escaped === 'u' ? /^\{([a-fA-F0-9]{1,6})\}/.exec(text.slice(at))
+        : escaped === 'x' ? /^([a-fA-F0-9]{2})/.exec(text.slice(at)) : null;
+      if (!match) fail();
+      const point = parseInt(match[1], 16); if (point > 0x10ffff) fail();
+      result += String.fromCodePoint(point); at += match[0].length;
+    }
+    fail();
+  }
+  function list(end, depth) {
+    const items = []; space();
+    while (text[at] !== end) {
+      items.push(value(depth + 1)); space();
+      if (text[at] !== ',') break;
+      at++; space();
+    }
+    take(end); return items;
+  }
+  function value(depth) {
+    if (depth > 1024) fail(); space();
+    if (text[at] === '"') return string();
+    if (text[at] === '[') { at++; return list(']', depth); }
+    if (text[at] === '(') { at++; return { tag: 'tuple', items: list(')', depth) }; }
+    const numeric = /^[+-]?(?:\d+\.\.\d+|\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(text.slice(at));
+    if (numeric) {
+      at += numeric[0].length;
+      if (numeric[0].includes('..')) return { range: numeric[0].split('..').map(Number) };
+      return { numeric: numeric[0] }; // Preserve large values without rounding.
+    }
+    const named = /^[A-Za-z_][A-Za-z0-9_:]*/.exec(text.slice(at)); if (!named) fail();
+    const tag = named[0]; at += tag.length; space();
+    if (text[at] === '(') { at++; return { tag, items: list(')', depth) }; }
+    if (text[at] === '{') {
+      at++; const fields = Object.create(null); space();
+      while (text[at] !== '}') {
+        const key = /^[A-Za-z_][A-Za-z0-9_]*/.exec(text.slice(at)); if (!key || Object.hasOwn(fields, key[0])) fail();
+        at += key[0].length; take(':'); fields[key[0]] = value(depth + 1); space();
+        if (text[at] !== ',') break;
+        at++; space();
+      }
+      take('}'); return { tag, fields };
+    }
+    return tag === 'true' ? true : tag === 'false' ? false : tag === 'None' ? null : { tag };
+  }
+  const root = value(0); space(); if (at !== text.length || root?.tag !== 'Module') fail();
+  return root;
+}
+
+export function unwrapRuff(value) {
+  while (value?.items?.length === 1) value = value.items[0];
+  return value;
+}
+export function ruffIdentifier(value) {
+  const node = unwrapRuff(value);
+  return typeof node === 'string' ? node : node?.tag === 'Identifier' ? ruffIdentifier(node.fields.id) : null;
+}
+export function ruffString(value) {
+  const node = unwrapRuff(value);
+  if (node?.tag !== 'ExprStringLiteral') return null;
+  const content = unwrapRuff(node.fields.value?.fields?.inner);
+  return ['StringLiteral', 'ConcatenatedStringLiteral'].includes(content?.tag) && typeof content.fields?.value === 'string'
+    ? content.fields.value : null;
+}
+
+// Breadth first across AST nodes, ignoring Rust enum/option/debug wrappers.
+// This is used for whole-module alias collection followed by call inspection.
+export function ruffNodes(root) {
+  const ast = node => node?.fields && /^(Mod|Stmt|Expr|Alias$|Keyword$|Comprehension$|Parameters$|Parameter$|WithItem$|MatchCase$|ExceptHandler)/.test(node.tag);
+  const children = item => {
+    if (!item || typeof item !== 'object') return [];
+    if (ast(item)) return [item];
+    return Object.values(item).flatMap(child => children(child));
+  };
+  const queue = children(root), result = [];
+  for (let i = 0; i < queue.length; i++) {
+    const node = queue[i]; result.push(node);
+    for (const [key, child] of Object.entries(node.fields)) if (key !== 'node_index' && key !== 'range') queue.push(...children(child));
+  }
+  return result;
+}

package/src/native/run-observation.mjs

@@ -0,0 +1,128 @@
+import { copy, reviewedBackgroundInterruption, reviewableBackgroundInterruption,
+  reviewedResourceInterruption, retirableBrowserResources } from '@kingsoftcloud/agentkit-harness-core';
+import { projectedNativeToolStates } from './tool-states.mjs';
+import { advanceNativeToolObservation, nativeObservedToolStates } from './tool-observation.mjs';
+import { nativeContextStatus } from './context-status.mjs';
+import { nativeActivityStatus } from './activity-status.mjs';
+import { nativeA2aReceiptWaitSource } from './a2a-receipt-source.mjs';
+import { canCloseNativeReadInterruption } from './read-interruption.mjs';
+import { advanceNativeContextMarkerState, nativeContextMarkerFactsFromState } from './context-markers.mjs';
+
+export const NATIVE_RUN_OBSERVATION = 'agentkit.native-run-observation/v1';
+export const NATIVE_COMMIT_PROJECTION = 'agentkit.native-commit-projection/v2';
+
+function contextProjection(previous, record) {
+  let lastPlan = previous?.lastPlan ?? null, lastAdmission = previous?.lastAdmission ?? null;
+  for (const event of record.events ?? []) if (event.kind === 'context.planned') {
+    lastPlan = { kind: event.kind, seq: event.seq, payload: { action: event.payload.action } };
+    if (event.payload.admission) lastAdmission = { kind: event.kind, seq: event.seq,
+      payload: { admission: event.payload.admission } };
+  }
+  return { lastPlan, lastAdmission, markers: advanceNativeContextMarkerState(previous?.markers, record) };
+}
+
+function observationHeader(s) {
+  const header = Object.fromEntries(['scope', 'runId', 'sessionId', 'turnId', 'buildId', 'parentRunId', 'taskChainId',
+    'configDigest', 'phase', 'revision', 'eventSeq', 'usage', 'descendantUsage', 'outcome', 'reason', 'pendingIntent',
+    'toolReconciliation'].filter(key => s[key] !== undefined).map(key => [key, s[key]]));
+  header.diagnostics = Object.fromEntries(['providerUsageIncomplete', 'descendantUsageIncomplete', 'lastModelFailure']
+    .filter(key => s.diagnostics[key] !== undefined).map(key => [key, s.diagnostics[key]]));
+  return header;
+}
+
+/** A control transaction changes no transcript, receipt or event. Its display
+ * consequence is derived from current authority, never used as execution input. */
+export function advanceNativeRunControlObservation(previous, state, changes) {
+  const view = copy(previous);
+  if (changes.claim) {
+    view.snapshot = observationHeader(changes.claim.snapshot);
+    const intent = changes.claim.intent;
+    view.facts.pendingEffect = { operationKey: intent.operationKey, kind: intent.kind, status: intent.status,
+      claimedFence: intent.claimedFence ?? null, receiptPresent: state.pendingIntentHasReceipt,
+      calls: (intent.payload.calls ?? []).map(({ callId, name }) => ({ callId, name })) };
+    view.commitProjection.tools = advanceNativeToolObservation(view.commitProjection.tools, { intents: [intent] });
+    for (const mode of ['idle', 'driving']) view.facts.toolStates[mode] = projectedNativeToolStates(
+      view.commitProjection.tools, changes.claim.snapshot, { driving: mode === 'driving' });
+  }
+  view.projections = copy(changes.projections ?? state.projections);
+  if (changes.commands?.some(row => !row.consumed)) {
+    view.facts.controlHints.reviewBackground = false;
+    view.facts.controlHints.retireResources = false;
+    view.facts.backgroundReview = null;
+    view.facts.resourceReview = null;
+  }
+  view.lease = copy(state.lease); view.fence = state.fence;
+  return copy(view);
+}
+
+/** Materialize a display read model inside the same ledger transaction.
+ * No transcript, model replay, tool arguments/results, image bytes or ports.
+ * Control hints are for display only: every control re-reads its original ledger.
+ */
+export function projectNativeRunObservation(record, tools = advanceNativeToolObservation(null, record)) {
+  const { snapshot: s, configuration: c } = record;
+  const header = observationHeader(s);
+  const receiptWait = nativeA2aReceiptWaitSource(record);
+  const pending = record.intents.find(i => i.operationKey === s.pendingIntent);
+  const resourceReviewed = reviewedResourceInterruption(record);
+  const backgroundReviewed = reviewedBackgroundInterruption(record);
+  const toolOutcomes = nativeObservedToolStates(tools, s).filter(call => ['uncertain', 'not_dispatched'].includes(call.status));
+  const facts = {
+    toolStates: { idle: projectedNativeToolStates(tools, s), driving: projectedNativeToolStates(tools, s, { driving: true }) },
+    contextStatus: { idle: nativeContextStatus(record), driving: nativeContextStatus(record, { driving: true }) },
+    activity: nativeActivityStatus(record),
+    acceptance: c.contract.acceptance.map(({ required, verifierRef }) => ({ required, verifierRef })),
+    toolNames: c.tools.map(tool => tool.name),
+    a2aTasks: record.intents.filter(i => i.kind === 'tool').flatMap(i => (i.payload.calls ?? [])
+      .filter(call => call.name === 'call_a2a_agent').map(call => ({ runId: s.runId, operationKey: i.operationKey, callId: call.callId }))),
+    uncertainCalls: toolOutcomes.filter(row => row.status === 'uncertain').map(({ callId }) => ({ callId })),
+    toolOutcomes,
+    receiptWait: receiptWait ? { operationKey: receiptWait.intent.operationKey, callId: receiptWait.call.callId } : null,
+    pendingEffect: pending ? { operationKey: pending.operationKey, kind: pending.kind, status: pending.status,
+      claimedFence: pending.claimedFence ?? null, receiptPresent: record.receipts.some(r => r.operationKey === pending.operationKey),
+      calls: (pending.payload.calls ?? []).map(({ callId, name }) => ({ callId, name })) } : null,
+    controlHints: {
+      closeReadInterruption: canCloseNativeReadInterruption(record),
+      reviewBackground: reviewableBackgroundInterruption(record),
+      retireResources: Boolean(retirableBrowserResources(record)),
+      repairWorkspace: c.tools.some(tool => tool.name === s.pendingTools[0]?.name && tool.workspaceRepairPolicy === 'preimage-compensation/v1'),
+    },
+    backgroundReview: backgroundReviewed ? record.backgroundInterruptionReview : null,
+    resourceReview: resourceReviewed ? { contract: 'agentkit.resource-retirement-review/v1',
+      commandId: record.resourceRetirementReview.commandId, eventSeq: record.resourceRetirementReview.eventSeq,
+      resourceKind: record.resourceRetirementReview.fence.resourceKind } : null,
+  };
+  return copy({ contract: NATIVE_RUN_OBSERVATION, snapshot: header, lease: record.lease, fence: record.fence,
+    projections: record.projections, facts,
+    commitProjection: { contract: NATIVE_COMMIT_PROJECTION, context: contextProjection(null, record), tools } });
+}
+
+/** Advance display facts from a validated append. These facts are never used
+ * as execution authority. Exceptional recovery keeps the complete-ledger path. */
+export function advanceNativeRunCommitObservation(previous, state, changes) {
+  const record = { ...state, snapshot: changes.snapshot, events: changes.events,
+    intents: [...state.intents, ...changes.intents], receipts: changes.receipts,
+    commands: changes.commands, projections: previous.projections };
+  const context = contextProjection(previous.commitProjection.context, record);
+  const tools = advanceNativeToolObservation(previous.commitProjection.tools, record);
+  const view = projectNativeRunObservation(record, tools);
+  const merge = (old, next, key) => [...new Map([...old, ...next].map(item => [key(item), item])).values()];
+  view.facts.a2aTasks = merge(previous.facts.a2aTasks, view.facts.a2aTasks, row => row.callId);
+  const contextRecord = { ...record, events: [context.lastAdmission, context.lastPlan].filter(Boolean) };
+  for (const mode of ['idle', 'driving']) {
+    const options = { driving: mode === 'driving' };
+    view.facts.contextStatus[mode] = nativeContextStatus(contextRecord, options);
+    if (view.facts.contextStatus[mode]) view.facts.contextStatus[mode].markers =
+      nativeContextMarkerFactsFromState(context.markers, record.snapshot, options).map(fact => fact.marker);
+  }
+  const observed = new Set(changes.events.filter(event => event.kind === 'background.commands_observed')
+    .flatMap(event => (event.payload.commands ?? []).map(command => command.taskId)));
+  const terminals = new Map(previous.facts.activity.terminals.map(row => [row.id, row]));
+  view.facts.activity.terminals = view.facts.activity.terminals.map(row => {
+    const old = terminals.get(row.id);
+    return !old ? row : { ...row, title: row.title === row.id ? old.title : row.title,
+      state: observed.has(row.id) ? row.state : old.state };
+  });
+  view.commitProjection = { contract: NATIVE_COMMIT_PROJECTION, context, tools };
+  return view;
+}

package/src/native/session-delivery-journal.mjs

@@ -0,0 +1,96 @@
+import { copy, canonical, terminal, RESULT_DELIVERY_POLICY, FINAL_SUBMISSION_TOOL } from '@kingsoftcloud/agentkit-harness-core';
+import { nativeDeliveryClosure } from './delivery-timeline.mjs';
+
+// Presentation evidence only. Neither this journal nor its cursor authorizes
+// execution, recovery, retries, model history or tool-result reconciliation.
+export const NATIVE_DELIVERY_JOURNAL = 'agentkit.native-delivery-journal/v1';
+export const DELIVERY_SNAPSHOT_FIELDS = Object.freeze(['scope', 'runId', 'sessionId', 'turnId', 'buildId',
+  'parentRunId', 'taskChainId', 'configDigest', 'revision', 'eventSeq', 'phase', 'reason', 'finalText', 'messages', 'backgroundNotification']);
+const eventKinds = new Set(['model.completed', 'context.summary_completed', 'completion.delivery_review_completed',
+  'model.stream_interrupted', 'output.restarted', 'tool.completed', 'tool.not_dispatched', 'context.planned',
+  'plan.initialized', 'plan.mode_changed', 'todo.initialized', 'todo.updated', 'effect.prepared']);
+const pick = (value, fields) => Object.fromEntries(fields.filter(key => Object.hasOwn(value, key)).map(key => [key, value[key]]));
+
+export function deliveryJournalHead(snapshot) {
+  return { contract: NATIVE_DELIVERY_JOURNAL, ...pick(snapshot,
+    ['scope', 'runId', 'sessionId', 'configDigest', 'revision', 'eventSeq']) };
+}
+export function matchesDeliveryJournal(head, snapshot) {
+  return head?.contract === NATIVE_DELIVERY_JOURNAL && head.revision === snapshot.revision
+    && head.eventSeq === snapshot.eventSeq && head.configDigest === snapshot.configDigest
+    && head.runId === snapshot.runId && head.sessionId === snapshot.sessionId
+    && canonical(head.scope) === canonical(snapshot.scope);
+}
+
+function deliveryEvent(event) {
+  if (!eventKinds.has(event.kind) || event.kind === 'effect.prepared' && event.payload.kind !== 'input') return null;
+  const fields = event.kind === 'tool.completed' ? ['callId', 'status']
+    : event.kind === 'tool.not_dispatched' ? ['callId']
+      : event.kind === 'context.planned' ? ['action', 'compactions']
+        : event.kind === 'effect.prepared' ? ['kind', 'operationKey'] : null;
+  return fields ? { ...event, payload: pick(event.payload, fields) } : event;
+}
+
+/** Full reference projection and incremental SQL append share this boundary.
+ * `intents` must contain the intents referenced by the supplied receipts. */
+export function sessionDeliveryEntries({ events = [], intents = [], receipts = [] }) {
+  const rows = [], byKey = new Map(intents.map(intent => [intent.operationKey, intent]));
+  const add = (collection, key, data) => rows.push({ collection, key: String(key), data: copy(data) });
+  for (const event of events) {
+    const projected = deliveryEvent(event);
+    if (projected) add('events', event.seq, projected);
+    if (['tool.completed', 'tool.not_dispatched'].includes(event.kind))
+      add('outcomes', event.payload.callId, event.kind === 'tool.not_dispatched' ? 'not_dispatched' : event.payload.status);
+  }
+  for (const intent of intents) {
+    if (intent.kind === 'input' && Number.isSafeInteger(intent.payload.messageCursor))
+      add('inputs', intent.operationKey, intent.payload.messageCursor);
+    if (intent.kind === 'tool') for (const [index, call] of (intent.payload.calls ?? []).entries())
+      add('tools', call.callId, { operationKey: intent.operationKey, index });
+  }
+  for (const receipt of receipts) {
+    const intent = byKey.get(receipt.operationKey);
+    if (!intent) continue;
+    if (receipt.status === 'not_dispatched' && intent.kind === 'tool')
+      for (const call of intent.payload.calls ?? []) add('outcomes', call.callId, 'not_dispatched');
+    if (receipt.status !== 'committed') continue;
+    const pairs = intent.kind === 'tool' ? (intent.payload.calls ?? []).map((call, index) => [call.callId, receipt.result.results?.[index]])
+      : ['tool_receipt', 'workspace_repair'].includes(intent.kind) ? [[intent.payload.callId, receipt.result.result]] : [];
+    for (const [callId, observation] of pairs) {
+      const meta = observation?.metadata?.nativeTaskDisplay;
+      if (observation?.status === 'ok' && meta?.contract === 'agentkit.workspace-display/v1' && meta.display?.kind === 'file_edit')
+        add('displays', callId, meta);
+    }
+  }
+  return rows;
+}
+
+/** Calls absent from the committed transcript still need an exact terminal
+ * closure. Resolve only their original receipts, never every historical body. */
+export function pendingDeliveryCalls(snapshot, configuration) {
+  if (!terminal(snapshot.phase)) return [];
+  const completed = new Set(snapshot.messages.filter(message => message.role === 'tool').map(message => message.callId));
+  return [...new Set(snapshot.messages.flatMap(message => (message.toolCalls ?? [])
+    .filter(call => configuration.deliveryScopePolicy !== RESULT_DELIVERY_POLICY || call.name !== FINAL_SUBMISSION_TOOL).map(call => call.callId)))]
+    .filter(callId => !completed.has(callId));
+}
+
+export function deliveryStateFromEntries({ snapshot, configuration, projections }, entries, resolveClosure) {
+  const groups = Object.fromEntries(['events', 'inputs', 'tools', 'outcomes', 'displays'].map(key => [key, new Map()]));
+  for (const row of entries) {
+    // A definitive nondispatch fact has the same precedence as the full
+    // receipt scan, including after later reconciliation events.
+    if (row.collection === 'outcomes' && groups.outcomes.get(row.key) === 'not_dispatched') continue;
+    if (row.collection === 'tools' && groups.tools.has(row.key)) continue;
+    groups[row.collection].set(row.key, row.data);
+  }
+  return copy({ contract: NATIVE_DELIVERY_JOURNAL,
+    snapshot: pick(snapshot, DELIVERY_SNAPSHOT_FIELDS), configuration, projections,
+    events: [...groups.events.values()].sort((a, b) => a.seq - b.seq),
+    inputBoundaries: [...groups.inputs], toolOutcomes: [...groups.outcomes], displays: [...groups.displays],
+    closures: pendingDeliveryCalls(snapshot, configuration).map(callId => [callId, resolveClosure(callId, groups.tools.get(callId))]) });
+}
+
+export function projectNativeSessionDelivery(record) {
+  return deliveryStateFromEntries(record, sessionDeliveryEntries(record), callId => nativeDeliveryClosure(record, callId));
+}