@openshain/mcp 0.2.0 → 0.4.0

package/NOTICE

@@ -0,0 +1,4 @@
+openshain
+Copyright 2026 openshain contributors
+
+Licensed under the Apache License, Version 2.0.

package/dist/server.js

@@ -1,21 +1,38 @@
+import { relative } from "node:path";
 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, DecisionFileSchema, isKnownEventType, isOpenshainError, isTerminal, loadAuthority, loadConfig, parsePayloadFile, parseWorkId, pendingApprovals, pendingQuestions, RUNTIME_PROVIDER_ID, resolveWorkspacePath, SESSION_WORK_TYPE, uuidv7, verifyArtifact, WorkStore, workHistory, writeDecision, } 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 +50,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 +68,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 +91,130 @@ 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: "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 = 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)]));
 /**
@@ -88,7 +226,14 @@ export async function createMcpServer(options) {
     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({ name: "openshain", version: pkg.version }, { capabilities: { tools: {} } });
@@ -115,18 +260,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 +291,292 @@ 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 "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 = [];
+                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;
+                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;
+                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 ?? {});
+                    const after = modifiedInput;
+                    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;
+                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;
+                    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();
@@ -153,8 +584,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 +625,26 @@ 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`);
+                }
+                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);
                 }
@@ -265,6 +717,7 @@ function toMcpTool(definition) {
         name: definition.name,
         description: definition.description,
         inputSchema: definition.inputSchema,
+        annotations: { readOnlyHint: definition.effect === "observe" },
     };
 }
 function toMcpResult(result) {
@@ -284,3 +737,25 @@ function failure(text) {
 function newCallId() {
     return `call_${uuidv7()}`;
 }
+/** The work holding a pending approval, found by scanning the works that wait for one. */
+async function findApproval(works, approvalId) {
+    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) {
+    const pad = (n) => 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)}`);
+}

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;