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

package/src/native/conversation-command-control.mjs

@@ -0,0 +1,133 @@
+// Host-only local-background cleanup controller. This is a private Host
+// capability for conversation rewind: it cancels removed-branch local background
+// commands while preserving retained rows exactly. It is not an advertised
+// model tool, never falls back to an environment backend, never launches
+// processes, fakes tools, mutates Native Run ledgers or marks notified. Retry
+// is idempotent via the existing durable cancel file and terminal record.
+import { canonical, copy, NativeError, backgroundCommandRef, scopeKey } from '@kingsoftcloud/agentkit-harness-core';
+import { ownedCommandReceipt } from './owned-command.mjs';
+import { LocalCommandStore } from './local-background.mjs';
+import { TERMINAL } from './local-command-state.mjs';
+import { lstatSync, realpathSync } from 'node:fs';
+
+export const CONVERSATION_COMMAND_CONTROL_CONTRACT = 'agentkit.native-conversation-command-control/v1';
+const STOP_WAIT_MS = 5000;
+const ACCEPTED_BACKEND = 'local_process';
+// wait() already rejects 'unknown'; this set is the explicit fail-closed guard.
+const KNOWN_TERMINAL = new Set([...TERMINAL].filter(status => status !== 'unknown'));
+
+const check = (condition, code) => { if (!condition) throw new NativeError(code); };
+const same = (a, b) => canonical(a) === canonical(b);
+
+export function createNativeConversationCommandControl({ workspaceRoot, stateRoot, scope, store, sessionId, isClosed = () => false }) {
+  check(typeof workspaceRoot === 'string' && !!workspaceRoot, 'conversation_command_workspace_root_invalid');
+  check(typeof stateRoot === 'string' && !!stateRoot, 'conversation_command_state_root_invalid');
+  check(typeof sessionId === 'string' && !!sessionId.trim(), 'conversation_command_session_id_invalid');
+  check(typeof isClosed === 'function', 'conversation_command_is_closed_invalid');
+  check(store && typeof store.load === 'function' && typeof store.sessionHead === 'function', 'conversation_command_store_invalid');
+  scopeKey(scope);
+  const pinnedScope = copy(scope);
+  // The owner binding is digest([realpath(workspace), 'local_process', sessionId]);
+  // commandId(operationKey) is digest([owner, operationKey]). Verifying the ref's
+  // taskId against this binding is what ties a head row to this local store.
+  // Match the launch transport's physical paths (macOS /var is an alias).
+  // The existing state directory itself must not be a substituted symlink.
+  check(!lstatSync(stateRoot).isSymbolicLink(), 'background_state_symlink');
+  const pinnedWorkspace = realpathSync(workspaceRoot), pinnedState = realpathSync(stateRoot);
+  const localStore = new LocalCommandStore({ stateRoot: pinnedState, workspaceRoot: pinnedWorkspace, sessionId });
+
+  async function settle({ record, retainedRefs, requestDigest, signal, assertCurrent }) {
+    check(record && typeof record === 'object' && record.snapshot && typeof record.snapshot === 'object',
+      'conversation_command_record_invalid');
+    check(signal instanceof AbortSignal, 'conversation_command_signal_required');
+    check(typeof assertCurrent === 'function', 'conversation_command_assert_current_required');
+    check(typeof requestDigest === 'string' && !!requestDigest, 'conversation_command_request_digest_invalid');
+    check(Array.isArray(retainedRefs), 'conversation_command_retained_refs_invalid');
+    signal.throwIfAborted();
+    const originalRecord = canonical(record), originalRefs = canonical(retainedRefs);
+    const pinnedRecord = copy(record);
+    check(same(pinnedRecord.snapshot.scope, pinnedScope), 'conversation_command_scope_mismatch');
+    check(pinnedRecord.snapshot.sessionId === sessionId, 'conversation_command_session_mismatch');
+    // assertCurrent is synchronous and must return exactly true, never a thenable.
+    const guard = () => {
+      signal.throwIfAborted();
+      check(!isClosed(), 'conversation_command_control_closed');
+      check(realpathSync(workspaceRoot) === pinnedWorkspace && realpathSync(stateRoot) === pinnedState,
+        'conversation_command_workspace_changed');
+      check(canonical(record) === originalRecord && canonical(retainedRefs) === originalRefs,
+        'conversation_command_input_changed');
+      const head = store.sessionHead(pinnedScope, sessionId);
+      check(head && head.runId === pinnedRecord.snapshot.runId, 'conversation_command_head_mismatch');
+      check(canonical(store.load(pinnedScope, head.runId)) === originalRecord, 'conversation_command_record_mismatch');
+      const result = assertCurrent();
+      if (result && typeof result.then === 'function') {
+        Promise.resolve(result).catch(() => {});
+        throw new NativeError('conversation_command_authority_thenable');
+      }
+      check(result === true, 'conversation_command_authority_lost');
+      signal.throwIfAborted();
+      check(canonical(record) === originalRecord && canonical(retainedRefs) === originalRefs
+        && store.sessionHead(pinnedScope, sessionId)?.runId === pinnedRecord.snapshot.runId
+        && canonical(store.load(pinnedScope, pinnedRecord.snapshot.runId)) === originalRecord,
+      'conversation_command_input_changed');
+    };
+    // Validate retained refs (shape + no duplicate taskIds).
+    const retained = retainedRefs.map(item => backgroundCommandRef(item));
+    check(new Set(retained.map(ref => ref.taskId)).size === retained.length, 'conversation_command_duplicate_ref');
+    guard();
+    signal.throwIfAborted();
+
+    // Verify ALL head rows' launch provenance before any external stop. This
+    // covers retained rows too: a retained row with a broken receipt fails the
+    // whole settlement rather than leaving a partial stop behind.
+    const headRows = pinnedRecord.snapshot.backgroundCommands;
+    check(Array.isArray(headRows), 'conversation_command_record_invalid');
+    check(new Set(headRows.map(row => row.ref.taskId)).size === headRows.length, 'conversation_command_duplicate_ref');
+    const verified = [];
+    for (const row of headRows) {
+      const ref = backgroundCommandRef(row.ref);
+      const receipt = ownedCommandReceipt({ scope: pinnedScope, store, current: pinnedRecord, ref });
+      check(receipt.backend === ACCEPTED_BACKEND, 'conversation_command_unsupported_backend');
+      check(localStore.commandId(ref.operationKey) === ref.taskId, 'conversation_command_task_id_mismatch');
+      verified.push({ row, ref });
+    }
+    // Foreign retained refs: every retainedRef must match a verified head row.
+    for (const ref of retained) {
+      check(verified.some(item => same(item.ref, ref)), 'conversation_command_foreign_ref');
+    }
+    // Partition head rows in original snapshot order.
+    const retainedRows = [], removedRows = [];
+    for (const item of verified) {
+      if (retained.some(ref => same(ref, item.ref))) retainedRows.push(item);
+      else removedRows.push(item);
+    }
+    // Stop removed rows with a bounded wait; preserve retained rows (never stop).
+    const stopped = [];
+    for (const item of removedRows) {
+      signal.throwIfAborted();
+      const handle = localStore.connect(item.ref.taskId);
+      guard(); // before the external mutation (durable cancel file)
+      handle.requestCancel();
+      let output;
+      try {
+        output = await handle.wait({ timeoutMs: STOP_WAIT_MS, signal });
+      } catch (error) {
+        signal.throwIfAborted();
+        guard(); // after the await, even on the error path
+        throw error;
+      }
+      guard(); // after the await
+      check(KNOWN_TERMINAL.has(output.status), 'conversation_command_stop_status_unknown');
+      stopped.push({ ref: copy(item.ref), status: output.status });
+    }
+    guard();
+    return Object.freeze({
+      contract: CONVERSATION_COMMAND_CONTROL_CONTRACT,
+      requestDigest,
+      retained: retainedRows.map(item => copy(item.row)),
+      stopped,
+    });
+  }
+
+  return Object.freeze({ contract: CONVERSATION_COMMAND_CONTROL_CONTRACT, settle });
+}

package/src/native/delivery-timeline.mjs

@@ -0,0 +1,39 @@
+import { createHash } from 'node:crypto';
+import { canonical, invariant } from '@kingsoftcloud/agentkit-harness-core';
+import { toolContext } from '@kingsoftcloud/agentkit-harness-core/tool-context';
+
+const hash = value => createHash('sha256').update(canonical(value)).digest('hex');
+export const nativeDeliveryId = (scope, runId, key) => `ak-native-${hash({ identity: hash({ scope, runId }), key })}`;
+
+/** Terminal delivery can close a call whose result never entered the transcript.
+ * Keep the same committed observation for delivery and later conversation cuts. */
+export function nativeDeliveryClosure(record, callId) {
+  const intent = record.intents.find(item => item.kind === 'tool' && item.payload.calls?.some(call => call.callId === callId));
+  const receipt = intent && record.receipts.find(item => item.operationKey === intent.operationKey);
+  const index = intent?.payload.calls.findIndex(call => call.callId === callId);
+  const observed = receipt?.status === 'committed' && index >= 0 ? receipt.result.results?.[index] : null;
+  if (observed) return { context: observed.context === undefined ? { content: canonical(observed.content) } : toolContext(observed.context),
+    isError: observed.status !== 'ok' };
+  const unknown = intent?.status === 'running' && (!receipt || receipt.status === 'uncertain');
+  return { context: { content: canonical({ status: unknown ? 'uncertain' : 'not_dispatched',
+    reason: unknown ? 'effect_outcome_unknown' : record.snapshot.reason ?? 'run_ended' }) }, isError: true };
+}
+
+/** Rebuild the original immutable message positions before replaying output
+ * retirements. Both delivery and conversation cuts must use the same timeline. */
+export function nativeDeliveryTimeline(record) {
+  const messages = structuredClone(record.snapshot.messages), retirements = new Map();
+  for (const event of record.events.filter(event => event.seq <= record.snapshot.eventSeq).toReversed()) {
+    if (event.kind !== 'output.restarted') continue;
+    const { retainedMessageCount: retained, retiredMessages: retired, notice } = event.payload;
+    invariant(Number.isSafeInteger(retained) && retained >= 0 && retained < messages.length && Array.isArray(retired)
+      && retired.every(message => message && ['user', 'assistant'].includes(message.role)
+        && typeof message.content === 'string' && ['continuation_fragment', 'continuation_observation'].includes(message.kind)
+        && Object.keys(message).every(key => ['role', 'kind', 'content'].includes(key)))
+      && canonical({ role: messages[retained].role, kind: messages[retained].kind ?? null, content: messages[retained].content })
+        === canonical(notice), 'native_delivery_output_restart_invalid');
+    retirements.set(event.seq, { retained, retired, notice: structuredClone(messages[retained]) });
+    messages.splice(retained, 1, ...structuredClone(retired));
+  }
+  return { messages, retirements };
+}

package/src/native/dsh-background-ownership.mjs

@@ -0,0 +1,102 @@
+import { createHash } from 'node:crypto';
+import { BACKGROUND_NOTIFICATION_ADMISSION, NATIVE_JSON_CODEC, NativeError, admitBackgroundNotification,
+  canonical, configure, invariant, parseNativeJson, scopeKey } from '@kingsoftcloud/agentkit-harness-core';
+import { nativeDshOwnershipHost } from './dsh-turn-ownership.mjs';
+
+export const NATIVE_DSH_BACKGROUND_TURN_CONTRACT = 'agentkit.native-dsh-background-turn/v1';
+export const NATIVE_DSH_BACKGROUND_ADMISSION = 'agentkit.native-dsh-background-admission/v1';
+export const NATIVE_DSH_IDLE_ADMISSION = 'dsh.external-turn-start/v1';
+const hash = value => createHash('sha256').update(canonical(value)).digest('hex');
+const text = value => typeof value === 'string' && value.trim().length > 0;
+const digest = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const fields = (value, names) => value && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).sort().join(',') === names;
+const identityOf = snapshot => Object.fromEntries(['scope', 'runId', 'sessionId', 'turnId', 'buildId', 'parentRunId', 'taskChainId']
+  .map(key => [key, snapshot[key]]));
+
+/** Serialize facts about an already admitted notice; no ports or new user input.
+ * Native notice IDs remain stable across crashes before DSH ownership is flushed.
+ * The numeric DSH turn is a separate delivery position, never a replacement ID.
+ */
+export function nativeDshBackgroundOwnership({ record, turn }) {
+  const admission = { contract: NATIVE_DSH_BACKGROUND_ADMISSION, jsonCodec: NATIVE_JSON_CODEC,
+    identity: identityOf(record.snapshot), configuration: record.configuration,
+    configDigest: record.snapshot.configDigest, notification: record.snapshot.backgroundNotification };
+  const ownership = { contract: 'dsh.external-turn/v1', engine: NATIVE_DSH_BACKGROUND_TURN_CONTRACT,
+    turn, binding: canonical(admission) };
+  readNativeDshBackgroundOwnership(ownership, { sessionId: record.snapshot.sessionId, turn });
+  return ownership;
+}
+
+/** Parse detached recovery facts. Matching these facts never grants execution authority. */
+export function readNativeDshBackgroundOwnership(ownership, { sessionId, turn }) {
+  invariant(fields(ownership, 'binding,contract,engine,turn') && ownership.contract === 'dsh.external-turn/v1'
+    && ownership.engine === NATIVE_DSH_BACKGROUND_TURN_CONTRACT && ownership.turn === turn
+    && Number.isSafeInteger(turn) && turn > 0 && text(ownership.binding), 'native_dsh_background_ownership_invalid');
+  const admission = parseNativeJson(ownership.binding);
+  invariant(fields(admission, 'configDigest,configuration,contract,identity,jsonCodec,notification')
+    && admission.contract === NATIVE_DSH_BACKGROUND_ADMISSION && admission.jsonCodec === NATIVE_JSON_CODEC
+    && canonical(admission) === ownership.binding, 'native_dsh_background_admission_invalid');
+  const { identity, configuration, notification } = admission;
+  invariant(fields(identity, 'buildId,parentRunId,runId,scope,sessionId,taskChainId,turnId')
+    && text(identity.sessionId) && identity.sessionId === sessionId && text(identity.buildId)
+    && text(identity.taskChainId) && text(identity.parentRunId), 'native_dsh_background_identity_invalid');
+  scopeKey(identity.scope);
+  invariant(fields(notification, 'admissionElapsedMs,contract,requestDigest,sourceConfigDigest,sourceRunId,taskId')
+    && notification.contract === BACKGROUND_NOTIFICATION_ADMISSION && text(notification.sourceRunId)
+    && notification.sourceRunId !== identity.runId && digest(notification.taskId) && digest(notification.requestDigest)
+    && digest(notification.sourceConfigDigest) && Number.isSafeInteger(notification.admissionElapsedMs)
+    && notification.admissionElapsedMs >= 0, 'native_dsh_background_origin_invalid');
+  invariant(identity.runId === 'wake_' + hash({ contract: BACKGROUND_NOTIFICATION_ADMISSION, scope: identity.scope,
+    sourceRunId: notification.sourceRunId, taskId: notification.taskId }) && identity.turnId === identity.runId,
+  'native_dsh_background_identity_invalid');
+  invariant(hash(configuration) === admission.configDigest && canonical(configure(configuration)) === canonical(configuration)
+    && configuration.backgroundNotificationPolicy === 'completed-before-model/v1' && configuration.inputMessages === null,
+  'native_dsh_background_configuration_invalid');
+  return admission;
+}
+
+function assertStoredAdmission(admission, record) {
+  invariant(canonical(identityOf(record.snapshot)) === canonical(admission.identity)
+    && record.snapshot.configDigest === admission.configDigest && hash(record.configuration) === admission.configDigest
+    && canonical(record.configuration) === canonical(admission.configuration)
+    && canonical(record.snapshot.backgroundNotification ?? null) === canonical(admission.notification),
+  'native_dsh_background_stored_admission_changed');
+}
+
+/** Recheck the real ledger and original launch before trusted Host port rebinding.
+ * This only takes the core admission's duplicate path: a missing record cannot
+ * poll, recreate a notice, start a model or relaunch a command. A live notice
+ * must remain the session head; terminal notices can still be delivered again.
+ */
+export async function verifyNativeDshBackgroundOwnership(ownership, { store, scope, sessionId, turn, signal }) {
+  invariant(signal instanceof AbortSignal, 'native_dsh_background_signal_required');
+  signal.throwIfAborted();
+  scopeKey(scope);
+  const admission = readNativeDshBackgroundOwnership(ownership, { sessionId, turn });
+  invariant(canonical(admission.identity.scope) === canonical(scope), 'native_dsh_background_scope_mismatch');
+  const { identity, notification } = admission;
+  assertStoredAdmission(admission, store.load(scope, identity.runId));
+  const duplicate = await admitBackgroundNotification({ store, scope, sourceRunId: notification.sourceRunId,
+    taskId: notification.taskId, digest: hash, signal,
+    observe: async () => { throw new NativeError('native_dsh_background_admission_missing'); } });
+  signal.throwIfAborted();
+  invariant(duplicate.created === false && duplicate.snapshot.runId === identity.runId,
+    'native_dsh_background_admission_missing');
+  const record = store.load(scope, identity.runId);
+  assertStoredAdmission(admission, record);
+  const source = store.load(scope, notification.sourceRunId);
+  invariant(source.snapshot.sessionId === sessionId && source.snapshot.buildId === identity.buildId
+    && source.snapshot.taskChainId === identity.taskChainId && canonical(source.snapshot.scope) === canonical(scope),
+  'native_dsh_background_source_identity_changed');
+  signal.throwIfAborted();
+  return { admission, record, source };
+}
+
+/** Require both the maintained provider version and its actual idle-start API. */
+export function nativeDshIdleOwnershipHost(agent) {
+  const host = nativeDshOwnershipHost(agent);
+  invariant(host.idleAdmissionContract === NATIVE_DSH_IDLE_ADMISSION && typeof host.start === 'function',
+    'native_dsh_idle_ownership_host_required');
+  return host;
+}

package/src/native/dsh-managed-ownership.mjs

@@ -0,0 +1,23 @@
+import { canonical, invariant, parseNativeJson, scopeKey } from '@kingsoftcloud/agentkit-harness-core';
+
+export const NATIVE_DSH_MANAGED_TURN_CONTRACT = 'agentkit.native-managed-dsh-turn/v1';
+const text = value => typeof value === 'string' && value.trim().length > 0;
+const fields = (value, keys) => value && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).sort().join(',') === keys;
+
+/** Persisted delivery identity, never an execution grant. The trusted Host must
+ * separately own the SDK turn and rebind the original Native configuration. */
+export function readNativeDshManagedOwnership(owner, { sessionId, turn } = {}) {
+  invariant(fields(owner, 'binding,contract,engine,turn') && owner.contract === 'dsh.external-turn/v1'
+    && owner.engine === NATIVE_DSH_MANAGED_TURN_CONTRACT && Number.isSafeInteger(owner.turn) && owner.turn > 0
+    && (turn === undefined || turn === owner.turn) && text(owner.binding), 'NATIVE_MANAGED_OWNER_INVALID');
+  const value = parseNativeJson(owner.binding), identity = value.identity;
+  invariant(fields(value, 'configDigest,contract,identity') && value.contract === NATIVE_DSH_MANAGED_TURN_CONTRACT
+    && canonical(value) === owner.binding && /^[a-f0-9]{64}$/u.test(value.configDigest)
+    && fields(identity, 'buildId,parentRunId,runId,scope,sessionId,taskChainId,turnId')
+    && ['runId', 'sessionId', 'turnId', 'buildId', 'taskChainId'].every(key => text(identity[key]))
+    && (identity.parentRunId === null || text(identity.parentRunId))
+    && (sessionId === undefined || identity.sessionId === sessionId), 'NATIVE_MANAGED_OWNER_INVALID');
+  scopeKey(identity.scope);
+  return value;
+}

package/src/native/dsh-turn-contract.mjs

@@ -0,0 +1,3 @@
+/** Explicit Host/preset opt-in while full Native capability parity is pending. */
+export const NATIVE_DSH_TURN_CONTRACT = 'agentkit.native-dsh-turn/v1';
+export const NATIVE_DSH_CONTENT_FORMAT = 'agentkit.dsh-content/v1';

package/src/native/dsh-turn-ownership.mjs

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+import { canonical, configure, invariant, NATIVE_JSON_CODEC, parseNativeJson, scopeKey } from '@kingsoftcloud/agentkit-harness-core';
+import { NATIVE_DSH_TURN_CONTRACT } from './dsh-turn-contract.mjs';
+
+export const NATIVE_DSH_ADMISSION_CONTRACT = 'agentkit.native-dsh-admission/v1';
+export const NATIVE_DSH_OWNERSHIP_HOST = 'dsh.external-turn-host/v1';
+const hash = value => createHash('sha256').update(canonical(value)).digest('hex');
+const text = value => typeof value === 'string' && value.trim().length > 0;
+const fields = (value, names) => value && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).sort().join(',') === names;
+
+/** Complete admission data, never live ports, credentials or execution authority. */
+export function nativeDshOwnership({ identity, configuration, input, source }) {
+  const admission = { contract: NATIVE_DSH_ADMISSION_CONTRACT, jsonCodec: NATIVE_JSON_CODEC,
+    identity, configuration, configDigest: hash(configuration), messages: input.messages, source };
+  const ownership = { contract: 'dsh.external-turn/v1', engine: NATIVE_DSH_TURN_CONTRACT,
+    turn: Number(identity.turnId), binding: canonical(admission) };
+  readNativeDshOwnership(ownership, { sessionId: identity.sessionId, turn: ownership.turn });
+  return ownership;
+}
+
+/** Validate persisted facts before a trusted Host resolves the original preset. */
+export function readNativeDshOwnership(ownership, { sessionId, turn }) {
+  invariant(fields(ownership, 'binding,contract,engine,turn') && ownership.contract === 'dsh.external-turn/v1'
+    && ownership.engine === NATIVE_DSH_TURN_CONTRACT && ownership.turn === turn
+    && Number.isSafeInteger(turn) && turn > 0 && text(ownership.binding), 'native_dsh_ownership_invalid');
+  const admission = parseNativeJson(ownership.binding);
+  invariant(fields(admission, 'configDigest,configuration,contract,identity,jsonCodec,messages,source')
+    && admission.contract === NATIVE_DSH_ADMISSION_CONTRACT && admission.jsonCodec === NATIVE_JSON_CODEC
+    && canonical(admission) === ownership.binding, 'native_dsh_admission_invalid');
+  const { identity, configuration, source, messages } = admission;
+  invariant(fields(identity, 'buildId,parentRunId,runId,scope,sessionId,taskChainId,turnId')
+    && text(identity.sessionId) && identity.sessionId === sessionId && identity.turnId === String(turn)
+    && text(identity.buildId) && text(identity.taskChainId)
+    && (identity.parentRunId === null || text(identity.parentRunId)), 'native_dsh_admission_identity_invalid');
+  scopeKey(identity.scope);
+  invariant(identity.runId === `native-dsh-${hash({ contract: NATIVE_DSH_TURN_CONTRACT,
+    scope: identity.scope, sessionId, turn })}`, 'native_dsh_admission_identity_invalid');
+  invariant(fields(source, 'model,provider') && text(source.model) && text(source.provider)
+    && Array.isArray(messages) && messages.length > 0
+    && messages.every(message => message?.role === 'user' && text(message.id) && Array.isArray(message.content)),
+  'native_dsh_admission_input_invalid');
+  invariant(hash(configuration) === admission.configDigest
+    && canonical(configure(configuration)) === canonical(configuration), 'native_dsh_admission_configuration_invalid');
+  return admission;
+}
+
+/** The Host must provide the maintained lifecycle capability before any dispatch. */
+export function nativeDshOwnershipHost(agent) {
+  const host = agent?.externalTurns;
+  invariant(host?.contract === NATIVE_DSH_OWNERSHIP_HOST && typeof host.claim === 'function'
+    && typeof host.pending === 'function' && typeof host.resume === 'function', 'native_dsh_ownership_host_required');
+  return host;
+}