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

package/src/native/child-history.mjs

@@ -0,0 +1,188 @@
+import { nativeChildObservation, nativeChildActivity } from './child-observation.mjs';
+import { nativeDeliveryId } from './delivery-timeline.mjs';
+import { createHash } from 'node:crypto';
+import { addUsage, canonical, copy, invariant, scopeKey, terminal, CHILD_OWNER_CONTRACT } from '@kingsoftcloud/agentkit-harness-core';
+import { accountedChildDelivery, loadOwnedDirectChild } from './owned-child.mjs';
+
+export const NATIVE_CHILD_HISTORY_CONTRACT = 'agentkit.studio-native-child-history/v1';
+const hash = value => createHash('sha256').update(canonical(value)).digest('hex');
+const id = value => typeof value === 'string' && value.trim() && value.length <= 256;
+
+function pageInventory(request, inventory) {
+  const offset = request.offset ?? 0, limit = request.limit ?? 16;
+  invariant(Number.isSafeInteger(offset) && offset >= 0 && Number.isSafeInteger(limit) && limit >= 1 && limit <= 64
+    && (request.inventoryDigest === undefined || typeof request.inventoryDigest === 'string'
+      && /^[0-9a-f]{64}$/.test(request.inventoryDigest)), 'child_history_query_invalid');
+  invariant((!offset || request.inventoryDigest)
+    && (request.inventoryDigest === undefined || request.inventoryDigest === inventory.inventoryDigest), 'child_history_inventory_changed');
+  invariant(offset <= inventory.tasks.length, 'child_history_offset_invalid');
+  const tasks = inventory.tasks.slice(offset, offset + limit), nextOffset = offset + tasks.length;
+  return { ...inventory, tasks, totalTasks: inventory.tasks.length, offset, nextOffset, complete: nextOffset === inventory.tasks.length };
+}
+
+/** Combine inventories supplied by trusted owners, never caller-selected stores
+ * or principals. Keep each owner's ancestry order; the current owner comes first.
+ * The digest binds every source, including heads without children. */
+export function mergeNativeChildHistory(request, inventories) {
+  invariant(id(request.sessionId) && request.runId === undefined && Array.isArray(inventories) && inventories.length > 0,
+    'child_history_query_invalid');
+  invariant(inventories.every(value => value.contract === NATIVE_CHILD_HISTORY_CONTRACT
+    && value.sessionId === request.sessionId && (value.runId === null || id(value.runId)) && Array.isArray(value.tasks)),
+  'child_history_ancestry_invalid');
+  const present = inventories.filter(value => value.runId !== null);
+  if (present.length <= 1) return pageInventory(request, present[0] ?? inventories[0]);
+  const tasks = present.flatMap(value => value.tasks), runId = present[0].runId;
+  // A public child ID must resolve to exactly one owner. Never silently choose
+  // one ledger on collision or copy controls onto another owner's history.
+  invariant(new Set(tasks.map(task => task.childRunId)).size === tasks.length, 'child_history_ancestry_invalid');
+  const parents = new Set();
+  for (const source of present) {
+    const sourceParents = new Set([source.runId, ...source.tasks.map(task => task.parentRunId)]);
+    invariant([...sourceParents].every(parent => !parents.has(parent)), 'child_history_ancestry_invalid');
+    for (const parent of sourceParents) parents.add(parent);
+  }
+  const selected = tasks.map(task => task.parentRunId === runId ? task
+    : { ...task, canPromote: false, canCancel: false, canSendInput: false });
+  return pageInventory(request, { contract: NATIVE_CHILD_HISTORY_CONTRACT, sessionId: request.sessionId, runId,
+    inventoryDigest: hash({ contract: 'agentkit.native-child-inventory-merge/v1', sessionId: request.sessionId,
+      sources: present.map(value => [value.runId, value.inventoryDigest]) }), tasks: selected });
+}
+
+/** Read-only product history. No Kernel, factories, leases, commands or accounting writes. */
+export function createNativeChildHistory({ scope, store, liveTasks = () => [], liveObservation = () => null }) {
+  scopeKey(scope);
+  const hierarchy = request => {
+    invariant(id(request.sessionId) && (request.runId === undefined || id(request.runId)), 'child_history_query_invalid');
+    const head = store.sessionHead(scope, request.sessionId), parents = [], seen = new Set();
+    if (!head) {
+      invariant(request.runId === undefined, 'child_history_run_unavailable');
+      return { head: null, parents };
+    }
+    const authority = runId => store.authority?.(scope, runId) ?? store.load(scope, runId);
+    let parent = authority(head.runId), cursor = parent.snapshot;
+    while (cursor) {
+      invariant(!seen.has(cursor.runId) && cursor.sessionId === request.sessionId
+        && canonical(cursor.scope) === canonical(scope), 'child_history_ancestry_invalid');
+      seen.add(cursor.runId);
+      invariant(hash(parent.configuration) === cursor.configDigest, 'stored_configuration_mismatch');
+      parents.push(parent);
+      if (!cursor.parentRunId) break;
+      parent = authority(cursor.parentRunId); cursor = parent.snapshot;
+      invariant(terminal(cursor.phase), 'child_history_ancestry_invalid');
+    }
+    if (request.runId !== undefined) {
+      const index = parents.findIndex(parent => parent.snapshot.runId === request.runId);
+      invariant(index >= 0, 'child_history_run_unavailable');
+      return { head: parents[index].snapshot, parents: parents.slice(index) };
+    }
+    return { head, parents };
+  };
+  const inventory = request => {
+    const { head, parents } = hierarchy(request), records = [];
+    for (const view of parents) {
+      const active = view.snapshot.runId === head?.runId ? liveTasks(view.snapshot.runId) : [];
+      const roles = [...new Set(view.configuration.tools.filter(tool => ['start/v1', 'delegate/v1'].includes(tool.childBudgetPolicy))
+        .flatMap(tool => tool.parameters.properties?.role?.enum ?? []))];
+      invariant(roles.every(role => typeof role === 'string' && /^[a-z0-9][a-z0-9_-]{0,63}$/.test(role)), 'child_history_roles_invalid');
+      // Browsing an empty child directory needs lineage authority, not every
+      // historical model result and screenshot. Only actual child observations
+      // materialize the journal needed to authenticate their settled delivery.
+      if (!(view.snapshot.childRunIds ?? []).length && !active.length) continue;
+      const parent = store.load(scope, view.snapshot.runId);
+      invariant(parent.snapshot.sessionId === request.sessionId
+        && parent.snapshot.configDigest === view.snapshot.configDigest
+        && canonical(parent.snapshot.scope) === canonical(scope), 'child_history_ancestry_invalid');
+      // Historical grants come from the frozen original tool, never current
+      // model arguments or a caller-provided child scope/role.
+      const childScopes = roles.map(role => ({ ...scope, agentId: `${scope.agentId}:child:${role}` }));
+      const children = [], descendants = new Set();
+      for (const childRunId of parent.snapshot.childRunIds ?? []) {
+        const child = loadOwnedDirectChild({ store, childScopes, parent: parent.snapshot, childRunId, roles });
+        if (child) { children.push(child); for (const runId of child.snapshot.childRunIds ?? []) descendants.add(runId); }
+      }
+      const direct = new Set(children.map(child => child.snapshot.runId));
+      invariant((parent.snapshot.childRunIds ?? []).every(runId => direct.has(runId) || descendants.has(runId)), 'child_history_not_available');
+      // The owning Kernel can authenticate a start before its parent receipt
+      // commits. Such a row has controls, but never a settled delivery.
+      for (const task of active) if (!direct.has(task.childRunId)) {
+        const childScope = childScopes.find(item => item.agentId === `${scope.agentId}:child:${task.role}`);
+        invariant(childScope, 'child_history_not_available');
+        const child = store.load(childScope, task.childRunId);
+        invariant(hash(child.configuration) === child.snapshot.configDigest, 'stored_configuration_mismatch');
+        children.push(child); direct.add(task.childRunId);
+      }
+      for (const child of children) records.push({ parent, child, control: active.find(task => task.childRunId === child.snapshot.runId) });
+    }
+    return { head, records };
+  };
+  const taskRow = ({ parent, child, control }) => {
+    const snapshot = child.snapshot, binding = child.configuration.childOwnerBinding;
+    const accounted = Boolean(accountedChildDelivery(parent, child));
+    const command = parent.commands.filter(row => ['message_child', 'cancel_child', 'promote_child'].includes(row.command.kind)
+      && row.command.payload.childRunId === snapshot.runId).at(-1);
+    const applied = command && parent.events.find(event => event.kind === 'command.applied' && event.payload.commandId === command.command.commandId);
+    const lastControl = command ? { commandId: command.command.commandId, action: command.command.kind,
+      status: !command.consumed ? 'pending' : ['queued', 'applied'].includes(applied?.payload.reason) ? 'delivered' : 'rejected',
+      reason: applied?.payload.reason ?? (command.consumed ? 'parent_run_ended' : null) } : null;
+    const a2aTasks = child.intents.filter(intent => intent.kind === 'tool').flatMap(intent => (intent.payload.calls ?? [])
+      .filter(call => call.name === 'call_a2a_agent').map(call => ({ runId: parent.snapshot.runId, childRunId: snapshot.runId,
+        childAgentId: snapshot.scope.agentId, childSessionId: snapshot.sessionId, operationKey: intent.operationKey, callId: call.callId })));
+    return { parentToolCallId: nativeDeliveryId(parent.snapshot.scope, parent.snapshot.runId, `call:${binding.parentToolCallId}`),
+      childRunId: snapshot.runId, sessionId: snapshot.sessionId, parentRunId: parent.snapshot.runId,
+      ...(a2aTasks.length ? { a2aTasks } : {}),
+      role: binding.role, phase: snapshot.phase, outcome: snapshot.outcome, reason: snapshot.reason,
+      activity: nativeChildActivity(child),
+      delivery: control?.delivery ?? (binding.deliveryMode === 'foreground'
+        && !(parent.snapshot.promotedChildRunIds ?? []).includes(snapshot.runId) ? 'foreground' : 'background'),
+      canPromote: control?.canPromote === true, canCancel: control?.canCancel === true, canSendInput: control?.canSendInput === true,
+      goalRevision: snapshot.goalRevision,
+      lastControl,
+      goalPreview: [...snapshot.goal].slice(0, 256).join(''), goalComplete: [...snapshot.goal].length <= 256,
+      snapshotRevision: snapshot.revision, resultAvailable: accounted,
+      usage: addUsage(snapshot.usage, snapshot.descendantUsage),
+      usageComplete: terminal(snapshot.phase) && snapshot.diagnostics.providerUsageIncomplete !== true && snapshot.diagnostics.descendantUsageIncomplete !== true,
+      usageIncludedInParent: accounted, continuationOf: binding.continuationOf ?? null, buildId: snapshot.buildId };
+  };
+  const readInventory = request => {
+    const { head, records } = inventory(request);
+    return { contract: NATIVE_CHILD_HISTORY_CONTRACT, sessionId: request.sessionId, runId: head?.runId ?? null,
+      inventoryDigest: hash({ scope, sessionId: request.sessionId, runId: head?.runId ?? null,
+        children: records.map(({ parent, child }) => [parent.snapshot.runId, child.snapshot.runId]) }), tasks: records.map(taskRow) };
+  };
+  return {
+    // Trusted Host composition only; public transports expose bounded list/result.
+    inventory: readInventory,
+    // Trusted Host fact lookup. Public list/result responses never expose the
+    // full record, and a current parent's lookup cannot select an ancestor's child.
+    record(request) {
+      invariant(id(request.childRunId), 'child_history_query_invalid');
+      const { head, records } = inventory(request);
+      const found = records.find(({ parent, child }) => parent.snapshot.runId === head?.runId && child.snapshot.runId === request.childRunId);
+      invariant(found, 'child_history_result_unavailable');
+      const binding = found.child.configuration.childOwnerBinding, parent = found.parent.snapshot;
+      invariant(binding?.contract === CHILD_OWNER_CONTRACT
+        && canonical(binding.parent) === canonical(Object.fromEntries(['scope', 'runId', 'sessionId', 'turnId', 'buildId', 'parentRunId', 'taskChainId']
+          .map(key => [key, parent[key]])))
+        && canonical(found.child.snapshot.scope) === canonical({ ...scope, agentId: `${scope.agentId}:child:${binding.role}` }),
+      'child_history_ancestry_invalid');
+      return copy(found.child);
+    },
+    list(request) {
+      return pageInventory(request, readInventory(request));
+    },
+    result(request) {
+      const offset = request.offset ?? 0, limit = request.limit ?? 4000;
+      invariant(id(request.childRunId) && Number.isSafeInteger(offset) && offset >= 0
+        && Number.isSafeInteger(limit) && limit >= 1 && limit <= 16000, 'child_history_query_invalid');
+      const { head, records } = inventory(request), found = records.find(({ child }) => child.snapshot.runId === request.childRunId);
+      invariant(found, 'child_history_result_unavailable');
+      const task = taskRow(found), chars = task.resultAvailable ? [...found.child.snapshot.finalText] : [];
+      invariant(offset <= chars.length, 'child_history_offset_invalid');
+      const text = chars.slice(offset, offset + limit).join(''), nextOffset = offset + [...text].length;
+      return { contract: NATIVE_CHILD_HISTORY_CONTRACT, sessionId: request.sessionId, runId: head.runId,
+        observation: nativeChildObservation(found.child, liveObservation(found.child)),
+        task, text, totalChars: chars.length, offset, nextOffset, complete: nextOffset === chars.length,
+        resultDigest: task.resultAvailable ? hash(found.child.snapshot.finalText) : null, parentAcceptance: 'not_evaluated' };
+    },
+  };
+}

package/src/native/child-merge.mjs

@@ -0,0 +1,98 @@
+import { canonical, copy, invariant, toolInputRejection, matchesToolExecutionContract } from '@kingsoftcloud/agentkit-harness-core';
+import { loadSessionChild, accountedChildDelivery } from '@kingsoftcloud/agentkit-harness-node/native/owned-child';
+import { createNativeToolAuthority } from './tool-authority.mjs';
+
+export const STUDIO_NATIVE_CHILD_MERGE = 'native.child-file-merge/v2';
+export function nativeChildMergeDefinition() {
+  return { name: 'native_child_merge',
+    description: 'Merge the isolated files of an accounted completed writing child into the parent workspace. Conflicts publish nothing. Inspect partial or unknown publication before continuing. Child findings and merged files do not verify the parent task.',
+    parameters: { type: 'object', additionalProperties: false, required: ['child_run_id'],
+      properties: { child_run_id: { type: 'string', minLength: 1, maxLength: 256 } } },
+    readOnly: false, concurrentSafe: false, permissions: ['workspace:write'], timeoutMs: 120000,
+    contextRole: 'none', observationRole: 'none', progressObservation: false, contextRetention: 'normal' };
+}
+
+/** Called only inside the admitted Host tool pipeline. The Native ledger is
+ * still checked independently, including after the synchronous filesystem lock. */
+export function createStudioNativeChildMerge({ scope, sessionId, store, roles, fileWorkspaces,
+  previousPublication, authorize, isClosed = () => false }) {
+  invariant(fileWorkspaces && typeof previousPublication === 'function' && typeof authorize === 'function',
+    'studio_native_child_merge_binding_missing');
+  const boundScope = copy(scope), boundRoles = copy(roles);
+  const childScopes = boundRoles.map(role => ({ ...boundScope, agentId: `${boundScope.agentId}:child:${role.name}` }));
+  const byRole = new Map(boundRoles.map(role => [role.name, role]));
+  const definition = nativeChildMergeDefinition();
+  const authority = createNativeToolAuthority({ scope: boundScope, sessionId, store, isClosed });
+  const error = code => ({ status: 'error', content: { error_code: code, executed: false } });
+  return { definition: copy(definition), contract: STUDIO_NATIVE_CHILD_MERGE,
+    async execute(request) {
+      const signal = request?.signal;
+      const body = () => { const value = { ...request }; delete value.signal; return value; };
+      let snapshot;
+      try { snapshot = canonical(body()); }
+      catch { return error('child_merge_identity_invalid'); }
+      let childCurrent = () => true;
+      const guard = () => {
+        try {
+          return request.signal === signal && signal instanceof AbortSignal && !signal.aborted
+            && canonical(body()) === snapshot
+            && matchesToolExecutionContract(request.definition, definition) && authority(request) && childCurrent()
+            && (() => {
+              const current = store.load(boundScope, request.runId);
+              const allowed = (current.snapshot.taskContract ?? current.configuration.contract).allowedToolNames;
+              return allowed == null || Array.isArray(allowed) && allowed.includes(definition.name);
+            })();
+        } catch { return false; }
+      };
+      if (!guard()) return error('child_merge_authority_lost');
+      const rejection = toolInputRejection(definition, request.call);
+      if (rejection) return { status: 'error', content: rejection };
+      const original = copy({ scope: request.scope, runId: request.runId, sessionId, operationKey: request.operationKey,
+        child_run_id: request.call.arguments.child_run_id });
+      let publicationStarted = false;
+      const uncertain = (code, applied = []) => ({ status: 'uncertain', workspaceChangedPaths: [...applied],
+        content: { schema_version: STUDIO_NATIVE_CHILD_MERGE, error_code: code, ...original, applied: [...applied],
+          instruction: 'Inspect the original child and parent files and the saved operation before continuing. Do not repeat an unknown publication automatically.' } });
+      try {
+        const decision = await authorize({ ...copy(body()), signal });
+        if (!guard()) return error('child_merge_authority_lost');
+        if (decision !== 'allow') return decision?.status === 'approval_required' && typeof decision.interactionId === 'string'
+          && decision.interactionId ? decision : error('child_merge_permission_denied');
+        const parent = store.load(boundScope, request.runId).snapshot;
+        const resolved = loadSessionChild({ store, childScopes, parent, childRunId: original.child_run_id });
+        if (!resolved || !accountedChildDelivery(resolved.parent, resolved.child)) return error('child_not_accounted');
+        const child = resolved.child, childSnapshot = child.snapshot;
+        const role = byRole.get(child.configuration.childOwnerBinding?.role);
+        const writing = role?.tools.some(name => ['write_workspace_file', 'write_workspace_files', 'edit_workspace_file',
+          'multi_edit_workspace_file', 'delete_workspace_file', 'apply_workspace_patch', 'rewind_workspace_files'].includes(name));
+        const head = store.sessionHead(childSnapshot.scope, childSnapshot.sessionId);
+        if (!writing || role.concurrentSafe || childSnapshot.phase !== 'completed'
+          || ['failed', 'blocked', 'budget_exhausted'].includes(childSnapshot.outcome)
+          || head?.runId !== childSnapshot.runId || !childSnapshot.workspaceRevision) return error('child_merge_unavailable');
+        const childSeal = canonical(childSnapshot);
+        childCurrent = () => store.sessionHead(childSnapshot.scope, childSnapshot.sessionId)?.runId === childSnapshot.runId
+          && canonical(store.load(childSnapshot.scope, childSnapshot.runId).snapshot) === childSeal;
+        const expectedBinding = child.configuration.hostRecoveryBinding?.childWorkspace;
+        if (!expectedBinding) return error('child_workspace_unbound');
+        const bound = fileWorkspaces.bind({ scope: childSnapshot.scope, sessionId: childSnapshot.sessionId, role,
+          existing: true, expectedBinding });
+        const previous = await previousPublication({ store, childScopes, parent, child });
+        if (!guard()) return error('child_merge_authority_lost');
+        // The directory publisher owns all remaining synchronous work and checks
+        // the live intent/fence again after acquiring every shared lock.
+        publicationStarted = true;
+        const result = fileWorkspaces.files.merge(bound.workspace, {
+          expectedRevision: childSnapshot.workspaceRevision, previous, assertCurrent: guard });
+        if (!guard()) return uncertain('child_merge_authority_lost', result.applied);
+        if (!result.ok && result.error_code === 'child_workspace_publish_failed')
+          return uncertain(result.error_code, result.applied);
+        return { status: result.ok ? 'ok' : 'error', workspaceChangedPaths: [...result.applied],
+          content: { schema_version: STUDIO_NATIVE_CHILD_MERGE, child_run_id: childSnapshot.runId, ...result } };
+      } catch (failure) {
+        if (failure?.effectStarted || publicationStarted && failure?.code !== 'child_workspace_guard_failed')
+          return uncertain(failure?.code || 'child_merge_publication_unknown', failure?.applied);
+        return error(failure?.code || 'child_workspace_merge_unavailable');
+      }
+    },
+  };
+}

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

@@ -0,0 +1,19 @@
+import { validateModelSurface } from '@kingsoftcloud/agentkit-harness-core';
+
+/** A child gets facts for its own workspace and selected model, with its narrower tool catalog. */
+export function nativeChildModelSurface(parent, { workspaceRoot, supportsImages, tools, original } = {}) {
+  if (!parent) return undefined;
+  const { commandCwd: _cwd, environmentNames: _names, commandResources: _resources, ...base } = parent.environment;
+  const root = workspaceRoot ?? base.workspaceRoot, commands = tools.some(tool => tool.name === 'run_command');
+  const environment = { ...base, workspaceRoot: root, cwd: root, supportsImages,
+    date: original?.environment.date ?? base.date, commandBackend: commands ? base.commandBackend : 'none',
+    ...(commands && base.commandBackend === 'local_process' ? { commandCwd: root,
+      environmentNames: parent.environment.environmentNames ?? [],
+      ...(parent.environment.commandResources ? { commandResources: structuredClone(parent.environment.commandResources) } : {}) } : {}) };
+  const source=original??parent;
+  const result = { contract: parent.contract, environment,
+    ...(parent.executionCapabilities === undefined ? {} : { executionCapabilities: parent.executionCapabilities
+      .filter(capability => tools.some(tool => tool.name === capability.toolName)).map(capability => structuredClone(capability)) }),
+    ...(source.verificationProjection ? {verificationProjection:source.verificationProjection} : {}) };
+  validateModelSurface(result); return result;
+}

package/src/native/child-observation.mjs

@@ -0,0 +1,100 @@
+import { canonical } from '@kingsoftcloud/agentkit-harness-core';
+
+const key = value => canonical({ scope: value.scope, runId: value.runId });
+const clip = (value, limit = 16000) => {
+  const text = typeof value === 'string' ? value : canonical(value ?? null);
+  return { text: text.slice(0, limit), omittedChars: Math.max(0, text.length - limit) };
+};
+
+/** Latest observed read/search activity, without results or execution authority. */
+export function nativeChildActivity(record) {
+  const names = new Set(['read_workspace_file', 'list_workspace_files', 'search_workspace_files']);
+  const intent = (record.intents ?? []).findLast(row => row.kind === 'tool' && row.payload.calls?.some(call => names.has(call.name)));
+  const calls = intent?.payload.calls ?? [], index = calls.findLastIndex(call => names.has(call.name)), call = calls[index];
+  if (!call) return null;
+  const receipt = (record.receipts ?? []).find(row => row.operationKey === intent.operationKey && row.status === 'committed');
+  const result = receipt?.result.results?.[index];
+  const running = !receipt && record.snapshot.pendingIntent === intent.operationKey && record.snapshot.phase === 'executing_tools'
+    && record.lease?.expiresAt > Date.now();
+  return { name: call.name, input: Object.fromEntries(['path', 'directory', 'pattern', 'query'].flatMap(key =>
+    typeof call.arguments?.[key] === 'string' ? [[key, call.arguments[key].slice(0, 512)]] : [])),
+    status: { ok: 'completed', error: 'failed', uncertain: 'uncertain', approval_required: 'waiting' }[result?.status]
+      ?? (running ? 'running' : 'scheduled') };
+}
+
+/** Ephemeral provider text only. It grants no execution, receipt or recovery authority. */
+export function createNativeChildObservationCache({ maxRuns = 32, maxChars = 65536, now = Date.now } = {}) {
+  const entries = new Map();
+  return {
+    accept(context, record) {
+      try {
+        if (context.signal?.aborted || !['text', 'thinking'].includes(record.event?.kind)) return;
+        const id = key(context), previous = entries.get(id);
+        const entry = previous?.operationKey === context.operationKey && previous.fence === context.executionFence
+          ? previous : { operationKey: context.operationKey, fence: context.executionFence, text: '', thinking: '', textOmitted: 0, thinkingOmitted: 0 };
+        const field = record.event.kind === 'thinking' ? 'thinking' : 'text';
+        const delta = record.event.text;
+        if (typeof delta !== 'string') return;
+        const available = Math.max(0, maxChars - entry[field].length);
+        entry[field] += delta.slice(0, available); entry[field + "Omitted"] += Math.max(0, delta.length - available); entry.time = now();
+        entries.delete(id); entries.set(id, entry);
+        while (entries.size > maxRuns) entries.delete(entries.keys().next().value);
+      } catch { /* presentation cannot interrupt model execution */ }
+    },
+    read(record) {
+      const entry = entries.get(key(record.snapshot));
+      if (!entry || entry.operationKey !== record.snapshot.pendingIntent || entry.fence !== record.fence
+        || record.snapshot.phase !== 'requesting_model' || !record.lease || record.lease.expiresAt <= now()
+        || record.receipts.some(receipt => receipt.operationKey === entry.operationKey)) return null;
+      return { operationKey: entry.operationKey, text: entry.text,
+        thinking: record.configuration.profile.providerThinkingDisplayPolicy === 'provider-visible/v1' ? entry.thinking : '',
+        omittedChars: entry.textOmitted + (record.configuration.profile.providerThinkingDisplayPolicy === 'provider-visible/v1' ? entry.thinkingOmitted : 0) };
+    },
+    clear() { entries.clear(); },
+  };
+}
+
+/** Bounded child-only public observations. System context and replay data never leave this view. */
+export function nativeChildObservation(record, live = null) {
+  const { snapshot, configuration } = record;
+  const reasoning = new Map();
+  if (configuration.profile.providerThinkingDisplayPolicy === 'provider-visible/v1')
+    for (const event of record.events ?? []) if (event.kind === 'model.completed' && Number.isSafeInteger(event.payload.messageIndex)
+      && snapshot.messages[event.payload.messageIndex]?.role === 'assistant'
+      && snapshot.messages[event.payload.messageIndex]?.content === event.payload.text) {
+      const text = (event.payload.displayStream?.records ?? []).filter(row => row.event?.kind === 'thinking').map(row => row.event.text).join('');
+      if (text) reasoning.set(event.payload.messageIndex, clip(text));
+    }
+  const results = new Map();
+  for (const receipt of record.receipts) {
+    if (receipt.status !== 'committed') continue;
+    const intent = record.intents.find(intent => intent.operationKey === receipt.operationKey);
+    const pairs = intent?.kind === 'tool' ? (intent.payload.calls ?? []).map((call, i) => [call.callId, receipt.result.results?.[i]])
+      : ['tool_receipt', 'workspace_repair'].includes(intent?.kind) ? [[intent.payload.callId, receipt.result.result]] : [];
+    for (const [id, result] of pairs) if (result) results.set(id, result);
+  }
+  const rows = [];
+  snapshot.messages.forEach((message, index) => {
+    if (message.history || message.role === 'system' || message.kind === 'compaction_summary') return;
+    if (message.role === 'assistant') {
+      if (reasoning.has(index)) rows.push({ id: `thought:${index}`, kind: 'thought', ...reasoning.get(index) });
+      if (message.content) rows.push({ id: `text:${index}`, kind: 'text', ...clip(message.content) });
+      for (const call of message.toolCalls ?? []) rows.push({ id: call.callId, kind: 'tool', name: call.name,
+        input: clip(call.arguments), status: 'scheduled' });
+    } else if (message.role === 'tool') {
+      const call = rows.find(row => row.kind === 'tool' && row.id === message.callId);
+      if (call) {
+        const result = results.get(message.callId);
+        call.status = { ok: 'completed', error: 'failed', uncertain: 'uncertain', approval_required: 'waiting' }[result?.status] ?? 'interrupted';
+        call.result = clip(message.content);
+        if (result?.status === 'ok' && result.metadata?.nativeTaskDisplay?.contract === 'agentkit.workspace-display/v1')
+          call.display = result.metadata.nativeTaskDisplay.display;
+      }
+    }
+  });
+  const selected = rows.slice(-120);
+  return { contract: 'agentkit.native-child-observation/v1', runId: snapshot.runId, sessionId: snapshot.sessionId,
+    workspaceView: configuration.hostRecoveryBinding?.childWorkspace ? 'isolated' : 'parent',
+    snapshotRevision: snapshot.revision, prompt: clip(snapshot.goal), driving: Boolean(record.lease && record.lease.expiresAt > Date.now()), phase: snapshot.phase, outcome: snapshot.outcome, totalRows: rows.length,
+    omittedRows: Math.max(0, rows.length - selected.length), rows: selected, live };
+}