firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/native/tool-reuse.js

@@ -0,0 +1,364 @@
+/**
+ * Tool definition reuse (Plan20 R10; root `native_tool_reuse.py`,
+ * `native_tool_reuse_views.py`, contract `accounts/native_tool_reuse_catalog.py`,
+ * base `/native-tool-definitions`).
+ *
+ * - Sharing is per exact inspected tool version, with workspaces of the same
+ *   organization only. An administrator of the owner workspace shares, reads
+ *   or withdraws an original sharing request, and revokes. The owner
+ *   workspace lists its grants.
+ * - A grant shares the definition only. It never shares a running instance,
+ *   session, state, credentials or runtime rights.
+ * - Using a shared version always needs an exact private copy: the package is
+ *   copied server-side into this workspace (pending → copying → copied) and
+ *   then inspected here like any upload. "copied" is not ready: the copy is
+ *   usable only once its own inspection finishes with a new private version.
+ *   This is not a tool's archive or state fork.
+ * - Request keys: the same key returns the original. A lost answer is read
+ *   back by its key, or the request is withdrawn so it can never land.
+ * Nothing here starts an instance, runs anything or spends anything.
+ */
+import { api } from '../auth.js';
+import { CliError } from '../http.js';
+import { SHA256_HEX } from './contracts.js';
+export const TOOL_COPY_STATES = ['pending', 'copying', 'copied', 'rejected', 'withdrawn'];
+export const TOOL_UPLOAD_STATES = ['uploading', 'inspecting', 'inspected', 'rejected', 'withdrawn'];
+export const TOOL_DEPENDENT_KINDS = ['world', 'fork'];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const RESPONSE_LIMIT = 4 * 1024 * 1024;
+const PAGE = 25;
+const PAGE_KEYS = 'count,next,page,page_size,previous,results';
+const DEFINITION_KEYS = ['archive_sha256', 'can_fork', 'contract_digest', 'description', 'id', 'inspected_at', 'interfaces', 'key', 'name',
+    'operation_count', 'owner_workspace_id', 'reuse_requires_private_copy', 'revoked_at', 'runtime_started', 'service_count', 'state', 'tool_id',
+    'version', 'workspace_id'];
+const SUMMARY_KEYS = DEFINITION_KEYS.join(',');
+const DETAIL_KEYS = [...DEFINITION_KEYS, 'inspection', 'services'].sort().join(',');
+const GRANT_KEYS = 'allow_use,created_at,id,implementation_id,recipient_workspace_id,request_key,revoked_at';
+const COPY_KEYS = 'archive_sha256,cleanup_pending,contract_digest,created_at,finished_at,id,problem,request_key,runtime_started,source_implementation_id,state,'
+    + 'upload,workspace_id';
+const UPLOAD_KEYS = 'actor_id,can_upload,can_withdraw,catalog_setup_id,catalog_setup_request_key,expires_at,filename,finished_at,id,implementation_id,'
+    + 'problem,request_key,sha256,size,state,submitted_at,withdrawn_at,workspace_id';
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const uuid = (value) => typeof value === 'string' && UUID.test(value);
+const sha = (value) => typeof value === 'string' && SHA256_HEX.test(value);
+const time = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+const maybe = (check) => (value) => value === null || check(value);
+const count = (value) => value === null || (Number.isSafeInteger(value) && value >= 0);
+const keys = (value) => Object.keys(value).sort().join(',');
+const lower = (value) => value === null ? null : value.toLowerCase();
+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}/native-tool-definitions`;
+/** A UUID argument exactly as Firedrill printed it, lowercased. */
+export function toolReuseId(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 pageNumber(value) {
+    const page = value ?? 1;
+    if (!Number.isSafeInteger(page) || page < 1)
+        throw new CliError('arguments_invalid', 'Use --page with a positive page number.', 2);
+    return page;
+}
+function searchParams(page, search) {
+    const params = new URLSearchParams({ page: String(page), page_size: String(PAGE) });
+    if (search !== undefined) {
+        // Root counts characters (code points), not UTF-16 units.
+        if ([...search].length > 120)
+            throw new CliError('arguments_invalid', 'Use a name prefix of up to 120 characters.', 2);
+        if (search)
+            params.set('q', search);
+    }
+    return params;
+}
+/** Root's standard page envelope for the 25-row page that was asked for. */
+function pageOf(raw, page, row, what) {
+    if (!object(raw) || keys(raw) !== PAGE_KEYS || !Number.isSafeInteger(raw.count) || raw.count < 0 || raw.page !== page
+        || raw.page_size !== PAGE || (raw.next !== null && typeof raw.next !== 'string') || (raw.previous !== null && typeof raw.previous !== 'string')
+        || !Array.isArray(raw.results) || raw.results.length > PAGE || (raw.next !== null) !== (page * PAGE < raw.count))
+        throw unconfirmed(what);
+    return { count: raw.count, page, next: raw.next, previous: raw.previous, results: raw.results.map(row) };
+}
+function serviceRow(value) {
+    if (!object(value) || keys(value) !== 'key,name,operation_count,visual_interface_declared' || typeof value.key !== 'string'
+        || typeof value.name !== 'string' || !Number.isSafeInteger(value.operation_count) || value.operation_count < 0
+        || typeof value.visual_interface_declared !== 'boolean')
+        throw unconfirmed('tool definition');
+    return { key: value.key, name: value.name, operation_count: value.operation_count, visual_interface_declared: value.visual_interface_declared };
+}
+function definitionRow(withDetail) {
+    return (value) => {
+        if (!object(value) || keys(value) !== (withDetail ? DETAIL_KEYS : SUMMARY_KEYS) || !uuid(value.id) || !uuid(value.workspace_id)
+            || !uuid(value.owner_workspace_id) || value.owner_workspace_id.toLowerCase() !== value.workspace_id.toLowerCase() || !uuid(value.tool_id)
+            || typeof value.key !== 'string' || typeof value.version !== 'string' || typeof value.name !== 'string' || typeof value.description !== 'string'
+            || typeof value.state !== 'string' || !value.state || !maybe(time)(value.inspected_at) || !maybe(time)(value.revoked_at)
+            || !sha(value.archive_sha256) || !sha(value.contract_digest) || !count(value.service_count) || !count(value.operation_count)
+            || !Array.isArray(value.interfaces) || value.interfaces.some((one) => typeof one !== 'string') || value.runtime_started !== false
+            || typeof value.can_fork !== 'boolean' || (value.can_fork && value.state !== 'inspected') || value.reuse_requires_private_copy !== true
+            || (withDetail && (!Array.isArray(value.services) || !object(value.inspection))))
+            throw unconfirmed('tool definition');
+        return {
+            id: value.id.toLowerCase(), workspace_id: value.workspace_id.toLowerCase(), owner_workspace_id: value.owner_workspace_id.toLowerCase(),
+            tool_id: value.tool_id.toLowerCase(), key: value.key, version: value.version, name: value.name, description: value.description, state: value.state,
+            inspected_at: value.inspected_at, revoked_at: value.revoked_at, archive_sha256: value.archive_sha256,
+            contract_digest: value.contract_digest, service_count: value.service_count, operation_count: value.operation_count,
+            interfaces: value.interfaces, runtime_started: false, can_fork: value.can_fork, reuse_requires_private_copy: true,
+            ...(withDetail ? { services: value.services.map(serviceRow), inspection: value.inspection } : {}),
+        };
+    };
+}
+function grantRow(implementationId) {
+    return (value) => {
+        if (!object(value) || keys(value) !== GRANT_KEYS || !uuid(value.id) || typeof value.implementation_id !== 'string'
+            || value.implementation_id.toLowerCase() !== implementationId || !uuid(value.recipient_workspace_id) || typeof value.allow_use !== 'boolean'
+            || !uuid(value.request_key) || !time(value.created_at) || !maybe(time)(value.revoked_at))
+            throw unconfirmed('tool sharing');
+        return { id: value.id.toLowerCase(), implementation_id: implementationId, recipient_workspace_id: value.recipient_workspace_id.toLowerCase(),
+            allow_use: value.allow_use, request_key: value.request_key.toLowerCase(), created_at: value.created_at, revoked_at: value.revoked_at };
+    };
+}
+function uploadRow(value, workspace) {
+    if (!object(value) || keys(value) !== UPLOAD_KEYS || !uuid(value.request_key) || !uuid(value.id) || !uuid(value.workspace_id)
+        || value.workspace_id.toLowerCase() !== workspace || !uuid(value.actor_id)
+        || !TOOL_UPLOAD_STATES.includes(value.state) || !maybe(uuid)(value.catalog_setup_id)
+        || !maybe(uuid)(value.catalog_setup_request_key) || typeof value.filename !== 'string' || !Number.isSafeInteger(value.size) || value.size < 1
+        || !sha(value.sha256) || !maybe(time)(value.submitted_at) || !maybe(time)(value.finished_at) || !time(value.expires_at)
+        || !maybe(time)(value.withdrawn_at) || !maybe(uuid)(value.implementation_id) || value.can_upload !== false || typeof value.can_withdraw !== 'boolean'
+        || !(value.problem === null || typeof value.problem === 'string'))
+        throw unconfirmed('tool copy');
+    return {
+        request_key: value.request_key.toLowerCase(), id: value.id.toLowerCase(), workspace_id: workspace, actor_id: value.actor_id.toLowerCase(),
+        state: value.state, catalog_setup_id: lower(value.catalog_setup_id),
+        catalog_setup_request_key: lower(value.catalog_setup_request_key), filename: value.filename, size: value.size,
+        sha256: value.sha256, submitted_at: value.submitted_at, finished_at: value.finished_at, expires_at: value.expires_at,
+        withdrawn_at: value.withdrawn_at, implementation_id: lower(value.implementation_id), can_upload: false,
+        can_withdraw: value.can_withdraw, problem: value.problem,
+    };
+}
+/** One private copy of this workspace. Its package must be exactly the source's archive. */
+function copyRow(workspace) {
+    return (value) => {
+        if (!object(value) || keys(value) !== COPY_KEYS || !uuid(value.id) || !uuid(value.source_implementation_id) || !uuid(value.workspace_id)
+            || value.workspace_id.toLowerCase() !== workspace || !uuid(value.request_key) || !TOOL_COPY_STATES.includes(value.state)
+            || !time(value.created_at) || !maybe(time)(value.finished_at) || !sha(value.archive_sha256) || !sha(value.contract_digest)
+            || value.runtime_started !== false || typeof value.cleanup_pending !== 'boolean'
+            || !(value.problem === null || typeof value.problem === 'string'))
+            throw unconfirmed('tool copy');
+        const upload = uploadRow(value.upload, workspace);
+        if (upload.sha256 !== value.archive_sha256)
+            throw unconfirmed('tool copy');
+        return {
+            id: value.id.toLowerCase(), source_implementation_id: value.source_implementation_id.toLowerCase(), workspace_id: workspace,
+            request_key: value.request_key.toLowerCase(), state: value.state, created_at: value.created_at,
+            finished_at: value.finished_at, archive_sha256: value.archive_sha256, contract_digest: value.contract_digest, upload,
+            runtime_started: false, cleanup_pending: value.cleanup_pending, problem: value.problem,
+        };
+    };
+}
+function worldDependentRow(value) {
+    if (!object(value) || keys(value) !== 'created_at,id,kind,revision,world_id' || !uuid(value.id) || value.kind !== 'world' || !uuid(value.world_id)
+        || !Number.isSafeInteger(value.revision) || value.revision < 1 || !time(value.created_at))
+        throw unconfirmed('tool dependents');
+    return { id: value.id.toLowerCase(), kind: 'world', world_id: value.world_id.toLowerCase(), revision: value.revision, created_at: value.created_at };
+}
+/** A withdrawal answer: withdrawn with no receipt, or the original that already landed. */
+function withdrawalOf(raw, receipt, what) {
+    if (object(raw) && keys(raw) === 'receipt,state' && raw.state === 'withdrawn' && raw.receipt === null)
+        return { state: 'withdrawn' };
+    if (object(raw) && keys(raw) === 'receipt,state' && raw.state === 'committed' && raw.receipt !== null)
+        return { state: 'committed', receipt: receipt(raw.receipt) };
+    throw unconfirmed(what);
+}
+/** Tool versions this workspace can read (its own and those shared with it), newest first, by name prefix. */
+export async function listToolDefinitions(scope, input) {
+    const page = pageNumber(input.page);
+    return pageOf(await api(`${base(scope)}?${searchParams(page, input.search)}`, scoped(scope, input.signal)), page, definitionRow(false), 'tool definitions');
+}
+/** One readable, available tool version with its declared services and inspection record. */
+export async function getToolDefinition(scope, input) {
+    const implementationId = toolReuseId(input.implementationId, 'tool version id');
+    const row = definitionRow(true)(await api(`${base(scope)}/${implementationId}`, scoped(scope, input.signal)));
+    if (row.id !== implementationId)
+        throw unconfirmed('tool definition');
+    return row;
+}
+/** Other active workspaces of this organization a tool version can be shared with (administrators only), by name prefix. */
+export async function listToolRecipients(scope, input) {
+    const page = pageNumber(input.page);
+    const own = scope.workspace.toLowerCase();
+    return pageOf(await api(`${base(scope)}/recipients?${searchParams(page, input.search)}`, scoped(scope, input.signal)), page, (value) => {
+        if (!object(value) || keys(value) !== 'id,name' || !uuid(value.id) || value.id.toLowerCase() === own || typeof value.name !== 'string') {
+            throw unconfirmed('tool recipients');
+        }
+        return { id: value.id.toLowerCase(), name: value.name };
+    }, 'tool recipients');
+}
+/** The sharing grants of one tool version this workspace owns, newest first, revoked ones included. */
+export async function listToolGrants(scope, input) {
+    const implementationId = toolReuseId(input.implementationId, 'tool version id');
+    const page = pageNumber(input.page);
+    const raw = await api(`${base(scope)}/${implementationId}/grants?page=${page}&page_size=${PAGE}`, scoped(scope, input.signal));
+    return pageOf(raw, page, grantRow(implementationId), 'tool sharing');
+}
+/**
+ * Share one tool version this workspace owns with another workspace of the
+ * organization, under the caller's request key, after the human approved it.
+ * The same key returns the original grant. Administrators only.
+ */
+export async function shareToolDefinition(scope, input) {
+    const implementationId = toolReuseId(input.implementationId, 'tool version id');
+    const recipient = toolReuseId(input.recipientWorkspaceId, 'workspace id');
+    const requestKey = toolReuseId(input.requestKey, 'request key');
+    if (recipient === scope.workspace.toLowerCase()) {
+        throw new CliError('arguments_invalid', 'Share with another workspace of this organization; this one already owns the tool. Nothing was sent.', 2);
+    }
+    const row = grantRow(implementationId)(await api(`${base(scope)}/${implementationId}/grants`, {
+        ...scoped(scope, input.signal), method: 'POST', body: { request_key: requestKey, recipient_workspace_id: recipient, allow_use: input.allowUse }
+    }));
+    if (row.request_key !== requestKey || row.recipient_workspace_id !== recipient || row.allow_use !== input.allowUse)
+        throw unconfirmed('tool sharing');
+    return row;
+}
+/** The caller's original grant under this key, or null when root has none (which does not prove it never arrived). Administrators only. */
+export async function recoverToolGrant(scope, input) {
+    const implementationId = toolReuseId(input.implementationId, 'tool version id');
+    const requestKey = toolReuseId(input.requestKey, 'request key');
+    try {
+        const row = grantRow(implementationId)(await api(`${base(scope)}/${implementationId}/grants/requests/${requestKey}`, scoped(scope, input.signal)));
+        if (row.request_key !== requestKey)
+            throw unconfirmed('tool sharing');
+        return row;
+    }
+    catch (error) {
+        if (error instanceof CliError && error.httpStatus === 404)
+            return null;
+        throw error;
+    }
+}
+/** Withdraw a sharing request that never landed, after the human approved it. A grant that landed is returned, not undone. */
+export async function withdrawToolGrantRequest(scope, input) {
+    const implementationId = toolReuseId(input.implementationId, 'tool version id');
+    const requestKey = toolReuseId(input.requestKey, 'request key');
+    const raw = await api(`${base(scope)}/${implementationId}/grants/requests/${requestKey}`, {
+        ...scoped(scope, input.signal), method: 'DELETE', body: { withdraw_consent: true }
+    });
+    const outcome = withdrawalOf(raw, grantRow(implementationId), 'tool sharing withdrawal');
+    if (outcome.state === 'committed' && outcome.receipt.request_key !== requestKey)
+        throw unconfirmed('tool sharing withdrawal');
+    return outcome;
+}
+/** Revoke one grant after the human's approval. Idempotent: an already revoked grant is returned as it is. */
+export async function revokeToolGrant(scope, input) {
+    const implementationId = toolReuseId(input.implementationId, 'tool version id');
+    const grantId = toolReuseId(input.grantId, 'grant id');
+    const row = grantRow(implementationId)(await api(`${base(scope)}/${implementationId}/grants/${grantId}`, {
+        ...scoped(scope, input.signal), method: 'DELETE', body: { revoke_consent: true }
+    }));
+    if (row.id !== grantId || row.revoked_at === null)
+        throw unconfirmed('tool sharing');
+    return row;
+}
+/**
+ * Start an exact private copy of one copyable tool version into this
+ * workspace, after the human approved it. The copy is pinned to the source's
+ * archive and contract digests, then inspected here before it can be used.
+ * The same key returns the original copy.
+ */
+export async function copyToolDefinition(scope, input) {
+    const implementationId = toolReuseId(input.source.id, 'tool version id');
+    const requestKey = toolReuseId(input.requestKey, 'request key');
+    const row = copyRow(scope.workspace.toLowerCase())(await api(`${base(scope)}/${implementationId}/forks`, {
+        ...scoped(scope, input.signal), method: 'POST', body: { request_key: requestKey, fork_consent: true }
+    }));
+    return checkCopy(row, { sourceId: implementationId, archive: input.source.archive_sha256, contract: input.source.contract_digest, requestKey });
+}
+/** A copy of exactly this source (and digests, when known) under exactly this key. */
+export function checkCopy(row, expected) {
+    if (row.source_implementation_id !== expected.sourceId.toLowerCase() || row.request_key !== expected.requestKey.toLowerCase()
+        || (expected.archive !== undefined && row.archive_sha256 !== expected.archive)
+        || (expected.contract !== undefined && row.contract_digest !== expected.contract))
+        throw unconfirmed('tool copy');
+    return row;
+}
+/** The caller's original copy under this key, or null when root has none (which does not prove it never arrived). */
+export async function recoverToolCopy(scope, input) {
+    const requestKey = toolReuseId(input.requestKey, 'request key');
+    try {
+        const row = copyRow(scope.workspace.toLowerCase())(await api(`${base(scope)}/forks/requests/${requestKey}`, scoped(scope, input.signal)));
+        if (row.request_key !== requestKey)
+            throw unconfirmed('tool copy');
+        return row;
+    }
+    catch (error) {
+        if (error instanceof CliError && error.httpStatus === 404)
+            return null;
+        throw error;
+    }
+}
+/** Withdraw a copy request that never landed, after the human approved it. A copy that landed is returned, not undone. */
+export async function withdrawToolCopyRequest(scope, input) {
+    const requestKey = toolReuseId(input.requestKey, 'request key');
+    const raw = await api(`${base(scope)}/forks/requests/${requestKey}`, {
+        ...scoped(scope, input.signal), method: 'DELETE', body: { withdraw_consent: true }
+    });
+    const outcome = withdrawalOf(raw, copyRow(scope.workspace.toLowerCase()), 'tool copy withdrawal');
+    if (outcome.state === 'committed' && outcome.receipt.request_key !== requestKey)
+        throw unconfirmed('tool copy withdrawal');
+    return outcome;
+}
+/** One of the caller's copies by its id. */
+export async function getToolCopy(scope, input) {
+    const copyId = toolReuseId(input.copyId, 'copy id');
+    const row = copyRow(scope.workspace.toLowerCase())(await api(`${base(scope)}/forks/${copyId}`, scoped(scope, input.signal)));
+    if (row.id !== copyId)
+        throw unconfirmed('tool copy');
+    return row;
+}
+/**
+ * Stop one of the caller's copies while it is still pending, after the human
+ * approved it. A copy already copying or finished is returned as it is.
+ */
+export async function withdrawToolCopy(scope, input) {
+    const copyId = toolReuseId(input.copyId, 'copy id');
+    const row = copyRow(scope.workspace.toLowerCase())(await api(`${base(scope)}/forks/${copyId}`, {
+        ...scoped(scope, input.signal), method: 'DELETE', body: { withdraw_consent: true }
+    }));
+    if (row.id !== copyId)
+        throw unconfirmed('tool copy');
+    return row;
+}
+/** This workspace's world revisions that depend on a tool version, or the caller's copies of it (25 per page). */
+export async function listToolDependents(scope, input) {
+    const implementationId = toolReuseId(input.implementationId, 'tool version id');
+    if (!TOOL_DEPENDENT_KINDS.includes(input.kind))
+        throw new CliError('arguments_invalid', `Use --kind ${TOOL_DEPENDENT_KINDS.join('|')} with tool dependents.`, 2);
+    const page = pageNumber(input.page);
+    const raw = await api(`${base(scope)}/${implementationId}/dependents?kind=${input.kind}&page=${page}&page_size=${PAGE}`, scoped(scope, input.signal));
+    const copies = copyRow(scope.workspace.toLowerCase());
+    const row = input.kind === 'world' ? worldDependentRow : (value) => {
+        const copy = copies(value);
+        if (copy.source_implementation_id !== implementationId)
+            throw unconfirmed('tool dependents');
+        return copy;
+    };
+    return pageOf(raw, page, row, 'tool dependents');
+}
+/** Where a copy stands, in the terms that matter: it is usable only once this workspace's inspection accepted it. */
+export function copyStatus(copy) {
+    const { upload } = copy;
+    switch (copy.state) {
+        case 'pending': return { ready: false, text: 'queued to copy; it can still be withdrawn' };
+        case 'copying': return { ready: false, text: 'copying the exact package into this workspace' };
+        case 'withdrawn': return { ready: false, text: 'withdrawn; nothing was copied' };
+        case 'rejected': return { ready: false, text: `stopped: ${copy.problem ?? 'the copy could not finish'}` };
+        default:
+            if (upload.state === 'inspected' && upload.implementation_id) {
+                return { ready: true, text: `copied and inspected here: private tool version ${upload.implementation_id}` };
+            }
+            if (upload.state === 'rejected' || upload.state === 'withdrawn') {
+                return { ready: false, text: `copied, but this workspace's inspection did not accept it: ${upload.problem ?? upload.state}` };
+            }
+            return { ready: false, text: 'copied; this workspace is still inspecting it, so it is not ready to use yet' };
+    }
+}