@tangle-network/agent-app 0.44.30 → 0.44.32

package/dist/sandbox/index.d.ts

@@ -727,6 +727,87 @@ interface SandboxPrewarmer {
 }
 declare function createSandboxPrewarmer(shell: SandboxRuntimeConfig, options: SandboxPrewarmerOptions): SandboxPrewarmer;
 
+/**
+ * `createD1PrewarmClaimStore` — the cross-isolate half of
+ * `createSandboxPrewarmer`'s single-flight, implemented once.
+ *
+ * WHY THIS SHIPS HERE. `SandboxPrewarmerOptions.claim` is REQUIRED and has no
+ * default, which is correct — the unsafe behaviour must be said out loud. But
+ * "required with no implementation" is how five products end up hand-rolling
+ * five subtly different atomic leases, and a lease that is subtly wrong is
+ * indistinguishable from one that works until two tabs leak a box. Every
+ * agent-app product deploys to Cloudflare Workers with a D1 binding, so the
+ * store is the same code in all of them: it is mechanism, not domain, and it
+ * belongs beside the prewarmer.
+ *
+ * The measured stake (staging-sandbox, 2026-07-28): two concurrent
+ * `POST /v1/sandboxes` with an identical name BOTH returned HTTP 201 and left
+ * two running boxes. The platform does not dedupe by name, so nothing below
+ * this line is defensive programming — an unclaimed race genuinely doubles
+ * spend.
+ *
+ * ── ATOMICITY IS THE WHOLE POINT ───────────────────────────────────────────
+ * `acquire` is ONE statement. A `SELECT` followed by an `INSERT` is exactly the
+ * race this exists to close: both isolates read "free", both write, both warm.
+ * The upsert's `DO UPDATE ... WHERE expires_at <= now` means an unexpired claim
+ * makes the conflict path a no-op, and `RETURNING` then yields no row — so the
+ * loser learns it lost from the same statement that would have made it the
+ * winner. `RETURNING` is used rather than `meta.changes` because a no-op upsert
+ * reporting `changes: 0` is a SQLite detail, whereas "no row came back" is the
+ * statement telling you directly.
+ *
+ * ── STRUCTURAL, NOT A DEPENDENCY ───────────────────────────────────────────
+ * The binding is taken as the narrow shape actually used (`prepare().bind()`,
+ * `.first()`, `.run()`), per the package's structural-over-hard-dep rule. No
+ * `@cloudflare/workers-types` import, so `/sandbox` stays importable in a plain
+ * node test. A real `D1Database` satisfies it.
+ *
+ * ── THE TABLE IS THE PRODUCT'S MIGRATION, NOT A LAZY CREATE ────────────────
+ * The store never runs DDL. A `CREATE TABLE IF NOT EXISTS` on every project
+ * open costs a round trip on the exact path this feature exists to keep fast,
+ * and it hides schema drift instead of failing on it. `PREWARM_CLAIM_TABLE_DDL`
+ * is exported so a product pastes it into a real migration. If the table is
+ * missing, `acquire` throws — and the prewarmer treats a throwing claim as a
+ * failed warm: it records the failure, emits `onEvent({type:'failed'})`, and
+ * degrades to the lazy path. Fail-closed and loud, never a silent double-warm.
+ */
+/** The columns and statements this store uses, and nothing else. A real
+ *  `D1Database` structurally satisfies it. */
+interface PrewarmClaimD1Like {
+    prepare(query: string): {
+        bind(...values: unknown[]): {
+            first<T = Record<string, unknown>>(): Promise<T | null>;
+            run(): Promise<unknown>;
+        };
+    };
+}
+interface D1PrewarmClaimStoreOptions {
+    /** Defaults to `sandbox_prewarm_claims`. Must be a bare SQL identifier — it
+     *  is interpolated, because a table name cannot be a bound parameter. */
+    table?: string;
+    /** Clock seam for tests. */
+    now?(): number;
+}
+declare const DEFAULT_PREWARM_CLAIM_TABLE = "sandbox_prewarm_claims";
+/** Paste into a migration. `expires_at` is epoch MILLISECONDS, matching
+ *  `Date.now()`, so no unit conversion sits between the lease and its clock. */
+declare const PREWARM_CLAIM_TABLE_DDL = "CREATE TABLE IF NOT EXISTS sandbox_prewarm_claims (\n  key TEXT PRIMARY KEY,\n  expires_at INTEGER NOT NULL\n)";
+/**
+ * A `PrewarmClaimStore` backed by one D1 table.
+ *
+ * ```ts
+ * const prewarmer = createSandboxPrewarmer(shell, {
+ *   claim: createD1PrewarmClaimStore(env.DB),
+ *   mode: 'create-or-resume',
+ * })
+ * ```
+ */
+declare function createD1PrewarmClaimStore(db: PrewarmClaimD1Like, options?: D1PrewarmClaimStoreOptions): {
+    acquire(key: string, ttlSeconds: number): Promise<boolean>;
+    release(key: string): Promise<void>;
+    isHeld(key: string): Promise<boolean>;
+};
+
 /** Define client credentials for accessing the sandbox environment with API key and base URL */
 interface SandboxClientCredentials {
     apiKey: string;
@@ -1228,4 +1309,4 @@ declare function isTerminalPromptEvent(event: unknown): boolean;
 /** Resolve the interactive question text from a structured event or return null if none found */
 declare function detectInteractiveQuestion(event: unknown): string | null;
 
-export { type AppToolDescriptor, type AuthenticatedSandboxUser, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, DEFAULT_SANDBOX_RESOURCES, type DriveSandboxTurnOptions, ENV_TOTAL_MAX_BYTES, ENV_VALUE_MAX_BYTES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type ModelSelection, type ModelSelectionError, type ModelSelectionFailure, type ModelSelectionSource, type Outcome, PROVISION_PAYLOAD_MAX_BYTES, type PeekWorkspaceSandboxOutcome, type PrewarmClaimStore, type PrewarmDecision, type PrewarmEvent, type PrewarmOutcome, type PrewarmResult, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ProvisionPayloadSections, type ProvisionProfileSection, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SandboxApiCredentials, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, type SandboxExecChannel, type SandboxExecOptions, type SandboxFileBytesOutcome, type SandboxFileSizeOutcome, SandboxModelResolutionError, type SandboxPermissionLevel, type SandboxPrewarmScope, type SandboxPrewarmer, type SandboxPrewarmerOptions, type SandboxReadiness, SandboxRecoveryFailedError, type SandboxRecoveryPhase, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxRuntimeConnection, type SandboxScope, type SandboxStepTransition, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalProxyIdentity, type TerminalUpgradeResponseLike, type WorkspaceSandboxConnectionArgs, type WorkspaceSandboxConnectionHandlerOptions, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRuntimeProxyArgs, type WorkspaceSandboxRuntimeProxyHandlerOptions, type WorkspaceSandboxTerminalUpgradeHandlerOptions, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, attachReasoningEffort, bearerSubprotocolToken, bearerToken, buildAppToolMcpServers, buildSandboxRuntimeProxyHeaders, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, collectSandboxPromptText, createSandboxPrewarmer, createSandboxTerminalToken, createWorkspaceSandboxConnectionHandler, createWorkspaceSandboxManager, createWorkspaceSandboxRuntimeProxyHandler, createWorkspaceSandboxTerminalUpgradeHandler, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, encodeSandboxRuntimePath, ensureWorkspaceSandbox, flattenHistory, getClient, isSandboxTerminalWsUpgrade, isTerminalPromptEvent, matchSandboxTerminalWsPath, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, mintTerminalProxyToken, peekWorkspaceSandbox, readSandboxBinaryBytes, readSecret, requireTransportableModel, resetClientCache, resolveModel, resolveModelSelection, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxSidecarProxyUrl, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, selectedBearerSubprotocol, shellQuote, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, terminalTokenFromRequest, terminalUpgradeSubprotocolEcho, verifySandboxTerminalToken, verifyTerminalProxyToken, writeProfileFilesToBox };
+export { type AppToolDescriptor, type AuthenticatedSandboxUser, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, type D1PrewarmClaimStoreOptions, DEFAULT_PREWARM_CLAIM_TABLE, DEFAULT_SANDBOX_RESOURCES, type DriveSandboxTurnOptions, ENV_TOTAL_MAX_BYTES, ENV_VALUE_MAX_BYTES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type ModelSelection, type ModelSelectionError, type ModelSelectionFailure, type ModelSelectionSource, type Outcome, PREWARM_CLAIM_TABLE_DDL, PROVISION_PAYLOAD_MAX_BYTES, type PeekWorkspaceSandboxOutcome, type PrewarmClaimD1Like, type PrewarmClaimStore, type PrewarmDecision, type PrewarmEvent, type PrewarmOutcome, type PrewarmResult, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ProvisionPayloadSections, type ProvisionProfileSection, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SandboxApiCredentials, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, type SandboxExecChannel, type SandboxExecOptions, type SandboxFileBytesOutcome, type SandboxFileSizeOutcome, SandboxModelResolutionError, type SandboxPermissionLevel, type SandboxPrewarmScope, type SandboxPrewarmer, type SandboxPrewarmerOptions, type SandboxReadiness, SandboxRecoveryFailedError, type SandboxRecoveryPhase, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxRuntimeConnection, type SandboxScope, type SandboxStepTransition, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalProxyIdentity, type TerminalUpgradeResponseLike, type WorkspaceSandboxConnectionArgs, type WorkspaceSandboxConnectionHandlerOptions, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRuntimeProxyArgs, type WorkspaceSandboxRuntimeProxyHandlerOptions, type WorkspaceSandboxTerminalUpgradeHandlerOptions, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, attachReasoningEffort, bearerSubprotocolToken, bearerToken, buildAppToolMcpServers, buildSandboxRuntimeProxyHeaders, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, collectSandboxPromptText, createD1PrewarmClaimStore, createSandboxPrewarmer, createSandboxTerminalToken, createWorkspaceSandboxConnectionHandler, createWorkspaceSandboxManager, createWorkspaceSandboxRuntimeProxyHandler, createWorkspaceSandboxTerminalUpgradeHandler, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, encodeSandboxRuntimePath, ensureWorkspaceSandbox, flattenHistory, getClient, isSandboxTerminalWsUpgrade, isTerminalPromptEvent, matchSandboxTerminalWsPath, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, mintTerminalProxyToken, peekWorkspaceSandbox, readSandboxBinaryBytes, readSecret, requireTransportableModel, resetClientCache, resolveModel, resolveModelSelection, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxSidecarProxyUrl, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, selectedBearerSubprotocol, shellQuote, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, terminalTokenFromRequest, terminalUpgradeSubprotocolEcho, verifySandboxTerminalToken, verifyTerminalProxyToken, writeProfileFilesToBox };

package/dist/sandbox/index.js

@@ -1,7 +1,9 @@
 import {
+  DEFAULT_PREWARM_CLAIM_TABLE,
   DEFAULT_SANDBOX_RESOURCES,
   ENV_TOTAL_MAX_BYTES,
   ENV_VALUE_MAX_BYTES,
+  PREWARM_CLAIM_TABLE_DDL,
   PROVISION_PAYLOAD_MAX_BYTES,
   SandboxModelResolutionError,
   SandboxRecoveryFailedError,
@@ -17,6 +19,7 @@ import {
   buildSandboxToolPathSetupScript,
   classifySeveredStream,
   collectSandboxPromptText,
+  createD1PrewarmClaimStore,
   createSandboxPrewarmer,
   createSandboxTerminalToken,
   createWorkspaceSandboxConnectionHandler,
@@ -67,7 +70,7 @@ import {
   verifySandboxTerminalToken,
   verifyTerminalProxyToken,
   writeProfileFilesToBox
-} from "../chunk-BAC2B2KI.js";
+} from "../chunk-7WXG4ZFP.js";
 import "../chunk-LWSJK546.js";
 import "../chunk-CQZSAR77.js";
 import "../chunk-ICOHEZK6.js";
@@ -76,9 +79,11 @@ import "../chunk-YEFFHORB.js";
 import "../chunk-S5SRJJQG.js";
 import "../chunk-JML7WKWU.js";
 export {
+  DEFAULT_PREWARM_CLAIM_TABLE,
   DEFAULT_SANDBOX_RESOURCES,
   ENV_TOTAL_MAX_BYTES,
   ENV_VALUE_MAX_BYTES,
+  PREWARM_CLAIM_TABLE_DDL,
   PROVISION_PAYLOAD_MAX_BYTES,
   SandboxModelResolutionError,
   SandboxRecoveryFailedError,
@@ -94,6 +99,7 @@ export {
   buildSandboxToolPathSetupScript,
   classifySeveredStream,
   collectSandboxPromptText,
+  createD1PrewarmClaimStore,
   createSandboxPrewarmer,
   createSandboxTerminalToken,
   createWorkspaceSandboxConnectionHandler,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-app",
-  "version": "0.44.30",
+  "version": "0.44.32",
   "packageManager": "pnpm@10.33.4",
   "description": "Application-shell framework for Tangle agent products: a bounded tool loop, the structured agent→app tool side channel, integration-hub client, per-workspace billing, and crypto — composed over the Tangle agent substrate through typed seams.",
   "keywords": [