@theoremjs/studio 0.0.0-stage → 0.3.2

package/ui/lib/studio-store.d.ts

@@ -0,0 +1,64 @@
+import { type SharedReach, type SharedSites, type StudioDraft, type StudioWorkspace, type ToolReach, type ToolSpecDraft } from '../../mod.ts';
+import { type RestoredStudio } from './studio-session.ts';
+export type DraftAuthor = 'th30' | 'visitor';
+/** Which sections one change touched, and who made it. */
+export interface DraftChange {
+    revision: number;
+    by: DraftAuthor;
+    sections: string[];
+}
+/** A tool as kept: its URLs and headers with their credentials masked. `started` is its start. */
+export declare function keptTool(tool: ToolSpecDraft, started?: ToolSpecDraft): ToolSpecDraft;
+/**
+ * The workspace as kept: each tool's URLs and headers with their credentials masked, in the library
+ * and in the starts a reset puts back.
+ */
+export declare function keptWorkspace(workspace: StudioWorkspace): StudioWorkspace;
+export type StudioStore = ReturnType<typeof createStudioStore>;
+/**
+ * The workspace as an external store. `getWorkspace()` is current the moment `update` returns,
+ * before React renders, so a th30 tool reads what it just did. th30 and the editor work on one
+ * agent at a time, the focused one: `getDraft` and `updateDraft` read and write its draft, with
+ * the whole tool library as its tools.
+ */
+export declare function createStudioStore(initial: RestoredStudio, sites?: SharedSites, toolSites?: SharedSites): {
+    getWorkspace: () => StudioWorkspace;
+    getRevision: () => number;
+    getFocus: () => string;
+    getDraft: () => StudioDraft;
+    update: (next: StudioWorkspace | ((current: StudioWorkspace) => StudioWorkspace), by?: DraftAuthor) => StudioWorkspace;
+    /** Takes in what the project's files changed, without the question an edit to a shared value gets. */
+    takeFiles: (made: StudioWorkspace) => StudioWorkspace;
+    /** Changes the focused agent's draft; a no-op keeps the revision. Returns the draft now held. */
+    updateDraft: (next: StudioDraft | ((current: StudioDraft) => StudioDraft), by?: DraftAuthor) => StudioDraft;
+    /** Opens a node, as `selectNode` does: an agent's node is the one the preview talks to. */
+    select: (id: string) => void;
+    /** Picks the agent the preview talks to; not an edit either. */
+    chatWith: (key: string) => void;
+    /** Changes after `since`, oldest first; only the last 50 are kept. */
+    changesSince: (since: number) => DraftChange[];
+    subscribe: (listener: () => void) => () => void;
+    /**
+     * Says which reading of the project's files the starts stand on now: after a Save, an undo,
+     * or opening the files again.
+     */
+    /** The reading of the project's files the starts stand on. */
+    standsOn: () => string | undefined;
+    /** Says where the files write each shared value now: after they are read again. */
+    setSites: (next: SharedSites | undefined, tools?: SharedSites) => void;
+    /** What a held change to a shared value reaches. Undefined when none is held. */
+    getPending: () => SharedReach | ToolReach | undefined;
+    /**
+     * Makes the held change, on every agent that shares the value. The same value is not asked
+     * about again while the same node stays open, and `quiet` stops the asking for this tab.
+     */
+    confirmShared: (quiet?: boolean) => void;
+    /** Whether a change to a shared value is made without asking. */
+    isQuiet: () => boolean;
+    setQuiet: (quiet: boolean) => void;
+    /** Drops the held change: no agent has it. */
+    cancelShared: () => void;
+    standOn: (files: string) => void;
+    /** Writes now if a write is pending; the route calls it on pagehide and unmount. */
+    flush(): void;
+};

package/ui/lib/studio-store.js

@@ -0,0 +1,391 @@
+/**
+ * The studio's workspace, kept in this tab's sessionStorage so it outlives a reload or a trip
+ * to the docs and back. Every change bumps a revision, so th30 can tell its own edits from the
+ * visitor's. Keys never come here: the vault stays in memory, and a tool's URLs and headers are kept
+ * with their credentials masked.
+ */
+import { maskHeaders, maskUrl } from '@theoremjs/agents/surface';
+import { agentNodeId, createBlankDraft, libraryDraft, STUDIO_WORKSPACE_VERSION, sharedSnapshot, toolReach, toolSnapshot, withLibraryDraft, withSharedCarry, withToolCarry, } from "../../mod.js";
+import { getPref, setPref } from "./studio-prefs.js";
+import { isRecord, session, WORKSPACE_KEY, } from "./studio-session.js";
+const WRITE_MS = 300;
+/** Beside the workspace's key: the builder said not to be asked about shared values again. */
+const QUIET_SUFFIX = '.shared-quiet';
+const NO_SNAPSHOT = new Map();
+const CHANGES_SIZE = 50;
+/** Headers that are a JSON object, else undefined: what can be masked with certainty. */
+function headersObject(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Headers as kept: unchanged (formatting and all) when nothing in them is a credential, masked when
+ * something is. Text that isn't a JSON object yet isn't kept: the headers as they started are, so
+ * nothing in it reaches storage unmasked.
+ */
+function keptHeaders(raw, started) {
+    const headers = headersObject(raw);
+    if (!headers)
+        return started && started !== raw ? keptHeaders(started, undefined) : '';
+    const masked = maskHeaders(headers);
+    return isRecord(masked) && Object.keys(headers).some((name) => masked[name] !== headers[name])
+        ? JSON.stringify(masked)
+        : raw;
+}
+/** A tool as kept: its URLs and headers with their credentials masked. `started` is its start. */
+export function keptTool(tool, started) {
+    return {
+        ...tool,
+        ...(tool.endpoint ? { endpoint: maskUrl(tool.endpoint) } : {}),
+        ...(tool.serverUrl ? { serverUrl: maskUrl(tool.serverUrl) } : {}),
+        ...(tool.headersJson
+            ? { headersJson: keptHeaders(tool.headersJson, started?.headersJson) }
+            : {}),
+    };
+}
+/**
+ * The workspace as kept: each tool's URLs and headers with their credentials masked, in the library
+ * and in the starts a reset puts back.
+ */
+export function keptWorkspace(workspace) {
+    return {
+        ...workspace,
+        toolSpecs: workspace.toolSpecs.map((tool) => keptTool(tool, workspace.starts.tools[tool.key])),
+        starts: {
+            ...workspace.starts,
+            tools: Object.fromEntries(Object.entries(workspace.starts.tools).map(([key, tool]) => [key, keptTool(tool)])),
+        },
+    };
+}
+/** True when two values are the same, or records holding the same values. */
+function sameSection(a, b) {
+    if (a === b)
+        return true;
+    if (!isRecord(a) || !isRecord(b))
+        return false;
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    return [...keys].every((key) => a[key] === b[key]);
+}
+/**
+ * The top-level draft sections that differ. Drafts are immutable, so a section that changed is a new
+ * object; the agent's lens rebuilds its tools section on every read, so that one is compared a level in.
+ */
+function changedSections(before, after) {
+    const was = { ...before };
+    const now = { ...after };
+    const keys = new Set([...Object.keys(was), ...Object.keys(now)]);
+    return [...keys].filter((key) => !sameSection(was[key], now[key]));
+}
+/** The agent whose draft an open node is under; a library tool keeps the one open before it. */
+function agentOf(workspace, id) {
+    return workspace.agents.find((agent) => {
+        const root = agentNodeId(agent.key);
+        return id === root || id.startsWith(`${root}/`);
+    })?.key;
+}
+/** Writes the workspace, masked, to sessionStorage. */
+function writeWorkspace(state) {
+    state.timer = undefined;
+    const record = {
+        v: STUDIO_WORKSPACE_VERSION,
+        workspace: keptWorkspace(state.workspace),
+        revision: state.revision,
+        ...(state.files === undefined ? {} : { files: state.files }),
+    };
+    try {
+        session()?.setItem(state.slot, JSON.stringify(record));
+    }
+    catch {
+        // Quota or a blocked store: the page keeps working on what is in memory.
+    }
+}
+/** Queues a write, unless one is already queued. */
+function scheduleWrite(state) {
+    state.timer ??= setTimeout(() => {
+        writeWorkspace(state);
+    }, WRITE_MS);
+}
+function notifyListeners(state) {
+    for (const listener of state.listeners)
+        listener();
+}
+/** The focused agent: the last one opened, or the first once that one is gone. */
+function focusOf(state) {
+    return state.workspace.agents.some((agent) => agent.key === state.focus)
+        ? state.focus
+        : (state.workspace.agents[0]?.key ?? '');
+}
+/** The focused agent's draft; the same object until the workspace or the focus changes. */
+function draftOf(state) {
+    const { workspace } = state;
+    let { view } = state;
+    const key = focusOf(state);
+    if (view?.agents !== workspace.agents ||
+        view.toolSpecs !== workspace.toolSpecs ||
+        view.providers !== workspace.providers ||
+        view.focus !== key) {
+        view = {
+            agents: workspace.agents,
+            toolSpecs: workspace.toolSpecs,
+            providers: workspace.providers,
+            focus: key,
+            draft: libraryDraft(workspace, key) ?? createBlankDraft(),
+        };
+        state.view = view;
+    }
+    return view.draft;
+}
+/** `made`, with a change to a value the files write once made on every agent or tool that shares it. */
+function sharedCarry(state, made) {
+    let carry = { workspace: made, snapshot: NO_SNAPSHOT };
+    if (state.sites) {
+        state.good ??= sharedSnapshot(state.workspace);
+        carry = withSharedCarry(state.good, made, state.sites);
+    }
+    if (!state.toolSites)
+        return carry;
+    state.goodTools ??= toolSnapshot(state.workspace);
+    const tools = withToolCarry(state.goodTools, carry.workspace, state.toolSites);
+    // One question covers both: agreeing to it agrees to each place.
+    const reach = carry.reach && tools.reach
+        ? { ...carry.reach, sites: [...carry.reach.sites, ...tools.reach.sites] }
+        : (carry.reach ?? tools.reach);
+    return {
+        workspace: tools.workspace,
+        snapshot: carry.snapshot,
+        tools: tools.snapshot,
+        ...(reach ? { reach } : {}),
+    };
+}
+/**
+ * Whether the builder said not to be asked about shared values: in Settings, for this browser, or
+ * with the question's own "don't ask again", for this tab.
+ */
+function isQuiet(state) {
+    if (getPref('askShared') === 'never')
+        return true;
+    try {
+        return session()?.getItem(`${state.slot}${QUIET_SUFFIX}`) === '1';
+    }
+    catch {
+        return false;
+    }
+}
+/** Sets whether shared values are asked about, as Settings does: asking again also ends this tab's "don't ask again". */
+function setQuiet(state, quiet) {
+    setPref('askShared', quiet ? 'never' : 'always');
+    if (!quiet) {
+        try {
+            session()?.removeItem(`${state.slot}${QUIET_SUFFIX}`);
+        }
+        catch {
+            // Storage is off: nothing was kept to end.
+        }
+    }
+    notifyListeners(state);
+}
+/** What agreeing to `reach` covers: the places the files write, or the tools. */
+const reachKeys = (reach) => 'tools' in reach ? reach.tools : reach.sites;
+/**
+ * Moves to `next`, as the visitor's or th30's change, with the move in the open node. A change
+ * to a shared value is held until the person says to make it: `confirmShared`. So is th30's
+ * change to a tool other agents allow: the person did not open that tool to change it.
+ */
+function updateWorkspace(state, next, by) {
+    const made = typeof next === 'function' ? next(state.workspace) : next;
+    if (made === state.workspace)
+        return state.workspace;
+    const carry = sharedCarry(state, made);
+    const reach = carry.reach ?? (by === 'th30' ? toolReach(state.workspace, made, focusOf(state)) : undefined);
+    const asks = reach && !isQuiet(state) && reachKeys(reach).some((key) => !state.agreed.has(key));
+    if (reach && asks) {
+        state.pending = { carry, reach, by };
+        notifyListeners(state);
+        return state.workspace;
+    }
+    return commitWorkspace(state, carry, by);
+}
+function commitWorkspace(state, carry, by) {
+    state.pending = undefined;
+    if (state.sites)
+        state.good = carry.snapshot;
+    if (state.toolSites)
+        state.goodTools = carry.tools;
+    const before = draftOf(state);
+    const agentsBefore = state.workspace.agents.map((agent) => agent.key).join();
+    state.workspace = carry.workspace;
+    state.focus = agentOf(state.workspace, state.workspace.selected) ?? state.focus;
+    const sections = changedSections(before, draftOf(state));
+    if (state.workspace.agents.map((agent) => agent.key).join() !== agentsBefore) {
+        sections.push('agents');
+    }
+    state.revision += 1;
+    state.changes = [...state.changes, { revision: state.revision, by, sections }].slice(-CHANGES_SIZE);
+    scheduleWrite(state);
+    notifyListeners(state);
+    return state.workspace;
+}
+/**
+ * Takes in what the project's files changed. Each value is in the code already, at every place
+ * that reads it: nothing is asked, nothing is carried, and what the files say now is what the next
+ * edit is measured against.
+ */
+function takeFiles(state, made) {
+    if (made === state.workspace)
+        return state.workspace;
+    const held = commitWorkspace(state, { workspace: made, snapshot: NO_SNAPSHOT }, 'visitor');
+    state.good = undefined;
+    state.goodTools = undefined;
+    return held;
+}
+/** Changes the workspace without an edit: no revision, no change record. */
+function moveWorkspace(state, workspace) {
+    state.workspace = workspace;
+    scheduleWrite(state);
+    notifyListeners(state);
+}
+/** Changes the focused agent's draft; a no-op keeps the revision. Returns the draft now held. */
+function updateFocusedDraft(state, next, by) {
+    const current = draftOf(state);
+    const value = typeof next === 'function' ? next(current) : next;
+    if (value !== current) {
+        updateWorkspace(state, withLibraryDraft(state.workspace, focusOf(state), value), by);
+    }
+    return draftOf(state);
+}
+/**
+ * Opens a node: not an edit, so the revision stays. An agent's node focuses that agent, and the
+ * preview talks to it, including one an edit just added and selected.
+ */
+function selectNode(state, id) {
+    const agent = agentOf(state.workspace, id);
+    const chatWith = agent ?? state.workspace.chatWith;
+    if (id === state.workspace.selected && chatWith === state.workspace.chatWith)
+        return;
+    const workspace = { ...state.workspace, selected: id, chatWith };
+    state.focus = agent ?? state.focus;
+    state.agreed.clear();
+    moveWorkspace(state, workspace);
+}
+/**
+ * The workspace as an external store. `getWorkspace()` is current the moment `update` returns,
+ * before React renders, so a th30 tool reads what it just did. th30 and the editor work on one
+ * agent at a time, the focused one: `getDraft` and `updateDraft` read and write its draft, with
+ * the whole tool library as its tools.
+ */
+export function createStudioStore(initial, sites, toolSites) {
+    const state = {
+        workspace: initial.workspace,
+        sites,
+        good: undefined,
+        toolSites,
+        goodTools: undefined,
+        pending: undefined,
+        agreed: new Set(),
+        revision: initial.revision,
+        focus: agentOf(initial.workspace, initial.workspace.selected) ?? initial.workspace.chatWith,
+        changes: [],
+        listeners: new Set(),
+        timer: undefined,
+        slot: initial.project?.key ?? WORKSPACE_KEY,
+        files: initial.project?.files,
+        view: undefined,
+    };
+    const getFocus = () => focusOf(state);
+    const getDraft = () => draftOf(state);
+    const update = (next, by = 'visitor') => updateWorkspace(state, next, by);
+    return {
+        getWorkspace: () => state.workspace,
+        getRevision: () => state.revision,
+        getFocus,
+        getDraft,
+        update,
+        /** Takes in what the project's files changed, without the question an edit to a shared value gets. */
+        takeFiles: (made) => takeFiles(state, made),
+        /** Changes the focused agent's draft; a no-op keeps the revision. Returns the draft now held. */
+        updateDraft: (next, by = 'visitor') => updateFocusedDraft(state, next, by),
+        /** Opens a node, as `selectNode` does: an agent's node is the one the preview talks to. */
+        select: (id) => {
+            selectNode(state, id);
+        },
+        /** Picks the agent the preview talks to; not an edit either. */
+        chatWith: (key) => {
+            if (key === state.workspace.chatWith)
+                return;
+            moveWorkspace(state, { ...state.workspace, chatWith: key });
+        },
+        /** Changes after `since`, oldest first; only the last 50 are kept. */
+        changesSince: (since) => state.changes.filter((change) => change.revision > since),
+        subscribe: (listener) => {
+            state.listeners.add(listener);
+            return () => {
+                state.listeners.delete(listener);
+            };
+        },
+        /**
+         * Says which reading of the project's files the starts stand on now: after a Save, an undo,
+         * or opening the files again.
+         */
+        /** The reading of the project's files the starts stand on. */
+        standsOn: () => state.files,
+        /** Says where the files write each shared value now: after they are read again. */
+        setSites: (next, tools) => {
+            state.sites = next;
+            state.good = undefined;
+            state.toolSites = tools;
+            state.goodTools = undefined;
+        },
+        /** What a held change to a shared value reaches. Undefined when none is held. */
+        getPending: () => state.pending?.reach,
+        /**
+         * Makes the held change, on every agent that shares the value. The same value is not asked
+         * about again while the same node stays open, and `quiet` stops the asking for this tab.
+         */
+        confirmShared: (quiet = false) => {
+            const { pending } = state;
+            if (!pending)
+                return;
+            for (const key of reachKeys(pending.reach))
+                state.agreed.add(key);
+            if (quiet) {
+                try {
+                    session()?.setItem(`${state.slot}${QUIET_SUFFIX}`, '1');
+                }
+                catch {
+                    // Storage is full or off: the builder is asked again.
+                }
+            }
+            commitWorkspace(state, pending.carry, pending.by);
+        },
+        /** Whether a change to a shared value is made without asking. */
+        isQuiet: () => isQuiet(state),
+        setQuiet: (quiet) => {
+            setQuiet(state, quiet);
+        },
+        /** Drops the held change: no agent has it. */
+        cancelShared: () => {
+            if (!state.pending)
+                return;
+            state.pending = undefined;
+            notifyListeners(state);
+        },
+        standOn: (files) => {
+            if (files === state.files)
+                return;
+            state.files = files;
+            scheduleWrite(state);
+        },
+        /** Writes now if a write is pending; the route calls it on pagehide and unmount. */
+        flush() {
+            if (state.timer === undefined)
+                return;
+            clearTimeout(state.timer);
+            writeWorkspace(state);
+        },
+    };
+}

package/ui/lib/studio-watch.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Watching the project's files from the page: the local server says when the builder's editor
+ * writes one. Whether the builder wants that is a preference, in `studio-prefs.ts`.
+ */
+/**
+ * Listens for the files the server says changed. `onOpen` runs when the server is watching: one
+ * started with `--no-watch` never opens. Answers how to stop listening.
+ */
+export declare function subscribeToFiles(endpoint: string, on: {
+    open: () => void;
+    files: (files: string[]) => void;
+}): () => void;

package/ui/lib/studio-watch.js

@@ -0,0 +1,27 @@
+/**
+ * Watching the project's files from the page: the local server says when the builder's editor
+ * writes one. Whether the builder wants that is a preference, in `studio-prefs.ts`.
+ */
+/**
+ * Listens for the files the server says changed. `onOpen` runs when the server is watching: one
+ * started with `--no-watch` never opens. Answers how to stop listening.
+ */
+export function subscribeToFiles(endpoint, on) {
+    if (typeof EventSource === 'undefined')
+        return () => undefined;
+    const source = new EventSource(`${endpoint}/watch`);
+    source.onopen = on.open;
+    source.onmessage = (event) => {
+        try {
+            const told = JSON.parse(event.data);
+            const files = typeof told === 'object' && told !== null && 'files' in told ? told.files : undefined;
+            on.files(Array.isArray(files) ? files.filter((file) => typeof file === 'string') : []);
+        }
+        catch {
+            on.files([]);
+        }
+    };
+    return () => {
+        source.close();
+    };
+}

package/ui/lib/tab-fills.d.ts

@@ -0,0 +1,6 @@
+import type { KeyboardEvent } from 'react';
+/**
+ * Tab in an empty field takes its placeholder up as the text, to edit rather than retype. Only for a
+ * placeholder that is a value (an example, or the default it stands for); anywhere else Tab moves on.
+ */
+export declare function tabFills(value: string, placeholder: string | undefined, onChange: (next: string) => void): (event: KeyboardEvent) => void;

package/ui/lib/tab-fills.js

@@ -0,0 +1,14 @@
+/**
+ * Tab in an empty field takes its placeholder up as the text, to edit rather than retype. Only for a
+ * placeholder that is a value (an example, or the default it stands for); anywhere else Tab moves on.
+ */
+export function tabFills(value, placeholder, onChange) {
+    return (event) => {
+        if (event.key !== 'Tab' || event.shiftKey || event.altKey || event.ctrlKey || event.metaKey)
+            return;
+        if (value !== '' || !placeholder)
+            return;
+        event.preventDefault();
+        onChange(placeholder);
+    };
+}

package/ui/lib/tool-credentials.d.ts

@@ -0,0 +1,3 @@
+export declare function toolCredential(key: string): string;
+export declare function setToolCredential(key: string, value: string): void;
+export declare function subscribeToolCredentials(listener: () => void): () => void;

package/ui/lib/tool-credentials.js

@@ -0,0 +1,23 @@
+/**
+ * The credentials typed into tool tests, by tool key. In this tab's memory only: never saved, never
+ * sent anywhere but the one test request. th30 sees them only as cards.
+ */
+const credentials = new Map();
+const listeners = new Set();
+export function toolCredential(key) {
+    return credentials.get(key) ?? '';
+}
+export function setToolCredential(key, value) {
+    if (value)
+        credentials.set(key, value);
+    else
+        credentials.delete(key);
+    for (const listener of listeners)
+        listener();
+}
+export function subscribeToolCredentials(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}

package/ui/lib/tool-probe.d.ts

@@ -0,0 +1,19 @@
+import type { GuardrailsDraft } from '../../draft.ts';
+import { type ToolSpecDraft } from '../../mod.ts';
+/** What the test-connection route answers: an HTTP response, or an MCP server's tool list. */
+export interface ProbeResult {
+    ok: boolean;
+    status?: number;
+    statusText?: string;
+    error?: string;
+    preview?: string;
+    elapsedMs?: number;
+    tools?: string[];
+    targetToolFound?: boolean;
+}
+/**
+ * Sends the probe with the draft's network guardrail, which the server keeps to only when it is
+ * the builder's own; any other keeps to public hosts. A request that can't be made, or a server
+ * that can't be reached, comes back as a failed result.
+ */
+export declare function runToolProbe(tool: ToolSpecDraft, sampleInput: string, credential: string, guardrails: GuardrailsDraft): Promise<ProbeResult>;

package/ui/lib/tool-probe.js

@@ -0,0 +1,104 @@
+/**
+ * One real call to a draft tool, from the server, which reaches public hosts only: the editor's
+ * Test and th30's `test` action both go through here.
+ */
+import { HTTP_METHODS } from '@theoremjs/agents';
+import { draftNetwork } from "../../compile.js";
+import { credentialHeaderProblem, credentialUrlProblem, unheldProblem, } from "../../mod.js";
+import { screenEndpoint } from "./project-address.js";
+/** A JSON object typed into the test, or why it isn't one. Blank is `undefined`. */
+function parseObject(raw, label) {
+    if (!raw.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return { value: parsed };
+        }
+    }
+    catch {
+        // Falls through to the error below.
+    }
+    return { error: `${label} must be a JSON object.` };
+}
+/** The test-connection request for `tool`. */
+function probeRequest(tool, sampleInput, credential) {
+    const headers = parseObject(tool.headersJson ?? '', 'Headers');
+    if (headers.error)
+        return { error: headers.error };
+    const credentialHeader = credentialHeaderProblem(headers.value);
+    if (credentialHeader)
+        return { error: credentialHeader };
+    const credentialInUrl = credentialUrlProblem(tool.toolType === 'mcp' ? tool.serverUrl : tool.endpoint);
+    if (credentialInUrl)
+        return { error: credentialInUrl };
+    // A mask stands for a value only the project holds: this request would carry the mask itself.
+    const unheld = unheldProblem(tool.toolName, {
+        endpoint: tool.endpoint,
+        serverUrl: tool.serverUrl,
+        headers: headers.value,
+    });
+    if (unheld)
+        return { error: unheld };
+    const authType = tool.authType ?? 'none';
+    const shared = {
+        headers: headers.value,
+        ...(authType === 'none'
+            ? {}
+            : {
+                auth: {
+                    type: authType,
+                    ...(authType === 'api_key' && tool.authQueryParam?.trim()
+                        ? { queryParam: tool.authQueryParam.trim() }
+                        : { headerName: tool.authHeaderName, headerPrefix: tool.authHeaderPrefix }),
+                },
+                testCredential: credential || undefined,
+            }),
+    };
+    if (tool.toolType === 'mcp') {
+        return {
+            body: {
+                type: 'mcp',
+                serverUrl: tool.serverUrl ?? '',
+                mcpToolName: tool.mcpToolName,
+                ...shared,
+            },
+        };
+    }
+    const input = parseObject(sampleInput, 'Sample input');
+    if (input.error)
+        return { error: input.error };
+    return {
+        body: {
+            type: 'http',
+            endpoint: tool.endpoint ?? '',
+            method: tool.method ?? HTTP_METHODS[0],
+            pathParams: tool.pathParams,
+            queryParams: tool.queryParams,
+            bodyParam: tool.bodyParam,
+            sampleInput: input.value,
+            ...shared,
+        },
+    };
+}
+/**
+ * Sends the probe with the draft's network guardrail, which the server keeps to only when it is
+ * the builder's own; any other keeps to public hosts. A request that can't be made, or a server
+ * that can't be reached, comes back as a failed result.
+ */
+export async function runToolProbe(tool, sampleInput, credential, guardrails) {
+    const request = probeRequest(tool, sampleInput, credential);
+    if (!request.body)
+        return { ok: false, error: request.error };
+    try {
+        const response = await fetch(`${screenEndpoint()}/test-connection`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ ...request.body, network: draftNetwork(guardrails) }),
+        });
+        return await response.json();
+    }
+    catch {
+        return { ok: false, error: "Couldn't reach the studio server." };
+    }
+}