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

package/src/native/component-tools.mjs

@@ -0,0 +1,280 @@
+/**
+ * Native component_status tool port.
+ *
+ * Ports ksadk.toolsets.platform.component_status: a read-only tool that reports
+ * the AgentEngine built-in toolset and runtime binding status. The Host passes
+ * a fixed admission status snapshot at construction; the port never reads
+ * process.env, the filesystem, or the network, never auto-discovers bindings,
+ * and never exposes credentials. A component that is not bound is reported
+ * explicitly as not enabled.
+ *
+ * Status is data, not a capability authorization: the real Native ledger owns
+ * authority via the required assertCurrent callback, and status never lets the
+ * model choose an environment, service endpoint, or backend.
+ */
+import { canonical, copy, invariant, scopeKey, toolInputRejection, matchesToolExecutionContract } from '@kingsoftcloud/agentkit-harness-core';
+
+export const NATIVE_COMPONENT_TOOLS_CONTRACT = 'agentkit.native-component-tools/v1';
+
+const MAX_RESULT_BYTES = 64 * 1024;
+const MAX_ARRAY = 4096;
+const MAX_STRING = 8192;
+const ENABLED_DISABLED = new Set(['enabled', 'not_enabled']);
+
+/** Reject any key in object that is not in the allowlist. */
+function rejectUnknownKeys(object, allow, prefix) {
+  for (const key of Object.keys(object)) {
+    invariant(allow.has(key), `component_status_unknown_field:${prefix}${key}`);
+  }
+}
+
+/** Validate a Host-provided status snapshot with precise per-field allowlists
+ *  at every nesting level. Unknown fields (including secrets) are rejected,
+ *  never silently dropped. Returns a frozen deep clone the caller cannot
+ *  mutate after construction. Missing tool lists default to empty — the port
+ *  never claims tools are available that the Host did not bind. */
+export function componentStatusSnapshot(raw) {
+  invariant(raw && typeof raw === 'object' && !Array.isArray(raw), 'component_status_invalid');
+  rejectUnknownKeys(raw, new Set(['summary', 'skill_space', 'skill_runtime', 'sandbox', 'workspace']), '');
+
+  const summary = group(raw.summary, new Set(['model', 'knowledge_base_bound', 'long_term_memory_bound',
+    'skill_space_bound', 'isolated_execution', 'sandbox_direct_tools']), 'summary.');
+  const skillSpace = group(raw.skill_space, new Set(['space_ids', 'user_space_ids', 'public_space_ids',
+    'service_url', 'aicp_endpoint_mode', 'tools']), 'skill_space.');
+  const skillRuntime = group(raw.skill_runtime, new Set(['backend', 'enabled', 'template_bound',
+    'request_protocol']), 'skill_runtime.');
+  const sandbox = group(raw.sandbox, new Set(['backend', 'enabled', 'template_bound', 'tools']), 'sandbox.');
+  const workspace = group(raw.workspace, new Set(['root', 'tools', 'boundary', 'editing_model']), 'workspace.');
+
+  const result = deepFreeze(copy({
+    // ok:true is a Host-fixed read-only result the port always emits (mirrors
+    // the Python component_status return). It is NOT accepted from the input
+    // status snapshot — the model cannot set it.
+    ok: true,
+    summary: {
+      model: stringField(summary.model),
+      knowledge_base_bound: boolField(summary.knowledge_base_bound),
+      long_term_memory_bound: boolField(summary.long_term_memory_bound),
+      skill_space_bound: boolField(summary.skill_space_bound),
+      isolated_execution: enabledDisabled(summary.isolated_execution),
+      sandbox_direct_tools: enabledDisabled(summary.sandbox_direct_tools),
+    },
+    skill_space: {
+      space_ids: stringArrayField(skillSpace.space_ids),
+      user_space_ids: stringArrayField(skillSpace.user_space_ids),
+      public_space_ids: stringArrayField(skillSpace.public_space_ids),
+      service_url: stringField(skillSpace.service_url),
+      aicp_endpoint_mode: stringField(skillSpace.aicp_endpoint_mode) || 'auto',
+      tools: stringArrayField(skillSpace.tools),
+    },
+    skill_runtime: {
+      backend: stringField(skillRuntime.backend) || 'disabled',
+      enabled: boolField(skillRuntime.enabled),
+      template_bound: boolField(skillRuntime.template_bound),
+      request_protocol: stringField(skillRuntime.request_protocol) || '--request-file JSON envelope',
+    },
+    sandbox: {
+      backend: stringField(sandbox.backend) || 'disabled',
+      enabled: boolField(sandbox.enabled),
+      template_bound: boolField(sandbox.template_bound),
+      tools: stringArrayField(sandbox.tools),
+    },
+    workspace: {
+      root: stringField(workspace.root),
+      tools: stringArrayField(workspace.tools),
+      boundary: stringField(workspace.boundary)
+        || 'Workspace tools are confined to the AgentEngine UI workspace directory.',
+      editing_model: stringField(workspace.editing_model)
+        || 'write tools support whole-file writes; edit_workspace_file supports exact snippet '
+          + 'replacement; lint_workspace_file provides lightweight built-in checks.',
+    },
+  }));
+  invariant(Buffer.byteLength(canonical(result), 'utf-8') <= MAX_RESULT_BYTES, 'component_status_oversized');
+  return result;
+}
+
+function group(value, allow, prefix) {
+  if (value === undefined || value === null) return {};
+  invariant(value && typeof value === 'object' && !Array.isArray(value), 'component_status_field_invalid');
+  rejectUnknownKeys(value, allow, prefix);
+  return value;
+}
+
+function boolField(value) {
+  invariant(value === undefined || typeof value === 'boolean', 'component_status_field_invalid');
+  return value === true;
+}
+
+function stringField(value) {
+  if (value === undefined || value === null) return '';
+  invariant(typeof value === 'string' && value.length <= MAX_STRING, 'component_status_field_invalid');
+  return value;
+}
+
+function stringArrayField(value) {
+  if (value === undefined || value === null) return [];
+  invariant(Array.isArray(value) && value.length <= MAX_ARRAY, 'component_status_field_invalid');
+  for (const item of value) invariant(typeof item === 'string' && item.length <= MAX_STRING, 'component_status_field_invalid');
+  return value;
+}
+
+function enabledDisabled(value) {
+  if (value === undefined || value === null) return 'not_enabled';
+  if (typeof value === 'boolean') return value ? 'enabled' : 'not_enabled';
+  invariant(typeof value === 'string' && ENABLED_DISABLED.has(value), 'component_status_field_invalid');
+  return value;
+}
+
+function deepFreeze(value) {
+  if (value && typeof value === 'object') {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+
+function errorResult(code) {
+  return { status: 'error', content: { code, executed: false } };
+}
+
+const FORMAL_DEFINITION = deepFreeze({
+  name: 'component_status',
+  description: 'Report the AgentEngine built-in toolset and runtime binding status '
+    + '(model, knowledge base, long-term memory, skill space, skill runtime, sandbox, workspace). '
+    + 'Read-only: returns the Host-fixed admission snapshot; does not discover bindings, read '
+    + 'environment variables, or expose credentials.',
+  parameters: { type: 'object', properties: {}, additionalProperties: false },
+  readOnly: true,
+  concurrentSafe: true,
+  permissions: [],
+  timeoutMs: 30000,
+  contextRole: 'none',
+  observationRole: 'none',
+  progressObservation: false,
+  contextRetention: 'normal',
+});
+
+/** Return an isolated copy of the fixed formal component_status definition.
+ *  The Host uses this to declare the tool schema before a real Session instance
+ *  exists. It does not construct a fake execution identity — only the
+ *  definition shape. Each call returns a fresh copy so a caller mutating the
+ *  returned array or definition cannot affect the port's own definitions. */
+export function nativeComponentToolDefinitions() {
+  return [copy(FORMAL_DEFINITION)];
+}
+
+/**
+ * @param {object} opts
+ * @param {object} opts.scope Trusted bound RunScope (validated via scopeKey).
+ * @param {string} opts.sessionId Trusted bound session id.
+ * @param {object} opts.status Host-fixed admission status snapshot.
+ * @param {(request:object)=>boolean} opts.assertCurrent Host authority check (required).
+ * @returns {{contract,definitions,execute(request):Promise<object>,close()}}
+ */
+export function createNativeComponentTools({ scope, sessionId, status, assertCurrent } = {}) {
+  invariant(scope && typeof scope === 'object', 'component_status_scope_missing');
+  // Validate all four scope domains via the core scopeKey (throws on missing/empty).
+  scopeKey(scope);
+  invariant(typeof sessionId === 'string' && sessionId.trim(), 'component_status_session_id_missing');
+  invariant(typeof assertCurrent === 'function', 'component_status_assert_current_required');
+
+  const boundScope = deepFreeze(copy(scope));
+  const boundSessionId = String(sessionId);
+  const frozenStatus = componentStatusSnapshot(status);
+  const statusCanonical = canonical(frozenStatus);
+  invariant(Buffer.byteLength(statusCanonical, 'utf-8') <= MAX_RESULT_BYTES, 'component_status_oversized');
+
+  const frozenDefinition = deepFreeze(copy(FORMAL_DEFINITION));
+  const definitions = Object.freeze([frozenDefinition]);
+
+  let closed = false;
+
+  /** Strict synchronous authority + identity guard. Runs before AND after the
+   *  assertCurrent call. Verifies: closed, original signal instance ===, signal
+   *  not aborted, bound scope/session match, and the sealed request body has not
+   *  drifted. assertCurrent must return a strict boolean; a thenable is a
+   *  contract violation whose rejection is observed (never an
+   *  unhandledRejection). A getter/throw is converted to a bounded error. */
+  function guard(sealed, request) {
+    if (closed) return { ok: false, code: 'component_status_closed' };
+    if (request.signal !== sealed.originalSignal) return { ok: false, code: 'component_status_signal_drifted' };
+    if (sealed.originalSignal.aborted) return { ok: false, code: 'component_status_canceled' };
+    if (canonical(request.scope) !== sealed.scopeCanonical) return { ok: false, code: 'component_status_scope_drifted' };
+    if (request.sessionId !== boundSessionId) return { ok: false, code: 'component_status_session_drifted' };
+    let live;
+    try { live = canonical(sealed.stripSignal(request)); }
+    catch { return { ok: false, code: 'component_status_request_invalid' }; }
+    if (live !== sealed.bodyCanonical) return { ok: false, code: 'component_status_body_drifted' };
+    return { ok: true };
+  }
+
+  function callAssertCurrent(request) {
+    let verdict;
+    try { verdict = assertCurrent(request); }
+    catch { return { ok: false, code: 'component_status_assert_current_invalid' }; }
+    if (verdict && typeof verdict === 'object' && typeof verdict.then === 'function') {
+      verdict.then(() => {}, () => {}); // observe the rejection
+      return { ok: false, code: 'component_status_assert_current_invalid' };
+    }
+    if (typeof verdict !== 'boolean') return { ok: false, code: 'component_status_assert_current_invalid' };
+    if (!verdict) return { ok: false, code: 'component_status_authority_lost' };
+    return { ok: true };
+  }
+
+  async function execute(request) {
+    if (!request || typeof request !== 'object') return errorResult('component_status_request_invalid');
+
+    // Validate formal parameters before anything else.
+    const rejection = toolInputRejection(frozenDefinition, request.call);
+    if (rejection) return { status: 'error', content: rejection };
+
+    // Compare the fixed execution protocol; the full original definition is
+    // still sealed into, and checked by, the current intent authority.
+    if (!matchesToolExecutionContract(request.definition, frozenDefinition))
+      return errorResult('component_status_definition_mismatch');
+
+    // Require a real AbortSignal by instance identity.
+    const signal = request.signal;
+    if (!(signal instanceof AbortSignal)) return errorResult('component_status_signal_missing');
+
+    // Validate the full Native identity fields are present and match the bound
+    // scope/session. The model cannot call with a foreign principal.
+    if (canonical(request.scope) !== canonical(boundScope)) return errorResult('component_status_scope_mismatch');
+    if (request.sessionId !== boundSessionId) return errorResult('component_status_session_mismatch');
+
+    // Seal the complete request body (excluding the non-JSON signal) and the
+    // original signal instance so every guard can detect drift.
+    const stripSignal = ({ signal: _s, ...rest }) => rest;
+    let bodyCanonical;
+    try { bodyCanonical = canonical(stripSignal(request)); }
+    catch { return errorResult('component_status_request_invalid'); }
+    const sealed = { originalSignal: signal, scopeCanonical: canonical(boundScope), bodyCanonical, stripSignal };
+
+    // Guard before authority.
+    let pre = guard(sealed, request);
+    if (!pre.ok) return errorResult(pre.code);
+
+    // Authority check.
+    let auth = callAssertCurrent(request);
+    if (!auth.ok) return errorResult(auth.code);
+
+    // Guard after authority: closed, signal, body, scope must not have drifted.
+    let post = guard(sealed, request);
+    if (!post.ok) return errorResult(post.code);
+
+    // Build a fresh copy of the frozen snapshot for this call.
+    const payload = copy(frozenStatus);
+
+    // Final guard: re-verify closed/cancel/body/signal one last time before
+    // returning. A close or abort that lands between the post-guard and here
+    // is caught.
+    let final = guard(sealed, request);
+    if (!final.ok) return errorResult(final.code);
+
+    return { status: 'ok', content: payload };
+  }
+
+  function close() { closed = true; }
+
+  return { contract: NATIVE_COMPONENT_TOOLS_CONTRACT, definitions, execute, close };
+}

package/src/native/context-counter.mjs

@@ -0,0 +1,133 @@
+import { createHash } from 'node:crypto';
+import { canonical, invariant } from '@kingsoftcloud/agentkit-harness-core';
+import { buildNativeModelRequest } from './model-request.mjs';
+
+// Pinned reference: native_planning.py + workspace_read_budget.py at 355059d.
+// These are conservative estimated tokens, never reported provider usage or a
+// claim of exact provider tokenization. The wire projection is the HTTP one.
+export const NATIVE_CONTEXT_COUNTER_ID = 'agentkit.studio-cjk-ascii-estimate-125-wire-image/v1';
+const whitespace = /^[\u0009-\u000d\u001c-\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+|[\u0009-\u000d\u001c-\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+$/gu;
+export function estimateNativeText(text) {
+  invariant(typeof text === 'string', 'context_counter_text_invalid');
+  let cjk = 0, other = 0;
+  for (const char of text.replace(whitespace, '')) {
+    const code = char.codePointAt(0);
+    if (code >= 0x3400 && code <= 0x4dbf || code >= 0x4e00 && code <= 0x9fff || code >= 0xf900 && code <= 0xfaff) cjk++;
+    else other++;
+  }
+  return Math.max(1, Math.ceil((Math.floor(cjk * 1.5) + Math.ceil(other / 4)) * 1.25));
+}
+
+/** Estimate actual provider fields, charging image bytes separately from text. */
+export function estimateNativeWireInput(body, protocol = Array.isArray(body.input) && !body.messages ? 'openai-responses' : 'openai-chat') {
+  const wire = structuredClone(body);
+  for (const key of ['model', 'stream', 'stream_options', 'max_tokens', 'max_completion_tokens', 'max_output_tokens']) delete wire[key];
+  if (protocol === 'anthropic-messages') {
+    expandToolReferences(wire.messages, wire.tools);
+    // Deferred definitions are HTTP catalog data, not initial model context.
+    if (wire.tools) wire.tools = wire.tools.filter(tool => tool.defer_loading !== true);
+  }
+  return priceWireSurface(wire, protocol === 'openai-responses' ? wire.input : wire.messages);
+}
+function expandToolReferences(messages = [], tools = []) {
+  const catalog = new Map(tools.map(tool => [tool.name, tool]));
+  for (const message of messages) {
+    if (!Array.isArray(message.content)) continue;
+    for (const result of message.content) {
+      if (result.type !== 'tool_result' || !Array.isArray(result.content)) continue;
+      result.content = result.content.map(block => {
+        if (block.type !== 'tool_reference') return block;
+        const definition = catalog.get(block.tool_name);
+        invariant(definition, 'context_counter_tool_reference_unknown');
+        const { defer_loading: _deferred, cache_control: _cache, ...expanded } = definition;
+        return { type: 'text', text: canonical(expanded) };
+      });
+    }
+  }
+}
+function priceWireSurface(surface, messages = []) {
+  let images = 0;
+  const reserve = url => {
+    invariant(typeof url === 'string' && url, 'context_counter_image_invalid');
+    images += url.startsWith('data:image/') ? Math.max(2048, Math.ceil(url.slice(url.indexOf(',') + 1).length / 8)) : 8192;
+  };
+  const visit = value => {
+    if (value === null || typeof value !== 'object') return;
+    if (value.type === 'image_url' && value.image_url?.url) {
+      reserve(value.image_url.url); value.image_url = { url: '[Host image budgeted separately]' }; return;
+    }
+    if (value.type === 'input_image' && typeof value.image_url === 'string') {
+      reserve(value.image_url); value.image_url = '[Host image budgeted separately]'; return;
+    }
+    if (value.type === 'image' && value.source) {
+      const source = value.source;
+      if (source.type === 'base64') reserve(`data:${source.media_type};base64,${source.data}`);
+      else if (source.type === 'url') reserve(source.url);
+      else invariant(false, 'context_counter_image_invalid');
+      value.source = { type: 'host-budgeted-image' }; return;
+    }
+    if (value.type === 'tool_result' && Array.isArray(value.content)) value.content.forEach(visit);
+  };
+  // Only provider message slots contain image blocks. Tool schemas and text
+  // may describe image-shaped data; that data must be priced as ordinary JSON.
+  for (const message of messages ?? []) {
+    if (Array.isArray(message.content)) message.content.forEach(visit);
+    if (message.type === 'function_call_output' && Array.isArray(message.output)) message.output.forEach(visit);
+  }
+  const count = estimateNativeText(canonical(surface)) + images;
+  invariant(Number.isSafeInteger(count) && count >= 0, 'context_counter_overflow');
+  return count;
+}
+
+/** Price actual provider fields for one logical message, including replay/media.
+ * Synthetic protocol partners only make the normal wire builder callable; their
+ * fields are excluded from the returned cost. No model or tool is executed. */
+export function estimateNativeMessage(binding, request) {
+  const message = structuredClone(request.message), messages = [message];
+  if (message.role === 'assistant' && message.toolCalls?.length) {
+    messages.push(...message.toolCalls.map(call => ({ role: 'tool', name: call.name, callId: call.callId, content: '' })));
+  } else if (message.role === 'tool') {
+    messages.unshift({ role: 'assistant', content: '', toolCalls: [{ callId: message.callId,
+      name: request.profile.providerToolSearchPolicy === 'anthropic-deferred/v1' && message.discoveredToolNames !== undefined
+        ? 'ToolSearch' : message.name || 'source', arguments: {} }] });
+  }
+  const tools = request.profile.providerToolSearchPolicy === 'anthropic-deferred/v1' ? request.tools ?? [] : [];
+  const built = buildNativeModelRequest(binding, { ...request, messages, tools, finalizationOnly: false });
+  const body = JSON.parse(built.body);
+  let projected;
+  if (binding.protocol === 'openai-responses') {
+    if (message.role === 'system') return priceWireSurface({ instructions: body.instructions ?? '' });
+    projected = body.input.filter(item => message.role === 'tool' ? item.type !== 'function_call'
+      : message.role === 'assistant' ? item.type !== 'function_call_output' : true);
+  } else if (binding.protocol === 'anthropic-messages' && message.role === 'system') {
+    return priceWireSurface(body.system ?? '');
+  } else {
+    projected = body.messages.filter(item => message.role === 'tool' ? item.role !== 'assistant'
+      : message.role === 'assistant' ? item.role === 'assistant' : true);
+  }
+  invariant(projected.length > 0, 'context_counter_message_invalid');
+  if (binding.protocol === 'anthropic-messages') expandToolReferences(projected, body.tools);
+  return priceWireSurface(projected.length === 1 ? projected[0] : projected, projected);
+}
+
+export function createNativeContextPort({ protocol, model, parameters = {} } = {}) {
+  invariant(['openai-chat', 'openai-responses', 'anthropic-messages'].includes(protocol)
+    && typeof model === 'string' && model.trim(), 'context_counter_binding_invalid');
+  const binding = { protocol, model, parameters: structuredClone(parameters),
+    baseUrl: 'https://native-counter.invalid/v1', apiKey: 'counting-only' };
+  const tokenizerDigest = createHash('sha256').update(canonical({ policy: NATIVE_CONTEXT_COUNTER_ID,
+    protocol, model, parameters: binding.parameters })).digest('hex');
+  return { tokens: Object.freeze({ tokenizerId: NATIVE_CONTEXT_COUNTER_ID, tokenizerDigest,
+    async countText(request) { request.signal.throwIfAborted(); return estimateNativeText(request.text); },
+    async countMessage(request) {
+      request.signal.throwIfAborted(); const count = estimateNativeMessage(binding, request);
+      request.signal.throwIfAborted(); return count;
+    },
+    async countRequest(request) {
+      request.signal.throwIfAborted();
+      const built = buildNativeModelRequest(binding, { ...request, finalizationOnly: false });
+      const count = estimateNativeWireInput(JSON.parse(built.body), binding.protocol);
+      request.signal.throwIfAborted(); return count;
+    },
+  }) };
+}

package/src/native/context-markers.mjs

@@ -0,0 +1,51 @@
+import { nativeDeliveryId } from './delivery-timeline.mjs';
+import { copy } from '@kingsoftcloud/agentkit-harness-core';
+
+/** Read-only timeline facts; proposals and summary model calls never mean adoption. */
+export function advanceNativeContextMarkerState(previous, record) {
+  const { snapshot, events = [] } = record;
+  const state = copy(previous ?? { anchor: { kind: 'start' }, adopted: 0, markers: [] });
+  let { anchor, adopted } = state;
+  const markers = state.markers;
+  let active = markers.findLast(fact => fact.settledSeq === null && fact.marker.status === 'running') ?? null;
+  for (const event of events) {
+    if (event.kind === 'model.completed' && event.eventId) anchor = {
+      kind: 'message', id: nativeDeliveryId(snapshot.scope, snapshot.runId, `response:${event.eventId}`),
+    };
+    if (event.kind === 'tool.completed' && event.payload.callId) anchor = {
+      kind: 'tool', id: nativeDeliveryId(snapshot.scope, snapshot.runId, `call:${event.payload.callId}`),
+    };
+    if (event.kind !== 'context.planned') continue;
+    const count = event.payload.compactions;
+    if (Number.isSafeInteger(count) && count > adopted) {
+      if (active) { active.marker.status = 'completed'; active.settledSeq = event.seq ?? null; active = null; }
+      // Never invent a missing historical start or position.
+      adopted = count;
+    }
+    if (event.payload.action === 'blocked' && active) { active.marker.status = 'failed'; active.settledSeq = event.seq ?? null; active = null; }
+    if (event.payload.action === 'compact' && !active && event.eventId) {
+      active = { marker: { id: nativeDeliveryId(snapshot.scope, snapshot.runId, `context:${event.eventId}`),
+        status: 'running', origin: 'auto', after: { ...anchor } }, settledSeq: null };
+      markers.push(active);
+    }
+  }
+  return { anchor, adopted, markers };
+}
+
+export function nativeContextMarkerFactsFromState(state, snapshot, { driving = false } = {}) {
+  const markers = copy(state.markers);
+  const active = markers.findLast(fact => fact.settledSeq === null && fact.marker.status === 'running');
+  if (active && !driving) {
+    active.marker.status = snapshot.phase === 'failed' ? 'failed' : 'interrupted';
+    if (['completed', 'failed', 'canceled', 'interrupted'].includes(snapshot.phase)) active.settledSeq = snapshot.eventSeq;
+  }
+  return markers;
+}
+
+export function nativeContextMarkerFacts(record, options) {
+  return nativeContextMarkerFactsFromState(advanceNativeContextMarkerState(null, record), record.snapshot, options);
+}
+
+export function nativeContextMarkers(record, options) {
+  return nativeContextMarkerFacts(record, options).map(fact => fact.marker);
+}

package/src/native/context-profile.mjs

@@ -0,0 +1,72 @@
+import { invariant } from '@kingsoftcloud/agentkit-harness-core';
+import { createNativeContextPort } from '@kingsoftcloud/agentkit-harness-node/native/context-counter';
+
+/** Restore the admitted context strategies rather than activating new defaults on an old Run. */
+export function nativeContextDefaults(configuration) {
+  const policy = configuration?.contextPolicy;
+  return {
+    structuredContinuityDefaults: !configuration || policy?.summaryFormatPolicy === 'task-continuity/v1',
+    readWorkingSetDefaults: !configuration || Object.hasOwn(policy ?? {}, 'readWorkingSetCount'),
+    recentToolBatchDefaults: !configuration || Object.hasOwn(policy ?? {}, 'recentToolBatchCount'),
+    pruningThresholdDefaults: !configuration || policy?.pruneThresholdPolicy === 'zcode-local/v1',
+    pruningSummaryDefaults: !configuration || policy?.pruneSummaryPolicy === 'zcode-local/v1',
+    pruningIdleDefaults: !configuration || policy?.pruneIdleThresholdMinutes !== undefined,
+    preModelBudgetDefaults: !configuration || policy?.budgetTiming === 'before-model/v1',
+    orderedContextDefaults: !configuration || policy?.continuityPlacement === 'after-history/v1',
+    sourceReuseDefaults: !configuration || policy?.sourceReusePolicy === 'captured-source/v1',
+  };
+}
+
+/** Bind budget, counter and policy from the resolved Agent revision/Frozen Build. */
+export function bindNativeContext({ description, context = {}, maxTokens, structuredContinuityDefaults = false, preModelBudgetDefaults = false, orderedContextDefaults = false, sourceReuseDefaults = false, readWorkingSetDefaults = false, recentToolBatchDefaults = false, pruningThresholdDefaults = false, pruningSummaryDefaults = false, pruningIdleDefaults = false } = {}) {
+  invariant(context && typeof context === 'object' && !Array.isArray(context), 'studio_native_context_invalid');
+  const raw = context.compaction ?? {};
+  invariant(raw && typeof raw === 'object' && !Array.isArray(raw), 'studio_native_compaction_invalid');
+  const supported = ['enabled', 'thresholdRatio', 'targetRatio', 'summaryMaxTokens', 'maxCompactions',
+    'maxCompactionsWithoutProgress', 'minModelTurnsBetween', 'maxSummaryRetries',
+    'readWorkingSetCount', 'readWorkingSetMaxTokens', 'readWorkingSetTotalMaxTokens',
+    'recentToolBatchCount', 'recentToolBatchMaxTokens', 'recentToolBatchesTotalMaxTokens',
+    'pruneToolResults', 'pruneKeepRecentBatches', 'pruneMinSavedTokens', 'pruneThresholdTokens', 'pruneIdleThresholdMinutes'];
+  invariant(Object.keys(raw).every(key => supported.includes(key)), 'studio_native_compaction_option_unsupported');
+  const requestedWindow = context.maxInputTokens ?? description.contextWindow;
+  const output = maxTokens ?? context.reserveOutputTokens ?? description.maxOutputTokens;
+  invariant(Number.isSafeInteger(requestedWindow) && requestedWindow > 0
+    && Number.isSafeInteger(output) && output > 0 && output <= description.maxOutputTokens, 'studio_native_context_budget_invalid');
+  const contextWindow = Math.min(requestedWindow, description.contextWindow);
+  invariant(output < contextWindow, 'studio_native_context_budget_conflict');
+  const port = createNativeContextPort({ protocol: description.protocol, model: description.modelName, parameters: description.parameters });
+  const triggerRatio = raw.thresholdRatio ?? .72;
+  return { port, profile: { contextWindow, maxOutputTokens: output }, policy: {
+    tokenizerId: port.tokens.tokenizerId, tokenizerDigest: port.tokens.tokenizerDigest,
+    summaryBudgetMode: 'context_bounded_estimate',
+    ...(structuredContinuityDefaults ? { summaryFormatPolicy: 'task-continuity/v1' } : {}),
+    ...(preModelBudgetDefaults ? { budgetTiming: 'before-model/v1' } : {}),
+    ...(orderedContextDefaults && description.protocol === 'openai-chat' ? { continuityPlacement: 'after-history/v1' } : {}),
+    ...(sourceReuseDefaults && description.protocol === 'openai-chat' ? { sourceReusePolicy: 'captured-source/v1' } : {}),
+    enabled: raw.enabled ?? true, triggerRatio, targetRatio: raw.targetRatio ?? Math.min(.45, triggerRatio * .45 / .72),
+    summaryMaxTokens: raw.summaryMaxTokens ?? Math.min(8192, output, Math.max(2048, Math.floor(contextWindow / 8))),
+    maxCompactions: raw.maxCompactions ?? null, maxCompactionsWithoutProgress: raw.maxCompactionsWithoutProgress ?? 8,
+    minModelTurnsBetween: raw.minModelTurnsBetween ?? 2, maxSummaryRetries: raw.maxSummaryRetries ?? 2,
+    ...(['pruneToolResults', 'pruneKeepRecentBatches', 'pruneMinSavedTokens', 'pruneThresholdTokens', 'pruneIdleThresholdMinutes'].some(key => Object.hasOwn(raw, key)) ? {
+      pruneToolResults: raw.pruneToolResults ?? false, pruneKeepRecentBatches: raw.pruneKeepRecentBatches ?? 5,
+      pruneMinSavedTokens: raw.pruneMinSavedTokens ?? 256,
+      ...(Object.hasOwn(raw, 'pruneThresholdTokens') ? { pruneThresholdTokens: raw.pruneThresholdTokens } : {}),
+      ...(pruningThresholdDefaults && raw.pruneToolResults === true && !Object.hasOwn(raw, 'pruneThresholdTokens')
+        ? { pruneThresholdPolicy: 'zcode-local/v1' } : {}),
+      ...(pruningSummaryDefaults && raw.pruneToolResults === true ? { pruneSummaryPolicy: 'zcode-local/v1' } : {}),
+      ...(Object.hasOwn(raw, 'pruneIdleThresholdMinutes') ? { pruneIdleThresholdMinutes: raw.pruneIdleThresholdMinutes }
+        : pruningIdleDefaults && raw.pruneToolResults === true ? { pruneIdleThresholdMinutes: 60 } : {}),
+    } : {}),
+    ...(readWorkingSetDefaults || ['readWorkingSetCount', 'readWorkingSetMaxTokens', 'readWorkingSetTotalMaxTokens']
+      .some(key => Object.hasOwn(raw, key)) ? {
+        readWorkingSetCount: raw.readWorkingSetCount ?? 8, readWorkingSetMaxTokens: raw.readWorkingSetMaxTokens ?? 6000,
+        readWorkingSetTotalMaxTokens: raw.readWorkingSetTotalMaxTokens ?? 16000,
+      } : {}),
+    ...(recentToolBatchDefaults || ['recentToolBatchCount', 'recentToolBatchMaxTokens', 'recentToolBatchesTotalMaxTokens']
+      .some(key => Object.hasOwn(raw, key)) ? {
+        recentToolBatchCount: raw.recentToolBatchCount ?? 4,
+        recentToolBatchMaxTokens: raw.recentToolBatchMaxTokens ?? Math.min(12000, Math.floor(contextWindow / 6)),
+        recentToolBatchesTotalMaxTokens: raw.recentToolBatchesTotalMaxTokens ?? Math.min(24000, Math.floor(contextWindow / 4)),
+      } : {}),
+  } };
+}

package/src/native/context-status.mjs

@@ -0,0 +1,27 @@
+import { nativeContextMarkers } from './context-markers.mjs';
+/** Bounded, content-free view of the committed context planner. Read-only. */
+export function nativeContextStatus(record, { driving = false } = {}) {
+  if (!record?.configuration.contextPolicy) return null;
+  const { snapshot, configuration, events = [] } = record;
+  let admission = null, lastAction = null, admissionSeq = null;
+  for (const event of events) if (event.kind === 'context.planned') {
+    lastAction = event.payload.action;
+    if (event.payload.admission) { admission = event.payload.admission; admissionSeq = event.seq; }
+  }
+  const policy = configuration.contextPolicy;
+  const state = snapshot.contextState;
+  // A proposal/model response is not a committed, adopted compaction.
+  const count = Number.isSafeInteger(state?.compactions) ? state.compactions : 0;
+  const compacting = snapshot.phase === 'compacting' || Boolean(state?.compaction);
+  return {
+    contract: 'agentkit.native-context-status/v1', runId: snapshot.runId, snapshotRevision: snapshot.revision,
+    enabled: policy.enabled, thresholdRatio: policy.triggerRatio, targetRatio: policy.targetRatio,
+    contextWindow: configuration.profile.contextWindow,
+    reservedOutputTokens: configuration.profile.maxOutputTokens,
+    lastRequestInputTokens: admission?.countedInputTokens ?? null,
+    lastAdmissionSeq: admissionSeq,
+    compactions: count,
+    markers: nativeContextMarkers(record, { driving }),
+    state: lastAction === 'blocked' ? 'blocked' : compacting ? driving ? 'compacting' : 'interrupted' : 'idle',
+  };
+}