toolroll 0.9.103 → 0.9.105

package/dist/project-tools.d.ts

@@ -1,318 +0,0 @@
-import type { Store, ToolActionInfo } from "./store.js";
-import { type BrokerOptions } from "./tool-broker.js";
-import { type FenceMethod, type LaunchFence } from "./agent-fence.js";
-import type { ProviderId } from "./contracts/provider.js";
-import { type SecretStoreKind } from "./tool-secret-store.js";
-import { type ToolSecret, type ToolSpec } from "./contracts/integration-metadata.js";
-export type { ToolSecret, ToolSpec };
-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;
-})[];
-/**
- * Apps that serve their own MCP on this computer: Connect adds them like a
- * common tool (`connect` is its one line of how), a test that can't reach one
- * says why (`offline`), and research may read what `reads` names (see
- * readsOnly in mcp-connect.ts). The only loopback address research reaches.
- */
-export type LocalApp = {
-    tool: string;
-    connect: string;
-    offline: string;
-    reads: readonly string[];
-};
-export declare const LOCAL_APPS: readonly LocalApp[];
-/** The local app a project's tool is, when it is one exactly as listed (same name and address). */
-export declare function localAppOf(spec: Pick<ToolSpec, "name" | "url">): LocalApp | null;
-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, a saved row), checked whole and made
- * the spec its schema (src/contracts/integration-metadata.ts) says. 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;
-/**
- * Where tool secrets were kept before (an existing ~/.toolroll/tool-secrets, or an older name's), read once when
- * Toolroll starts so their files move in on first use. Never where new secrets go.
- */
-export declare function legacyToolSecretsDir(home?: string): string | null;
-/** Commands that can start builds or serve the console: Toolroll's folder for secrets is made before any build runs. */
-export declare const SECRETS_FIRST: ReadonlySet<string>;
-/**
- * Toolroll's folder for the secrets it holds, beside `databaseFile`, checked against the sealing key the database
- * recorded: made now when `eager` (a command that can start builds), else the first time a secret is used.
- * A folder that can't be used is said in Settings and `toolroll integrations`; every secret is refused until then.
- */
-export declare function startToolSecrets(store: Pick<Store, "toolSecretKeyDigest" | "swapToolSecretKeyDigest" | "toolSecretLegacyDir">, databaseFile: string, clock: () => Date, options: {
-    eager: boolean;
-}): void;
-/** Toolroll's folder for secrets (tool-secret-store.ts): beside the database Toolroll started with, or a test's `state`. */
-export declare function toolSecretsDir(state?: string): string;
-/** A tool's secret values. Read only to test it, change it or start a run: a page reads which are set (secretsSetFor). */
-export declare function readToolSecrets(repo: string, tool: string, state?: 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, state?: string): void;
-/** Set (or, with empty values, clear) some secrets of one tool, in one change. */
-export declare function setToolSecrets(repo: string, tool: string, values: Record<string, string>, state?: string): void;
-export declare function clearToolSecrets(repo: string, tool: string, state?: string): void;
-/**
- * One renewal of a sign-in at a time, across Toolroll's processes (a lock in its folder) and within one: a service
- * that rotates its refresh token on every use would otherwise see the same one twice, and whichever answer was saved
- * last would be the newest only by luck.
- */
-export declare function renewingSignIn<T>(repo: string, tool: string, state: string | undefined, work: () => Promise<T>): Promise<T>;
-/** 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, projectConfig?: Record<string, unknown> | null): 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[];
-    server: ToolServer | Promise<ToolServer>;
-}): 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 subagent 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[];
-    server: ToolServer | Promise<ToolServer>;
-}): 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[];
-    server: ToolServer | Promise<ToolServer>;
-}): Promise<ToolCall>;
-/** The exact servers one launch gets, and those left out with why (`repo`: the project, from the run's record). */
-export type ToolLaunch = {
-    tools: ResolvedTool[];
-    skipped: {
-        name: string;
-        reason: string;
-    }[];
-    repo?: string;
-};
-/** Everything a provider spawn needs to use exactly these tools, and the
- * cleanup. `privateDir` holds the run's launch files, which name the broker
- * and its token, never a tool's secret (tool-broker.ts). */
-export type ToolLaunchArgs = {
-    argv: string[];
-    env: Record<string, string>;
-    omitEnv: string[];
-    cleanup: () => void;
-    privateDir?: string;
-    serverPids?: () => number[];
-    brokerPort?: number;
-};
-/** How a launch's tools are offered: research steps' servers only their read-only actions. */
-export type ToolLaunchOptions = {
-    broker?: BrokerOptions;
-    enabledTools?: Readonly<Record<string, readonly string[]>>;
-};
-/**
- * Claude: only these servers, in a private 0600 file removed after the run
- * (the provider adds `--strict-mcp-config`). Each is the broker's address
- * with this launch's token: Claude and its shell share one sandbox, so the
- * file holds nothing a tool signs in with.
- */
-export declare function claudeToolArgs(launch: ToolLaunch, options?: ToolLaunchOptions): Promise<ToolLaunchArgs>;
-/** Where the tool launcher lives beside this module, built. */
-export declare function toolLauncherPath(): string;
-/**
- * Codex: each tool is named by `-c` and started through the launcher, which
- * relays it to the launch's broker. The operator's config.toml, rules, apps,
- * plugins and hooks are already off (the provider's
- * CODEX_BUILD_ISOLATION_ARGV), and nothing of config.toml is carried. Codex
- * gives its own environment to the agent's shell whatever its policy says,
- * so nothing rides it: the launch files name the broker and its token, and
- * the folder holding them is fenced from the agent.
- */
-export declare function codexToolArgs(launch: ToolLaunch, options?: ToolLaunchOptions & {
-    launcher?: string;
-    node?: string;
-}): Promise<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;
-/** What stops a build reading a local tool server's environment: this computer's platform and the OS fence its run
- * gets, both fixed by the gateway before any tool is prepared (never from a launch's own files or the checkout). */
-export type ToolContainment = {
-    platform: NodeJS.Platform;
-    fence: FenceMethod;
-};
-/**
- * Why a local tool that carries secrets can't start for this launch, or null when it can. Its server's environment
- * holds the values, and a process of the same user can read another's (KERN_PROCARGS2, /proc/<pid>/environ) unless
- * an OS fence stops it: only the macOS sandbox around a Claude build does. Codex's filesystem policy can't deny that
- * read (OpenRouter uses the same harness); Claude's own file rules and Linux's bubblewrap don't stop it, and on Linux
- * hidepid hides nothing from the same user, so Linux never starts one.
- */
-export declare function secretToolRefusal(provider: ProviderId, containment: ToolContainment): string | null;
-/**
- * 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: ProviderId, options: {
-    home?: string;
-    now: Date;
-    containment: ToolContainment;
-    readOnly?: Readonly<Record<string, readonly string[]>>;
-    withheld?: Readonly<Record<string, string>>;
-    broker?: BrokerOptions;
-    fetcher?: typeof fetch;
-}): Promise<ToolLaunchArgs>;
-/** A run whose sign-ins couldn't all be made and kept: it doesn't start, and every token made for it is revoked. */
-export declare class RunSignInError extends Error {
-}
-/** 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: ProviderId): 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 | undefined;
-}): {
-    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 & ToolServerStore, repo: string, name: string, now: Date, options?: {
-    home?: string | undefined;
-    timeoutMs?: number;
-    omitEnv?: readonly string[];
-    available?: () => boolean;
-}): 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;
-};
-/** How a tool's runs get its credentials, in the words Settings and `toolroll integrations` share. */
-export type CredentialMode = {
-    mode: "run-token" | "held-key" | "no-key";
-    words: string;
-    detail: string | null;
-};
-export declare const CREDENTIAL_MODES: Readonly<Record<CredentialMode["mode"], Omit<CredentialMode, "mode">>>;
-/** A tool's credential mode from the names of its secrets that are set (never their values); null while a key it needs is missing. */
-export declare function credentialModeOf(spec: ToolSpec, secretsSet: readonly string[]): CredentialMode | null;
-/** Names of a tool's secrets that have a value, never the values: in the keychain, from the names kept beside them. */
-export declare function secretsSetFor(repo: string, tool: ToolSpec, state?: string): string[];
-/** Where this computer keeps tool secrets, in the words Settings and `toolroll integrations` share; `problem` when they can't be used. */
-export declare function toolSecretStorage(): {
-    kind: SecretStoreKind;
-    words: string;
-    filesOnly: boolean;
-    problem?: string;
-};
-/** A command line split into program and arguments, honouring "double" and 'single' quotes. */
-export declare function splitCommandLine(line: string): string[];
-/** What a tool server started outside a build needs of the store: the plane's own records of its state and pools. */
-export type ToolServerStore = Pick<Store, "databaseFile" | "listWorktrees" | "unfencedAgentsAllowed">;
-/** How a tool server started outside a build runs (toolServerFor): inside `fence`, or with none where there is nothing to
- * fence (a store with no database file) or an instance operator allowed unconfined agents; or not at all. */
-export type ToolServer = {
-    fence: LaunchFence | null;
-} | {
-    problem: string;
-};
-/**
- * The server fence for a project tool started outside a build (docs/plans/sandbox-parity.md C2): discovery, its Test
- * button, a flow's "Use a tool" step, a subagent's call. As the broker's servers are fenced: Toolroll's state, every
- * other launch's folder and the checkout pools denied, and nothing a build writes (its project's caches) read, so no
- * byte a build wrote can load into a process that holds the tool's secrets. Required: where this machine can't confine
- * it, it doesn't start unless an instance operator allowed unconfined agents.
- */
-export declare function toolServerFor(store: ToolServerStore, repo: string, options?: {
-    home?: string;
-    available?: () => boolean;
-}): Promise<ToolServer>;
-/** Each project's `.mcp.json` as the console last read it off its thread (its background pass): what its pages and the
- * lead offer, so neither reads a project folder on the console's thread. */
-export declare const savedProjectMcp: Map<string, Record<string, unknown> | null>;

package/dist/project.d.ts

@@ -1,65 +0,0 @@
-/**
- * Projects, as the console means them: a project IS a repo path on this
- * server — one row of truth, no new concept — and, critically, project
- * *selection* is never project *authorization*.
- *
- * The ceiling is server configuration: the repos named at startup, plus any
- * git repository under a configured project root. A session picking a
- * project picks from inside that ceiling; a registry row, a store row, or a
- * request header can name a path, but naming is not access (per the v2
- * review's first finding). No configuration at all is the legacy unscoped
- * mode — everything visible — and the code says so where it decides.
- */
-import { type ExecResult, type RunOptions } from "./exec.js";
-export type ProjectExec = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
-/**
- * One canonicalization for every path that becomes project identity:
- * startup config, a session open, task placement. Comparisons elsewhere
- * fall back to raw equality for legacy rows written before this existed.
- * Throws FolderUnavailable when the console's folder gate holds the read back (folder-gate.ts).
- */
-export declare function canonicalProject(path: string): string | null;
-/** Two repo identities, canonical when possible, raw-equal as the legacy fallback. */
-export declare function sameRepo(a: string | null, b: string | null): boolean;
-/** Whether this path is actually a git repository — direct argv, bounded, no shell. */
-export declare function isGitRepo(path: string, exec?: ProjectExec): Promise<boolean>;
-/** Validate a whole selection before enrolling anything; subfolders resolve to their checkout root. */
-export declare function projectSelection(paths: readonly string[], exec?: ProjectExec): Promise<string[]>;
-export type ProjectCeiling = {
-    /** Canonical repo paths named at startup. */
-    repos: readonly string[];
-    /** Canonical directories: any git repo under one is authorized. */
-    roots: readonly string[];
-    /** How this ceiling resolves a path it is asked about (project-identity.ts): the console's saved identities, which
-     * read no folder. Absent: canonicalProject, a synchronous read. */
-    canon?: (path: string) => string | null;
-};
-/**
- * Resolve the startup configuration once. A configured path that does not
- * currently resolve is kept in its normalized form rather than dropped —
- * dropping would silently *widen* the server toward unscoped mode, and a
- * ceiling that loosens itself when a disk is unmounted is not a ceiling.
- */
-export declare function resolveCeiling(repos: readonly string[], roots: readonly string[], canon?: (path: string) => string | null | undefined): {
-    ceiling: ProjectCeiling;
-    unresolved: string[];
-};
-/** Whether the ceiling is even configured. Unconfigured = legacy unscoped mode. */
-export declare function unscoped(ceiling: ProjectCeiling): boolean;
-/**
- * The authorization question, answered from configuration alone. A path
- * under a root must additionally BE a git repository — a root authorizes
- * its repos, not every directory beneath it — which is why this is async.
- */
-export declare function authorizedProject(ceiling: ProjectCeiling, path: string, exec?: ProjectExec): Promise<boolean>;
-/**
- * The cheap synchronous subset for per-row visibility checks: a row whose
- * repo is NULL (unplaced) is always visible; a named repo must match the
- * configured set or live under a root. The under-a-root case skips the
- * git check here — rows only enter the store through placement, which
- * validated them; this guards reads, and a non-repo directory under an
- * authorized root read-visible is a smaller wrong than an async row filter.
- */
-export declare function rowVisible(ceiling: ProjectCeiling, repo: string | null): boolean;
-/** A display name for a project: its basename, the way people say it. */
-export declare function projectName(path: string): string;

package/dist/prompt.d.ts

@@ -1,33 +0,0 @@
-/**
- * Interactive prompts, for exactly one situation: a person at a real
- * terminal left out a value a command needs. Every prompt is gated on a
- * TTY at both ends and never fires under --json — an agent or a cron job
- * gets the same immediate usage refusal as always, because a scheduler
- * hanging on "password:" at 3am is the one bug this module must not have.
- */
-/** Whether asking is even possible: a human on both ends of the pipe. */
-export declare function interactive(): boolean;
-/** The program names of this process's ancestors, nearest first: each one's command and, for a script run by node
- * or python, the script's name. Empty where `ps` cannot say. */
-export declare function ancestorPrograms(): string[];
-/**
- * Whether a coding agent is running this command. An agent's shell can be a
- * real terminal, yet whatever is printed lands in its transcript and nobody
- * types at the prompt, so it is treated like no terminal at all. The agent is
- * known by a variable it sets or, for one that sets none, by the program above
- * this one. `programs` is read only for this process's own environment.
- */
-export declare function underAgent(env?: Record<string, string | undefined>, programs?: () => readonly string[]): boolean;
-export declare function ask(question: string): Promise<string>;
-/** Like ask, but what is typed never echoes — passwords live here. */
-/**
- * Raw-mode input is not text: a terminal with bracketed paste on wraps a
- * pasted password in ESC[200~ … ESC[201~, and any arrow or function key
- * arrives as an escape sequence. Every CSI/SS3 sequence is dropped whole,
- * so a pasted secret compares equal to a typed one (setup review: the
- * hidden prompt refused every pasted password on iTerm and Terminal.app).
- */
-export declare function sanitizeHiddenInput(text: string): string;
-export declare function askHidden(question: string): Promise<string>;
-/** A yes/no gate for an act worth a beat of deliberateness. */
-export declare function confirm(question: string): Promise<boolean>;