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

package/src/native/model-sse.mjs

@@ -0,0 +1,171 @@
+// Strict SSE byte framing for the native model transport.
+//
+// Ports ksadk._model_sse: UTF-8 is deliberately strict (replacing corrupt bytes
+// inside JSON changes model facts), a byte budget bounds the whole body, and a
+// blank line is the only frame dispatch. A discarded terminal fragment at EOF
+// is an unfinished frame, never a complete response. Idle silence is bounded.
+//
+// This framer yields { data, event } frames and never parses JSON: the protocol
+// handlers own envelope validation. [DONE] is yielded as a data frame for the
+// handler to seal termination.
+
+export class SseFramingError extends Error {
+  constructor(message, code = 'framing_invalid') { super(message); this.name = 'SseFramingError'; this.code = code; }
+}
+
+// No nonempty model data arrived within the host's read interval.
+export class IdleTimeout extends Error {
+  constructor(message = 'model stream idle timeout') { super(message); this.name = 'IdleTimeout'; }
+}
+
+// Normalize a fetch body (web ReadableStream or async iterable) to an async
+// iterator of Uint8Array chunks. Fetch's response.body is a web ReadableStream
+// in Node; both shapes are accepted so tests can feed a plain async iterable.
+function toAsyncIterator(body) {
+  if (body && typeof body[Symbol.asyncIterator] === 'function') return body[Symbol.asyncIterator]();
+  if (body && typeof body.getReader === 'function') {
+    const reader = body.getReader();
+    const next = () => reader.read();
+    const return_ = async () => {
+      try { await reader.cancel(); } catch { /* already closed or released */ }
+      try { reader.releaseLock(); } catch { /* ignore */ }
+    };
+    return { next, return: return_, [Symbol.asyncIterator]() { return this; } };
+  }
+  throw new SseFramingError('model SSE requires a byte stream');
+}
+
+// Stateful line framer mirroring ksadk._model_sse._Framer. CRLF/CR/LF all
+// terminate lines; a blank line dispatches a frame from accumulated data lines.
+class SseFramer {
+  constructor() {
+    this.lineParts = [];
+    this.dataLines = [];
+    this.eventName = '';
+    this.afterCr = false;
+  }
+
+  feed(text, frames) {
+    if (!text) return;
+    if (this.afterCr) {
+      if (text.startsWith('\n')) text = text.slice(1);
+      this.afterCr = false;
+    }
+    let start = 0;
+    for (const m of text.matchAll(/\r\n|\r|\n/g)) {
+      this.lineParts.push(text.slice(start, m.index));
+      const line = this.lineParts.join('');
+      this.lineParts = [];
+      start = m.index + m[0].length;
+      this.afterCr = m[0] === '\r' && start === text.length;
+      const frame = this.handleLine(line);
+      if (frame) frames.push(frame);
+    }
+    if (start < text.length) this.lineParts.push(text.slice(start));
+  }
+
+  handleLine(line) {
+    if (line === '') {
+      if (this.dataLines.length === 0) { this.eventName = ''; return null; }
+      const frame = { data: this.dataLines.join('\n'), event: this.eventName || '' };
+      this.dataLines = [];
+      this.eventName = '';
+      return frame;
+    }
+    if (line.startsWith(':')) return null; // comment / heartbeat
+    const sep = line.indexOf(':');
+    const name = sep === -1 ? line : line.slice(0, sep);
+    let value = sep === -1 ? '' : line.slice(sep + 1);
+    if (value.startsWith(' ')) value = value.slice(1);
+    if (name === 'data') this.dataLines.push(value);
+    else if (name === 'event') this.eventName = value;
+    // `id` and `retry` are transport controls, not model payloads; ignore them.
+    return null;
+  }
+
+  finish() {
+    const pending = this.lineParts.join('');
+    // A trailing data fragment without a blank-line dispatch is unfinished.
+    if (this.dataLines.length || pending === 'data' || pending.startsWith('data:')) {
+      throw new SseFramingError('unfinished model SSE data');
+    }
+  }
+}
+
+/**
+ * Yield { data, event } SSE frames from a byte stream with strict framing.
+ *
+ * @param body fetch response body (ReadableStream or async iterable of bytes)
+ * @param {maxBytes, idleTimeoutMs, abort} bounds. maxBytes bounds total bytes;
+ *   idleTimeoutMs bounds silence between nonempty frames: when it fires, abort
+ *   is called with an IdleTimeout so the underlying fetch aborts and the
+ *   pending read rejects cleanly (no orphaned read to cancel). Throws
+ *   SseFramingError (terminal) or propagates transport/abort errors.
+ */
+export async function* readModelSse(body, { maxBytes = 8 * 1024 * 1024, idleTimeoutMs, abort, observeBytes } = {}) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new SseFramingError('model SSE needs a positive byte budget');
+  }
+  const iter = toAsyncIterator(body);
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  const framer = new SseFramer();
+  let total = 0;
+  const idleEnabled = typeof idleTimeoutMs === 'number' && idleTimeoutMs > 0 && typeof abort === 'function';
+  let idleTimer = null;
+  const armIdle = () => {
+    if (!idleEnabled) return;
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => abort(new IdleTimeout()), idleTimeoutMs);
+    idleTimer.unref?.();
+  };
+  const disarmIdle = () => { if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; } };
+  armIdle();
+  const frames = [];
+  try {
+    while (true) {
+      let result;
+      result = await iter.next();
+      if (result.done) break;
+      const chunk = result.value;
+      if (!(chunk instanceof Uint8Array) && !(chunk instanceof ArrayBuffer)) {
+        throw new SseFramingError('model SSE requires byte chunks');
+      }
+      total += chunk.byteLength;
+      observeBytes?.(chunk.byteLength);
+      if (total > maxBytes) throw new SseFramingError('model SSE byte budget exceeded', 'body_limit');
+      let text;
+      try {
+        text = decoder.decode(chunk, { stream: true });
+      } catch {
+        throw new SseFramingError('invalid utf-8 in model stream', 'body_encoding');
+      }
+      frames.length = 0;
+      framer.feed(text, frames);
+      for (const frame of frames) {
+        yield frame;
+        // Time spent by the consumer is not provider idle time. Comments and
+        // blank data do not reset the deadline; only nonempty data does.
+        if (frame.data && frame.data.trim()) armIdle();
+      }
+    }
+    let tail;
+    try {
+      tail = decoder.decode();
+    } catch {
+      throw new SseFramingError('invalid utf-8 in model stream', 'body_encoding');
+    }
+    if (tail) {
+      frames.length = 0;
+      framer.feed(tail, frames);
+      for (const frame of frames) yield frame;
+    }
+    framer.finish();
+  } finally {
+    disarmIdle();
+    // Fire-and-forget: the fetch abort already errored the body stream, and
+    // awaiting cancel here must not block propagating the IdleTimeout/abort.
+    if (typeof iter.return === 'function') {
+      try { Promise.resolve(iter.return()).catch(() => {}); } catch { /* already closed */ }
+    }
+  }
+}

package/src/native/model-surface-host.mjs

@@ -0,0 +1,27 @@
+import { validateModelSurface } from '@kingsoftcloud/agentkit-harness-core';
+
+/** The tool owner supplies actual roots; neither process.cwd nor ambient host prompt data is a fallback. */
+export function bindNativeModelSurface({ environment, description, original, executionCapabilities } = {}) {
+  const modelSurface = { contract: 'bound-model-surface/v1',
+    ...(original === undefined ? {verificationProjection:'readable-evidence/v1'}
+      : original.verificationProjection ? {verificationProjection:original.verificationProjection} : {}),
+    ...(executionCapabilities === undefined ? {} : { executionCapabilities: structuredClone(executionCapabilities) }),
+    environment: { ...structuredClone(environment),
+    date: original?.environment.date ?? new Date().toISOString().slice(0, 10),
+    supportsImages: description.input.includes('image') } };
+  validateModelSurface(modelSurface);
+  return modelSurface;
+}
+
+/** Preserve content-part indices when exposing the last actual user input to children. */
+export function nativeChildInputMediaSources(rows, admission) {
+  let sources = new Map();
+  rows.forEach(({ message }, index) => {
+    if (admission.messages[index].kind !== 'user_input') return;
+    sources = new Map(); let image = 0;
+    message.content.forEach((part, partIndex) => {
+      if (part.type === 'image' && part.offloaded !== true) sources.set(partIndex, admission.messages[index].media?.[image++]);
+    });
+  });
+  return sources;
+}

package/src/native/model-tool-search-policy.mjs

@@ -0,0 +1,16 @@
+import { invariant } from '@kingsoftcloud/agentkit-harness-core';
+
+// Exact supported model IDs from the provider's tool-search compatibility table.
+// Custom Anthropic endpoints can explicitly declare support in their profile.
+const supported = new Set(['claude-fable-5-1', 'claude-mythos-5-1', 'claude-fable-5', 'claude-mythos-5',
+  'claude-opus-5-5', 'claude-opus-5', 'claude-sonnet-5-5', 'claude-sonnet-5', 'claude-haiku-5-5',
+  'claude-opus-4-8', 'claude-opus-4-7', 'claude-opus-4-6', 'claude-sonnet-4-6',
+  'claude-opus-4-5-20251101', 'claude-sonnet-4-5-20250929', 'claude-haiku-4-5-20251001']);
+
+export function admitProviderToolSearchPolicy({ protocol, model, requested, discovery }) {
+  invariant(requested === undefined || typeof requested === 'boolean', 'native_provider_tool_search_invalid');
+  invariant(requested !== true || protocol === 'anthropic-messages', 'native_provider_tool_search_protocol_unsupported');
+  return protocol === 'anthropic-messages' && discovery && requested !== false
+    && (requested === true || supported.has(String(model).trim().toLowerCase()))
+    ? 'anthropic-deferred/v1' : 'local-only/v1';
+}

package/src/native/model-transport-observation.mjs

@@ -0,0 +1,27 @@
+/** Keep observations outside the model transcript and outside execution policy. */
+export function modelTransportObservation(now = () => performance.now()) {
+  const start = now(), ms = () => Math.max(0, Math.round(now() - start));
+  const facts = { contract: 'model-transport-observation/v1', phase: 'prepare', headersMs: null,
+    bodyChunks: 0, bodyBytes: 0, lastByteMs: null, lastFrameMs: null, lastOutputMs: null, lastToolDeltaMs: null };
+  return {
+    phase: value => { facts.phase = value; },
+    headers: () => { facts.headersMs = ms(); },
+    bytes: size => { if (size > 0) { facts.bodyChunks++;facts.bodyBytes += size;facts.lastByteMs = ms(); } },
+    frame: () => { facts.lastFrameMs = ms(); },
+    output: event => {
+      if (!event?.text) return;
+      facts.lastOutputMs = ms();if (event.kind === 'tool_delta') facts.lastToolDeltaMs = facts.lastOutputMs;
+    },
+    finish: () => ({ ...facts, elapsedMs: ms() }),
+  };
+}
+
+export function observeModelTransportPort(generate) {
+  return { async generate(request, emit) {
+    const observation = modelTransportObservation();
+    const result = await generate(request, event => {
+      observation.output(event);if (typeof emit === 'function') emit(event);
+    }, observation);
+    return { ...result, transportObservation: observation.finish() };
+  } };
+}

package/src/native/owned-child.mjs

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto';
+import { CHILD_OWNER_CONTRACT, canonical, copy, terminal } from '@kingsoftcloud/agentkit-harness-core';
+
+const hash = value => createHash('sha256').update(canonical(value)).digest('hex');
+const same = (left, right) => canonical(left) === canonical(right);
+const identity = value => Object.fromEntries(['scope', 'runId', 'sessionId', 'turnId', 'buildId', 'parentRunId', 'taskChainId']
+  .map(key => [key, copy(value[key])]));
+
+/** A saved decision awaiting consumption is runnable work, not a new request
+ * for approval. This observation grants nothing: the child Kernel still checks
+ * and consumes the original command against its own pending interaction. */
+export function childNeedsApproval(record) {
+  const pending = record.snapshot.pendingInteraction;
+  return record.snapshot.phase === 'awaiting_interaction' && (!pending || !record.commands.some(row => !row.consumed
+    && row.command.kind === 'submit_interaction' && row.command.payload.interactionId === pending?.interactionId
+    && ['allow', 'deny'].includes(row.command.payload.decision)));
+}
+
+export function resolveChildToolIntent(parentRecord, operationKey) {
+  const intent = parentRecord.intents.find(item => item.operationKey === operationKey);
+  if (intent && Array.isArray(intent.payload.calls) && intent.payload.calls.length === 1)
+    return { intent, calls: intent.payload.calls, index: 0, base: operationKey };
+  const match = operationKey.match(/^(.+):call:([1-9][0-9]*)$/);
+  if (!match) return null;
+  const base = match[1], index = Number(match[2]) - 1;
+  const baseIntent = parentRecord.intents.find(item => item.operationKey === base);
+  return baseIntent?.kind === 'tool' && Array.isArray(baseIntent.payload.calls) && baseIntent.payload.calls.length > 1
+    && Number.isSafeInteger(index) && index < baseIntent.payload.calls.length
+    ? { intent: baseIntent, calls: baseIntent.payload.calls, index, base } : null;
+}
+
+/** Locators confer no authority: prove the original causal binding and committed start receipt. */
+export function loadOwnedDirectChild({ store, childScopes, parent, childRunId, roles }) {
+  if (!(parent.childRunIds ?? []).includes(childRunId)) return null;
+  const parentRecord = store.load(parent.scope, parent.runId);
+  for (const childScope of childScopes) {
+    let record;
+    try { record = store.load(childScope, childRunId); }
+    catch (error) { if (error.code === 'run_not_found') continue; throw error; }
+    const binding = record.configuration.childOwnerBinding;
+    if (binding?.contract !== CHILD_OWNER_CONTRACT || !same(record.snapshot.scope, childScope)
+      || !same(binding.parent, identity(parent)) || roles && !roles.includes(binding.role)) continue;
+    const reservation = (parent.childBudgetReservations ?? []).find(item => item.childRunId === childRunId);
+    if (!reservation || !same(reservation.childScope, childScope)
+      || reservation.parentOperationKey !== binding.parentOperationKey || reservation.parentToolCallId !== binding.parentToolCallId
+      || reservation.childRequestDigest !== binding.childRequestDigest || reservation.deliveryMode !== binding.deliveryMode
+      || reservation.configurationDigest !== record.snapshot.configDigest || hash(record.configuration) !== reservation.configurationDigest
+      || reservation.maxModelCalls !== binding.maxModelCalls || reservation.maxToolCalls !== binding.maxToolCalls) continue;
+    const start = resolveChildToolIntent(parentRecord, binding.parentOperationKey), call = start?.calls[start.index];
+    const receipt = parentRecord.receipts.find(item => item.operationKey === start?.base && item.status === 'committed');
+    const original = receipt?.result.results?.[start?.index]?.childBudgetReservation;
+    if (start?.intent.kind !== 'tool' || !call || !['native_start_child', 'native_delegate'].includes(call.name)
+      || call.callId !== binding.parentToolCallId || call.arguments.role !== binding.role
+      || call.arguments.task !== record.configuration.contract.objective
+      || !original || !same(original, { ...reservation, settledUsageDigest: null })) continue;
+    return record;
+  }
+  return null;
+}
+
+export function hasUnsafeChildReceipt(record) {
+  const reconciled = intent => {
+    const original = intent?.kind === 'tool_receipt'
+      ? record.intents.find(row => row.operationKey === intent.payload.originalOperationKey) : intent;
+    const call = original?.payload.calls?.[0];
+    if (original?.kind !== 'tool' || original.status !== 'running' || original.payload.calls.length !== 1
+      || !Number.isSafeInteger(original.claimedFence) || original.claimedFence <= 0
+      || record.configuration.tools.find(tool => tool.name === call.name)?.recoveryPolicy !== 'receipt-observation/v1') return false;
+    if (intent.kind === 'tool_receipt' && (intent.payload.contract !== 'agentkit.tool-receipt-observation/v1'
+      || intent.payload.callId !== call.callId || intent.payload.originalClaimedFence !== original.claimedFence)) return false;
+    return record.intents.some(query => {
+      const p = query.payload;
+      if (query.kind !== 'tool_receipt' || query.status !== 'running' || p.contract !== 'agentkit.tool-receipt-observation/v1'
+        || p.originalOperationKey !== original.operationKey || p.callId !== call.callId || p.originalClaimedFence !== original.claimedFence) return false;
+      const receipt = record.receipts.find(row => row.operationKey === query.operationKey);
+      return receipt?.status === 'committed' && receipt.result.contract === p.contract
+        && receipt.result.originalOperationKey === original.operationKey && receipt.result.callId === call.callId
+        && ['ok', 'error'].includes(receipt.result.result?.status);
+    });
+  };
+  return record.receipts.some(receipt => receipt.status === 'uncertain'
+    && !(receipt.result.retryScheduled === true && ['safe-read/v1', 'workspace-observation/v1'].includes(receipt.result.recoveryPolicy))
+    && record.intents.find(intent => intent.operationKey === receipt.operationKey)?.kind !== 'model'
+    && !reconciled(record.intents.find(intent => intent.operationKey === receipt.operationKey)));
+}
+
+/** A settled marker alone cannot authorize delivery or reuse of a Session. */
+export function accountedChildDelivery(parentRecord, childRecord) {
+  const child = childRecord.snapshot;
+  if (!terminal(child.phase) || child.phase === 'interrupted' || hasUnsafeChildReceipt(childRecord)) return null;
+  const reservation = parentRecord.snapshot.childBudgetReservations.find(item => item.childRunId === child.runId);
+  if (!reservation?.settledUsageDigest) return null;
+  return parentRecord.receipts.filter(receipt => receipt.status === 'committed').flatMap(receipt => receipt.result.results ?? [])
+    .find(result => result.childBudgetSettlement?.childRunId === child.runId
+      && result.childBudgetSettlement.terminalSnapshotDigest === hash(child)
+      && hash({ settlement: result.childBudgetSettlement, usage: result.resourceUsage, childRunIds: result.childRunIds })
+        === reservation.settledUsageDigest) ?? null;
+}
+
+/** Only terminal ancestors in this exact parent Session may grant their original child. */
+export function loadSessionChild({ store, childScopes, parent, childRunId }) {
+  const seen = new Set();
+  for (let cursor = parent; cursor && !seen.has(cursor.runId);) {
+    seen.add(cursor.runId);
+    const child = loadOwnedDirectChild({ store, childScopes, parent: cursor, childRunId });
+    if (child) return { child, parent: store.load(cursor.scope, cursor.runId) };
+    if (!cursor.parentRunId) return null;
+    const previous = store.load(parent.scope, cursor.parentRunId);
+    if (!same(previous.snapshot.scope, parent.scope) || previous.snapshot.sessionId !== parent.sessionId
+      || !terminal(previous.snapshot.phase)) return null;
+    cursor = previous.snapshot;
+  }
+  return null;
+}

package/src/native/owned-command.mjs

@@ -0,0 +1,106 @@
+import { canonical, copy, backgroundCommandRef, NativeError } from '@kingsoftcloud/agentkit-harness-core';
+const check = (value, code) => { if (!value) throw new NativeError(code); };
+const same = (a, b) => canonical(a) === canonical(b);
+export const OWNED_COMMAND_OUTPUT_CONTRACT = 'agentkit.owned-command-output/v1';
+
+/** Authenticated Hosts may page an existing process without manufacturing a
+ * model tool call. Every read is bound to the current session head and the
+ * original committed launch receipt, including reads after a Host restart.
+ * Readers have no launch/cancel capability. Raw output still requires the
+ * Host's operator-output disclosure policy before publication.
+ */
+export function createOwnedCommandOutputReader({ scope, store, readers = {}, isClosed = () => false }) {
+  const pinned = copy(scope), bindings = Object.fromEntries(Object.entries(readers));
+  check(typeof isClosed === 'function' && Object.entries(bindings).every(([name, reader]) =>
+    ['local_process', 'e2b'].includes(name) && typeof reader === 'function'), 'invalid_command_output_readers');
+  return Object.freeze({ contract: OWNED_COMMAND_OUTPUT_CONTRACT, async read(request) {
+    const signal = request?.signal;
+    check(signal instanceof AbortSignal, 'command_output_signal_invalid');
+    const { signal: _, ...body } = request, sealed = canonical(body);
+    check(Object.keys(body).every(key => ['contract', 'scope', 'runId', 'sessionId', 'taskId', 'stdoutCursor', 'stderrCursor', 'maxBytes'].includes(key))
+      && body.contract === OWNED_COMMAND_OUTPUT_CONTRACT && same(body.scope, pinned)
+      && ['runId', 'sessionId'].every(key => typeof body[key] === 'string' && body[key].trim())
+      && /^[a-f0-9]{64}$/.test(body.taskId)
+      && [body.stdoutCursor, body.stderrCursor].every(cursor => Number.isSafeInteger(cursor) && cursor >= 0)
+      && Number.isSafeInteger(body.maxBytes) && body.maxBytes >= 4 && body.maxBytes <= 65536,
+    'command_output_request_invalid');
+    const current = () => {
+      signal.throwIfAborted(); check(isClosed() === false, 'command_output_closed');
+      const { signal: liveSignal, ...live } = request;
+      check(liveSignal === signal && canonical(live) === sealed, 'command_output_request_changed');
+      const head = store.sessionHead(pinned, body.sessionId);
+      check(head?.runId === body.runId, 'command_output_head_changed');
+      const record = store.load(pinned, body.runId);
+      check(record.snapshot.sessionId === body.sessionId && same(record.snapshot.scope, pinned), 'command_output_owner_mismatch');
+      const matches = record.snapshot.backgroundCommands.filter(row => row.ref.taskId === body.taskId);
+      check(matches.length === 1 && head.backgroundCommands.some(row => same(row.ref, matches[0].ref)), 'background_command_not_owned');
+      return ownedCommandReceipt({ scope: pinned, store, current: record, ref: matches[0].ref, includeCommand: true });
+    };
+    const owner = current(), reader = bindings[owner.backend];
+    check(reader, 'command_output_backend_unavailable');
+    const output = await reader({ scope: copy(pinned), sessionId: body.sessionId, runId: body.runId,
+      ref: copy(owner.ref), stdoutCursor: body.stdoutCursor, stderrCursor: body.stderrCursor,
+      maxBytes: body.maxBytes, waitSeconds: 0, signal });
+    check(same(current(), owner), 'command_output_owner_changed');
+    check(output && typeof output === 'object' && !Array.isArray(output)
+      && ['starting', 'running', 'completed', 'failed', 'canceled', 'timed_out', 'output_limit', 'unknown', 'unavailable'].includes(output.status),
+    'command_output_invalid');
+    for (const channel of ['stdout', 'stderr']) {
+      check(typeof output[channel] === 'string' && Buffer.byteLength(output[channel]) <= body.maxBytes
+        && Number.isSafeInteger(output[channel + 'Cursor']) && output[channel + 'Cursor'] >= body[channel + 'Cursor']
+        && output[channel + 'Cursor'] - body[channel + 'Cursor'] === Buffer.byteLength(output[channel]), 'command_output_cursor_invalid');
+    }
+    check((output.exitCode == null || Number.isSafeInteger(output.exitCode))
+      && (output.observedExitCode == null || Number.isSafeInteger(output.observedExitCode))
+      && [output.outputMayBeTruncated, output.evidenceIncomplete].every(value => value === undefined || typeof value === 'boolean'),
+    'command_output_invalid');
+    const settled = ['completed', 'failed', 'canceled', 'timed_out', 'output_limit'].includes(output.status);
+    return { contract: OWNED_COMMAND_OUTPUT_CONTRACT, sessionId: body.sessionId, runId: body.runId, taskId: body.taskId,
+      command: owner.command, status: output.status, stdout: output.stdout, stderr: output.stderr,
+      stdoutCursor: output.stdoutCursor, stderrCursor: output.stderrCursor,
+      exitCode: settled && output.evidenceIncomplete !== true ? output.exitCode ?? null : null,
+      observedExitCode: output.observedExitCode ?? null, evidenceIncomplete: output.evidenceIncomplete === true,
+      outputMayBeTruncated: output.outputMayBeTruncated === true };
+  } });
+}
+
+/** The backend is a fact in the canonical launch receipt, never a model hint. */
+export function ownedCommandReceipt({ scope, store, current, ref: input, includeCommand = false }) {
+  const ref = backgroundCommandRef(input), source = store.load(scope, ref.sourceRunId);
+  const receipt = source.receipts.find(item => item.operationKey === ref.operationKey);
+  const launch = source.intents.find(item => item.operationKey === ref.operationKey);
+  const calls = launch?.payload.calls, results = receipt?.result.results;
+  const result = Array.isArray(results) && results.length === 1 ? results[0] : null;
+  const definition = Array.isArray(calls) && calls.length === 1
+    ? source.configuration.tools.find(tool => tool.name === calls[0].name) : null;
+  check(same(source.snapshot.scope, scope) && source.snapshot.sessionId === current.snapshot.sessionId
+    && receipt?.status === 'committed' && launch?.kind === 'tool'
+    && definition?.backgroundCommandPolicy === 'owned-command-launch/v1' && result?.status === 'ok'
+    && same(result.backgroundCommandRef ?? null, ref), 'background_command_launcher_receipt_mismatch');
+  const backend = typeof result.content?.backend === 'string' && result.content.backend.startsWith('sandbox/')
+    ? result.content.backend.slice('sandbox/'.length) : null;
+  return { ref, backend: ['local_process', 'e2b'].includes(backend) ? backend : null,
+    ...(includeCommand ? { command: typeof calls[0].arguments?.command === 'string' ? calls[0].arguments.command.slice(0, 32768) : '' } : {}) };
+}
+
+/** Resolve read/stop authority from the current claimed Native tool operation.
+ * Inherited session handles retain their original source run and receipt.
+ */
+export function createOwnedCommandResolver({ scope, store }) {
+  const pinnedScope = copy(scope);
+  return (request, taskId) => {
+    request.signal.throwIfAborted();
+    check(same(request.scope, pinnedScope), 'background_command_scope_mismatch');
+    const current = store.load(pinnedScope, request.runId), snapshot = current.snapshot;
+    check(['sessionId', 'turnId', 'buildId', 'parentRunId', 'taskChainId'].every(key => request[key] === snapshot[key]),
+      'background_command_owner_mismatch');
+    const intent = current.intents.find(item => item.operationKey === snapshot.pendingIntent), calls = intent?.payload.calls;
+    const index = Array.isArray(calls) ? calls.findIndex(call => same(call, request.call)) : -1;
+    check(intent?.kind === 'tool' && intent.status === 'running' && index >= 0
+      && request.operationKey === (calls.length === 1 ? intent.operationKey : `${intent.operationKey}:call:${index + 1}`),
+    'background_command_tool_operation_mismatch');
+    const matches = snapshot.backgroundCommands.filter(item => item.ref.taskId === taskId);
+    check(matches.length === 1, 'background_command_not_owned');
+    return ownedCommandReceipt({ scope: pinnedScope, store, current, ref: matches[0].ref });
+  };
+}

package/src/native/python-syntax-worker.mjs

@@ -0,0 +1,60 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { Workspace, PositionEncoding } from '@astral-sh/ruff-wasm-nodejs';
+import { NATIVE_PYTHON_SYNTAX } from './python-syntax.mjs';
+
+if (Workspace.version() !== NATIVE_PYTHON_SYNTAX.parserVersion) throw new Error('Python parser version mismatch');
+const workspace = new Workspace({ 'target-version': NATIVE_PYTHON_SYNTAX.targetVersion,
+  lint: { select: [] } }, PositionEncoding.Utf32);
+const bytes = Buffer.from(workerData, 'utf8');
+function issueAt(start, message) {
+  const lines = bytes.subarray(0, start).toString('utf8').replace(/\r\n?/g, '\n').split('\n');
+  return [{ severity: 'error', line: lines.length, column: Array.from(lines.at(-1)).length + 1, message }];
+}
+let issues;
+try {
+  const nul = bytes.indexOf(0);
+  if (nul !== -1) issues = issueAt(nul, 'Source code cannot contain NUL bytes.');
+  // `check` also performs compile-time checks even with no lint rules selected:
+  // duplicate parameters, module nonlocal, unreachable match cases, etc.
+  // CPython ast.parse deliberately permits these. `comments` first calls the
+  // strict grammar parser, without those later scoping/compilation checks.
+  try { if (!issues) workspace.comments(workerData); }
+  catch (error) {
+    const match = /^(.*) at byte range (\d+)\.\.(\d+)$/s.exec(error.message);
+    if (!match) throw error;
+    const start = Number(match[2]);
+    if (!Number.isSafeInteger(start) || start > bytes.length) throw error;
+    issues = issueAt(start, match[1]);
+  }
+  if (!issues) {
+    // Ruff exposes token kind/byte ranges as a debug string in this pinned
+    // WASM API. Source lexing remains in Rust: digits in strings/comments,
+    // floats, imaginaries and base-prefixed integers never count as decimal
+    // integer tokens. Preserve CPython 3.12's default conversion/token limits.
+    let nesting = 0, indent = 0;
+    const tokens = workspace.tokens(workerData);
+    for (const match of tokens.matchAll(/^\s+(Int|Lpar|Rpar|Lsqb|Rsqb|Lbrace|Rbrace|Indent|Dedent) (\d+)\.\.(\d+),?$/gm)) {
+      const [, kind, from, to] = match, start = Number(from), end = Number(to);
+      if (end < start || end > bytes.length) throw new Error('Python token range invalid');
+      let message;
+      if (kind === 'Int') {
+        const token = bytes.subarray(start, end).toString('utf8');
+        if (/^[0-9][0-9_]*$/.test(token) && token.replaceAll('_', '').length > NATIVE_PYTHON_SYNTAX.decimalDigitLimit)
+          message = 'Decimal integer exceeds the 4300-digit limit.';
+      } else if (['Lpar', 'Lsqb', 'Lbrace'].includes(kind)) {
+        if (++nesting > NATIVE_PYTHON_SYNTAX.nestingLimit) message = 'Too many nested parentheses.';
+      } else if (['Rpar', 'Rsqb', 'Rbrace'].includes(kind)) nesting--;
+      else if (kind === 'Indent') {
+        if (++indent > NATIVE_PYTHON_SYNTAX.indentLimit) message = 'Too many levels of indentation.';
+      } else if (kind === 'Dedent') indent--;
+      if (message) { issues = issueAt(start, message); break; }
+    }
+  }
+  // The grammar-only API parses the latest grammar. Keep its version gates
+  // from `check`, but never promote compile-time diagnostics to ast.parse.
+  if (!issues) issues = workspace.check(workerData)
+    .filter(item => / on Python 3\.12 \(syntax was added in Python 3\.\d+\)$/.test(item.message))
+    .slice(0, 1).map(item => ({ severity: 'error', line: item.start_location.row,
+      column: item.start_location.column, message: item.message }));
+  parentPort.postMessage({ contract: NATIVE_PYTHON_SYNTAX.contract, issues });
+} finally { workspace.free(); parentPort.close(); }

package/src/native/python-syntax.mjs

@@ -0,0 +1,50 @@
+import { Worker } from 'node:worker_threads';
+
+export const NATIVE_PYTHON_SYNTAX = Object.freeze({
+  contract: 'agentkit.python-ast-syntax/v1',
+  parser: 'ruff-wasm', parserVersion: '0.16.8', targetVersion: 'py312', mode: 'ast-only',
+  decimalDigitLimit: 4300, nestingLimit: 200, indentLimit: 99,
+});
+const failure = (code, message) => Object.assign(new Error(message), { code });
+
+/** Parse captured source, never a path, project configuration or executable.
+ * A fresh worker bounds each parse's lifetime and keeps malformed source from
+ * blocking the Host. V8 limits do not cap WASM linear memory; the input limit
+ * and terminated worker are additional resource boundaries, not a sandbox.
+ */
+export async function checkPythonSyntax(source, { signal, timeoutMs = 10000 } = {}) {
+  signal?.throwIfAborted();
+  if (typeof source !== 'string' || Buffer.byteLength(source, 'utf8') > 2 * 1024 * 1024)
+    throw failure('python_syntax_input_invalid', 'Python source exceeds the workspace text limit.');
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 10000)
+    throw failure('python_syntax_deadline_invalid', 'Invalid Python syntax deadline.');
+  let worker;
+  try { worker = new Worker(new URL('./python-syntax-worker.mjs', import.meta.url), {
+    workerData: source, execArgv: [],
+    resourceLimits: { maxOldGenerationSizeMb: 128, maxYoungGenerationSizeMb: 16, stackSizeMb: 4 },
+  }); } catch { throw failure('python_syntax_unavailable', 'The Node Python syntax parser could not start.'); }
+  return await new Promise((resolve, reject) => {
+    let output, error, stopping = false;
+    const stop = reason => {
+      if (stopping) return;
+      stopping = true; error = reason;
+      // Settle only at exit, after the parser can no longer consume resources.
+      void worker.terminate().catch(() => {});
+    };
+    const abort = () => stop(signal.reason ?? failure('python_syntax_cancelled', 'Python syntax check cancelled.'));
+    const timer = setTimeout(() => stop(failure('python_syntax_timeout', 'Python syntax check timed out.')), timeoutMs);
+    signal?.addEventListener('abort', abort, { once: true });
+    worker.once('message', value => { output = value; });
+    worker.once('error', () => stop(failure('python_syntax_unavailable', 'The Node Python syntax parser failed.')));
+    worker.once('exit', code => {
+      clearTimeout(timer); signal?.removeEventListener('abort', abort);
+      if (error) return reject(error);
+      if (code !== 0 || output?.contract !== NATIVE_PYTHON_SYNTAX.contract || !Array.isArray(output.issues)
+        || output.issues.some(issue => issue?.severity !== 'error' || !Number.isSafeInteger(issue.line) || issue.line < 1
+          || !Number.isSafeInteger(issue.column) || issue.column < 1 || typeof issue.message !== 'string' || !issue.message))
+        return reject(failure('python_syntax_unavailable', 'The Node Python syntax parser returned no valid result.'));
+      resolve(output.issues);
+    });
+    if (signal?.aborted) abort();
+  });
+}

package/src/native/read-interruption.mjs

@@ -0,0 +1,16 @@
+import { safeReadRecoveryCalls } from '@kingsoftcloud/agentkit-harness-core';
+
+/** Classify an original complete ledger, never a presentation read model. */
+export function canCloseNativeReadInterruption(record) {
+  if (!record || record.snapshot.phase !== 'interrupted' || record.snapshot.reason !== 'effect_outcome_unknown'
+    || record.snapshot.pendingIntent || record.snapshot.toolReconciliation
+    || record.snapshot.children?.length || record.snapshot.backgroundCommands?.length
+    || record.snapshot.childBudgetReservations?.some(row => row.settledUsageDigest === null)) return false;
+  const unknown = record.receipts.filter(receipt => receipt.status === 'uncertain'
+    || receipt.result.results?.some(result => result.status === 'uncertain'));
+  return unknown.length > 0 && unknown.every(receipt => {
+    const intent = record.intents.find(item => item.operationKey === receipt.operationKey);
+    return intent?.kind === 'tool' && safeReadRecoveryCalls(intent.payload.calls, record.configuration);
+  }) && !record.intents.some(intent => ['tool', 'hook', 'child', 'input'].includes(intent.kind)
+    && intent.status === 'running' && !record.receipts.some(receipt => receipt.operationKey === intent.operationKey));
+}