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

package/src/native/child-publication.mjs

@@ -0,0 +1,76 @@
+import { canonical, terminal } from '@kingsoftcloud/agentkit-harness-core';
+import { loadSessionChild, accountedChildDelivery } from './owned-child.mjs';
+import { ChildFilePublication } from './child-workspaces.mjs';
+
+export const MERGE_SCHEMA = 'native.child-file-merge/v2';
+const bindingContract = 'agentkit.native-child-workspace-binding/v1';
+const sha = /^sha256:[0-9a-f]{64}$/;
+const same = (left, right) => canonical(left) === canonical(right);
+function workspaceBinding(record) {
+  const value = record.configuration?.hostRecoveryBinding?.childWorkspace;
+  return value?.contract === bindingContract && /^[0-9a-f]{64}$/.test(value.isolationId)
+    && sha.test(value.baseRevision) ? value : null;
+}
+
+/** Only actual prepared tool effects with canonical committed success grant a
+ * publication. A saved inventory, model text and an uncertain receipt do not. */
+function confirmedPublication({ store, parent, source }) {
+  const visited = new Set();
+  for (let cursor = parent; cursor && !visited.has(cursor.runId);) {
+    visited.add(cursor.runId);
+    const record = store.load(parent.scope, cursor.runId);
+    if (!same(record.snapshot.scope, parent.scope) || record.snapshot.sessionId !== parent.sessionId) return null;
+    for (const event of [...record.events].reverse()) {
+      if (event.kind !== 'effect.prepared' || event.payload.kind !== 'tool') continue;
+      const intent = record.intents.find(item => item.operationKey === event.payload.operationKey && item.kind === 'tool');
+      const calls = intent?.payload.calls;
+      const receipt = record.receipts.find(item => item.operationKey === intent?.operationKey && item.status === 'committed');
+      const results = receipt?.result.results;
+      if (!Array.isArray(calls) || !Array.isArray(results) || calls.length !== results.length) continue;
+      for (let index = calls.length - 1; index >= 0; index--) {
+        const call = calls[index], result = results[index];
+        if (call?.name !== 'native_child_merge' || !same(call.arguments, { child_run_id: source.runId })
+          || result?.status !== 'ok') continue;
+        const content = result.content;
+        if (content?.schema_version !== MERGE_SCHEMA || content.ok !== true || content.child_run_id !== source.runId
+          || content.child_revision !== source.workspaceRevision) continue;
+        const grant = content.publication;
+        if (!sha.test(source.workspaceRevision) || !grant || grant.revision !== source.workspaceRevision
+          || !sha.test(grant.inventory_digest)) throw Error('child_publication_receipt_invalid');
+        return new ChildFilePublication(grant.revision, grant.inventory_digest);
+      }
+    }
+    if (!record.snapshot.parentRunId) return null;
+    const previous = store.load(parent.scope, record.snapshot.parentRunId).snapshot;
+    if (!same(previous.scope, parent.scope) || previous.sessionId !== parent.sessionId || !terminal(previous.phase)) return null;
+    cursor = previous;
+  }
+  return null;
+}
+
+/** Resolve only this child's real continuation ancestors, in this parent's
+ * Session. Current-child ownership and immutable configuration are re-proved
+ * even when a caller supplies a record-shaped object. */
+export function previousChildPublication({ store, childScopes, parent, child }) {
+  const actual = loadSessionChild({ store, childScopes, parent, childRunId: child.snapshot.runId });
+  if (!actual || !same(actual.child.snapshot, child.snapshot) || !same(actual.child.configuration, child.configuration)
+    || !accountedChildDelivery(actual.parent, actual.child)) return null;
+  const binding = workspaceBinding(child);
+  if (!binding) return null;
+  const visited = new Set([child.snapshot.runId]);
+  let current = child;
+  while (current.snapshot.parentRunId) {
+    const sourceId = current.snapshot.parentRunId;
+    if (visited.has(sourceId) || current.configuration.childOwnerBinding?.continuationOf !== sourceId) return null;
+    visited.add(sourceId);
+    const resolved = loadSessionChild({ store, childScopes, parent, childRunId: sourceId });
+    if (!resolved || !accountedChildDelivery(resolved.parent, resolved.child)) return null;
+    const source = resolved.child;
+    if (!same(source.snapshot.scope, child.snapshot.scope) || source.snapshot.sessionId !== child.snapshot.sessionId
+      || !same(workspaceBinding(source), binding)) return null;
+    const publication = confirmedPublication({ store, parent, source: source.snapshot });
+    if (publication) return publication;
+    current = source;
+  }
+  return null;
+}

package/src/native/child-readers.mjs

@@ -0,0 +1,366 @@
+// Scoped, paged read-only tools for already-accounted direct children.
+//
+// Ports the pure-read semantics of ksadk/harness/subagent_adapters/native_child_result.py
+// (NativeChildResultPort + NativeChildTasksPort) at pinned commit 355059d.
+//
+// The read capability owns no Kernel, model, factory, lease or execution method.
+// An accounted identity is a locator, never a semantic completion verdict.
+// Results do not verify the parent task; they are untrusted data.
+//
+// Validation follows child-owner.mjs's toolInvocation pattern: the parent must
+// have a running tool intent matching the request operationKey (including
+// parallel :call:<index> delegation), the frozen definition must match, the
+// executionFence must equal the current lease fence, the lease must be valid,
+// and taskContract.allowedToolNames must permit the tool.
+
+import { createHash } from 'node:crypto';
+import { NativeError, isNativeError, canonical, copy, terminal, scopeKey, matchesToolExecutionContract } from '@kingsoftcloud/agentkit-harness-core';
+
+import { resolveChildToolIntent as resolveIntent, loadOwnedDirectChild, accountedChildDelivery } from './owned-child.mjs';
+
+const hash = value => createHash('sha256').update(canonical(value)).digest('hex');
+const textHash = value => createHash('sha256').update(value).digest('hex');
+const same = (left, right) => canonical(left) === canonical(right);
+const check = (value, code) => { if (!value) throw new NativeError(code); };
+const identityFields = ['scope', 'runId', 'sessionId', 'turnId', 'buildId', 'parentRunId', 'taskChainId'];
+const identity = value => Object.fromEntries(identityFields.map(key => [key, copy(value[key])]));
+
+export function nativeChildReaderDefinitions() {
+  const resultDefinition = {
+    name: 'native_child_result',
+    description: "Read a child's status and page its original settled delivery. Active or uncertain children return metadata with result_available=false. This query starts no work and does not verify the parent task.",
+    parameters: {
+      type: 'object', additionalProperties: false, required: ['child_run_id'],
+      properties: {
+        child_run_id: { type: 'string', minLength: 1, maxLength: 256 },
+        offset_chars: { type: 'integer', minimum: 0, default: 0 },
+        limit_chars: { type: 'integer', minimum: 1, maximum: 16000, default: 4000 },
+      },
+    },
+    readOnly: true, concurrentSafe: true, permissions: [], timeoutMs: 1000, recoveryPolicy: 'safe-read/v1',
+    contextRole: 'none', observationRole: 'none', progressObservation: false, contextRetention: 'normal',
+  };
+
+  const tasksDefinition = {
+    name: 'native_child_tasks',
+    description: "List saved direct child tasks, their current status and delivery locators. Use this when previous child results or IDs are no longer in context. For later pages, use the returned inventory_digest and next_offset. Starts no work. Read a delivery with native_child_result.",
+    parameters: {
+      type: 'object', additionalProperties: false,
+      properties: {
+        offset: { type: 'integer', minimum: 0, default: 0 },
+        limit: { type: 'integer', minimum: 1, maximum: 16, default: 8 },
+        inventory_digest: { type: 'string', pattern: '^[0-9a-f]{64}$' },
+      },
+    },
+    readOnly: true, concurrentSafe: true, permissions: [], timeoutMs: 1000, recoveryPolicy: 'safe-read/v1',
+    contextRole: 'none', observationRole: 'none', progressObservation: false, contextRetention: 'normal',
+  };
+
+  return [resultDefinition, tasksDefinition];
+}
+
+export function createNativeChildResultTools({ scope, childScopes = [scope], store, roles, now = Date.now }) {
+  const parentScope = copy(scope);
+  scopeKey(parentScope);
+  const scopes = copy(childScopes);
+  check(Array.isArray(scopes) && scopes.length > 0 && scopes.every(item => {
+    scopeKey(item);
+    return ['tenantId', 'workspaceId', 'userId'].every(key => item[key] === parentScope[key]);
+  }), 'invalid_child_reader_scopes');
+  check(store, 'invalid_child_reader_store');
+  const roleIds = copy(roles);
+  check(Array.isArray(roleIds) && roleIds.length > 0 && roleIds.every(role => typeof role === 'string' && role.trim())
+    && new Set(roleIds).size === roleIds.length, 'invalid_child_reader_roles');
+
+  const definitions = nativeChildReaderDefinitions();
+  const definitionsByName = new Map(definitions.map(d => [d.name, d]));
+
+  // --- Internal: validate parent running tool intent -----------------------
+  // Mirrors child-owner.mjs toolInvocation: the request must be bound to a
+  // live parent tool effect — running intent, matching call, frozen definition,
+  // signal, executionFence, valid lease, and taskContract tool scope.
+
+  function validateRequest(request) {
+    check(same(request.scope, parentScope), 'child_reader_scope_mismatch');
+    const def = definitionsByName.get(request.call.name);
+    check(def, 'child_reader_definition_mismatch');
+    check(matchesToolExecutionContract(request.definition, def), 'child_reader_definition_mismatch');
+
+    let parentRecord;
+    try { parentRecord = store.load(parentScope, request.runId); }
+    catch (error) { if (error.code === 'run_not_found') throw new NativeError('child_reader_parent_unavailable'); throw error; }
+
+    // Validate full RunIdentity against the parent snapshot (not self-comparison)
+    check(same(identity(request), identity(parentRecord.snapshot)), 'child_reader_identity_mismatch');
+
+    const resolved = resolveIntent(parentRecord, request.operationKey);
+    check(resolved, 'child_reader_intent_not_owned');
+    const { intent, calls, index, base } = resolved;
+
+    // Intent must be a running tool; pendingIntent stays at the base key
+    check(intent.kind === 'tool' && intent.status === 'running'
+      && parentRecord.snapshot.pendingIntent === base,
+      'child_reader_intent_not_owned');
+
+    // Validate the call matches the intent's call at the resolved index
+    const expectedCall = calls?.[index];
+    check(expectedCall && same(expectedCall, request.call), 'child_reader_call_not_owned');
+
+    // Validate the frozen definition matches (from effective config tools)
+    const effectiveConfig = parentRecord.snapshot.taskContract
+      ? { ...parentRecord.configuration, contract: parentRecord.snapshot.taskContract }
+      : parentRecord.configuration;
+    const frozenDef = effectiveConfig.tools.find(tool => tool.name === request.call.name);
+    check(frozenDef && same(frozenDef, request.definition), 'child_reader_definition_not_frozen');
+
+    // Validate executionFence and lease
+    check(intent.claimedFence === request.executionFence
+      && parentRecord.lease?.fence === request.executionFence
+      && parentRecord.lease.expiresAt > now(), 'child_reader_fence_lost');
+
+    // Validate taskContract.allowedToolNames if present on the effective config
+    const allowedToolNames = effectiveConfig.contract.allowedToolNames;
+    if (allowedToolNames !== undefined && allowedToolNames !== null) {
+      check(Array.isArray(allowedToolNames) && allowedToolNames.includes(request.call.name), 'child_reader_tool_not_allowed');
+    }
+
+    // Signal must not be aborted
+    request.signal.throwIfAborted();
+
+    return parentRecord;
+  }
+
+  // --- Internal: check terminal-safe delivery ------------------------------
+
+  function isTerminalSafe(record) {
+    const snapshot = record.snapshot;
+    if (!terminal(snapshot.phase)) return false;
+    if (snapshot.phase === 'interrupted') return false;
+    // Check for uncertain receipts that make the delivery unsafe
+    for (const receipt of record.receipts) {
+      if (receipt.status === 'uncertain') {
+        const intent = record.intents.find(item => item.operationKey === receipt.operationKey);
+        if (intent?.kind !== 'model' && !(receipt.result.retryScheduled === true
+          && ['safe-read/v1', 'workspace-observation/v1'].includes(receipt.result.recoveryPolicy))) return false;
+      }
+    }
+    return true;
+  }
+
+  // --- Internal: unsafe (non-model, non-safe-read) receipt -----------------
+  // Same uncertain-receipt predicate as isTerminalSafe and child-owner.mjs
+  // unsafeReceipt, exposed as a standalone check for non-terminal children.
+
+  function hasUnsafeReceipt(record) {
+    for (const receipt of record.receipts) {
+      if (receipt.status === 'uncertain') {
+        const intent = record.intents.find(item => item.operationKey === receipt.operationKey);
+        if (intent?.kind !== 'model' && !(receipt.result.retryScheduled === true
+          && ['safe-read/v1', 'workspace-observation/v1'].includes(receipt.result.recoveryPolicy))) return true;
+      }
+    }
+    return false;
+  }
+
+  // --- Internal: load a direct child by run ID -----------------------------
+
+  const loadDirectChild = (parent, childRunId) => loadOwnedDirectChild({ store, childScopes: scopes, parent, childRunId, roles: roleIds });
+
+  // --- native_child_result execute -----------------------------------------
+
+  async function executeResult(request) {
+    const parentRecord = validateRequest(request);
+    const parent = parentRecord.snapshot;
+    const args = request.call.arguments ?? {};
+    const childRunId = args.child_run_id;
+    check(typeof childRunId === 'string' && childRunId.trim() && childRunId.length <= 256, 'child_result_query_invalid');
+    const offsetChars = args.offset_chars ?? 0;
+    const limitChars = args.limit_chars ?? 4000;
+    check(Number.isSafeInteger(offsetChars) && offsetChars >= 0, 'child_result_query_invalid');
+    check(Number.isSafeInteger(limitChars) && limitChars >= 1 && limitChars <= 16000, 'child_result_query_invalid');
+
+    const childRecord = loadDirectChild(parent, childRunId);
+    if (!childRecord) return { status: 'error', content: { error_code: 'child_result_not_available' } };
+
+    const child = childRecord.snapshot;
+    const binding = childRecord.configuration.childOwnerBinding;
+
+    // Only read terminal-safe deliveries
+    const reservation = parent.childBudgetReservations.find(item => item.childRunId === childRunId);
+    const settled = accountedChildDelivery(parentRecord, childRecord);
+    const available = Boolean(reservation.settledUsageDigest && settled && isTerminalSafe(childRecord));
+    const finalText = available ? child.finalText : '';
+    const charCount = [...finalText].length;
+    if (offsetChars > charCount)
+      return { status: 'error', content: { error_code: 'child_result_offset_invalid' } };
+
+    const chars = [...finalText];
+    const sliced = chars.slice(offsetChars, offsetChars + limitChars).join('');
+    const stop = offsetChars + [...sliced].length;
+
+    return {
+      status: 'ok',
+      content: {
+        schema_version: 'native.child-result/v1',
+        child_run_id: child.runId,
+        child_session_id: child.sessionId,
+        parent_run_id: parent.runId,
+        parent_tool_call_id: binding.parentToolCallId,
+        parent_operation_key: binding.parentOperationKey,
+        role: binding.role,
+        snapshot_revision: child.revision,
+        event_seq: child.eventSeq,
+        goal_digest: textHash(child.goal ?? ''),
+        contract_digest: hash(child.taskContract ?? childRecord.configuration.contract),
+        phase: child.phase,
+        terminal: terminal(child.phase),
+        result_available: available,
+        outcome: child.outcome,
+        final_text: sliced,
+        final_text_digest: textHash(finalText),
+        offset_chars: offsetChars,
+        next_offset_chars: stop,
+        complete: stop === charCount,
+        total_chars: charCount,
+        parent_acceptance: 'not_evaluated',
+        execution_started: false,
+        resource_usage_accounted_again: false,
+      },
+    };
+  }
+
+  // --- native_child_tasks execute ------------------------------------------
+
+  async function executeTasks(request) {
+    const parentRecord = validateRequest(request);
+    const parent = parentRecord.snapshot;
+    const args = request.call.arguments ?? {};
+    const offset = args.offset ?? 0;
+    const limit = args.limit ?? 8;
+    const inventoryDigest = args.inventory_digest ?? null;
+    check(Number.isSafeInteger(offset) && offset >= 0, 'child_tasks_query_invalid');
+    check(Number.isSafeInteger(limit) && limit >= 1 && limit <= 16, 'child_tasks_query_invalid');
+    if (inventoryDigest !== null)
+      check(typeof inventoryDigest === 'string' && /^[0-9a-f]{64}$/.test(inventoryDigest), 'child_tasks_query_invalid');
+
+    // Build direct child inventory — only children loadable via loadDirectChild
+    const children = [];
+    const descendants = new Set();
+    for (const childId of parent.childRunIds ?? []) {
+      const childRecord = loadDirectChild(parent, childId);
+      if (childRecord) {
+        children.push(childRecord);
+        for (const descId of childRecord.snapshot.childRunIds ?? []) descendants.add(descId);
+      }
+    }
+    const directIds = new Set(children.map(r => r.snapshot.runId));
+    // If any child ID is neither a direct child nor a descendant of a direct child, inventory is unavailable
+    for (const childId of parent.childRunIds ?? []) {
+      if (!directIds.has(childId) && !descendants.has(childId))
+        return { status: 'error', content: { error_code: 'child_tasks_not_available' } };
+    }
+
+    // Delivery changes independently of the immutable startup reservation.
+    // Control availability comes from current durable ownership, not findings.
+    const promotionEnabled = parentRecord.configuration.childPromotionPolicy === 'owned-child-promotion/v1';
+    const promoted = new Set(parent.promotedChildRunIds ?? []);
+    const controlState = children.map(record => {
+      const child = record.snapshot;
+      const reservation = (parent.childBudgetReservations ?? []).find(item => item.childRunId === child.runId);
+      const foreground = reservation?.deliveryMode === 'foreground' && !promoted.has(child.runId);
+      const live = !terminal(parent.phase) && parent.phase !== 'finalizing' && !parent.childTerminalPhase
+        && !parentRecord.commands.some(row => !row.consumed && ['cancel', 'policy_revoked'].includes(row.command.kind))
+        && !terminal(child.phase) && !hasUnsafeReceipt(record)
+        && reservation?.settledUsageDigest === null;
+      return {
+        child_run_id: child.runId,
+        delivery: foreground ? 'foreground' : 'background',
+        can_promote: foreground && promotionEnabled && live,
+        can_cancel: live,
+        can_send_input: live,
+      };
+    });
+    const controlByRunId = new Map(controlState.map(item => [item.child_run_id, item]));
+
+    // Keep the v2 inventory identity stable while live metadata changes.
+    const digestInput = canonical({
+      inventory_policy: 'direct-child-inventory/v2',
+      scope: parentScope,
+      parent_run_id: parent.runId,
+      child_run_ids: children.map(r => r.snapshot.runId),
+    });
+    const computedDigest = textHash(digestInput);
+
+    if ((offset && inventoryDigest === null) || (inventoryDigest !== null && inventoryDigest !== computedDigest))
+      return { status: 'error', content: { error_code: 'child_tasks_inventory_changed' } };
+    if (offset > children.length)
+      return { status: 'error', content: { error_code: 'child_tasks_offset_invalid' } };
+
+    const tasks = children.slice(offset, offset + limit).map(record => {
+      const child = record.snapshot;
+      const binding = record.configuration.childOwnerBinding;
+      const goal = child.goal ?? '';
+      const finalText = child.finalText ?? '';
+      const control = controlByRunId.get(child.runId);
+      return {
+        child_run_id: child.runId,
+        child_session_id: child.sessionId,
+        role: binding.role,
+        parent_tool_call_id: binding.parentToolCallId,
+        snapshot_revision: child.revision,
+        phase: child.phase,
+        terminal: terminal(child.phase),
+        outcome: child.outcome,
+        delivery: control?.delivery ?? 'background',
+        can_promote: control?.can_promote ?? false,
+        can_cancel: control?.can_cancel ?? false,
+        can_send_input: control?.can_send_input ?? false,
+        goal_preview: [...goal].slice(0, 256).join(''),
+        goal_preview_trust: 'untrusted',
+        goal_preview_complete: [...goal].length <= 256,
+        goal_digest: textHash(goal),
+        final_text_chars: [...finalText].length,
+        final_text_digest: textHash(finalText),
+        result_tool: 'native_child_result',
+        parent_acceptance: 'not_evaluated',
+      };
+    });
+
+    const stop = offset + tasks.length;
+    return {
+      status: 'ok',
+      content: {
+        schema_version: 'native.child-tasks/v2',
+        parent_run_id: parent.runId,
+        parent_snapshot_revision: parent.revision,
+        inventory_digest: computedDigest,
+        tasks,
+        total_tasks: children.length,
+        offset,
+        next_offset: stop,
+        complete: stop === children.length,
+        parent_acceptance: 'not_evaluated',
+        execution_started: false,
+        resource_usage_accounted_again: false,
+      },
+    };
+  }
+
+  // --- Execute dispatcher --------------------------------------------------
+
+  async function execute(request) {
+    try {
+      if (request.call.name === 'native_child_result') return await executeResult(request);
+      if (request.call.name === 'native_child_tasks') return await executeTasks(request);
+      return { status: 'error', content: { error_code: 'child_reader_unknown_tool' } };
+    } catch (error) {
+      request.signal?.throwIfAborted();
+      if (error.name === 'AbortError') throw error;
+      if (isNativeError(error) && /^(child_|invalid_child_)/.test(error.code))
+        return { status: 'error', content: { error_code: error.code } };
+      return { status: 'uncertain', content: { error_code: 'child_reader_store_unavailable' } };
+    }
+  }
+
+  return Object.freeze({ definitions, execute });
+}

package/src/native/child-tools.mjs

@@ -0,0 +1,46 @@
+import { invariant } from '@kingsoftcloud/agentkit-harness-core';
+import { CHILD_CAPABILITY_POLICY, childRequiredToolsSchema } from './child-capabilities.mjs';
+export { CHILD_CAPABILITY_POLICY, childCapabilityDirectory, admitChildCapabilities, childRequiredToolsSchema } from './child-capabilities.mjs';
+
+export const NATIVE_CHILD_TOOLS_CONTRACT = 'agentkit.native-child-tools/v1';
+export function nativeChildToolDefinitions(roles, startTimeoutMs = 120000, { childCapabilityPolicy, capabilities } = {}) {
+  invariant(childCapabilityPolicy === undefined || childCapabilityPolicy === CHILD_CAPABILITY_POLICY, 'invalid_child_capability_policy');
+  invariant(Array.isArray(roles) && roles.length > 0 && roles.length <= 32
+    && roles.every(role => typeof role === 'string' && /^[a-z0-9][a-z0-9_-]{0,63}$/.test(role))
+    && new Set(roles).size === roles.length, 'native_child_roles_invalid');
+  const base = { readOnly: false, concurrentSafe: false, permissions: [], timeoutMs: 120000,
+    contextRole: 'none', observationRole: 'none', progressObservation: false, contextRetention: 'normal' };
+  invariant(Number.isSafeInteger(startTimeoutMs) && startTimeoutMs >= 120000, 'native_child_timeout_invalid');
+  const definitions = [{ ...base, timeoutMs: startTimeoutMs, name: 'native_start_child', childBudgetPolicy: 'start/v1',
+    description: 'Start a bounded approved child, in the background by default. background=false waits for its delivery. continuation_of reuses a terminal, collected child Session from this parent Session with a fresh Run and budget; collect it first. An early startup receipt reserves budget and is not findings.',
+    parameters: { type: 'object', additionalProperties: false, required: ['role', 'task'], properties: {
+      role: { type: 'string', enum: [...roles] }, task: { type: 'string', minLength: 1, maxLength: 32000 },
+      background: { type: 'boolean', default: true }, model_call_limit: { type: 'integer', minimum: 1, default: 4 },
+      tool_call_limit: { type: 'integer', minimum: 0, default: 8 },
+      output_format: { type: 'string', enum: ['text', 'json_object'] }, output_contract: { type: 'string', enum: ['parent'] },
+      continuation_of: { type: 'string', minLength: 1, maxLength: 256 },
+      media: { type: 'array', maxItems: 20, items: { type: 'object', additionalProperties: false, required: ['source', 'index'],
+        properties: { source: { type: 'string', enum: ['parent_user_input'] }, index: { type: 'integer', minimum: 0 } } },
+        description: 'Original content-part indices of images in the current admitted parent user input. Pass references only.' },
+    } } }, { ...base, name: 'native_child_control', childBudgetPolicy: 'settle/v1',
+    description: 'Send guidance, stop, or wait up to 30 seconds for a child owned by this parent. A running response is not completion. Sealed terminal results settle actual usage once.',
+    parameters: { type: 'object', additionalProperties: false, required: ['child_run_id', 'action'], properties: {
+      child_run_id: { type: 'string', minLength: 1, maxLength: 256 }, action: { type: 'string', enum: ['wait', 'send', 'stop'] },
+      message: { type: 'string', minLength: 1, maxLength: 32000 }, wait_seconds: { type: 'number', minimum: 0, maximum: 30, default: 15 },
+    } } }];
+  const delegate = structuredClone(definitions[0]);
+  delegate.name = 'native_delegate'; delegate.childBudgetPolicy = 'delegate/v1';
+  delegate.description = 'Run a bounded approved child and wait for its original delivery. continuation_of reuses a terminal, collected child Session with a fresh Run and budget. Its findings do not verify the parent task. background=true returns a budget reservation instead.';
+  delegate.parameters.properties.background.default = false;
+  for (const key of ['model_call_limit', 'tool_call_limit']) delete delegate.parameters.properties[key];
+  if (childCapabilityPolicy) {
+    invariant(Array.isArray(capabilities) && capabilities.length === roles.length
+      && roles.every(role => capabilities.some(item => item.role === role && Array.isArray(item.tools))), 'invalid_child_capability_directory');
+    for (const definition of [definitions[0], delegate]) {
+      definition.parameters.properties.required_tools = childRequiredToolsSchema();
+      definition.parameters.required.push('required_tools');
+      definition.description += '\nApproved role capabilities: ' + JSON.stringify(capabilities);
+    }
+  }
+  return [...definitions, delegate];
+}

package/src/native/child-workspace-binding.mjs

@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { canonical, invariant, scopeKey } from '@kingsoftcloud/agentkit-harness-core';
+import { DirectoryChildWorkspaces } from '@kingsoftcloud/agentkit-harness-node/native/child-workspaces';
+
+export const STUDIO_NATIVE_CHILD_WORKSPACE_BINDING = 'agentkit.native-child-workspace-binding/v1';
+const hash = value => createHash('sha256').update(canonical(value)).digest('hex');
+
+/** Trusted Host inputs only. No model path or model-provided isolation id. */
+export function createStudioNativeChildWorkspaces({ workspaceRoot, stateDir }) {
+  const files = new DirectoryChildWorkspaces({ source: workspaceRoot, storage: join(stateDir, 'child-workspaces') });
+  const sourceRootDigest = hash(files.source), storageRootDigest = hash(files.storage);
+  return {
+    contract: STUDIO_NATIVE_CHILD_WORKSPACE_BINDING,
+    bindingDigest: hash({ contract: STUDIO_NATIVE_CHILD_WORKSPACE_BINDING, sourceRootDigest, storageRootDigest }),
+    files,
+    bind({ scope, sessionId, role, existing = false, expectedBinding }) {
+      scopeKey(scope);
+      invariant(typeof sessionId === 'string' && sessionId.trim(), 'studio_native_child_workspace_session_missing');
+      const isolationId = hash({ contract: STUDIO_NATIVE_CHILD_WORKSPACE_BINDING, scope, sessionId, role, source: files.source });
+      const workspace = existing ? files.load(isolationId) : files.prepare(isolationId);
+      const binding = { contract: STUDIO_NATIVE_CHILD_WORKSPACE_BINDING, isolationId, baseRevision: workspace.baseRevision,
+        sourceRootDigest, storageRootDigest, roleDigest: hash(role) };
+      invariant(expectedBinding === undefined || canonical(expectedBinding) === canonical(binding),
+        'studio_native_child_workspace_binding_changed');
+      return { workspace, root: workspace.root, binding, observer: files.observer(workspace) };
+    },
+  };
+}

package/src/native/child-workspace-tools.mjs

@@ -0,0 +1 @@
+export { NATIVE_CHILD_WORKSPACE_TOOLS, NATIVE_CHILD_COMMAND_TOOLS } from '@kingsoftcloud/agentkit-harness-core/child-workspace-tools';