@cr1992/agentkit 1.0.0

package/domains/orchestrate/contract-tool.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { createHash, randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isHelpRequest, renderCliHelp } from '../../core/cli-help.mjs';
+import { createDigestKit } from '../../core/digest.mjs';
+
+export class ContractError extends Error {}
+
+// strict=false：本 Skill 此前不校验代理对、也不拒绝非有限 number，保持原样。
+// envelopeDigest 的默认摘要字段仍是 contract_digest。
+export const { canonicalJson, envelopeDigest, sha256 } = createDigestKit({
+  ValidationError: ContractError, strict: false, defaultDigestField: 'contract_digest',
+});
+
+class Parser {
+  constructor(text) { this.text = text; this.index = 0; }
+  ws() { while (/\s/u.test(this.text[this.index] ?? '')) this.index += 1; }
+  parse() { const value = this.value(); this.ws(); if (this.index !== this.text.length) throw new ContractError(`JSON 尾部非法 at ${this.index}`); return value; }
+  value() {
+    this.ws(); const char = this.text[this.index];
+    if (char === '{') return this.object(); if (char === '[') return this.array(); if (char === '"') return this.string();
+    if (char === '-' || /[0-9]/u.test(char ?? '')) return this.number();
+    for (const [token, value] of [['true', true], ['false', false], ['null', null]]) if (this.text.startsWith(token, this.index)) { this.index += token.length; return value; }
+    throw new ContractError(`JSON 值非法 at ${this.index}`);
+  }
+  object() {
+    this.index += 1; this.ws(); const value = Object.create(null); const keys = new Set();
+    if (this.text[this.index] === '}') { this.index += 1; return value; }
+    for (;;) {
+      this.ws(); if (this.text[this.index] !== '"') throw new ContractError(`JSON key 非字符串 at ${this.index}`);
+      const key = this.string(); if (keys.has(key)) throw new ContractError(`JSON duplicate key: ${key}`); keys.add(key);
+      this.ws(); if (this.text[this.index] !== ':') throw new ContractError(`JSON 缺冒号 at ${this.index}`); this.index += 1; value[key] = this.value(); this.ws();
+      if (this.text[this.index] === '}') { this.index += 1; return value; } if (this.text[this.index] !== ',') throw new ContractError(`JSON 缺逗号 at ${this.index}`); this.index += 1;
+    }
+  }
+  array() {
+    this.index += 1; this.ws(); const value = []; if (this.text[this.index] === ']') { this.index += 1; return value; }
+    for (;;) { value.push(this.value()); this.ws(); if (this.text[this.index] === ']') { this.index += 1; return value; } if (this.text[this.index] !== ',') throw new ContractError(`JSON array 缺逗号 at ${this.index}`); this.index += 1; }
+  }
+  string() { const start = this.index++; let escaped = false; while (this.index < this.text.length) { const char = this.text[this.index]; if (!escaped && char === '"') { this.index += 1; const value = JSON.parse(this.text.slice(start, this.index)); if (/\p{Surrogate}/u.test(value)) throw new ContractError('JSON string 含未配对 surrogate'); return value; } escaped = !escaped && char === '\\'; this.index += 1; } throw new ContractError('JSON string 未闭合'); }
+  number() { const match = this.text.slice(this.index).match(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/u); if (!match) throw new ContractError('JSON number 非法'); this.index += match[0].length; const value = Number(match[0]); if (!Number.isFinite(value)) throw new ContractError('JSON number 必须有限'); return value; }
+}
+
+export function parseJsonStrict(text) { return new Parser(text).parse(); }
+export function validateContract(contract, { requireDigest = true } = {}) {
+  const required = ['schema_version', 'contract_id', 'objective', 'scope', 'acceptance', 'permissions', 'environment', 'skill_set', 'stop_conditions', 'extensions'];
+  if (contract?.schema_version !== 1) throw new ContractError('Task Contract schema_version 必须为 1');
+  for (const field of required) if (!Object.hasOwn(contract, field)) throw new ContractError(`Task Contract 缺少 ${field}`);
+  if (!contract.contract_id || !contract.objective || !Array.isArray(contract.scope?.include) || !Array.isArray(contract.scope?.exclude) || [...contract.scope.include, ...contract.scope.exclude].some((item) => typeof item !== 'string' || !item)) throw new ContractError('Task Contract identity/scope 无效');
+  if (!Array.isArray(contract.acceptance) || !contract.acceptance.length) throw new ContractError('acceptance 不能为空');
+  const ids = new Set();
+  for (const item of contract.acceptance) { if (!item?.contract_item_id || !item?.requirement || ids.has(item.contract_item_id)) throw new ContractError('acceptance ID 缺失或重复'); ids.add(item.contract_item_id); }
+  if (!['read_only', 'write'].includes(contract.permissions?.mode) || !Array.isArray(contract.permissions?.writable_paths) || contract.permissions.writable_paths.some((item) => typeof item !== 'string' || !item)) throw new ContractError('permissions 无效');
+  if (contract.permissions.mode === 'read_only' && contract.permissions.writable_paths.length) throw new ContractError('read_only 合同不能声明 writable_paths');
+  if (typeof contract.environment?.repository !== 'string' || !contract.environment.repository || !['shared_tree', 'worktree', 'caller_supplied'].includes(contract.environment?.isolation)) throw new ContractError('environment 无效');
+  if (!Array.isArray(contract.stop_conditions) || !contract.extensions || typeof contract.extensions !== 'object' || Array.isArray(contract.extensions)) throw new ContractError('stop_conditions/extensions 无效');
+  const verification = contract.extensions.verification;
+  if (verification !== undefined && (
+    !verification || typeof verification !== 'object' || Array.isArray(verification)
+    || !['none', 'verify-agent-output', 'run-agent-verify-loop'].includes(verification.provider)
+  )) throw new ContractError('extensions.verification 无效');
+  const reviewPolicy = contract.extensions.review_policy;
+  if (reviewPolicy !== undefined) {
+    const expected = ['max_escalation_reviews_per_artifact', 'max_primary_reviews_per_artifact', 'max_review_input_tokens', 'require_distinct_lens', 'review_only_after_smoke_pass', 'schema_version'];
+    const keys = reviewPolicy && typeof reviewPolicy === 'object' && !Array.isArray(reviewPolicy) ? Object.keys(reviewPolicy).sort() : [];
+    if (
+      reviewPolicy?.schema_version !== 1
+      || JSON.stringify(keys) !== JSON.stringify(expected)
+      || !Number.isSafeInteger(reviewPolicy.max_primary_reviews_per_artifact) || reviewPolicy.max_primary_reviews_per_artifact < 0
+      || !Number.isSafeInteger(reviewPolicy.max_escalation_reviews_per_artifact) || reviewPolicy.max_escalation_reviews_per_artifact < 0
+      || !Number.isSafeInteger(reviewPolicy.max_review_input_tokens) || reviewPolicy.max_review_input_tokens < 1
+      || typeof reviewPolicy.require_distinct_lens !== 'boolean'
+      || typeof reviewPolicy.review_only_after_smoke_pass !== 'boolean'
+    ) throw new ContractError('extensions.review_policy 无效');
+  }
+  if (!Array.isArray(contract.skill_set)) throw new ContractError('skill_set 必须是数组');
+  const skills = new Set();
+  for (const skill of contract.skill_set) {
+    if (!skill?.name || skills.has(skill.name) || !/^sha256:[0-9a-f]{64}$/u.test(String(skill.content_digest ?? '')) || !['primary', 'optional'].includes(skill.provider_mode)) throw new ContractError('skill_set entry 无效或重复');
+    skills.add(skill.name);
+  }
+  const common = new Set(required.concat('contract_digest'));
+  for (const key of Object.keys(contract.extensions)) if (common.has(key)) throw new ContractError(`extension 覆盖公共字段: ${key}`);
+  if (requireDigest && (!/^sha256:[0-9a-f]{64}$/u.test(String(contract.contract_digest ?? '')) || envelopeDigest(contract) !== contract.contract_digest)) throw new ContractError('contract_digest 无效');
+  return contract;
+}
+
+export function normalizeContract(contract) {
+  const normalized = structuredClone(contract);
+  delete normalized.contract_digest;
+  validateContract(normalized, { requireDigest: false });
+  normalized.contract_digest = envelopeDigest(normalized);
+  return normalized;
+}
+
+export function acceptanceItemDigest(item) { return sha256(Buffer.from(canonicalJson(item), 'utf8')); }
+
+// 合同投影：从公共父合同切出节点级、产物专属的验证合同。acceptance 条目逐字节 verbatim 拷贝，
+// 其余公共字段原样继承，血缘写入 extensions.projection 供 ledger 校验。
+export function projectContract(parent, itemIds, { contractId = null } = {}) {
+  validateContract(parent);
+  if (!Array.isArray(itemIds) || !itemIds.length) throw new ContractError('projection items 不能为空');
+  if (itemIds.some((id) => typeof id !== 'string' || !id)) throw new ContractError('projection item id 无效');
+  if (new Set(itemIds).size !== itemIds.length) throw new ContractError('projection items 重复');
+  const byId = new Map(parent.acceptance.map((item) => [item.contract_item_id, item]));
+  const acceptance = itemIds.map((id) => { const item = byId.get(id); if (!item) throw new ContractError(`projection item 不在 parent acceptance 中: ${id}`); return structuredClone(item); });
+  if (contractId !== null && (typeof contractId !== 'string' || !contractId)) throw new ContractError('contract-id 无效');
+  // 以 parent 展开为基底：只有 contract_id / acceptance / extensions / contract_digest 允许改动，
+  // 其余顶层字段（含 parent 自带的扩展字段）原样继承，ledger 侧会逐字段核对全等。
+  const projected = {
+    ...structuredClone(parent),
+    contract_id: contractId ?? `${parent.contract_id}--proj-${randomBytes(4).toString('hex')}`,
+    acceptance,
+    extensions: { ...structuredClone(parent.extensions), projection: { parent_contract_digest: parent.contract_digest, projected_item_ids: [...itemIds] } },
+  };
+  projected.contract_digest = envelopeDigest(projected);
+  return validateContract(projected);
+}
+
+export function contractDiff(left, right) {
+  const changed = [];
+  for (const key of [...new Set([...Object.keys(left), ...Object.keys(right)])].sort()) if (canonicalJson(left[key]) !== canonicalJson(right[key])) changed.push(key);
+  const resign = changed.some((key) => key !== 'contract_digest');
+  return { changed_fields: changed, requires_resign: resign, old_digest: left.contract_digest ?? null, new_digest: right.contract_digest ?? null };
+}
+
+// CLI 命令与参数的唯一真源：`--help` 清单和未知命令错误信息都从这里推导。
+const CLI_SPEC = {
+  normalize: { required: ['input'] },
+  validate: { required: ['input'] },
+  digest: { required: ['input'] },
+  'review-view': { required: ['input'] },
+  diff: { required: ['left', 'right'] },
+  project: { required: ['input', 'items'], optional: ['contract-id'] },
+  capabilities: {},
+};
+const CLI_NOTES = ['--items 是逗号分隔的 acceptance contract_item_id 列表，投影合同只能收窄这些条目。'];
+function parseCli(argv) { const command = argv[0]; const options = {}; for (let i = 1; i < argv.length; i += 2) { if (!argv[i]?.startsWith('--') || argv[i + 1] === undefined) throw new ContractError('参数必须是 --name value'); options[argv[i].slice(2)] = argv[i + 1]; } return { command, options }; }
+function read(path) { return parseJsonStrict(readFileSync(resolve(path), 'utf8')); }
+export function main(argv = process.argv.slice(2)) {
+  if (isHelpRequest(argv)) return { help: renderCliHelp('contract-tool.mjs', CLI_SPEC, CLI_NOTES) };
+  const { command, options } = parseCli(argv);
+  if (command === 'normalize') return normalizeContract(read(options.input));
+  if (command === 'validate') { const value = validateContract(read(options.input)); return { valid: true, contract_id: value.contract_id, contract_digest: value.contract_digest }; }
+  if (command === 'digest') return { contract_digest: envelopeDigest(read(options.input)) };
+  if (command === 'review-view') { const value = validateContract(read(options.input)); return { schema_version: 1, contract_id: value.contract_id, objective: value.objective, scope: value.scope, acceptance: value.acceptance, contract_permissions: value.permissions, reviewer_permissions: { mode: 'read_only', writable_paths: [] }, environment: value.environment, contract_digest: value.contract_digest }; }
+  if (command === 'diff') return contractDiff(read(options.left), read(options.right));
+  if (command === 'project') return projectContract(read(options.input), String(options.items ?? '').split(',').map((item) => item.trim()).filter(Boolean), { contractId: options['contract-id'] ?? null });
+  if (command === 'capabilities') return { tool: 'contract-tool', runtime_version: '1.1.0', task_contract_versions: [1], features: ['strict-json', 'canonical-digest', 'review-view', 'resign-diff', 'contract-projection'] };
+  throw new ContractError(`命令必须是 ${Object.keys(CLI_SPEC).join('/')}`);
+}
+
+function isEntry() { try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return pathToFileURL(resolve(process.argv[1] ?? '')).href === import.meta.url; } }
+export function runCli(argv = process.argv.slice(2)) {
+  try {
+    const result = main(argv);
+    process.stdout.write(typeof result?.help === 'string' ? result.help : `${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+  } catch (error) {
+    process.stderr.write(`${JSON.stringify({ error: 'invalid_contract', message: error.message })}\n`);
+    return 2;
+  }
+}
+if (isEntry()) process.exitCode = runCli();

package/domains/orchestrate/host_capability_cache.mjs

@@ -0,0 +1,437 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parseJsonStrict } from './contract-tool.mjs';
+import { projectConfigDir, resolveUserPath, userConfigDir } from './resolve_model_policy.mjs';
+
+const SCHEMA_VERSION = 1;
+const MAX_JSON_BYTES = 256 * 1024;
+const HOST_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/u;
+const KEY_PATTERN = /^[a-z][a-z0-9_.-]{0,63}$/u;
+const OBSERVED_KEYS = new Set(['schema_version', 'host', 'host_version', 'tools', 'capabilities', 'limits', 'unknown']);
+const TOOL_KEYS = new Set(['name', 'parameters', 'returns']);
+const SNAPSHOT_KEYS = new Set(['schema_version', 'host', 'host_version', 'generated_at', 'expires_at', 'capability_fingerprint', 'source', 'observed']);
+const EVENT_KEYS = new Set(['schema_version', 'category', 'summary', 'confidence', 'evidence', 'portable']);
+const CONFIDENCE_VALUES = new Set(['observed-once', 'reproduced', 'schema-confirmed']);
+const MODEL_DISCOVERY_VALUES = new Set(['available', 'unavailable']);
+const ISO_TZ_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/u;
+
+export class CapabilityCacheError extends Error {}
+
+function checkKeys(value, allowed, label) {
+  const unknown = Object.keys(value).filter((k) => !allowed.has(k)).sort();
+  if (unknown.length) {
+    throw new CapabilityCacheError(`${label} has unknown keys: ${unknown.join(', ')}`);
+  }
+}
+
+function assertHost(value) {
+  if (typeof value !== 'string' || !HOST_PATTERN.test(value)) {
+    throw new CapabilityCacheError(`host must match ${HOST_PATTERN}`);
+  }
+  return value;
+}
+
+function stringList(value, label) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || !item)) {
+    throw new CapabilityCacheError(`${label} must be a string array`);
+  }
+  return Array.from(new Set(value)).sort();
+}
+
+function flatMap(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new CapabilityCacheError(`${label} must be a JSON object`);
+  }
+  const normalized = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (!KEY_PATTERN.test(key)) {
+      throw new CapabilityCacheError(`${label} key ${JSON.stringify(key)} is invalid`);
+    }
+    if (Array.isArray(item)) {
+      normalized[key] = stringList(item, `${label}.${key}`);
+    } else if (typeof item === 'number') {
+      if (!Number.isFinite(item)) throw new CapabilityCacheError(`${label}.${key} must be a finite number`);
+      normalized[key] = item;
+    } else if (typeof item === 'string' || typeof item === 'boolean' || item === null) {
+      normalized[key] = item;
+    } else {
+      throw new CapabilityCacheError(`${label}.${key} must be a scalar or string array`);
+    }
+  }
+  return normalized;
+}
+
+export function normalizeObserved(value, expectedHost) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new CapabilityCacheError('observed descriptor must be a JSON object');
+  }
+  checkKeys(value, OBSERVED_KEYS, 'observed descriptor');
+  if (value.schema_version !== SCHEMA_VERSION) {
+    throw new CapabilityCacheError(`observed descriptor must declare schema_version ${SCHEMA_VERSION}`);
+  }
+  if (value.host !== expectedHost) {
+    throw new CapabilityCacheError(`observed descriptor host must be ${JSON.stringify(expectedHost)}`);
+  }
+  const hostVersion = value.host_version ?? 'unknown';
+  if (typeof hostVersion !== 'string' || !hostVersion) {
+    throw new CapabilityCacheError('observed descriptor host_version must be a string');
+  }
+  const tools = value.tools;
+  if (!Array.isArray(tools)) {
+    throw new CapabilityCacheError('observed descriptor tools must be an array');
+  }
+  const normalizedTools = [];
+  const names = new Set();
+  for (let index = 0; index < tools.length; index += 1) {
+    const raw = tools[index];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+      throw new CapabilityCacheError(`tools[${index}] must be a JSON object`);
+    }
+    checkKeys(raw, TOOL_KEYS, `tools[${index}]`);
+    const name = raw.name;
+    if (typeof name !== 'string' || !name || name.length > 256 || /[\x00-\x1f]/u.test(name) || names.has(name)) {
+      throw new CapabilityCacheError(`tools[${index}].name must be a unique string`);
+    }
+    names.add(name);
+    normalizedTools.push({
+      name,
+      parameters: stringList(raw.parameters === undefined ? [] : raw.parameters, `tools[${index}].parameters`),
+      returns: stringList(raw.returns === undefined ? [] : raw.returns, `tools[${index}].returns`),
+    });
+  }
+  const capabilities = flatMap(value.capabilities === undefined ? {} : value.capabilities, 'capabilities');
+  if (capabilities['model.discovery'] !== undefined && !MODEL_DISCOVERY_VALUES.has(capabilities['model.discovery'])) {
+    throw new CapabilityCacheError('capabilities.model.discovery must be available or unavailable');
+  }
+  return {
+    schema_version: SCHEMA_VERSION,
+    host: expectedHost,
+    host_version: hostVersion,
+    tools: normalizedTools.sort((a, b) => a.name.localeCompare(b.name)),
+    capabilities,
+    limits: flatMap(value.limits === undefined ? {} : value.limits, 'limits'),
+    unknown: stringList(value.unknown === undefined ? [] : value.unknown, 'unknown'),
+  };
+}
+
+export function capabilityFingerprint(observed) {
+  const interfaceData = { tools: observed.tools };
+  const payload = Buffer.from(JSON.stringify(interfaceData), 'utf8');
+  return `sha256:${createHash('sha256').update(payload).digest('hex')}`;
+}
+
+export function cacheRoot(repo, scope, explicit = null) {
+  if (explicit) return resolveUserPath(explicit);
+  return scope === 'global' ? userConfigDir() : projectConfigDir(resolvePath(repo));
+}
+
+export function snapshotPath(root, host) {
+  return join(root, 'capabilities', `${assertHost(host)}.json`);
+}
+
+export function observationsDir(root, host) {
+  return join(root, 'observations', assertHost(host));
+}
+
+function readJsonFile(path) {
+  try {
+    const stats = statSync(path);
+    if (stats.size > MAX_JSON_BYTES) {
+      throw new CapabilityCacheError(`${path} exceeds ${MAX_JSON_BYTES} bytes`);
+    }
+    return parseJsonStrict(readFileSync(path, 'utf8'));
+  } catch (error) {
+    if (error instanceof CapabilityCacheError) throw error;
+    throw new CapabilityCacheError(`cannot read ${path}: ${error.message}`);
+  }
+}
+
+export function atomicWrite(path, value) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temp, path);
+  } finally {
+    try {
+      if (existsSync(temp)) unlinkSync(temp);
+    } catch {}
+  }
+}
+
+export function parseTime(value, label) {
+  if (typeof value !== 'string' || !ISO_TZ_PATTERN.test(value)) {
+    throw new CapabilityCacheError(`${label} must be a valid ISO-8601 string with timezone (e.g. 2026-08-01T12:00:00Z)`);
+  }
+  const timestamp = Date.parse(value);
+  if (Number.isNaN(timestamp)) {
+    throw new CapabilityCacheError(`${label} is not valid ISO-8601`);
+  }
+  return new Date(timestamp);
+}
+
+export function refreshSnapshot(root, host, observedValue, ttlHours = 168, now = null) {
+  if (!Number.isInteger(ttlHours) || ttlHours < 1 || ttlHours > 24 * 90) {
+    throw new CapabilityCacheError('ttl_hours must be an integer between 1 and 2160');
+  }
+  const current = now || new Date();
+  const observed = normalizeObserved(observedValue, assertHost(host));
+  const expires = new Date(current.getTime() + ttlHours * 3600 * 1000);
+  const snapshot = {
+    schema_version: SCHEMA_VERSION,
+    host,
+    host_version: observed.host_version,
+    generated_at: current.toISOString(),
+    expires_at: expires.toISOString(),
+    capability_fingerprint: capabilityFingerprint(observed),
+    source: 'live-tool-schema',
+    observed,
+  };
+  const path = snapshotPath(root, host);
+  try {
+    atomicWrite(path, snapshot);
+  } catch (error) {
+    return {
+      status: 'write-blocked',
+      snapshot_path: path,
+      error: error.message,
+      candidate_snapshot: snapshot,
+    };
+  }
+  return { status: 'refreshed', snapshot_path: path, snapshot };
+}
+
+export function inspectSnapshot(root, host, observedValue, now = null) {
+  const observed = normalizeObserved(observedValue, assertHost(host));
+  const path = snapshotPath(root, host);
+  const base = {
+    snapshot_path: path,
+    observations_path: observationsDir(root, host),
+    current_fingerprint: capabilityFingerprint(observed),
+  };
+  if (!existsSync(path)) {
+    return { ...base, status: 'absent', refresh_required: true, reasons: ['snapshot-missing'] };
+  }
+  const current = now || new Date();
+  try {
+    const snapshot = readJsonFile(path);
+    if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+      throw new CapabilityCacheError('snapshot must be a JSON object');
+    }
+    checkKeys(snapshot, SNAPSHOT_KEYS, 'snapshot');
+    if (snapshot.schema_version !== SCHEMA_VERSION) {
+      throw new CapabilityCacheError('snapshot schema_version is unsupported');
+    }
+    if (snapshot.host !== host) {
+      throw new CapabilityCacheError('snapshot host does not match');
+    }
+    const cachedObserved = normalizeObserved(snapshot.observed, host);
+    if (snapshot.host_version !== cachedObserved.host_version) {
+      throw new CapabilityCacheError('snapshot host_version does not match its observed descriptor');
+    }
+    if (snapshot.capability_fingerprint !== capabilityFingerprint(cachedObserved)) {
+      throw new CapabilityCacheError('snapshot fingerprint does not match its observed descriptor');
+    }
+    if (snapshot.source !== 'live-tool-schema') {
+      throw new CapabilityCacheError('snapshot source must be live-tool-schema');
+    }
+    const expiresAt = parseTime(snapshot.expires_at, 'snapshot.expires_at');
+    const generatedAt = parseTime(snapshot.generated_at, 'snapshot.generated_at');
+    if (generatedAt.getTime() > current.getTime() + 5 * 60 * 1000) {
+      throw new CapabilityCacheError('snapshot generated_at is in the future');
+    }
+    if (expiresAt.getTime() <= generatedAt.getTime() || expiresAt.getTime() - generatedAt.getTime() > 24 * 90 * 3600 * 1000) {
+      throw new CapabilityCacheError('snapshot validity window is invalid');
+    }
+    const reasons = [];
+    if (current.getTime() >= expiresAt.getTime()) {
+      reasons.push('snapshot-expired');
+    }
+    if (snapshot.host_version !== observed.host_version) {
+      reasons.push('host-version-changed');
+    }
+    if (snapshot.capability_fingerprint !== base.current_fingerprint) {
+      reasons.push('live-capability-fingerprint-changed');
+    }
+    return {
+      ...base,
+      status: reasons.length ? 'stale' : 'fresh',
+      refresh_required: reasons.length > 0,
+      reasons,
+      snapshot,
+    };
+  } catch (error) {
+    return { ...base, status: 'stale', refresh_required: true, reasons: [`snapshot-invalid: ${error.message}`] };
+  }
+}
+
+export function recordObservation(root, host, value, now = null) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new CapabilityCacheError('observation must be a JSON object');
+  }
+  checkKeys(value, EVENT_KEYS, 'observation');
+  if (value.schema_version !== SCHEMA_VERSION) {
+    throw new CapabilityCacheError(`observation must declare schema_version ${SCHEMA_VERSION}`);
+  }
+  const category = value.category;
+  if (typeof category !== 'string' || !KEY_PATTERN.test(category)) {
+    throw new CapabilityCacheError('observation.category is invalid');
+  }
+  const summary = value.summary;
+  if (typeof summary !== 'string' || !summary.trim() || summary.length > 2000) {
+    throw new CapabilityCacheError('observation.summary must be 1-2000 characters');
+  }
+  const confidence = value.confidence;
+  if (!CONFIDENCE_VALUES.has(confidence)) {
+    throw new CapabilityCacheError('observation.confidence is invalid');
+  }
+  const evidence = flatMap(value.evidence || {}, 'observation.evidence');
+  const portable = value.portable === true;
+  if (value.portable !== undefined && typeof value.portable !== 'boolean') {
+    throw new CapabilityCacheError('observation.portable must be boolean');
+  }
+  const current = now || new Date();
+  const snapshotFile = snapshotPath(root, assertHost(host));
+  let fingerprint = null;
+  if (existsSync(snapshotFile)) {
+    try {
+      const cached = readJsonFile(snapshotFile);
+      if (cached && typeof cached.capability_fingerprint === 'string' && /^sha256:[0-9a-f]{64}$/u.test(cached.capability_fingerprint)) {
+        fingerprint = cached.capability_fingerprint;
+      }
+    } catch {}
+  }
+  const record = {
+    schema_version: SCHEMA_VERSION,
+    host,
+    recorded_at: current.toISOString(),
+    capability_fingerprint: fingerprint,
+    event: {
+      category,
+      summary: summary.trim(),
+      confidence,
+      evidence,
+      portable,
+    },
+  };
+  const directory = observationsDir(root, host);
+  const filename = `${current.toISOString().replace(/[:.]/gu, '')}-${randomUUID()}.json`;
+  const path = join(directory, filename);
+  try {
+    atomicWrite(path, record);
+  } catch (error) {
+    return {
+      status: 'write-blocked',
+      observation_path: path,
+      error: error.message,
+      candidate_record: record,
+    };
+  }
+  return { status: 'recorded', observation_path: path, record };
+}
+
+export function parseCli(argv = process.argv.slice(2)) {
+  if (!argv.length) {
+    throw new CapabilityCacheError('missing command: status, refresh, or observe');
+  }
+  const command = argv[0];
+  if (!['status', 'refresh', 'observe'].includes(command)) {
+    throw new CapabilityCacheError('command must be status, refresh, or observe');
+  }
+  const options = { command, host: '', repo: '.', scope: 'global', config_dir: null, observed: null, ttl_hours: 168, event: null };
+  for (let i = 1; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--host') {
+      if (i + 1 >= argv.length || argv[i + 1].startsWith('--')) throw new CapabilityCacheError('缺少 --host 参数值');
+      options.host = argv[++i];
+    } else if (arg === '--repo') {
+      if (i + 1 >= argv.length || argv[i + 1].startsWith('--')) throw new CapabilityCacheError('缺少 --repo 参数值');
+      options.repo = argv[++i];
+    } else if (arg === '--scope') {
+      if (i + 1 >= argv.length || argv[i + 1].startsWith('--')) throw new CapabilityCacheError('缺少 --scope 参数值');
+      options.scope = argv[++i];
+    } else if (arg === '--config-dir') {
+      if (i + 1 >= argv.length || argv[i + 1].startsWith('--')) throw new CapabilityCacheError('缺少 --config-dir 参数值');
+      options.config_dir = argv[++i];
+    } else if (arg === '--observed') {
+      if (i + 1 >= argv.length || argv[i + 1].startsWith('--')) throw new CapabilityCacheError('缺少 --observed 参数值');
+      options.observed = argv[++i];
+    } else if (arg === '--ttl-hours') {
+      if (i + 1 >= argv.length || argv[i + 1].startsWith('--')) throw new CapabilityCacheError('缺少 --ttl-hours 参数值');
+      const raw = argv[++i];
+      const parsed = Number(raw);
+      if (!Number.isInteger(parsed) || !/^-?\d+$/u.test(raw)) {
+        throw new CapabilityCacheError(`--ttl-hours must be an integer, got ${JSON.stringify(raw)}`);
+      }
+      options.ttl_hours = parsed;
+    } else if (arg === '--event') {
+      if (i + 1 >= argv.length || argv[i + 1].startsWith('--')) throw new CapabilityCacheError('缺少 --event 参数值');
+      options.event = argv[++i];
+    } else {
+      throw new CapabilityCacheError(`unknown option: ${arg}`);
+    }
+  }
+  if (!options.host) throw new CapabilityCacheError('缺少 --host');
+  assertHost(options.host);
+
+  if (!['global', 'project'].includes(options.scope)) {
+    throw new CapabilityCacheError(`scope must be "global" or "project", got ${JSON.stringify(options.scope)}`);
+  }
+  if (options.command === 'status' && !options.observed) {
+    throw new CapabilityCacheError('status command requires --observed <path>');
+  }
+  if (options.command === 'refresh') {
+    if (!options.observed) {
+      throw new CapabilityCacheError('refresh command requires --observed <path>');
+    }
+    if (options.ttl_hours < 1 || options.ttl_hours > 2160) {
+      throw new CapabilityCacheError(`--ttl-hours must be between 1 and 2160, got ${options.ttl_hours}`);
+    }
+  }
+  if (options.command === 'observe' && !options.event) {
+    throw new CapabilityCacheError('observe command requires --event <path>');
+  }
+  return options;
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const options = parseCli(argv);
+  const root = cacheRoot(options.repo, options.scope, options.config_dir);
+  let result;
+  if (options.command === 'status') {
+    result = inspectSnapshot(root, options.host, readJsonFile(resolveUserPath(options.observed)));
+  } else if (options.command === 'refresh') {
+    result = refreshSnapshot(root, options.host, readJsonFile(resolveUserPath(options.observed)), options.ttl_hours);
+  } else {
+    result = recordObservation(root, options.host, readJsonFile(resolveUserPath(options.event)));
+  }
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return 0;
+}
+
+function entry() {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return pathToFileURL(resolvePath(process.argv[1] ?? '')).href === import.meta.url;
+  }
+}
+
+export function runCli(argv = process.argv.slice(2)) {
+  try {
+    return main(argv);
+  } catch (error) {
+    if (error instanceof CapabilityCacheError) {
+      process.stderr.write(`host capability cache error: ${error.message}\n`);
+      return 2;
+    }
+    throw error;
+  }
+}
+
+if (entry()) process.exitCode = runCli();