@cloudhal/mcp-server 0.0.0-stage → 0.1.1

package/dist/src/common.d.ts

@@ -0,0 +1,258 @@
+/**
+ * What every tool module shares: the SDK-independent tool shape, the call context, `ToolError` and
+ * the mapping of store errors to it (stable codes, actionable text), and small schema/prompt helpers.
+ */
+import { type ApprovalStore, type AuditLog, type CallClass, type Decision, type OwnershipResolver, type OwnLimit, type PolicyEngine, type Principal, type Scope, type ToolAnnotations } from "@cloudhal/agent-runtime";
+import type { AnalyticsService } from "@cloudhal/analytics/service";
+import type { Actor, ContentEntry, Page, Site, Snapshot } from "@cloudhal/core-contracts";
+import type { InvariantCode, SiteGraphStore } from "@cloudhal/core-ts";
+import type { BodyDiff } from "@cloudhal/core-ts/body-blocks";
+import type { FetchTransport } from "@cloudhal/core-ts/media";
+import type { CommentsDeps } from "./comments.js";
+import type { PageRenderer, RenderLimiter } from "./render.js";
+import { type RunContext, type SchedulesDeps } from "./schedules.js";
+export type JsonSchema = Record<string, unknown>;
+export interface ToolDefinition {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema: JsonSchema;
+    annotations: ToolAnnotations;
+    scopes: Scope[];
+    /**
+     * MCP Apps (RFC-0020 §6): the View a host shows with this tool's results
+     * (`_meta.ui.resourceUri`); `visibility` defaults to the model and the View.
+     */
+    ui?: {
+        readonly resourceUri: string;
+        readonly visibility?: readonly ("model" | "app")[];
+    };
+    requiresApproval?: boolean;
+    /** Human-readable question shown in the approval gate. */
+    approvalPrompt?: (args: Record<string, unknown>, ctx: ToolContext) => Promise<string>;
+    /**
+     * Agent-layer refusals (RFC-0002 §6.4: who may create terms, external redirect targets, approving
+     * one's own proposal). Runs after the scope check and before anyone is asked to approve, so a call
+     * that cannot succeed never waits for a person; a throw is audited as a denial.
+     */
+    precheck?: (args: Record<string, unknown>, ctx: ToolContext) => Promise<void>;
+    /**
+     * The own variants of the tool's scope satisfy it with a limit (RFC-0005 §9): `entry` — the
+     * handler (and `precheck`) check the target with `entryLimitCheck`; `changeset` — `runTool`
+     * checks that a publish is own-only.
+     */
+    own?: "entry" | "changeset" | "comment" | "release";
+    /**
+     * Per-argument policy (RFC-0007 §10.2): `read`, `advisory`, `reduce` or `person`. `person`
+     * calls wait for a person in every mode, `bypass` included.
+     */
+    classify?: (args: Record<string, unknown>) => CallClass | undefined;
+    /** The scopes a `propose` call needs instead of `scopes` (ADR-0028). */
+    proposeScopes?: Scope[];
+    /**
+     * What the call would change, for a person deciding its approval request (RFC-0014 §5): Studio
+     * lists it with the request. Computed against the current state when the request is listed.
+     */
+    changes?: (args: Record<string, unknown>, ctx: ToolContext) => Promise<ApprovalChanges>;
+    /**
+     * What an approval of this call is bound to, instead of the site graph's `stateHash` (RFC-0007
+     * §10.3): comment tools bind to the `cm1:` hash of the comments and threads they name.
+     */
+    bindState?: (args: Record<string, unknown>, ctx: ToolContext) => Promise<string>;
+    /**
+     * Approving a request for this tool in Studio runs it at once as the approving person
+     * (RFC-0007 §10.3); the agent never redeems it.
+     */
+    carryOutOnApproval?: boolean;
+    /**
+     * RFC-0008 §10.4: the tool files its own approval request (a release bound to its `rl1:` hash,
+     * open until the release's time) instead of the generic gate. When the decision for an agent is
+     * `approval-required` and the server has out-of-band approvals — or `auto` mode offers the
+     * low-risk path — the handler runs with `ctx.pending` set and answers `approval-pending` itself.
+     */
+    handlesApproval?: boolean;
+    /**
+     * The text content of a result (default: the result as JSON). Comment tools write reader text
+     * inside labelled untrusted blocks (RFC-0007 §11.2).
+     */
+    renderText?: (result: unknown) => string;
+    /**
+     * Rich content for a result (RFC-0021 §4: `render_page`'s screenshots): the blocks a client
+     * shows, and the structured result without the bytes. Takes precedence over `renderText`.
+     */
+    renderContent?: (result: unknown) => {
+        content: ToolContent[];
+        structured: Record<string, unknown>;
+    };
+    handler: (args: Record<string, unknown>, ctx: ToolContext) => Promise<unknown>;
+    /**
+     * What the audit log keeps of the arguments (default: all of them, truncated). `upload_asset`
+     * replaces its base64 payload with its size, so file bytes never land in the audit table.
+     */
+    auditArgs?: (args: Record<string, unknown>) => Record<string, unknown>;
+}
+/** A content block of a tool result (the MCP shapes Cloudhal uses). */
+export type ToolContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+/** Media settings of a deployment for the asset tools (RFC-0004 §5.6–§5.7). */
+export interface MediaToolOptions {
+    /**
+     * How `fetch_asset_url` reaches the network: `nodeTransport()` from `@cloudhal/core-ts/media-node`
+     * on Node (resolves, checks and pins every address), `workersTransport()` (the default) on Workers.
+     */
+    fetchTransport?: FetchTransport | undefined;
+    /** Hosts agents may fetch from, for every site (each site may add `cloudhal.media.allowHosts`). */
+    allowHosts?: readonly string[] | undefined;
+    /** This deployment's own hosts (Studio, admin API, workers.dev): never fetched. */
+    blockedHosts?: readonly string[] | undefined;
+    /** Per agent key per day (default 100 assets and 500 MB; audited as a denial when exceeded). */
+    agentDailyAssets?: number | undefined;
+    agentDailyBytes?: number | undefined;
+}
+/** What `render_page` renders with (RFC-0021 §4). */
+export interface RenderDeps {
+    readonly renderer: PageRenderer;
+    /** Defaults to one shared per process: 10 a minute per key, 200 a day per site. */
+    readonly limiter?: RenderLimiter | undefined;
+    /** Per call (default 20 s). */
+    readonly timeoutMs?: number | undefined;
+}
+/**
+ * Watches drafts being built (RFC-0020 §6): Studio's Build view follows a page while agents
+ * change it. Called after a write succeeds, and when a build's operations are refused, so a
+ * person sees the agent correct itself. Awaited through `notifyBuild`, which bounds and swallows
+ * failures: watching never fails or slows a write noticeably.
+ */
+export interface BuildObserver {
+    pageChanged(change: {
+        readonly siteId: string;
+        readonly page: Page;
+        readonly tool: string;
+        readonly actor: Actor;
+        /** The operations applied (after repairs), when the change was a patch. */
+        readonly ops?: readonly unknown[] | undefined;
+        readonly repairs?: readonly string[] | undefined;
+    }): void | Promise<void>;
+    patchRejected(rejection: {
+        readonly siteId: string;
+        readonly pageId: string;
+        readonly tool: string;
+        readonly actor: Actor;
+        readonly issues: readonly unknown[];
+    }): void | Promise<void>;
+}
+/** Tells the Build view, waiting at most 2 s; a failure is logged, never thrown (RFC-0020 §6). */
+export declare function notifyBuild(report: () => void | Promise<void>): Promise<void>;
+export interface ToolContext {
+    store: SiteGraphStore;
+    /** Studio's Build view, when a server runs one (RFC-0020 §6). */
+    build?: BuildObserver | undefined;
+    principal: Principal;
+    /** Out-of-band approvals (HTTP): where `request_elevation` files its request. */
+    approvals?: ApprovalStore | undefined;
+    /** Clock (tests); defaults to the system time. */
+    now?: (() => Date) | undefined;
+    /** Base URL of a running `cloudhal dev` server, when known (preview links). */
+    previewBaseUrl?: string | undefined;
+    /** Shared preview secret: signed links to the deployed site (preferred over `previewBaseUrl`). */
+    previewSecret?: string | undefined;
+    /**
+     * Set by `runTool` for one call: what the call did beyond its arguments (assignment deltas, a
+     * governance operation's id and counts). It lands in the audit row's `input.effect`.
+     */
+    report?: ((effect: Record<string, unknown>) => void) | undefined;
+    /** Who owns what: the person behind an agent (RFC-0005 §4). */
+    ownership?: OwnershipResolver | undefined;
+    /** Set by `runTool`: the own limit this call runs under (absent = full scope). */
+    limit?: OwnLimit | undefined;
+    /** Media settings (fetch transport, host lists, daily limits). */
+    media?: MediaToolOptions | undefined;
+    /** Site analytics (RFC-0006): the analytics tools answer `analytics_disabled` without it. */
+    analytics?: AnalyticsService | undefined;
+    /** Reader comments (RFC-0007): the comment tools answer `comments_disabled` without them. */
+    comments?: CommentsDeps | undefined;
+    /**
+     * Set by `runTool`: a person said yes to this call in their own client (or a decided approval
+     * is being carried out), so a `person`-class call may run.
+     */
+    confirmed?: boolean | undefined;
+    /**
+     * Set when Studio carries out an approved request (RFC-0007 §10.3): `principal` is the approving
+     * person, `requestedBy` the agent that asked.
+     */
+    approval?: {
+        readonly id: string;
+        readonly requestedBy: Actor;
+    } | undefined;
+    /** Schedules (RFC-0008): the schedule tools answer `schedules_disabled` without them. */
+    schedules?: SchedulesDeps | undefined;
+    /** A browser for `render_page` (RFC-0021 §4); without it the tool answers `render_unavailable`. */
+    render?: RenderDeps | undefined;
+    /** Set by the server for an automation key's call: its open run (RFC-0008 §11.2). */
+    run?: RunContext | undefined;
+    /**
+     * Set by `runTool` for a `handlesApproval` tool whose decision waits for a person: the handler
+     * files the request itself (or takes the `auto` low-risk path).
+     */
+    pending?: Extract<Decision, {
+        kind: "approval-required";
+    }> | undefined;
+    /** Set by `runTool`: the policy engine (a run envelope lists the tools the run may call). */
+    policy?: PolicyEngine | undefined;
+    /** Set by `runTool`: the audit log (`get_run` lists a run's rows). */
+    audit?: AuditLog | undefined;
+}
+/**
+ * Without a membership source an agent owns what it wrote itself (local stdio with own-limited
+ * scopes); people are themselves; the system owns nothing.
+ */
+export declare const ACTOR_OWNERSHIP: OwnershipResolver;
+/** The person a call is measured against for "own" (RFC-0005 §4). */
+export declare function callerPerson(ctx: ToolContext): string;
+/** Checks an entry write against the call's own limit (I9); refusals are `denied`. */
+export declare function entryLimitCheck(ctx: ToolContext, op: "create" | "update" | "delete", stored: ContentEntry | undefined, next?: Pick<ContentEntry, "author" | "status"> & {
+    publishedAt?: string | undefined;
+}): Promise<void>;
+/** Stable error codes agents can branch on; the text says what to do next. */
+export type ToolErrorCode = "not_found" | "conflict" | "invalid" | "denied" | "approval_required" | InvariantCode | "unknown_taxonomy" | "unknown_term" | "ambiguous_term" | "invalid_filter" | "analytics_disabled" | "analytics_unavailable" | "comments_disabled" | "schedules_disabled" | "outside_run" | "tainted" | "no_egress_in_runs" | "budget_exceeded" | "run" | "render_unavailable" | "render_limited" | "render_failed";
+/** What an approval request would change (RFC-0014 §5): a body, block by block. */
+export interface ApprovalChanges {
+    kind: "body";
+    /** The article, or the page whose rich-text section `sectionId` it changes. */
+    nodeId: string;
+    sectionId?: string;
+    title: string;
+    diff: BodyDiff;
+}
+export declare class ToolError extends Error {
+    readonly name = "ToolError";
+    readonly code: ToolErrorCode;
+    /** Machine-readable context (suggestions, counts, ids). */
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: ToolErrorCode, message: string, details?: Record<string, unknown>);
+}
+export declare const id: {
+    type: string;
+    pattern: string;
+};
+export declare const SLUG_PATTERN = "^[a-z0-9]+(?:-[a-z0-9]+)*$";
+export declare const str: (desc: string, extra?: JsonSchema) => {
+    type: string;
+    description: string;
+};
+export declare const obj: (properties: JsonSchema, required?: string[], extra?: JsonSchema) => JsonSchema;
+export declare const strip: (schema: unknown) => JsonSchema;
+/** Agent-controlled text in approval prompts is shortened and quoted so it cannot pose as UI. */
+export declare function quote(text: string, max?: number): string;
+export declare function requireSite(ctx: ToolContext, siteId: string): Promise<Site>;
+export declare function autoSnapshot(ctx: ToolContext, siteId: string, tool: string, metadata?: Record<string, string>): Promise<Snapshot>;
+/** Store errors as `ToolError`s with stable codes; anything else is returned unchanged. */
+export declare function toToolError(e: unknown): unknown;
+export declare function mapError(e: unknown): never;