@falari/harness 0.0.0-stage → 0.8.9

package/lib/service.js

@@ -0,0 +1,1429 @@
+/**
+ * FalariDataService — the single business entry point shared by the Agent
+ * tools and the Web settings/panel routes.
+ *
+ * Credentials: the Agent Key lives in the DSH credential store as the record
+ * `falari-harness/agent-key`; it never reaches the browser and never enters
+ * plugin configuration.
+ *
+ * Transfers: uploads go through the SDK's persistent upload queue so a task
+ * survives a Host restart, and the queue driver started here advances it.
+ */
+import { randomUUID } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdir, readFile, readdir, realpath, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, parse as parsePath, relative, resolve, sep } from 'node:path';
+
+import { DURATION_NAMES, validateConfigPatch } from './config.js';
+import { ServiceError, errorText, publicError as toPublicError } from './errors.js';
+import { MIN_PIN_LENGTH, PinError, isSealed, openSecret, sealSecret, validatePin } from './pin.js';
+import { sdk } from './sdk.js';
+
+const RECORD_KEY = 'falari-harness/agent-key';
+const TEMP_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+/** The chain's `max_intent_duration_seconds`: 100 years. */
+const MAX_DURATION_SECONDS = 3_153_600_000;
+/** Chain permanent window (30 years) plus its 20% reserve: 36 years. */
+const PERMANENT_CAP_SECONDS = 946_080_000 + (946_080_000 * 20) / 100;
+
+/** A cached status older than this triggers a background chain read. */
+const STATUS_REFRESH_AFTER_SECONDS = 15;
+/** Wrong-PIN budget: five misses cost a 30 second pause, then it resets. */
+const PIN_MAX_FAILURES = 5;
+const PIN_BLOCK_MS = 30 * 1000;
+/** A start code rotation clears the in-memory secret. */
+const PIN_ATTEMPT_WINDOW_MS = 10 * 60 * 1000;
+
+/**
+ * One live service per process. A plugin row reload constructs a new service
+ * while the previous one may still have an upload tick in flight; two drivers on
+ * the same queue sign batch commits against the same account sequence, and the
+ * chain rejects the loser with code 32. Retiring the old instance first keeps a
+ * single writer.
+ */
+let activeService = null;
+
+/**
+ * The decrypted key outlives one service instance but not the process.
+ *
+ * A plugin row reload (saving settings, toggling the bundle, reinstalling)
+ * constructs a new service; without this the user had to retype the PIN for a
+ * change that never touched the key. The vault is keyed by the sealed record's
+ * ciphertext, so a different key — or a key re-sealed under a new PIN — is never
+ * adopted. Process exit clears it; nothing here touches disk.
+ */
+const processVault = { key: null, ct: '', lastUsedAt: 0, unlockedAt: 0 };
+
+function normalizeAgentKey(raw) {
+  const cleaned = String(raw ?? '').replace(/\s+/g, '');
+  if (!/^far_[A-Za-z0-9_-]+$/.test(cleaned)) {
+    throw new ServiceError(
+      'invalid_key_format',
+      'Agent Key must start with "far_" and contain only base64url characters.',
+      'Copy the complete export string from the Falari wallet; do not add spaces or punctuation.',
+    );
+  }
+  try {
+    sdk.loadAgentIdentity(cleaned);
+  } catch (error) {
+    throw new ServiceError(
+      'invalid_key_format',
+      error && error.message ? error.message : 'Agent Key is not a valid far_ export string.',
+      'The string may be truncated. Copy the complete key again, or export it once more from the wallet.',
+    );
+  }
+  return cleaned;
+}
+
+function wei(value) {
+  const text = String(value ?? '0').trim();
+  return /^-?\d+$/.test(text) ? BigInt(text) : 0n;
+}
+
+function isActiveStatus(status) {
+  return status === 'creating' || status === 'queued' || status === 'uploading';
+}
+
+function isFinishedStatus(status) {
+  return status === 'completed' || status === 'terminated';
+}
+
+export class FalariDataService {
+  constructor(ctx, config, credentials) {
+    this.ctx = ctx;
+    this.config = config;
+    this.credentials = credentials;
+    this.log = ctx.logger;
+    this.agent = null;
+    this.agentKey = null;
+    this.driverAgent = null;
+    this.tempFiles = new Map();
+    this.dataKeys = new Map();
+    this.downloads = new Map();
+    this.statusCache = null;
+    this.statusRefresh = null;
+    // The decrypted far_ string never leaves this process and never touches disk.
+    this.unlockedKey = null;
+    this.unlockedAt = 0;
+    this.lastUsedAt = 0;
+    this.pinFailures = 0;
+    this.pinBlockedUntil = 0;
+    if (activeService && activeService !== this) {
+      try {
+        activeService.dispose();
+      } catch {
+        // an old instance that cannot be disposed must not stop the new one
+      }
+    }
+    activeService = this;
+  }
+
+  // ── lifecycle ──────────────────────────────────────────────────────────
+
+  async start() {
+    await mkdir(this.tempDir, { recursive: true, mode: 0o700 });
+    await this.cleanTemps();
+    try {
+      // A sealed key stays sealed across a Host restart: nothing to start until
+      // the user types the PIN.
+      const state = await this.readKeyState();
+      if (state.mode === 'legacy' && state.key) {
+        const agent = await this.getAgent(state.key);
+        this.startDriver(agent);
+      }
+    } catch (error) {
+      this.log?.warn?.(`falari-harness: stored Agent Key could not be used at startup: ${errorText(error)}`);
+    }
+  }
+
+  dispose() {
+    if (activeService === this) activeService = null;
+    this.stopDriver();
+    this.agent = null;
+    this.agentKey = null;
+    this.tempFiles.clear();
+    this.dataKeys.clear();
+    this.downloads.clear();
+  }
+
+  get tempDir() {
+    return join(this.config.dataDir, 'tmp');
+  }
+
+  get keyringDir() {
+    return join(this.config.dataDir, 'keyring');
+  }
+
+  get downloadDir() {
+    return this.config.downloadDir || join(this.config.dataDir, 'downloads');
+  }
+
+  // ── credentials ────────────────────────────────────────────────────────
+
+  /**
+   * What the credentials store holds: nothing, a sealed secret, or the legacy
+   * plaintext record this plugin used before PINs existed.
+   */
+  async readKeyState() {
+    const record = await this.credentials.readRecord(RECORD_KEY);
+    if (!record || record.kind !== 'api-key') return { mode: 'none', locked: false };
+    if (isSealed(record)) {
+      // Adopt a still-fresh in-process unlock after a row reload.
+      if (!this.unlockedKey && processVault.key && processVault.ct && processVault.ct === record.ct) {
+        this.unlockedKey = processVault.key;
+        this.lastUsedAt = processVault.lastUsedAt;
+        this.unlockedAt = processVault.unlockedAt;
+      }
+      const expired = this.unlockedKey && this.idleExpired();
+      if (expired) {
+        if (await this.hasActiveUploads()) {
+          // An upload in progress is activity; restart the idle clock instead.
+          this.touch();
+        } else {
+          this.lock(`idle for ${this.idleMinutes()} minutes`);
+        }
+      }
+      const unlocked = Boolean(this.unlockedKey);
+      if (unlocked) this.touch();
+      return { mode: 'sealed', locked: !unlocked, key: unlocked ? this.unlockedKey : null, record };
+    }
+    const key = typeof record.key === 'string' ? record.key.trim() : '';
+    return key ? { mode: 'legacy', locked: false, key, record } : { mode: 'none', locked: false };
+  }
+
+  /** Plaintext key when one is available, else null (sealed and locked). */
+  async readStoredKey() {
+    const state = await this.readKeyState();
+    return state.key || null;
+  }
+
+  idleMinutes() {
+    const value = Number(this.config.lockIdleMinutes);
+    return Number.isFinite(value) && value > 0 ? value : 0;
+  }
+
+  /**
+   * True while any upload is queued or in flight. The auto-lock counts this as
+   * activity: locking mid-upload would stop the driver and strand a paid task
+   * until the user typed the PIN again.
+   */
+  async hasActiveUploads() {
+    const active = (row) => ['creating', 'queued', 'uploading'].includes(String(row && row.status ? row.status : ''));
+    if (this.agent) {
+      try {
+        const rows = await this.agent.uploadTasks();
+        if (Array.isArray(rows) && rows.some(active)) return true;
+      } catch {
+        // fall through to the ledger on disk
+      }
+    }
+    try {
+      const raw = await readFile(join(this.config.dataDir, 'upload-queue.json'), 'utf8');
+      const rows = JSON.parse(raw);
+      return Array.isArray(rows) && rows.some(active);
+    } catch {
+      return false;
+    }
+  }
+
+  idleExpired() {
+    const minutes = this.idleMinutes();
+    if (!minutes || !this.lastUsedAt) return false;
+    return Date.now() - this.lastUsedAt > minutes * 60 * 1000;
+  }
+
+  touch() {
+    this.lastUsedAt = Date.now();
+    if (this.unlockedKey) processVault.lastUsedAt = this.lastUsedAt;
+  }
+
+  /** Remember (or forget) the decrypted key for later service instances. */
+  rememberUnlocked(key, recordCt) {
+    processVault.key = key;
+    processVault.ct = recordCt || '';
+    processVault.unlockedAt = Date.now();
+    processVault.lastUsedAt = Date.now();
+  }
+
+  forgetUnlocked() {
+    processVault.key = null;
+    processVault.ct = '';
+    processVault.unlockedAt = 0;
+    processVault.lastUsedAt = 0;
+  }
+
+  /** Drop the plaintext secret and stop the queue that would need it. */
+  lock(reason = 'manual') {
+    const wasUnlocked = Boolean(this.unlockedKey);
+    this.forgetUnlocked();
+    this.unlockedKey = null;
+    this.unlockedAt = 0;
+    this.lastUsedAt = 0;
+    this.agent = null;
+    this.agentKey = null;
+    this.stopDriver();
+    if (wasUnlocked && reason) this.log?.debug?.(`falari-harness: Agent Key locked (${reason})`);
+    return wasUnlocked;
+  }
+
+  lockState() {
+    const remaining = this.pinBlockedUntil > Date.now() ? Math.ceil((this.pinBlockedUntil - Date.now()) / 1000) : 0;
+    return {
+      minPinLength: MIN_PIN_LENGTH,
+      idleMinutes: this.idleMinutes(),
+      attemptsLeft: Math.max(0, PIN_MAX_FAILURES - this.pinFailures),
+      retryAfterSeconds: remaining,
+    };
+  }
+
+  /** Decrypt the sealed key into memory; a wrong PIN is counted and rate limited. */
+  async unlock(pin) {
+    const now = Date.now();
+    if (this.pinBlockedUntil > now) {
+      throw new ServiceError(
+        'pin_blocked',
+        `Too many wrong PIN attempts. Wait ${Math.ceil((this.pinBlockedUntil - now) / 1000)} seconds.`,
+        'The stored key is safe; the delay only slows down guessing.',
+      );
+    }
+    const record = await this.credentials.readRecord(RECORD_KEY);
+    if (!record || !isSealed(record)) {
+      throw new ServiceError('no_sealed_key', 'No PIN-protected Agent Key is stored.', 'Save an Agent Key with a PIN first.');
+    }
+    let key;
+    try {
+      key = await openSecret(record, pin);
+    } catch (error) {
+      this.pinFailures += 1;
+      if (this.pinFailures >= PIN_MAX_FAILURES) {
+        this.pinFailures = 0;
+        this.pinBlockedUntil = Date.now() + PIN_BLOCK_MS;
+      }
+      throw new ServiceError(
+        'wrong_pin',
+        error instanceof PinError ? error.message : 'That PIN does not open this key.',
+        `Wrong PIN. ${this.lockState().attemptsLeft} attempt(s) left before a 30 second pause.`,
+      );
+    }
+    if (!/^far_[A-Za-z0-9_-]+$/.test(String(key).trim())) {
+      throw new ServiceError('invalid_key_format', 'The stored key is not an Agent Key export string.');
+    }
+    this.unlockedKey = String(key).trim();
+    this.unlockedAt = Date.now();
+    this.pinFailures = 0;
+    this.pinBlockedUntil = 0;
+    this.rememberUnlocked(this.unlockedKey, String(record.ct || ''));
+    this.touch();
+    const agent = await this.getAgent(this.unlockedKey);
+    this.startDriver(agent);
+    try {
+      const status = await agent.status();
+      const view = this.keyStatusFrom(status);
+      await this.writeStatusCache(this.unlockedKey, view);
+      return { ...view, security: await this.securityView() };
+    } catch {
+      // The key opened: a chain hiccup is reported by the status card, not here.
+      return { configured: true, network: this.config.network, security: await this.securityView() };
+    }
+  }
+
+  /** Seal the legacy plaintext record under a PIN, then unlock it. */
+  async secureLegacyKey(pin) {
+    validatePin(pin);
+    const record = await this.credentials.readRecord(RECORD_KEY);
+    if (!record) throw new ServiceError('no_agent_key', 'No Agent Key is stored yet.');
+    if (isSealed(record)) throw new ServiceError('already_sealed', 'This key is already protected by a PIN.');
+    const legacy = typeof record.key === 'string' ? record.key.trim() : '';
+    if (!legacy) throw new ServiceError('no_agent_key', 'No Agent Key is stored yet.');
+    const sealed = await sealSecret(legacy, pin);
+    await this.credentials.modifyRecord(RECORD_KEY, async () => ({ kind: 'api-key', ...sealed }));
+    this.unlockedKey = legacy;
+    this.unlockedAt = Date.now();
+    this.rememberUnlocked(legacy, String(sealed.ct || ''));
+    this.touch();
+    try {
+      this.startDriver(await this.getAgent(legacy));
+    } catch {
+      // Starting the queue is a convenience; a chain hiccup is not a save failure.
+    }
+    return { rotated: true, security: await this.securityView() };
+  }
+
+  /** What the UI needs to know about the stored secret, without the secret. */
+  async securityView() {
+    const state = await this.readKeyState();
+    return {
+      mode: state.mode,
+      locked: state.mode === 'sealed' ? state.locked : false,
+      requiresPinSetup: state.mode === 'legacy',
+      uploadActive: await this.hasActiveUploads(),
+      ...this.lockState(),
+    };
+  }
+
+  async getAgent(rawKey) {
+    if (this.agent && this.agentKey === rawKey) return this.agent;
+    this.stopDriver();
+    await mkdir(this.config.dataDir, { recursive: true, mode: 0o700 });
+    const options = {
+      agentKey: rawKey,
+      network: this.config.network,
+      timeoutMs: this.config.timeoutMs,
+      keyringDir: this.keyringDir,
+      uploadQueueFile: join(this.config.dataDir, 'upload-queue.json'),
+      defaultPrivacy: this.config.defaultPrivacy,
+    };
+    if (this.config.gatewayUrl) options.gatewayUrl = this.config.gatewayUrl;
+    if (this.config.retrievalUrl) options.retrievalUrl = this.config.retrievalUrl;
+    if (this.config.explorerUrl) options.explorerUrl = this.config.explorerUrl;
+    const agent = new sdk.FalariAgent(options);
+    this.agent = agent;
+    this.agentKey = rawKey;
+    return agent;
+  }
+
+  async ensureAgent() {
+    const state = await this.readKeyState();
+    if (state.mode === 'none') {
+      throw new ServiceError(
+        'no_agent_key',
+        'No Falari Agent Key is configured.',
+        'Open the plugin page (Plugins → Falari Data → Configure) and paste a far_ export string.',
+      );
+    }
+    if (state.mode === 'legacy') {
+      throw new ServiceError(
+        'pin_required',
+        'The stored Agent Key is still plain text. Set a PIN to encrypt it before uploading.',
+        'Open the plugin page, Settings → Agent Key, and set a PIN. The key is re-encrypted in place; nothing is uploaded.',
+      );
+    }
+    if (state.locked || !state.key) {
+      throw new ServiceError(
+        'agent_key_locked',
+        'The Agent Key is locked. Enter your PIN in the plugin panel to unlock it.',
+        'The key stays encrypted on disk; the PIN is only held in memory.',
+      );
+    }
+    return this.getAgent(state.key);
+  }
+
+  async configureKey(rawKey, pin) {
+    const cleaned = normalizeAgentKey(rawKey);
+    // A key without a PIN would be stored in clear text, which other plugins can
+    // read; refuse it instead of quietly weakening the profile.
+    validatePin(pin);
+    const agent = await this.getAgent(cleaned);
+    const status = await agent.status();
+    if (!status.agentKey) {
+      throw new ServiceError(
+        'agent_key_not_registered',
+        `This key is not registered under its master account on ${this.config.network}.`,
+        'Check that this far_ string belongs to a key created on the same network, and that it has not been revoked.',
+      );
+    }
+    const sealed = await sealSecret(cleaned, pin);
+    await this.credentials.modifyRecord(RECORD_KEY, async () => ({ kind: 'api-key', ...sealed }));
+    this.unlockedKey = cleaned;
+    this.unlockedAt = Date.now();
+    this.pinFailures = 0;
+    this.pinBlockedUntil = 0;
+    this.rememberUnlocked(cleaned, String(sealed.ct || ''));
+    this.touch();
+    this.startDriver(agent);
+    const view = this.keyStatusFrom(status);
+    await this.writeStatusCache(cleaned, view);
+    return { ...view, security: await this.securityView() };
+  }
+
+  /**
+   * Read the key status, preferring the cached view so a page open is instant.
+   *
+   * The cache is written after every real chain read and reused until it ages
+   * past STATUS_REFRESH_AFTER_SECONDS; a stale hit kicks off one background
+   * refresh, so the next poll returns the newer numbers.
+   */
+  async keyStatus(options = {}) {
+    const security = await this.securityView();
+    if (security.mode === 'none') {
+      this.statusCache = null;
+      return { configured: false, network: this.config.network, security };
+    }
+    if (security.mode === 'legacy') {
+      return { configured: true, locked: false, security, network: this.config.network, requiresPinSetup: true };
+    }
+    if (security.locked) {
+      return { configured: true, locked: true, security, network: this.config.network };
+    }
+    const rawKey = await this.readStoredKey();
+    if (!rawKey) {
+      return { configured: true, locked: true, security, network: this.config.network };
+    }
+
+    let fingerprint;
+    try {
+      fingerprint = statusFingerprint(sdk.loadAgentIdentity(rawKey), this.config.network);
+    } catch (error) {
+      return {
+        configured: true,
+        healthy: false,
+        network: this.config.network,
+        error: toPublicError(error),
+        checkedAt: new Date().toISOString(),
+      };
+    }
+
+    const cached = await this.readStatusCache(fingerprint);
+    if (!cached || options.refresh === true) {
+      return { ...(await this.refreshStatus(rawKey, fingerprint, cached)), security };
+    }
+
+    const age = Math.floor(Date.now() / 1000) - cached.at;
+    if (age > STATUS_REFRESH_AFTER_SECONDS) this.scheduleStatusRefresh(rawKey, fingerprint);
+    return { ...cached.view, cached: true, cachedAt: cached.at, ageSeconds: age, security };
+  }
+
+  /** One real chain read. Writes the cache on success and keeps it on failure. */
+  async refreshStatus(rawKey, fingerprint, cached) {
+    try {
+      const agent = await this.getAgent(rawKey);
+      const status = await agent.status();
+      this.startDriver(agent);
+      const view = this.keyStatusFrom(status);
+      await this.writeStatusCache(rawKey, view, fingerprint);
+      return view;
+    } catch (error) {
+      const failure = toPublicError(error);
+      if (cached) {
+        // Keep the last good numbers on screen; report the failed read beside them.
+        return { ...cached.view, cached: true, cachedAt: cached.at, refreshError: failure };
+      }
+      return {
+        configured: true,
+        healthy: false,
+        network: this.config.network,
+        error: failure,
+        checkedAt: new Date().toISOString(),
+      };
+    }
+  }
+
+  scheduleStatusRefresh(rawKey, fingerprint) {
+    if (this.statusRefresh) return;
+    const run = this.refreshStatus(rawKey, fingerprint, this.statusCache && this.statusCache.fingerprint === fingerprint ? this.statusCache : null)
+      .catch(() => undefined)
+      .finally(() => {
+        if (this.statusRefresh === run) this.statusRefresh = null;
+      });
+    this.statusRefresh = run;
+  }
+
+  get statusCacheFile() {
+    return join(this.config.dataDir, 'status-cache.json');
+  }
+
+  async readStatusCache(fingerprint) {
+    if (this.statusCache && this.statusCache.fingerprint === fingerprint) return this.statusCache;
+    try {
+      const parsed = JSON.parse(await readFile(this.statusCacheFile, 'utf8'));
+      if (parsed && parsed.fingerprint === fingerprint && parsed.view) {
+        this.statusCache = parsed;
+        return parsed;
+      }
+    } catch {
+      // no cache yet, or it belongs to another key or network
+    }
+    return null;
+  }
+
+  async writeStatusCache(rawKey, view, fingerprint) {
+    let id;
+    try {
+      id = fingerprint || statusFingerprint(sdk.loadAgentIdentity(rawKey), this.config.network);
+    } catch {
+      return;
+    }
+    const entry = { fingerprint: id, at: Math.floor(Date.now() / 1000), view };
+    this.statusCache = entry;
+    try {
+      await mkdir(dirname(this.statusCacheFile), { recursive: true, mode: 0o700 });
+      await writeFile(this.statusCacheFile, JSON.stringify(entry, null, 2), { mode: 0o600 });
+    } catch {
+      // a read-only data directory only costs the cross-restart warm start
+    }
+  }
+
+  async clearKey() {
+    this.forgetUnlocked();
+    this.unlockedKey = null;
+    this.unlockedAt = 0;
+    this.lastUsedAt = 0;
+    await this.credentials.deleteRecord(RECORD_KEY);
+    this.stopDriver();
+    this.agent = null;
+    this.agentKey = null;
+    this.dataKeys.clear();
+    this.statusCache = null;
+    this.statusRefresh = null;
+    await rm(this.statusCacheFile, { force: true }).catch(() => undefined);
+    return { configured: false, network: this.config.network };
+  }
+
+  keyStatusFrom(status) {
+    const key = status && status.agentKey ? status.agentKey : null;
+    return {
+      configured: true,
+      healthy: Boolean(key && key.status === 'active'),
+      network: this.config.network,
+      chainId: status.chainId,
+      height: status.height,
+      owner: status.owner,
+      balance: status.balance,
+      balanceWei: status.balanceWei,
+      minerCount: status.minerCount,
+      miners: Array.isArray(status.miners) ? status.miners : [],
+      agentKey: key
+        ? {
+            ordinal: key.ordinal,
+            status: key.status,
+            permissions: Array.isArray(key.permissions) ? key.permissions : [],
+            tiers: Array.isArray(key.tiers) ? key.tiers : [],
+            totalLimit: key.totalLimit,
+            usedTotal: key.usedTotal,
+            dailyLimit: key.dailyLimit,
+            usedToday: key.usedToday,
+            expiresAt: key.expiresAt,
+          }
+        : null,
+      checkedAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Persist a settings-page edit through the profile's config editor. The edit
+   * restarts this plugin, so the caller reports a reload instead of pretending
+   * the running instance already uses the new values.
+   */
+  async updateConfig(patch) {
+    const editor = this.ctx.get('configEditor');
+    const entry = this.ctx.fiber && this.ctx.fiber.entry;
+    if (!editor || typeof editor.edit !== 'function' || !entry) {
+      throw new ServiceError(
+        'config_unavailable',
+        'This profile cannot save plugin configuration from the panel.',
+        'Edit the falari-harness row in cordis.patch.yml instead.',
+      );
+    }
+    let clean;
+    try {
+      clean = validateConfigPatch(patch);
+    } catch (error) {
+      throw new ServiceError('invalid_config', errorText(error));
+    }
+    if (Object.keys(clean).length === 0) {
+      throw new ServiceError('nothing_to_update', 'No supported configuration field was provided.');
+    }
+    await editor.edit(entry, (current) => ({ ...(current && typeof current === 'object' ? current : {}), ...clean }));
+    return { applied: true, reloading: true, fields: Object.keys(clean) };
+  }
+
+  // ── queue driver ───────────────────────────────────────────────────────
+
+  startDriver(agent) {
+    if (this.driverAgent === agent) return;
+    this.stopDriver();
+    try {
+      agent.startUploadQueue({ pollMs: 2500, retryMs: 15000 });
+      this.driverAgent = agent;
+    } catch (error) {
+      this.log?.warn?.(`falari-harness: upload queue driver did not start: ${errorText(error)}`);
+    }
+  }
+
+  stopDriver() {
+    if (this.driverAgent) {
+      try {
+        this.driverAgent.stopUploadQueue();
+      } catch {
+        // a disposed SDK client must not block unloading the plugin
+      }
+    }
+    this.driverAgent = null;
+  }
+
+  // ── quote and budget ───────────────────────────────────────────────────
+
+  /**
+   * A preset name, or any whole number of seconds from 0 (permanent) up to the
+   * chain's maximum term. The fee arithmetic for both lives in the SDK, which
+   * mirrors Params.RequiredFee: whole days rounded up, and anything past 36
+   * years is charged the permanent price.
+   */
+  normalizeDuration(value) {
+    if (value === undefined || value === null || value === '') return this.config.defaultDuration;
+    const text = String(value).trim();
+    if (DURATION_NAMES.includes(text)) return text;
+    if (/^\d+$/.test(text)) {
+      const seconds = Number(text);
+      if (!Number.isSafeInteger(seconds) || seconds < 0 || seconds > MAX_DURATION_SECONDS) {
+        throw new ServiceError(
+          'invalid_duration',
+          `A custom duration must be between 0 and ${MAX_DURATION_SECONDS} seconds.`,
+          '0 means permanent; the chain caps a finite term at 100 years.',
+        );
+      }
+      return seconds;
+    }
+    throw new ServiceError(
+      'invalid_duration',
+      `unknown duration "${value}"`,
+      `Use one of ${DURATION_NAMES.join(', ')} or a number of seconds.`,
+    );
+  }
+
+  async quote(input = {}) {
+    const agent = await this.ensureAgent();
+    const size = Number(input.sizeBytes);
+    if (!Number.isFinite(size) || size <= 0) {
+      throw new ServiceError('invalid_size', 'A positive file size is required for a quote.');
+    }
+    if (size > this.config.maxFileSizeBytes) {
+      throw new ServiceError(
+        'file_too_large',
+        `The file is ${size} bytes, above the configured limit of ${this.config.maxFileSizeBytes}.`,
+        'Raise maxFileSizeBytes in the plugin configuration to allow larger uploads.',
+      );
+    }
+    const duration = this.normalizeDuration(input.duration);
+    const quote = await agent.quote({ size, duration });
+    const requiredWei = sdk.uploadAllowanceRequiredWei(null, BigInt(quote.estimatedTotalFeeWei));
+    const budget = await this.budgetCheck(agent, requiredWei);
+    // Billing is per whole day, rounded up, minimum one day; the price of a
+    // term past the permanent window collapses to the permanent price, so the
+    // effective term becomes "permanent" there too.
+    const pricedAsPermanent = Boolean(quote.permanent) || quote.seconds > PERMANENT_CAP_SECONDS;
+    const billableDays = pricedAsPermanent ? 30 * 365 : Math.max(1, Math.ceil(quote.seconds / 86400));
+    return {
+      sizeBytes: size,
+      durationSeconds: pricedAsPermanent ? 0 : quote.seconds,
+      permanent: pricedAsPermanent,
+      billableDays,
+      durationLimits: { maxSeconds: MAX_DURATION_SECONDS, permanentCapSeconds: PERMANENT_CAP_SECONDS },
+      requestedDuration: String(duration),
+      estimatedLockFee: quote.estimatedLockFee,
+      estimatedLockFeeWei: quote.estimatedLockFeeWei,
+      estimatedTotalFee: quote.estimatedTotalFee,
+      estimatedTotalFeeWei: quote.estimatedTotalFeeWei,
+      nonRefundableFee: quote.nonRefundableFee,
+      nonRefundableFeeWei: quote.nonRefundableFeeWei,
+      feeBreakdown: quote.feeBreakdown,
+      note: quote.note,
+      requiredAllowanceWei: requiredWei.toString(),
+      budget,
+      quotedAt: new Date().toISOString(),
+    };
+  }
+
+  async budgetCheck(agent, requiredWei) {
+    const [allowanceResult, statusResult] = await Promise.allSettled([
+      agent.agentKeyAllowance(),
+      agent.status(),
+    ]);
+    const allowance = allowanceResult.status === 'fulfilled' ? allowanceResult.value : null;
+    const status = statusResult.status === 'fulfilled' ? statusResult.value : null;
+    const shortfall = allowance ? sdk.uploadAllowanceShortfall(allowance, requiredWei) : null;
+    const balanceWei = status ? wei(status.balanceWei) : 0n;
+    const tiers = status && status.agentKey && Array.isArray(status.agentKey.tiers) ? status.agentKey.tiers : [];
+    const canUpload = tiers.length === 0 ? null : tiers.includes('write_data');
+    const totalLimit = allowance ? wei(allowance.total_limit) : 0n;
+    const dailyLimit = allowance ? wei(allowance.daily_limit) : 0n;
+    const totalRemaining = totalLimit === -1n ? '-1' : (totalLimit - wei(allowance.total_used)).toString();
+    const dailyRemaining = dailyLimit === -1n ? '-1' : (dailyLimit - wei(allowance.daily_used)).toString();
+    let reason = null;
+    if (canUpload === false) reason = 'permission_missing';
+    else if (shortfall === 'total') reason = 'allowance_total';
+    else if (shortfall === 'daily') reason = 'allowance_daily';
+    else if (status && balanceWei < requiredWei) reason = 'balance';
+    return {
+      ok: reason === null,
+      reason,
+      requiredWei: requiredWei.toString(),
+      allowanceTotalRemainingWei: totalRemaining,
+      allowanceDailyRemainingWei: dailyRemaining,
+      balanceWei: status ? String(status.balanceWei ?? '0') : null,
+      canUpload,
+    };
+  }
+
+  // ── uploads ────────────────────────────────────────────────────────────
+
+  async assertUploadableFile(path) {
+    let info;
+    try {
+      info = await stat(path);
+    } catch {
+      throw new ServiceError('source_missing', `File not found: ${path}`);
+    }
+    if (!info.isFile()) throw new ServiceError('source_not_file', `Not a regular file: ${path}`);
+    if (info.size <= 0) throw new ServiceError('empty_file', 'Refusing to upload an empty file.');
+    if (info.size > this.config.maxFileSizeBytes) {
+      throw new ServiceError(
+        'file_too_large',
+        `The file is ${info.size} bytes, above the configured limit of ${this.config.maxFileSizeBytes}.`,
+        'Raise maxFileSizeBytes in the plugin configuration to allow larger uploads.',
+      );
+    }
+    return info;
+  }
+
+  async enqueueUpload(input = {}) {
+    const agent = await this.ensureAgent();
+    const source = String(input.path ?? '').trim();
+    if (!source) throw new ServiceError('missing_path', 'An upload needs a file path.');
+    const absolute = resolve(source);
+    const info = await this.assertUploadableFile(absolute);
+    const privacy = input.privacy === 'private' ? 'private' : input.privacy === 'public' ? 'public' : this.config.defaultPrivacy;
+    const duration = this.normalizeDuration(input.duration);
+    const fileName = String(input.fileName ?? '').trim() || undefined;
+
+    const quoted = await this.quote({ sizeBytes: info.size, duration });
+    if (!quoted.budget.ok) {
+      throw new ServiceError(
+        'budget_shortfall',
+        budgetMessage(quoted.budget),
+        budgetHint(quoted.budget),
+      );
+    }
+
+    const task = await agent.enqueueUpload(absolute, {
+      privacy,
+      duration,
+      ...(fileName ? { fileName } : {}),
+      ...(input.dataKey ? { dataKey: input.dataKey } : {}),
+      resume: input.resume !== false,
+    });
+    if (input.temp === true) this.tempFiles.set(task.id, absolute);
+    this.startDriver(agent);
+    return this.taskView(task);
+  }
+
+  /**
+   * Persist one browser upload into the plugin's temp directory, then queue it.
+   * The bytes stream in, so a multi-gigabyte body never sits in memory.
+   */
+  async saveUploadStream(stream, options = {}) {
+    const fileName = sanitizeFileName(options.fileName);
+    if (!fileName) throw new ServiceError('missing_file_name', 'An upload needs a file name.');
+    await mkdir(this.tempDir, { recursive: true, mode: 0o700 });
+    const tempPath = join(this.tempDir, `${randomUUID()}.bin`);
+    const sink = createWriteStream(tempPath, { flags: 'wx', mode: 0o600 });
+    let size = 0;
+    let tooLarge = false;
+    let failure = null;
+    sink.on('error', (error) => {
+      failure = failure || error;
+    });
+    try {
+      for await (const chunk of stream) {
+        size += chunk.length;
+        if (size > this.config.maxFileSizeBytes) {
+          tooLarge = true;
+          break;
+        }
+        if (!sink.write(chunk)) {
+          await new Promise((done) => sink.once('drain', done));
+        }
+        if (failure) break;
+      }
+    } catch (error) {
+      failure = failure || error;
+    }
+    await new Promise((done) => sink.end(done));
+    if (tooLarge || failure || size === 0) {
+      await unlink(tempPath).catch(() => undefined);
+      if (tooLarge) {
+        throw new ServiceError(
+          'file_too_large',
+          `The file is above the configured limit of ${this.config.maxFileSizeBytes} bytes.`,
+          'Raise maxFileSizeBytes in the plugin configuration to allow larger uploads.',
+        );
+      }
+      if (failure) throw failure;
+      throw new ServiceError('empty_file', 'Refusing to upload an empty file.');
+    }
+    try {
+      const task = await this.enqueueUpload({
+        path: tempPath,
+        fileName,
+        privacy: options.privacy,
+        duration: options.duration,
+        temp: true,
+      });
+      return { ...task, fileSize: size };
+    } catch (error) {
+      await unlink(tempPath).catch(() => undefined);
+      throw error;
+    }
+  }
+
+  async listTasks() {
+    let agent;
+    try {
+      agent = await this.ensureAgent();
+    } catch (error) {
+      if (error instanceof ServiceError && error.code === 'no_agent_key') return [];
+      throw error;
+    }
+    const rows = await agent.uploadTasks();
+    const views = await Promise.all(rows.map((row) => this.taskView(row)));
+    const merged = [...views, ...this.downloads.values()].map((task) => ({ ...task }));
+    return merged.sort((left, right) => right.createdAt - left.createdAt || right.updatedAt - left.updatedAt);
+  }
+
+  async getTask(id) {
+    const tasks = await this.listTasks();
+    const found = tasks.find((task) => task.id === id);
+    if (!found) throw new ServiceError('task_not_found', `No upload task with id ${id}.`);
+    return found;
+  }
+
+  async taskAction(id, action) {
+    const download = this.downloads.get(id);
+    if (download) {
+      if (action === 'remove') {
+        this.downloads.delete(id);
+        return { id, removed: true };
+      }
+      if (action === 'retry') {
+        return this.startDownload({ intentId: download.intentId, outPath: download.outPath });
+      }
+      throw new ServiceError(
+        'unsupported_action',
+        'A download cannot be paused or cancelled. Start it again if it failed.',
+      );
+    }
+    const agent = await this.ensureAgent();
+    if (action === 'pause') {
+      await agent.pauseUpload(id);
+    } else if (action === 'resume') {
+      await agent.resumeUpload(id);
+    } else if (action === 'retry') {
+      await agent.retryUpload(id);
+    } else if (action === 'cancel') {
+      await agent.terminateUploadTask(id, 'user_stop');
+    } else if (action === 'remove') {
+      const removed = await agent.removeUploadTask(id);
+      if (!removed) {
+        throw new ServiceError('task_not_finished', 'Only a completed or terminated task can be removed.');
+      }
+      await this.dropTempFile(id);
+    } else {
+      throw new ServiceError('unknown_action', `Unknown task action "${action}".`);
+    }
+    try {
+      return await this.getTask(id);
+    } catch (error) {
+      if (action === 'remove' && error instanceof ServiceError && error.code === 'task_not_found') {
+        return { id, removed: true };
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * What cancelling this upload returns, before anything is signed: the escrow
+   * the chain holds for the intent, the non-refundable compensation it charges
+   * for a deal that already committed shards, and the service fee billed
+   * separately from the master balance.
+   *
+   * The numbers mirror keeper.closeUnfinalizedIntent: a voluntary close reads
+   * voluntary_cancellation_fee_bps, clamps the fee to min_cancellation_fee and
+   * never charges more than the escrow. An intent with no receipt yet is closed
+   * without compensation, so the whole escrow comes back.
+   */
+  async refundPreview(id) {
+    const task = await this.getTask(id);
+    if (task.kind !== 'upload') {
+      throw new ServiceError('not_an_upload', 'Only an upload holds an escrow to refund.');
+    }
+    const base = {
+      taskId: id,
+      intentId: task.intentId || null,
+      fileName: task.fileName,
+      fileSize: task.fileSize,
+      status: task.status,
+      escrowWei: '0',
+      cancellationFeeWei: '0',
+      refundWei: '0',
+      serviceFeeWei: '0',
+      paidFeeWei: '0',
+      uploadedSize: 0,
+      committedSegments: 0,
+      hasReceipts: false,
+      cancellationBps: 0,
+      minCancellationFeeWei: '0',
+      terminated: false,
+      refundedFeeWei: null,
+      estimated: true,
+    };
+    if (!task.intentId) {
+      return { ...base, hasIntent: false, cancelling: 'local_only' };
+    }
+    const agent = await this.ensureAgent();
+    const [intent, params] = await Promise.all([
+      agent.api.getIntent(task.intentId).catch(() => null),
+      agent.api.getStorageParams().catch(() => null),
+    ]);
+    if (!intent) {
+      return {
+        ...base,
+        hasIntent: true,
+        estimated: false,
+        unavailable: 'intent_unreadable',
+      };
+    }
+
+    const escrow = bigWei(intent.locked_fee_wei ?? intent.locked_fee);
+    const paid = bigWei(intent.paid_fee_wei ?? intent.paid_fee);
+    const uploadedSize = Number(intent.uploaded_size ?? 0);
+    const committedSegments = Number(intent.committed_segments ?? 0);
+    const hasReceipts = uploadedSize > 0 || committedSegments > 0;
+    const bps = bigWei(
+      params?.voluntary_cancellation_fee_bps ?? params?.cancellation_fee_bps ?? 0,
+    );
+    const minFee = bigWei(params?.min_cancellation_fee ?? 0);
+    const serviceFee = bigWei(params?.service_fees && params.service_fees.terminate);
+
+    const finalized = String(intent.status || '') === 'finalized';
+    if (finalized) {
+      return {
+        ...base,
+        hasIntent: true,
+        status: intent.status,
+        storageStatus: intent.storage_status || '',
+        uploadedSize,
+        committedSegments,
+        hasReceipts,
+        paidFeeWei: paid.toString(),
+        finalized: true,
+        estimated: false,
+        unavailable: 'finalized',
+      };
+    }
+    let cancellation = 0n;
+    if (hasReceipts && escrow > 0n) {
+      cancellation = (escrow * bps) / 10000n;
+      if (cancellation < minFee) cancellation = minFee;
+      if (cancellation > escrow) cancellation = escrow;
+    }
+    const refund = escrow > cancellation ? escrow - cancellation : 0n;
+    const terminated = String(intent.status || '') === 'terminated';
+
+    return {
+      ...base,
+      hasIntent: true,
+      status: intent.status || task.status,
+      storageStatus: intent.storage_status || '',
+      escrowWei: escrow.toString(),
+      paidFeeWei: paid.toString(),
+      uploadedSize,
+      committedSegments,
+      hasReceipts,
+      cancellationBps: Number(bps),
+      minCancellationFeeWei: minFee.toString(),
+      cancellationFeeWei: (terminated ? bigWei(intent.locked_fee_wei) : cancellation).toString(),
+      refundWei: (terminated ? bigWei(intent.refunded_fee_wei ?? intent.refunded_fee) : refund).toString(),
+      serviceFeeWei: serviceFee.toString(),
+      terminated,
+      refundedFeeWei: terminated ? bigWei(intent.refunded_fee_wei ?? intent.refunded_fee).toString() : null,
+      estimated: !terminated,
+    };
+  }
+
+  /** Cancel an upload and report what the chain actually released. */
+  async cancelUpload(id) {
+    // The preview is a nicety: a chain read that hiccups must not stop the
+    // termination, which is the thing that actually frees the escrow.
+    const preview = await this.refundPreview(id).catch(() => null);
+    await this.taskAction(id, 'cancel');
+    const task = await this.getTask(id).catch(() => null);
+    let refund = preview;
+    if (preview && preview.hasIntent && !preview.terminated) {
+      const agent = await this.ensureAgent();
+      let confirmed = false;
+      for (let attempt = 0; attempt < 8; attempt += 1) {
+        const intent = await agent.api.getIntent(preview.intentId).catch(() => null);
+        if (intent && String(intent.status || '') === 'terminated') {
+          const refunded = bigWei(intent.refunded_fee_wei ?? intent.refunded_fee);
+          refund = {
+            ...preview,
+            status: intent.status,
+            storageStatus: intent.storage_status || '',
+            executed: true,
+            pending: false,
+            estimated: false,
+            refundWei: refunded.toString(),
+            refundedFeeWei: refunded.toString(),
+            escrowWei: (refunded + bigWei(intent.burned_fee_wei ?? intent.burned_fee)).toString(),
+          };
+          confirmed = true;
+          break;
+        }
+        await new Promise((done) => setTimeout(done, 700));
+      }
+      if (!confirmed) {
+        // The transaction was accepted but the intent has not flipped yet: say
+        // that, rather than showing the estimate as if it were the settlement.
+        refund = { ...preview, executed: true, pending: true, estimated: true };
+      }
+    }
+    return { task, refund };
+  }
+
+  async taskView(row) {
+    const dataKey = row.privacy === 'private' && row.intentId ? await this.dataKeyFor(row.intentId) : null;
+    const percent =
+      row.status === 'completed'
+        ? 100
+        : row.bytesTotal > 0
+          ? Math.max(0, Math.min(99, Math.round((row.bytesDone / row.bytesTotal) * 100)))
+          : row.segmentsTotal > 0
+            ? Math.max(0, Math.min(99, Math.round((row.segmentsDone / row.segmentsTotal) * 100)))
+            : 0;
+    if (isFinishedStatus(row.status)) {
+      await this.dropTempFile(row.id);
+    }
+    return {
+      id: row.id,
+      kind: 'upload',
+      status: row.status,
+      stage: row.stage || '',
+      fileName: row.fileName,
+      fileSize: row.fileSize,
+      bytesDone: row.bytesDone,
+      bytesTotal: row.bytesTotal || row.fileSize,
+      segmentsDone: row.segmentsDone,
+      segmentsTotal: row.segmentsTotal,
+      percent,
+      privacy: row.privacy,
+      durationSeconds: row.durationSeconds,
+      intentId: row.intentId || null,
+      dataKey,
+      attempt: row.attempt,
+      deadlineUnix: row.deadlineUnix,
+      stopRequested: Boolean(row.stopRequested),
+      error: row.lastError ? { code: 'upload_failed', message: row.lastError } : null,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+      completedAt: row.completedAt || null,
+    };
+  }
+
+  async dataKeyFor(intentId) {
+    const cached = this.dataKeys.get(intentId);
+    if (cached !== undefined) return cached;
+    try {
+      const raw = await readFile(join(this.keyringDir, `${intentId}.json`), 'utf8');
+      const parsed = JSON.parse(raw);
+      const value = typeof parsed.dataKey === 'string' && parsed.dataKey ? parsed.dataKey : null;
+      this.dataKeys.set(intentId, value);
+      return value;
+    } catch {
+      this.dataKeys.set(intentId, null);
+      return null;
+    }
+  }
+
+  // ── intents and downloads ──────────────────────────────────────────────
+
+  async listIntents(options = {}) {
+    const agent = await this.ensureAgent();
+    const limit = Number.isFinite(options.limit) && options.limit > 0 ? Math.min(200, Math.trunc(options.limit)) : 50;
+    const rows = await agent.list({ limit });
+    const views = await Promise.all(rows.map((row) => this.intentView(row)));
+    return views;
+  }
+
+  async getIntent(intentId) {
+    const agent = await this.ensureAgent();
+    return this.intentView(await agent.info(String(intentId)));
+  }
+
+  async intentView(row) {
+    const encrypted = Boolean(row.encrypted);
+    let fileName = String(row.fileName ?? '');
+    if (encrypted && fileName.startsWith('enc:')) {
+      // The chain stores the sealed name; only this machine's keyring can open
+      // it without a network round trip.
+      const dataKey = await this.dataKeyFor(row.intentId);
+      if (dataKey) {
+        try {
+          fileName = await sdk.decryptIntentName(fileName, Buffer.from(dataKey, 'base64'), String(row.fileRoot ?? ''));
+        } catch {
+          fileName = row.intentId;
+        }
+      } else {
+        fileName = row.intentId;
+      }
+    }
+    return {
+      intentId: row.intentId,
+      fileName,
+      size: Number(row.size ?? 0),
+      status: row.status,
+      storageStatus: row.storageStatus,
+      accessStatus: row.accessStatus,
+      privacy: encrypted ? 'private' : 'public',
+      encrypted,
+      collectionId: row.collectionId || null,
+      durationSeconds: Number(row.durationSeconds ?? 0),
+      expiresAtUnix: Number(row.expiresAtUnix ?? 0),
+      createdAtUnix: Number(row.createdAtUnix ?? 0),
+      lockedFeeWei: String(row.lockedFeeWei ?? '0'),
+      url: row.url || null,
+    };
+  }
+
+  /**
+   * Start a download. The SDK call aggregates the object in memory and writes
+   * the file once it verifies, so this runs as a task and reports progress.
+   */
+  async startDownload(input = {}) {
+    const intentId = String(input.intentId ?? '').trim();
+    if (!intentId) throw new ServiceError('missing_intent', 'An intent id is required to download.');
+    const agent = await this.ensureAgent();
+    const info = await this.intentView(await agent.info(intentId));
+    const target = await this.resolveDownloadTarget(info, input.outPath);
+    const now = Math.floor(Date.now() / 1000);
+    const task = {
+      id: `dl_${randomUUID()}`,
+      kind: 'download',
+      status: 'running',
+      stage: 'downloading',
+      fileName: info.fileName,
+      fileSize: info.size,
+      bytesDone: 0,
+      bytesTotal: info.size,
+      segmentsDone: 0,
+      segmentsTotal: 0,
+      percent: 0,
+      privacy: info.privacy,
+      durationSeconds: info.durationSeconds,
+      intentId,
+      dataKey: null,
+      outPath: target,
+      attempt: 1,
+      deadlineUnix: 0,
+      stopRequested: false,
+      error: null,
+      createdAt: now,
+      updatedAt: now,
+      completedAt: null,
+    };
+    this.downloads.set(task.id, task);
+    this.pruneDownloads();
+    void this.runDownload(task, agent, input.dataKey);
+    return { ...task };
+  }
+
+  async runDownload(task, agent, dataKey) {
+    try {
+      const result = await agent.download(task.intentId, {
+        out: task.outPath,
+        ...(dataKey ? { dataKey: String(dataKey) } : {}),
+        onProgress: (event) => {
+          if (!event || typeof event.percent !== 'number') return;
+          task.percent = Math.max(0, Math.min(99, Math.round(event.percent)));
+          task.stage = event.stage || task.stage;
+          task.bytesDone = Math.round((task.bytesTotal * task.percent) / 100);
+          task.updatedAt = Math.floor(Date.now() / 1000);
+        },
+      });
+      task.status = 'completed';
+      task.stage = 'done';
+      task.percent = 100;
+      task.fileName = result.fileName || task.fileName;
+      task.fileSize = result.size;
+      task.bytesTotal = result.size;
+      task.bytesDone = result.size;
+      task.outPath = result.path || task.outPath;
+      task.completedAt = Math.floor(Date.now() / 1000);
+      task.updatedAt = task.completedAt;
+    } catch (error) {
+      task.status = 'failed';
+      task.stage = 'failed';
+      task.error = toPublicError(error);
+      task.updatedAt = Math.floor(Date.now() / 1000);
+    }
+  }
+
+  pruneDownloads() {
+    if (this.downloads.size <= 50) return;
+    const entries = [...this.downloads.values()].sort((left, right) => left.createdAt - right.createdAt);
+    for (const entry of entries) {
+      if (this.downloads.size <= 50) break;
+      if (entry.status === 'running') continue;
+      this.downloads.delete(entry.id);
+    }
+  }
+
+  async resolveDownloadTarget(info, outPath) {
+    const dir = this.downloadDir;
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const wanted = typeof outPath === 'string' && outPath.trim() ? outPath.trim() : '';
+    let target;
+    if (wanted) {
+      const absolute = isAbsolute(wanted) ? wanted : join(dir, wanted);
+      const rel = relative(dir, absolute);
+      const inside = rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel));
+      if (!inside) {
+        throw new ServiceError(
+          'path_outside_download_dir',
+          `Refusing to write ${absolute}: downloads stay inside ${dir}.`,
+          'Set downloadDir in the plugin configuration to change where files land.',
+        );
+      }
+      target = absolute;
+    } else {
+      const name = sanitizeFileName(info.fileName) || sanitizeFileName(info.intentId) || 'download.bin';
+      target = join(dir, name);
+    }
+    return uniquePath(target);
+  }
+
+  // ── workspace guard (Agent tool uploads only) ──────────────────────────
+
+  async sessionDirectory(agent) {
+    const workingDirectory = this.ctx.get('workingDirectory');
+    if (workingDirectory && typeof workingDirectory.ensure === 'function' && agent) {
+      try {
+        return await workingDirectory.ensure(agent);
+      } catch {
+        // fall through to the deployment default
+      }
+    }
+    if (workingDirectory && typeof workingDirectory.defaultDirectory === 'string') {
+      return workingDirectory.defaultDirectory;
+    }
+    return process.cwd();
+  }
+
+  /**
+   * Resolve a model-supplied path. Unless the profile explicitly allows it, the
+   * target must stay inside the Session's working directory — a model must not
+   * be able to read and pay for an arbitrary host file.
+   */
+  async guardedSourcePath(agent, input) {
+    const base = await this.sessionDirectory(agent);
+    const target = resolve(base, String(input ?? ''));
+    if (this.config.allowUploadOutsideWorkspace) return target;
+    let baseReal = base;
+    try {
+      baseReal = await realpath(base);
+    } catch {
+      // keep the unresolved base
+    }
+    let targetReal = target;
+    try {
+      targetReal = await realpath(target);
+    } catch {
+      throw new ServiceError('source_missing', `File not found: ${target}`);
+    }
+    const rel = relative(baseReal, targetReal);
+    const outside = rel === '' || rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel);
+    if (outside) {
+      throw new ServiceError(
+        'path_outside_workspace',
+        `Refusing to upload ${target}: the path is outside this session's working directory (${baseReal}).`,
+        'Copy the file into the workspace first, or ask the user to upload it from the Falari Data panel.',
+      );
+    }
+    return targetReal;
+  }
+
+  // ── temp files ─────────────────────────────────────────────────────────
+
+  async dropTempFile(taskId) {
+    const path = this.tempFiles.get(taskId);
+    if (!path) return;
+    this.tempFiles.delete(taskId);
+    await unlink(path).catch(() => undefined);
+  }
+
+  async cleanTemps() {
+    let names = [];
+    try {
+      names = await readdir(this.tempDir);
+    } catch {
+      return;
+    }
+    const cutoff = Date.now() - TEMP_MAX_AGE_MS;
+    for (const name of names) {
+      const path = join(this.tempDir, name);
+      try {
+        const info = await stat(path);
+        if (info.isFile() && info.mtimeMs < cutoff) await rm(path, { force: true });
+      } catch {
+        // a concurrently removed file is not an error
+      }
+    }
+  }
+
+}
+
+function budgetMessage(budget) {
+  if (budget.reason === 'permission_missing') return 'This Agent Key has no write_data tier, so it cannot upload.';
+  if (budget.reason === 'allowance_total') return 'The Agent Key total allowance does not cover this upload.';
+  if (budget.reason === 'allowance_daily') return 'The Agent Key daily allowance does not cover this upload.';
+  if (budget.reason === 'balance') return 'The owner account balance does not cover this upload.';
+  return 'The upload budget check failed.';
+}
+
+function budgetHint(budget) {
+  if (budget.reason === 'permission_missing') return 'Ask the owner to issue a key with write_data.';
+  if (budget.reason === 'allowance_total') return 'Raise the key total limit, or use a shorter storage duration.';
+  if (budget.reason === 'allowance_daily') return 'Raise the daily limit, or retry after the UTC reset.';
+  if (budget.reason === 'balance') return 'Top up the owner account.';
+  return '';
+}
+
+/** Parse a wei amount from either a "_wei" string or a decimal string. */
+function bigWei(value) {
+  if (value === null || value === undefined || value === '') return 0n;
+  try {
+    return BigInt(String(value).trim());
+  } catch {
+    return 0n;
+  }
+}
+
+function statusFingerprint(identity, network) {
+  return `${network}|${String(identity.master || '').toLowerCase()}|${String(identity.address || '').toLowerCase()}`;
+}
+
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function uniquePath(target) {
+  const { dir, name, ext } = parsePath(target);
+  let candidate = target;
+  let index = 1;
+  while (await exists(candidate)) {
+    candidate = join(dir, `${name} (${index})${ext}`);
+    index += 1;
+  }
+  return candidate;
+}
+
+export function sanitizeFileName(raw) {
+  const base = String(raw ?? '').trim().split(/[\\/]/).pop() ?? '';
+  const cleaned = base.replace(/[\u0000-\u001f\u007f]/g, '').trim();
+  if (!cleaned || cleaned === '.' || cleaned === '..') return '';
+  return cleaned.slice(0, 255);
+}