@cloudhal/mcp-server 0.0.0-stage → 0.1.0

package/dist/src/tools.js

@@ -0,0 +1,511 @@
+/**
+ * Cloudhal's semantic tool surface, defined independently of the MCP SDK so the same definitions
+ * serve stdio, HTTP and tests. Each tool carries: JSON Schema input/output, honest annotations,
+ * the scopes the policy engine checks, and a handler over `SiteGraphStore`.
+ *
+ * Mutations snapshot automatically (reason `agentMutation`, label = tool name) so every agent
+ * change is diffable and reversible. `publish` and `rollback` are approval-gated.
+ */
+
+             
+           
+            
+           
+               
+             
+                                 
+import {
+                 
+  checkAutoPublish,
+  describeAutoCheck,
+  describeOwnOnly,
+  effectiveMode,
+} from "@cloudhal/agent-runtime";
+import {
+  afterRunCall,
+  checkRunBudget,
+  checkRunCall,
+  withinDailyWriteCap,
+} from "@cloudhal/schedules";
+import { analyticsTools } from "./analytics-tools.js";
+import { assetTools } from "./asset-tools.js";
+import { bodyTools } from "./body-tools.js";
+import { chromeTools } from "./chrome-tools.js";
+import { commentTools } from "./comment-tools.js";
+import {                                        ToolError, toToolError } from "./common.js";
+import { designTools } from "./design-tools.js";
+import { elevationTools } from "./elevation-tools.js";
+import { entryTools } from "./entry-tools.js";
+import { menuTools } from "./menu-tools.js";
+import { pageRemovalTools, siteAndPageTools } from "./page-tools.js";
+import { previewDoc } from "./preview-doc.js";
+import { ownOnlyPublish, publishTools } from "./publish-tools.js";
+import { renderTools } from "./render-tools.js";
+import { scheduleTools } from "./schedule-tools.js";
+import { RUN_COUNTS,                 } from "./schedules.js";
+import { hoistDefs, relaxImageRefs } from "./schema-transforms.js";
+import { searchTools } from "./search-tools.js";
+import { surfaceTools } from "./surface-tools.js";
+import { taxonomyTools } from "./taxonomy-tools.js";
+import { translationTools } from "./translation-tools.js";
+
+export {
+                       
+                     
+                  
+                        
+  notifyBuild,
+                  
+                   
+                      
+  ToolError,
+                     
+  toToolError,
+} from "./common.js";
+export { previewDoc } from "./preview-doc.js";
+export { ownOnlyPublish } from "./publish-tools.js";
+export { hoistDefs, relaxImageRefs } from "./schema-transforms.js";
+
+/** All tools, in the deterministic order `tools/list` exposes them (agents see this order). */
+export function defineTools()                   {
+  return [
+    ...siteAndPageTools(),
+    ...surfaceTools(),
+    ...pageRemovalTools(),
+    ...entryTools(),
+    ...translationTools(),
+    // RFC-0029 §8: find nodes by words (drafts included), or what readers find.
+    ...searchTools(),
+    ...bodyTools(),
+    // RFC-0021 §2: DESIGN.md
+    ...designTools(),
+    // RFC-0025 §5: the header, footer and brand
+    ...chromeTools(),
+    ...renderTools(previewDoc),
+    // Taxonomy, term and redirect tools (RFC-0002 §6.2), then menu tools (RFC-0003 §6.1) and
+    // media tools (RFC-0004 §6.2), follow the article tools.
+    ...taxonomyTools(),
+    ...menuTools(),
+    ...assetTools(),
+    ...publishTools(),
+    // RFC-0006 §9.3: read-only analytics (`analytics:read`).
+    ...analyticsTools(),
+    // RFC-0007 §11: reader comments (read, advisory labels, reductions; approvals for the rest).
+    ...commentTools(),
+    // RFC-0008 §12: the schedule, releases, gates and automation runs.
+    ...scheduleTools(),
+    ...elevationTools(),
+  ].map((t) => ({
+    ...t,
+    inputSchema: relaxImageRefs(hoistDefs(t.inputSchema)),
+    outputSchema: hoistDefs(t.outputSchema),
+  }));
+}
+
+export function toolPolicies(tools                  )               {
+  return tools.map((t) => ({
+    name: t.name,
+    scopes: t.scopes,
+    annotations: t.annotations,
+    ...(t.requiresApproval ? { requiresApproval: true } : {}),
+    ...(t.own ? { own: t.own } : {}),
+    ...(t.classify ? { classify: t.classify } : {}),
+    ...(t.proposeScopes ? { proposeScopes: t.proposeScopes } : {}),
+  }));
+}
+
+                             
+                     
+                                                                                                       
+                        
+                                                                       
+                        
+                                                                     
+                          
+                   
+ 
+
+/**
+ * Policy → audit → handler. Transports call this; it is the only path a tool runs through.
+ * `confirmed` is set by the transport once the human said yes (MRTR response or confirm token);
+ * `approved` once an out-of-band approval was redeemed — someone who could make the full call
+ * decided it (RFC-0005 §6), so an own limit on a publish no longer applies.
+ */
+export async function runTool(
+  def                ,
+  args                         ,
+  ctx             ,
+  deps   
+                         
+                                 
+                                    
+                                   
+   ,
+)                      {
+  const started = Date.now();
+  let decision = deps.policy.evaluate(ctx.principal, def.name, {
+    confirmed: deps.confirmed ?? false,
+    args,
+  });
+  const siteId = typeof args.siteId === "string" ? args.siteId : undefined;
+  const limit = decision.kind === "deny" ? undefined : decision.limit;
+  ctx = {
+    ...ctx,
+    limit,
+    confirmed: deps.confirmed === true,
+    policy: deps.policy,
+    ...(deps.audit ? { audit: deps.audit } : {}),
+  };
+  // Own-only publish (I10): an Author's (or their agent's) publish that carries someone else's
+  // work, or structure, waits for someone whose role allows it (cause `role`).
+  if (limit?.target === "changeset" && !deps.approved && siteId && decision.kind !== "deny") {
+    const check = await ownOnlyPublish(ctx, siteId).catch(() => undefined);
+    if (!check?.ownOnly) {
+      const why = check ? describeOwnOnly(check) : "the site could not be read";
+      decision = {
+        kind: "approval-required",
+        reason: `your role publishes only your own work, but ${why}`,
+        cause: "role",
+        limit,
+      };
+    }
+  }
+  const audited = def.auditArgs ? def.auditArgs(args) : args;
+  const base = {
+    at: new Date().toISOString(),
+    actor: ctx.principal.actor,
+    siteId,
+    tool: def.name,
+    skill: ctx.principal.skill?.name,
+    input: audited,
+    mode: effectiveMode(ctx.principal),
+    ...(ctx.principal.actor.kind === "agent" && ctx.principal.elevation
+      ? { elevation: ctx.principal.elevation }
+      : {}),
+    // RFC-0008 §5.1: a run's rows carry the run and its automation; release tools the release.
+    ...(ctx.run ? { runId: ctx.run.run.id, automationId: ctx.run.automation.id } : {}),
+    ...(typeof args.releaseId === "string" ? { releaseId: args.releaseId } : {}),
+  };
+  // Inside an automation run (RFC-0008 §11.4–§11.5): the run's site, the taint rule, the budget.
+  const run = ctx.run;
+  const cls = runCallClass(def, args);
+  if (run) {
+    const refusal = await runRefusal(def, args, ctx, run, cls, decision);
+    if (refusal) {
+      await deps.audit?.record({
+        ...base,
+        decision: "deny",
+        reason: refusal.message,
+        outcome: "error",
+      });
+      await noteRunCall(ctx, run, def.name, cls, "refused");
+      throw refusal;
+    }
+  }
+  if (decision.kind === "deny") {
+    if (run) await noteRunCall(ctx, run, def.name, cls, "refused");
+    await deps.audit?.record({
+      ...base,
+      decision: "deny",
+      reason: decision.reason,
+      outcome: "error",
+    });
+    return { decision };
+  }
+  if (def.precheck) {
+    try {
+      await def.precheck(args, ctx);
+    } catch (raw) {
+      const e = toToolError(raw);
+      await deps.audit?.record({
+        ...base,
+        decision: "deny",
+        reason: e instanceof Error ? e.message : String(e),
+        outcome: "error",
+      });
+      throw e;
+    }
+  }
+  // `auto` mode: a publish that only adds or edits a few articles goes live without a person.
+  let autoCheck                       ;
+  let autoNote                    ;
+  if (
+    decision.kind === "approval-required" &&
+    decision.autoApprove === "low-risk-publish" &&
+    siteId
+  ) {
+    const pending = await ctx.store.pendingChanges(siteId);
+    // New raster images used only by the articles in this publish ride along (RFC-0004 §6.3).
+    autoCheck = checkAutoPublish(pending, {
+      ridingAssets: await ctx.store.ridingAssets(siteId, pending),
+      corrections: await ctx.store.correctingEntries(siteId, pending),
+    });
+    if (autoCheck.lowRisk)
+      autoNote = `auto mode: published without approval (${describeAutoCheck(autoCheck)})`;
+    else
+      decision = {
+        ...decision,
+        reason: `auto mode waits for a person: ${describeAutoCheck(autoCheck)}`,
+      };
+  }
+  const checked = autoCheck ? { autoCheck } : {};
+  // RFC-0008 §10.4: release tools file their own request bound to `rl1:` (or take `auto`'s
+  // low-risk path), so their handler runs with the waiting decision instead of the generic gate.
+  if (
+    decision.kind === "approval-required" &&
+    def.handlesApproval &&
+    !deps.confirmed &&
+    decision.cause !== "role" &&
+    ((ctx.approvals && ctx.principal.actor.kind === "agent") ||
+      decision.autoApprove === "low-risk-release")
+  ) {
+    const pending = decision;
+    let effect                                     ;
+    const callCtx              = {
+      ...ctx,
+      pending,
+      report: (e) => {
+        effect = { ...effect, ...e };
+      },
+    };
+    try {
+      const result = await def.handler(args, callCtx);
+      const waits = (result                                   )?.status === "approval-pending";
+      const releaseId =
+        (result                                             )?.release?.id ??
+        (typeof effect?.releaseId === "string" ? effect.releaseId : undefined);
+      await deps.audit?.record({
+        ...base,
+        ...(effect ? { input: { ...audited, effect } } : {}),
+        ...(releaseId ? { releaseId } : {}),
+        decision: waits ? "approval-required" : "allow",
+        reason: waits
+          ? pending.reason
+          : `auto mode: scheduled without a person (${describeAutoCheck((effect?.autoCheck                         ) ?? { rule: "low-risk-release", lowRisk: true, code: "low-risk", changes: 0, limit: 20 })})`,
+        ...(waits ? { cause: pending.cause } : {}),
+        outcome: waits ? "pending" : "ok",
+        durationMs: Date.now() - started,
+      });
+      if (run) await noteRunCall(ctx, run, def.name, cls, "allowed");
+      return { decision: { kind: "allow" }, result };
+    } catch (raw) {
+      const e = toToolError(raw);
+      await deps.audit?.record({
+        ...base,
+        decision: "allow",
+        outcome: "error",
+        reason: e instanceof Error ? e.message : String(e),
+        durationMs: Date.now() - started,
+      });
+      if (run)
+        await noteRunCall(
+          ctx,
+          run,
+          def.name,
+          cls,
+          e instanceof ToolError && e.code === "denied" ? "refused" : "allowed",
+        );
+      throw e;
+    }
+  }
+  if (decision.kind === "approval-required" && !autoNote) {
+    const approvalPrompt = def.approvalPrompt
+      ? await def.approvalPrompt(args, ctx)
+      : decision.reason;
+    await deps.audit?.record({
+      ...base,
+      decision: "approval-required",
+      reason: decision.reason,
+      cause: decision.cause,
+      ...checked,
+      outcome: "pending",
+    });
+    if (run) await noteRunCall(ctx, run, def.name, cls, "allowed");
+    return { decision, approvalPrompt, ...checked };
+  }
+  // What the call did beyond its arguments (assignment deltas, a governance operation) goes into
+  // the audit row's `input.effect` (RFC-0002 §6.4).
+  let effect                                     ;
+  const callCtx              = {
+    ...ctx,
+    report: (e) => {
+      effect = { ...effect, ...e };
+    },
+  };
+  try {
+    const result = await def.handler(args, callCtx);
+    const snapshotId = (result                                              )?.snapshot?.id;
+    const releaseId =
+      (result                                             )?.release?.id ??
+      (typeof (effect                                       )?.releaseId === "string"
+        ? (effect                         ).releaseId
+        : undefined);
+    await deps.audit?.record({
+      ...base,
+      ...(effect ? { input: { ...audited, effect } } : {}),
+      ...(releaseId ? { releaseId } : {}),
+      decision: "allow",
+      outcome: "ok",
+      snapshotId,
+      durationMs: Date.now() - started,
+      ...(autoNote ? { reason: autoNote } : {}),
+      ...checked,
+    });
+    if (run) await noteRunCall(ctx, run, def.name, cls, "allowed");
+    return {
+      decision: { kind: "allow" },
+      result,
+      ...(autoNote ? { autoApproved: autoNote } : {}),
+      ...checked,
+    };
+  } catch (raw) {
+    const e = toToolError(raw);
+    await deps.audit?.record({
+      ...base,
+      decision: "allow",
+      outcome: "error",
+      reason: e instanceof Error ? e.message : String(e),
+      durationMs: Date.now() - started,
+    });
+    if (run)
+      await noteRunCall(
+        ctx,
+        run,
+        def.name,
+        cls,
+        e instanceof ToolError && e.code === "denied" ? "refused" : "allowed",
+      );
+    throw e;
+  }
+}
+
+/** Bookkeeping tools a run may always call: they never count against its budget. */
+const RUN_BOOKKEEPING = new Set(["end_run", "get_mode", "pause_automation", "begin_run"]);
+
+/** A call's class inside a run (§11.4): its own `classify`, else read-only or not. */
+function runCallClass(def                , args                         )               {
+  const cls = def.classify?.(args);
+  // A proposal is a note a person reads before deciding, like a label (RFC-0014 phase 4).
+  if (cls === "propose") return "advisory";
+  if (cls) return cls;
+  return def.annotations.readOnlyHint === true ? "read" : "advisory";
+}
+
+/** The classes runs account for (RFC-0008 §11.4): `propose` counts as `advisory`. */
+                                                  
+
+/**
+ * Why a run may not make this call (RFC-0008 §10.7, §11.4, §11.5), or undefined: another site,
+ * `request_elevation` (code `run`), no egress, the taint rule, the run's budget (which ends the run
+ * and pauses its automation) and the site's daily cap on automation writes.
+ */
+async function runRefusal(
+  def                ,
+  args                         ,
+  ctx             ,
+  run            ,
+  cls              ,
+  decision          ,
+)                                 {
+  const siteId = run.automation.siteId;
+  if (typeof args.siteId === "string" && args.siteId !== siteId)
+    return new ToolError("outside_run", `this run works on site ${siteId} only`);
+  if (def.name === "request_elevation")
+    return new ToolError(
+      "run",
+      "a run's autonomy is fixed by its automation (modeCap); request_elevation is not available inside runs",
+    );
+  const taint = checkRunCall(run.state, { tool: def.name, class: cls });
+  if (!taint.allowed) return new ToolError(taint.code, taint.message);
+  if (RUN_BOOKKEEPING.has(def.name) || !ctx.schedules) return undefined;
+  const store = ctx.schedules.store;
+  const now = (ctx.now?.() ?? new Date()).toISOString();
+  const writes = decision.kind === "allow" && def.annotations.readOnlyHint !== true;
+  const usage = await store.runUsage(siteId, run.run.id);
+  const budget = checkRunBudget(
+    run.automation.job.budget,
+    usage,
+    { startedAt: run.run.startedAt ?? now, now },
+    { write: writes, approvalRequest: decision.kind === "approval-required" },
+  );
+  if (!budget.ok) {
+    await store.endAgentRunAs(siteId, run.run.id, {
+      now,
+      state: "budget-exceeded",
+      error: { code: "budget_exceeded", message: budget.exceeded },
+      usage,
+    });
+    const a = await store.getAutomation(siteId, run.automation.id);
+    if (a?.state === "active")
+      await store
+        .transitionAutomation(siteId, a.id, {
+          expectedRev: a.rev,
+          to: "auto-paused",
+          pausedReason: "budget",
+        })
+        .catch(() => undefined);
+    return new ToolError(
+      "budget_exceeded",
+      `the run's ${budget.exceeded} budget is used up: the run ended and the automation is paused until a person resumes it`,
+    );
+  }
+  if (writes) {
+    const settings = await store.settings(siteId);
+    if (
+      !withinDailyWriteCap(await store.automationWritesToday(siteId, now), settings.dailyWriteCap)
+    )
+      return new ToolError(
+        "budget_exceeded",
+        `daily_write_cap: automations on this site made ${settings.dailyWriteCap} changes today (UTC); try tomorrow or ask a person to raise the cap`,
+      );
+  }
+  return undefined;
+}
+
+/**
+ * Records a call on its run (§11.4): the taint from the first tainting tool on, the anomaly counters
+ * and the usage. More than 50 reductions or 10 refusals in a row end the run (`killed`) and pause
+ * the automation.
+ */
+async function noteRunCall(
+  ctx             ,
+  run            ,
+  tool        ,
+  cls              ,
+  result                       ,
+)                {
+  const store = ctx.schedules?.store;
+  if (!store) return;
+  const siteId = run.automation.siteId;
+  const now = (ctx.now?.() ?? new Date()).toISOString();
+  const next = afterRunCall(run.state, { tool, class: cls }, result, now);
+  run.state = next.state;
+  const counts = {
+    ...(run.run.counts ?? {}),
+    [RUN_COUNTS.reduce]: next.state.reduceCalls,
+    [RUN_COUNTS.refusals]: next.state.consecutiveRefusals,
+  };
+  const usage = await store.runUsage(siteId, run.run.id);
+  await store.recordRunCall(siteId, run.run.id, {
+    now,
+    ...(next.state.taint ? { taint: next.state.taint } : {}),
+    counts,
+    usage,
+  });
+  if (!next.kill) return;
+  await store.endAgentRunAs(siteId, run.run.id, {
+    now,
+    state: "killed",
+    error: { code: next.kill },
+    usage,
+  });
+  const a = await store.getAutomation(siteId, run.automation.id);
+  if (a?.state === "active")
+    await store
+      .transitionAutomation(siteId, a.id, {
+        expectedRev: a.rev,
+        to: "auto-paused",
+        pausedReason: "failures",
+      })
+      .catch(() => undefined);
+}

package/dist/src/translation-tools.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDefinition } from "./common.js";
+/** list_translations, list_stale_translations, get_translation_source, save_translation. */
+export declare function translationTools(): ToolDefinition[];