@runuai/host 0.9.167 → 0.9.169

package/src/protocol.ts

@@ -1,3 +1,4 @@
+import type { TaskSecretApplied, TaskSecretStagingPut, TaskSecretStagingAck } from "./task-secrets";
 import {
   parseCaptureFlowWire,
   parseCaptureResultWire,
@@ -48,6 +49,7 @@ export enum HostErrorCode {
   NoSuchPermission = "no_such_permission",
   HostUnavailable = "host_unavailable",
   Internal = "internal",
+  PayloadTooLarge = "payload_too_large",
 }
 
 export type HostCommandResult<T> =
@@ -62,8 +64,10 @@ export type HostCommandResult<T> =
        * ignore this additive field; new readers use it only to bridge the
        * short supervisor restart after a managed-runtime activation. Generic
        * `retryable` failures (for example, no Docker runtime) remain fail-fast.
+       * `connection_changed` is cloud-only: the runner's socket generation
+       * moved after this launch was built, so the command was not sent.
        */
-      retryReason?: "managed_restart" | "runtime_setup";
+      retryReason?: "managed_restart" | "runtime_setup" | "connection_changed";
       /**
        * Who decided this failed.
        *
@@ -93,6 +97,8 @@ export type HostCommandResult<T> =
     };
 
 /** Capability ids shared by host advertisement and fail-closed cloud gates. */
+export const ASSIGNMENT_EVIDENCE_PROTOCOL_FEATURE = "assignment-evidence-v1";
+export const LEAD_EVIDENCE_PROTOCOL_FEATURE = "lead-evidence-v1";
 export const TRANSCRIPT_TARGETS_PROTOCOL_FEATURE = "transcript-targets-v1";
 export const SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE =
   "secretary-typed-dispatch-v1";
@@ -232,6 +238,14 @@ export const LIVE_ROSTER_EDIT_PROTOCOL_FEATURE = "live-roster-edit-v1";
  * generation is not its roster entry's, so a token minted for an earlier agent
  * under the same handle stays dead. */
 export const AGENT_TOKEN_GENERATION_PROTOCOL_FEATURE = "agent-token-generation-v1";
+/** ADR-161 §2: the runner can add a repository to a RUNNING task through the
+ * fenced `taskProjectPrepare` → `taskProjectActivate` operation (with
+ * `taskProjectStatus` and `taskProjectCompensate` for recovery). It clones a
+ * self-contained repository inside the task's own runtime, as the task user,
+ * journals an activation intent before the rename into `/workspace/<slug>`,
+ * and answers published / not_published / uncertain from the disk. A cloud
+ * refuses the add with HOST_UPDATE_REQUIRED until a runner advertises it. */
+export const LIVE_TASK_PROJECTS_PROTOCOL_FEATURE = "live-task-projects-v1";
 /** ADR-153 declarations + owner bindings. Advertising this means the host
  * understands every additive env frame field, persists bindings separately
  * from values, and reports immutable repository schema observations. Keep it
@@ -3097,7 +3111,7 @@ export interface CommandContext {
    */
   timeoutMs?: number;
   /**
-   * Cloud-internal routing override for a durable taskDown. Lifecycle cleanup
+   * Cloud-internal routing override for durable taskDown or archival attachmentRead. Lifecycle cleanup
    * may outlive the task row whose host assignment normally routes commands.
    * This field is context metadata: it is never serialized onto the host
    * command frame, and no host/request payload may populate it.
@@ -3110,6 +3124,15 @@ export interface CommandContext {
    * Like targetHostId, this is relay metadata and never reaches the host wire.
    */
   expectedHostTokenHash?: string;
+  /**
+   * Cloud-internal generation of the host connection whose advertisement
+   * built this taskUp. The bridge does not send the launch when the socket
+   * that would receive it is a different generation. Never serialized onto
+   * the host frame. Absent skips the fence. Null means the features were
+   * read with no live connection, so a socket that appears before the send
+   * is a change and the launch must be built again.
+   */
+  capabilityGeneration?: string | null;
 }
 
 export type PermissionDecision = { kind: "accept" } | { kind: "decline" };
@@ -4045,6 +4068,15 @@ export function isHostConfigAckFrame(
  * changes. The cloud caches it per hostId to drive the task-creation pickers.
  */
 export interface HostCapabilities {
+  /** Filesystem capacity, refreshed each minute. Null means unmeasurable
+   * (for example Docker in a VM); available excludes root-reserved blocks. */
+  disk?: {
+    sampledAt: number;
+    /** Cloud-only: overwritten on authenticated receipt, never trusted from the host. */
+    receivedAt?: number;
+    home: { totalBytes: number; availableBytes: number } | null;
+    docker: { totalBytes: number; availableBytes: number } | null;
+  };
   /** The host-agent package version — the cloud UI shows it on the host page
    *  and flags when npm has a newer release. Optional (older hosts omit it). */
   version?: string;
@@ -4314,6 +4346,124 @@ export interface TaskDiffInput {
   projects: Array<{ id: string; slug: string }>;
 }
 
+/** Cloud Prepare retry timing. */
+export const TASK_PROJECT_PREPARE_MAX_ATTEMPTS = 12;
+export const TASK_PROJECT_PREPARE_TIMEOUT_MS = 11 * 60_000;
+export function taskProjectRetryDelayMs(attempts: number): number {
+  return Math.min(5 * 60_000, 2_000 * 2 ** Math.min(attempts, 7));
+}
+/** Bound the CLI tool call; the durable cloud operation may outlast it. */
+export const TASK_PROJECT_ADD_WAIT_MS = 40 * 60_000;
+
+/**
+ * ADR-161 §2.3: every live-project command names the task's run, the
+ * operation, and the project-set revision the operation commits. The runner
+ * refuses a command for a run it has not admitted, and any Prepare or
+ * Activate for a revision older than one it has already activated or
+ * compensated.
+ */
+export interface TaskProjectOpFence {
+  taskId: string;
+  runEpoch: number;
+  operationId: string;
+  projectSetRevision: number;
+}
+
+export interface TaskProjectPrepareInput extends TaskProjectOpFence {
+  /** The task branch the clone checks out (from origin when it exists). */
+  branch: string;
+  /** `toolVersions` is the project's fallback `.tool-versions`, seeded into
+   *  a clone that ships none, exactly as task-up seeds a startup project. */
+  project: { id: string; slug: string; repoUrl: string; toolVersions?: string };
+}
+
+/** Why a live-project command did nothing. `grant_not_installed` and
+ *  `busy` are retryable; the rest are final for that operation. */
+export type TaskProjectRefusal =
+  | "invalid_request"
+  | "repo_access_denied"
+  | "clone_failed"
+  | "workspace_path_taken"
+  | "stale"
+  | "not_running"
+  | "compensated"
+  | "not_prepared"
+  | "grant_not_installed"
+  | "published"
+  | "busy"
+  /** The running environment cannot take a live project (no env spec or no
+   *  live env gateway): the cloud answers REQUIRES_TASK_RESTART. */
+  | "unsupported_environment"
+  /** Published, but a required step (Git root, env install) did not
+   *  complete; Activate repairs it when repeated. Never terminal. */
+  | "incomplete";
+
+export type TaskProjectPrepareResult =
+  | {
+      outcome: "prepared";
+      head: string | null;
+      /** The `.env.schema` observation read from the fresh clone, stored on
+       *  the runner before the project is exposed to anything (ADR-153 §4). */
+      envSchema: ProjectEnvSchemaObservation | null;
+    }
+  | { outcome: "refused"; reason: TaskProjectRefusal; message: string };
+
+export interface TaskProjectActivateInput extends TaskProjectOpFence {
+  /** The full project, for the task's env spec and the agents' notice. */
+  project: TaskCommandProject;
+  /** The cloud-computed preview URL literals of this project's declared
+   *  previews (`urlEnv`), added to the task's env for names it lacks. */
+  previewEnv: Record<string, string>;
+  /** The exact grant the runner must hold before it publishes; null for a
+   *  task on the runner's own credentials, which has no per-task grant. */
+  grant: { manifestRevision: number; manifestDigest: string; targetGeneration: number } | null;
+}
+
+export type TaskProjectActivateResult =
+  | { outcome: "ready" | "ready_with_warning"; warning: string | null }
+  | { outcome: "refused"; reason: TaskProjectRefusal; message: string }
+  /** The intent was recorded but the disk proves neither outcome. */
+  | { outcome: "uncertain"; message: string };
+
+export type TaskProjectCompensateInput = TaskProjectOpFence;
+
+export type TaskProjectCompensateResult =
+  | { outcome: "compensated" }
+  | { outcome: "refused"; reason: TaskProjectRefusal | "uncertain"; message: string };
+
+export interface TaskProjectStatusInput {
+  taskId: string;
+  runEpoch: number;
+  operationId: string;
+  projectId: string;
+}
+
+/** The runner's journal for one operation, with any activation intent
+ *  resolved from the disk first. */
+export type TaskProjectMilestone =
+  | "none"
+  | "prepared"
+  | "not_published"
+  | "published"
+  | "uncertain"
+  | "ready"
+  | "ready_with_warning"
+  | "compensated";
+
+export interface TaskProjectStatusResult {
+  milestone: TaskProjectMilestone;
+  warning: string | null;
+  /** The grant this run holds right now (cloud credentials only). */
+  installedGrant: { runEpoch: number; manifestRevision: number; manifestDigest: string } | null;
+  /** Whether the task's env can serve `projectId` now: the open grant's
+   *  replica names it, or the runner serves its own store. */
+  envServes: boolean;
+  /** The projects the run's env serves right now (cloud credentials: the
+   *  open grant's, once its replica can serve them all); null otherwise. */
+  servedProjectIds: string[] | null;
+  credentials: "cloud" | "own";
+}
+
 /** A human in the task chat (ADR-049) — owner or invited collaborator. */
 export interface ChannelHuman {
   /** Per-task mention handle (`@diogo`), unique vs agent ids. */
@@ -4322,7 +4472,10 @@ export interface ChannelHuman {
   isOwner: boolean;
 }
 
+
 export interface ChannelEnsureInput {
+  /** Server-issued immutable lead context; old hosts leave measurements unknown. */
+  leadRunId?: string;
   taskId: string;
   agents: TaskAgent[];
   /** ADR-083: channel projection/routing mode. Optional for older clouds. */
@@ -4496,6 +4649,7 @@ export interface HostCommands {
      *  redeliveries are not messages a router would ever classify. Absent
      *  from an older cloud, which the host reads as "not a human turn". */
     origin?: DeliveryOrigin,
+    assignment?: AssignmentDelivery,
   ): Promise<HostCommandResult<void>>;
   channelResolvePermission(
     ctx: CommandContext,
@@ -4559,10 +4713,28 @@ export interface HostCommands {
   ): Promise<HostCommandResult<TaskDiffResult>>;
   // Chat attachments live in the task workspace on the host (ADR-015); the
   // cloud relays bytes (base64) in and out, never persisting them.
+  /** ADR-161 §2.3 (`live-task-projects-v1`). */
+  taskProjectPrepare(
+    ctx: CommandContext,
+    input: TaskProjectPrepareInput,
+  ): Promise<HostCommandResult<TaskProjectPrepareResult>>;
+  taskProjectActivate(
+    ctx: CommandContext,
+    input: TaskProjectActivateInput,
+  ): Promise<HostCommandResult<TaskProjectActivateResult>>;
+  taskProjectCompensate(
+    ctx: CommandContext,
+    input: TaskProjectCompensateInput,
+  ): Promise<HostCommandResult<TaskProjectCompensateResult>>;
+  taskProjectStatus(
+    ctx: CommandContext,
+    input: TaskProjectStatusInput,
+  ): Promise<HostCommandResult<TaskProjectStatusResult>>;
   attachmentWrite(
     ctx: CommandContext,
     input: { taskId: string; filename: string; dataBase64: string },
   ): Promise<HostCommandResult<void>>;
+  workspaceFileRead(ctx: CommandContext, input: { taskId: string; path: string; maxBytes: number }): Promise<HostCommandResult<{ dataBase64: string; size: number }>>;
   attachmentRead(
     ctx: CommandContext,
     input: { taskId: string; filename: string },
@@ -4745,6 +4917,7 @@ export type CloudToHost =
   | ProjectEnvReconcileBeginFrame
   | ProjectEnvReconciledFrame
   | ProjectEnvDeliverySkipFrame
+  | TaskSecretStagingPut
   | ProjectEnvStagingPutFrame
   | ProjectEnvLegacyTagFrame
   | ProjectEnvReplicaBeginFrame
@@ -4809,6 +4982,30 @@ export type CloudToHost =
   | SshMintFrame
   | GithubRevokeFrame;
 
+/** ADR-162: cloud-bound delivery identity, preserved by the runner journal. */
+export interface AssignmentDelivery {
+  assignmentId: string;
+  deliveryId: string;
+  runEpoch: number;
+  recipientGeneration: string | null;
+}
+export interface AssignmentTurnEvidence {
+  leadRunId?: string | null;
+  turnId: string;
+  assignmentId: string | null;
+  deliveryId: string | null;
+  sessionId: string;
+  runEpoch: number;
+  recipientGeneration: string | null;
+  correlation: "explicit" | "followup" | "ambiguous" | "unknown";
+  acceptedAt: number;
+  endedAt?: number;
+  engine: string;
+  runtimeVersion: string | null;
+  // A configured model/effort isn't an observation. Actual model comes from
+  // provider usage; unreported effort, CLI version and duration remain null.
+}
+
 /** ADR-141: provenance of a channelDeliver. */
 export type DeliveryOrigin = "human" | "agent" | "system";
 
@@ -4987,6 +5184,8 @@ export type HostToCloud =
   | ProjectEnvAckFrame
   | ProjectEnvReconcileAckFrame
   | ProjectEnvDeliveryAckFrame
+  | TaskSecretApplied
+  | TaskSecretStagingAck
   | ProjectEnvStagingAckFrame
   | ProjectEnvLegacyTagAckFrame
   | ProjectEnvReplicaAckFrame
@@ -5036,12 +5235,14 @@ export type HostEvent =
     }
   | {
       kind: "agent.message_delta";
+      evidence?: AssignmentTurnEvidence;
       taskId: string;
       agentId: string;
       chunk: string;
     }
   | {
       kind: "agent.message_complete";
+      evidence?: AssignmentTurnEvidence;
       taskId: string;
       agentId: string;
       fullText: string;
@@ -5055,6 +5256,7 @@ export type HostEvent =
   // of delivering it.
   | {
       kind: "agent.turn_complete";
+      evidence?: AssignmentTurnEvidence;
       taskId: string;
       agentId: string;
       aborted?: boolean;

package/src/task-env-names.ts

@@ -0,0 +1,28 @@
+import { ENGINE_ENV_CREDENTIAL_KEYS } from "./cloud-credentials";
+
+const RESERVED_TASK_ENV_EXACT = new Set([
+  "GH_TOKEN", "GITHUB_TOKEN", "GH_CONFIG_DIR", "GH_HOST",
+  "GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_OBJECT_DIRECTORY",
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_INDEX_FILE", "GIT_EXEC_PATH",
+  "GIT_ASKPASS", "SSH_ASKPASS", "GIT_SSH", "GIT_SSH_COMMAND",
+  "HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME",
+  "PATH", "LD_PRELOAD", "LD_AUDIT", "LD_LIBRARY_PATH", "NODE_OPTIONS",
+  "NODE_PATH", "SHELL", "SHELLOPTS", "BASHOPTS", "PS4", "BASH_ENV", "ENV",
+  "NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "REQUESTS_CA_BUNDLE",
+  "__CURSOR_SANDBOX_ENV_RESTORE", "GROK_LOGIN_ENV",
+  // Every name an env-token engine's account may set (ADR-154's contract):
+  // a project value never stands in for an engine's credential.
+  ...Object.values(ENGINE_ENV_CREDENTIAL_KEYS).flat(),
+  "PLAYWRIGHT_BROWSERS_PATH",
+]);
+const RESERVED_TASK_ENV_NPM = /^npm_config_(prefix|cache|logs[_-]dir|umask)$/i;
+/** Toolchain prefixes, in any case, as task-up.sh matches them. */
+const RESERVED_TASK_ENV_TOOLCHAIN = /^(asdf|corepack)_/i;
+
+export function isReservedTaskEnvName(name: string): boolean {
+  if (RESERVED_TASK_ENV_EXACT.has(name)) return true;
+  if (name.startsWith("GIT_CONFIG") || RESERVED_TASK_ENV_TOOLCHAIN.test(name)) return true;
+  if (name.startsWith("UAI_")) return true;
+  if (name.startsWith("__UAI_ENV_")) return true;
+  return RESERVED_TASK_ENV_NPM.test(name);
+}

package/src/task-secrets.ts

@@ -0,0 +1,75 @@
+/** ADR-161 §5: value-free task-secret wire contract. No I/O. */
+export const TASK_SECRETS_FEATURE = "task-secrets-v1";
+export const MAX_TASK_SECRETS = 20;
+export const TASK_SECRET_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+export const TASK_SECRET_STAGING_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export interface TaskSecretManifestEntry {
+  credentialId: string;
+  name: string;
+  stagingId: string;
+  generation: number;
+  parameter: string;
+  version: number;
+  mode: "proxied" | "delivered";
+  domains: string[];
+  placeholder: { prefix: string; totalLength: number } | null;
+  sessionId: string;
+}
+export interface TaskSecretStagingPut {
+  kind: "task.secret.staging.put";
+  opId: string;
+  orgId: string;
+  taskId: string;
+  name: string;
+  stagingId: string;
+  value: string;
+}
+export interface TaskSecretStagingAck {
+  kind: "task.secret.staging.ack";
+  opId: string;
+  stagingId: string;
+  ok: boolean;
+}
+const ID = /^[A-Za-z0-9_-]{1,128}$/;
+export function isTaskSecretStagingPut(value: unknown): value is TaskSecretStagingPut {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const o = value as Record<string, unknown>;
+  return Object.keys(o).length === 7 && o.kind === "task.secret.staging.put" &&
+    [o.opId, o.orgId, o.taskId].every(v => typeof v === "string" && ID.test(v)) &&
+    typeof o.name === "string" && TASK_SECRET_NAME.test(o.name) &&
+    typeof o.stagingId === "string" && TASK_SECRET_STAGING_ID.test(o.stagingId) &&
+    typeof o.value === "string" && o.value.length > 0 && !o.value.includes("\0") &&
+    new TextEncoder().encode(JSON.stringify({ v: 1, kind: "task-secret", orgId: o.orgId, taskId: o.taskId, name: o.name, stagingId: o.stagingId, value: o.value })).byteLength <= 4096;
+}
+export function isTaskSecretStagingAck(value: unknown): value is TaskSecretStagingAck {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const o = value as Record<string, unknown>;
+  return Object.keys(o).length === 4 && o.kind === "task.secret.staging.ack" && typeof o.opId === "string" && ID.test(o.opId) &&
+    typeof o.stagingId === "string" && TASK_SECRET_STAGING_ID.test(o.stagingId) && typeof o.ok === "boolean";
+}
+export interface TaskSecretMaterial {
+  class: "task-secret";
+  location: { orgId: string; taskId: string; name: string; stagingId: string };
+  value: string;
+}
+/** Compare every envelope identity; no provider text is included in errors. */
+export function parseTaskSecretMaterial(raw: string, expected: TaskSecretMaterial["location"]): TaskSecretMaterial | null {
+  try {
+    if (new TextEncoder().encode(raw).byteLength > 4096) return null;
+    const o = JSON.parse(raw) as Record<string, unknown>;
+    if (!o || Object.keys(o).length !== 7 || o.v !== 1 || o.kind !== "task-secret" ||
+      o.orgId !== expected.orgId || o.taskId !== expected.taskId || o.name !== expected.name || o.stagingId !== expected.stagingId ||
+      typeof o.value !== "string" || !o.value.length || o.value.includes("\0")) return null;
+    return { class: "task-secret", location: { ...expected }, value: o.value };
+  } catch { return null; }
+}
+
+/** Sent only after the lease's consumers have opened on the exact new view. */
+export interface TaskSecretApplied { kind: "task.secret.applied"; taskId: string; runEpoch: number; manifestRevision: number; manifestDigest: string }
+export function isTaskSecretApplied(value: unknown): value is TaskSecretApplied {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const o = value as Record<string, unknown>;
+  return Object.keys(o).length === 5 && o.kind === "task.secret.applied" && typeof o.taskId === "string" && ID.test(o.taskId) &&
+    typeof o.runEpoch === "number" && Number.isSafeInteger(o.runEpoch) && o.runEpoch > 0 &&
+    typeof o.manifestRevision === "number" && Number.isSafeInteger(o.manifestRevision) && o.manifestRevision > 0 && typeof o.manifestDigest === "string" && /^[0-9a-f]{64}$/.test(o.manifestDigest);
+}

package/src/workspace-path-policy.ts

@@ -0,0 +1,41 @@
+import { ENGINE_ACCOUNT_PATH_RULES } from "./engine-account-paths";
+export { ENGINE_ACCOUNT_PATH_RULES } from "./engine-account-paths";
+/** Shared by cloud validation and runner reads. Check normalized and lexical
+ * components: normalization must never erase a traversal through credentials. */
+export function normalizedWorkspacePath(input: string): string {
+  if (!input.startsWith("/workspace/") || /[\x00-\x1f\x7f\\]/.test(input)) throw new Error("Use an absolute path under /workspace.");
+  const parts: string[] = [];
+  for (const part of input.split("/").slice(2)) {
+    if (!part || part === ".") continue;
+    if (part === "..") { if (!parts.length) throw new Error("Path escapes /workspace."); parts.pop(); }
+    else parts.push(part);
+  }
+  if (!parts.length) throw new Error("Choose a file under /workspace.");
+  return `/workspace/${parts.join("/")}`;
+}
+export function assertShareablePath(input: string): string { return validateShareablePath(input, ENGINE_ACCOUNT_PATH_RULES); }
+/** Kept self-contained for embedding together with its data in the agent CLI. */
+export function validateShareablePath(input: string, engineRules: ReadonlyArray<{ components: readonly string[]; prefix: boolean }>): string {
+  if (/[\x00-\x1f\x7f\\]/.test(input)) throw new Error("This path cannot be shared.");
+  if (!input.startsWith("/")) throw new Error("Use an absolute file path.");
+  const lexical = input.split("/").filter(Boolean);
+  const parts: string[] = [];
+  for (const part of lexical) {
+    if (part === "..") parts.pop(); else if (part !== ".") parts.push(part);
+    // Refuse entering these roots even when later '..' components erase them.
+    if (engineRules.some((rule) => parts.some((_, i) => rule.components.every((component, offset) => offset === rule.components.length - 1 && rule.prefix ? (parts[i + offset] ?? "").startsWith(component) : parts[i + offset] === component)))) throw new Error("Credential and Uai internal paths cannot be shared.");
+    if (["proc", "sys"].includes(parts[0] ?? "") || (parts[0] === "run" && ((parts[1] ?? "").startsWith("uai") || parts[1] === "secrets"))) throw new Error("Credential and Uai internal paths cannot be shared.");
+  }
+  const normalized = `/${parts.join("/")}`;
+  // Keep this function self-contained: its source is embedded into the
+  // dependency-free CLI. Inline callbacks need no compiler name helpers.
+  for (const components of [lexical, parts]) {
+    if (components.some((part, i) =>
+      (part === ".env" || (part.startsWith(".env.") && ![".env.example", ".env.schema"].includes(part))) ||
+      part.startsWith(".codex") ||
+      [".git", ".claude", ".ssh", ".grok", ".cursor", ".opencode", ".claude.json", ".git-credentials", ".netrc", ".npmrc", ".pypirc", ".aws", ".docker", ".kube", ".gnupg"].includes(part) ||
+      (part === ".config" && components[i + 1] === "gh") ||
+      (part === ".uai" && components[i + 1] !== "attachments"))) throw new Error("Credential and Uai internal paths cannot be shared.");
+  }
+  return normalized;
+}