firedrill-run 2.2.5 → 3.0.0

package/dist/contracts/tool-command-contracts.js

@@ -0,0 +1,57 @@
+import { sessionStateCounter } from './session-state-contracts.js';
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const states = ['queued', 'publishing', 'accepted', 'observed', 'not_dispatched', 'unknown'];
+const positive = (value) => sessionStateCounter(value) !== null && value !== '0';
+function fileMatches(value, available, maximum) {
+    if (!available)
+        return value === null;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const file = value;
+    return Object.keys(file).sort().join(',') === 'sha256,size' && typeof file.size === 'number'
+        && Number.isSafeInteger(file.size) && file.size >= 0 && file.size <= maximum
+        && typeof file.sha256 === 'string' && /^[a-f0-9]{64}$/.test(file.sha256);
+}
+export function toolCommandRead(value, matches) {
+    if (!matches)
+        throw new Error('The operation response did not match this instance or original request. Inspect its retained activity.');
+    return value;
+}
+export function toolCommandScope(base, actor) {
+    const parts = base.split('/');
+    return parts.length === 7 && parts[0] === '' && parts[1] === 'api' && parts[2] === 'workspaces'
+        && parts[4] === 'tools' && parts[5] === 'instances' && [parts[3], parts[6]].every(one => uuid.test(one ?? ''))
+        ? { workspace: parts[3], instance: parts[6], ...(actor ? { actor } : {}) } : null;
+}
+export function toolCommandMatches(value, scope, selected = {}) {
+    return !!value && value.workspace_id === scope.workspace && value.instance_id === scope.instance
+        && [scope.workspace, scope.instance, value.id, value.actor_id, value.request_key].every(one => uuid.test(one))
+        && /^[a-f0-9]{64}$/.test(value.request_digest) && (!selected.digest || value.request_digest === selected.digest)
+        && positive(value.sequence) && positive(value.state_epoch) && states.includes(value.state)
+        && ['operation', 'surface_open', 'surface_action'].includes(value.kind)
+        && (value.kind === 'operation' ? value.surface_id === null : !!value.surface_id && uuid.test(value.surface_id))
+        && (!selected.id || value.id === selected.id) && (!selected.key || value.request_key === selected.key && value.actor_id === scope.actor)
+        && (!selected.service || value.service_key === selected.service && value.kind === 'operation')
+        && (!selected.operation || value.operation_name === selected.operation && value.kind === 'operation')
+        && (value.state === 'observed' ? !!value.response : value.response === null)
+        && typeof value.request_available === 'boolean' && typeof value.response_available === 'boolean'
+        && typeof value.response_withheld === 'boolean'
+        && fileMatches(value.request_file, value.request_available, 8 * 1024 ** 2)
+        && fileMatches(value.response_file, value.response_available, 16 * 1024 ** 2)
+        && (!value.response_file || value.response_file.size === value.response?.body_size)
+        && (!value.response_withheld || !value.response_available)
+        && (!value.response_withheld || value.response?.transport !== 'http' || value.response.headers === undefined)
+        && (!value.response || Number.isSafeInteger(value.response.body_size) && value.response.body_size >= 0
+            && value.response.body_size <= 16 * 1024 ** 2 && (value.kind === 'operation'
+            ? value.response.transport === 'http' || value.response.transport === 'mcp' : value.response.transport === 'surface'));
+}
+export function toolCommandsMatch(value, scope, selected = {}) {
+    if (!value || value.workspace_id !== scope.workspace || value.instance_id !== scope.instance
+        || value.query !== (selected.query ?? '').trim() || value.outcome !== (selected.outcome ?? '')
+        || selected.anchor !== undefined && value.anchor !== selected.anchor || sessionStateCounter(value.anchor) === null
+        || !Number.isSafeInteger(value.limit) || value.limit < 1 || value.limit > 100 || value.results.length > value.limit
+        || [value.next_before, value.previous_after].some(one => one !== null && (!positive(one) || BigInt(one) > BigInt(value.anchor))))
+        return false;
+    return value.results.every((row, index) => toolCommandMatches(row, scope) && BigInt(row.sequence) <= BigInt(value.anchor)
+        && (!index || BigInt(value.results[index - 1].sequence) > BigInt(row.sequence)) && (!value.outcome || row.state === value.outcome));
+}

package/dist/contracts/tool-connection-contracts.js

@@ -0,0 +1,87 @@
+import { sessionStateCounter } from './session-state-contracts.js';
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const serviceKey = /^[a-z][a-z0-9_-]{0,79}$/;
+const operationName = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
+const pair = (one) => JSON.stringify([one.service_key, one.operation_name]);
+export function toolConnectionRead(value, matches) {
+    if (!matches)
+        throw new Error('The connection response did not match this instance or original permission. Inspect and revoke the original connection before replacing it.');
+    return value;
+}
+function protocols(value) {
+    return value.length >= 1 && value.length <= 2 && new Set(value).size === value.length && value.every(one => one === 'http' || one === 'mcp');
+}
+function permissions(value) {
+    return value.length >= 1 && new Set(value.map(pair)).size === value.length
+        && value.every(one => serviceKey.test(one.service_key) && operationName.test(one.operation_name));
+}
+function scopeMatches(value, scope) {
+    return !!value && uuid.test(scope.workspace) && uuid.test(scope.instance) && value.workspace_id === scope.workspace && value.instance_id === scope.instance;
+}
+function epochMatches(value, scope) {
+    return sessionStateCounter(value) !== null && value !== '0' && (!scope.epoch || scope.epoch === value);
+}
+function audienceMatches(value, instance) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && !url.username && !url.password && !url.port && !url.search && !url.hash
+            && url.pathname === `/tools/serve/${instance}` && url.origin + url.pathname === value;
+    }
+    catch {
+        return false;
+    }
+}
+function pageMatches(value, page) {
+    return Number.isSafeInteger(value.page) && value.page >= 1 && (!page || page === value.page) && Number.isSafeInteger(value.page_size)
+        && value.page_size >= 1 && value.page_size <= 100 && Number.isSafeInteger(value.count) && value.count >= 0 && value.results.length <= value.page_size;
+}
+export function toolConnectionMatches(value, scope, selected = {}) {
+    return scopeMatches(value, scope) && [value.id, value.actor_id, value.request_key].every(one => uuid.test(one))
+        && (!selected.id || selected.id === value.id) && (!selected.key || value.request_key === selected.key && value.actor_id === scope.actor)
+        && /^[a-f0-9]{64}$/.test(value.request_digest) && (!selected.digest || selected.digest === value.request_digest)
+        && epochMatches(value.state_epoch, scope) && permissions(value.operations) && protocols(value.protocols)
+        && audienceMatches(value.audience, scope.instance)
+        && value.http_url === (value.protocols.includes('http') ? value.audience + '/operations' : null)
+        && value.mcp_url === (value.protocols.includes('mcp') ? value.audience + '/mcp' : null)
+        && value.http_result_url === (value.http_services.length ? value.audience + '/http-requests/{request_id}' : null)
+        && (value.protocols.includes('http') || value.http_services.length === 0) && (!selected.revoked || !!value.revoked_at)
+        && new Set(value.http_services.map(one => one.service_key)).size === value.http_services.length
+        && value.http_services.every(service => serviceKey.test(service.service_key) && service.base_url === value.audience + '/http/' + service.service_key
+            && service.operations.every(operation => operationName.test(operation.name)
+                && value.operations.some(one => one.service_key === service.service_key && one.operation_name === operation.name)
+                && ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'].includes(operation.method) && operation.path.startsWith('/')
+                && ['uuid_request', 'declared_vendor_key'].includes(operation.idempotency_key_mode)
+                && !operation.path.startsWith('//') && !/[\\?#%\u0000-\u0020\u007f]/.test(operation.path)));
+}
+export async function toolConnectionAccepted(value, scope, key, input, selected = {}) {
+    if (!toolConnectionMatches(value, scope, { ...selected, key }) || !permissions(input.operations) || !protocols(input.protocols)
+        || !Number.isSafeInteger(input.duration_seconds) || input.duration_seconds < 60)
+        return false;
+    const operations = input.operations.map(one => ({ operation_name: one.operation_name, service_key: one.service_key }))
+        .sort((left, right) => left.service_key < right.service_key ? -1 : left.service_key > right.service_key ? 1
+        : left.operation_name < right.operation_name ? -1 : left.operation_name > right.operation_name ? 1 : 0);
+    const sorted = [...input.protocols].sort();
+    if (JSON.stringify(value.operations.map(pair)) !== JSON.stringify(operations.map(pair)) || JSON.stringify(value.protocols) !== JSON.stringify(sorted))
+        return false;
+    const bytes = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify({
+        duration_seconds: input.duration_seconds, operations, protocols: sorted
+    })));
+    return value.request_digest === Array.from(new Uint8Array(bytes), one => one.toString(16).padStart(2, '0')).join('');
+}
+export function toolConnectionTokenMatches(value) {
+    return value.token_available_once ? typeof value.token === 'string' && /^fd_tool_[a-f0-9-]{36}\.[A-Za-z0-9_-]{64}$/.test(value.token)
+        && value.token.startsWith('fd_tool_' + value.id + '.') : value.token === null;
+}
+export function toolConnectionsMatch(value, scope, query = '', page) {
+    return scopeMatches(value, scope) && value.query === query.trim() && pageMatches(value, page)
+        && value.results.every(row => toolConnectionMatches(row, scope));
+}
+export function toolConnectionOptionsMatch(value, scope, query = '', page) {
+    if (!scopeMatches(value, scope) || value.query !== query.trim() || !pageMatches(value, page) || !epochMatches(value.state_epoch, scope)
+        || !protocols(value.protocols) || !Number.isSafeInteger(value.duration_seconds) || value.duration_seconds < 0
+        || !audienceMatches(value.http_url.replace(/\/operations$/, ''), scope.instance)
+        || value.mcp_url !== value.http_url.replace(/\/operations$/, '/mcp'))
+        return false;
+    return value.results.every(one => serviceKey.test(one.service_key) && operationName.test(one.operation_name)
+        && ['none', 'read', 'write', 'mixed'].includes(one.effect));
+}

package/dist/contracts/tool-contribution-contracts.js

@@ -0,0 +1,35 @@
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const digest = /^[a-f0-9]{64}$/;
+const states = ['submitted', 'reviewed', 'rejected', 'withdrawn', 'published'];
+export function contributionRead(value, scope, selected = {}) {
+    if (!value || value.workspace_id !== scope.workspace || value.actor_id !== scope.actor
+        || ![value.id, value.workspace_id, value.actor_id, value.request_key, value.implementation_id].every(one => uuid.test(one))
+        || selected.key !== undefined && value.request_key !== selected.key || selected.implementation !== undefined && value.implementation_id !== selected.implementation
+        || !digest.test(value.archive_sha256) || !digest.test(value.contract_digest) || !['Apache-2.0', 'MIT'].includes(value.license)
+        || value.consent_version !== '2026-11-05' || !states.includes(value.state) || value.automatically_shared !== false
+        || typeof value.can_withdraw !== 'boolean' || !Number.isFinite(Date.parse(value.submitted_at))
+        || !['', 'clean_native_version', 'rights_unclear', 'private_material', 'native_rework', 'out_of_scope'].includes(value.review_code)
+        || [value.reviewed_at, value.withdrawn_at].some(one => one !== null && !Number.isFinite(Date.parse(one)))
+        || value.release_id !== null && !uuid.test(value.release_id)
+        || value.state === 'published' && (!value.release_id || value.can_withdraw)
+        || value.state === 'withdrawn' && (!value.withdrawn_at || value.can_withdraw)
+        || value.can_withdraw && !['submitted', 'reviewed', 'rejected'].includes(value.state)
+        || selected.input && ['implementation_id', 'archive_sha256', 'contract_digest', 'license', 'consent_version'].some(field => value[field] !== selected.input[field])) {
+        throw new Error('The contribution response did not match this exact version and original review. Recover its status before another action.');
+    }
+    return value;
+}
+export function contributionPageRead(value, scope, selected) {
+    if (!value || value.workspace_id !== scope.workspace || value.actor_id !== scope.actor || value.page !== selected.page
+        || typeof value.can_nominate !== 'boolean'
+        || value.implementation_id !== (selected.implementation ?? null) || value.state_filter !== (selected.state ?? 'all')
+        || !Number.isSafeInteger(value.count) || value.count < 0 || !Number.isSafeInteger(value.page_size) || value.page_size < 1 || value.page_size > 100
+        || !Array.isArray(value.results) || value.results.length > value.page_size)
+        throw new Error('The private contribution history changed. Reload it before continuing.');
+    value.results.forEach(row => {
+        contributionRead(row, scope, selected);
+        if (selected.state && selected.state !== 'all' && row.state !== selected.state)
+            throw new Error('The private contribution history did not match its selected state.');
+    });
+    return value;
+}

package/dist/contracts/tool-group-contracts.js

@@ -0,0 +1,53 @@
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const optionalId = (value) => value === null || uuid.test(value);
+export function toolGroupRead(value, matches) {
+    if (!matches)
+        throw new Error('The tool setup response did not match this workspace or original request. Inspect its retained setup history.');
+    return value;
+}
+export function toolGroupMatches(value, scope, selected = {}) {
+    if (!value || value.workspace_id !== scope.workspace || ![value.id, value.workspace_id, value.actor_id, value.request_key].every(one => uuid.test(one))
+        || !/^[a-f0-9]{64}$/.test(value.request_digest) || selected.id !== undefined && selected.id !== value.id
+        || selected.key !== undefined && (selected.key !== value.request_key || scope.actor !== value.actor_id)
+        || selected.digest !== undefined && selected.digest !== value.request_digest || selected.stopped && !value.stop_requested_at
+        || !Number.isSafeInteger(value.duration_seconds) || value.duration_seconds < 60
+        || !value.counts || Object.values(value.counts).some(one => !Number.isSafeInteger(one) || one < 0) || value.counts.selected < 1)
+        return false;
+    const counts = value.counts;
+    return counts.selected === counts.pending + counts.refused + counts.canceled + counts.created
+        && ['running', 'closing', 'failed', 'closed'].every(key => counts[key] <= counts.created)
+        && value.dispatch_complete === (counts.pending === 0) && value.all_closed === (counts.pending === 0 && counts.closed === counts.created)
+        && (!value.stop_requested_at || counts.running === 0);
+}
+export async function toolGroupAccepted(value, scope, key, input, selected = {}) {
+    if (!toolGroupMatches(value, scope, { ...selected, key }) || value.name !== input.name || value.duration_seconds !== input.duration_seconds
+        || input.start_consent !== true || value.counts.selected !== input.selections.length)
+        return false;
+    const selections = input.selections.map(one => 'implementation_id' in one
+        ? { dataset_id: one.dataset_id, implementation_id: one.implementation_id, usage_quote_id: one.usage_quote_id } : { dataset_id: null, release_id: one.release_id, usage_quote_id: one.usage_quote_id });
+    const bytes = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify({
+        duration_seconds: input.duration_seconds, name: input.name, selections, start_consent: true
+    })));
+    return value.request_digest === Array.from(new Uint8Array(bytes), one => one.toString(16).padStart(2, '0')).join('');
+}
+function pageMatches(value, page) {
+    return Number.isSafeInteger(value.page) && value.page >= 1 && (!page || page === value.page) && Number.isSafeInteger(value.page_size)
+        && value.page_size >= 1 && value.page_size <= 100 && Number.isSafeInteger(value.count) && value.count >= 0 && value.results.length <= value.page_size;
+}
+export function toolGroupsMatch(value, scope, query = '', page) {
+    return !!value && value.workspace_id === scope.workspace && value.query === query.trim() && pageMatches(value, page)
+        && value.results.every(row => toolGroupMatches(row, scope));
+}
+export function toolGroupMembersMatch(value, scope, group, query = '', page) {
+    return !!value && uuid.test(group) && value.workspace_id === scope.workspace && value.group_id === group
+        && value.query === query.trim() && pageMatches(value, page) && value.results.every((row, index) => {
+        if (row.workspace_id !== scope.workspace || row.group_id !== group || !uuid.test(row.id) || !Number.isSafeInteger(row.position) || row.position < 0
+            || index > 0 && row.position <= value.results[index - 1].position || !optionalId(row.release_id) || !optionalId(row.implementation_id)
+            || !optionalId(row.catalog_request_key) || row.release_id === null && row.implementation_id === null
+            || !['pending', 'preparing', 'created', 'failed', 'canceled'].includes(row.state)
+            || row.dataset && (!uuid.test(row.dataset.id) || !Number.isSafeInteger(row.dataset.version) || row.dataset.version < 1))
+            return false;
+        return !row.instance || uuid.test(row.instance.id) && ['queued', 'starting', 'active', 'closing', 'reconciling', 'stopped', 'failed', 'canceled'].includes(row.instance.state)
+            && (!row.instance.observation_current || row.instance.state === 'active' && row.instance.terminal_at === null && row.instance.removal === null);
+    });
+}

package/dist/contracts/tool-group-state-contracts.js

@@ -0,0 +1,63 @@
+import { toolAllocationQuoteMatches } from './tool-runtime-billing-contracts.js';
+const id = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+const date = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+export function groupStateInputMatches(value) {
+    const row = value;
+    return !!row && typeof row === 'object' && !Array.isArray(row)
+        && Object.keys(row).sort().join(',') === 'action,duration_seconds,member_quotes,name,source_operation_id,state_consent'
+        && ['capture', 'reset', 'fork'].includes(row.action) && typeof row.name === 'string'
+        && row.name.trim().length > 0 && row.name.trim().length <= 120 && !/[\u0000-\u001f\u007f]/.test(row.name) && row.state_consent === true
+        && Array.isArray(row.member_quotes) && new Set(row.member_quotes.map(one => one?.position)).size === row.member_quotes.length
+        && row.member_quotes.every(one => !!one && Object.keys(one).sort().join(',') === 'position,usage_quote_id'
+            && Number.isSafeInteger(one.position) && one.position >= 0 && typeof one.usage_quote_id === 'string' && id.test(one.usage_quote_id))
+        && (row.action === 'capture' ? row.source_operation_id === null && row.duration_seconds === null && row.member_quotes.length === 0
+            : typeof row.source_operation_id === 'string' && id.test(row.source_operation_id) && Number.isSafeInteger(row.duration_seconds)
+                && row.duration_seconds >= 60 && row.member_quotes.length > 0);
+}
+export function groupStateInputsEqual(left, right) {
+    return groupStateInputMatches(left) && groupStateInputMatches(right) && left.action === right.action && left.name === right.name
+        && left.source_operation_id === right.source_operation_id && left.duration_seconds === right.duration_seconds
+        && left.member_quotes.length === right.member_quotes.length && left.member_quotes.every((one, index) => one.position === right.member_quotes[index].position && one.usage_quote_id === right.member_quotes[index].usage_quote_id);
+}
+export function groupStateMatches(value, workspace, group, actor, key) {
+    return !!value && id.test(value.id) && value.workspace_id === workspace && value.group_id === group
+        && id.test(value.actor_id) && id.test(value.request_key) && (!actor || value.actor_id === actor) && (!key || value.request_key === key)
+        && groupStateInputMatches(value.request) && value.action === value.request.action && value.name === value.request.name.trim()
+        && value.source_operation_id === value.request.source_operation_id && date(value.created_at) && (value.finished_at === null || date(value.finished_at))
+        && ['preparing', 'holding', 'capturing', 'stopping', 'starting', 'releasing', 'recovery', 'completed', 'failed'].includes(value.state)
+        && !!value.counts && Object.keys(value.counts).sort().join(',') === 'held,ready,released,saved,total' && Number.isSafeInteger(value.counts.total)
+        && value.counts.total > 0 && Object.values(value.counts).every(one => Number.isSafeInteger(one) && one >= 0 && one <= value.counts.total)
+        && value.process_memory_included === false && value.external_state_included === false
+        && value.coordinated === (value.action === 'capture' && value.state === 'completed');
+}
+export function groupStatePageMatches(value, workspace, group, page) {
+    return !!value && value.page === page && Number.isSafeInteger(value.count) && value.count >= 0
+        && Number.isSafeInteger(value.page_size) && value.page_size > 0 && value.page_size <= 100
+        && Array.isArray(value.results) && value.results.length <= value.page_size && value.results.length <= value.count
+        && value.results.every(one => groupStateMatches(one, workspace, group)) && new Set(value.results.map(one => one.id)).size === value.results.length;
+}
+export function groupStateMemberPageMatches(value, page) {
+    return !!value && value.page === page && Number.isSafeInteger(value.count) && value.count >= 0
+        && Number.isSafeInteger(value.page_size) && value.page_size > 0 && value.page_size <= 100
+        && Array.isArray(value.results) && value.results.length <= value.page_size && value.results.length <= value.count
+        && new Set(value.results.map(one => one?.id)).size === value.results.length
+        && new Set(value.results.map(one => one?.position)).size === value.results.length
+        && value.results.every(one => !!one && id.test(one.id) && id.test(one.instance_id) && typeof one.name === 'string'
+            && Number.isSafeInteger(one.position) && one.position >= 0 && /^[1-9][0-9]{0,18}$/.test(one.state_epoch)
+            && (one.checkpoint_id === null || id.test(one.checkpoint_id)) && (one.successor_id === null || id.test(one.successor_id))
+            && (one.checkpoint_sha256 === null || /^[a-f0-9]{64}$/.test(one.checkpoint_sha256))
+            && [one.held_at, one.released_at, one.captured_at].every(at => at === null || date(at))
+            && (one.event_watermark === null || /^(0|[1-9][0-9]{0,18})$/.test(one.event_watermark)));
+}
+export function groupStateQuoteMatches(value, workspace, group, key, selected) {
+    return !!value && value.group_id === group && value.operation_request_key === key && value.action === selected.action
+        && value.source_operation_id === selected.source_operation_id && value.duration_seconds === selected.duration_seconds
+        && Array.isArray(value.members) && value.members.length > 0 && new Set(value.members.map(one => one?.position)).size === value.members.length
+        && new Set(value.members.map(one => one?.quote?.id)).size === value.members.length && value.members.every(one => !!one
+        && Number.isSafeInteger(one.position) && one.position >= 0 && typeof one.name === 'string' && !!one.selection
+        && one.selection.release_id === null && one.selection.dataset_id === null && one.selection.duration_seconds === selected.duration_seconds
+        && id.test(one.selection.implementation_id ?? '') && id.test(one.selection.launch_request_key)
+        && id.test(one.selection.restore?.instance_id ?? '') && id.test(one.selection.restore?.checkpoint_id ?? '')
+        && one.selection.restore?.action === (selected.action === 'fork' ? 'fork' : 'restore')
+        && toolAllocationQuoteMatches(one.quote, workspace, one.selection) && Date.parse(one.quote.expires_at) > Date.now());
+}

package/dist/contracts/tool-lifecycle-contracts.js

@@ -0,0 +1,94 @@
+import { sessionStateCounter } from './session-state-contracts.js';
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const digest = /^[a-f0-9]{64}$/;
+const states = ['queued', 'starting', 'active', 'closing', 'reconciling', 'stopped', 'failed', 'canceled'];
+const terminal = ['stopped', 'failed', 'canceled'];
+const optionalId = (value) => value === null || uuid.test(value);
+export function toolLifecycleRead(value, matches) {
+    if (!matches)
+        throw new Error('The instance response did not match this selection. Inspect the original instance or request.');
+    return value;
+}
+export function toolInstanceMatches(value, workspace, selected = {}) {
+    return !!value && value.workspace_id === workspace && [workspace, value.id, value.actor_id, value.request_key, value.implementation_id].every(one => uuid.test(one))
+        && (!selected.id || value.id === selected.id) && (!selected.key || value.request_key === selected.key && value.actor_id === selected.actor)
+        && typeof value.tool_key === 'string' && value.tool_key.length > 0 && value.tool_key.length <= 160
+        && digest.test(value.request_digest) && sessionStateCounter(value.state_epoch) !== null && value.state_epoch !== '0'
+        && states.includes(value.state) && (terminal.includes(value.state) ? !!value.terminal_at : value.terminal_at === null)
+        && (!value.observation_current || value.state === 'active' && !value.terminal_at && !!value.last_observed_at)
+        && (!value.removal || uuid.test(value.removal.request_key) && (!value.removal.completed_at || !!value.terminal_at));
+}
+export function toolInstanceDetailMatches(value, workspace, selected = {}) {
+    return toolInstanceMatches(value, workspace, selected) && [value.parent_instance_id, value.restored_checkpoint_id, value.dataset_id].every(optionalId)
+        && ['declared_stateless', 'stored_data', 'unspecified'].includes(value.data_mode)
+        && value.visual_interfaces.every(one => /^[a-z][a-z0-9_-]{0,79}$/.test(one.service_key))
+        && !!value.lifetime && ['standalone', 'setup_member'].includes(value.lifetime.owner)
+        && value.lifetime.expires_at === value.expires_at && sessionStateCounter(value.lifetime.revision) !== null
+        && Number.isSafeInteger(value.lifetime.idle_timeout_seconds) && value.lifetime.idle_timeout_seconds >= 0
+        && Number.isSafeInteger(value.lifetime.maximum_extension_seconds) && value.lifetime.maximum_extension_seconds >= 60
+        && typeof value.lifetime.can_extend === 'boolean' && (!value.lifetime.can_extend || !value.terminal_at && value.state === 'active')
+        && ['supported_data_only', 'not_available', 'declared_stateless'].includes(value.lifetime.saved_state);
+}
+export function toolExtensionMatches(value, scope, selected = {}) {
+    if (!value || value.workspace_id !== scope.workspace || value.instance_id !== scope.instance
+        || ![value.id, value.workspace_id, value.instance_id, value.actor_id, value.request_key].every(one => typeof one === 'string' && uuid.test(one))
+        || !digest.test(value.request_digest) || sessionStateCounter(value.state_epoch) === null || value.state_epoch === '0'
+        || value.usage_quote_id !== null && !uuid.test(value.usage_quote_id)
+        || sessionStateCounter(value.revision) === null || value.revision === '0'
+        || !['queued', 'publishing', 'accepted', 'confirmed', 'failed'].includes(value.state)
+        || !Number.isSafeInteger(value.idle_timeout_seconds) || value.idle_timeout_seconds < 0
+        || !Number.isFinite(Date.parse(value.expected_expires_at)) || !Number.isFinite(Date.parse(value.requested_expires_at))
+        || Date.parse(value.requested_expires_at) <= Date.parse(value.expected_expires_at)
+        || (['confirmed', 'failed'].includes(value.state) ? !value.finished_at : value.finished_at !== null)
+        || (value.state === 'confirmed' ? value.confirmed_expires_at !== value.requested_expires_at : value.confirmed_expires_at !== null)
+        || selected.key && (value.request_key !== selected.key || value.actor_id !== scope.actor))
+        return false;
+    const input = selected.input;
+    return !input || value.usage_quote_id === input.usage_quote_id && value.state_epoch === input.state_epoch && value.idle_timeout_seconds === input.idle_timeout_seconds
+        && Date.parse(value.expected_expires_at) === Date.parse(input.expected_expires_at)
+        && Date.parse(value.requested_expires_at) === Date.parse(input.expected_expires_at) + input.additional_seconds * 1000;
+}
+export function toolExtensionPageMatches(value, scope, page) {
+    return !!value && value.workspace_id === scope.workspace && value.instance_id === scope.instance && value.page === page
+        && Number.isSafeInteger(value.page_size) && value.page_size >= 1 && value.page_size <= 100
+        && Number.isSafeInteger(value.count) && value.count >= 0 && Array.isArray(value.results) && value.results.length <= value.page_size
+        && value.results.every(one => toolExtensionMatches(one, scope));
+}
+export function toolRuntimeQuoteMatches(value, tool, input) {
+    return !!value && uuid.test(value.id) && value.workspace_id === tool.workspace_id && value.activity === 'tool_runtime'
+        && value.execution_location === 'managed' && digest.test(value.scope_digest) && digest.test(value.tariff_digest)
+        && Number.isSafeInteger(value.credit_scale) && value.credit_scale >= 1
+        && Number.isSafeInteger(value.estimated_units) && value.estimated_units >= 0
+        && Number.isSafeInteger(value.maximum_units) && value.maximum_units >= value.estimated_units
+        && Number.isFinite(Date.parse(value.expires_at)) && value.scope?.instance_id === tool.id
+        && value.scope.state_epoch === input.state_epoch && value.scope.idle_timeout_seconds === input.idle_timeout_seconds
+        && Date.parse(String(value.scope.expected_expires_at)) === Date.parse(input.expected_expires_at)
+        && Date.parse(String(value.scope.requested_expires_at)) === Date.parse(input.expected_expires_at) + input.additional_seconds * 1000;
+}
+export function toolInstancePageMatches(value, workspace, query = '', state = 'all', selectedPage) {
+    return !!value && value.workspace_id === workspace && value.query === query.trim() && value.state_filter === state
+        && Number.isSafeInteger(value.page) && value.page >= 1 && (!selectedPage || value.page === selectedPage)
+        && Number.isSafeInteger(value.count) && value.count >= 0 && Number.isSafeInteger(value.page_size) && value.page_size >= 1 && value.page_size <= 100
+        && value.results.length <= value.page_size && value.results.every(row => toolInstanceMatches(row, workspace) && row.details_included === false
+        && (state === 'removed' ? !!row.removal?.completed_at : !row.removal?.completed_at)
+        && (state === 'active' ? !row.terminal_at : state === 'closed' ? !!row.terminal_at : true))
+        && value.setup.default_duration_seconds >= 60 && value.setup.default_duration_seconds <= value.setup.maximum_duration_seconds
+        && Number.isSafeInteger(value.setup.maximum_tools) && value.setup.maximum_tools >= 1;
+}
+export async function toolStartReceiptMatches(value, scope, key, input) {
+    if (!toolInstanceDetailMatches(value, scope.workspace, { key, actor: scope.actor }) || value.implementation_id !== input.implementation_id
+        || value.dataset_id !== input.dataset_id)
+        return false;
+    // The server retains a digest, not a guessed duration derived from timestamps.
+    // These fixed keys are Python canonical_digest's sorted original input shape.
+    const original = JSON.stringify({ checkpoint_id: null, dataset_id: input.dataset_id, duration_seconds: input.duration_seconds,
+        generation_kind: '', implementation_id: input.implementation_id, parent_instance_id: null, usage_quote_id: input.usage_quote_id });
+    const bytes = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(original));
+    return value.request_digest === Array.from(new Uint8Array(bytes), one => one.toString(16).padStart(2, '0')).join('');
+}
+export function toolRemovalMatches(value, scope, selected = {}) {
+    return !!value && value.workspace_id === scope.workspace && [value.id, value.workspace_id, value.actor_id, value.instance_id, value.request_key].every(one => uuid.test(one))
+        && (!selected.instance || value.instance_id === selected.instance) && (!selected.id || value.id === selected.id)
+        && (!selected.key || value.request_key === selected.key && value.actor_id === scope.actor)
+        && value.retains_saved_data === true && (value.completed_at ? value.state === 'removed' : value.state === 'removing');
+}

package/dist/contracts/tool-package-contracts.js

@@ -0,0 +1,91 @@
+import { toolProtocolMetadataMatches } from './tool-protocol-contracts.js';
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const digest = /^[a-f0-9]{64}$/;
+const serviceKey = /^[a-z][a-z0-9_-]{0,79}$/;
+const operationName = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
+export function packageRead(value, matches) {
+    if (!matches)
+        throw new Error('The tool package response did not match this selection. Inspect the original version or request.');
+    return value;
+}
+function page(value, selected) {
+    return Number.isSafeInteger(value.page) && value.page >= 1 && (!selected || value.page === selected)
+        && Number.isSafeInteger(value.page_size) && value.page_size >= 1 && value.page_size <= 100
+        && Number.isSafeInteger(value.count) && value.count >= 0 && value.results.length <= value.page_size;
+}
+export function toolVersionMatches(value, workspace, id) {
+    return !!value && uuid.test(workspace) && value.workspace_id === workspace && [value.id, value.tool_id].every(one => uuid.test(one))
+        && (!id || value.id === id) && ['inspected', 'revoked', 'unavailable'].includes(value.state) && value.runtime_started === false
+        && digest.test(value.archive_sha256) && digest.test(value.contract_digest)
+        && [value.service_count, value.operation_count].every(one => one === null || Number.isSafeInteger(one) && one >= 1)
+        && value.interfaces.every(one => one === 'http' || one === 'mcp');
+}
+export function toolVersionPageMatches(value, workspace, selected = {}) {
+    return !!value && value.workspace_id === workspace && value.query === (selected.query ?? '').trim()
+        && value.state_filter === (selected.state ?? 'inspected') && value.single_service === (selected.single ?? false) && page(value, selected.page)
+        && value.results.every(row => toolVersionMatches(row, workspace) && (value.state_filter === 'all'
+            || row.state === value.state_filter || value.state_filter === 'inspected' && row.state === 'unavailable'))
+        && Number.isSafeInteger(value.package_capacity.upload_bytes) && value.package_capacity.upload_bytes >= 1
+        && Number.isSafeInteger(value.package_capacity.contract_bytes) && value.package_capacity.contract_bytes >= 1;
+}
+function selection(value, version) {
+    return value.workspace_id === version.workspace_id && value.implementation_id === version.id && value.contract_digest === version.contract_digest;
+}
+export function toolServiceMatches(value, version, key) {
+    return !!value && selection(value, version) && serviceKey.test(key) && value.id === key && value.key === key;
+}
+export function toolServicesMatch(value, version, query = '', selectedPage) {
+    return !!value && selection(value, version) && value.query === query.trim() && page(value, selectedPage)
+        && value.results.every(row => row.id === row.key && serviceKey.test(row.key) && Number.isSafeInteger(row.operation_count) && row.operation_count >= 1);
+}
+export function toolOperationsMatch(value, version, service, query = '', selectedPage) {
+    return !!value && selection(value, version) && serviceKey.test(service) && value.service_key === service
+        && value.query === query.trim() && page(value, selectedPage) && value.results.every(row => operationName.test(row.name)
+        && toolProtocolMetadataMatches(row)
+        && ['http', 'mcp'].includes(row.transport.kind) && ['none', 'read', 'write', 'mixed'].includes(row.effect));
+}
+export function toolOperationMatches(value, version, service, name) {
+    return !!value && selection(value, version) && serviceKey.test(service) && value.service_key === service && value.name === name
+        && operationName.test(name) && !!value.input_schema && (value.output_schema !== null
+        || value.transport.kind === 'http' && value.transport.response_encoding !== undefined && value.transport.response_encoding !== 'json')
+        && toolProtocolMetadataMatches(value);
+}
+export function toolPackageMatches(value, scope, selected = {}) {
+    const input = selected.input;
+    return !!value && value.workspace_id === scope.workspace && value.actor_id === scope.actor
+        && [scope.workspace, scope.actor, value.id, value.request_key].every(one => uuid.test(one))
+        && (!selected.key || value.request_key === selected.key) && (!selected.id || value.id === selected.id)
+        && (!input || value.filename === input.filename && value.size === input.size && value.sha256 === input.sha256)
+        && Number.isSafeInteger(value.size) && value.size >= 1 && digest.test(value.sha256)
+        && ['uploading', 'inspecting', 'inspected', 'rejected', 'withdrawn'].includes(value.state)
+        && (value.implementation_id === null || uuid.test(value.implementation_id))
+        && (value.state !== 'inspected' || value.implementation_id !== null && value.finished_at !== null)
+        && (value.catalog_setup_id === null && value.catalog_setup_request_key === null
+            || !!value.catalog_setup_id && !!value.catalog_setup_request_key && uuid.test(value.catalog_setup_id) && uuid.test(value.catalog_setup_request_key))
+        && (!value.can_upload || value.state === 'uploading' && !value.withdrawn_at && !value.catalog_setup_id)
+        && (!value.can_withdraw || ['uploading', 'inspecting'].includes(value.state) && !value.finished_at && !value.withdrawn_at);
+}
+export function toolPackagePageMatches(value, scope, query = '', state = 'all', selectedPage) {
+    return !!value && value.workspace_id === scope.workspace && value.actor_id === scope.actor && value.query === query.trim()
+        && value.state_filter === state && page(value, selectedPage)
+        && value.results.every(row => toolPackageMatches(row, scope) && (state === 'all' || row.state === state));
+}
+export function toolPackageUploadDestination(value, scope, request) {
+    let url;
+    try {
+        url = new URL(value.upload_url);
+    }
+    catch {
+        throw new Error('Package upload access could not be confirmed.');
+    }
+    const parts = url.pathname.split('/');
+    packageRead(value, toolPackageMatches(request, scope) && request.can_upload
+        && value.workspace_id === scope.workspace && value.actor_id === scope.actor && value.id === request.id
+        && value.request_key === request.request_key && value.size === request.size && value.sha256 === request.sha256
+        && url.origin === 'https://storage.googleapis.com' && !url.username && !url.password && !url.hash && value.method === 'PUT'
+        && parts.length === 7 && !!parts[1] && parts[2] === 'private' && uuid.test(parts[3] ?? '') && parts[4] === scope.workspace
+        && parts[5] === 'tool-uploads' && parts[6] === `${request.id}.zip`
+        && Object.keys(value.headers).sort().join(',') === 'Content-Type,x-goog-if-generation-match'
+        && value.headers['Content-Type'] === 'application/zip' && value.headers['x-goog-if-generation-match'] === '0');
+    return url;
+}

package/dist/contracts/tool-protocol-contracts.js

@@ -0,0 +1,71 @@
+const names = /^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/;
+const field = /^[A-Za-z_][A-Za-z0-9_]{0,79}$/;
+const headers = new Set(['notion-version', 'stripe-version', 'stripe-account', 'x-goog-api-client']);
+export function toolProtocolMetadataMatches(value) {
+    if (!value || !value.transport || typeof value.transport !== 'object' || Array.isArray(value.transport)
+        || !['http', 'mcp'].includes(value.transport.kind))
+        return false;
+    if (value.mcp_aliases !== undefined && (!Array.isArray(value.mcp_aliases) || value.mcp_aliases.length > 16
+        || value.mcp_aliases.some(name => typeof name !== 'string' || !names.test(name))
+        || new Set(value.mcp_aliases).size !== value.mcp_aliases.length))
+        return false;
+    if (value.transport.kind !== 'http')
+        return value.transport.idempotency === undefined && value.transport.ignored_headers === undefined
+            && value.transport.content_type_argument === undefined && value.transport.parts === undefined;
+    const metadata = value.transport;
+    if (metadata.content_type_argument !== undefined && (typeof metadata.content_type_argument !== 'string'
+        || !field.test(metadata.content_type_argument) || !['text', 'base64'].includes(String(metadata.encoding))
+        || metadata.content_type_argument === metadata.body))
+        return false;
+    if (metadata.idempotency !== undefined) {
+        if (!metadata.idempotency || typeof metadata.idempotency !== 'object' || Array.isArray(metadata.idempotency))
+            return false;
+        const mapping = metadata.idempotency;
+        if (Object.keys(mapping).sort().join(',') !== 'argument,header' || mapping.header !== 'Idempotency-Key'
+            || typeof mapping.argument !== 'string' || !field.test(mapping.argument))
+            return false;
+    }
+    if (metadata.encoding === 'multipart' || metadata.parts !== undefined) {
+        if (metadata.encoding !== 'multipart' || !metadata.parts || typeof metadata.parts !== 'object' || Array.isArray(metadata.parts)
+            || metadata.body !== undefined || metadata.content_type !== undefined || metadata.content_type_argument !== undefined)
+            return false;
+        const parts = Object.entries(metadata.parts), argumentsUsed = new Set();
+        if (parts.length < 1 || parts.length > 100)
+            return false;
+        for (const [name, descriptor] of parts) {
+            if (!/^[A-Za-z_][A-Za-z0-9_.-]{0,99}$/.test(name) || !descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor))
+                return false;
+            const part = descriptor;
+            if (Object.keys(part).some(key => !['argument', 'encoding', 'filename_argument', 'content_type_argument', 'content_type'].includes(key))
+                || !['text', 'json', 'base64'].includes(String(part.encoding)) || typeof part.argument !== 'string' || !field.test(part.argument)
+                || part.encoding !== 'base64' && ['filename_argument', 'content_type_argument', 'content_type'].some(key => key in part))
+                return false;
+            for (const key of ['argument', 'filename_argument', 'content_type_argument']) {
+                if (!(key in part))
+                    continue;
+                const argument = part[key];
+                if (typeof argument !== 'string' || !field.test(argument) || argumentsUsed.has(argument))
+                    return false;
+                argumentsUsed.add(argument);
+            }
+            if (part.content_type !== undefined && (typeof part.content_type !== 'string' || part.content_type.length > 128
+                || !/^[A-Za-z0-9!#$&^_.+-]+\/[A-Za-z0-9!#$&^_.+-]+(?:;\s*charset=utf-8)?$/i.test(part.content_type)))
+                return false;
+        }
+        const idempotency = metadata.idempotency;
+        if (idempotency && argumentsUsed.has(idempotency.argument))
+            return false;
+    }
+    if (metadata.ignored_headers !== undefined && (!Array.isArray(metadata.ignored_headers) || metadata.ignored_headers.length > 4
+        || metadata.ignored_headers.some(name => typeof name !== 'string' || !headers.has(name.toLowerCase()))
+        || new Set(metadata.ignored_headers.map(name => String(name).toLowerCase())).size !== metadata.ignored_headers.length))
+        return false;
+    if (Array.isArray(metadata.ignored_headers) && metadata.headers !== undefined) {
+        if (!metadata.headers || typeof metadata.headers !== 'object' || Array.isArray(metadata.headers))
+            return false;
+        const mapped = new Set(Object.keys(metadata.headers).map(name => name.toLowerCase()));
+        if (metadata.ignored_headers.some(name => mapped.has(String(name).toLowerCase())))
+            return false;
+    }
+    return true;
+}

package/dist/contracts/tool-runtime-billing-contracts.js

@@ -0,0 +1,28 @@
+const id = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/, digest = /^[a-f0-9]{64}$/;
+export function toolAllocationQuoteMatches(value, workspace, selected) {
+    const scope = value?.scope, source = scope?.source;
+    return !!value && value.workspace_id === workspace && id.test(value.id) && value.activity === 'tool_runtime' && value.execution_location === 'managed'
+        && digest.test(value.scope_digest) && digest.test(value.tariff_digest) && typeof value.tariff_version === 'string' && value.tariff_version.length > 0
+        && Number.isSafeInteger(value.credit_scale) && value.credit_scale > 0 && /^10*$/.test(String(value.credit_scale))
+        && typeof value.denomination === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,31}$/.test(value.denomination)
+        && Number.isSafeInteger(value.estimated_units) && value.estimated_units >= 0
+        && Number.isSafeInteger(value.maximum_units) && value.maximum_units >= value.estimated_units && Number.isFinite(Date.parse(value.expires_at))
+        && scope?.schema === 'firedrill.tool-runtime-budget.v1' && scope.launch_request_key === selected.launch_request_key
+        && scope.duration_seconds === selected.duration_seconds && source?.id === (selected.release_id ?? selected.implementation_id)
+        && source.kind === (selected.release_id ? 'catalog' : 'version') && [source.digest, source.contract_digest].every(one => digest.test(one)) && /^sha256:[a-f0-9]{64}$/.test(source.bundle_digest)
+        && (scope.dataset?.id ?? null) === selected.dataset_id
+        && (selected.restore === null ? scope.restore === null : !!scope.restore && scope.restore.instance_id === selected.restore.instance_id
+            && (selected.restore.checkpoint_id === null ? id.test(scope.restore.checkpoint_id) : scope.restore.checkpoint_id === selected.restore.checkpoint_id) && scope.restore.action === selected.restore.action)
+        && !!scope.resources && Object.values(scope.resources).every(one => Number.isSafeInteger(one) && one > 0);
+}
+export function allocationCredits(value, kind = 'maximum') {
+    const units = kind === 'estimated' ? value.estimated_units : value.maximum_units;
+    if (!Number.isSafeInteger(units) || units < 0 || !Number.isSafeInteger(value.credit_scale) || value.credit_scale < 1
+        || !/^10*$/.test(String(value.credit_scale)))
+        return 'Not available';
+    const exact = BigInt(units), scale = BigInt(value.credit_scale);
+    const whole = new Intl.NumberFormat(undefined, { maximumFractionDigits: 0 }).format(exact / scale);
+    const fraction = (exact % scale).toString().padStart(scale.toString().length - 1, '0').replace(/0+$/, '');
+    const separator = new Intl.NumberFormat().formatToParts(1.1).find(one => one.type === 'decimal')?.value ?? '.';
+    return whole + (fraction ? separator + fraction : '');
+}