toolroll 0.5.0

package/dist/project-tools.d.ts

@@ -0,0 +1,219 @@
+import type { Store, ToolActionInfo } from "./store.js";
+/** One secret a tool needs: an env name for a local server, or the value behind an http header. */
+export type ToolSecret = {
+    name: string;
+    optional: boolean;
+};
+export type ToolSpec = {
+    name: string;
+    transport: "stdio" | "http";
+    /** stdio: the program and its arguments (no secrets in either). */
+    command: string | null;
+    args: string[];
+    /** http: the server's address. */
+    url: string | null;
+    /** Every secret the tool needs. stdio: each is an env variable of the server process. */
+    secrets: ToolSecret[];
+    /** http: the secret sent as `Authorization: Bearer <value>`. */
+    bearer: string | null;
+    /** http: header name → the secret sent as its raw value. */
+    headerSecrets: Record<string, string>;
+    /** What it does, in plain words. */
+    about: string;
+};
+export type ToolTest = {
+    at: string;
+    ok: boolean;
+    tools: string[];
+    problem: string | null;
+};
+export type ProjectTool = {
+    id: number;
+    repo: string;
+    name: string;
+    spec: ToolSpec;
+    digest: string;
+    source: string;
+    createdAt: string;
+    createdBy: string;
+    lastTest: ToolTest | null;
+};
+/** A tool resolved for one launch: its spec and the secret values it gets. */
+export type ResolvedTool = {
+    spec: ToolSpec;
+    digest: string;
+    values: Record<string, string>;
+};
+/** Common servers, pinned to exact versions: the lead suggests from here first. */
+export declare const TOOL_CATALOG: readonly (ToolSpec & {
+    label: string;
+})[];
+export declare function catalogTool(id: string): (ToolSpec & {
+    label: string;
+}) | null;
+/** What a build is held to: how the server starts and which secrets it names — never their values or its description. */
+export declare function toolDigest(spec: ToolSpec): string;
+/** A tool definition from any source (catalog, console form, the lead, an import), checked whole. Throws in plain words. */
+export declare function validateToolSpec(input: Record<string, unknown>): ToolSpec;
+/** How the tool starts, in one line a person can check. Never a secret value. */
+export declare function toolCommandLine(spec: ToolSpec): string;
+export declare function toolSecretsDir(home?: string): string;
+export declare function readToolSecrets(repo: string, tool: string, home?: string): Record<string, string>;
+/** Set (or, with an empty value, clear) one secret of one tool. */
+export declare function setToolSecret(repo: string, tool: string, name: string, value: string, home?: string): void;
+export declare function setToolSecrets(repo: string, tool: string, values: Record<string, string>, home?: string): void;
+export declare function clearToolSecrets(repo: string, tool: string, home?: string): void;
+/** Required secrets with no value yet: the tool is left out of builds until they are set. */
+export declare function missingSecrets(spec: ToolSpec, values: Record<string, string>): string[];
+/** A server already configured on this computer, ready to add to a project (values moved, never shown). */
+export type FoundTool = {
+    spec: ToolSpec;
+    source: string;
+    values: Record<string, string>;
+};
+/**
+ * The MCP servers this computer already configures for a project: the
+ * repository's `.mcp.json`, Claude's global and per-project servers, and
+ * Codex's (from `codex mcp list --json`, passed in). The first of each
+ * name wins; unusable entries are left out.
+ */
+export declare function discoverTools(repo: string, codexServers: unknown[] | null, home?: string, environment?: NodeJS.ProcessEnv): FoundTool[];
+/** Start the server once, ask for its tools, and stop it: the proof a build can use it. */
+export declare function testTool(spec: ToolSpec, values: Record<string, string>, options?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    omitEnv?: readonly string[];
+}): Promise<{
+    ok: true;
+    tools: string[];
+} | {
+    ok: false;
+    problem: string;
+}>;
+/**
+ * Start the server once and read what each of its tools does (v94): the name,
+ * its description, what input it takes, and whether it says it only reads.
+ * A teammate is offered these, each under its own rule.
+ */
+export declare function listProjectToolActions(spec: ToolSpec, values: Record<string, string>, options?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    omitEnv?: readonly string[];
+}): Promise<{
+    ok: true;
+    actions: ToolActionInfo[];
+} | {
+    ok: false;
+    problem: string;
+}>;
+export declare function toolActions(result: unknown): ToolActionInfo[];
+export type ToolCall = {
+    ok: true;
+    text: string;
+    isError: boolean;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * Start the server once, call one of its tools, and stop it (v87): a flow's
+ * "Use a tool" step. The answer's text parts are kept; a tool that says it
+ * failed (isError) is an answer, not trouble reaching it.
+ */
+export declare function callProjectTool(spec: ToolSpec, values: Record<string, string>, name: string, args: Record<string, unknown>, options?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    omitEnv?: readonly string[];
+}): Promise<ToolCall>;
+/** The exact servers one launch gets, and those left out with why. */
+export type ToolLaunch = {
+    tools: ResolvedTool[];
+    skipped: {
+        name: string;
+        reason: string;
+    }[];
+};
+/** Everything a provider spawn needs to use exactly these tools, and the
+ * cleanup. `privateDir` holds the run's secret launch files: Codex starts
+ * tool servers outside its command sandbox, so its agent can be fenced out
+ * of that folder while the tools still read it. */
+export type ToolLaunchArgs = {
+    argv: string[];
+    env: Record<string, string>;
+    omitEnv: string[];
+    cleanup: () => void;
+    privateDir?: string;
+};
+/** Claude: only these servers (`--strict-mcp-config`), written to a private 0600 file removed after the run. */
+export declare function claudeToolArgs(launch: ToolLaunch): ToolLaunchArgs;
+export declare function carriedCodexSettings(includeModel: boolean, codexHome?: string): string[];
+/** Where the tool launcher lives beside this module, built. */
+export declare function toolLauncherPath(): string;
+/**
+ * Codex: the operator's config.toml is ignored whole (its MCP servers
+ * with it), ChatGPT apps and plugins are off, the model settings above
+ * are carried, and each tool is named by `-c` and started through the
+ * launcher. Codex gives its own environment to the agent's shell whatever
+ * its policy says, so no secret rides it: each tool's values sit in the
+ * run's private 0600 file and reach only that tool's process.
+ */
+export declare function codexToolArgs(launch: ToolLaunch, options: {
+    includeModel: boolean;
+    codexHome?: string;
+    launcher?: string;
+    node?: string;
+}): ToolLaunchArgs;
+/** Gemini: no way yet to hand it exactly these servers, so it gets none. */
+export declare const GEMINI_NO_TOOLS_ARGV: readonly string[];
+type ToolRows = Pick<Store, "projectTools">;
+/** The project's active tools with their parsed definitions and last test. */
+export declare function projectToolsOf(store: ToolRows, repo: string): ProjectTool[];
+/**
+ * The exact tools one attempt launches with: the project's active tools,
+ * limited to those its approval saw (a task approved before tools were
+ * sealed gets today's list), each with every required secret set. What is
+ * left out says why, in words the task page can show.
+ */
+export declare function toolLaunchFor(store: Pick<Store, "projectTools" | "getRun" | "refById" | "getScope" | "toolSealFor" | "orgPolicy">, runId: number, home?: string): ToolLaunch;
+/**
+ * One attempt's tools, ready for its provider, and recorded on the run:
+ * what it launched with and what was left out and why. The caller spawns
+ * with `argv`/`env` and calls `cleanup` when the process is done.
+ */
+export declare function prepareRunTools(store: Pick<Store, "projectTools" | "getRun" | "refById" | "getScope" | "toolSealFor" | "recordRunTools" | "orgPolicy">, runId: number, provider: "claude" | "codex" | "openrouter" | "gemini", options: {
+    home?: string;
+    now: Date;
+    includeModel: boolean;
+}): ToolLaunchArgs;
+/** When a launch's tools cannot be prepared, it still gets none of anything else's: the same isolation with an empty list. */
+export declare function noToolsArgs(provider: "claude" | "codex" | "openrouter" | "gemini", includeModel: boolean): ToolLaunchArgs;
+type ToolWrites = Pick<Store, "projectTools" | "addProjectTool" | "removeProjectTool" | "recordProjectToolTest">;
+/** Add one tool (and, for an import, the values it brings) to a project's builds. */
+export declare function addToolTo(store: ToolWrites, repo: string, input: ToolSpec, source: string, by: string, now: Date, options?: {
+    values?: Record<string, string>;
+    home?: string;
+}): {
+    ok: true;
+    spec: ToolSpec;
+} | {
+    ok: false;
+    message: string;
+};
+/** Take one tool away from every build now, with its stored secrets. */
+export declare function removeToolFrom(store: ToolWrites, repo: string, name: string, by: string, now: Date, home?: string): boolean;
+/** Test one tool of a project and keep the answer on it. */
+export declare function testToolOf(store: ToolWrites, repo: string, name: string, now: Date, options?: {
+    home?: string;
+    timeoutMs?: number;
+    omitEnv?: readonly string[];
+}): Promise<ToolTest | null>;
+/** Where a tool stands, in a few words: what a person reads first. */
+export declare function toolStanding(tool: ProjectTool, secretsSet: readonly string[]): {
+    ready: boolean;
+    words: string;
+};
+/** Names of a tool's secrets that have a value (never the values). */
+export declare function secretsSetFor(repo: string, tool: ToolSpec, home?: string): string[];
+/** A command line split into program and arguments, honouring "double" and 'single' quotes. */
+export declare function splitCommandLine(line: string): string[];
+export {};