@openshain/mcp 0.2.0 → 0.4.0

package/src/server.ts

@@ -1,3 +1,4 @@
+import { relative } from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
   CallToolRequestSchema,
@@ -8,15 +9,27 @@ import {
 import {
   type AnyEvent,
   type Artifact,
+  ASK_USER,
   compileInputValidator,
+  countToolCalls,
   createToolCaller,
   createToolRegistry,
+  DecisionFileSchema,
+  type DecisionRecord,
   type Event,
+  type EventType,
   type InputValidation,
+  isKnownEventType,
   isOpenshainError,
   isTerminal,
+  loadAuthority,
   loadConfig,
+  type PendingApproval,
+  parsePayloadFile,
   parseWorkId,
+  pendingApprovals,
+  pendingQuestions,
+  RUNTIME_PROVIDER_ID,
   type RuntimeProviders,
   resolveWorkspacePath,
   SESSION_WORK_TYPE,
@@ -27,6 +40,8 @@ import {
   type Work,
   type WorkId,
   WorkStore,
+  workHistory,
+  writeDecision,
 } from "@openshain/core";
 import pkg from "../package.json" with { type: "json" };
 import { Session } from "./session.ts";
@@ -42,15 +57,32 @@ const WORK_TOOLS: Tool[] = [
   {
     name: "work_create",
     description:
-      "Start a work for a request from the person you work for, and make it the current work. Tool calls are recorded against the current work. Finish the current work with work_complete or work_fail before starting another.",
+      'Start a work for a request from the person you work for, and make it the current work. Tool calls are recorded against the current work. Finish the current work with work_complete or work_fail before starting another. The type "session" records a conversation: no tool can run inside it, so start the actual work with parent set to the session\'s id.',
     inputSchema: {
       type: "object",
       properties: {
-        objective: { type: "string", description: "The request, in the person's words." },
+        objective: {
+          type: "string",
+          minLength: 1,
+          maxLength: 10_000,
+          description: "The request, in the person's words.",
+        },
         type: {
           type: "string",
+          maxLength: 50,
           description: "A short label for the kind of work. Defaults to request.",
         },
+        parent: {
+          type: "string",
+          maxLength: 100,
+          description: "The id of the work this one was started from, such as the session.",
+        },
+        agent_name: {
+          type: "string",
+          maxLength: 100,
+          description:
+            "The name the agent goes by in this work. A session picks one; the works under it carry the same.",
+        },
       },
       required: ["objective"],
       additionalProperties: false,
@@ -68,10 +100,11 @@ const WORK_TOOLS: Tool[] = [
   },
   {
     name: "work_get",
-    description: "The state of the current work, or of the work with the given id.",
+    description:
+      "The state of the current work, or of the work with the given id. With history, also the tool calls so far, the calls that never got a result, and the questions still waiting for an answer, so a stopped work can be picked up.",
     inputSchema: {
       type: "object",
-      properties: { id: { type: "string" } },
+      properties: { id: { type: "string" }, history: { type: "boolean" } },
       additionalProperties: false,
     },
   },
@@ -87,12 +120,15 @@ const WORK_TOOLS: Tool[] = [
     inputSchema: {
       type: "object",
       properties: {
-        summary: { type: "string" },
+        summary: { type: "string", maxLength: 20_000 },
         artifacts: {
           type: "array",
           items: {
             type: "object",
-            properties: { path: { type: "string" }, sha256: { type: "string" } },
+            properties: {
+              path: { type: "string", maxLength: 1000 },
+              sha256: { type: "string", maxLength: 64 },
+            },
             required: ["path"],
             additionalProperties: false,
           },
@@ -107,13 +143,141 @@ const WORK_TOOLS: Tool[] = [
     description: "Give up on the current work. Say why in a short reason and, if useful, a detail.",
     inputSchema: {
       type: "object",
-      properties: { reason: { type: "string" }, detail: { type: "string" } },
+      properties: {
+        reason: { type: "string", maxLength: 200 },
+        detail: { type: "string", maxLength: 20_000 },
+      },
       required: ["reason"],
       additionalProperties: false,
     },
   },
+  {
+    name: ASK_USER.name,
+    description: ASK_USER.description,
+    inputSchema: ASK_USER.inputSchema as Tool["inputSchema"],
+  },
+  {
+    name: "work_answer",
+    description:
+      "Record the person's answer to a question the current work is waiting on, and let the work continue.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        call_id: { type: "string", maxLength: 100 },
+        answer: { type: "string", maxLength: 20_000 },
+      },
+      required: ["call_id", "answer"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "context",
+    description:
+      "Where and when you are working: the current time with its offset, the time zone, today's business date, the company folder, the company, the person you work for, and the current work. Call it when a date or a time matters; the answer is recorded.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "approval_list",
+    description:
+      "Every tool call held for a person's approval across the works of this workspace, oldest first: approval_id, work_id, the call, the rule, and who may approve.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "approval_decide",
+    description:
+      "Decide a held tool call as the person this connection acts for. approve runs the call now and returns its result; reject refuses it. Either way the work continues.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        approval_id: { type: "string", maxLength: 100 },
+        decision: { type: "string", enum: ["approve", "reject"] },
+        comment: { type: "string", maxLength: 2000 },
+      },
+      required: ["approval_id", "decision"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "review_decide",
+    description:
+      "Record what a qualified reviewer decided about a call the policy held for review. approve and modify write a decision under authority/decisions/ and run the call (modify runs the reviewer's input); reject refuses it. The reviewer is named by the company; openshain does not verify a qualification.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        approval_id: { type: "string", maxLength: 100 },
+        decision: { type: "string", enum: ["approve", "reject", "modify"] },
+        reviewer: {
+          type: "object",
+          properties: {
+            name: { type: "string", maxLength: 200 },
+            role: { type: "string", maxLength: 100 },
+            qualification: { type: "string", maxLength: 500 },
+          },
+          required: ["name", "role"],
+          additionalProperties: false,
+        },
+        interpretation: { type: "string", maxLength: 20_000 },
+        modified_input: { type: "object" },
+        effective_from: { type: "string", maxLength: 10 },
+        effective_until: { type: "string", maxLength: 10 },
+        applies_to: {
+          type: "object",
+          properties: {
+            action: { type: "string", maxLength: 200 },
+            path: { type: "string", maxLength: 1000 },
+          },
+          additionalProperties: false,
+        },
+      },
+      required: ["approval_id", "decision", "reviewer"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "work_record",
+    description:
+      "Record an event of the client itself on a work: what the person said (human.message), a prompt command expanded for the model (prompt.expanded), a model call (model.requested, model.completed, model.failed) or its usage (usage.recorded with kind model_inference). The payload is in the file form of spec/schemas/events.v1.json. Tool calls are recorded by the runtime and cannot be recorded here.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        work_id: { type: "string" },
+        type: {
+          type: "string",
+          enum: [
+            "human.message",
+            "prompt.expanded",
+            "model.requested",
+            "model.completed",
+            "model.failed",
+            "usage.recorded",
+          ],
+        },
+        payload: { type: "object" },
+      },
+      required: ["work_id", "type", "payload"],
+      additionalProperties: false,
+    },
+  },
 ];
 
+/** A client event larger than this is refused: the log is for records, not for payloads. */
+const MAX_RECORD_CHARS = 262_144;
+
+/** The event types a client may record itself. Everything else is the runtime's to write. */
+const RECORDABLE_TYPES: ReadonlySet<string> = new Set([
+  "human.message",
+  "prompt.expanded",
+  "model.requested",
+  "model.completed",
+  "model.failed",
+  "usage.recorded",
+]);
+
+const SESSION_HAS_NO_TOOLS =
+  "a session records the conversation and runs no tools: call work_create with parent set to the session's id, then call the tool inside that work";
+
 const NO_WORK =
   "no current work: call work_create to start one for the person's request, or work_select to pick an existing one";
 
@@ -130,7 +294,14 @@ export async function createMcpServer(options: McpServerOptions): Promise<Server
   const { workspaceRoot } = options;
   const config = await loadConfig(workspaceRoot);
   const registry = await createToolRegistry(workspaceRoot, config, options.tools);
-  const callTool = createToolCaller({ registry, config, workspaceRoot });
+  // Reloaded when a reviewer writes a decision, so the next call can cite it.
+  let authority = await loadAuthority(workspaceRoot);
+  const callTool = createToolCaller({
+    registry,
+    config,
+    workspaceRoot,
+    authority: () => authority,
+  });
   const works = new WorkStore(workspaceRoot);
   const session = new Session();
   const server = new Server(
@@ -163,22 +334,32 @@ export async function createMcpServer(options: McpServerOptions): Promise<Server
     switch (name) {
       case "work_create": {
         const current = session.current;
-        if (current && !isTerminal((await works.get(current)).status)) {
-          return failure(
-            `work ${current} is still in progress; finish it with work_complete or work_fail before starting another`,
-          );
+        if (current) {
+          const open = await works.get(current);
+          // A session is a conversation: starting a work under it is the normal thing to do.
+          if (!isTerminal(open.status) && open.type !== SESSION_WORK_TYPE) {
+            return failure(
+              `work ${current} is still in progress; finish it with work_complete or work_fail before starting another`,
+            );
+          }
         }
-        const { objective, type } = input as { objective: string; type?: string };
-        if (type === SESSION_WORK_TYPE) {
-          return failure(
-            `type "${SESSION_WORK_TYPE}" is reserved for conversations; use another label, such as request`,
-          );
+        const {
+          objective,
+          type,
+          parent,
+          agent_name: agentName,
+        } = input as { objective: string; type?: string; parent?: string; agent_name?: string };
+        if (parent !== undefined) await works.get(parseWorkId(parent));
+        if (type === SESSION_WORK_TYPE && parent !== undefined) {
+          return failure("a session is a conversation of its own and cannot have a parent");
         }
         const work = await works.create({
           objective,
           principal: config.principal.id,
           profession: config.profession.id,
           ...(type && { type }),
+          ...(parent !== undefined && { parent }),
+          ...(agentName !== undefined && { agentName }),
         });
         await works.transition(work.id, "in_progress", "an agent took the work over MCP");
         session.select(work.id);
@@ -189,13 +370,330 @@ export async function createMcpServer(options: McpServerOptions): Promise<Server
         const work = await works.get(id);
         if (isTerminal(work.status)) return failure(`work ${id} is already ${work.status}`);
         session.select(id);
-        return json(work);
+        return json({ ...work, history: workHistory(await works.events(id)) });
       }
       case "work_get": {
-        const given = (input as { id?: string }).id;
+        const { id: given, history } = input as { id?: string; history?: boolean };
         const id = given ? parseWorkId(given) : session.current;
         if (!id) return failure(NO_WORK);
-        return json(await works.get(id));
+        const work = await works.get(id);
+        if (!history) return json(work);
+        return json({ ...work, history: workHistory(await works.events(id)) });
+      }
+      case ASK_USER.name: {
+        const gate = await openWork();
+        if ("refused" in gate) return gate.refused;
+        const work = await works.get(gate.id);
+        if (work.type === SESSION_WORK_TYPE) return failure(SESSION_HAS_NO_TOOLS);
+        if (work.status === "waiting_input") {
+          return failure(
+            `work ${gate.id} is already waiting for an answer; record it with work_answer before asking again`,
+          );
+        }
+        const { question } = input as { question: string };
+        const callId = newCallId();
+        const opened = await works.open(gate.id);
+        try {
+          await opened.append({
+            type: "tool.called",
+            payload: { callId, provider: RUNTIME_PROVIDER_ID, name: ASK_USER.name, input },
+          });
+          await opened.append({ type: "human.input_requested", payload: { callId, question } });
+          await opened.transition("waiting_input", "the agent asked the person a question");
+        } finally {
+          await opened.close();
+        }
+        return json({ pending: true, call_id: callId, question });
+      }
+      case "work_answer": {
+        const gate = await openWork();
+        if ("refused" in gate) return gate.refused;
+        const { call_id: callId, answer } = input as { call_id: string; answer: string };
+        const work = await works.get(gate.id);
+        if (work.status !== "waiting_input") {
+          return failure(`work ${gate.id} is ${work.status}, not waiting for an answer`);
+        }
+        const pending = pendingQuestions(await works.events(gate.id));
+        if (!pending.some((q) => q.callId === callId)) {
+          return failure(
+            `no unanswered question with call_id ${callId}; pending: ${pending.map((q) => q.callId).join(", ") || "none"}`,
+          );
+        }
+        const opened = await works.open(gate.id);
+        try {
+          await opened.append({ type: "human.input_provided", payload: { callId, answer } });
+          await opened.append({
+            type: "tool.completed",
+            payload: { callId, content: [{ type: "text", text: answer }], isError: false },
+          });
+          await opened.transition("in_progress", "the person answered");
+          return json(await opened.current());
+        } finally {
+          await opened.close();
+        }
+      }
+      case "work_record": {
+        const { work_id, type, payload } = input as {
+          work_id: string;
+          type: string;
+          payload: unknown;
+        };
+        const id = parseWorkId(work_id);
+        if (!RECORDABLE_TYPES.has(type) || !isKnownEventType(type)) {
+          return failure(`type ${type} cannot be recorded by a client`);
+        }
+        if (JSON.stringify(payload).length > MAX_RECORD_CHARS) {
+          return failure(`payload is larger than ${MAX_RECORD_CHARS} characters`);
+        }
+        if (!session.knows(id)) {
+          return failure(
+            `work ${id} was not created or selected on this connection; a client records only on its own works`,
+          );
+        }
+        const parsed = parsePayloadFile(type as EventType, payload);
+        if (type === "usage.recorded" && (parsed as { kind: string }).kind !== "model_inference") {
+          return failure("usage.recorded from a client must have kind model_inference");
+        }
+        const opened = await works.open(id);
+        try {
+          const status = (await opened.current()).status;
+          if (isTerminal(status)) return failure(`work ${id} is already ${status}`);
+          const event = await opened.append({ type, payload: parsed } as never);
+          return json({ id: event.id, seq: event.seq });
+        } finally {
+          await opened.close();
+        }
+      }
+      case "context": {
+        const now = new Date();
+        const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        const info = {
+          now: localIso(now),
+          timezone,
+          business_date: localIso(now).slice(0, 10),
+          workspace: workspaceRoot,
+          company: config.company.name,
+          principal: { id: config.principal.id, name: config.principal.name },
+          profession: config.profession.id,
+          work: session.current ?? null,
+        };
+        const result = json(info);
+        // Recorded on the current work when there is one, even a session: it touches no file.
+        const current = session.current;
+        if (current && !isTerminal((await works.get(current)).status)) {
+          const callId = newCallId();
+          const opened = await works.open(current);
+          try {
+            await opened.append({
+              type: "tool.called",
+              payload: { callId, provider: RUNTIME_PROVIDER_ID, name: "context", input: {} },
+            });
+            await opened.append({
+              type: "tool.completed",
+              payload: { callId, content: [{ type: "json", value: info }], isError: false },
+            });
+          } finally {
+            await opened.close();
+          }
+        }
+        return result;
+      }
+      case "approval_list": {
+        const held: unknown[] = [];
+        const { works: all } = await works.list();
+        for (const w of all) {
+          if (w.status !== "waiting_approval") continue;
+          for (const a of pendingApprovals(await works.events(w.id))) {
+            held.push({ ...a, work_id: w.id, objective: w.objective });
+          }
+        }
+        return json({ approvals: held });
+      }
+      case "approval_decide": {
+        const {
+          approval_id: approvalId,
+          decision,
+          comment,
+        } = input as { approval_id: string; decision: "approve" | "reject"; comment?: string };
+        const found = await findApproval(works, approvalId);
+        if (!found) return failure(`no pending approval ${approvalId}`);
+        const { workId, approval } = found;
+        const by = config.principal.id;
+        if (approval.kind === "review") {
+          return failure(
+            `${approvalId} waits for a qualified reviewer, not a person's approval; use review_decide`,
+          );
+        }
+        if (approval.approvers && !approval.approvers.includes(by)) {
+          return failure(
+            `${by} may not decide ${approvalId}; approvers: ${approval.approvers.join(", ")}`,
+          );
+        }
+        const opened = await works.open(workId);
+        try {
+          // Under the lock: another connection may have decided this approval in between.
+          if (!pendingApprovals(await opened.events()).some((a) => a.approvalId === approvalId)) {
+            return failure(`approval ${approvalId} was already decided`);
+          }
+          await opened.append({
+            type: "approval.decided",
+            payload: { approvalId, decision, by, ...(comment !== undefined && { comment }) },
+          });
+          if (decision === "reject") {
+            await opened.append({
+              type: "tool.rejected",
+              payload: {
+                callId: approval.call.callId,
+                name: approval.call.name,
+                code: "rejected_by_person",
+                reason: comment ?? `${by} rejected ${approvalId}`,
+              },
+            });
+            await opened.transition("in_progress", `${by} rejected ${approvalId}`);
+            return json({ approval_id: approvalId, decision, work_id: workId });
+          }
+          await opened.transition("in_progress", `${by} approved ${approvalId}`);
+          const result = await callTool(
+            opened,
+            { id: approval.call.callId, name: approval.call.name, input: approval.call.input },
+            { approvedBy: approvalId },
+          );
+          return json({
+            approval_id: approvalId,
+            decision,
+            work_id: workId,
+            result: { content: result.content, isError: result.isError ?? false },
+          });
+        } finally {
+          await opened.close();
+        }
+      }
+      case "review_decide": {
+        const {
+          approval_id: approvalId,
+          decision,
+          reviewer,
+          interpretation,
+          modified_input: modifiedInput,
+          effective_from: effectiveFrom,
+          effective_until: effectiveUntil,
+          applies_to: appliesTo,
+        } = input as {
+          approval_id: string;
+          decision: "approve" | "reject" | "modify";
+          reviewer: { name: string; role: string; qualification?: string };
+          interpretation?: string;
+          modified_input?: Record<string, unknown>;
+          effective_from?: string;
+          effective_until?: string;
+          applies_to?: { action?: string; path?: string };
+        };
+        const found = await findApproval(works, approvalId);
+        if (!found) return failure(`no pending approval ${approvalId}`);
+        const { workId, approval } = found;
+        if (approval.kind !== "review") {
+          return failure(
+            `${approvalId} waits for a person's approval, not a review; use approval_decide`,
+          );
+        }
+        if (decision !== "reject" && (interpretation ?? "") === "") {
+          return failure("a decision needs the reviewer's interpretation in their own words");
+        }
+        if (approval.reviewer && approval.reviewer.role !== reviewer.role) {
+          return failure(
+            `rule ${approval.ruleId} asks for a ${approval.reviewer.role}; the decision names a ${reviewer.role}`,
+          );
+        }
+        if (decision === "modify" && modifiedInput) {
+          // Checked before anything is recorded: a refused input leaves the approval pending.
+          const before = (approval.call.input ?? {}) as { path?: unknown };
+          const after = modifiedInput as { path?: unknown };
+          if (before.path !== after.path) {
+            return failure(
+              `a modified call must touch the same path: ${String(before.path)} was held, ${String(after.path)} was given`,
+            );
+          }
+        }
+        // Built and checked before anything is recorded: an input the decision refuses must not
+        // consume the approval and leave the work waiting with nobody able to move it.
+        const today = new Date();
+        let record: DecisionRecord | undefined;
+        if (decision !== "reject") {
+          const parsed = DecisionFileSchema.safeParse({
+            id: `dec_${uuidv7()}`,
+            reviewer,
+            approval_id: approvalId,
+            decided_at: today.toISOString(),
+            effective_from: effectiveFrom ?? today.toISOString().slice(0, 10),
+            effective_until: effectiveUntil ?? null,
+            interpretation,
+            applies_to: appliesTo ?? {},
+          });
+          if (!parsed.success) {
+            return failure(
+              `the decision is not well formed: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`,
+            );
+          }
+          record = parsed.data;
+        }
+        const opened = await works.open(workId);
+        try {
+          // Under the lock: another connection may have decided this approval in between.
+          if (!pendingApprovals(await opened.events()).some((a) => a.approvalId === approvalId)) {
+            return failure(`approval ${approvalId} was already decided`);
+          }
+          await opened.append({
+            type: "approval.decided",
+            payload: {
+              approvalId,
+              decision,
+              by: reviewer.name,
+              ...(interpretation !== undefined && { comment: interpretation }),
+              ...(decision === "modify" && modifiedInput && { modifiedInput }),
+            },
+          });
+          if (decision === "reject") {
+            await opened.append({ type: "review.decided", payload: { approvalId } });
+            await opened.append({
+              type: "tool.rejected",
+              payload: {
+                callId: approval.call.callId,
+                name: approval.call.name,
+                code: "rejected_by_person",
+                reason: interpretation ?? `${reviewer.name} did not approve ${approvalId}`,
+              },
+            });
+            await opened.transition("in_progress", `${reviewer.name} rejected ${approvalId}`);
+            return json({ approval_id: approvalId, decision, work_id: workId });
+          }
+          const written = record as DecisionRecord;
+          const file = await writeDecision(workspaceRoot, written);
+          await opened.append({
+            type: "review.decided",
+            payload: { approvalId, decisionId: written.id },
+          });
+          await opened.transition("in_progress", `${reviewer.name} decided ${approvalId}`);
+          const ranWith =
+            decision === "modify" && modifiedInput ? modifiedInput : approval.call.input;
+          const ran = await callTool(
+            opened,
+            { id: approval.call.callId, name: approval.call.name, input: ranWith },
+            { approvedBy: approvalId },
+          );
+          // The decision is on disk; a rule that cites its id can use it from here on. Reloaded
+          // so that a rule already written for it takes effect without a restart.
+          authority = await loadAuthority(workspaceRoot);
+          return json({
+            approval_id: approvalId,
+            decision,
+            work_id: workId,
+            decision_id: written.id,
+            decision_file: relative(workspaceRoot, file),
+            result: { content: ran.content, isError: ran.isError ?? false },
+          });
+        } finally {
+          await opened.close();
+        }
       }
       case "work_list": {
         const { works: all, problems } = await works.list();
@@ -203,8 +701,11 @@ export async function createMcpServer(options: McpServerOptions): Promise<Server
           works: all.map((w) => ({
             id: w.id,
             status: w.status,
+            type: w.type,
             objective: w.objective,
             createdAt: w.createdAt,
+            ...(w.parent !== undefined && { parent: w.parent }),
+            ...(w.agentName !== undefined && { agentName: w.agentName }),
           })),
           problems: problems.map((p) => ({
             id: p.id,
@@ -240,8 +741,29 @@ export async function createMcpServer(options: McpServerOptions): Promise<Server
       default: {
         const gate = await openWork();
         if ("refused" in gate) return gate.refused;
+        const work = await works.get(gate.id);
+        if (work.type === SESSION_WORK_TYPE) return failure(SESSION_HAS_NO_TOOLS);
+        if (work.status === "waiting_input") {
+          return failure(
+            `work ${gate.id} is waiting for the person's answer; record it with work_answer before calling tools`,
+          );
+        }
+        if (work.status === "waiting_approval") {
+          return failure(
+            `work ${gate.id} is waiting for an approval; decide it with approval_decide (see approval_list) before calling tools`,
+          );
+        }
         const opened = await works.open(gate.id);
         try {
+          const limit = config.limits.maxToolCalls;
+          if (countToolCalls(await opened.events()) >= limit) {
+            const reason = `this work has reached its limit of ${limit} tool calls; finish it with work_complete or work_fail`;
+            await opened.append({
+              type: "tool.rejected",
+              payload: { callId: newCallId(), name, code: "limit_reached", reason },
+            });
+            return failure(`limit_reached: ${reason}`);
+          }
           const result = await callTool(opened, { id: newCallId(), name, input });
           return toMcpResult(result);
         } finally {
@@ -323,6 +845,7 @@ function toMcpTool(definition: ToolDefinition): Tool {
     name: definition.name,
     description: definition.description,
     inputSchema: definition.inputSchema as Tool["inputSchema"],
+    annotations: { readOnlyHint: definition.effect === "observe" },
   };
 }
 
@@ -348,3 +871,32 @@ function failure(text: string): CallToolResult {
 function newCallId(): string {
   return `call_${uuidv7()}`;
 }
+
+/** The work holding a pending approval, found by scanning the works that wait for one. */
+async function findApproval(
+  works: WorkStore,
+  approvalId: string,
+): Promise<{ workId: WorkId; approval: PendingApproval } | undefined> {
+  const { works: all } = await works.list();
+  for (const w of all) {
+    if (w.status !== "waiting_approval") continue;
+    const approval = pendingApprovals(await works.events(w.id)).find(
+      (a) => a.approvalId === approvalId,
+    );
+    if (approval) return { workId: w.id, approval };
+  }
+  return undefined;
+}
+
+/** ISO 8601 with the local offset instead of Z, so the time reads as the person's clock. */
+function localIso(date: Date): string {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  const offset = -date.getTimezoneOffset();
+  const sign = offset >= 0 ? "+" : "-";
+  const abs = Math.abs(offset);
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+    `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
+    `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`
+  );
+}