@openshain/mcp 0.2.0 → 0.3.1

package/dist/server.js

@@ -1,21 +1,37 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { compileInputValidator, createToolCaller, createToolRegistry, isOpenshainError, isTerminal, loadConfig, parseWorkId, resolveWorkspacePath, SESSION_WORK_TYPE, uuidv7, verifyArtifact, WorkStore, } from "@openshain/core";
+import { ASK_USER, compileInputValidator, countToolCalls, createToolCaller, createToolRegistry, isKnownEventType, isOpenshainError, isTerminal, loadConfig, parsePayloadFile, parseWorkId, pendingQuestions, RUNTIME_PROVIDER_ID, resolveWorkspacePath, SESSION_WORK_TYPE, uuidv7, verifyArtifact, WorkStore, workHistory, } from "@openshain/core";
 import pkg from "../package.json" with { type: "json" };
 import { Session } from "./session.js";
 /** The tools every session has, before the workspace's own. Their names are reserved in the runtime. */
 const WORK_TOOLS = [
     {
         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.",
+        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. 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,
@@ -33,10 +49,10 @@ const WORK_TOOLS = [
     },
     {
         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,
         },
     },
@@ -51,12 +67,15 @@ const WORK_TOOLS = [
         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,
                     },
@@ -71,12 +90,69 @@ const WORK_TOOLS = [
         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,
+    },
+    {
+        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: "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 = 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";
 const validators = new Map(WORK_TOOLS.map((tool) => [tool.name, compileInputValidator(tool.inputSchema)]));
 /**
@@ -115,18 +191,26 @@ export async function createMcpServer(options) {
         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;
-                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;
+                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);
@@ -138,14 +222,98 @@ export async function createMcpServer(options) {
                 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.id;
+                const { id: given, history } = input;
                 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;
+                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;
+                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;
+                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, payload);
+                if (type === "usage.recorded" && parsed.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 });
+                    return json({ id: event.id, seq: event.seq });
+                }
+                finally {
+                    await opened.close();
+                }
             }
             case "work_list": {
                 const { works: all, problems } = await works.list();
@@ -153,8 +321,11 @@ export async function createMcpServer(options) {
                     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,
@@ -191,8 +362,23 @@ export async function createMcpServer(options) {
                 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`);
+                }
                 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);
                 }
@@ -265,6 +451,7 @@ function toMcpTool(definition) {
         name: definition.name,
         description: definition.description,
         inputSchema: definition.inputSchema,
+        annotations: { readOnlyHint: definition.effect === "observe" },
     };
 }
 function toMcpResult(result) {

package/dist/session.d.ts

@@ -2,9 +2,12 @@ import type { WorkId } from "@openshain/core";
 /** What one connection remembers: the work the agent is on, and the order of its calls. */
 export declare class Session {
     private currentId;
+    private readonly known;
     private queue;
     get current(): WorkId | undefined;
     select(id: WorkId): void;
+    /** Whether this connection created or selected the work, so it may record its own events on it. */
+    knows(id: WorkId): boolean;
     clear(): void;
     /** Runs one call after the previous one finished, so calls the agent makes in parallel do not fight over the work's lock. */
     run<T>(fn: () => Promise<T>): Promise<T>;

package/dist/session.js

@@ -1,12 +1,18 @@
 /** What one connection remembers: the work the agent is on, and the order of its calls. */
 export class Session {
     currentId;
+    known = new Set();
     queue = Promise.resolve();
     get current() {
         return this.currentId;
     }
     select(id) {
         this.currentId = id;
+        this.known.add(id);
+    }
+    /** Whether this connection created or selected the work, so it may record its own events on it. */
+    knows(id) {
+        return this.known.has(id);
     }
     clear() {
         this.currentId = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openshain/mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "MCP server that exposes an openshain workspace to any agent",
   "keywords": [
     "openshain",
@@ -45,10 +45,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
-    "@openshain/core": "0.2.0"
+    "@openshain/core": "0.3.1"
   },
   "devDependencies": {
-    "@openshain/tools": "0.2.0"
+    "@openshain/tools": "0.3.1"
   },
   "publishConfig": {
     "access": "public"

package/src/server.ts

@@ -8,15 +8,22 @@ import {
 import {
   type AnyEvent,
   type Artifact,
+  ASK_USER,
   compileInputValidator,
+  countToolCalls,
   createToolCaller,
   createToolRegistry,
   type Event,
+  type EventType,
   type InputValidation,
+  isKnownEventType,
   isOpenshainError,
   isTerminal,
   loadConfig,
+  parsePayloadFile,
   parseWorkId,
+  pendingQuestions,
+  RUNTIME_PROVIDER_ID,
   type RuntimeProviders,
   resolveWorkspacePath,
   SESSION_WORK_TYPE,
@@ -27,6 +34,7 @@ import {
   type Work,
   type WorkId,
   WorkStore,
+  workHistory,
 } from "@openshain/core";
 import pkg from "../package.json" with { type: "json" };
 import { Session } from "./session.ts";
@@ -42,15 +50,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 +93,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 +113,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 +136,76 @@ 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: "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";
 
@@ -163,22 +255,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 +291,99 @@ 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 "work_list": {
         const { works: all, problems } = await works.list();
@@ -203,8 +391,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 +431,24 @@ 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`,
+          );
+        }
         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 +530,7 @@ function toMcpTool(definition: ToolDefinition): Tool {
     name: definition.name,
     description: definition.description,
     inputSchema: definition.inputSchema as Tool["inputSchema"],
+    annotations: { readOnlyHint: definition.effect === "observe" },
   };
 }
 

package/src/session.ts

@@ -3,6 +3,7 @@ import type { WorkId } from "@openshain/core";
 /** What one connection remembers: the work the agent is on, and the order of its calls. */
 export class Session {
   private currentId: WorkId | undefined;
+  private readonly known = new Set<WorkId>();
   private queue: Promise<unknown> = Promise.resolve();
 
   get current(): WorkId | undefined {
@@ -11,6 +12,12 @@ export class Session {
 
   select(id: WorkId): void {
     this.currentId = id;
+    this.known.add(id);
+  }
+
+  /** Whether this connection created or selected the work, so it may record its own events on it. */
+  knows(id: WorkId): boolean {
+    return this.known.has(id);
   }
 
   clear(): void {