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

package/src/native/tool-authority.mjs

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import { canonical, copy, invariant, scopeKey, sourceReadBudgetForState, activePlanMode,
+  projectRunToolAuthority } from '@kingsoftcloud/agentkit-harness-core';
+const hash = value => createHash('sha256').update(canonical(value)).digest('hex');
+
+/** A DSH registration/permission decision alone cannot authorize a later
+ * publication after waiting for a workspace lock. Re-read the Native ledger. */
+export function createNativeToolAuthority({ scope, sessionId, store, isClosed = () => false, expectedHostBindingDigest }) {
+  const read = createNativeToolAuthorityReader({ scope, sessionId, store, isClosed, expectedHostBindingDigest });
+  return request => read(request) !== null;
+}
+
+/** Read one validated current authority view. Callers may inspect its immutable
+ * identity; it grants no authority after another wait or generation change. */
+export function createNativeToolAuthorityReader({ scope, sessionId, store, isClosed = () => false, expectedHostBindingDigest }) {
+  scopeKey(scope);
+  invariant(typeof sessionId === 'string' && sessionId.trim() && typeof store?.load === 'function'
+    && typeof isClosed === 'function' && (expectedHostBindingDigest === undefined
+      || typeof expectedHostBindingDigest === 'string' && expectedHostBindingDigest.trim() && expectedHostBindingDigest.length <= 1024), 'studio_native_tool_authority_binding_invalid');
+  const fixedScope = copy(scope);
+  return request => {
+    try {
+      if (isClosed() || !(request.signal instanceof AbortSignal) || request.signal.aborted
+        || canonical(request.scope) !== canonical(fixedScope) || request.sessionId !== sessionId) return null;
+      let current;
+      if (store.toolAuthority) current = store.toolAuthority(fixedScope, request.runId);
+      else {
+        const record = store.authority?.(fixedScope, request.runId) ?? store.load(fixedScope, request.runId);
+        current = projectRunToolAuthority({ ...record, pendingIntent: 'pendingIntent' in record ? record.pendingIntent
+          : record.intents.find(item => item.operationKey === record.snapshot.pendingIntent) ?? null });
+      }
+      const snapshot = current.snapshot;
+      if (expectedHostBindingDigest !== undefined && current.configuration.hostBindingDigest !== expectedHostBindingDigest) return null;
+      if (request.resultGovernance !== (current.configuration.artifactPolicy === 'runtime-artifacts/v1'
+        ? 'runtime-artifacts/v1' : undefined)) return null;
+      if (!snapshot || snapshot.phase !== 'executing_tools'
+        || !['sessionId', 'runId', 'turnId', 'buildId', 'parentRunId', 'taskChainId'].every(key => request[key] === snapshot[key])
+        || !current.lease || current.lease.expiresAt <= Date.now()
+        || !Number.isSafeInteger(request.executionFence) || request.executionFence <= 0
+        || current.lease.fence !== request.executionFence) return null;
+      const intent = current.pendingIntent;
+      if (intent?.kind !== 'tool' || intent.status !== 'running' || intent.claimedFence !== request.executionFence
+        || !Array.isArray(intent.payload?.calls)) return null;
+      const index = intent.payload.calls.findIndex(call => canonical(call) === canonical(request.call));
+      if (index < 0 || request.operationKey !== (intent.payload.calls.length === 1
+        ? intent.operationKey : `${intent.operationKey}:call:${index + 1}`)) return null;
+      if (request.definition.approvalPolicy === 'durable-preflight/v1'
+        && canonical(request.interaction ?? null) !== canonical(intent.payload.interaction ?? null)) return null;
+      const definition = current.configuration.tools.find(tool => tool.name === request.call.name);
+      if (request.planMode !== (activePlanMode(snapshot, current.configuration)
+        && definition?.planModeCommandPolicy ? 'session-plan/v1' : undefined)) return null;
+      if (canonical(request.sourceReadBudget ?? null) !== canonical(sourceReadBudgetForState(snapshot, current.configuration,
+        current.sourceReadMessage, request.call, hash) ?? null)) return null;
+      return definition && canonical(definition) === canonical(request.definition) ? current : null;
+    } catch { return null; }
+  };
+}
+
+/** Current read intent authority never grants execution rights to the old tool. */
+export function createNativeToolReceiptAuthority(options) {
+  return originalEffectAuthority(options, false);
+}
+/** A new operator write claim; a receipt-read claim is never interchangeable. */
+export function createNativeWorkspaceRepairAuthority(options) {
+  return originalEffectAuthority(options, true);
+}
+function originalEffectAuthority({ scope, sessionId, store, isClosed = () => false }, repair) {
+  scopeKey(scope); const fixedScope = copy(scope);
+  invariant(typeof sessionId === 'string' && sessionId.trim() && typeof store?.load === 'function',
+    'studio_native_tool_receipt_binding_invalid');
+  return request => {
+    try {
+      if (isClosed() || !(request.signal instanceof AbortSignal) || request.signal.aborted
+        || request.contract !== (repair ? 'agentkit.workspace-compensation/v1' : 'agentkit.tool-receipt-observation/v1')
+        || canonical(request.scope) !== canonical(fixedScope) || request.sessionId !== sessionId) return false;
+      const record = store.load(fixedScope, request.runId), snapshot = record.snapshot;
+      if (snapshot.phase !== 'reconciling_tool' || !record.lease || record.lease.expiresAt <= Date.now()
+        || record.lease.fence !== request.executionFence
+        || !['sessionId', 'runId', 'turnId', 'buildId', 'parentRunId', 'taskChainId'].every(key => request[key] === snapshot[key])
+        || snapshot.toolReconciliation?.operationKey !== request.originalOperationKey
+        || snapshot.toolReconciliation?.callId !== request.call?.callId) return false;
+      const query = record.intents.find(item => item.operationKey === snapshot.pendingIntent);
+      if (query?.kind !== (repair ? 'workspace_repair' : 'tool_receipt') || query.status !== 'running' || query.claimedFence !== request.executionFence
+        || query.operationKey !== request.operationKey || query.payload.contract !== request.contract
+        || query.payload.originalOperationKey !== request.originalOperationKey
+        || query.payload.originalClaimedFence !== request.originalClaimedFence || query.payload.callId !== request.call.callId) return false;
+      const original = record.intents.find(item => item.operationKey === request.originalOperationKey);
+      const receipt = record.receipts.find(item => item.operationKey === request.originalOperationKey);
+      const definition = record.configuration.tools.find(item => item.name === request.call.name);
+      return original?.kind === 'tool' && original.status === 'running' && original.claimedFence === request.originalClaimedFence
+        && Array.isArray(original.payload.calls) && original.payload.calls.length === 1
+        && canonical(original.payload.calls[0]) === canonical(request.call)
+        && Boolean(receipt && (receipt.status === 'uncertain' || receipt.result.results?.[0]?.status === 'uncertain'))
+        && definition?.recoveryPolicy === 'receipt-observation/v1'
+        && (!repair || definition.workspaceRepairPolicy === 'preimage-compensation/v1')
+        && canonical(definition) === canonical(request.definition);
+    } catch { return false; }
+  };
+}

package/src/native/tool-guidance.mjs

@@ -0,0 +1,12 @@
+/** Tool owners contribute usage guidance; the core only assembles admitted contributions. */
+export function nativeToolModelGuidance(tool, { commandBackend } = {}) {
+  if (tool.name === 'read_workspace_file' && tool.workspaceMediaPolicy === 'bounded-image-read/v1')
+    return ['Inspect workspace text or supported images through this tool. A partial read is not a complete observation.'];
+  if (tool.name === 'run_command') return [
+    'Use the bound backend and its reported cwd. Read saved output using task_id and cursors; a truncated preview is not command failure. Never relaunch an unknown write to recover output.',
+    ...(commandBackend === 'e2b' ? ['Commands run in a remote sandbox. Workspace paths describe the host filesystem; do not assume they exist as remote command paths.'] : []),
+  ];
+  if (tool.childBudgetPolicy === 'start/v1' || tool.childBudgetPolicy === 'delegate/v1')
+    return ['Child tasks share the parent task budget and permissions. Set smaller explicit limits when useful; await owned results rather than duplicating the work.'];
+  return [];
+}

package/src/native/tool-observation.mjs

@@ -0,0 +1,75 @@
+import { terminal } from '@kingsoftcloud/agentkit-harness-core';
+
+/** Content-free presentation evidence. Never a permission, retry or execution input. */
+export const NATIVE_TOOL_OBSERVATION = 'agentkit.native-tool-observation/v1';
+export function advanceNativeToolObservation(previous, { intents = [], receipts = [], events = [] }) {
+  const calls = new Map((previous?.calls ?? []).map(call => [call.callId, { ...call }]));
+  const byKey = new Map(intents.map(intent => [intent.operationKey, intent]));
+  for (const intent of intents) {
+    if (intent.kind !== 'tool') continue;
+    for (const [index, call] of (intent.payload.calls ?? []).entries()) {
+      const old = calls.get(call.callId), same = old?.operationKey === intent.operationKey;
+      const priorUncertain = !same && (old?.priorUncertain === true || old?.receiptStatus === 'uncertain'
+        || old?.resultStatus === 'uncertain' || old?.eventStatus === 'uncertain');
+      calls.set(call.callId, same ? { ...old, claimed: intent.status === 'running' ? true : old.claimed }
+        : { callId: call.callId, operationKey: intent.operationKey, index,
+          claimed: intent.status === 'running' ? true : intent.status === 'prepared' ? false : null,
+          preparedSeq: 0, receiptStatus: null, resultStatus: null, eventStatus: null, reconciledStatus: null,
+          notDispatched: old?.notDispatched === true, ...(priorUncertain ? { priorUncertain: true } : {}) });
+    }
+  }
+  const byOperation = new Map();
+  for (const call of calls.values()) {
+    if (!byOperation.has(call.operationKey)) byOperation.set(call.operationKey, []);
+    byOperation.get(call.operationKey).push(call);
+  }
+  for (const receipt of receipts) {
+    const intent = byKey.get(receipt.operationKey);
+    if (intent?.kind === 'tool_receipt' && receipt.status === 'committed') {
+      for (const call of byOperation.get(intent.payload.originalOperationKey) ?? [])
+        if (!intent.payload.callId || call.callId === intent.payload.callId)
+        call.reconciledStatus = receipt.result.result?.status ?? null;
+      continue;
+    }
+    for (const call of byOperation.get(receipt.operationKey) ?? []) {
+      call.receiptStatus = receipt.status;
+      call.resultStatus = receipt.status === 'committed' ? receipt.result.results?.[call.index]?.status ?? null : null;
+    }
+  }
+  // Locate the latest attempt before folding completion events. A result from
+  // an earlier attempt cannot erase a later claimed effect with no receipt.
+  for (const event of events) if (event.kind === 'effect.prepared' && event.payload.kind === 'tool')
+    for (const call of byOperation.get(event.payload.operationKey) ?? []) call.preparedSeq = event.seq;
+  for (const event of events) {
+    const call = calls.get(event.payload.callId);
+    if (event.kind === 'tool.not_dispatched') {
+      if (call) call.notDispatched = true;
+      else calls.set(event.payload.callId, { callId: event.payload.callId, operationKey: null, index: null,
+        claimed: null, preparedSeq: 0, receiptStatus: null, resultStatus: null, eventStatus: null,
+        reconciledStatus: null, notDispatched: true });
+    } else if (event.kind === 'tool.completed') {
+      if (call && event.seq >= call.preparedSeq) call.eventStatus = event.payload.status;
+      else if (!call) calls.set(event.payload.callId, { callId: event.payload.callId, operationKey: null, index: null,
+        claimed: null, preparedSeq: 0, receiptStatus: null, resultStatus: null, eventStatus: event.payload.status,
+        reconciledStatus: null, notDispatched: false });
+    }
+  }
+  return { contract: NATIVE_TOOL_OBSERVATION, calls: [...calls.values()] };
+}
+
+export function nativeObservedToolStates(observation, snapshot, { driving = false } = {}) {
+  return observation.calls.flatMap(call => {
+    const result = call.reconciledStatus ?? call.eventStatus ?? call.resultStatus;
+    const status = call.notDispatched || call.receiptStatus === 'not_dispatched' ? 'not_dispatched'
+      : { ok: 'completed', error: 'failed', uncertain: 'uncertain' }[result]
+      // A durable preflight refusal is not an effect. It can remain waiting
+      // only while the Run is open. A later attempt replaces this evidence.
+      ?? (result === 'approval_required' ? terminal(snapshot.phase) ? 'not_dispatched' : 'waiting'
+          : call.receiptStatus === 'uncertain' || call.priorUncertain ? 'uncertain'
+          : terminal(snapshot.phase) && !call.receiptStatus && call.claimed !== null
+            ? call.claimed ? 'uncertain' : 'not_dispatched'
+            : driving && !call.receiptStatus && snapshot.pendingIntent === call.operationKey
+              && snapshot.phase === 'executing_tools' ? 'running' : null);
+    return status ? [{ callId: call.callId, status }] : [];
+  });
+}

package/src/native/tool-states.mjs

@@ -0,0 +1,14 @@
+import { nativeDeliveryId } from './delivery-timeline.mjs';
+import { advanceNativeToolObservation, nativeObservedToolStates } from './tool-observation.mjs';
+
+/** A content-free display projection, never a tool execution authority. */
+export function nativeToolStates(record, { driving = false } = {}) {
+  if (!record) return null;
+  return projectedNativeToolStates(advanceNativeToolObservation(null, record), record.snapshot, { driving });
+}
+
+export function projectedNativeToolStates(observation, snapshot, options) {
+  return { contract: 'agentkit.native-tool-states/v1', runId: snapshot.runId,
+    calls: nativeObservedToolStates(observation, snapshot, options).map(call => ({ ...call,
+      callId: nativeDeliveryId(snapshot.scope, snapshot.runId, `call:${call.callId}`) })) };
+}

package/src/native/verification-authority.mjs

@@ -0,0 +1,37 @@
+import { createHash } from 'node:crypto';
+import { canonical, copy, effectiveRunConfiguration, invariant, scopeKey, webDelivery } from '@kingsoftcloud/agentkit-harness-core';
+const digest = value => createHash('sha256').update(canonical(value)).digest('hex');
+
+/** A verifier may observe through a granted tool while its own verify intent
+ * is claimed. It cannot borrow ordinary tool-dispatch authority or execute an
+ * old model call. Every publication after permission waits re-reads this claim. */
+export function createNativeVerificationAuthority({ scope, sessionId, store, toolName, isClosed = () => false }) {
+  scopeKey(scope); const boundScope = copy(scope);
+  invariant(typeof sessionId === 'string' && sessionId && typeof store?.load === 'function'
+    && typeof toolName === 'string' && toolName && typeof isClosed === 'function', 'native_verification_authority_binding_invalid');
+  return request => {
+    try {
+      if (isClosed() || !(request.signal instanceof AbortSignal) || request.signal.aborted
+        || canonical(request.scope) !== canonical(boundScope) || request.sessionId !== sessionId) return false;
+      const current = store.authority?.(boundScope, request.runId) ?? store.load(boundScope, request.runId), snapshot = current.snapshot;
+      if (snapshot.phase !== 'verifying' || !current.lease || current.lease.expiresAt <= Date.now()
+        || !Number.isSafeInteger(request.executionFence) || request.executionFence <= 0
+        || current.lease.fence !== request.executionFence
+        || !['sessionId', 'runId', 'turnId', 'buildId', 'parentRunId', 'taskChainId'].every(key => request[key] === snapshot[key])) return false;
+      const intent = 'pendingIntent' in current ? current.pendingIntent
+        : current.intents.find(item => item.operationKey === snapshot.pendingIntent);
+      if (intent?.kind !== 'verify' || intent.status !== 'running' || intent.claimedFence !== request.executionFence
+        || intent.operationKey !== request.operationKey || !snapshot.candidate
+        || request.candidateId !== snapshot.candidate.candidateId
+        || canonical(request.candidate) !== canonical(snapshot.candidate)
+        || canonical(intent.payload.candidate) !== canonical(snapshot.candidate)
+        || request.snapshot?.revision !== snapshot.revision || request.snapshot?.configDigest !== snapshot.configDigest) return false;
+      const config = effectiveRunConfiguration(snapshot, current.configuration, digest);
+      if (canonical(request.contract) !== canonical(config.contract)
+        || !config.tools.some(tool => tool.name === toolName && tool.observationRole === 'browser')
+        || config.contract.allowedToolNames !== null && !config.contract.allowedToolNames.includes(toolName)) return false;
+      const entry = webDelivery(snapshot);
+      return typeof request.entryPath === 'string' && request.entryPath.length > 0 && (!entry || entry.path === request.entryPath);
+    } catch { return false; }
+  };
+}