@inneranimalmedia/agentsam-sdk 2.6.10 → 2.6.11

package/src/go/{cloudflare.js → providers/cloudflare.js}

@@ -1,25 +1,21 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { parseWranglerVersionId } from '../lib/deploy/health.js';
+import { parseWranglerVersionId } from '../../lib/deploy/health.js';
 import {
   writeDeploymentReceipt,
   writeDeploymentValidationReceipt,
   writeProductRegistryLocal,
   writeProductValidationLocal,
   buildProductRow,
-} from './receipts.js';
-import { applyInnerAnimalMediaOfficialGoProductRegistry } from './official-registry.js';
-import { SDK_ROOT } from './discover.js';
-
-const EXPECTED_HASH = '2e60bba13dc2bc37d75dd2ce5deb25466f19cb2994e20889388948879875eae9';
+} from '../receipts.js';
+import { applyInnerAnimalMediaOfficialGoProductRegistry } from '../official-registry.js';
+import { SDK_ROOT } from '../discover.js';
+import { resolveWranglerBin } from '../contract.js';
+import { probeGoDeploymentWithRetry } from '../probe.js';
 
 function resolveWranglerInvocation(productRoot) {
-  const js = path.join(productRoot, 'node_modules', 'wrangler', 'bin', 'wrangler.js');
-  if (fs.existsSync(js)) return { command: process.execPath, args: [js] };
-  const bin = path.join(productRoot, 'node_modules', '.bin', 'wrangler');
-  if (fs.existsSync(bin)) return { command: bin, args: [] };
-  return { command: 'npx', args: ['--yes', 'wrangler'] };
+  return resolveWranglerBin(productRoot);
 }
 
 function runWrangler(wrangler, args, {
@@ -56,8 +52,11 @@ function publicAccount(account) {
   };
 }
 
-export function resolveConfiguredDeploymentUrl(productRoot) {
-  const configPath = path.join(productRoot, 'wrangler.jsonc');
+export function resolveConfiguredDeploymentUrl(
+  productRoot,
+  configName = 'wrangler.jsonc',
+) {
+  const configPath = path.join(productRoot, configName);
   if (!fs.existsSync(configPath)) return null;
 
   try {
@@ -189,8 +188,9 @@ function deploymentArgs({
   dryRun = false,
   source = null,
   builtAt = null,
+  configName = 'wrangler.jsonc',
 } = {}) {
-  const args = ['deploy', '-c', 'wrangler.jsonc'];
+  const args = ['deploy', '-c', configName];
   if (source?.identity) args.push('--var', 'AGENTSAM_BUILD_SOURCE:' + source.identity);
   if (source?.commit) args.push('--var', 'AGENTSAM_BUILD_COMMIT:' + source.commit);
   if (builtAt) args.push('--var', 'AGENTSAM_BUILT_AT:' + builtAt);
@@ -225,8 +225,16 @@ export async function deployGoCloudflare({
   spawn = spawnSync,
   fetchImpl = globalThis.fetch,
 } = {}) {
-  const wranglerConfig = path.join(productRoot, 'wrangler.jsonc');
-  if (!fs.existsSync(wranglerConfig)) throw new Error('wrangler_config_missing: ' + wranglerConfig);
+  const configName = officialRelease
+    ? 'wrangler.inneranimalmedia.jsonc'
+    : 'wrangler.jsonc';
+
+  const wranglerConfig = path.join(productRoot, configName);
+  if (!fs.existsSync(wranglerConfig)) {
+    const err = new Error('wrangler_config_missing: ' + wranglerConfig);
+    err.code = 'wrangler_config_missing';
+    throw err;
+  }
 
   let cfIdentity = cloudflareIdentity;
   if (!skipDeploy) {
@@ -247,15 +255,6 @@ export async function deployGoCloudflare({
     accountId = cfIdentity.account.id;
   }
 
-  const docker = spawn('docker', ['info'], { encoding: 'utf8' });
-  const dockerOk = docker.status === 0;
-  if (!dockerOk && !skipDeploy) {
-    const err = new Error('docker_unavailable');
-    err.detail = (docker.stderr || docker.stdout || '').trim().slice(0, 400);
-    err.hint = 'Cloudflare Containers require a local container engine for image build.';
-    throw err;
-  }
-
   const wrangler = resolveWranglerInvocation(productRoot);
   let deployOutput = '';
   let deployed = false;
@@ -267,7 +266,12 @@ export async function deployGoCloudflare({
   } else if (dryRun) {
     const res = runWrangler(
       wrangler,
-      deploymentArgs({ dryRun: true, source, builtAt }),
+      deploymentArgs({
+        dryRun: true,
+        source,
+        builtAt,
+        configName,
+      }),
       { productRoot, spawn, accountId },
     );
     deployOutput = res.output;
@@ -280,7 +284,11 @@ export async function deployGoCloudflare({
   } else {
     const res = runWrangler(
       wrangler,
-      deploymentArgs({ source, builtAt }),
+      deploymentArgs({
+        source,
+        builtAt,
+        configName,
+      }),
       { productRoot, spawn, accountId },
     );
     deployOutput = res.output;
@@ -347,7 +355,7 @@ export async function deployGoCloudflare({
 
   const url = deployed
     ? (
-        resolveConfiguredDeploymentUrl(productRoot)
+        resolveConfiguredDeploymentUrl(productRoot, configName)
         || extractWorkersDevUrl(deployOutput)
         || guessWorkersDevUrl(product)
       )
@@ -483,7 +491,6 @@ export async function deployGoCloudflare({
     productPath,
     productRow,
     registry,
-    dockerOk,
     cloudflare: cfIdentity,
     deployOutput,
   };
@@ -499,110 +506,3 @@ export function guessWorkersDevUrl(product) {
   return account ? 'https://' + product + '.' + account + '.workers.dev' : null;
 }
 
-export async function probeGoDeployment(origin, {
-  fetchImpl = globalThis.fetch,
-  expectedSource = null,
-  expectedSourceCommit = null,
-  expectedTarget = null,
-  edge = true,
-} = {}) {
-  const base = String(origin).replace(/\/+$/, '');
-  const results = {};
-  const checks = {};
-  const probedAt = new Date().toISOString();
-
-  async function request(key, pathname, init = {}) {
-    try {
-      const res = await fetchImpl(base + pathname, init);
-      let body = null;
-      try { body = await res.json(); } catch {}
-      results[key] = {
-        path: pathname,
-        status: res.status,
-        ok: res.status >= 200 && res.status < 300,
-        body,
-      };
-      return results[key];
-    } catch (error) {
-      results[key] = { path: pathname, status: 0, ok: false, error: error.message };
-      return results[key];
-    }
-  }
-
-  if (edge) {
-    await request('edge_root', '/', { headers: { Accept: 'application/json' } });
-    await request('edge_health', '/edge/health', { headers: { Accept: 'application/json' } });
-  }
-  await request('health', '/health', { headers: { Accept: 'application/json' } });
-  await request('runtime', '/v1/runtime', { headers: { Accept: 'application/json' } });
-  await request('capabilities', '/v1/capabilities', { headers: { Accept: 'application/json' } });
-  await request('hash', '/v1/hash', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
-    body: JSON.stringify({ input: 'agentsam', algorithm: 'sha256' }),
-  });
-  await request('inspect', '/v1/inspect', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
-    body: JSON.stringify({ files: [{ path: 'demo.css', content: '.button { color: #2563eb; }' }] }),
-  });
-  await request('malformed', '/v1/inspect', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
-    body: JSON.stringify({ not_files: true }),
-  });
-
-  const health = results.health?.body;
-  const runtime = results.runtime?.body;
-  const caps = results.capabilities?.body;
-  const malformed = results.malformed?.body;
-
-  if (edge) {
-    checks.edge_root = results.edge_root?.status === 200 && results.edge_root?.body?.edge === 'worker';
-    checks.edge_health = results.edge_health?.status === 200 && results.edge_health?.body?.edge === 'worker';
-    checks.edge_source = expectedSource
-      ? results.edge_root?.body?.source === expectedSource
-      : true;
-  }
-  checks.health = results.health?.status === 200
-    && health?.ok === true
-    && health?.runtime === 'go'
-    && (!expectedTarget || health?.target === expectedTarget);
-  checks.source_identity = expectedSource ? health?.build?.source === expectedSource : true;
-  checks.source_commit = expectedSourceCommit ? health?.build?.commit === expectedSourceCommit : true;
-  checks.runtime = results.runtime?.status === 200
-    && runtime?.schema === 'agentsam.go-runtime.v1'
-    && runtime?.os === 'linux';
-  checks.capabilities = results.capabilities?.status === 200
-    && caps?.schema === 'agentsam.go-capabilities.v1'
-    && ['hash', 'inspect', 'runtime', 'capabilities'].every((name) => caps?.capabilities?.includes(name));
-  checks.hash = results.hash?.status === 200 && results.hash?.body?.hash === EXPECTED_HASH;
-  checks.inspect = results.inspect?.status === 200
-    && results.inspect?.body?.findings?.some((finding) => finding.kind === 'hardcoded_color' && finding.value === '#2563eb');
-  checks.error_envelope = results.malformed?.status === 400
-    && malformed?.ok === false
-    && malformed?.schema_version === 1
-    && malformed?.reason === 'input_invalid'
-    && malformed?.code === 'INVALID_ARGUMENT';
-
-  results.deterministic_hash = { ok: checks.hash };
-  results.deterministic_inspect = { ok: checks.inspect };
-  results.malformed_rejected = { ok: checks.error_envelope };
-  const ok = Object.values(checks).every(Boolean);
-  return { origin: base, ok, checks, results, probed_at: probedAt };
-}
-
-export async function probeGoDeploymentWithRetry(origin, {
-  attempts = 12,
-  delayMs = 2500,
-  ...options
-} = {}) {
-  let latest = null;
-  for (let attempt = 1; attempt <= attempts; attempt += 1) {
-    latest = await probeGoDeployment(origin, options);
-    latest.attempt = attempt;
-    if (latest.ok) return latest;
-    if (attempt < attempts) await new Promise((resolve) => setTimeout(resolve, delayMs));
-  }
-  return latest || { origin, ok: false, checks: {}, results: {}, probed_at: new Date().toISOString() };
-}

package/src/go/verify.js

@@ -1,5 +1,5 @@
 import { readLatestStatus } from './receipts.js';
-import { probeGoDeployment } from './cloudflare.js';
+import { probeGoDeployment } from './probe.js';
 import { runGoTests, runGoVet } from './build.js';
 
 export async function verifyGoProduct({

package/src/indexing/ingest/inventory.js

@@ -57,7 +57,7 @@ const CATEGORY_TOOLING = new Set([
 /** Generated / historical — review before including. */
 const CATEGORY_GENERATED = new Set([
   'generated', 'fixtures', 'snapshots', 'artifacts',
-  'site', 'sites', 'templates', 'level-1', 'focus-timer',
+  'site', 'sites', 'templates', 'level-1',
 ]);
 
 /** AgentSam / config control plane — review. */

package/src/lib/deploy/local-studio.js

@@ -12,7 +12,7 @@ export const DEPLOY_INPUT_GLOBS = Object.freeze([
   'apps/local-studio',
   'packages/agentsam-contracts',
   'packages/agentsam-workbench',
-  'packages/connectors/cloudflare',
+  'packages/connectors/cfoa',
 ]);
 
 export function findRepoRoot(start = process.cwd()) {
@@ -176,7 +176,7 @@ export async function runLocalStudioDeploy({
       target.wranglerConfig,
       path.join(target.appRoot, '.env.cloudflare.example'),
       path.join(target.appRoot, 'backend/worker/index.js'),
-      path.join(target.repoRoot, 'packages/connectors/cloudflare/src/index.js'),
+      path.join(target.repoRoot, 'packages/connectors/cfoa/src/index.js'),
     ]);
   }
   if (plan.skip) {

package/src/lib/mini/scaffold.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 
 const templateRoot = fileURLToPath(new URL('../../../templates/mini/', import.meta.url));
 export const MINI_TEMPLATES = Object.freeze({
-  gadget: 'A working focus timer',
+  gadget: 'A blank interactive widget canvas',
   page: 'A small editable landing page',
   data: 'A searchable JSON viewer',
 });

package/src/lib/whoami-capabilities.js

@@ -9,7 +9,7 @@ import { listProviderCredentialStatus } from './provider-credentials.js';
 import {
   listCloudflareFeaturePacks,
   scopesForFeaturePacks,
-} from '../../packages/connectors/cloudflare/src/index.js';
+} from '../../packages/connectors/cfoa/src/index.js';
 import { projectTerminalCapability } from './terminal-scopes.js';
 
 function clean(value) {

package/src/local/runtime-store.js

@@ -5,6 +5,7 @@ import { applyRuntimeMigrations } from './migrations.js';
 import { findCliProjectRoot } from '../lib/cli-preferences.js';
 import { getLocalDatabasePath, tryReadProjectConfig } from '../lib/project-config.js';
 import { createHookStore } from '../../packages/agentsam-hooks/src/store.js';
+import { reconcileParentAfterChildTerminal } from '../acp/dependencies.js';
 
 function clean(value) { return value == null ? '' : String(value).trim(); }
 function hash(value) { return createHash('sha256').update(String(value || '')).digest('hex'); }
@@ -115,6 +116,13 @@ export async function finishRuntimeRun(value = {}) {
       Number.isFinite(Number(value.latency_ms)) ? Math.max(0, Math.round(Number(value.latency_ms))) : null,
       value.id,
     ).run();
+
+    await reconcileParentAfterChildTerminal(db, {
+      runId: value.id,
+      status: clean(value.status) || 'completed',
+      errorCode: clean(value.error_code) || null,
+      errorMessage: clean(value.error_message) || null,
+    });
   });
 }
 

package/src/mcp/cloudflare-bundles.js

@@ -9,7 +9,7 @@
 import {
   scopesForCapabilities,
   scopesForFeaturePacks,
-} from '../../packages/connectors/cloudflare/src/capabilities.js';
+} from '../../packages/connectors/cfoa/src/capabilities.js';
 
 /**
  * @typedef {object} CloudflareMcpBundle

package/src/plugins/index.js

@@ -9,6 +9,7 @@ export {
   installPlugin,
   listPlugins,
   listPluginTools,
+  updatePluginPreferences,
   recordPluginHealthCheck,
   recordAiPluginModelDiscovery,
   recordToolCall,

package/src/plugins/registry.js

@@ -42,9 +42,11 @@ export async function installPlugin(db, options = {}) {
         provider_key=?, plugin_kind=?, category=?, display_name=?, short_name=?, description=?, mention_aliases_json=?,
         endpoint_url=?, transport=?, auth_type=?, secret_ref=?, oauth_connect_url=?, capabilities_json=?, tool_lanes_json=?,
         resource_scope_json=?, config_json=?, metadata_json=?, icon_url=?, icon_dark_url=?, icon_alt=?, icon_fit=?,
-        composer_visible=?, settings_visible=?, sort_priority=?, health_strategy=?, is_enabled=1, updated_at=unixepoch()
+        composer_visible=?, settings_visible=?, sort_priority=?, health_strategy=?,
+        is_enabled=CASE WHEN ? THEN is_enabled ELSE 1 END,
+        updated_at=unixepoch()
       WHERE id=?
-    `, [...values, pluginId]);
+    `, [...values, options.preserveEnabled === true ? 1 : 0, pluginId]);
   } else {
     await runMutation(db, `
       INSERT INTO agentsam_plugins (
@@ -122,11 +124,13 @@ export async function installPlugin(db, options = {}) {
 export async function listPlugins(db, options = {}) {
   const accountId = clean(options.accountId);
   const environment = clean(options.environment || 'production');
+  const includeDisabled = options.includeDisabled === true;
   const result = await db.prepare(`
     SELECT * FROM agentsam_plugins
-    WHERE account_id = ? AND environment = ? AND is_enabled = 1
+    WHERE account_id = ? AND environment = ?
+      AND (? = 1 OR is_enabled = 1)
     ORDER BY sort_priority, display_name
-  `).bind(accountId, environment).all();
+  `).bind(accountId, environment, includeDisabled ? 1 : 0).all();
   return (result?.results || []).map((row) => ({
     ...row,
     mention_aliases: json(row.mention_aliases_json, []), capabilities: json(row.capabilities_json, []),
@@ -137,18 +141,67 @@ export async function listPlugins(db, options = {}) {
 
 export async function listPluginTools(db, options = {}) {
   const accountId = clean(options.accountId);
+  const includeDisabledPlugins = options.includeDisabledPlugins === true;
   const result = await db.prepare(`
     SELECT t.* FROM agentsam_tools t
     JOIN agentsam_plugins p ON p.id = t.plugin_id
-    WHERE t.account_id = ? AND t.is_active = 1 AND p.is_enabled = 1
+    WHERE t.account_id = ? AND t.is_active = 1
+      AND (? = 1 OR p.is_enabled = 1)
     ORDER BY t.connector_priority, t.sort_priority, t.tool_name
-  `).bind(accountId).all();
+  `).bind(accountId, includeDisabledPlugins ? 1 : 0).all();
   return (result?.results || []).map((row) => ({
     ...row, input_schema: json(row.input_schema, {}), output_schema: json(row.output_schema, null),
     handler_config: json(row.handler_config, {}), intent_tags: json(row.intent_tags, []),
   }));
 }
 
+
+export async function updatePluginPreferences(db, options = {}) {
+  if (!db?.prepare) throw new TypeError('D1-compatible database binding required');
+  const accountId = clean(options.accountId);
+  const pluginId = clean(options.pluginId);
+  if (!accountId) throw new Error('plugin_account_id_required');
+  if (!pluginId) throw new Error('plugin_id_required');
+
+  const fields = [];
+  const values = [];
+  if (typeof options.enabled === 'boolean') {
+    fields.push('is_enabled=?');
+    values.push(options.enabled ? 1 : 0);
+  }
+  if (typeof options.composerVisible === 'boolean') {
+    fields.push('composer_visible=?');
+    values.push(options.composerVisible ? 1 : 0);
+  }
+  if (typeof options.settingsVisible === 'boolean') {
+    fields.push('settings_visible=?');
+    values.push(options.settingsVisible ? 1 : 0);
+  }
+  if (!fields.length) throw new Error('plugin_preferences_empty');
+
+  await runMutation(db, `
+    UPDATE agentsam_plugins
+    SET ${fields.join(', ')}, updated_at=unixepoch()
+    WHERE id=? AND account_id=?
+  `, [...values, pluginId, accountId]);
+
+  const row = await db.prepare(`
+    SELECT * FROM agentsam_plugins
+    WHERE id=? AND account_id=?
+    LIMIT 1
+  `).bind(pluginId, accountId).first();
+  if (!row) throw new Error('plugin_not_found');
+  return {
+    ...row,
+    mention_aliases: json(row.mention_aliases_json, []),
+    capabilities: json(row.capabilities_json, []),
+    tool_lanes: json(row.tool_lanes_json, []),
+    resource_scope: json(row.resource_scope_json, {}),
+    config: json(row.config_json, {}),
+    metadata: json(row.metadata_json, {}),
+  };
+}
+
 export async function recordPluginHealthCheck(db, value = {}) {
   const startedAt = Number(value.startedAt || Math.floor(Date.now() / 1000));
   const completedAt = Number(value.completedAt || Math.floor(Date.now() / 1000));

package/src/receipts/contract.js

@@ -0,0 +1,68 @@
+export const RECEIPT_ENVELOPE_SCHEMA = "agentsam.receipt.v1";
+export const SCHEMA_BASE_URL = "https://schemas.inneranimalmedia.com";
+export const SCHEMAS_BUCKET_NAME = "inneranimalmedia-schemas";
+export const RECEIPT_SCHEMA_URL =
+  `${SCHEMA_BASE_URL}/agentsam/schemas/agentsam.receipt.v1.json`;
+export const RECEIPT_R2_PREFIX = "agentsam/runtime/receipts/v1";
+export const BLOB_R2_PREFIX = "agentsam/runtime/blobs/sha256";
+
+export function validateReceiptEnvelope(receipt) {
+  const errors = [];
+  if (!receipt || typeof receipt !== "object") {
+    return { ok: false, errors: ["receipt must be an object"] };
+  }
+  if (receipt.schema !== RECEIPT_ENVELOPE_SCHEMA) {
+    errors.push(`schema must be ${RECEIPT_ENVELOPE_SCHEMA}`);
+  }
+  if (!receipt.receipt_id) errors.push("receipt_id is required");
+  if (!receipt.kind) errors.push("kind is required");
+  if (!["passed", "failed", "skipped"].includes(receipt.status)) {
+    errors.push("status must be passed, failed, or skipped");
+  }
+  if (
+    !["ephemeral_success", "failure_bundle", "release_proof"].includes(
+      receipt.retention_class,
+    )
+  ) {
+    errors.push("retention_class is invalid");
+  }
+  if (!receipt.identity?.account_id) {
+    errors.push("identity.account_id is required");
+  }
+  if (!Number.isFinite(Number(receipt.metrics?.created_at_unix))) {
+    errors.push("metrics.created_at_unix is required");
+  }
+  for (const artifact of receipt.evidence?.artifacts || []) {
+    if (
+      artifact.r2_key &&
+      !String(artifact.r2_key).startsWith(`${BLOB_R2_PREFIX}/`)
+    ) {
+      errors.push(
+        `artifact r2_key must start with ${BLOB_R2_PREFIX}/`,
+      );
+    }
+  }
+  return Object.freeze({ ok: errors.length === 0, errors: Object.freeze(errors) });
+}
+
+export function receiptDatePrefix(receipt) {
+  const unix = Number(receipt?.metrics?.created_at_unix);
+  if (!Number.isFinite(unix) || unix < 0) {
+    throw new TypeError("receipt.metrics.created_at_unix is required");
+  }
+  return new Date(unix * 1000).toISOString().slice(0, 10).replace(/-/g, "/");
+}
+
+export function receiptR2Key(receipt) {
+  return `${RECEIPT_R2_PREFIX}/${receiptDatePrefix(receipt)}/${receipt.receipt_id}.json`;
+}
+
+export function retentionExpiresAt(receipt, nowUnix = Math.floor(Date.now() / 1000)) {
+  if (receipt.retention_class === "ephemeral_success") {
+    return nowUnix + 7 * 86400;
+  }
+  if (receipt.retention_class === "failure_bundle") {
+    return nowUnix + 60 * 86400;
+  }
+  return null;
+}

package/src/receipts/index.js

@@ -0,0 +1,20 @@
+export {
+  BLOB_R2_PREFIX,
+  RECEIPT_ENVELOPE_SCHEMA,
+  RECEIPT_R2_PREFIX,
+  RECEIPT_SCHEMA_URL,
+  SCHEMA_BASE_URL,
+  SCHEMAS_BUCKET_NAME,
+  receiptDatePrefix,
+  receiptR2Key,
+  retentionExpiresAt,
+  validateReceiptEnvelope,
+} from "./contract.js";
+export {
+  CompositeReceiptSink,
+  D1ReceiptCatalog,
+  LocalReceiptSink,
+  R2ReceiptSink,
+  ReceiptCatalogReader,
+} from "./sinks.js";
+export { pruneLocalWorkspaces } from "./prune.js";

package/src/receipts/prune.js

@@ -0,0 +1,64 @@
+import { readdir, rm, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+async function directorySize(root) {
+  let total = 0;
+  const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    const full = path.join(root, entry.name);
+    if (entry.isDirectory()) total += await directorySize(full);
+    else if (entry.isFile()) total += (await stat(full)).size;
+  }
+  return total;
+}
+
+export async function pruneLocalWorkspaces({
+  maxTmpGb = 1,
+  tmpDir = os.tmpdir(),
+  prefix = "agentsam-",
+  dryRun = false,
+  detailLimit = 100,
+} = {}) {
+  const maxBytes = Math.max(0, Number(maxTmpGb)) * 1024 * 1024 * 1024;
+  const entries = await readdir(tmpDir, { withFileTypes: true });
+  const targets = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.startsWith(prefix)) continue;
+    const fullPath = path.join(tmpDir, entry.name);
+    const info = await stat(fullPath);
+    const byteSize = await directorySize(fullPath);
+    targets.push({ path: fullPath, mtime: info.mtimeMs, byteSize });
+  }
+
+  targets.sort((a, b) => a.mtime - b.mtime);
+  let remainingBytes = targets.reduce((sum, target) => sum + target.byteSize, 0);
+  const purged = [];
+
+  for (const target of targets) {
+    if (remainingBytes <= maxBytes) break;
+    if (!dryRun) {
+      await rm(target.path, { recursive: true, force: true });
+    }
+    remainingBytes -= target.byteSize;
+    purged.push(target);
+  }
+
+  const boundedDetailLimit = Math.max(0, Math.min(1000, Number(detailLimit) || 0));
+  const purgeDetails = purged
+    .slice(0, boundedDetailLimit)
+    .map((item) => Object.freeze({ ...item }));
+
+  return Object.freeze({
+    maxBytes,
+    scannedCount: targets.length,
+    purgedCount: purged.length,
+    purgedBytes: purged.reduce((sum, item) => sum + item.byteSize, 0),
+    remainingBytes: Math.max(0, remainingBytes),
+    dryRun,
+    purged: Object.freeze(purgeDetails),
+    purgedDetailLimit: boundedDetailLimit,
+    purgedDetailsTruncated: purged.length > purgeDetails.length,
+  });
+}