@the-open-engine/zeroshot 6.25.0 → 6.26.0

package/cli/index.js

@@ -2086,12 +2086,9 @@ async function getPurgeData(orchestrator) {
       cluster.state === 'running' || cluster.state === 'initializing' || cluster.state === 'setup'
   );
   const { loadTasks } = await import('../task-lib/store.js');
-  const { isProcessRunning } = await import('../task-lib/runner.js');
   const tasks = Object.values(loadTasks());
-  const runningTasks = tasks.filter(
-    (task) => task.status === 'running' && isProcessRunning(task.pid)
-  );
-  return { clusters, runningClusters, tasks, runningTasks, isProcessRunning };
+  const runningTasks = tasks.filter((task) => task.status === 'running');
+  return { clusters, runningClusters, tasks, runningTasks };
 }
 
 function printPurgeSummary({ clusters, runningClusters, tasks, runningTasks }) {
@@ -2133,45 +2130,105 @@ async function confirmPurge(options) {
   return answer.toLowerCase() === 'y';
 }
 
+function validateClusterKillResults(runningClusters, clusterResults) {
+  if (
+    clusterResults === null ||
+    typeof clusterResults !== 'object' ||
+    !Array.isArray(clusterResults.killed) ||
+    !Array.isArray(clusterResults.errors)
+  ) {
+    throw new Error(
+      'Refusing destructive cluster cleanup: kill-all returned incomplete or invalid results ' +
+        '(malformed fields: killed or errors). Retry after confirming every cluster process ' +
+        'boundary is terminal.'
+    );
+  }
+
+  const expectedIds = runningClusters.map((cluster) => cluster.id);
+  const expected = new Set(expectedIds);
+  const outcomeIds = [...clusterResults.killed, ...clusterResults.errors.map((error) => error?.id)];
+  const counts = outcomeIds.reduce((byId, id) => {
+    byId.set(id, (byId.get(id) || 0) + 1);
+    return byId;
+  }, new Map());
+  const problems = [
+    ['unknown outcomes', outcomeIds.filter((id) => typeof id !== 'string' || !expected.has(id))],
+    ['duplicate outcomes', expectedIds.filter((id) => (counts.get(id) || 0) > 1)],
+    ['missing outcomes', expectedIds.filter((id) => (counts.get(id) || 0) === 0)],
+  ]
+    .filter(([, ids]) => ids.length > 0)
+    .map(([label, ids]) => `${label}: ${ids.join(', ')}`);
+
+  if (problems.length > 0) {
+    throw new Error(
+      `Refusing destructive cluster cleanup: kill-all returned incomplete or invalid results (${problems.join(
+        '; '
+      )}). Retry after confirming every cluster process boundary is terminal.`
+    );
+  }
+
+  return clusterResults;
+}
+
 async function killRunningClusters(orchestrator, runningClusters) {
   if (runningClusters.length === 0) {
     return;
   }
   console.log(chalk.bold('Killing running clusters...'));
-  const clusterResults = await orchestrator.killAll();
-  for (const id of clusterResults.killed) {
+  const { killed, errors } = validateClusterKillResults(
+    runningClusters,
+    await orchestrator.killAll()
+  );
+
+  for (const id of killed) {
     console.log(chalk.green(`✓ Killed cluster: ${id}`));
   }
-  for (const err of clusterResults.errors) {
-    console.log(chalk.red(`✗ Failed to kill cluster ${err.id}: ${err.error}`));
+  if (errors.length > 0) {
+    for (const err of errors) {
+      console.log(chalk.red(`✗ Failed to kill cluster ${err.id}: ${err.error}`));
+    }
+    throw new Error(
+      `Refusing destructive cluster cleanup: termination failed for ${errors
+        .map((error) => error.id)
+        .join(', ')}. Retry after confirming every cluster process boundary is terminal.`
+    );
   }
 }
 
-async function killRunningTasks(runningTasks, isProcessRunning) {
+async function killRunningTasks(runningTasks) {
   if (runningTasks.length === 0) {
     return;
   }
   console.log(chalk.bold('Killing running tasks...'));
-  const { killTask } = await import('../task-lib/runner.js');
-  const { updateTask } = await import('../task-lib/store.js');
-
+  const [{ killTaskCommand }, { getTask }] = await Promise.all([
+    import('../task-lib/commands/kill.js'),
+    import('../task-lib/store.js'),
+  ]);
+  const unconfirmed = [];
+
+  // Reuse the standalone kill boundary instead of treating successful signal delivery as process
+  // termination. Then verify its durable terminal write: killTaskCommand also serves the interactive
+  // CLI and reports an unconfirmed boundary through process.exitCode rather than throwing. Purge
+  // must turn that report into a hard gate before it reaches any destructive cleanup.
   for (const task of runningTasks) {
-    if (!isProcessRunning(task.pid)) {
-      updateTask(task.id, {
-        status: 'stale',
-        error: 'Process died unexpectedly',
-      });
-      console.log(chalk.yellow(`○ Task ${task.id} was already dead, marked stale`));
-      continue;
-    }
-
-    const killed = killTask(task.pid);
-    if (killed) {
-      updateTask(task.id, { status: 'killed', error: 'Killed by clear' });
-      console.log(chalk.green(`✓ Killed task: ${task.id}`));
-    } else {
-      console.log(chalk.red(`✗ Failed to kill task: ${task.id}`));
-    }
+    await killTaskCommand(task.id);
+    const current = getTask(task.id);
+    if (
+      !current ||
+      current.status === 'running' ||
+      Number.isInteger(current.pid) ||
+      Number.isInteger(current.processGroupId)
+    ) {
+      unconfirmed.push(task.id);
+    }
+  }
+
+  if (unconfirmed.length > 0) {
+    throw new Error(
+      `Refusing destructive task cleanup: provider termination is unconfirmed for ${unconfirmed.join(
+        ', '
+      )}. Retry after confirming the persisted provider process boundary is terminal.`
+    );
   }
 }
 
@@ -2183,17 +2240,18 @@ async function killRunningTasks(runningTasks, isProcessRunning) {
  * cannot be safely resolved keeps its owner record plus a warning instead of being deleted.
  */
 async function deleteClusterOmpSessions(clusters) {
-  const { cleanupOmpSessionPartitionsForCluster } = await import(
-    '../task-lib/omp-session-cleanup.js'
-  );
+  const { cleanupOmpSessionPartitionsForCluster } =
+    await import('../task-lib/omp-session-cleanup.js');
   let deleted = 0;
   let retained = 0;
+  const unreadable = new Set();
   for (const cluster of clusters) {
     const result = cleanupOmpSessionPartitionsForCluster(cluster.id, (message) =>
       console.log(chalk.yellow(`Warning: ${message}`))
     );
     deleted += result.deleted.length;
     retained += result.retained.length;
+    for (const taskId of result.unreadable) unreadable.add(taskId);
   }
   if (deleted > 0) {
     console.log(chalk.green(`✓ Deleted ${deleted} OMP session partition(s)`));
@@ -2201,6 +2259,13 @@ async function deleteClusterOmpSessions(clusters) {
   if (retained > 0) {
     console.log(chalk.yellow(`○ Retained ${retained} OMP session partition(s) for inspection`));
   }
+  if (unreadable.size > 0) {
+    console.log(
+      chalk.yellow(
+        `○ ${unreadable.size} task row(s) hold an unreadable OMP session ownership record and were left intact`
+      )
+    );
+  }
 }
 
 async function deleteClusterData(orchestrator, clusters) {
@@ -3204,11 +3269,8 @@ program
       );
 
       const { loadTasks } = await import('../task-lib/store.js');
-      const { isProcessRunning } = await import('../task-lib/runner.js');
       const tasks = loadTasks();
-      const runningTasks = Object.values(tasks).filter(
-        (t) => t.status === 'running' && isProcessRunning(t.pid)
-      );
+      const runningTasks = Object.values(tasks).filter((task) => task.status === 'running');
 
       const totalCount = runningClusters.length + runningTasks.length;
 
@@ -3253,44 +3315,9 @@ program
 
       console.log('');
 
-      // Kill clusters
-      if (runningClusters.length > 0) {
-        const clusterResults = await orchestrator.killAll();
-        for (const id of clusterResults.killed) {
-          console.log(chalk.green(`✓ Killed cluster: ${id}`));
-        }
-        for (const err of clusterResults.errors) {
-          console.log(chalk.red(`✗ Failed to kill cluster ${err.id}: ${err.error}`));
-        }
-      }
-
-      // Kill tasks
-      if (runningTasks.length > 0) {
-        const { killTask, isProcessRunning: checkPid } = await import('../task-lib/runner.js');
-        const { updateTask } = await import('../task-lib/store.js');
-
-        for (const task of runningTasks) {
-          if (!checkPid(task.pid)) {
-            updateTask(task.id, {
-              status: 'stale',
-              error: 'Process died unexpectedly',
-            });
-            console.log(chalk.yellow(`○ Task ${task.id} was already dead, marked stale`));
-            continue;
-          }
+      await killRunningClusters(orchestrator, runningClusters);
 
-          const killed = killTask(task.pid);
-          if (killed) {
-            updateTask(task.id, {
-              status: 'killed',
-              error: 'Killed by kill-all',
-            });
-            console.log(chalk.green(`✓ Killed task: ${task.id}`));
-          } else {
-            console.log(chalk.red(`✗ Failed to kill task: ${task.id}`));
-          }
-        }
-      }
+      await killRunningTasks(runningTasks);
 
       console.log(chalk.bold.green(`\nDone.`));
     } catch (error) {
@@ -3801,7 +3828,7 @@ program
       console.log('');
 
       await killRunningClusters(orchestrator, purgeData.runningClusters);
-      await killRunningTasks(purgeData.runningTasks, purgeData.isProcessRunning);
+      await killRunningTasks(purgeData.runningTasks);
       await deleteClusterData(orchestrator, purgeData.clusters);
       await deleteTaskData(purgeData.tasks);
 
@@ -6089,4 +6116,5 @@ module.exports = {
   renderRecentMessagesToTerminal,
   isStartupUpdateEligible,
   resolveRunMode,
+  killRunningClusters,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-open-engine/zeroshot",
-  "version": "6.25.0",
+  "version": "6.26.0",
   "description": "Multi-agent orchestration engine for Claude, Codex, and Gemini",
   "main": "src/orchestrator.js",
   "bin": {
@@ -40,8 +40,10 @@
     "test:coverage:report": "c8 --reporter=html npm run test:unit && echo 'Coverage report generated at coverage/index.html'",
     "postinstall": "node scripts/fix-node-pty-permissions.js && node scripts/check-path.js",
     "start": "node cli/index.js",
-    "typecheck": "tsc --noEmit && npm run typecheck:cluster",
+    "typecheck": "tsc --noEmit && npm run typecheck:cluster && npm run typecheck:hosted-target",
     "typecheck:agent-cli-provider": "tsc --project tsconfig.agent-cli-provider.json",
+    "typecheck:hosted-target": "tsc --project tsconfig.hosted-target.json",
+    "test:hosted-target": "node --test tests/hosted-target/*.test.ts",
     "typecheck:cluster": "tsc --project tsconfig.cluster.json",
     "lint:agent-cli-provider": "eslint \"src/agent-cli-provider/**/*.ts\" \"tests/agent-cli-provider/**/*.ts\"",
     "build:agent-cli-provider": "tsc --project tsconfig.agent-cli-provider.build.json",

package/src/agent/provider-session.js

@@ -65,13 +65,25 @@ const OMP_SESSION_KEYS = new Set([
 ]);
 const IDENTITY_KEYS = new Set(['device', 'inode']);
 
+/**
+ * A `{device, inode}` pair, both already canonical unsigned decimal *strings* (issue #866).
+ *
+ * The type is required, not coerced. `String(value.device)` used to accept a JSON number, a
+ * boxed String, a one-element array, or anything else whose `toString()` happened to look decimal,
+ * and then write the coerced result into the snapshot — so a snapshot that had never contained the
+ * canonical form would compare equal to the persisted ownership record it is supposed to be
+ * checked against. A snapshot that is not already canonical is not this writer's snapshot, and is
+ * rejected rather than repaired. Both keys are required and no others are allowed.
+ */
 function normalizeIdentity(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
-  if (!Object.keys(value).every((key) => IDENTITY_KEYS.has(key))) return null;
-  if (!DECIMAL_STRING.test(String(value.device)) || !DECIMAL_STRING.test(String(value.inode))) {
+  const keys = Object.keys(value);
+  if (keys.length !== IDENTITY_KEYS.size || !keys.every((key) => IDENTITY_KEYS.has(key))) {
     return null;
   }
-  return { device: String(value.device), inode: String(value.inode) };
+  if (typeof value.device !== 'string' || typeof value.inode !== 'string') return null;
+  if (!DECIMAL_STRING.test(value.device) || !DECIMAL_STRING.test(value.inode)) return null;
+  return { device: value.device, inode: value.inode };
 }
 
 /**
@@ -299,7 +311,9 @@ function providerSessionFromCompletedTask({
   // rpc-watcher.js never populates the generic sessionId column; the OMP-observed session ID
   // committed alongside ompSession is the one authoritative identity for this provider.
   const sessionId = isOmp
-    ? normalizeNonEmptyString(ompOwnership?.state === 'committed' ? ompOwnership.session?.sessionId : null)
+    ? normalizeNonEmptyString(
+        ompOwnership?.state === 'committed' ? ompOwnership.session?.sessionId : null
+      )
     : normalizeNonEmptyString(taskInfo.sessionId);
   const taskId = normalizeNonEmptyString(taskInfo.id);
   const generation = agent?.iteration;

package/src/hosted-target/bounds.ts

@@ -0,0 +1,6 @@
+export const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+export const MAX_PAGINATION_PAGES = 100;
+export const MAX_RETRY_ATTEMPTS = 3;
+export const MAX_RETRY_ELAPSED_MS = 30_000;
+export const MAX_ERROR_BODY_BYTES = 8192;
+export const IDEMPOTENCY_KEY_PATTERN = /^[a-zA-Z0-9_-]{1,128}$/;

package/src/hosted-target/errors.ts

@@ -0,0 +1,90 @@
+function sanitize(text: string): string {
+  return text
+    .replace(/Authorization:\s*Bearer\s+\S+/gi, 'Authorization: Bearer [REDACTED]')
+    .replace(/token["']?\s*[:=]\s*["'][^"']+["']/gi, 'token: "[REDACTED]"')
+    .replace(/https?:\/\/[^\s]*(?:token|key|secret|credential|auth)[^\s]*/gi, '[REDACTED_URL]');
+}
+
+function sanitizeCause(cause: unknown): unknown {
+  if (!cause) return cause;
+  if (cause instanceof Error) {
+    const cleaned = new Error(sanitize(cause.message));
+    cleaned.name = cause.name;
+    if (cause.cause) cleaned.cause = sanitizeCause(cause.cause);
+    return cleaned;
+  }
+  if (typeof cause === 'string') return sanitize(cause);
+  return cause;
+}
+
+export class TargetAdapterError extends Error {
+  readonly code: string;
+  readonly retryable: boolean;
+
+  constructor(code: string, message: string, retryable: boolean, cause?: unknown) {
+    super(sanitize(message), { cause: sanitizeCause(cause) });
+    this.name = 'TargetAdapterError';
+    this.code = code;
+    this.retryable = retryable;
+  }
+}
+
+export class TargetAuthError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('AUTH_FAILED', message, false, cause);
+    this.name = 'TargetAuthError';
+  }
+}
+
+export class TargetConflictError extends TargetAdapterError {
+  readonly idempotencyKey: string;
+
+  constructor(idempotencyKey: string, message: string, cause?: unknown) {
+    super('CONFLICT', message, true, cause);
+    this.name = 'TargetConflictError';
+    this.idempotencyKey = idempotencyKey;
+  }
+}
+
+export class TargetRateLimitError extends TargetAdapterError {
+  readonly retryAfterMs: number | undefined;
+
+  constructor(message: string, retryAfterMs?: number, cause?: unknown) {
+    super('RATE_LIMITED', message, true, cause);
+    this.name = 'TargetRateLimitError';
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+export class TargetTransportError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('TRANSPORT', message, true, cause);
+    this.name = 'TargetTransportError';
+  }
+}
+
+export class TargetProtocolError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('PROTOCOL', message, false, cause);
+    this.name = 'TargetProtocolError';
+  }
+}
+
+export class TargetCapacityError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('CAPACITY', message, false, cause);
+    this.name = 'TargetCapacityError';
+  }
+}
+
+export class TargetNotFoundError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('NOT_FOUND', message, false, cause);
+    this.name = 'TargetNotFoundError';
+  }
+}
+
+export function isRetryable(error: unknown): boolean {
+  if (error instanceof TargetAdapterError) return error.retryable;
+  return false;
+}

package/src/hosted-target/index.ts

@@ -0,0 +1,44 @@
+export type { TargetAdapter } from './target-adapter.ts';
+export { ZeroCloudV1TargetAdapter } from './zero-cloud-v1-adapter.ts';
+export {
+  TargetAdapterError,
+  TargetAuthError,
+  TargetConflictError,
+  TargetRateLimitError,
+  TargetTransportError,
+  TargetProtocolError,
+  TargetCapacityError,
+  TargetNotFoundError,
+  isRetryable,
+} from './errors.ts';
+export type {
+  TargetAccessTokenProvider,
+  CapsuleState,
+  Capsule,
+  CapsuleAccess,
+  CapsuleListPage,
+  CapsuleLimits,
+  AllocateRequest,
+  HttpTransport,
+  Clock,
+  RetryPolicy,
+  TargetDiscovery,
+} from './types.ts';
+export { KNOWN_CAPSULE_STATES } from './types.ts';
+export {
+  MAX_RESPONSE_BYTES,
+  MAX_PAGINATION_PAGES,
+  MAX_RETRY_ATTEMPTS,
+  MAX_RETRY_ELAPSED_MS,
+  MAX_ERROR_BODY_BYTES,
+  IDEMPOTENCY_KEY_PATTERN,
+} from './bounds.ts';
+export { DefaultRetryPolicy, parseRetryAfter } from './retry.ts';
+export {
+  assertRequiredFields,
+  assertKnownEnum,
+  assertCapsule,
+  assertCapsuleAccess,
+  assertCapsuleLimits,
+  assertCapsuleListPage,
+} from './response-validation.ts';

package/src/hosted-target/response-validation.ts

@@ -0,0 +1,86 @@
+import { TargetProtocolError } from './errors.ts';
+import { KNOWN_CAPSULE_STATES } from './types.ts';
+import type { Capsule, CapsuleAccess, CapsuleLimits, CapsuleListPage } from './types.ts';
+
+export function assertRequiredFields(
+  body: unknown,
+  fields: readonly string[],
+  context: string,
+): asserts body is Record<string, unknown> {
+  if (body === null || typeof body !== 'object') {
+    throw new TargetProtocolError(`${context}: expected object, got ${typeof body}`);
+  }
+  const record = body as Record<string, unknown>;
+  for (const field of fields) {
+    if (record[field] === undefined || record[field] === null) {
+      throw new TargetProtocolError(`${context}: missing required field "${field}"`);
+    }
+  }
+}
+
+export function assertKnownEnum(value: string, known: readonly string[], field: string): void {
+  if (!known.includes(value)) {
+    // eslint-disable-next-line no-console
+    console.warn(`Unknown ${field} value: "${value}". Known values: ${known.join(', ')}`);
+  }
+}
+
+export function assertCapsule(body: unknown): Capsule {
+  assertRequiredFields(body, ['id', 'state', 'createdAt'], 'Capsule');
+  const record = body as Record<string, unknown>;
+  if (typeof record['id'] !== 'string') {
+    throw new TargetProtocolError('Capsule: "id" must be a string');
+  }
+  if (typeof record['state'] !== 'string') {
+    throw new TargetProtocolError('Capsule: "state" must be a string');
+  }
+  if (typeof record['createdAt'] !== 'string') {
+    throw new TargetProtocolError('Capsule: "createdAt" must be a string');
+  }
+  assertKnownEnum(record['state'] as string, KNOWN_CAPSULE_STATES, 'CapsuleState');
+  return record as unknown as Capsule;
+}
+
+export function assertCapsuleAccess(body: unknown): CapsuleAccess {
+  assertRequiredFields(body, ['endpoint', 'token', 'expiresAt'], 'CapsuleAccess');
+  const record = body as Record<string, unknown>;
+  if (typeof record['endpoint'] !== 'string') {
+    throw new TargetProtocolError('CapsuleAccess: "endpoint" must be a string');
+  }
+  if (typeof record['token'] !== 'string') {
+    throw new TargetProtocolError('CapsuleAccess: "token" must be a string');
+  }
+  if (typeof record['expiresAt'] !== 'string') {
+    throw new TargetProtocolError('CapsuleAccess: "expiresAt" must be a string');
+  }
+  return record as unknown as CapsuleAccess;
+}
+
+export function assertCapsuleLimits(body: unknown): CapsuleLimits {
+  assertRequiredFields(body, ['maxConcurrent', 'maxPerHour'], 'CapsuleLimits');
+  const record = body as Record<string, unknown>;
+  if (typeof record['maxConcurrent'] !== 'number') {
+    throw new TargetProtocolError('CapsuleLimits: "maxConcurrent" must be a number');
+  }
+  if (typeof record['maxPerHour'] !== 'number') {
+    throw new TargetProtocolError('CapsuleLimits: "maxPerHour" must be a number');
+  }
+  return record as unknown as CapsuleLimits;
+}
+
+export function assertCapsuleListPage(body: unknown): CapsuleListPage {
+  assertRequiredFields(body, ['items'], 'CapsuleListPage');
+  const record = body as Record<string, unknown>;
+  if (!Array.isArray(record['items'])) {
+    throw new TargetProtocolError('CapsuleListPage: "items" must be an array');
+  }
+  const items = (record['items'] as unknown[]).map((item) => assertCapsule(item));
+  const cursor = record['cursor'];
+  if (cursor !== undefined && cursor !== null && typeof cursor !== 'string') {
+    throw new TargetProtocolError('CapsuleListPage: "cursor" must be a string if present');
+  }
+  if (typeof cursor === 'string') {
+    return { items, cursor };
+  }
+  return { items };
+}

package/src/hosted-target/retry.ts

@@ -0,0 +1,46 @@
+import { MAX_RETRY_ATTEMPTS, MAX_RETRY_ELAPSED_MS } from './bounds.ts';
+import type { TargetAdapterError } from './errors.ts';
+import { TargetAuthError, TargetRateLimitError } from './errors.ts';
+import type { Clock, RetryPolicy } from './types.ts';
+
+export class DefaultRetryPolicy implements RetryPolicy {
+  shouldRetry(
+    attempt: number,
+    elapsed: number,
+    error: TargetAdapterError,
+  ): { retry: boolean; delayMs: number } {
+    if (error instanceof TargetAuthError) return { retry: false, delayMs: 0 };
+    if (!error.retryable) return { retry: false, delayMs: 0 };
+    if (attempt >= MAX_RETRY_ATTEMPTS) return { retry: false, delayMs: 0 };
+    if (elapsed >= MAX_RETRY_ELAPSED_MS) return { retry: false, delayMs: 0 };
+
+    const requestedDelay =
+      error instanceof TargetRateLimitError && error.retryAfterMs !== undefined
+        ? Math.max(0, error.retryAfterMs)
+        : Math.min(1000 * Math.pow(2, attempt), 10_000);
+    const remaining = MAX_RETRY_ELAPSED_MS - elapsed;
+    if (!Number.isFinite(requestedDelay) || requestedDelay >= remaining) {
+      return { retry: false, delayMs: 0 };
+    }
+
+    return { retry: true, delayMs: requestedDelay };
+  }
+}
+
+export function parseRetryAfter(header: string | null, clock: Clock): number | null {
+  if (header === null) return null;
+
+  const trimmed = header.trim();
+  if (trimmed.length === 0) return null;
+
+  const numericSeconds = Number(trimmed);
+  if (Number.isFinite(numericSeconds) && numericSeconds >= 0) {
+    return Math.ceil(numericSeconds * 1000);
+  }
+
+  const date = Date.parse(trimmed);
+  if (Number.isNaN(date)) return null;
+
+  const delayMs = date - clock.now();
+  return delayMs > 0 ? Math.ceil(delayMs) : 0;
+}

package/src/hosted-target/target-adapter.ts

@@ -0,0 +1,10 @@
+import type { AllocateRequest, Capsule, CapsuleAccess, CapsuleLimits, CapsuleListPage } from './types.ts';
+
+export interface TargetAdapter {
+  allocate(req: AllocateRequest, signal?: AbortSignal): Promise<Capsule>;
+  list(cursor?: string, signal?: AbortSignal): Promise<CapsuleListPage>;
+  inspect(capsuleId: string, signal?: AbortSignal): Promise<Capsule>;
+  terminate(capsuleId: string, signal?: AbortSignal): Promise<void>;
+  limits(signal?: AbortSignal): Promise<CapsuleLimits>;
+  access(capsuleId: string, signal?: AbortSignal): Promise<CapsuleAccess>;
+}

package/src/hosted-target/types.ts

@@ -0,0 +1,58 @@
+import type { TargetAdapterError } from './errors.ts';
+
+export interface TargetAccessTokenProvider {
+  getAccessToken(signal?: AbortSignal): Promise<string>;
+}
+
+export type CapsuleState = 'provisioning' | 'running' | 'stopping' | 'terminated' | 'failed' | (string & {});
+
+export const KNOWN_CAPSULE_STATES = ['provisioning', 'running', 'stopping', 'terminated', 'failed'] as const;
+
+export interface Capsule {
+  readonly id: string;
+  readonly state: CapsuleState;
+  readonly createdAt: string;
+  readonly [key: string]: unknown;
+}
+
+export interface CapsuleAccess {
+  readonly endpoint: string;
+  readonly token: string;
+  readonly expiresAt: string;
+}
+
+export interface CapsuleListPage {
+  readonly items: readonly Capsule[];
+  readonly cursor?: string;
+}
+
+export interface CapsuleLimits {
+  readonly maxConcurrent: number;
+  readonly maxPerHour: number;
+  readonly [key: string]: unknown;
+}
+
+export interface AllocateRequest {
+  readonly idempotencyKey: string;
+  readonly profile: string;
+}
+
+export interface HttpTransport {
+  fetch(url: string, init: RequestInit & { redirect: 'error' }): Promise<Response>;
+}
+
+export interface Clock {
+  now(): number;
+}
+
+export interface RetryPolicy {
+  shouldRetry(
+    attempt: number,
+    elapsed: number,
+    error: TargetAdapterError,
+  ): { retry: boolean; delayMs: number };
+}
+
+export interface TargetDiscovery {
+  readonly capsuleV1: string;
+}