@task-handoff/node-agent 0.0.8 → 0.0.9-alpha.2

package/docker/entrypoint.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+mkdir -p \
+  "${TASK_HANDOFF_DATA_DIR:-/data/task-handoff}" \
+  "${TASK_HANDOFF_APP_CATALOG_DIR:-/data/task-handoff/app-catalog}" \
+  "${TASK_HANDOFF_APP_SESSION_DIR:-/data/task-handoff/app-sessions}" \
+  "${TASK_HANDOFF_RUNTIME_DIR:-/data/task-handoff/runtime}" \
+  "${TASK_HANDOFF_EVENTS_DIR:-/data/task-handoff/events}" \
+  "${TASK_HANDOFF_ARTIFACT_DIR:-/data/artifacts}" \
+  "${TASK_HANDOFF_LOG_DIR:-/data/logs}" \
+  "${CODEX_HOME:-/home/agent/.codex}" \
+  "${CLAUDE_HOME:-/home/agent/.claude}" \
+  "${TASK_HANDOFF_WORKSPACE:-/workspace}"
+
+bootstrap_workspace() {
+  local workspace="${TASK_HANDOFF_WORKSPACE:-/workspace}"
+  local mode="${TASK_HANDOFF_WORKSPACE_MODE:-}"
+  local git_url="${TASK_HANDOFF_GIT_URL:-}"
+  local git_ref="${TASK_HANDOFF_GIT_REF:-}"
+
+  if [ "${mode}" != "git-clone" ] || [ -z "${git_url}" ]; then
+    return
+  fi
+
+  if ! command -v git >/dev/null 2>&1; then
+    echo "Git workspace bootstrap requested, but git is not installed." >&2
+    return 1
+  fi
+
+  mkdir -p "${workspace}"
+  if [ -n "$(find "${workspace}" -mindepth 1 -maxdepth 1 -print -quit 2>/dev/null)" ]; then
+    echo "Workspace ${workspace} is not empty; skipping git clone."
+    return
+  fi
+
+  local clone_args=(clone)
+  if [ -n "${TASK_HANDOFF_GIT_DEPTH:-}" ]; then
+    clone_args+=(--depth "${TASK_HANDOFF_GIT_DEPTH}")
+  fi
+  if [ "${TASK_HANDOFF_GIT_SUBMODULES:-false}" = "true" ]; then
+    clone_args+=(--recurse-submodules)
+  fi
+  if [ -n "${git_ref}" ]; then
+    clone_args+=(--branch "${git_ref}")
+  fi
+  clone_args+=("${git_url}" "${workspace}")
+
+  echo "Cloning workspace ${git_url} into ${workspace}."
+  git "${clone_args[@]}"
+
+  if [ -n "${TASK_HANDOFF_GIT_COMMIT:-}" ]; then
+    git -C "${workspace}" checkout "${TASK_HANDOFF_GIT_COMMIT}"
+  fi
+}
+
+if command -v web-cap >/dev/null 2>&1 && [ -d /tmp/task-handoff-web-cap-skill ]; then
+  for skills_dir in \
+    /home/agent/.agents/skills \
+    "${CODEX_HOME:-/home/agent/.codex}/skills" \
+    "${CLAUDE_HOME:-/home/agent/.claude}/skills"
+  do
+    rm -rf "${skills_dir}/web-cap"
+    mkdir -p "${skills_dir}"
+    cp -R /tmp/task-handoff-web-cap-skill "${skills_dir}/web-cap"
+  done
+fi
+
+start_web_cap_daemon() {
+  if ! command -v web-cap >/dev/null 2>&1; then
+    return
+  fi
+
+  local log_file="${TASK_HANDOFF_LOG_DIR:-/data/logs}/web-cap-daemon.log"
+  local idle_timeout="${WEB_CAP_DAEMON_IDLE_TIMEOUT_MS:-0}"
+
+  if WEB_CAP_DAEMON_IDLE_TIMEOUT_MS="${idle_timeout}" timeout 15s web-cap session-status >"${log_file}" 2>&1; then
+    echo "Web Cap daemon startup probe completed."
+  else
+    echo "Web Cap daemon startup probe failed; see ${log_file}."
+  fi
+}
+
+if [ "${1:-}" = "task-handoff" ] && [ "${2:-}" = "web" ]; then
+  bootstrap_workspace
+  start_web_cap_daemon
+  exec task-handoff-instance-launcher
+fi
+
+if [ "${1:-}" = "task-handoff" ]; then
+  shift
+  if [ "$#" -eq 0 ] || { [ "${1:-}" = "web" ] && [ "$#" -eq 1 ]; }; then
+    exec task-handoff-instance-launcher
+  fi
+  echo "Managed container commands must be launched through the active controlled-instance runtime." >&2
+  exit 64
+fi
+
+exec "$@"

package/docker/instance-launcher.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Stable launcher ABI 1. Application releases are installed independently of
+# the image and selected through the atomic `current` symlink.
+readonly runtime_root="${TASK_HANDOFF_INSTANCE_RUNTIME_ROOT:-/opt/task-handoff/instance-runtime}"
+readonly current="${runtime_root}/current"
+
+bootstrap_wait() {
+  echo "No controlled-instance runtime is active; waiting for node-agent bootstrap."
+  trap 'exit 0' TERM INT
+  while [ ! -L "${current}" ]; do
+    sleep 2 &
+    wait "$!"
+  done
+  echo "A controlled-instance runtime is now active; restart the container to launch it."
+  while true; do
+    sleep 3600 &
+    wait "$!"
+  done
+}
+
+if [ ! -L "${current}" ]; then
+  if command -v task-handoff-controlled-instance >/dev/null 2>&1; then
+    exec task-handoff-controlled-instance web \
+      --host "${TASK_HANDOFF_WEB_HOST:-0.0.0.0}" \
+      --port "${TASK_HANDOFF_WEB_PORT:-8080}"
+  fi
+  bootstrap_wait
+fi
+
+exec node --input-type=module - "${current}" <<'NODE'
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const current = process.argv[2];
+const releaseRoot = fs.realpathSync(current);
+const manifestPath = path.join(releaseRoot, "runtime-manifest.json");
+const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+if (manifest.packageName !== "@task-handoff/controlled-instance" || typeof manifest.entrypoint !== "string") {
+  throw new Error("Active controlled-instance runtime manifest is invalid.");
+}
+const entrypoint = path.resolve(releaseRoot, manifest.entrypoint);
+if (!entrypoint.startsWith(`${releaseRoot}${path.sep}`) || !fs.statSync(entrypoint).isFile()) {
+  throw new Error("Active controlled-instance runtime entrypoint is invalid.");
+}
+process.argv = [process.execPath, entrypoint, "web", "--host", process.env.TASK_HANDOFF_WEB_HOST || "0.0.0.0", "--port", process.env.TASK_HANDOFF_WEB_PORT || "8080"];
+await import(pathToFileURL(entrypoint).href);
+NODE

package/docker/runtime-installer.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const LAUNCHER_ABI = 1;
+const PACKAGE_NAME = "@task-handoff/controlled-instance";
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  if (!["install", "rollback", "verify-active"].includes(argv[0])) fail("Usage: task-handoff-runtime <install|rollback|verify-active> [...]");
+  const result = { command: argv[0] };
+  for (let index = 1; index < argv.length; index += 2) {
+    const key = argv[index];
+    const value = argv[index + 1];
+    if (!key?.startsWith("--") || value === undefined) fail("Invalid runtime installer arguments.");
+    result[key.slice(2)] = value;
+  }
+  return result;
+}
+
+function listPayloadFiles(root, relative = "") {
+  const files = [];
+  for (const entry of fs.readdirSync(path.join(root, relative), { withFileTypes: true })) {
+    const child = relative ? `${relative}/${entry.name}` : entry.name;
+    if (child === "runtime-manifest.json") continue;
+    if (!entry.isSymbolicLink() && !entry.isDirectory() && !entry.isFile()) fail(`Runtime artifact contains an unsupported entry: ${child}`);
+    if (entry.isDirectory()) files.push(...listPayloadFiles(root, child));
+    else files.push({ relative: child, type: entry.isSymbolicLink() ? "L" : "F" });
+  }
+  return files;
+}
+
+function payloadSha256(root) {
+  const hash = crypto.createHash("sha256");
+  const resolvedRoot = fs.realpathSync(root);
+  const files = listPayloadFiles(root).sort((left, right) => Buffer.compare(Buffer.from(left.relative), Buffer.from(right.relative)));
+  for (const item of files) {
+    const absolute = path.join(root, item.relative);
+    const contents = item.type === "L" ? Buffer.from(fs.readlinkSync(absolute), "utf8") : fs.readFileSync(absolute);
+    if (item.type === "L") {
+      const resolved = fs.realpathSync(absolute);
+      if (resolved !== resolvedRoot && !resolved.startsWith(`${resolvedRoot}${path.sep}`)) fail(`Runtime artifact symlink escapes its root: ${item.relative}`);
+    }
+    hash.update(Buffer.from(item.type, "ascii"));
+    hash.update(Buffer.from(item.relative, "utf8"));
+    hash.update(Buffer.from([0]));
+    hash.update(Buffer.from(String(contents.byteLength), "ascii"));
+    hash.update(Buffer.from([0]));
+    hash.update(contents);
+    hash.update(Buffer.from([0]));
+  }
+  return hash.digest("hex");
+}
+
+function validateVersion(value) {
+  return typeof value === "string" && /^[0-9A-Za-z][0-9A-Za-z.+_-]{0,79}$/.test(value);
+}
+
+function lockReleaseTree(root) {
+  const owner = typeof process.getuid === "function" ? process.getuid() : 0;
+  const group = typeof process.getgid === "function" ? process.getgid() : 0;
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const absolute = path.join(root, entry.name);
+    if (entry.isDirectory()) lockReleaseTree(absolute);
+    fs.lchownSync(absolute, owner, group);
+    if (!entry.isSymbolicLink()) {
+      const mode = fs.lstatSync(absolute).mode & 0o777;
+      fs.chmodSync(absolute, entry.isDirectory() || (mode & 0o111) !== 0 ? 0o755 : 0o644);
+    }
+  }
+  fs.chownSync(root, owner, group);
+  fs.chmodSync(root, 0o755);
+}
+
+const args = parseArgs(process.argv.slice(2));
+const runtimeRoot = process.env.TASK_HANDOFF_INSTANCE_RUNTIME_ROOT || "/opt/task-handoff/instance-runtime";
+function validateRelease(release, expectedVersion) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(release, "runtime-manifest.json"), "utf8"));
+  if (manifest.packageName !== PACKAGE_NAME || (expectedVersion && manifest.version !== expectedVersion) || manifest.formatVersion !== 1 || manifest.launcherAbi !== LAUNCHER_ABI) fail("Runtime release manifest is invalid.");
+  const compatible = (manifest.platform === "universal" || manifest.platform === process.platform)
+    && (manifest.arch === "universal" || manifest.arch === process.arch);
+  if (!compatible || payloadSha256(release) !== manifest.sha256) fail("Runtime release is incompatible or corrupt.");
+  const entrypoint = path.resolve(release, manifest.entrypoint);
+  if (!entrypoint.startsWith(`${release}${path.sep}`) || !fs.statSync(entrypoint).isFile()) fail("Runtime release entrypoint is invalid.");
+  return manifest;
+}
+if (args.command === "verify-active") {
+  const release = fs.realpathSync(path.join(runtimeRoot, "current"));
+  const manifest = validateRelease(release);
+  process.stdout.write(`${JSON.stringify(manifest)}\n`);
+  process.exit(0);
+}
+if (args.command === "rollback") {
+  const previousRelease = fs.readFileSync(path.join(runtimeRoot, "previous-release"), "utf8").trim();
+  if (!validateVersion(previousRelease)) fail("No previous runtime release is available.");
+  const release = path.join(runtimeRoot, "releases", previousRelease);
+  const manifest = validateRelease(release);
+  const next = path.join(runtimeRoot, `.current-${process.pid}-${Date.now()}`);
+  fs.symlinkSync(path.relative(runtimeRoot, release), next);
+  fs.renameSync(next, path.join(runtimeRoot, "current"));
+  process.stdout.write(`${JSON.stringify({ version: manifest.version, sha256: manifest.sha256, release })}\n`);
+  process.exit(0);
+}
+const expected = {
+  version: args.version,
+  sha256: args.sha256,
+  platform: args.platform,
+  arch: args.arch,
+  launcherAbi: Number(args["launcher-abi"]),
+};
+if (!args.artifact || !validateVersion(expected.version) || !/^[a-f0-9]{64}$/.test(expected.sha256 || "")) fail("Invalid runtime artifact identity.");
+if (expected.launcherAbi !== LAUNCHER_ABI) fail(`Unsupported launcher ABI: ${expected.launcherAbi}`);
+
+const stagingRoot = path.join(runtimeRoot, "staging");
+const releasesRoot = path.join(runtimeRoot, "releases");
+const releaseKey = `${expected.version}-${expected.sha256}`;
+fs.mkdirSync(stagingRoot, { recursive: true });
+fs.mkdirSync(releasesRoot, { recursive: true });
+const staging = fs.mkdtempSync(path.join(stagingRoot, `${expected.version}-`));
+let preserveStaging = false;
+
+try {
+  // A production runtime contains thousands of dependency files, so its tar
+  // listing legitimately exceeds spawnSync's small default output buffer.
+  // The archive itself is already pinned by the release identity; keep a
+  // bounded but production-sized buffer while validating every entry type.
+  const listing = spawnSync("tar", ["-tvzf", args.artifact], { encoding: "utf8", maxBuffer: 128 * 1024 * 1024 });
+  if (listing.status !== 0) fail(listing.stderr || "Could not inspect runtime artifact.");
+  for (const line of listing.stdout.split(/\r?\n/).filter(Boolean)) {
+    if (!["-", "d", "l"].includes(line[0])) fail("Runtime artifact contains a hard link or special file.");
+  }
+  const unpacked = spawnSync("tar", ["-xzf", args.artifact, "--no-same-owner", "--no-same-permissions", "-C", staging], { encoding: "utf8" });
+  if (unpacked.status !== 0) fail(unpacked.stderr || "Could not unpack runtime artifact.");
+  const manifestPath = path.join(staging, "runtime-manifest.json");
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const manifestKeys = ["arch", "entrypoint", "formatVersion", "launcherAbi", "packageName", "platform", "sha256", "version"];
+  const exactIdentity = Object.keys(manifest).sort().join("\0") === manifestKeys.join("\0")
+    && manifest.packageName === PACKAGE_NAME
+    && manifest.version === expected.version
+    && manifest.platform === expected.platform
+    && manifest.arch === expected.arch
+    && manifest.formatVersion === 1
+    && manifest.launcherAbi === expected.launcherAbi
+    && manifest.sha256 === expected.sha256
+    && typeof manifest.entrypoint === "string";
+  if (!exactIdentity) fail("Runtime artifact manifest does not match the requested identity.");
+  const compatible = (manifest.platform === "universal" || manifest.platform === process.platform)
+    && (manifest.arch === "universal" || manifest.arch === process.arch);
+  if (!compatible) fail(`Runtime artifact is incompatible with ${process.platform}/${process.arch}.`);
+  const entrypoint = path.resolve(staging, manifest.entrypoint);
+  if (!entrypoint.startsWith(`${staging}${path.sep}`) || !fs.statSync(entrypoint).isFile()) fail("Runtime artifact entrypoint is invalid.");
+  if (payloadSha256(staging) !== expected.sha256) fail("Runtime artifact payload SHA-256 is invalid.");
+
+  const release = path.join(releasesRoot, releaseKey);
+  if (fs.existsSync(release)) {
+    const existingManifest = JSON.parse(fs.readFileSync(path.join(release, "runtime-manifest.json"), "utf8"));
+    const existingIdentityMatches = existingManifest.packageName === PACKAGE_NAME
+      && existingManifest.version === expected.version
+      && existingManifest.platform === expected.platform
+      && existingManifest.arch === expected.arch
+      && existingManifest.formatVersion === 1
+      && existingManifest.launcherAbi === expected.launcherAbi
+      && existingManifest.sha256 === expected.sha256
+      && typeof existingManifest.entrypoint === "string";
+    if (!existingIdentityMatches || payloadSha256(release) !== expected.sha256) fail(`Existing release ${releaseKey} is invalid.`);
+  } else {
+    fs.renameSync(staging, release);
+    preserveStaging = true;
+  }
+  lockReleaseTree(release);
+
+  let previousRelease = "";
+  try {
+    previousRelease = path.basename(fs.realpathSync(path.join(runtimeRoot, "current")));
+  } catch {}
+  const next = path.join(runtimeRoot, `.current-${process.pid}-${Date.now()}`);
+  fs.symlinkSync(path.relative(runtimeRoot, release), next);
+  fs.renameSync(next, path.join(runtimeRoot, "current"));
+  if (previousRelease && previousRelease !== releaseKey) fs.writeFileSync(path.join(runtimeRoot, "previous-release"), `${previousRelease}\n`);
+  process.stdout.write(`${JSON.stringify({ version: expected.version, sha256: expected.sha256, release })}\n`);
+} finally {
+  if (!preserveStaging) fs.rmSync(staging, { recursive: true, force: true });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@task-handoff/node-agent",
-  "version": "0.0.8",
+  "version": "0.0.9-alpha.2",
   "description": "Prebuilt TaskHandoff node agent runtime.",
   "license": "Apache-2.0",
   "type": "commonjs",
@@ -10,6 +10,8 @@
   "files": [
     "bin",
     "dist",
+    "docker",
+    "runtime-artifacts",
     "README.md",
     "LICENSE",
     "NOTICE"
@@ -26,6 +28,7 @@
     "fastify": "5.8.5",
     "node-pty": "1.1.0",
     "semver": "7.8.5",
+    "tar": "7.5.20",
     "telegramify-markdown": "1.3.3",
     "write-file-atomic": "8.0.0",
     "ws": "8.21.0",

package/runtime-artifacts/controlled-instance-runtime-0.0.9-alpha.2-linux-universal.manifest.json

@@ -0,0 +1,10 @@
+{
+  "packageName": "@task-handoff/controlled-instance",
+  "version": "0.0.9-alpha.2",
+  "platform": "linux",
+  "arch": "universal",
+  "formatVersion": 1,
+  "launcherAbi": 1,
+  "entrypoint": "dist/controlled-instance-cli.js",
+  "sha256": "443ac2b1efaf7cb2c76641740550b9ac5cd351604ba73f36c7faa88a3ef136f8"
+}

package/runtime-artifacts/controlled-instance-runtime-0.0.9-alpha.2-linux-universal.tar.gz.sha256

@@ -0,0 +1 @@
+f3a14a8289b749efe45a83c8cd45bdb687d80d7a9f3a8e23e00834d8e04520ef  controlled-instance-runtime-0.0.9-alpha.2-linux-universal.tar.gz