@amistio/cli 0.1.36 → 0.1.38

package/README.md

@@ -9,7 +9,19 @@ npm install -g @amistio/cli
 amistio --help
 ```
 
-The package install only installs the `amistio` command. Repository cloning, project pairing, credential storage, sync watching, and runner execution happen only when the user explicitly runs commands such as `amistio bootstrap`, `amistio import`, `amistio pair`, `amistio sync watch`, or `amistio run --watch`. When the app copies a personal project into an organization, the CLI command syntax stays the same; create the org-scoped code and run `amistio import <code>` from the intended local checkout. Import scans repo-local project-brain docs plus recognized repo-local IDE, harness, and local AI tool memory or instruction files such as `AGENTS.md`, `.github/copilot-instructions.md`, `.cursor/rules/*.mdc`, `.windsurfrules`, and `memories/*.md`; durable Amistio memory belongs in `docs/memory/`, and global plugin or harness memory outside the repository is not scanned by default.
+The package install provides the `amistio` command and the optional `amistio-host-helper` executable. Repository cloning, project pairing, credential storage, sync watching, helper activation, and runner execution happen only when the user explicitly runs commands such as `amistio bootstrap`, `amistio import`, `amistio pair`, `amistio sync watch`, `amistio host-helper status`, or `amistio run --watch`. When the app copies a personal project into an organization, the CLI command syntax stays the same; create the org-scoped code and run `amistio import <code>` from the intended local checkout. Import scans repo-local project-brain docs plus recognized repo-local IDE and local AI tool memory or instruction files such as `AGENTS.md`, `.github/copilot-instructions.md`, `.cursor/rules/*.mdc`, `.windsurfrules`, and `memories/*.md`; durable Amistio memory belongs in `docs/memory/`, and global plugin memory outside the repository is not scanned by default.
+
+For enterprise setup, use the web Runner panel as the primary guide. It shows repository, pairing code, GitHub access, AI provider, local runner, and verification readiness with plain next actions; advanced CLI logs remain secondary diagnostics. The panel also shows trust/privacy boundaries, cost forecast and budget posture, runner health, blockers, verification health, and runner-version distribution from safe runner metadata.
+
+Optional host helpers are configured outside the SaaS with `AMISTIO_HOST_HELPER_PATH`. The official npm package ships `amistio-host-helper` for Level 1 supervised process execution diagnostics; enable it with `AMISTIO_HOST_HELPER_PATH=$(command -v amistio-host-helper)` on reviewed runner machines and confirm `amistio host-helper status` plus `amistio host-helper conformance`. PTY and sandbox requests use a helper only when its versioned handshake advertises support; otherwise the CLI returns deterministic unsupported results instead of silently downgrading. The npm helper does not advertise PTY or sandbox support. Helper request envelopes include allowlisted environment values, explicit sandbox policy metadata, and bounded normalized output, and must never include provider tokens, OAuth material, runner API tokens, local auth files, or arbitrary SaaS-originated shell text.
+
+Before publishing the CLI, run the package release gate:
+
+```sh
+corepack pnpm --config.verify-deps-before-run=false --filter @amistio/cli release:check
+```
+
+The check packs and installs the package, rejects source maps/tests/source files in the tarball, verifies both installed bins, and runs helper handshake, status, and conformance from the installed artifact.
 
 Runner lifecycle controls in the web app, such as update, restart, and remove, apply only to the runner paired by that user unless the active organization role is an admin role. The runner API binds command polling, command status, logs, activity, and tool sessions to the local runner credential that produced them.
 
@@ -27,6 +39,8 @@ After pairing, confirm that at least one local AI tool is available:
 
 ```sh
 amistio tools
+amistio host-helper status
+amistio host-helper conformance
 ```
 
 If no supported tool is available, install and authenticate one of the supported local tools, such as opencode, then start the runner:
@@ -37,12 +51,16 @@ amistio run --watch --tool opencode
 amistio run --watch --tool opencode --provider anthropic --model-id claude-opus-4.6 --reasoning-effort xhigh
 amistio run --watch --max-concurrent-work 2 --tool opencode
 amistio run --watch --background --tool opencode
+AMISTIO_HOST_HELPER_PATH=$(command -v amistio-host-helper) amistio host-helper status
+AMISTIO_HOST_HELPER_PATH=$(command -v amistio-host-helper) amistio host-helper conformance
 amistio runner status
 amistio runner smoke-session-lifecycle
 ```
 
 Provider-backed model preferences use sanitized catalog fields: `--provider`, `--model-id`, optional `--model-variant`, and `--reasoning-effort` (`auto`, `low`, `medium`, `high`, or `xhigh`). Opencode catalog metadata is synthesized by Amistio or derived from readable local OpenCode JSON config until opencode exposes a native catalog. Provider credentials, API keys, and local secret paths stay in the local tool configuration; they are not stored in Amistio preferences or runner heartbeats.
 
+Opencode remains an optional compatibility route. When a provider/model is named for opencode, Amistio validates it against the safe provider catalog before launching the external tool instead of silently falling back. Command-mode local tool runs are bounded by `--tool-timeout-seconds`, wait for process cleanup after timeout, and return redacted/capped stdout and stderr so large external output, local execution-root paths, and secret-looking assignments are not persisted unbounded.
+
 When `--tool copilot` uses the GitHub Copilot SDK, Amistio approves read-only permission requests by default and denies mutating, network, MCP, hook, memory, and shell requests. Set `AMISTIO_COPILOT_APPROVE_ALL=1` only on a local machine where broad Copilot SDK approval is intentional.
 
 When `--tool codex` uses the Codex SDK, intermediate progress can be quiet until the final response. For live Codex CLI logs, run `amistio run --watch --tool codex --invocation-channel command`.
@@ -65,6 +83,8 @@ Watch mode prints a completed-work success once per work item, keeps fresh compl
 
 Known validation failures such as `unsafe_context_path` are printed with attention-needed next steps. For project-context refresh path-safety failures, deploy the latest web/API fix, update and restart the runner when applicable, retry the refresh, and capture only bounded non-secret output if it repeats.
 
+If watch mode reports that the runner was forgotten by the server, stop the foreground process and start or pair a new runner from the Runner panel. Forgotten runner IDs are intentionally blocked from heartbeats and work claims, so the CLI exits instead of retrying with the tombstoned identity.
+
 App-evaluation result finalization rejections print safe validation paths and preserve the local finalization evidence without exposing raw source or secrets. If a structured app-evaluation result is rejected, update and restart the runner, confirm the web/API deployment is current, and retry the evaluation before acting on cleanup or implementation recommendations.
 
 When brain generation or plan revision output is parsed but the Amistio API is temporarily unavailable during finalization, the runner keeps a safe pending result envelope in user-level Amistio config and replays it before claiming more work. The envelope uses a stable idempotency key and does not store raw tool stdout, provider sessions, credentials, or arbitrary local paths.

package/dist/host-helper.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+
+// src/host-helper.ts
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+// src/host-execution.ts
+import { spawn } from "node:child_process";
+var hostExecutionProtocolVersion = "amistio.hostExecution.v1";
+var nativeHostHelperSecretBoundary = {
+  credentialPolicy: "never-send-credentials",
+  environmentPolicy: "allowlist-only",
+  forbiddenInputs: [
+    "runner API tokens",
+    "provider API keys",
+    "OAuth tokens",
+    "refresh tokens",
+    "SaaS credentials",
+    "local auth files",
+    "unbounded environment variables",
+    "arbitrary SaaS-sourced shell text"
+  ]
+};
+var defaultNativeHostOutputBudgetBytes = 64 * 1024;
+var nodeHostExecutionCapabilities = {
+  protocolVersion: hostExecutionProtocolVersion,
+  implementation: "node",
+  processGroups: process.platform === "win32" ? { supported: false, reason: "Windows process-group cleanup needs a native helper or platform-specific implementation." } : { supported: true },
+  signalEscalation: { supported: true },
+  streamCapture: { supported: true },
+  pty: { supported: false, reason: "PTY bridging is reserved for a future native helper." },
+  sandbox: { supported: false, reason: "Sandboxed command execution is reserved for a future native helper." },
+  outputEncoding: "utf8"
+};
+var defaultHostExecution = {
+  capabilities: nodeHostExecutionCapabilities,
+  executeCommand: executeNodeCommand,
+  commandExists
+};
+async function executeNodeCommand(request) {
+  if (request.requirePty) {
+    return unsupportedResult("pty_unsupported", "PTY command execution is not supported by the default Node host execution port.");
+  }
+  if (request.sandbox && request.sandbox !== "none") {
+    return unsupportedResult("sandbox_unsupported", `${request.sandbox} sandbox execution is not supported by the default Node host execution port.`);
+  }
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(request.command, [...request.args], {
+        cwd: request.cwd,
+        env: request.env ?? process.env,
+        detached: process.platform !== "win32",
+        shell: request.shell ?? false,
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+    } catch (error) {
+      resolve(spawnFailedResult(error));
+      return;
+    }
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let forceKillTimer;
+    let timedOutError;
+    const timeout = request.timeoutMs && request.timeoutMs > 0 ? setTimeout(() => {
+      if (settled) return;
+      const message = request.timeoutMessage ?? `Command timed out after ${request.timeoutMs}ms: ${request.command}`;
+      stderr += `${message}
+`;
+      timedOutError = { code: "timeout", message };
+      killProcessTree(child, "SIGTERM");
+      forceKillTimer = setTimeout(() => killProcessTree(child, "SIGKILL"), request.killGraceMs ?? 5e3);
+      forceKillTimer.unref?.();
+    }, request.timeoutMs) : void 0;
+    timeout?.unref?.();
+    const resolveOnce = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+      resolve(result);
+    };
+    child.on("error", (error) => {
+      if (timedOutError) return;
+      resolveOnce(spawnFailedResult(error, stdout, stderr));
+    });
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+      if (request.streamOutput) process.stdout.write(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+      if (request.streamOutput) process.stderr.write(chunk);
+    });
+    child.stdin.on("error", () => void 0);
+    if (request.stdin) {
+      child.stdin.write(request.stdin);
+    }
+    child.stdin.end();
+    child.on("close", (exitCode) => {
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+      if (timedOutError) {
+        resolveOnce({ status: "timedOut", exitCode: 1, stdout, stderr, error: timedOutError });
+        return;
+      }
+      resolveOnce({ status: "completed", exitCode: exitCode ?? 1, stdout, stderr });
+    });
+  });
+}
+function unsupportedResult(code, message) {
+  return { status: "unsupported", exitCode: 1, stdout: "", stderr: "", error: { code, message } };
+}
+function spawnFailedResult(error, stdout = "", stderr = "") {
+  return { status: "spawnFailed", exitCode: 1, stdout, stderr, error: { code: "spawn_failed", message: errorMessage(error) } };
+}
+function killProcessTree(child, signal) {
+  if (child.pid && process.platform !== "win32") {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch {
+    }
+  }
+  child.kill(signal);
+}
+async function commandExists(command) {
+  const lookupCommand = process.platform === "win32" ? "where" : "which";
+  return new Promise((resolve) => {
+    const lookup = spawn(lookupCommand, [command], { stdio: "ignore" });
+    lookup.on("error", () => resolve(false));
+    lookup.on("close", (exitCode) => resolve(exitCode === 0));
+  });
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/host-helper.ts
+var maxRequestEnvelopeBytes = 512 * 1024;
+var defaultOutputBudgetBytes = 64 * 1024;
+function createOfficialHostHelperHandshake() {
+  const capabilities = {
+    ...nodeHostExecutionCapabilities,
+    implementation: "nativeHelper",
+    pty: { supported: false, reason: "The official npm helper does not allocate PTYs yet. Use a future native helper build for PTY support." },
+    sandbox: { supported: false, reason: "The official npm helper does not enforce OS sandboxes yet. Use a future native helper build for sandbox support." }
+  };
+  return { protocolVersion: hostExecutionProtocolVersion, capabilities, secretBoundary: nativeHostHelperSecretBoundary };
+}
+async function executeOfficialHostHelperRequest(input) {
+  const parsed = parseJson(input);
+  if (!isNativeHostCommandRequestEnvelope(parsed)) {
+    const requestId = requestIdFromUnknown(parsed) ?? "invalid-request";
+    return resultEnvelope(requestId, protocolMismatch("Host helper request envelope did not match the Amistio host execution protocol."));
+  }
+  if (parsed.stdin === "provided") {
+    return resultEnvelope(parsed.requestId, unsupportedResult2("helper_failed", "The official helper does not accept stdin payload delegation."));
+  }
+  if (parsed.shell) {
+    return resultEnvelope(parsed.requestId, unsupportedResult2("helper_failed", "The official helper does not execute shell-wrapped requests."));
+  }
+  if (parsed.requirePty) {
+    return resultEnvelope(parsed.requestId, unsupportedResult2("pty_unsupported", "PTY execution is not supported by the official npm helper."));
+  }
+  if (parsed.sandbox !== "none") {
+    return resultEnvelope(parsed.requestId, unsupportedResult2("sandbox_unsupported", `${parsed.sandbox} sandbox execution is not supported by the official npm helper.`));
+  }
+  const commandRequest = {
+    command: parsed.command,
+    args: parsed.args,
+    cwd: parsed.cwd,
+    env: sanitizeRequestEnvironment(parsed),
+    shell: false,
+    streamOutput: false,
+    outputBudgetBytes: positiveInteger(parsed.outputBudgetBytes) ?? defaultOutputBudgetBytes
+  };
+  const timeoutMs = positiveInteger(parsed.timeoutMs);
+  if (timeoutMs !== void 0) {
+    commandRequest.timeoutMs = timeoutMs;
+  }
+  const result = await defaultHostExecution.executeCommand(commandRequest);
+  return resultEnvelope(parsed.requestId, result, positiveInteger(parsed.outputBudgetBytes) ?? defaultOutputBudgetBytes);
+}
+async function runOfficialHostHelperCli(argv = process.argv.slice(2), io = process) {
+  const mode = argv[0];
+  if (mode === "--amistio-host-helper-handshake") {
+    io.stdout.write(`${JSON.stringify(createOfficialHostHelperHandshake())}
+`);
+    return 0;
+  }
+  if (mode === "--amistio-host-helper-execute") {
+    try {
+      const input = await readStdinLimited(io.stdin, maxRequestEnvelopeBytes);
+      const result = await executeOfficialHostHelperRequest(input);
+      io.stdout.write(`${JSON.stringify(result)}
+`);
+      return 0;
+    } catch (error) {
+      io.stderr.write(`${errorMessage2(error)}
+`);
+      return 1;
+    }
+  }
+  if (mode === "--help" || mode === "-h") {
+    io.stdout.write("Usage: amistio-host-helper --amistio-host-helper-handshake | --amistio-host-helper-execute\n");
+    return 0;
+  }
+  io.stderr.write("Unknown Amistio host helper mode. Use --help for usage.\n");
+  return 1;
+}
+function resultEnvelope(requestId, result, outputBudgetBytes = defaultOutputBudgetBytes) {
+  return {
+    protocolVersion: hostExecutionProtocolVersion,
+    requestId,
+    status: result.status,
+    exitCode: result.exitCode,
+    stdout: capUtf8Text(result.stdout, outputBudgetBytes),
+    stderr: capUtf8Text(result.stderr, outputBudgetBytes),
+    ...result.error ? { error: result.error } : {}
+  };
+}
+function unsupportedResult2(code, message) {
+  return { status: "unsupported", exitCode: 1, stdout: "", stderr: "", error: { code, message } };
+}
+function protocolMismatch(message) {
+  return { status: "protocolMismatch", exitCode: 1, stdout: "", stderr: "", error: { code: "protocol_mismatch", message } };
+}
+function sanitizeRequestEnvironment(request) {
+  const allowedNames = new Set(request.envAllowlist);
+  const env = {};
+  for (const [name, value] of Object.entries(request.env)) {
+    if (!allowedNames.has(name) || isSensitiveEnvironmentName(name)) {
+      continue;
+    }
+    env[name] = value;
+  }
+  return env;
+}
+function isNativeHostCommandRequestEnvelope(value) {
+  if (!isRecord(value) || value.protocolVersion !== hostExecutionProtocolVersion) return false;
+  return typeof value.requestId === "string" && value.requestId.trim().length > 0 && typeof value.command === "string" && value.command.trim().length > 0 && Array.isArray(value.args) && value.args.every((item) => typeof item === "string") && typeof value.cwd === "string" && value.cwd.trim().length > 0 && typeof value.shell === "boolean" && typeof value.timeoutMs === "number" && Number.isFinite(value.timeoutMs) && value.timeoutMs >= 0 && (value.stdin === "none" || value.stdin === "provided") && isStringRecord(value.env) && Array.isArray(value.envAllowlist) && value.envAllowlist.every((item) => typeof item === "string") && typeof value.streamOutput === "boolean" && typeof value.requirePty === "boolean" && isSandboxMode(value.sandbox) && isRecord(value.sandboxPolicy) && typeof value.outputBudgetBytes === "number" && Number.isFinite(value.outputBudgetBytes) && value.outputBudgetBytes >= 0;
+}
+function isSandboxMode(value) {
+  return value === "none" || value === "filesystemReadOnly" || value === "networkDisabled";
+}
+function isStringRecord(value) {
+  return isRecord(value) && Object.values(value).every((item) => typeof item === "string");
+}
+function requestIdFromUnknown(value) {
+  return isRecord(value) && typeof value.requestId === "string" && value.requestId.trim() ? value.requestId : void 0;
+}
+function readStdinLimited(stdin, limitBytes) {
+  return new Promise((resolve, reject) => {
+    let input = "";
+    let bytes = 0;
+    stdin.setEncoding("utf8");
+    stdin.on("data", (chunk) => {
+      bytes += Buffer.byteLength(chunk, "utf8");
+      if (bytes > limitBytes) {
+        reject(new Error(`Host helper request exceeded ${limitBytes} bytes.`));
+        stdin.pause();
+        return;
+      }
+      input += chunk;
+    });
+    stdin.on("error", reject);
+    stdin.on("end", () => resolve(input));
+  });
+}
+function capUtf8Text(value, budgetBytes) {
+  if (Buffer.byteLength(value, "utf8") <= budgetBytes) return value;
+  let capped = Buffer.from(value, "utf8").subarray(0, budgetBytes).toString("utf8");
+  while (Buffer.byteLength(capped, "utf8") > budgetBytes && capped.length > 0) {
+    capped = capped.slice(0, -1);
+  }
+  return capped;
+}
+function isSensitiveEnvironmentName(name) {
+  return /(?:TOKEN|SECRET|PASSWORD|PASS|KEY|CREDENTIAL|AUTH|OAUTH|COOKIE|SESSION|PRIVATE|CERT|SSH)/i.test(name);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseJson(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return void 0;
+  }
+}
+function positiveInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
+}
+function errorMessage2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function isDirectExecution(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+  } catch {
+    return fileURLToPath(metaUrl) === fileURLToPath(new URL(`file://${process.argv[1]}`).href);
+  }
+}
+if (isDirectExecution(import.meta.url)) {
+  process.exitCode = await runOfficialHostHelperCli();
+}
+export {
+  createOfficialHostHelperHandshake,
+  executeOfficialHostHelperRequest,
+  runOfficialHostHelperCli
+};