firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/native/standalone-renewals.js

@@ -0,0 +1,183 @@
+/**
+ * Renewing a running shared-pool tool batch (Plan20 R27, root
+ * `native_standalone_renewal_views.py`): extending the same live batch's end
+ * time for all of its instances, with no reset, restart or new instance. It is
+ * never a heartbeat. Root reviews the extension under the caller's request key
+ * and quotes it at once (`reviewed`, nothing reserved); the extension and its
+ * credit hold commit together only when the exact quote is approved
+ * (`applied`). An unused review is closed explicitly (`cancelled`), and an
+ * original request whose answer was lost is read back by its key or withdrawn.
+ *
+ * Isolated tools keep their own extension flow, and drill-owned tools never
+ * extend a campaign's deadline: this module only speaks to standalone batches.
+ */
+import { api } from '../auth.js';
+import { creditApprovalPolicy, withoutCreditPolicyKeys } from './credit-approval.js';
+import { CliError } from '../http.js';
+export const RENEWAL_MIN_SECONDS = 60;
+export const RENEWAL_MAX_SECONDS = 31_536_000;
+export const RENEWAL_STATES = ['reviewed', 'applied', 'cancelled'];
+const RENEWAL_PAGE = 25;
+const RENEWAL_SCHEMA = 'firedrill.native-standalone-renewal.v1';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHA256 = /^[0-9a-f]{64}$/;
+const RESPONSE_LIMIT = 4 * 1024 * 1024;
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const uuid = (value) => typeof value === 'string' && UUID.test(value);
+const count = (value, min = 0) => typeof value === 'number' && Number.isSafeInteger(value) && value >= min;
+const time = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+const text = (value, max) => typeof value === 'string' && value.length >= 1 && value.length <= max;
+const keys = (value) => Object.keys(value).sort().join(',');
+const sameTime = (left, right) => time(left) && time(right) && Date.parse(left) === Date.parse(right);
+const unconfirmed = (what) => new CliError('native_response_unconfirmed', `The ${what} response could not be confirmed. Nothing further was sent for it.`);
+const scoped = (scope, signal) => ({ actor: scope.owner, workspace: scope.workspace, signal, maximumResponseBytes: RESPONSE_LIMIT });
+const base = (scope, batchId) => `/api/workspaces/${scope.workspace}/tools/native/batches/${batchId}/renewals`;
+export function renewalId(value, label) {
+    if (!uuid(value))
+        throw new CliError('arguments_invalid', `Use the ${label} exactly as Firedrill printed it. Nothing was sent.`, 2);
+    return value.toLowerCase();
+}
+const ROW_KEYS = 'additional_seconds,applied_at,batch_id,created_at,id,instance_count,new_expires_at,previous_expires_at,quote,request_key,state';
+const QUOTE_KEYS = 'activity,credit_scale,denomination,estimated_quantities,estimated_units,execution_location,expires_at,id,maximum_units,organization_id,'
+    + 'resource_class,scope,scope_digest,tariff_digest,tariff_version,workspace_id';
+const SCOPE_KEYS = 'batch_id,instance_count,local_target_compute_charged,new_expires_at,previous_expires_at,renewal_digest,renewal_id,schema';
+/**
+ * One renewal exactly as root defines it: this workspace's batch, the asked-for
+ * batch, a new end exactly `additional_seconds` after the previous one, applied
+ * exactly when it has an `applied_at`, and a quote frozen to this renewal's own
+ * end times and instance count that never charges local compute.
+ */
+function renewalRow(scope, batchId) {
+    return (value) => {
+        const quote = object(value) ? value.quote : null;
+        const frozen = object(quote) ? quote.scope : null;
+        const quantities = object(quote) ? quote.estimated_quantities : null;
+        if (!object(value) || keys(value) !== ROW_KEYS || !uuid(value.id) || value.batch_id !== batchId || !uuid(value.request_key)
+            || !RENEWAL_STATES.includes(value.state)
+            || !count(value.additional_seconds, RENEWAL_MIN_SECONDS) || value.additional_seconds > RENEWAL_MAX_SECONDS
+            || !time(value.previous_expires_at) || !time(value.new_expires_at)
+            || Date.parse(value.new_expires_at) - Date.parse(value.previous_expires_at) !== value.additional_seconds * 1000
+            || !count(value.instance_count, 1) || value.instance_count > 32 || !time(value.created_at)
+            || (value.applied_at !== null && !time(value.applied_at)) || (value.state === 'applied') !== (value.applied_at !== null)
+            || !object(quote) || withoutCreditPolicyKeys(quote) !== QUOTE_KEYS || !uuid(quote.id) || quote.workspace_id !== scope.workspace.toLowerCase()
+            || !uuid(quote.organization_id) || quote.activity !== 'tool_runtime' || quote.execution_location !== 'managed'
+            || !text(quote.resource_class, 64) || !text(quote.tariff_version, 64) || !text(quote.denomination, 64)
+            || typeof quote.scope_digest !== 'string' || !SHA256.test(quote.scope_digest)
+            || typeof quote.tariff_digest !== 'string' || !SHA256.test(quote.tariff_digest) || !count(quote.credit_scale, 1)
+            || !count(quote.estimated_units) || !count(quote.maximum_units) || quote.estimated_units > quote.maximum_units || !time(quote.expires_at)
+            || !object(quantities) || keys(quantities) !== 'allocated_ms'
+            || quantities.allocated_ms !== value.additional_seconds * 1000 * value.instance_count
+            || !object(frozen) || keys(frozen) !== SCOPE_KEYS || frozen.schema !== RENEWAL_SCHEMA || frozen.renewal_id !== value.id
+            || frozen.batch_id !== batchId || typeof frozen.renewal_digest !== 'string' || !SHA256.test(frozen.renewal_digest)
+            || !sameTime(frozen.previous_expires_at, value.previous_expires_at) || !sameTime(frozen.new_expires_at, value.new_expires_at)
+            || frozen.instance_count !== value.instance_count || frozen.local_target_compute_charged !== false)
+            throw unconfirmed('tool renewal');
+        return {
+            id: value.id.toLowerCase(), batch_id: batchId, request_key: value.request_key.toLowerCase(), state: value.state,
+            additional_seconds: value.additional_seconds, previous_expires_at: value.previous_expires_at, new_expires_at: value.new_expires_at,
+            instance_count: value.instance_count, created_at: value.created_at, applied_at: value.applied_at,
+            quote: { ...creditApprovalPolicy(quote), id: quote.id.toLowerCase(), denomination: quote.denomination, credit_scale: quote.credit_scale, estimated_units: quote.estimated_units,
+                maximum_units: quote.maximum_units, expires_at: quote.expires_at, resource_class: quote.resource_class, allocated_ms: quantities.allocated_ms },
+        };
+    };
+}
+/** A batch's reviews and applied extensions, newest first (25 per page). */
+export async function listRenewals(scope, input) {
+    const batchId = renewalId(input.batchId, 'tool session id');
+    const page = input.page ?? 1;
+    if (!count(page, 1))
+        throw new CliError('arguments_invalid', 'Use --page with a positive page number.', 2);
+    const raw = await api(`${base(scope, batchId)}?page=${page}&page_size=${RENEWAL_PAGE}`, scoped(scope, input.signal));
+    if (!object(raw) || keys(raw) !== 'count,next,page,page_size,previous,results' || !count(raw.count) || raw.page !== page
+        || raw.page_size !== RENEWAL_PAGE || (raw.next !== null && typeof raw.next !== 'string') || (raw.previous !== null && typeof raw.previous !== 'string')
+        || !Array.isArray(raw.results) || raw.results.length > RENEWAL_PAGE || (raw.next !== null) !== (page * RENEWAL_PAGE < raw.count)) {
+        throw unconfirmed('tool renewals');
+    }
+    return { count: raw.count, page, next: raw.next, previous: raw.previous, results: raw.results.map(renewalRow(scope, batchId)) };
+}
+/** One renewal by id (a review, an applied extension or a closed review). */
+export async function getRenewal(scope, input) {
+    const batchId = renewalId(input.batchId, 'tool session id');
+    const id = renewalId(input.renewalId, 'renewal id');
+    const row = renewalRow(scope, batchId)(await api(`${base(scope, batchId)}/${id}`, scoped(scope, input.signal)));
+    if (row.id !== id)
+        throw unconfirmed('tool renewal');
+    return row;
+}
+/**
+ * Review extending the batch by `seconds` under the caller's request key. It
+ * reserves nothing and extends nothing; the same key returns the same original
+ * review (a different length under it is refused by root).
+ */
+export async function reviewRenewal(scope, input) {
+    const batchId = renewalId(input.batchId, 'tool session id');
+    const requestKey = renewalId(input.requestKey, 'request key');
+    const row = renewalRow(scope, batchId)(await api(base(scope, batchId), {
+        ...scoped(scope, input.signal), method: 'POST', idempotencyKey: requestKey, body: { additional_seconds: input.seconds }
+    }));
+    if (row.request_key !== requestKey || row.additional_seconds !== input.seconds)
+        throw unconfirmed('tool renewal');
+    return row;
+}
+/** The caller's original review under this key, or null when root has none yet (which does not prove it will never arrive). */
+export async function recoverRenewal(scope, input) {
+    const batchId = renewalId(input.batchId, 'tool session id');
+    const requestKey = renewalId(input.requestKey, 'request key');
+    try {
+        const row = renewalRow(scope, batchId)(await api(`${base(scope, batchId)}/requests/${requestKey}`, scoped(scope, input.signal)));
+        if (row.request_key !== requestKey)
+            throw unconfirmed('tool renewal');
+        return row;
+    }
+    catch (error) {
+        if (error instanceof CliError && error.httpStatus === 404)
+            return null;
+        throw error;
+    }
+}
+/**
+ * Apply a reviewed extension with exactly its quote, after the human approved
+ * it. The credit hold and the new end time commit together; an already applied
+ * renewal is returned unchanged, so a lost answer is recovered, never charged twice.
+ */
+export async function applyRenewal(scope, input) {
+    const batchId = renewalId(input.renewal.batch_id, 'tool session id');
+    const id = renewalId(input.renewal.id, 'renewal id');
+    const row = renewalRow(scope, batchId)(await api(`${base(scope, batchId)}/${id}`, {
+        ...scoped(scope, input.signal), method: 'POST', body: { quote_id: input.renewal.quote.id, renew_consent: true, credit_approval: input.creditApproval === true }
+    }));
+    if (row.id !== id || row.quote.id !== input.renewal.quote.id)
+        throw unconfirmed('tool renewal');
+    return row;
+}
+/** Close an unused review after the human's approval; an applied extension is returned unchanged (never undone). */
+export async function cancelRenewal(scope, input) {
+    const batchId = renewalId(input.batchId, 'tool session id');
+    const id = renewalId(input.renewalId, 'renewal id');
+    const row = renewalRow(scope, batchId)(await api(`${base(scope, batchId)}/${id}`, {
+        ...scoped(scope, input.signal), method: 'DELETE', body: { cancel_review_consent: true }
+    }));
+    if (row.id !== id || row.state === 'reviewed')
+        throw unconfirmed('tool renewal');
+    return row;
+}
+/**
+ * Withdraw an original review request whose answer was lost, after the human's
+ * approval. Root either fences the key for good (`withdrawn`) or returns the
+ * review it already holds (`committed`); nothing is undone.
+ */
+export async function withdrawRenewal(scope, input) {
+    const batchId = renewalId(input.batchId, 'tool session id');
+    const requestKey = renewalId(input.requestKey, 'request key');
+    const raw = await api(`${base(scope, batchId)}/requests/${requestKey}`, { ...scoped(scope, input.signal), method: 'DELETE', body: { withdraw_consent: true } });
+    if (!object(raw) || keys(raw) !== 'receipt,state')
+        throw unconfirmed('renewal withdrawal');
+    if (raw.state === 'withdrawn' && raw.receipt === null)
+        return { state: 'withdrawn', receipt: null };
+    if (raw.state !== 'committed')
+        throw unconfirmed('renewal withdrawal');
+    const receipt = renewalRow(scope, batchId)(raw.receipt);
+    if (receipt.request_key !== requestKey)
+        throw unconfirmed('renewal withdrawal');
+    return { state: 'committed', receipt };
+}

package/dist/cli/src/native/standalone-state.js

@@ -0,0 +1,193 @@
+/**
+ * State operations on one shared-pool tool instance (Plan20, root
+ * `native_standalone_state*`): save a checkpoint of its data, or change its data
+ * through one of its own declared operations. Each request carries a key the
+ * caller keeps (sent as `Idempotency-Key`): sending it again returns the same
+ * original and never runs it twice. Root runs the operation asynchronously, so
+ * an accepted request is followed by reading it back.
+ *
+ * When an answer is lost, the original is read back by its key. A 404 there is
+ * not proof the request never arrived: it stays unknown, and the caller either
+ * replays the same key or withdraws it explicitly. Withdrawal is only ever the
+ * human's explicit choice; it blocks a late arrival and never undoes an effect.
+ *
+ * Starting from a snapshot (reset or fork) is a new reviewed tool session made
+ * elsewhere; this module can only read back or withdraw such a request by key.
+ */
+import { api } from '../auth.js';
+import { CliError } from '../http.js';
+import { standaloneBatchRow } from './standalone-tools.js';
+export const STATE_ACTIONS = ['checkpoint', 'edit'];
+/** States root may still change; `unknown` is waiting for root to confirm an outcome. */
+export const STATE_OPEN = new Set(['pending', 'effect_pending', 'unknown']);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const STATE = /^[a-z][a-z_]{0,23}$/;
+const RESPONSE_LIMIT = 1024 * 1024;
+const RESULT_KEYS = new Set(['snapshot_id', 'before_revision', 'after_revision', 'status', 'outcome']);
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const uuid = (value) => typeof value === 'string' && UUID.test(value);
+const count = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+const time = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+const unconfirmed = (what) => new CliError('native_response_unconfirmed', `The ${what} response could not be confirmed. Nothing further was sent for it.`);
+const scoped = (scope, signal) => ({ actor: scope.owner, workspace: scope.workspace, signal, maximumResponseBytes: RESPONSE_LIMIT });
+const instanceBase = (scope, instanceId) => `/api/workspaces/${scope.workspace}/tools/native/instances/${instanceId}`;
+export function stateId(value, label) {
+    if (!uuid(value))
+        throw new CliError('arguments_invalid', `Use the ${label} exactly as Firedrill printed it. Nothing was sent.`, 2);
+    return value.toLowerCase();
+}
+function resultRow(value) {
+    if (value === null)
+        return null;
+    if (!object(value) || !Object.keys(value).every((key) => RESULT_KEYS.has(key))
+        || (value.snapshot_id !== undefined && !uuid(value.snapshot_id))
+        || (value.before_revision !== undefined && !count(value.before_revision))
+        || (value.after_revision !== undefined && !count(value.after_revision))
+        || (value.status !== undefined && value.status !== null && !(count(value.status) && value.status >= 100 && value.status <= 599))
+        || (value.outcome !== undefined && !(typeof value.outcome === 'string' && STATE.test(value.outcome))))
+        throw unconfirmed('tool state operation');
+    return { ...value, ...(value.snapshot_id ? { snapshot_id: value.snapshot_id.toLowerCase() } : {}) };
+}
+function operationRow(instanceId, expectedKey) {
+    return (value) => {
+        if (!object(value) || !uuid(value.id) || value.instance_id !== instanceId || !uuid(value.request_key)
+            || (expectedKey !== undefined && value.request_key.toLowerCase() !== expectedKey)
+            || !STATE_ACTIONS.includes(value.action)
+            || (value.action === 'checkpoint' ? value.operation !== null : !(typeof value.operation === 'string' && value.operation.length >= 1 && value.operation.length <= 200))
+            || typeof value.state !== 'string' || !STATE.test(value.state) || !time(value.created_at)
+            || (value.finished_at !== null && !time(value.finished_at))
+            // Root shows a result only for a completed operation; a checkpoint's result names its snapshot.
+            || ((value.state === 'completed') !== (value.result !== null)))
+            throw unconfirmed('tool state operation');
+        const result = resultRow(value.result);
+        if (result && value.action === 'checkpoint' && !result.snapshot_id)
+            throw unconfirmed('tool state operation');
+        return { ...value, id: value.id.toLowerCase(), request_key: value.request_key.toLowerCase(), result };
+    };
+}
+function snapshotRow(instanceId) {
+    return (value) => {
+        if (!object(value) || !uuid(value.id) || value.instance_id !== instanceId || typeof value.kind !== 'string' || !STATE.test(value.kind)
+            || (value.operation_id !== null && !uuid(value.operation_id)) || !time(value.created_at) || typeof value.available !== 'boolean') {
+            throw unconfirmed('tool snapshot');
+        }
+        return { ...value, id: value.id.toLowerCase(),
+            operation_id: value.operation_id === null ? null : value.operation_id.toLowerCase() };
+    };
+}
+function page(raw, row, what) {
+    if (!object(raw) || !count(raw.count) || !count(raw.page) || raw.page < 1 || raw.page_size !== 25
+        || !Array.isArray(raw.results) || raw.results.length > 25 || raw.results.length > raw.count
+        || (raw.next !== null && typeof raw.next !== 'string') || (raw.previous !== null && typeof raw.previous !== 'string'))
+        throw unconfirmed(what);
+    return { count: raw.count, page: raw.page, next: raw.next,
+        previous: raw.previous, results: raw.results.map(row) };
+}
+function query(pageNumber) {
+    return new URLSearchParams({ page_size: '25', ...(pageNumber === undefined ? {} : { page: String(pageNumber) }) }).toString();
+}
+/**
+ * Send one state request under the caller's key. Root answers the original
+ * (new or replayed); it must be this key's request for the same action and operation.
+ */
+export async function requestStateOperation(scope, input) {
+    const instanceId = stateId(input.instanceId, 'tool instance id');
+    const requestKey = stateId(input.requestKey, 'request key');
+    const row = operationRow(instanceId, requestKey)(await api(`${instanceBase(scope, instanceId)}/state-operations`, { ...scoped(scope, input.signal), method: 'POST', idempotencyKey: requestKey, body: input.request }));
+    if (!stateMatches(row, input.request))
+        throw unconfirmed('tool state operation');
+    return row;
+}
+/** The original is this request: same action, and for an edit the same operation. */
+export function stateMatches(row, request) {
+    return row.action === request.action && row.operation === (request.action === 'edit' ? request.operation : null);
+}
+/** Newest first, 25 per page. */
+export async function listStateOperations(scope, input) {
+    const instanceId = stateId(input.instanceId, 'tool instance id');
+    return page(await api(`${instanceBase(scope, instanceId)}/state-operations?${query(input.page)}`, scoped(scope, input.signal)), operationRow(instanceId), 'tool state operations');
+}
+export async function getStateOperation(scope, input) {
+    const instanceId = stateId(input.instanceId, 'tool instance id');
+    const operationId = stateId(input.operationId, 'state operation id');
+    const row = operationRow(instanceId)(await api(`${instanceBase(scope, instanceId)}/state-operations/${operationId}`, scoped(scope, input.signal)));
+    if (row.id !== operationId)
+        throw unconfirmed('tool state operation');
+    return row;
+}
+/** This actor's original state request by key, or null when root has none (which is not proof it never arrives). */
+export async function recoverStateOperation(scope, input) {
+    const instanceId = stateId(input.instanceId, 'tool instance id');
+    const requestKey = stateId(input.requestKey, 'request key');
+    try {
+        return operationRow(instanceId, requestKey)(await api(`${instanceBase(scope, instanceId)}/state-operations/requests/${requestKey}`, scoped(scope, input.signal)));
+    }
+    catch (error) {
+        if (error instanceof CliError && error.httpStatus === 404)
+            return null;
+        throw error;
+    }
+}
+/** Snapshots of the instance's data (its baseline and each checkpoint), newest first. */
+export async function listStateSnapshots(scope, input) {
+    const instanceId = stateId(input.instanceId, 'tool instance id');
+    return page(await api(`${instanceBase(scope, instanceId)}/snapshots?${query(input.page)}${input.kind ? `&kind=${input.kind}` : ''}`, scoped(scope, input.signal)), snapshotRow(instanceId), 'tool snapshots');
+}
+export const CLONE_ACTIONS = ['reset', 'fork'];
+/**
+ * Ask root for a reset (from the instance's baseline snapshot) or a fork (from
+ * any of its snapshots) under the caller's key. Root reviews it as a new
+ * one-tool session (`reviewed`): nothing is reserved or started until it is
+ * quoted and admitted. The same key and body replay the original review.
+ */
+export async function requestClone(scope, input) {
+    const instanceId = stateId(input.instanceId, 'tool instance id');
+    const requestKey = stateId(input.requestKey, 'request key');
+    const snapshotId = stateId(input.snapshotId, 'snapshot id');
+    if (!CLONE_ACTIONS.includes(input.action))
+        throw new CliError('arguments_invalid', 'Use reset or fork. Nothing was sent.', 2);
+    const batch = standaloneBatchRow(scope)(await api(`${instanceBase(scope, instanceId)}/clones`, { ...scoped(scope, input.signal),
+        method: 'POST', idempotencyKey: requestKey, body: { snapshot_id: snapshotId, duration_seconds: input.durationSeconds, action: input.action } }));
+    if (batch.request_key !== requestKey || batch.instances.length !== 1 || batch.duration_seconds !== input.durationSeconds
+        || batch.clone_source?.source_instance_id !== instanceId || batch.clone_source.source_snapshot_id !== snapshotId
+        || batch.clone_source.action !== input.action)
+        throw unconfirmed('tool session');
+    return batch;
+}
+/** This actor's original reset or fork request by key (a reviewed tool session), or null when root has none yet. */
+export async function recoverCloneRequest(scope, input) {
+    const instanceId = stateId(input.instanceId, 'tool instance id');
+    const requestKey = stateId(input.requestKey, 'request key');
+    try {
+        const batch = standaloneBatchRow(scope)(await api(`${instanceBase(scope, instanceId)}/clones/requests/${requestKey}`, scoped(scope, input.signal)));
+        if (batch.request_key !== requestKey || batch.clone_source?.source_instance_id !== instanceId)
+            throw unconfirmed('tool session');
+        return batch;
+    }
+    catch (error) {
+        if (error instanceof CliError && error.httpStatus === 404)
+            return null;
+        throw error;
+    }
+}
+/**
+ * Withdraw an original request after the human's explicit approval. Root
+ * either blocks it for good (`withdrawn`) or returns the original it already
+ * accepted (`committed`); nothing that already happened is undone.
+ */
+export async function withdrawStateRequest(scope, input) {
+    const instanceId = stateId(input.instanceId, 'tool instance id');
+    const requestKey = stateId(input.requestKey, 'request key');
+    const path = input.kind === 'state' ? 'state-operations' : 'clones';
+    const raw = await api(`${instanceBase(scope, instanceId)}/${path}/requests/${requestKey}`, { ...scoped(scope, input.signal), method: 'DELETE', body: { withdraw_consent: true } });
+    if (!object(raw) || Object.keys(raw).sort().join(',') !== 'receipt,state')
+        throw unconfirmed('withdrawal');
+    if (raw.state === 'withdrawn' && raw.receipt === null)
+        return { state: 'withdrawn', receipt: null };
+    if (raw.state !== 'committed')
+        throw unconfirmed('withdrawal');
+    const receipt = input.kind === 'state' ? operationRow(instanceId, requestKey)(raw.receipt) : standaloneBatchRow(scope)(raw.receipt);
+    if (receipt.request_key !== requestKey)
+        throw unconfirmed('withdrawal');
+    return { state: 'committed', receipt };
+}

package/dist/cli/src/native/standalone-tools.js

@@ -0,0 +1,187 @@
+/**
+ * Standalone tool batches on the shared reviewed tool pool (Plan20, root
+ * `native_standalone_*`). New tool sessions start through mixed setups
+ * (`tool-setups.ts`), whose pooled children the shared pool runs as one batch;
+ * sessions started before mixed setups are batches too. What stays here is
+ * what both still need: reading and stopping a batch, reading an instance, and
+ * the terminal credential that `tools access` uses to serve a pooled instance.
+ *
+ * Terminal access (`/instances/{id}/credentials`) returns a token that lives
+ * for at most 30 seconds and belongs only in this process's memory: it is
+ * wrapped in a SecretValue at once and never printed, logged or persisted.
+ */
+import { createHash } from 'node:crypto';
+import { api } from '../auth.js';
+import { creditApprovalPolicy } from './credit-approval.js';
+import { CliError } from '../http.js';
+import { SecretValue } from './contracts.js';
+/** Root limits. */
+const STANDALONE_MAX_SELECTIONS = 32;
+const STANDALONE_MAX_OPERATIONS = 256;
+const STANDALONE_MIN_SECONDS = 60;
+const STANDALONE_MAX_SECONDS = 31_536_000;
+export const STANDALONE_PROTOCOL = 'firedrill.logical-operations.v1';
+export const STANDALONE_MCP_VERSION = '2025-06-18';
+/** Root's batch states; a state outside these is shown as given. */
+export const STANDALONE_ACTIVE = 'active';
+export const STANDALONE_TERMINAL = new Set(['stopped', 'cancelled', 'rejected', 'failed']);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHA256 = /^[0-9a-f]{64}$/;
+const STATE = /^[a-z][a-z_]{0,23}$/;
+const RESPONSE_LIMIT = 4 * 1024 * 1024;
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const uuid = (value) => typeof value === 'string' && UUID.test(value);
+const count = (value, min = 0) => typeof value === 'number' && Number.isSafeInteger(value) && value >= min;
+const time = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+const nullableTime = (value) => value === null || time(value);
+const text = (value, max) => typeof value === 'string' && value.length >= 1 && value.length <= max;
+const names = (value) => Array.isArray(value) && value.length >= 1 && value.length <= STANDALONE_MAX_OPERATIONS
+    && value.every((one) => text(one, 200)) && new Set(value).size === value.length;
+const unconfirmed = (what) => new CliError('native_response_unconfirmed', `The ${what} response could not be confirmed. Nothing further was sent for it.`);
+const scoped = (scope, signal) => ({ actor: scope.owner, workspace: scope.workspace, signal, maximumResponseBytes: RESPONSE_LIMIT });
+const base = (scope) => `/api/workspaces/${scope.workspace}/tools/native`;
+function id(value, label) {
+    if (!uuid(value))
+        throw new CliError('arguments_invalid', `Use the ${label} id exactly as Firedrill printed it. Nothing was sent.`, 2);
+    return value.toLowerCase();
+}
+function instanceRow(batchId) {
+    return (value) => {
+        if (!object(value) || !uuid(value.id) || !uuid(value.batch_id) || (batchId !== null && value.batch_id.toLowerCase() !== batchId)
+            || !count(value.position) || value.position >= STANDALONE_MAX_SELECTIONS || !uuid(value.workspace_id) || !uuid(value.implementation_id)
+            || !text(value.name, 200) || !text(value.family, 128) || !text(value.version, 128) || !text(value.service_key, 200)
+            || !names(value.operations) || typeof value.has_preview !== 'boolean' || !count(value.generation, 1)
+            || typeof value.state !== 'string' || !STATE.test(value.state) || !time(value.created_at)
+            || !nullableTime(value.expires_at) || !nullableTime(value.terminal_at))
+            throw unconfirmed('tool instance');
+        return { ...value, id: value.id.toLowerCase(), batch_id: value.batch_id.toLowerCase(),
+            implementation_id: value.implementation_id.toLowerCase(), operations: [...value.operations] };
+    };
+}
+function summaryFields(value) {
+    return uuid(value.id) && uuid(value.workspace_id) && uuid(value.actor_id) && uuid(value.request_key)
+        && typeof value.original_digest === 'string' && SHA256.test(value.original_digest) && typeof value.state === 'string' && STATE.test(value.state)
+        && count(value.duration_seconds, STANDALONE_MIN_SECONDS) && value.duration_seconds <= STANDALONE_MAX_SECONDS && time(value.created_at)
+        && nullableTime(value.expires_at) && nullableTime(value.stop_requested_at);
+}
+function batchRow(scope, expected) {
+    return (value) => {
+        if (!object(value) || !summaryFields(value) || !Array.isArray(value.instances) || value.instances.length < 1
+            || value.instances.length > STANDALONE_MAX_SELECTIONS)
+            throw unconfirmed('tool session');
+        const batchId = value.id.toLowerCase();
+        const instances = value.instances.map(instanceRow(batchId));
+        const source = value.clone_source;
+        if (source !== null && (!object(source) || Object.keys(source).sort().join(',') !== 'action,source_instance_id,source_snapshot_id'
+            || (source.action !== 'reset' && source.action !== 'fork') || !uuid(source.source_instance_id) || !uuid(source.source_snapshot_id))) {
+            throw unconfirmed('tool session');
+        }
+        // The session is this workspace's, the one asked for, and its instances are in position order.
+        if (value.workspace_id.toLowerCase() !== scope.workspace.toLowerCase()
+            || (expected.batchId !== undefined && batchId !== expected.batchId)
+            || !instances.every((one, index) => one.position === index))
+            throw unconfirmed('tool session');
+        return { ...value, id: batchId, request_key: value.request_key.toLowerCase(), instances };
+    };
+}
+/** A batch of this workspace as root returns it (a tool session, or a reviewed reset or fork of one instance). */
+export const standaloneBatchRow = (scope) => batchRow(scope, {});
+const QUOTE_COMPONENTS = ['baseline', 'runtime'];
+/**
+ * Quote a reviewed batch under the caller's quote key. Quoting reserves
+ * nothing; the same key replays the same two quotes (`replayed`), so a later
+ * run admits exactly the estimate the human saw.
+ */
+export async function quoteStandaloneBatch(scope, input) {
+    const batchId = id(input.batch.id, 'tool session');
+    const quoteKey = id(input.quoteKey, 'quote key');
+    const raw = await api(`${base(scope)}/batches/${batchId}/quotes`, { ...scoped(scope, input.signal), method: 'POST', idempotencyKey: quoteKey, body: {} });
+    if (!object(raw) || Object.keys(raw).sort().join(',') !== 'batch_digest,batch_id,bundle_digest,quotes,replayed'
+        || raw.batch_id !== batchId || raw.batch_digest !== input.batch.original_digest || typeof raw.replayed !== 'boolean'
+        || typeof raw.bundle_digest !== 'string' || !SHA256.test(raw.bundle_digest) || !Array.isArray(raw.quotes) || raw.quotes.length !== 2) {
+        throw unconfirmed('tool estimate');
+    }
+    const quotes = raw.quotes.map((value, index) => {
+        const frozen = object(value) ? value.scope : null;
+        // Each quote is for this batch's reviewed original, in root's fixed order, and never charges local compute.
+        if (!object(value) || !uuid(value.id) || value.workspace_id !== scope.workspace.toLowerCase() || value.execution_location !== 'managed'
+            || !text(value.activity, 64) || !text(value.denomination, 64) || !count(value.credit_scale, 1)
+            || !count(value.estimated_units) || !count(value.maximum_units) || value.estimated_units > value.maximum_units || !time(value.expires_at)
+            || !object(frozen) || frozen.schema !== 'firedrill.native-standalone-funding.v1' || frozen.batch_id !== batchId
+            || frozen.batch_digest !== input.batch.original_digest || frozen.component !== QUOTE_COMPONENTS[index]
+            || frozen.local_target_compute_charged !== false)
+            throw unconfirmed('tool estimate');
+        return { ...creditApprovalPolicy(value), id: value.id.toLowerCase(), component: index === 0 ? 'baseline' : 'runtime', activity: value.activity, denomination: value.denomination,
+            credit_scale: value.credit_scale, estimated_units: value.estimated_units, maximum_units: value.maximum_units, expires_at: value.expires_at };
+    });
+    // Root's bundle digest is over the two quote ids in order; it is what admission is bound to.
+    const ids = quotes.map((one) => one.id);
+    if (createHash('sha256').update(JSON.stringify(ids)).digest('hex') !== raw.bundle_digest)
+        throw unconfirmed('tool estimate');
+    return { batch_id: batchId, batch_digest: raw.batch_digest, replayed: raw.replayed, bundle_digest: raw.bundle_digest, quote_key: quoteKey,
+        quotes: [quotes[0], quotes[1]] };
+}
+/**
+ * Admit a reviewed batch with exactly this quote bundle, after the human
+ * approved it. Root reserves the quoted credits and queues the batch on the
+ * shared pool (202). The same bundle replays the admitted batch; any other
+ * bundle for an admitted batch is refused, so nothing is admitted twice.
+ */
+export async function admitStandaloneBatch(scope, input) {
+    const batchId = id(input.quotes.batch_id, 'tool session');
+    const batch = batchRow(scope, { batchId })(await api(`${base(scope)}/batches/${batchId}/admit`, { ...scoped(scope, input.signal), method: 'POST',
+        body: { quote_ids: input.quotes.quotes.map((one) => one.id), bundle_digest: input.quotes.bundle_digest, credit_approval: input.creditApproval === true } }));
+    if (batch.original_digest !== input.quotes.batch_digest)
+        throw unconfirmed('tool admission');
+    return batch;
+}
+export async function getStandaloneBatch(scope, input) {
+    const batchId = id(input.batchId, 'tool session');
+    return batchRow(scope, { batchId })(await api(`${base(scope)}/batches/${batchId}`, scoped(scope, input.signal)));
+}
+/** Ask root to stop a batch (idempotent). Acceptance is not proof that storage or processes are gone. */
+export async function stopStandaloneBatch(scope, input) {
+    const batchId = id(input.batchId, 'tool session');
+    return batchRow(scope, { batchId })(await api(`${base(scope)}/batches/${batchId}`, { ...scoped(scope, input.signal), method: 'DELETE', body: { stop_consent: true } }));
+}
+export async function getStandaloneInstance(scope, input) {
+    const instanceId = id(input.instanceId, 'tool instance');
+    const row = instanceRow(null)(await api(`${base(scope)}/instances/${instanceId}`, scoped(scope, input.signal)));
+    if (row.id !== instanceId || row.workspace_id.toLowerCase() !== scope.workspace.toLowerCase())
+        throw unconfirmed('tool instance');
+    return row;
+}
+/**
+ * A short-lived terminal credential for one active instance. Only a signed-in
+ * terminal of the selected workspace may ask. The token is wrapped at once and
+ * must stay in this process's memory: never output, logs, files or argv.
+ */
+export async function standaloneCredential(scope, input) {
+    const instance = input.instance;
+    const raw = await api(`${base(scope)}/instances/${instance.id}/credentials`, { ...scoped(scope, input.signal), method: 'POST', body: { generation: instance.generation, mode: input.mode } });
+    if (!object(raw) || typeof raw.access_token !== 'string' || raw.access_token.length < 1 || raw.access_token.length > 16_384
+        || raw.token_type !== 'Bearer' || raw.instance_id !== instance.id || raw.generation !== instance.generation
+        || raw.service_key !== instance.service_key || !count(raw.expires_at, 1) || raw.protocol !== STANDALONE_PROTOCOL
+        || raw.mcp_protocol_version !== STANDALONE_MCP_VERSION || typeof raw.invoke_url !== 'string' || typeof raw.mcp_url !== 'string') {
+        throw unconfirmed('tool access');
+    }
+    // Both endpoints live on one isolated https origin, at exactly the paths root defines.
+    let origin;
+    try {
+        const invoke = new URL(raw.invoke_url);
+        origin = invoke.origin;
+        if (invoke.protocol !== 'https:' || invoke.username || invoke.password || invoke.search || invoke.hash
+            || raw.invoke_url !== `${origin}/v1/invoke` || raw.mcp_url !== `${origin}/mcp/${pathSegment(instance.service_key)}`)
+            throw new Error();
+    }
+    catch {
+        throw unconfirmed('tool access');
+    }
+    return { instance_id: instance.id, generation: instance.generation, service_key: instance.service_key,
+        token: new SecretValue(raw.access_token, `tool-access:${instance.id}`), expires_at: raw.expires_at,
+        invoke_url: raw.invoke_url, mcp_url: raw.mcp_url };
+}
+/** Python `quote(value, safe="")`, as root builds the MCP path: only unreserved characters stay literal. */
+function pathSegment(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}