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

package/src/native/local-background-supervisor.mjs

@@ -0,0 +1,108 @@
+// Separate trusted Node process: the tool/Host caller may disappear while this
+// supervisor continues. Its own death closes the bounded runner's owner pipe.
+import { constants, closeSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { commandRequest } from './local-background.mjs';
+import { runBoundedProcess } from './local-process.mjs';
+import { commandFailureEvidence, commandExceptionCause } from './local-command-evidence.mjs';
+import { shellCommandArgv } from './command-shell.mjs';
+import { START_GRACE_MS, TERMINAL, atomicPrivate, check, digest, fsyncPrivate, lockUntil, openPrivate,
+  privateDirectory, privateFile, readRecord, unknownRecord, validId, writeRecord } from './local-command-state.mjs';
+
+async function inputRequest() {
+  let size = 0; const parts = [];
+  const timer = setTimeout(() => process.stdin.destroy(Error('request_timeout')), START_GRACE_MS);
+  try {
+    for await (const part of process.stdin) {
+      size += part.length; check(size <= 1024 * 1024, 'background_command_request_too_large'); parts.push(part);
+    }
+    return commandRequest(JSON.parse(Buffer.concat(parts).toString('utf8')));
+  } finally { clearTimeout(timer); }
+}
+async function supervise() {
+  const [directory, owner, commandId] = process.argv.slice(2);
+  check(typeof directory === 'string' && validId(owner) && validId(commandId), 'invalid_background_supervisor_arguments');
+  privateDirectory(directory);
+  const unlock = await lockUntil(join(directory, 'supervisor.sqlite'), performance.now() + START_GRACE_MS);
+  let record, stage = 'request', commandEvidence;
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  process.on('SIGTERM', cancel); process.on('SIGINT', cancel);
+  let poll;
+  try {
+    record = readRecord(directory, owner, commandId);
+    // A duplicate/stale supervisor can never reclaim a prepared operation.
+    if (record.status !== 'starting') return;
+    const request = await inputRequest();
+    check(record.requestDigest === digest(request), 'background_command_request_digest_mismatch');
+    record = readRecord(directory, owner, commandId);
+    if (record.status !== 'starting') return;
+    if (Date.now() - record.createdAt >= START_GRACE_MS) {
+      unknownRecord(directory, record, 'supervisor_start_expired'); return;
+    }
+    const persistedStream = !!request.outputPolicy;
+    const persist = (status, exitCode, stdout, stderr, metadata = {}) => {
+      // Complete bytes are fsynced and published BEFORE the terminal receipt.
+      if (persistedStream) {
+        // persisted-stream/v1: runBoundedProcess streamed the FULL capped output
+        // to the owned files via onOutput. fsync those files in place before the
+        // terminal receipt; NEVER overwrite them with the bounded preview held in
+        // stdout/stderr (a preview cannot reconstruct the full output).
+        for (const channel of ['stdout', 'stderr']) fsyncPrivate(join(directory, channel));
+      } else {
+        // Legacy: replace the incrementally-appended file with the complete
+        // in-memory captured bytes (capped at maxOutputBytes), exact old contract.
+        for (const [channel, text] of [['stdout', stdout], ['stderr', stderr]]) atomicPrivate(join(directory, channel), text);
+      }
+      const next = { ...record, ...metadata, status, exitCode, completedAt: Date.now() };
+      writeRecord(directory, next); record = next;
+    };
+    if (privateFile(join(directory, 'cancel'), true) || controller.signal.aborted) {
+      persist('canceled', null, '', ''); return;
+    }
+    record = { ...record, status: 'running', supervisorPid: process.pid }; writeRecord(directory, record);
+    stage = 'execute';
+    let outputError = false, stateError = false;
+    poll = setInterval(() => {
+      try { if (privateFile(join(directory, 'cancel'), true)) cancel(); }
+      catch { stateError = true; cancel(); }
+    }, 20);
+    const result = await runBoundedProcess({ argv: shellCommandArgv(request.command, request.shellPolicy ?? null), cwd: request.cwd,
+      env: request.env, timeoutMs: request.timeoutMs, settings: request.settings, outputPolicy: request.outputPolicy,
+      signal: controller.signal,
+      onOutput(channel, text) {
+        let fd;
+        try {
+          fd = openPrivate(join(directory, channel), constants.O_WRONLY | constants.O_APPEND); writeFileSync(fd, text);
+        } catch { outputError = true; cancel(); }
+        finally { if (fd !== undefined) closeSync(fd); }
+      } });
+    clearInterval(poll); poll = null;
+    let status = result.exitCode === 0 ? 'completed' : 'failed', exitCode = result.exitCode, diagnostic = '';
+    if (result.canceled) status = 'canceled';
+    else if (result.timedOut) { status = 'timed_out'; exitCode = 124; diagnostic = 'command timed out'; }
+    else if (result.outputLimitExceeded) { status = 'output_limit'; exitCode = 122; diagnostic = 'command output limit exceeded'; }
+    commandEvidence = commandFailureEvidence(stage, { result, failures: [
+      ...(outputError ? ['output_recording_failed'] : []), ...(stateError ? ['state_observation_failed'] : [])] });
+    if (result.controls.status === 'failed' || result.cleanupError || outputError || stateError) {
+      status = 'unknown'; exitCode = null; diagnostic = 'command supervision or cleanup failed';
+    }
+    // Under persisted-stream, result.stdout/stderr are bounded PREVIEWS; the full
+    // output lives in the streamed files. Append diagnostics to the stderr PREVIEW
+    // for the receipt only; the streamed stderr file is unchanged by this append.
+    const stderr = result.stderr + (diagnostic ? (result.stderr && !result.stderr.endsWith('\n') ? '\n' : '') + diagnostic : '');
+    stage = 'publish';
+    persist(status, exitCode, result.stdout, stderr, { controls: result.controls, outputLimitExceeded: result.outputLimitExceeded,
+      ...(status === 'unknown' ? { commandEvidence } : {}),
+      evidenceIncomplete: status === 'unknown', observedExitCode: status === 'unknown' ? result.exitCode : null,
+      outcomeReason: status === 'unknown' ? 'process_supervision_failed' : '' });
+  } catch (error) {
+    // Secrets/input exception strings never enter records or diagnostics.
+    if (record && !TERMINAL.has(record.status)) unknownRecord(directory, { ...record,
+      commandEvidence: commandFailureEvidence(stage, { previous: commandEvidence,
+        failures: [commandExceptionCause(error, 'supervisor_exception')] }) }, 'supervisor_failed');
+  } finally {
+    clearInterval(poll); process.off('SIGTERM', cancel); process.off('SIGINT', cancel); unlock();
+  }
+}
+supervise().catch(() => { process.exitCode = 1; });

package/src/native/local-background.mjs

@@ -0,0 +1,207 @@
+// Lifecycle substrate for Host-authorized commands, independent of disposable
+// tool workers. Command/workspace policy and tool approvals are caller duties.
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { constants, closeSync, existsSync, fsyncSync, realpathSync, renameSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { localControlSettings, resolveLocalProcessLauncher } from './local-process.mjs';
+import { localEnvironmentPolicy, localOutputPolicy } from './local-output-policy.mjs';
+import { shellCommandArgv } from './command-shell.mjs';
+import { LOCAL_BACKGROUND_CONTRACT, START_GRACE_MS, TERMINAL, LocalCommandError,
+  check, createPrivate, delay, digest, fsyncPrivate, lockUntil, openPrivate, privateDirectory, privateFile,
+  readAll, readRecord, readWindow, syncDirectory, tryLock, unknownRecord, validId, writeRecord } from './local-command-state.mjs';
+
+export { LOCAL_BACKGROUND_CONTRACT, LocalCommandError };
+const supervisor = fileURLToPath(new URL('./local-background-supervisor.mjs', import.meta.url));
+const inside = (path, root) => path === root || path.startsWith(root + sep);
+const workerEnvironment = Object.freeze({ PATH: '/bin:/usr/bin', LANG: 'C.UTF-8', NODE_NO_WARNINGS: '1' });
+const deadline = () => performance.now() + START_GRACE_MS;
+
+// commandRequest validates raw policy inputs at this public entrypoint. The
+// policies travel as separate optional fields, NOT inside settings, so the
+// normalized settings object (and thus the request digest) is byte-identical
+// to legacy when no policy is supplied. Omit absent policies: canonical
+// serialization rejects undefined, and the digest must stay deterministic.
+export function commandRequest({ command, cwd, env, timeoutMs, settings = {}, outputPolicy = null, environmentPolicy = null, shellPolicy = null } = {}) {
+  settings = localControlSettings(settings);
+  const outPolicy = localOutputPolicy(outputPolicy);
+  const envPolicy = localEnvironmentPolicy(environmentPolicy);
+  check(typeof command === 'string' && command.length > 0 && !command.includes('\0')
+    && typeof cwd === 'string' && cwd.length > 0 && !cwd.includes('\0'), 'invalid_background_command');
+  check(env && typeof env === 'object' && !Array.isArray(env) && Object.entries(env).every(([name, value]) =>
+    /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && typeof value === 'string' && !value.includes('\0')), 'invalid_background_command_environment');
+  timeoutMs ??= settings.wallSeconds * 1000;
+  check(Number.isSafeInteger(timeoutMs) && timeoutMs > 0, 'invalid_background_command_timeout');
+  const request = { command, cwd: resolve(cwd), env: Object.fromEntries(Object.entries(env)), timeoutMs, settings };
+  if (outPolicy) request.outputPolicy = outPolicy;
+  if (envPolicy) request.environmentPolicy = envPolicy;
+  shellCommandArgv(command, shellPolicy);
+  if (shellPolicy) request.shellPolicy = shellPolicy;
+  check(Buffer.byteLength(JSON.stringify(request)) <= 1024 * 1024, 'background_command_request_too_large');
+  return request;
+}
+
+export class LocalBackgroundCommand {
+  constructor(directory, owner, commandId) {
+    this.directory = directory; this.owner = owner; this.commandId = commandId;
+    readRecord(directory, owner, commandId); Object.freeze(this);
+  }
+  get processId() {
+    const record = readRecord(this.directory, this.owner, this.commandId);
+    check(Number.isSafeInteger(record.supervisorPid) && record.supervisorPid > 0, 'background_supervisor_identity_unavailable');
+    return record.supervisorPid; // Diagnostic locator only. Never used to cancel.
+  }
+  readOutput({ stdoutCursor = 0, stderrCursor = 0, maxBytes = 65536 } = {}) {
+    check(Number.isSafeInteger(maxBytes) && maxBytes >= 4 && maxBytes <= 65536, 'invalid_background_output_window');
+    privateDirectory(this.directory);
+    const release = tryLock(join(this.directory, 'supervisor.sqlite'));
+    let record;
+    try {
+      // Read the record while the ownership probe is held, so a final commit
+      // cannot be mistaken for a lost supervisor using an older snapshot.
+      record = readRecord(this.directory, this.owner, this.commandId);
+      if (release && !TERMINAL.has(record.status)
+        && (record.status !== 'starting' || Date.now() - record.createdAt >= START_GRACE_MS))
+        record = { ...record, status: 'unknown', exitCode: null, evidenceIncomplete: true, outcomeReason: 'supervisor_lost' };
+    } finally { release?.(); }
+    const stdout = readWindow(join(this.directory, 'stdout'), stdoutCursor, maxBytes);
+    const stderr = readWindow(join(this.directory, 'stderr'), stderrCursor, maxBytes);
+    return { status: record.status, stdout: stdout.text, stderr: stderr.text,
+      stdoutCursor: stdout.cursor, stderrCursor: stderr.cursor, exitCode: TERMINAL.has(record.status) ? record.exitCode : null,
+      cancelRequested: privateFile(join(this.directory, 'cancel'), true) !== null,
+      outputMayBeTruncated: record.outputLimitExceeded === true || stdout.hasMore || stderr.hasMore,
+      evidenceIncomplete: record.evidenceIncomplete === true, observedExitCode: record.observedExitCode ?? null,
+      outcomeReason: record.outcomeReason ?? '',
+      ...(record.commandEvidence ? { commandEvidence: record.commandEvidence } : {}) };
+  }
+  requestCancel() {
+    if (!TERMINAL.has(this.readOutput().status)) {
+      const fd = openPrivate(join(this.directory, 'cancel'), constants.O_WRONLY | constants.O_CREAT);
+      try { fsyncSync(fd); } finally { closeSync(fd); }
+      syncDirectory(this.directory);
+    }
+    return this.readOutput();
+  }
+  async wait({ timeoutMs = null, signal } = {}) {
+    check(timeoutMs === null || Number.isFinite(timeoutMs) && timeoutMs >= 0, 'invalid_background_wait_timeout');
+    const until = timeoutMs === null ? Infinity : performance.now() + timeoutMs;
+    for (;;) {
+      signal?.throwIfAborted(); const output = this.readOutput();
+      if (TERMINAL.has(output.status)) {
+        check(output.status !== 'unknown', 'background_command_outcome_unknown');
+        const stdout = readAll(join(this.directory, 'stdout')), stderr = readAll(join(this.directory, 'stderr'));
+        const record = readRecord(this.directory, this.owner, this.commandId);
+        return { ...output, stdout, stderr, stdoutCursor: Buffer.byteLength(stdout), stderrCursor: Buffer.byteLength(stderr),
+          outputMayBeTruncated: record.outputLimitExceeded === true };
+      }
+      check(performance.now() < until, 'background_command_still_running'); await delay(20);
+    }
+  }
+  async kill() {
+    this.requestCancel();
+    try { return (await this.wait({ timeoutMs: 3000 })).status === 'canceled'; }
+    catch (error) { if (error instanceof LocalCommandError) return false; throw error; }
+  }
+}
+
+export class LocalCommandStore {
+  constructor({ stateRoot, workspaceRoot, sessionId }) {
+    check(process.platform === 'darwin' || process.platform === 'linux', 'unsupported_local_background_platform');
+    check(typeof stateRoot === 'string' && !!stateRoot && typeof workspaceRoot === 'string' && !!workspaceRoot
+      && typeof sessionId === 'string' && !!sessionId.trim(), 'invalid_background_command_scope');
+    const root = resolve(stateRoot === '~' ? homedir() : stateRoot.startsWith('~/') ? join(homedir(), stateRoot.slice(2)) : stateRoot);
+    const workspace = realpathSync(workspaceRoot);
+    check(!inside(root, workspace), 'background_state_inside_workspace');
+    privateDirectory(root, true); privateDirectory(join(root, 'commands'), true);
+    this.owner = digest([workspace, 'local_process', sessionId]); this.directory = join(root, 'commands', this.owner); this.sessionId = sessionId;
+    privateDirectory(this.directory, true); Object.freeze(this);
+  }
+  commandId(operationKey) {
+    check(typeof operationKey === 'string' && !!operationKey.trim(), 'invalid_background_operation_key');
+    // The format is private/versioned; no historical Python data is imported.
+    return digest([this.owner, operationKey]);
+  }
+  connect(commandId) {
+    check(validId(commandId), 'invalid_background_command_identity');
+    return new LocalBackgroundCommand(join(this.directory, commandId), this.owner, commandId);
+  }
+  async start({ operationKey = randomUUID(), assertCurrent = () => true, ...input }) {
+    check(typeof assertCurrent === 'function', 'background_command_guard_invalid');
+    const guard = () => {
+      const allowed = assertCurrent();
+      if (allowed && typeof allowed.then === 'function') Promise.resolve(allowed).catch(() => {});
+      check(allowed === true, 'background_command_authority_lost');
+    };
+    const request = commandRequest(input), commandId = this.commandId(operationKey), requestDigest = digest(request);
+    const release = await lockUntil(join(this.directory, 'launch.sqlite'), deadline());
+    let handle;
+    try {
+      guard();
+      const directory = join(this.directory, commandId);
+      if (existsSync(directory)) {
+        handle = this.connect(commandId);
+        check(readRecord(directory, this.owner, commandId).requestDigest === requestDigest, 'background_operation_arguments_changed');
+        return handle; // An existing/unknown operation is never launched again.
+      }
+      resolveLocalProcessLauncher(); // New effects require a verified launcher.
+      const record = { schemaVersion: LOCAL_BACKGROUND_CONTRACT, owner: this.owner, commandId, requestDigest,
+        status: 'starting', createdAt: Date.now(), timeoutMs: request.timeoutMs, exitCode: null };
+      // A killed preparer may leave a private temporary directory, but cannot
+      // expose a half-created command handle. Only the complete, durable
+      // directory is published; there is no spawn before this publication.
+      const preparing = join(this.directory, `.preparing-${randomUUID()}`);
+      try {
+        privateDirectory(preparing, true);
+        for (const file of ['stdout', 'stderr', 'supervisor.sqlite']) createPrivate(join(preparing, file));
+        writeRecord(preparing, record);
+        renameSync(preparing, directory); syncDirectory(dirname(directory));
+      } finally { if (existsSync(preparing)) rmSync(preparing, { recursive: true, force: true }); }
+      // Intent is durable BEFORE the first spawn.
+      handle = this.connect(commandId);
+      guard();
+      let child;
+      try {
+        child = spawn(process.execPath, [supervisor, directory, this.owner, commandId], {
+          detached: true, cwd: directory, env: workerEnvironment, stdio: ['pipe', 'ignore', 'ignore'],
+        });
+      } catch {
+        unknownRecord(directory, record, 'supervisor_launch_failed'); return handle;
+      }
+      child.once('error', () => {
+        // A spawn error proves no child was created; a pipe failure does not.
+        let unlock;
+        try {
+          unlock = tryLock(join(directory, 'supervisor.sqlite'));
+          const current = readRecord(directory, this.owner, commandId);
+          if (unlock && current.status === 'starting') unknownRecord(directory, current, 'supervisor_launch_failed');
+        } catch { /* existing durable intent remains recoverably unknown */ }
+        finally { unlock?.(); }
+      });
+      child.stdin.on('error', () => { /* return the stable locator; never retry */ });
+      // Secrets travel only through the private stdin pipe, never argv/record.
+      child.stdin.end(JSON.stringify(request)); child.unref();
+    } finally { release(); }
+    const until = performance.now() + START_GRACE_MS;
+    while (readRecord(handle.directory, this.owner, commandId).status === 'starting' && performance.now() < until) await delay(20);
+    return handle;
+  }
+}
+
+/** Reader for createBackgroundCommandPort's canonical, owned launch receipts.
+ * This performs no launch/cancel/record transition and never selects a backend
+ * from the environment. A missing supervisor is a derived unknown outcome.
+ */
+export function createLocalBackgroundReader(store) {
+  check(store instanceof LocalCommandStore, 'invalid_local_background_store');
+  return Object.freeze(async request => {
+    request.signal.throwIfAborted();
+    check(request.sessionId === store.sessionId && request.ref
+      && request.ref.taskId === store.commandId(request.ref.operationKey), 'background_reader_owner_mismatch');
+    check(request.waitSeconds === 0, 'background_observation_must_not_wait');
+    const result = store.connect(request.ref.taskId).readOutput({ stdoutCursor: request.stdoutCursor,
+      stderrCursor: request.stderrCursor, maxBytes: request.maxBytes });
+    request.signal.throwIfAborted(); return result;
+  });
+}

package/src/native/local-command-evidence.mjs

@@ -0,0 +1,57 @@
+// Bounded diagnostic facts only. Exception text, tool input and paths never
+// enter these records, and an observed exit code is not a verified outcome.
+export const COMMAND_EVIDENCE_CONTRACT = 'agentkit.local-command-evidence/v1';
+const stages = new Set(['request', 'execute', 'publish', 'transport']);
+const causes = new Set(['control_report_failed', 'process_cleanup_failed', 'output_recording_failed',
+  'state_observation_failed', 'private_state_invalid', 'authority_lost', 'request_changed',
+  'canceled', 'filesystem_failed', 'supervisor_exception', 'transport_exception']);
+const cleanup = new Set(['spawn_observer_failed', 'stdout_read_error', 'stderr_read_error',
+  'control_report_read_error', 'control_report_oversize', 'owner_lease_error',
+  'process_reap_timeout', 'process_stdio_close_timeout', 'group_signal_failed', 'cleanup_issue_unclassified']);
+const privateCodes = new Set(['background_state_not_private', 'background_state_symlink',
+  'background_state_changed', 'invalid_background_record']);
+const filesystemCodes = new Set(['ENOENT', 'EACCES', 'EPERM', 'EIO', 'ENOSPC', 'EMFILE', 'ENFILE', 'EROFS']);
+
+/** Classify only explicitly recognized exception codes, never their text. */
+export function commandExceptionCause(error, fallback) {
+  let code;
+  try { code = error?.code; } catch { return fallback; }
+  if (privateCodes.has(code)) return 'private_state_invalid';
+  if (filesystemCodes.has(code)) return 'filesystem_failed';
+  if (['local_command_authority_stale', 'background_command_authority_lost'].includes(code)) return 'authority_lost';
+  if (code === 'local_command_request_drifted') return 'request_changed';
+  if (code === 'local_command_signal_stale') return 'canceled';
+  return fallback;
+}
+
+/** Combine observed failure facts without assigning a task execution verdict. */
+export function commandFailureEvidence(stage, { result, failures = [], previous } = {}) {
+  if (!stages.has(stage)) throw Error('invalid_command_evidence_stage');
+  const reasons = new Set(previous?.causes ?? []), issues = new Set(previous?.cleanupIssues ?? []);
+  for (const value of failures) reasons.add(value);
+  if (result?.controls?.status === 'failed') reasons.add('control_report_failed');
+  if (result?.cleanupError) {
+    reasons.add('process_cleanup_failed');
+    for (const value of result.cleanupError.split(','))
+      issues.add(cleanup.has(value) ? value : /^group_SIG(?:TERM|KILL):/.test(value)
+        ? 'group_signal_failed' : 'cleanup_issue_unclassified');
+  }
+  const observedExitCode = result?.exitCode ?? previous?.observedExitCode ?? null;
+  const evidence = { contract: COMMAND_EVIDENCE_CONTRACT, stage,
+    causes: [...reasons].sort(), cleanupIssues: [...issues].sort(), observedExitCode };
+  if (!validCommandEvidence(evidence)) throw Error('invalid_command_evidence');
+  return evidence;
+}
+
+/** Durable optional field: old records retain their absence of diagnostics. */
+export function validCommandEvidence(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).length === 5
+    && Object.keys(value).every(key => ['contract', 'stage', 'causes', 'cleanupIssues', 'observedExitCode'].includes(key))
+    && value.contract === COMMAND_EVIDENCE_CONTRACT && stages.has(value.stage)
+    && Array.isArray(value.causes) && value.causes.length <= causes.size
+    && value.causes.every(item => causes.has(item)) && new Set(value.causes).size === value.causes.length
+    && Array.isArray(value.cleanupIssues) && value.cleanupIssues.length <= cleanup.size
+    && value.cleanupIssues.every(item => cleanup.has(item)) && new Set(value.cleanupIssues).size === value.cleanupIssues.length
+    && (value.observedExitCode === null || Number.isSafeInteger(value.observedExitCode));
+}

package/src/native/local-command-policy-worker.mjs

@@ -0,0 +1,197 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { lstatSync, readFileSync, readlinkSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, join, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+import { Workspace, PositionEncoding } from '@astral-sh/ruff-wasm-nodejs';
+import { NATIVE_PYTHON_SYNTAX } from './python-syntax.mjs';
+import { LOCAL_COMMAND_POLICY } from './local-command-policy.mjs';
+import { analyzeShellSource } from './shell-analysis.mjs';
+import { decodeRuffAst, ruffIdentifier, ruffNodes, ruffString, unwrapRuff } from './ruff-ast.mjs';
+
+if (Workspace.version() !== NATIVE_PYTHON_SYNTAX.parserVersion) throw Error('command_policy_parser_version_mismatch');
+const parser = new Workspace({ 'target-version': NATIVE_PYTHON_SYNTAX.targetVersion, lint: { select: [] } }, PositionEncoding.Utf32);
+const blocked = new Set(['kill', 'killall', 'nohup', 'pkill', 'setsid']);
+const suffixes = new Set(['.py', '.sh', '.bash']);
+const subprocesses = new Set(['subprocess.call', 'subprocess.check_call', 'subprocess.check_output', 'subprocess.Popen', 'subprocess.run']);
+const python = command => command === 'python' || command.startsWith('python3');
+const shell = command => ['bash', 'dash', 'sh'].includes(command);
+const finding = (rule, detail, path = '', line = null) => ({ rule, detail, path, line });
+function limited(depth) { if (depth > 64) throw Error('command_policy_nesting_limit'); }
+function expanded(path) {
+  if (path.startsWith('~') && path !== '~' && !path.startsWith('~/')) throw Error('command_policy_named_home_unsupported');
+  return path === '~' ? homedir() : path.startsWith('~/') ? join(homedir(), path.slice(2)) : path;
+}
+function weakRealpath(path, depth = 0) {
+  limited(depth); path = resolve(path);
+  try { return realpathSync(path); }
+  catch (error) {
+    if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error;
+    try { if (lstatSync(path).isSymbolicLink()) return weakRealpath(resolve(dirname(path), readlinkSync(path)), depth + 1); }
+    catch (nested) { if (nested.code !== 'ENOENT' && nested.code !== 'ENOTDIR') throw nested; }
+    if (dirname(path) === path) throw error;
+    return join(weakRealpath(dirname(path), depth + 1), basename(path));
+  }
+}
+const roots = workerData.allowedRoots.map(path => weakRealpath(expanded(path)));
+const cwd = weakRealpath(workerData.cwd);
+function inside(path) {
+  try { const target = weakRealpath(path); return roots.some(root => target === root || root === sep || target.startsWith(root + sep)); }
+  catch { return false; }
+}
+
+// Gateway restrictions and local risks consume the same parsed invocations.
+// This deliberately retains the existing policy choices, without treating
+// comments or heredoc data as command arguments.
+function gatewayPolicy(args) {
+  for (let i = 0; i + 1 < args.length; i++) if (args[i] === 'rm'
+    && args.slice(i + 1, i + 3).some(flag => flag.startsWith('-') && /[rR]/.test(flag)))
+    return finding('command_rejected', 'recursive rm is not allowed without explicit approval');
+  if (args.some(arg => ['sudo', 'kubectl', 'docker'].includes(arg)))
+    return finding('command_rejected', `${args[0]} command is not allowed by default policy`);
+  if (args[0] === 'git' && args.length > 1) {
+    if (['status', 'diff', 'log', 'show', 'branch', 'ls-files'].includes(args[1])) return null;
+    if (['reset', 'clean', 'push', 'checkout'].includes(args[1]))
+      return finding('command_rejected', `git ${args[1]} is not allowed without explicit approval`);
+  }
+  if (args.join(' ').includes('169.254.169.254') || args.join(' ').includes('metadata.google.internal'))
+    return finding('command_rejected', 'metadata/private endpoint access is not allowed by default policy');
+  return null;
+}
+function executableIndex(args) {
+  return args.findIndex(arg => !/^[A-Za-z_][A-Za-z0-9_]*=.*$/.test(arg));
+}
+function recursiveForce(args) {
+  let options = '';
+  for (const arg of args) {
+    if ([';', '&&', '||', '|', '--'].includes(arg)) break;
+    if (arg.startsWith('-')) options += arg.replace(/^-+/, '');
+  }
+  return options.toLowerCase().includes('r') && options.toLowerCase().includes('f');
+}
+function checkTokens(args, path, line, depth, stdin = null) {
+  limited(depth);
+  const index = executableIndex(args); if (index < 0) return null;
+  const command = basename(args[index]).toLowerCase(), rest = args.slice(index + 1);
+  if (blocked.has(command)) return finding(`shell.blocked_command.${command}`, `command '${command}' is not allowed by the local-process policy`, path, line);
+  if (command === 'rm' && recursiveForce(rest)) return finding('shell.recursive_force_remove', 'recursive forced removal is not allowed', path, line);
+  if (stdin !== null && !rest.includes('-c') && !rest.includes('-m')
+    && (!rest.length || rest[0] === '-' || shell(command) && rest.includes('-s'))) {
+    const result = python(command) ? checkPython(stdin, path || '<stdin>', depth + 1)
+      : shell(command) ? checkShell(stdin, path || '<stdin>', depth + 1, false, false, command === 'bash' ? 'bash' : 'posix') : null;
+    if (result) return result;
+  }
+  const option = rest.indexOf('-c');
+  if (option < 0 || option + 1 >= rest.length) return null;
+  return python(command) ? checkPython(rest[option + 1], path || '<command>', depth + 1)
+    : shell(command) ? checkShell(rest[option + 1], path, depth + 1, false, false, command === 'bash' ? 'bash' : 'posix') : null;
+}
+function checkShell(text, path, depth, governed = false, scanEntries = false, dialect = 'bash') {
+  limited(depth);
+  const analysis = analyzeShellSource(text);
+  if (analysis.hasParseErrors) return finding('invalid_command', 'invalid shell syntax', path);
+  if (dialect === 'posix' && analysis.hasBashCombinedRedirects)
+    return finding('invalid_command', 'Bash combined redirection requires an explicit Bash interpreter', path);
+  if (analysis.backgrounds.length) return finding('shell.background_process', 'background process syntax is not allowed', path, analysis.backgrounds[0]);
+  for (const { argv, line, stdin } of analysis.commands) {
+    const result = (governed ? gatewayPolicy(argv) : null) ?? checkTokens(argv, path, line, depth + 1, stdin)
+      ?? (scanEntries ? scanScripts(argv) : null);
+    if (result) return result;
+  }
+  return null;
+}
+function callName(value, aliases) {
+  const node = unwrapRuff(value);
+  if (node?.tag === 'ExprName') { const name = ruffIdentifier(node.fields.id); return aliases.get(name) ?? name; }
+  if (node?.tag === 'ExprAttribute') {
+    const parent = callName(node.fields.value, aliases), attr = ruffIdentifier(node.fields.attr);
+    return parent ? `${parent}.${attr}` : attr;
+  }
+  return '';
+}
+function commandLiteral(value) {
+  const text = ruffString(value); if (text !== null) return text;
+  const node = unwrapRuff(value);
+  if (!['ExprList', 'ExprTuple'].includes(node?.tag)) return null;
+  const parts = node.fields.elts.map(ruffString);
+  return parts.every(part => part !== null) ? parts : null;
+}
+function keywordTrue(args, name) {
+  return args.keywords.some(item => ruffIdentifier(item.fields.arg) === name
+    && unwrapRuff(item.fields.value)?.tag === 'ExprBooleanLiteral' && unwrapRuff(item.fields.value).fields.value === true);
+}
+function checkPython(source, path, depth) {
+  limited(depth); if (Buffer.byteLength(source) > 2 * 1024 * 1024) throw Error('command_policy_source_limit');
+  let wire;
+  try {
+    parser.comments(source); // Grammar only, matching ast.parse rather than compile.
+    if (parser.check(source).some(item => / on Python 3\.12 \(syntax was added in Python 3\.\d+\)$/.test(item.message))) return null;
+    wire = parser.parse(source);
+  } catch (error) {
+    if (/ at byte range \d+\.\.\d+$/.test(error.message)) return null;
+    throw error;
+  }
+  const nodes = ruffNodes(decodeRuffAst(wire)), aliases = new Map(), bytes = Buffer.from(source);
+  for (const node of nodes) {
+    if (node.tag === 'StmtImport' || node.tag === 'StmtImportFrom') {
+      const module = node.tag === 'StmtImportFrom' ? ruffIdentifier(node.fields.module) : '';
+      if (node.tag === 'StmtImportFrom' && !module) continue;
+      for (const alias of node.fields.names) {
+        const name = ruffIdentifier(alias.fields.name), asname = ruffIdentifier(alias.fields.asname);
+        aliases.set(asname ?? name, module ? `${module}.${name}` : name);
+      }
+    }
+  }
+  for (const node of nodes) {
+    if (node.tag !== 'ExprCall') continue;
+    const name = callName(node.fields.func, aliases), args = node.fields.arguments.fields;
+    const line = bytes.subarray(0, node.fields.range.range[0]).toString('utf8').split(/\r\n|\r|\n/).length;
+    if (['os.kill', 'os.killpg', 'os.setsid'].includes(name)) return finding('python.process_control', `call to ${name} is not allowed`, path, line);
+    if (['os.popen', 'os.system'].includes(name) && args.args.length) {
+      const text = ruffString(args.args[0]);
+      if (text !== null) { const result = checkShell(text, path, depth + 1); if (result) return result; }
+    }
+    if (subprocesses.has(name)) {
+      if (name === 'subprocess.Popen' && keywordTrue(args, 'start_new_session'))
+        return finding('python.detached_process', 'subprocess start_new_session=True is not allowed', path, line);
+      const command = args.args.length ? commandLiteral(args.args[0]) : null;
+      const result = Array.isArray(command) ? checkTokens(command, path, line, depth + 1)
+        : typeof command === 'string' && keywordTrue(args, 'shell') ? checkShell(command, path, depth + 1) : null;
+      if (result) return result;
+    }
+    if (name === 'shutil.rmtree' && args.args.length) {
+      const value = ruffString(args.args[0]);
+      if (value !== null && !inside(resolve(cwd, expanded(value))))
+        return finding('path.destructive_outside_workspace', `shutil.rmtree target ${JSON.stringify(value)} is outside the allowed roots`, path, line);
+    }
+  }
+  return null;
+}
+function directScript(command, rest) {
+  if (suffixes.has(extname(command).toLowerCase())) return command;
+  if (!(python(basename(command).toLowerCase()) || shell(basename(command).toLowerCase())) || rest.includes('-c') || rest.includes('-m')) return null;
+  for (const arg of rest) {
+    if (arg === '--' || arg.startsWith('-')) continue;
+    return suffixes.has(extname(arg).toLowerCase()) ? arg : null;
+  }
+  return null;
+}
+function scanScripts(args) {
+  const index = executableIndex(args); if (index < 0) return null;
+  const script = directScript(args[index], args.slice(index + 1)); if (script === null) return null;
+  let path, source;
+  try {
+    path = realpathSync(isAbsolute(script) ? script : resolve(cwd, script));
+    if (!statSync(path).isFile() || !inside(path)) return null;
+    if (statSync(path).size > 2 * 1024 * 1024) throw Error('command_policy_source_limit');
+    source = new TextDecoder('utf8', { fatal: true, ignoreBOM: true }).decode(readFileSync(path));
+  } catch (error) { if (error.message === 'command_policy_source_limit') throw error; return null; }
+  return extname(path).toLowerCase() === '.py' ? checkPython(source, path, 0)
+    : checkShell(source, path, 0, false, false, ['sh', 'dash'].includes(basename(args[index])) ? 'posix' : 'bash');
+}
+try {
+  const { command } = workerData;
+  const required = workerData.governed && (typeof command !== 'string' || !command.trim())
+    ? finding('command_required', 'command is required') : null;
+  parentPort.postMessage({ contract: LOCAL_COMMAND_POLICY, finding: required ?? (typeof command === 'string'
+    ? checkShell(command, '', 0, workerData.governed, true) : checkTokens(command, '', null, 0) ?? scanScripts(command)) });
+} finally { parser.free(); parentPort.close(); }

package/src/native/local-command-policy.mjs

@@ -0,0 +1,46 @@
+import { Worker } from 'node:worker_threads';
+export { LOCAL_COMMAND_SHELL } from './command-shell.mjs';
+
+export const LOCAL_COMMAND_POLICY = 'agentkit.local-command-policy/v2';
+export const GOVERNED_COMMAND_POLICY = 'agentkit.governed-command-policy/v2';
+const failure = code => Object.assign(new Error(code), { code });
+
+/** Same-container risk checks, not an OS sandbox. Approval and workspace
+ * ownership are Host duties. Source is parsed/read in a bounded Node worker;
+ * no Python interpreter or workspace module is imported or executed.
+ */
+export const checkLocalCommand = (command, options) => checkCommand(command, options, false);
+export const checkGovernedCommand = (command, options) => checkCommand(command, options, true);
+async function checkCommand(command, { cwd, allowedRoots, signal, timeoutMs = 10000 } = {}, governed) {
+  signal?.throwIfAborted();
+  if (!(typeof command === 'string' || Array.isArray(command) && command.every(item => typeof item === 'string'))
+    || Buffer.byteLength(JSON.stringify(command)) > 2 * 1024 * 1024 || typeof cwd !== 'string'
+    || !Array.isArray(allowedRoots) || !allowedRoots.length || allowedRoots.some(root => typeof root !== 'string'))
+    throw failure('invalid_command_policy_input');
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 10000) throw failure('invalid_command_policy_deadline');
+  let worker;
+  try { worker = new Worker(new URL('./local-command-policy-worker.mjs', import.meta.url), {
+    workerData: { command, cwd, allowedRoots, governed }, execArgv: [],
+    resourceLimits: { maxOldGenerationSizeMb: 128, maxYoungGenerationSizeMb: 16, stackSizeMb: 4 },
+  }); } catch { throw failure('command_policy_unavailable'); }
+  return await new Promise((resolve, reject) => {
+    let output, error, stopping = false;
+    const stop = reason => { if (stopping) return; stopping = true; error = reason; void worker.terminate().catch(() => {}); };
+    const abort = () => stop(signal.reason ?? failure('command_policy_canceled'));
+    const timer = setTimeout(() => stop(failure('command_policy_timeout')), timeoutMs);
+    signal?.addEventListener('abort', abort, { once: true });
+    worker.once('message', value => { output = value; });
+    worker.once('error', () => stop(failure('command_policy_unavailable')));
+    worker.once('exit', code => {
+      clearTimeout(timer); signal?.removeEventListener('abort', abort);
+      if (error) return reject(error);
+      const finding = output?.finding;
+      if (code !== 0 || output?.contract !== LOCAL_COMMAND_POLICY || !(finding === null || finding
+        && typeof finding.rule === 'string' && finding.rule && typeof finding.detail === 'string'
+        && typeof finding.path === 'string' && (finding.line === null || Number.isSafeInteger(finding.line) && finding.line > 0)))
+        return reject(failure('command_policy_unavailable'));
+      resolve(finding);
+    });
+    if (signal?.aborted) abort();
+  });
+}