@aiden-ade/sandbox-agent 0.1.67 → 0.1.68

package/dist/index.cjs

@@ -22087,7 +22087,7 @@ function describeError(error2) {
 }
 
 // src/version.ts
-var AGENT_VERSION = "0.1.67";
+var AGENT_VERSION = "0.1.68";
 
 // src/daemon-worktree.ts
 var import_node_child_process3 = require("child_process");
@@ -43094,11 +43094,11 @@ var SocketWithoutUpgrade = class _SocketWithoutUpgrade extends Emitter {
    */
   _resetPingTimeout() {
     this.clearTimeoutFn(this._pingTimeoutTimer);
-    const delay2 = this._pingInterval + this._pingTimeout;
-    this._pingTimeoutTime = Date.now() + delay2;
+    const delay3 = this._pingInterval + this._pingTimeout;
+    this._pingTimeoutTime = Date.now() + delay3;
     this._pingTimeoutTimer = this.setTimeoutFn(() => {
       this._onClose("ping timeout");
-    }, delay2);
+    }, delay3);
     if (this.opts.autoUnref) {
       this._pingTimeoutTimer.unref();
     }
@@ -45079,8 +45079,8 @@ var Manager = class extends Emitter {
       this.emitReserved("reconnect_failed");
       this._reconnecting = false;
     } else {
-      const delay2 = this.backoff.duration();
-      debug10("will wait %dms before reconnect attempt", delay2);
+      const delay3 = this.backoff.duration();
+      debug10("will wait %dms before reconnect attempt", delay3);
       this._reconnecting = true;
       const timer = this.setTimeoutFn(() => {
         if (self.skipReconnect)
@@ -45100,7 +45100,7 @@ var Manager = class extends Emitter {
             self.onreconnect();
           }
         });
-      }, delay2);
+      }, delay3);
       if (this.opts.autoUnref) {
         timer.unref();
       }
@@ -61929,13 +61929,13 @@ var StreamableHTTPClientTransport = class {
       this.onerror?.(new Error(`Maximum reconnection attempts (${maxRetries}) exceeded.`));
       return;
     }
-    const delay2 = this._getNextReconnectionDelay(attemptCount);
+    const delay3 = this._getNextReconnectionDelay(attemptCount);
     this._reconnectionTimeout = setTimeout(() => {
       this._startOrAuthSse(options).catch((error2) => {
         this.onerror?.(new Error(`Failed to reconnect SSE stream: ${error2 instanceof Error ? error2.message : String(error2)}`));
         this._scheduleReconnection(options, attemptCount + 1);
       });
-    }, delay2);
+    }, delay3);
   }
   _handleSseStream(stream, options, isReconnectable) {
     if (!stream) {
@@ -64748,38 +64748,96 @@ var publishSkillInputSchema = defineWireSchema()(external_exports.object({
   expectedContentHash: sha256Schema,
   uploadGrant: runtimeUploadGrantSchema
 }));
-var boundedMetadataSchema = external_exports.record(external_exports.string().max(1024)).default({}).superRefine((value2, context) => {
-  const entries = Object.entries(value2);
-  if (entries.length > 64) {
-    context.addIssue({
-      code: external_exports.ZodIssueCode.custom,
-      message: "metadata has more than 64 entries"
-    });
-  }
-  for (const [key] of entries) {
-    if (new TextEncoder().encode(key).byteLength > 128) {
-      context.addIssue({
-        code: external_exports.ZodIssueCode.custom,
-        message: `metadata key exceeds 128 UTF-8 bytes: ${key.slice(0, 32)}`
-      });
+var skillFrontmatterAdmissionSchema = external_exports.object({
+  name: external_exports.string().min(1).max(64).regex(SKILL_NAME_PATTERN),
+  description: external_exports.string().trim().min(1).max(1024)
+}).passthrough();
+var PROJECTED_VALUE_MAX_BYTES = 16384;
+function formatKeys(keys) {
+  const shown = keys.slice(0, 3).map((key) => `metadata.${key}`);
+  const remaining = keys.length - shown.length;
+  const listed = shown.join(", ");
+  return remaining > 0 ? `${listed} and ${remaining} more` : listed;
+}
+function unsupported(message) {
+  return { severity: "warning", code: "UNSUPPORTED_FRONTMATTER", message, path: "SKILL.md" };
+}
+function projectSkillFrontmatter(admitted) {
+  const conformance = [];
+  const raw = admitted;
+  const optionalText = (key, max) => {
+    const value2 = raw[key];
+    if (value2 === void 0)
+      return void 0;
+    if (typeof value2 !== "string") {
+      conformance.push(unsupported(`${key} is not a string; the Agent Skills spec expects text`));
+      return void 0;
+    }
+    const trimmed = value2.trim();
+    if (!trimmed)
+      return void 0;
+    if (trimmed.length > max) {
+      conformance.push(unsupported(`${key} exceeds ${max} characters and was not indexed`));
+      return void 0;
+    }
+    return trimmed;
+  };
+  const license = optionalText("license", 1024);
+  const compatibility = optionalText("compatibility", 500);
+  const allowedTools = optionalText("allowed-tools", 1024);
+  const metadata = {};
+  const rawMetadata = raw.metadata;
+  if (rawMetadata !== void 0) {
+    if (typeof rawMetadata !== "object" || rawMetadata === null || Array.isArray(rawMetadata)) {
+      conformance.push(unsupported("metadata is not a mapping and was not indexed"));
+    } else {
+      const encoder = new TextEncoder();
+      const notStrings = [];
+      const selfReferential = [];
+      const tooLarge = [];
+      for (const [key, value2] of Object.entries(rawMetadata)) {
+        if (typeof value2 !== "string")
+          notStrings.push(key);
+        let encoded;
+        if (typeof value2 === "string") {
+          encoded = value2;
+        } else {
+          try {
+            encoded = JSON.stringify(value2) ?? "";
+          } catch {
+            selfReferential.push(key);
+            continue;
+          }
+        }
+        if (encoder.encode(encoded).byteLength > PROJECTED_VALUE_MAX_BYTES) {
+          tooLarge.push(key);
+          continue;
+        }
+        metadata[key] = value2;
+      }
+      if (notStrings.length > 0) {
+        conformance.push(unsupported(`${formatKeys(notStrings)} ${notStrings.length === 1 ? "is" : "are"} not ${notStrings.length === 1 ? "a string" : "strings"}; the Agent Skills spec expects text`));
+      }
+      if (selfReferential.length > 0) {
+        conformance.push(unsupported(`${formatKeys(selfReferential)} ${selfReferential.length === 1 ? "refers" : "refer"} to itself and ${selfReferential.length === 1 ? "was" : "were"} not indexed`));
+      }
+      if (tooLarge.length > 0) {
+        conformance.push(unsupported(`${formatKeys(tooLarge)} ${tooLarge.length === 1 ? "is" : "are"} too large to index`));
+      }
     }
   }
-});
-var skillFrontmatterSchema = external_exports.object({
-  name: external_exports.string().min(1).max(64).regex(SKILL_NAME_PATTERN),
-  description: external_exports.string().trim().min(1).max(1024),
-  license: external_exports.string().trim().min(1).max(1024).optional(),
-  compatibility: external_exports.string().trim().min(1).max(500).optional(),
-  metadata: boundedMetadataSchema,
-  "allowed-tools": external_exports.string().trim().min(1).max(1024).optional()
-}).passthrough().transform((value2) => ({
-  name: value2.name,
-  description: value2.description,
-  ...value2.license ? { license: value2.license } : {},
-  ...value2.compatibility ? { compatibility: value2.compatibility } : {},
-  metadata: value2.metadata,
-  ...value2["allowed-tools"] ? { allowedTools: value2["allowed-tools"] } : {}
-}));
+  return {
+    metadata: {
+      name: admitted.name,
+      description: admitted.description,
+      ...license ? { license } : {},
+      ...compatibility ? { compatibility } : {},
+      metadata,
+      ...allowedTools ? { allowedTools } : {}
+    },
+    conformance
+  };
+}
 var skillPackageDiagnosticSchema = external_exports.object({
   severity: external_exports.literal("warning"),
   code: external_exports.enum(["BROKEN_REFERENCE", "UNSUPPORTED_FRONTMATTER"]),
@@ -65052,7 +65110,10 @@ async function inspectSkillPackage(packageRoot, options = {}) {
   inspectedFiles.sort(comparePackageFiles);
   const parsedMetadata = parseSkillMetadata(inspectedFiles.find((file2) => file2.manifest.path === "SKILL.md")?.bytes, options.expectedName === void 0 ? (0, import_node_path15.basename)(root) : options.expectedName);
   const manifestFiles = inspectedFiles.map((file2) => file2.manifest);
-  const diagnostics = collectDiagnostics(inspectedFiles.find((file2) => file2.manifest.path === "SKILL.md")?.bytes, parsedMetadata.metadata.license, new Set(manifestFiles.map((file2) => file2.path)));
+  const diagnostics = [
+    ...parsedMetadata.conformance,
+    ...collectDiagnostics(inspectedFiles.find((file2) => file2.manifest.path === "SKILL.md")?.bytes, parsedMetadata.metadata.license, new Set(manifestFiles.map((file2) => file2.path)))
+  ];
   return {
     schemaVersion: 1,
     entrypoint: "SKILL.md",
@@ -65294,14 +65355,14 @@ function parseSkillMetadata(bytes, expectedName) {
   if (!isRecord2(parsed)) {
     throw new SkillPackageError("INVALID_FRONTMATTER", "SKILL.md frontmatter must be a YAML mapping", "SKILL.md");
   }
-  const result = skillFrontmatterSchema.safeParse(parsed);
-  if (!result.success) {
-    throw new SkillPackageError("INVALID_FRONTMATTER", `SKILL.md frontmatter is invalid: ${result.error.issues.map(formatFrontmatterIssue).join("; ")}`, "SKILL.md");
+  const admitted = skillFrontmatterAdmissionSchema.safeParse(parsed);
+  if (!admitted.success) {
+    throw new SkillPackageError("INVALID_FRONTMATTER", `SKILL.md frontmatter is invalid: ${admitted.error.issues.map(formatFrontmatterIssue).join("; ")}`, "SKILL.md");
   }
-  if (expectedName !== null && result.data.name !== expectedName.normalize("NFC")) {
-    throw new SkillPackageError("DIRECTORY_NAME_MISMATCH", `Skill name ${result.data.name} must match its directory ${expectedName}`, "SKILL.md");
+  if (expectedName !== null && admitted.data.name !== expectedName.normalize("NFC")) {
+    throw new SkillPackageError("DIRECTORY_NAME_MISMATCH", `Skill name ${admitted.data.name} must match its directory ${expectedName}`, "SKILL.md");
   }
-  return { metadata: result.data };
+  return projectSkillFrontmatter(admitted.data);
 }
 function formatFrontmatterIssue(issue2) {
   const field = issue2.path.map(String).join(".");
@@ -68694,6 +68755,332 @@ function decodeResumeFallbackContext(encoded) {
 // src/sandbox.ts
 var import_node_os12 = require("os");
 
+// src/execution-activity-tracker.ts
+var ExecutionActivityTracker = class {
+  constructor(onChange) {
+    this.onChange = onChange;
+  }
+  activities = /* @__PURE__ */ new Map();
+  register(input) {
+    const normalized = normalizeRegistration(input);
+    const existing = this.activities.get(normalized.ownerId);
+    if (existing) {
+      if (!sameRegistration(existing.input, normalized)) {
+        throw new Error(`Execution activity owner ${normalized.ownerId} changed identity`);
+      }
+      existing.refCount += 1;
+    } else {
+      const activeLease = this.firstActivity()?.input.leaseRunId;
+      if (activeLease && activeLease !== normalized.leaseRunId) {
+        throw new Error(
+          `Cannot track execution leases ${activeLease} and ${normalized.leaseRunId} concurrently`
+        );
+      }
+      this.activities.set(normalized.ownerId, { input: normalized, refCount: 1 });
+    }
+    this.emitChange();
+    let released = false;
+    return {
+      release: () => {
+        if (released) return;
+        released = true;
+        const tracked = this.activities.get(normalized.ownerId);
+        if (!tracked) return;
+        tracked.refCount -= 1;
+        if (tracked.refCount <= 0) this.activities.delete(normalized.ownerId);
+        this.emitChange();
+      }
+    };
+  }
+  snapshot() {
+    const first = this.firstActivity();
+    if (!first) return null;
+    const activeRunIds = /* @__PURE__ */ new Set([first.input.leaseRunId]);
+    let trackedChildCount = 0;
+    let trackedWorkCount = 0;
+    let childAlive = false;
+    let phase;
+    for (const { input, refCount } of this.activities.values()) {
+      activeRunIds.add(input.activeRunId ?? input.leaseRunId);
+      trackedWorkCount += refCount;
+      if (input.kind === "child") trackedChildCount += refCount;
+      childAlive ||= input.childAlive === true;
+      phase ??= input.phase;
+    }
+    return {
+      runId: first.input.leaseRunId,
+      conversationId: first.input.conversationId,
+      taskId: first.input.taskId,
+      sandboxId: first.input.sandboxId,
+      activeRunIds: [...activeRunIds].sort(),
+      phase,
+      childAlive,
+      trackedChildCount,
+      trackedWorkCount
+    };
+  }
+  firstActivity() {
+    return this.activities.values().next().value;
+  }
+  emitChange() {
+    this.onChange(this.snapshot());
+  }
+};
+function normalizeRegistration(input) {
+  const ownerId = input.ownerId.trim();
+  const leaseRunId = input.leaseRunId.trim();
+  const activeRunId = input.activeRunId?.trim() || void 0;
+  const conversationId = input.conversationId.trim();
+  const taskId = input.taskId.trim();
+  const sandboxId = input.sandboxId.trim();
+  if (!ownerId || !leaseRunId || !conversationId || !taskId || !sandboxId) {
+    throw new Error("Execution activity identity fields must be non-empty");
+  }
+  return {
+    ...input,
+    ownerId,
+    leaseRunId,
+    activeRunId,
+    conversationId,
+    taskId,
+    sandboxId
+  };
+}
+function sameRegistration(left, right) {
+  return left.ownerId === right.ownerId && left.leaseRunId === right.leaseRunId && left.activeRunId === right.activeRunId && left.conversationId === right.conversationId && left.taskId === right.taskId && left.sandboxId === right.sandboxId && left.kind === right.kind;
+}
+
+// src/execution-lease-client.ts
+var EXECUTION_LEASE_RENEW_INTERVAL_MS = 3e4;
+var EXECUTION_LEASE_REQUEST_TIMEOUT_MS = 1e4;
+var DEFAULT_RETRY_DELAYS_MS = [250, 1e3];
+var ExecutionLeaseClient = class {
+  constructor(options) {
+    this.options = options;
+    this.apiUrl = options.apiUrl.replace(/\/+$/, "");
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    this.renewIntervalMs = options.renewIntervalMs ?? EXECUTION_LEASE_RENEW_INTERVAL_MS;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? EXECUTION_LEASE_REQUEST_TIMEOUT_MS;
+    this.retryDelaysMs = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+    this.enabled = options.enabled !== false;
+  }
+  apiUrl;
+  fetchImpl;
+  renewIntervalMs;
+  requestTimeoutMs;
+  retryDelaysMs;
+  activity = null;
+  activityGeneration = 0;
+  interval = null;
+  inFlight = null;
+  trailingRenewal = false;
+  nextSequence = 1;
+  enabled;
+  closed = false;
+  terminalSessionFailure = false;
+  terminalRunIds = /* @__PURE__ */ new Set();
+  setActivity(activity) {
+    if (this.closed || this.terminalSessionFailure) return;
+    const previousRunId = this.activity?.runId ?? null;
+    const nextRunId = activity?.runId ?? null;
+    if (previousRunId !== nextRunId) this.activityGeneration += 1;
+    this.activity = activity;
+    if (!activity) {
+      this.stopInterval();
+      this.trailingRenewal = false;
+      this.options.lifecycle?.debug("sandbox_agent_execution_lease_stopped", {
+        reason: "idle"
+      });
+      return;
+    }
+    if (this.terminalRunIds.has(activity.runId)) {
+      this.stopInterval();
+      return;
+    }
+    if (!this.enabled) return;
+    this.startInterval();
+    if (previousRunId !== activity.runId || !this.inFlight) this.requestRenewal();
+    else this.trailingRenewal = true;
+  }
+  /** Enable renewals after the connected WS server proves route support. */
+  enable() {
+    if (this.enabled || this.closed || this.terminalSessionFailure) return;
+    this.enabled = true;
+    this.options.lifecycle?.info("sandbox_agent_execution_lease_enabled");
+    if (!this.activity || this.terminalRunIds.has(this.activity.runId)) return;
+    this.startInterval();
+    this.requestRenewal();
+  }
+  close() {
+    this.closed = true;
+    this.activityGeneration += 1;
+    this.activity = null;
+    this.trailingRenewal = false;
+    this.stopInterval();
+  }
+  startInterval() {
+    if (this.interval) return;
+    this.interval = setInterval(() => this.requestRenewal(), this.renewIntervalMs);
+    this.interval.unref?.();
+  }
+  stopInterval() {
+    if (!this.interval) return;
+    clearInterval(this.interval);
+    this.interval = null;
+  }
+  loseAuthority(activity, seq, status, code) {
+    this.terminalSessionFailure = true;
+    this.stopInterval();
+    this.options.lifecycle?.error("sandbox_agent_execution_lease_authority_lost", {
+      runId: activity.runId,
+      seq,
+      status,
+      code
+    });
+    this.options.onAuthorityLost?.({ runId: activity.runId, code, status });
+  }
+  requestRenewal() {
+    if (this.closed || !this.enabled || this.terminalSessionFailure || !this.activity || this.terminalRunIds.has(this.activity.runId)) {
+      return;
+    }
+    if (this.inFlight) {
+      this.trailingRenewal = true;
+      return;
+    }
+    const activity = this.activity;
+    const activityGeneration = this.activityGeneration;
+    const seq = this.nextSequence;
+    this.nextSequence += 1;
+    this.inFlight = this.renewWithRetry(activity, activityGeneration, seq).finally(() => {
+      this.inFlight = null;
+      if (!this.trailingRenewal) return;
+      this.trailingRenewal = false;
+      if (this.activity) this.requestRenewal();
+    });
+  }
+  isCurrentRun(activity, generation) {
+    return !this.closed && this.activityGeneration === generation && this.activity?.runId === activity.runId;
+  }
+  async renewWithRetry(activity, activityGeneration, seq) {
+    const body = {
+      conversationId: activity.conversationId,
+      taskId: activity.taskId,
+      sandboxId: activity.sandboxId,
+      agentSessionId: this.options.agentSessionId,
+      seq,
+      activeRunIds: activity.activeRunIds,
+      agentVersion: this.options.agentVersion,
+      phase: activity.phase,
+      childAlive: activity.childAlive,
+      trackedChildCount: activity.trackedChildCount
+    };
+    const url3 = `${this.apiUrl}/public/agent-runs/${encodeURIComponent(activity.runId)}/execution-lease`;
+    for (let attempt = 0; attempt <= this.retryDelaysMs.length; attempt += 1) {
+      if (!this.isCurrentRun(activity, activityGeneration)) return;
+      try {
+        const response = await this.fetchImpl(url3, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${this.options.sessionToken}`,
+            "content-type": "application/json"
+          },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(this.requestTimeoutMs)
+        });
+        if (response.ok) {
+          this.options.lifecycle?.debug("sandbox_agent_execution_lease_renewed", {
+            runId: activity.runId,
+            seq,
+            attempt: attempt + 1
+          });
+          return;
+        }
+        const errorBody = await readErrorBody(response);
+        const code = errorBody.code;
+        const sessionAuthorityLost = response.status === 409 && code === "EXECUTION_LEASE_FENCED" || response.status === 401 && code === "EXECUTION_LEASE_INVALID_TOKEN";
+        if (sessionAuthorityLost && code) {
+          this.loseAuthority(activity, seq, response.status, code);
+          return;
+        }
+        const runAuthorityLost = response.status === 409 && code === "EXECUTION_LEASE_INACTIVE_RUN" || response.status === 403 && code === "EXECUTION_LEASE_BINDING_MISMATCH" || response.status === 404 && code === "EXECUTION_LEASE_RUN_NOT_FOUND";
+        if (runAuthorityLost && code) {
+          if (!this.isCurrentRun(activity, activityGeneration)) {
+            this.options.lifecycle?.debug("sandbox_agent_execution_lease_stale_response_ignored", {
+              runId: activity.runId,
+              seq,
+              status: response.status,
+              code
+            });
+            return;
+          }
+          this.loseAuthority(activity, seq, response.status, code);
+          return;
+        }
+        if (response.status === 409 && code === "EXECUTION_LEASE_PROVIDER_UNRESOLVED") {
+          this.terminalRunIds.add(activity.runId);
+          if (this.activity?.runId === activity.runId) this.stopInterval();
+          this.options.lifecycle?.warn("sandbox_agent_execution_lease_run_rejected", {
+            runId: activity.runId,
+            seq,
+            code
+          });
+          return;
+        }
+        const takeoverPending = response.status === 409 && code === "EXECUTION_LEASE_TAKEOVER_PENDING";
+        const mixedVersionUnavailable = (response.status === 401 || response.status === 403 || response.status === 404) && !code?.startsWith("EXECUTION_LEASE_");
+        const retryable = takeoverPending || mixedVersionUnavailable || isRetryableStatus(response.status);
+        if (!retryable || attempt === this.retryDelaysMs.length) {
+          this.options.lifecycle?.warn("sandbox_agent_execution_lease_renew_failed", {
+            runId: activity.runId,
+            seq,
+            status: response.status,
+            code,
+            attempt: attempt + 1
+          });
+          return;
+        }
+        if (takeoverPending) {
+          this.options.lifecycle?.debug("sandbox_agent_execution_lease_takeover_pending", {
+            runId: activity.runId,
+            seq,
+            attempt: attempt + 1
+          });
+        }
+      } catch (error2) {
+        if (attempt === this.retryDelaysMs.length) {
+          this.options.lifecycle?.warn("sandbox_agent_execution_lease_renew_failed", {
+            runId: activity.runId,
+            seq,
+            attempt: attempt + 1,
+            error: error2 instanceof Error ? error2 : new Error(String(error2))
+          });
+          return;
+        }
+      }
+      await delay2(this.retryDelaysMs[attempt] ?? 0);
+    }
+  }
+};
+function isRetryableStatus(status) {
+  return status === 408 || status === 429 || status >= 500;
+}
+async function readErrorBody(response) {
+  try {
+    const body = await response.json();
+    if (!body || typeof body !== "object") return {};
+    const record2 = body;
+    return {
+      code: typeof record2.code === "string" ? record2.code : void 0,
+      message: typeof record2.message === "string" ? record2.message : void 0
+    };
+  } catch {
+    return {};
+  }
+}
+function delay2(ms) {
+  return new Promise((resolve14) => setTimeout(resolve14, ms));
+}
+
 // src/web-presenter.ts
 var import_node_crypto15 = require("crypto");
 var WebPresenter = class {
@@ -69086,6 +69473,21 @@ var SandboxEventDispatcher = class {
 
 // src/ws-client.ts
 var ACCEPTED_MESSAGE_ID_CACHE_SIZE = 200;
+var SUPERVISED_RECONNECT_BASE_DELAY_MS = 1e3;
+var SUPERVISED_RECONNECT_MAX_DELAY_MS = 5e3;
+var SUPERVISED_RECONNECT_MAX_JITTER_MS = 500;
+function parseConnectionDirective(data) {
+  if (typeof data !== "object" || data === null || typeof data.code !== "string" || typeof data.retryable !== "boolean") {
+    return null;
+  }
+  const candidate = data;
+  return {
+    code: candidate.code,
+    retryable: candidate.retryable,
+    reason: typeof candidate.reason === "string" ? candidate.reason : void 0,
+    retryAfterMs: typeof candidate.retryAfterMs === "number" && Number.isFinite(candidate.retryAfterMs) && candidate.retryAfterMs >= 0 ? candidate.retryAfterMs : void 0
+  };
+}
 var WSClient = class {
   constructor(wsUrl, sessionId, taskId, token, callbacks, agentVersion, lifecycle) {
     this.lifecycle = lifecycle;
@@ -69094,7 +69496,7 @@ var WSClient = class {
     this.getRunState = callbacks.getRunState;
     this.socket = lookup(wsUrl, {
       query: { type: "agent", sessionId, taskId, agentVersion: agentVersion ?? "" },
-      auth: { token },
+      auth: { token, agentSessionId: this.agentSessionId },
       transports: ["websocket"],
       reconnection: true,
       reconnectionAttempts: Infinity,
@@ -69126,6 +69528,10 @@ var WSClient = class {
   /** Monotonic heartbeat sequence — advances on every hello + heartbeat. */
   heartbeatSeq = 0;
   heartbeatTimer = null;
+  supervisedReconnectTimer = null;
+  supervisedReconnectAttempt = 0;
+  connectionDirective = null;
+  intentionalClose = false;
   agentVersion;
   getRunState;
   /**
@@ -69232,16 +69638,82 @@ var WSClient = class {
   get connected() {
     return this.socket.connected;
   }
+  getAgentSessionId() {
+    return this.agentSessionId;
+  }
   setLifecycleContext(context) {
     this.lifecycle?.setContext(context);
   }
   close() {
     this.lifecycle?.info("sandbox_agent_ws_close_requested");
+    this.intentionalClose = true;
+    this.clearSupervisedReconnect();
     this.stopHeartbeat();
     this.socket.disconnect();
   }
+  clearSupervisedReconnect() {
+    if (this.supervisedReconnectTimer) {
+      clearTimeout(this.supervisedReconnectTimer);
+      this.supervisedReconnectTimer = null;
+    }
+  }
+  /**
+   * Socket.IO reconnects transport failures through its Manager. It does not
+   * reconnect an `io server disconnect`, where `socket.active` is false. Only
+   * supervise that terminal transport state, and only after the server has
+   * explicitly classified the disconnect as retryable (including the legacy
+   * `server_shutdown` advisory emitted by older WS servers).
+   */
+  scheduleSupervisedReconnect(reason) {
+    if (this.intentionalClose || this.socket.connected || this.socket.active || this.supervisedReconnectTimer || this.connectionDirective?.retryable !== true) {
+      return;
+    }
+    const attempt = this.supervisedReconnectAttempt + 1;
+    this.supervisedReconnectAttempt = attempt;
+    const exponentialDelay = Math.min(
+      SUPERVISED_RECONNECT_BASE_DELAY_MS * 2 ** (attempt - 1),
+      SUPERVISED_RECONNECT_MAX_DELAY_MS
+    );
+    const requestedDelay = Math.max(exponentialDelay, this.connectionDirective.retryAfterMs ?? 0);
+    const jitterRange = Math.min(SUPERVISED_RECONNECT_MAX_JITTER_MS, requestedDelay / 2);
+    const delayMs = requestedDelay + Math.floor(Math.random() * jitterRange);
+    this.lifecycle?.warn("sandbox_agent_ws_supervised_reconnect_scheduled", {
+      reason,
+      directiveCode: this.connectionDirective.code,
+      attempt,
+      delayMs
+    });
+    this.supervisedReconnectTimer = setTimeout(() => {
+      this.supervisedReconnectTimer = null;
+      if (this.intentionalClose || this.socket.connected || this.socket.active) return;
+      this.lifecycle?.info("sandbox_agent_ws_supervised_reconnect_attempt", {
+        directiveCode: this.connectionDirective?.code,
+        attempt
+      });
+      this.connectionDirective = null;
+      this.socket.connect();
+    }, delayMs);
+    this.supervisedReconnectTimer.unref?.();
+  }
   setupListeners(callbacks) {
+    this.socket.io.on("reconnect_attempt", (attempt) => {
+      this.lifecycle?.info("sandbox_agent_ws_manager_reconnect_attempt", { attempt });
+    });
+    this.socket.io.on("reconnect", (attempt) => {
+      this.lifecycle?.info("sandbox_agent_ws_manager_reconnected", { attempt });
+    });
+    this.socket.io.on("reconnect_error", (error2) => {
+      this.lifecycle?.warn("sandbox_agent_ws_manager_reconnect_error", {
+        error: error2 instanceof Error ? error2 : new Error(String(error2))
+      });
+    });
+    this.socket.io.on("reconnect_failed", () => {
+      this.lifecycle?.error("sandbox_agent_ws_manager_reconnect_failed");
+    });
     this.socket.on("connect", () => {
+      this.clearSupervisedReconnect();
+      this.supervisedReconnectAttempt = 0;
+      this.connectionDirective = null;
       this.lifecycle?.info("sandbox_agent_ws_socket_connected", { socketId: this.socket.id });
       this.startHeartbeat();
       this.eventDispatcher.flush();
@@ -69252,6 +69724,36 @@ var WSClient = class {
       this.stopHeartbeat();
       this.eventDispatcher.disconnect();
       callbacks.onDisconnect?.(reason);
+      this.scheduleSupervisedReconnect(reason);
+    });
+    this.socket.on("server_shutdown", (data) => {
+      this.connectionDirective = {
+        code: "server_shutdown",
+        reason: data?.reason,
+        retryable: true,
+        retryAfterMs: data?.retryAfterMs ?? 1e3
+      };
+    });
+    this.socket.on("agent.capabilities", (data) => {
+      if (typeof data !== "object" || data === null || typeof data.executionLeaseV1 !== "boolean") {
+        return;
+      }
+      const capabilities = {
+        executionLeaseV1: data.executionLeaseV1
+      };
+      this.lifecycle?.info("sandbox_agent_ws_capabilities_received", {
+        executionLeaseV1: capabilities.executionLeaseV1
+      });
+      callbacks.onCapabilities?.(capabilities);
+    });
+    this.socket.on("connection_directive", (data) => {
+      const directive = parseConnectionDirective(data);
+      if (!directive) return;
+      this.connectionDirective = directive;
+      if (!directive.retryable) {
+        this.clearSupervisedReconnect();
+        callbacks.onTerminalDirective?.({ code: directive.code, reason: directive.reason });
+      }
     });
     this.socket.on("agent.probe", (_data, ack) => {
       ack?.({
@@ -69261,9 +69763,24 @@ var WSClient = class {
       });
     });
     this.socket.on("connect_error", (error2) => {
+      const directive = parseConnectionDirective(
+        error2?.data
+      );
+      if (directive) {
+        this.connectionDirective = directive;
+        if (!directive.retryable) {
+          this.clearSupervisedReconnect();
+          callbacks.onTerminalDirective?.({ code: directive.code, reason: directive.reason });
+        }
+      } else {
+        this.connectionDirective = null;
+      }
       this.lifecycle?.warn("sandbox_agent_ws_socket_connect_error", {
-        error: error2 instanceof Error ? error2 : new Error(String(error2))
+        error: error2 instanceof Error ? error2 : new Error(String(error2)),
+        directiveCode: directive?.code,
+        retryable: directive?.retryable
       });
+      this.scheduleSupervisedReconnect("connect_error");
     });
     this.socket.on(
       "user_message",
@@ -69367,10 +69884,14 @@ async function runSandbox(config2) {
   let currentImages = [];
   let currentFiles = [];
   let currentParsedAttachments = [];
-  const stopped = false;
+  let stopped = false;
   let pendingMessageResolve = null;
   const queuedMessages = [];
   let currentAgent = null;
+  let executionLeaseClient = null;
+  let executionLeaseV1Supported = false;
+  let activeRootExecutionActivity = null;
+  let reportActiveRun = false;
   let currentTaskMeta;
   let currentPrMeta;
   let currentWorkflowTools;
@@ -69398,6 +69919,32 @@ async function runSandbox(config2) {
   lifecycle.info("sandbox_agent_ws_connect_attempt", {
     wsUrl: config2.wsUrl
   });
+  const stopActiveAgent = () => {
+    reportActiveRun = false;
+    activeRootExecutionActivity?.release();
+    activeRootExecutionActivity = null;
+    const agent = currentAgent;
+    if (!agent) return;
+    const killed = agent.kill();
+    if (!killed) {
+      agent.abort();
+      return;
+    }
+    const abortDeadline = setTimeout(() => {
+      if (currentAgent === agent) agent.abort();
+    }, 5e3);
+    abortDeadline.unref?.();
+  };
+  const terminateAgentProcess = (reason) => {
+    if (stopped) return;
+    lifecycle.warn("sandbox_agent_process_fenced", reason);
+    stopped = true;
+    executionLeaseClient?.close();
+    stopActiveAgent();
+    const resolvePendingMessage = pendingMessageResolve;
+    pendingMessageResolve = null;
+    resolvePendingMessage?.(null);
+  };
   const wsClient = new WSClient(
     config2.wsUrl,
     config2.sessionId,
@@ -69440,10 +69987,7 @@ async function runSandbox(config2) {
       },
       onStop: () => {
         lifecycle.info("sandbox_agent_stop_received");
-        if (currentAgent) {
-          const killed = currentAgent.kill();
-          if (!killed) currentAgent.abort();
-        }
+        stopActiveAgent();
       },
       onToolResponse: (toolId, response) => {
         if (currentAgent) {
@@ -69457,12 +70001,40 @@ async function runSandbox(config2) {
       },
       onConnect: () => lifecycle.info("sandbox_agent_ws_connected"),
       onDisconnect: (reason) => lifecycle.info("sandbox_agent_ws_disconnected", { reason }),
+      onCapabilities: (capabilities) => {
+        if (!capabilities.executionLeaseV1) return;
+        executionLeaseV1Supported = true;
+        executionLeaseClient?.enable();
+      },
+      onTerminalDirective: terminateAgentProcess,
       // Liveness heartbeat run state: a run is active while CoreAgent is executing.
-      getRunState: () => currentAgent ? { idle: false, activeRunIds: currentRunId ? [currentRunId] : [] } : { idle: true, activeRunIds: [] }
+      getRunState: () => {
+        const activeRunId = currentRunId ?? config2.runId;
+        return currentAgent && reportActiveRun ? { idle: false, activeRunIds: activeRunId ? [activeRunId] : [] } : { idle: true, activeRunIds: [] };
+      }
     },
     AGENT_VERSION,
     lifecycle
   );
+  const agentSessionId = wsClient.getAgentSessionId();
+  executionLeaseClient = config2.apiUrl && config2.sandboxId && agentSessionId ? new ExecutionLeaseClient({
+    apiUrl: config2.apiUrl,
+    sessionToken: config2.sessionToken,
+    agentSessionId,
+    agentVersion: AGENT_VERSION,
+    lifecycle,
+    enabled: false,
+    onAuthorityLost: ({ code }) => terminateAgentProcess({ code })
+  }) : null;
+  if (executionLeaseV1Supported) executionLeaseClient?.enable();
+  const executionActivityTracker = executionLeaseClient ? new ExecutionActivityTracker((activity) => executionLeaseClient.setActivity(activity)) : null;
+  if (!executionLeaseClient && (currentRunId ?? config2.runId)) {
+    lifecycle.warn("sandbox_agent_execution_lease_unavailable", {
+      hasApiUrl: Boolean(config2.apiUrl),
+      hasSandboxId: Boolean(config2.sandboxId),
+      hasAgentSessionId: Boolean(agentSessionId)
+    });
+  }
   try {
     await wsClient.waitForConnection();
   } catch (error2) {
@@ -69490,6 +70062,18 @@ async function runSandbox(config2) {
         backendKind: activeBackendKind
       });
       currentAgent = agent;
+      const activeRunId = currentRunId ?? config2.runId;
+      const rootExecutionActivity = executionActivityTracker && activeRunId && currentTaskId ? executionActivityTracker.register({
+        ownerId: `root:${activeRunId}`,
+        leaseRunId: activeRunId,
+        conversationId: currentConversationId,
+        taskId: currentTaskId,
+        sandboxId: config2.sandboxId,
+        kind: "root",
+        phase: "agent_run"
+      }) : null;
+      activeRootExecutionActivity = rootExecutionActivity;
+      reportActiveRun = true;
       wsClient.setCurrentRunId(currentRunId ?? config2.runId);
       presenter.setRunContext?.(currentRunId ?? config2.runId, activeBackendKind);
       const correlation = correlationLogFields2({
@@ -69642,6 +70226,12 @@ async function runSandbox(config2) {
           presenter.onError(errorMessage, false);
         }
         presenter.onComplete(result);
+      } finally {
+        reportActiveRun = false;
+        rootExecutionActivity?.release();
+        if (activeRootExecutionActivity === rootExecutionActivity) {
+          activeRootExecutionActivity = null;
+        }
       }
       currentAgent = null;
       resumeFallbackContext = void 0;
@@ -69733,6 +70323,7 @@ async function runSandbox(config2) {
   }
   presenter.setSuppressSessionLifecycle(false);
   lifecycle.info("sandbox_agent_process_exit");
+  executionLeaseClient?.close();
   wsClient.close();
 }
 
@@ -70098,6 +70689,7 @@ function logEffectiveGitIdentity(lifecycle, projectPath) {
 }
 async function runSessionFromEnv() {
   const wsUrl = process.env.ALAN_WS_URL;
+  const apiUrl = process.env.ALAN_API_URL || void 0;
   const sessionId = process.env.ALAN_SESSION_ID;
   const taskId = process.env.ALAN_TASK_ID;
   const sessionToken = process.env.ALAN_SESSION_TOKEN;
@@ -70143,6 +70735,7 @@ async function runSessionFromEnv() {
   logEffectiveGitIdentity(lifecycle, projectPath);
   await runSandbox({
     wsUrl,
+    apiUrl,
     sessionId,
     taskId,
     sessionToken,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiden-ade/sandbox-agent",
-  "version": "0.1.67",
+  "version": "0.1.68",
   "type": "module",
   "description": "Alan agent runtime — cloud sandbox and local daemon (alan-agent CLI)",
   "bin": {
@@ -25,8 +25,8 @@
     "tsup": "^8.5.1",
     "tsx": "^4.19.0",
     "typescript": "~5.9.3",
-    "@alan-ai/agent-core": "0.1.0",
-    "@alan-ai/shared": "0.1.0"
+    "@alan-ai/shared": "0.1.0",
+    "@alan-ai/agent-core": "0.1.0"
   },
   "deprecated": "Use @alan-ai-hq/agent-manager instead.",
   "scripts": {
@@ -35,7 +35,7 @@
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
-    "test": "vitest run src/__tests__/daemon-socket.integration.test.ts && vitest run --exclude src/__tests__/daemon-socket.integration.test.ts",
+    "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "type-check": "tsc --noEmit",