@praesidias/sdk 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,671 @@
+/**
+ * Faults: Praesidias could not give a clear answer. They are thrown, and whenever one is thrown
+ * the guarded action has NOT run. A policy answer (blocked, needs approval) is never an error;
+ * it is a result.
+ *
+ * No error ever carries the API key, a request body or a reply body: only a code, a status and
+ * a correlation id.
+ */
+declare class PraesidiasError extends Error {
+    /** A stable, machine-readable code. */
+    readonly code: string;
+    readonly status: number | null;
+    readonly correlationId: string | null;
+    constructor(message: string, details: {
+        code: string;
+        status?: number | null;
+        correlationId?: string | null;
+    });
+}
+/** Praesidias could not be reached, timed out, or answered in a way that cannot be trusted. */
+declare class PraesidiasUnavailableError extends PraesidiasError {
+}
+/** The key was refused (401 or 403). Not retried. */
+declare class PraesidiasAuthError extends PraesidiasError {
+}
+/** The SDK is set up in a way that cannot work: no key, an insecure address, the kit not enabled. */
+declare class PraesidiasConfigError extends PraesidiasError {
+}
+/** Praesidias refused the request itself (a 4xx that is not about the key). */
+declare class PraesidiasRequestError extends PraesidiasError {
+}
+
+type LogEvent = {
+    event: 'request' | 'retry' | 'response' | 'failure';
+    method: string;
+    path: string;
+    attempt: number;
+    status?: number;
+    code?: string;
+    correlationId: string;
+    durationMs?: number;
+};
+/** The header a workload identity token is sent in (workload binding). */
+declare const WORKLOAD_TOKEN_HEADER = "x-praesidias-workload-token";
+
+/**
+ * Telling Praesidias which tools an agent has (POST /agent/tools), so the Console can show them
+ * and say which have a rule. One shape for every reporter: the SDK, the adapters, the gateways
+ * and the command line. Only names and the TYPES of inputs are sent, never values.
+ */
+/** Who is reporting. The core accepts exactly these. */
+type ToolSource = 'claude_code' | 'codex' | 'mcp' | 'sdk' | 'adapter' | 'gateway';
+type ToolInputType = 'string' | 'number' | 'boolean' | 'array' | 'object';
+type ReportedTool = {
+    /** The tool's own name, as the agent knows it. */
+    name: string;
+    /** The action Praesidias decides on when the tool is used. */
+    action: string;
+    description?: string | null;
+    /** The tool's inputs by name: their types only. */
+    inputs?: Record<string, {
+        type: ToolInputType;
+        description?: string;
+    }>;
+};
+/** At most this many tools in one request; more are sent in several. */
+declare const TOOLS_PER_REPORT = 500;
+/**
+ * The tools as the core accepts them: anything it would refuse is left out or shortened here,
+ * so one odd tool never loses the whole list. The same action twice keeps the last.
+ */
+declare function toolsForReport(tools: readonly ReportedTool[]): ReportedTool[];
+/** A JSON Schema's top-level properties as input types (MCP's inputSchema, a tool's parameters). */
+declare function inputsOfSchema(schema: unknown): NonNullable<ReportedTool['inputs']>;
+
+type Resource = {
+    type: string;
+    id?: string | null;
+};
+type PraesidiasOptions = {
+    /** The agent's key. Defaults to the PRAESIDIAS_API_KEY environment variable. Never hard-code it. */
+    apiKey?: string;
+    /** Where Praesidias is. Defaults to PRAESIDIAS_URL. https, except on localhost. */
+    baseUrl?: string;
+    /** The system this agent acts on, as your areas name it (for example "payments"). */
+    system?: string;
+    /** The Console's address, for links in results. Defaults to PRAESIDIAS_CONSOLE_URL. */
+    consoleUrl?: string;
+    /** Per-request timeout. Default 10 seconds. */
+    timeoutMs?: number;
+    /** Retries on network errors and 429/502/503/504 only. Default 2. */
+    retries?: number;
+    /** What to do when an action needs approval. Default "wait". */
+    onApproval?: 'wait' | 'return';
+    /** How long "wait" waits. Default 15 minutes. */
+    approvalTimeoutMs?: number;
+    /** Called for each request, retry and reply. It is never given the key or a body. */
+    logger?: (event: LogEvent) => void;
+    /** Replace fetch (for tests or a proxy). */
+    fetch?: typeof fetch;
+    /** Accept plain http for an address that is not localhost. Do not use in production. */
+    allowInsecure?: boolean;
+    /**
+     * When this agent is bound to its workload in the Console: a file the platform keeps a fresh
+     * identity token in (for Kubernetes, the projected service account token's path). Read on every
+     * request. Defaults to PRAESIDIAS_WORKLOAD_TOKEN_FILE.
+     */
+    workloadTokenFile?: string;
+    /**
+     * The workload identity token itself, or a function that returns a fresh one (or null to send
+     * none with that request). Use instead of `workloadTokenFile` when the token does not come from
+     * a file. Given, it takes the place of PRAESIDIAS_WORKLOAD_TOKEN_FILE.
+     */
+    workloadToken?: string | (() => string | null | undefined | Promise<string | null | undefined>);
+    /** @internal Timings, shortened by tests. */
+    timing?: Partial<Timing>;
+};
+type Timing = {
+    retryDelayMs: number;
+    /** How long "who am I" (and with it Audit mode) is cached. */
+    meCacheMs: number;
+    pollStartMs: number;
+    pollMaxMs: number;
+    /** How long an authorization proof says it is good for. */
+    authorizationTtlMs: number;
+};
+type AgentInfo = {
+    organizationId: string;
+    principalId: string;
+    name: string | null;
+    kind: string | null;
+    /** The grants to assert. Whether they are still good is for the decision to say. */
+    grantIds: string[];
+    hasAccess?: boolean;
+    frozen: boolean;
+    mode: 'enforce' | 'audit';
+    audit: {
+        level: 'new_actions' | 'everything';
+        endsAt: string;
+    } | null;
+    agentKitEnabled: boolean;
+    authorizationKind: string;
+    /** True when this agent is bound to its workload: every request carries its token. */
+    workloadRequired?: boolean;
+};
+/** What a decision says beyond yes or no, for the rules that use them (schemaVersion 3). */
+type DecisionDetails = {
+    /** The request's fields that did not match what the rule expects: missing, wrong type, too long. */
+    problems: Array<{
+        path: string;
+        problem: string;
+    }>;
+    /** The budget that would have gone over its cap, when that was the reason. */
+    budget: {
+        budgetId: string;
+        spent: string;
+        amount: string;
+        cap: string;
+    } | null;
+    /** Why the approvals given were not accepted, one code per approval. */
+    approvalFailures: string[];
+};
+type Decision = {
+    decisionId: string;
+    allowed: boolean;
+    /** Praesidias's reason code and the same thing in plain words. */
+    reason: {
+        code: string;
+        message: string;
+    };
+    /** The facts sent with the request, exactly as decided on. */
+    context: Record<string, unknown>;
+    /** The case of the rule that decided, when the rule has cases. */
+    caseId: string | null;
+    /**
+     * The fields the decision is locked to: the authorization and the execution must carry the
+     * same values. The SDK sends them for you.
+     */
+    boundPaths: string[];
+    details: DecisionDetails;
+    /** True when the only thing missing is a person's approval. */
+    needsApproval: boolean;
+    expiresAt: string | null;
+    action: string;
+    resource: Resource;
+    system: string;
+    rulesVersion: number | null;
+    correlationId: string;
+};
+/** Praesidias's signed statement that this action on this resource was authorized. */
+type Proof = {
+    id: string;
+    decisionId: string;
+    kind: string;
+    subjectId: string;
+    hash: string;
+    signature: string;
+    signingKeyId: string | null;
+    issuedAt: string;
+    payload: Record<string, unknown>;
+    /** The whole proof as Praesidias returned it, to hand to a service that will verify it. */
+    raw: Record<string, unknown>;
+};
+type ApprovalStatus = {
+    decisionId: string;
+    state: 'waiting' | 'approved' | 'rules_changed' | 'not_waiting';
+    approvalsHave: number;
+    approvalsNeeded: number | null;
+    approvalArtifactIds: string[];
+};
+type CallOptions = {
+    /** Overrides the client's system for this call. */
+    system?: string;
+    /** Facts about the request, recorded with the decision. Never put secrets here. */
+    context?: Record<string, unknown>;
+    /** Reuse the same key to make a repeat of this exact call safe. One is made if you give none. */
+    idempotencyKey?: string;
+    /** Ties this call to your own request id in every record. */
+    correlationId?: string;
+    signal?: AbortSignal;
+};
+type GuardOptions = CallOptions & {
+    onApproval?: 'wait' | 'return';
+    approvalTimeoutMs?: number;
+};
+/** What the guarded function is given. */
+type GuardContext = {
+    decisionId: string;
+    correlationId: string;
+    /** The signed authorization. Null only when running under Audit mode, where there is none. */
+    proof: Proof | null;
+    /** True when Praesidias denied this and it is going ahead only because of Audit mode. */
+    auditMode: boolean;
+};
+type Common = {
+    decisionId: string | null;
+    correlationId: string;
+    consoleUrl: string | null;
+};
+type GuardResult<T> = (Common & {
+    status: 'executed';
+    value: T;
+    proof: Proof | null;
+    /**
+     * Set when it ran under Audit mode: what would have happened otherwise. `unknown`, with
+     * `offline`, when Praesidias could not be reached: it ran because the agent is in Audit
+     * mode, and the request is sent to Praesidias to record once it can be reached again.
+     */
+    audit: {
+        wouldHave: 'blocked' | 'waited' | 'unknown';
+        level: 'new_actions' | 'everything';
+        offline?: true;
+    } | null;
+    /** False when the action ran but reporting its outcome failed. The action still ran. */
+    outcomeRecorded: boolean;
+}) | (Common & {
+    status: 'blocked';
+    reason: {
+        code: string;
+        message: string;
+    };
+}) | (Common & {
+    status: 'needs_approval';
+    reason: {
+        code: string;
+        message: string;
+    };
+    approvalsHave: number;
+    approvalsNeeded: number | null;
+    /** Wait again (for example after telling the user), with the same or a new timeout. */
+    resume: (options?: {
+        approvalTimeoutMs?: number;
+        signal?: AbortSignal;
+    }) => Promise<GuardResult<T>>;
+});
+/**
+ * A client for one agent. It needs only the agent's key: who the agent is, and which grants it
+ * must assert, are read from Praesidias.
+ */
+declare class Praesidias {
+    private readonly http;
+    private readonly timing;
+    private readonly system;
+    private readonly consoleUrl;
+    private readonly onApproval;
+    private readonly approvalTimeoutMs;
+    private cachedMe;
+    /** The last "who am I" ever read, however old: only to know, offline, if Audit mode was on. */
+    private lastMe;
+    /** Requests run offline under Audit mode, oldest first, to record once Praesidias answers. */
+    private readonly offline;
+    private flushing;
+    constructor(options?: PraesidiasOptions);
+    toJSON(): {
+        praesidias: string;
+    };
+    /**
+     * Who this key is. Cached briefly. If it cannot be read, this throws: the SDK never guesses
+     * who the agent is or whether it is in Audit mode.
+     */
+    me(options?: {
+        fresh?: boolean;
+        signal?: AbortSignal;
+    }): Promise<AgentInfo>;
+    /** How many requests that ran offline, under Audit mode, are still to be recorded. */
+    get offlinePending(): number;
+    /**
+     * Sends the requests that ran offline under Audit mode as ordinary decisions, oldest first, so
+     * they are in the record. Stops at the first that cannot be sent; the rest wait for next time.
+     */
+    flushOffline(): Promise<number>;
+    /**
+     * Tells Praesidias which tools this agent has, so the Console can list them and say which have
+     * a rule. Names and input types only. Never throws and never holds the agent up: false when it
+     * could not be sent (an older Praesidias without this, or one that cannot be reached).
+     */
+    reportTools(source: ToolSource, tools: readonly ReportedTool[]): Promise<boolean>;
+    private linkTo;
+    private systemFor;
+    /** Asks Praesidias whether this agent may do this action on this resource. Nothing is run. */
+    decide(action: string, resource: Resource, options?: CallOptions & {
+        approvalArtifactIds?: string[];
+    }): Promise<Decision>;
+    /**
+     * Gets Praesidias's signed authorization for an allowed decision. Call it straight after an
+     * ALLOW and before running the action; a decision can be authorized once.
+     */
+    commit(decision: Decision, options?: Pick<CallOptions, 'idempotencyKey' | 'signal'>): Promise<Proof>;
+    /** Whether a decision that needs approval has been approved yet. */
+    approvalStatus(decisionId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ApprovalStatus>;
+    /** Reports what happened after an authorized action ran. */
+    reportOutcome(proof: Proof, outcome: {
+        status: 'succeeded';
+    } | {
+        status: 'failed';
+        error?: unknown;
+    }): Promise<void>;
+    /**
+     * Runs `fn` only if Praesidias allows this action on this resource.
+     *
+     *   decide → (wait for approval if needed) → get the signed authorization → run fn → report
+     *
+     * Returns `executed`, `blocked` or `needs_approval`. Throws a PraesidiasError when Praesidias
+     * could not give a clear answer; in that case `fn` has not run. If `fn` itself throws, its
+     * error is reported as a failed outcome and thrown on unchanged.
+     */
+    guard<T>(action: string, resource: Resource, fn: (context: GuardContext) => Promise<T> | T, options?: GuardOptions): Promise<GuardResult<T>>;
+}
+
+/**
+ * The subject of an authorization must be a UUID. This derives one from the resource, the same
+ * way every time (a version 5 UUID), so the same resource in the same organization always has
+ * the same subject, in every SDK.
+ */
+declare function subjectIdFor(organizationId: string, resource: {
+    type: string;
+    id?: string | null;
+}): string;
+
+declare function sentenceFor(code: string): string;
+
+/**
+ * The mapping: how a tool call becomes an action on a resource. One format, used everywhere a
+ * tool is governed: the MCP gateway, the API gateway's sibling, and every framework adapter.
+ *
+ * Every tool is governed unless the mapping says otherwise. With nothing said about a tool, a
+ * call to `create_issue` in a tool set named `github` is the action `github.create_issue` on a
+ * resource of type `create_issue`, whose id is taken from the first of a few common argument
+ * names.
+ */
+type Condition = {
+    arg: string;
+} & ({
+    gt: number;
+} | {
+    gte: number;
+} | {
+    lt: number;
+} | {
+    lte: number;
+} | {
+    eq: string | number | boolean;
+} | {
+    ne: string | number | boolean;
+} | {
+    in: Array<string | number>;
+} | {
+    startsWith: string;
+} | {
+    contains: string;
+} | {
+    exists: boolean;
+});
+type FieldSource = string | {
+    arg: string;
+    as?: 'integer' | 'string' | 'boolean';
+};
+type ToolMapping = {
+    /** The action name. `{server}` and `{tool}` are filled in. */
+    action?: string;
+    resource?: {
+        type?: string;
+        idFrom?: string | string[];
+    };
+    /** Checked in order; the first that matches replaces the action (and resource, if given). */
+    when?: Array<{
+        if: Condition | Condition[];
+        action: string;
+        resource?: ToolMapping['resource'];
+    }>;
+    /** Argument names whose VALUES are recorded with the decision. Nothing else is. */
+    context?: string[];
+    /**
+     * The request's fields, for a rule that states what its action carries (schemaVersion 3):
+     * field name to argument (`"amount": "amount_cents"`, or `{ "arg": "to.account" }`), with an
+     * optional type to read a numeric or yes/no string as (`"as": "integer" | "string" | "boolean"`).
+     * Given, the request carries exactly these fields and nothing else, so it matches the rule's
+     * list. A value that is missing or cannot be read as asked is left out, and Praesidias refuses
+     * the request: nothing is guessed.
+     */
+    fields?: Record<string, FieldSource>;
+    /** Overrides the system for this tool. */
+    system?: string;
+    /**
+     * Let this tool through WITHOUT asking Praesidias. For tools that only read and that you have
+     * decided need no record. Off unless you set it.
+     */
+    ungoverned?: boolean;
+};
+type MappingFile = {
+    /** The system these tools act on, as your areas name it. */
+    system: string;
+    /** A short name for this set of tools (an MCP server, an agent's toolbox), used in default action names. */
+    server: string;
+    defaults?: Pick<ToolMapping, 'action' | 'resource' | 'context' | 'fields'>;
+    /** By tool name. A name may end in `*` to cover a family of tools. */
+    tools?: Record<string, ToolMapping>;
+};
+type Mapped = {
+    governed: false;
+} | {
+    governed: true;
+    action: string;
+    resource: {
+        type: string;
+        id: string | null;
+    };
+    system: string;
+    context: Record<string, unknown>;
+};
+declare class MappingError extends Error {
+}
+/** Checks a mapping when it is loaded, so a mistake stops the program at start instead of surfacing mid-call. */
+declare function checkMapping(raw: unknown): MappingFile;
+declare function loadMapping(path: string): MappingFile;
+/** Plain comparisons on one argument. No expressions are ever evaluated. */
+declare function matches(condition: Condition, args: unknown): boolean;
+/**
+ * The action a tool is decided as, before any `when` picks another for particular arguments:
+ * what a tool list reports. Null for a tool the mapping leaves ungoverned, or whose action name
+ * Praesidias would not accept.
+ */
+declare function toolAction(file: MappingFile, tool: string): string | null;
+/** Turns one tool call into the action and resource Praesidias is asked about. */
+declare function mapToolCall(file: MappingFile, tool: string, args: unknown): Mapped;
+
+/** A tool as a framework describes it: its name, and optionally what it does and its inputs. */
+type DescribedTool = {
+    name: string;
+    description?: unknown;
+    schema?: unknown;
+};
+/**
+ * What happened to one tool call. `ran` says whether the tool's own code was run; `message`
+ * is a plain sentence fit to hand back to a model or a person.
+ */
+type ToolOutcome<T> = {
+    status: 'executed';
+    ran: true;
+    value: T;
+    message: string;
+    decisionId: string | null;
+    audit: boolean;
+} | {
+    status: 'passed_through';
+    ran: true;
+    value: T;
+    message: string;
+    decisionId: null;
+    audit: false;
+} | {
+    status: 'blocked';
+    ran: false;
+    message: string;
+    decisionId: string | null;
+    code: string;
+    consoleUrl: string | null;
+} | {
+    status: 'needs_approval';
+    ran: false;
+    message: string;
+    decisionId: string | null;
+    approvalsHave: number;
+    approvalsNeeded: number | null;
+    consoleUrl: string | null;
+}
+/** Praesidias could not confirm the action is allowed. It was not carried out. */
+ | {
+    status: 'unavailable';
+    ran: false;
+    message: string;
+    decisionId: null;
+    code: string;
+};
+type ToolGateOptions = {
+    /**
+     * What to do when a tool call needs a person's approval. "return" (the default for tools)
+     * answers at once so a chat agent never hangs: the model is told it needs approval, and the
+     * same call made again after someone approves goes ahead. "wait" holds the call open.
+     */
+    onApproval?: 'return' | 'wait';
+    /** With "wait": how long, in milliseconds. */
+    approvalTimeoutMs?: number;
+    /** One line per tool call. Tool and action names only: never arguments, never a key. */
+    log?: (line: string) => void;
+};
+/**
+ * Governs an agent's tools with one mapping. This is what every framework adapter is built on:
+ * give it the tool's name, its arguments, and the function that does the work.
+ *
+ * The work runs only when Praesidias allows the action. Nothing is ever let through because
+ * Praesidias could not be asked: that is "unavailable", and the tool does not run.
+ */
+declare class ToolGate {
+    private readonly praesidias;
+    readonly mapping: MappingFile;
+    private readonly onApproval;
+    private readonly approvalTimeoutMs;
+    private readonly log;
+    private readonly waiting;
+    /** Every tool this gate has been given, by action, as last sent to Praesidias. */
+    private readonly known;
+    private reportTimer;
+    private lastReport;
+    constructor(praesidias: Praesidias, mapping: MappingFile, options?: ToolGateOptions);
+    /**
+     * Tells Praesidias about tools this agent has (the adapters call it with the tools they are
+     * given), so the Console lists them and says which have a rule. Tools given together, or one
+     * at a time in a row, go in one report, sent shortly after; a list that has not changed is not
+     * sent again. Never throws and never holds anything up.
+     */
+    reportTools(tools: readonly DescribedTool[]): void;
+    /** Runs `fn` if Praesidias allows this tool call, and says what happened either way. */
+    run<T>(tool: string, args: unknown, fn: () => Promise<T> | T): Promise<ToolOutcome<T>>;
+    /**
+     * A tool function that governs itself. When the action is not allowed it does not throw: it
+     * returns the sentence saying why, which is what a model needs to read in order to tell the
+     * user or to try again later. Pass `refuse` to turn that sentence into your framework's shape.
+     */
+    wrap<A, T, R = string>(tool: string, fn: (args: A) => Promise<T> | T, refuse?: (outcome: Exclude<ToolOutcome<T>, {
+        ran: true;
+    }>) => R): (args: A) => Promise<T | R>;
+}
+/** A gate for an agent's tools: `createToolGate(new Praesidias(), mapping)`. */
+declare function createToolGate(praesidias: Praesidias, mapping: MappingFile, options?: ToolGateOptions): ToolGate;
+
+/**
+ * Reads a shell command the way Praesidias needs to decide on it: which programs it runs, with
+ * which subcommand and flags. It never runs anything and never expands anything.
+ *
+ * A compound command (`&&`, `||`, `;`, `|`, `&`, newlines, subshells) is split into its parts,
+ * and every part is decided on. Anything that would make the shell build or run code that cannot
+ * be read here (`eval`, `$(…)`, backticks, `<(…)`, `sh -c`, a program named by a variable) makes
+ * the whole command "unparsed": it is then decided once, as the program `__unparsed__`.
+ *
+ * The same rules are implemented in the Python SDK (praesidias/agent_actions.py); both run the
+ * cases in spec/tool-actions-cases.json and must agree.
+ */
+type ShellPart = {
+    /** The program run, without its directory: `/usr/bin/git` is `git`. Lowercase. */
+    program: string;
+    /** The first argument that is not a flag (for `git push`, `push`). Empty when there is none. */
+    subcommand: string;
+    /** Every flag, as written, plus `-rf` split into `-r` and `-f`, and `--x=y` also as `--x`. */
+    flags: string[];
+    /** This part's own text. */
+    command: string;
+};
+type ParsedShell = {
+    parsed: true;
+    parts: ShellPart[];
+} | {
+    parsed: false;
+};
+declare const UNPARSED = "__unparsed__";
+/**
+ * `posix` is sh/bash/zsh. `powershell` differs where it matters here: a backslash is an ordinary
+ * character (Windows paths), and `''` inside single quotes is a quote. Its escape character, the
+ * backtick, makes a command unparsed in both.
+ */
+type ShellDialect = 'posix' | 'powershell';
+/** Reads a shell command into the parts Praesidias decides on. See the top of this file. */
+declare function parseShellCommand(command: string, dialect?: ShellDialect): ParsedShell;
+
+/**
+ * What Praesidias decides on for one tool call of a coding agent (Claude Code, Codex): the
+ * action, the resource and the facts sent with it. Fixed by the contract between the kit and
+ * the Console's starting policy, and by spec/tool-actions-cases.json, which the Python SDK runs
+ * too (praesidias/agent_actions.py).
+ *
+ * File contents are never sent: only paths.
+ */
+type CodingAgent = 'claude_code' | 'codex';
+type AgentAction = {
+    action: string;
+    resourceType: string;
+    resourceId: string | null;
+    context: Record<string, unknown>;
+};
+type AgentToolCall = {
+    agent: CodingAgent;
+    /** The tool's name as the agent reports it (`Bash`, `Read`, `mcp__github__create_issue`). */
+    tool: string;
+    /** The tool's input as the agent reports it. */
+    input: unknown;
+    /** Where the agent is working. Relative paths are read from here. */
+    cwd?: string;
+    /** The project's root (CLAUDE_PROJECT_DIR), for `in_project`. Defaults to `cwd`. */
+    projectDir?: string;
+    /** The user's home folder, shown as `~`. */
+    home?: string;
+    /** For an MCP tool: the input names its server declares. Only those are sent. */
+    declaredInputs?: string[] | null;
+    /** Which path rules apply. Defaults to this machine's. */
+    platform?: 'posix' | 'win32';
+};
+/** The longest action name the decision endpoint accepts. */
+declare const MAX_ACTION_LENGTH = 64;
+/**
+ * True when any folder or file name in the path is a secret's (`.env`, `*.pem`, `.ssh`, …).
+ * A glob is read with its wildcards taken as empty, so `.env*` and `**\/*.pem` count too.
+ */
+declare function isSensitivePath(path: string): boolean;
+/** The action name rules: `[A-Za-z0-9_.:-]`, at most 64 characters. A longer one keeps a hash. */
+declare function fitActionName(name: string): string;
+/** `mcp__<server>__<tool>` as the action `mcp.<server>.<tool>`; null when the name is not an MCP tool's. */
+declare function mcpAction(tool: string): {
+    action: string;
+    server: string;
+    tool: string;
+} | null;
+/** The action for a tool the table does not know: `claude_code.<tool>` or `codex.<tool>`. */
+declare function otherAction(agent: CodingAgent, tool: string): string;
+/** Every part of a shell command, each its own `shell.run`; one `__unparsed__` if it cannot be read. */
+declare function shellActions(command: string, dialect?: ShellDialect): AgentAction[];
+/** The files a Codex patch touches (`*** Add File:`, `*** Update File:`, `*** Delete File:`, `*** Move to:`). */
+declare function patchPaths(patch: string): string[];
+/**
+ * The actions for one tool call: usually one; one per part of a compound shell command and one
+ * per file of a Codex patch. Every one must be allowed for the call to go ahead.
+ */
+declare function agentToolActions(call: AgentToolCall): AgentAction[];
+/** The inputs a built-in tool's action carries, as the tool list reports them (POST /agent/tools). */
+declare const BUILT_IN_INPUTS: Record<string, Record<string, {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    description: string;
+}>>;
+
+export { type AgentAction, type AgentInfo, type AgentToolCall, type ApprovalStatus, BUILT_IN_INPUTS, type CallOptions, type CodingAgent, type Condition, type Decision, type DecisionDetails, type DescribedTool, type FieldSource, type GuardContext, type GuardOptions, type GuardResult, type LogEvent, MAX_ACTION_LENGTH, type Mapped, MappingError, type MappingFile, type ParsedShell, Praesidias, PraesidiasAuthError, PraesidiasConfigError, PraesidiasError, type PraesidiasOptions, PraesidiasRequestError, PraesidiasUnavailableError, type Proof, type ReportedTool, type Resource, type ShellDialect, type ShellPart, TOOLS_PER_REPORT, ToolGate, type ToolGateOptions, type ToolInputType, type ToolMapping, type ToolOutcome, type ToolSource, UNPARSED, WORKLOAD_TOKEN_HEADER, agentToolActions, checkMapping, createToolGate, fitActionName, inputsOfSchema, isSensitivePath, loadMapping, mapToolCall, matches, mcpAction, otherAction, parseShellCommand, patchPaths, sentenceFor, shellActions, subjectIdFor, toolAction, toolsForReport };