@openshain/core 0.2.0 → 0.4.0

package/src/index.ts

@@ -1,11 +1,35 @@
 // @openshain/core: Contracts (provider interfaces), fundamental objects, and the work runtime
+
+export {
+  AUTHORITY_DIR_NAME,
+  type Authority,
+  type AuthorityRequest,
+  DECISION_KINDS,
+  DECISIONS_DIR_NAME,
+  DELEGATIONS_FILE_NAME,
+  type Decision,
+  DecisionFileSchema,
+  type DecisionKind,
+  type DecisionRecord,
+  type Delegation,
+  DelegationsFileSchema,
+  evaluate,
+  loadAuthority,
+  matchGlob,
+  OPEN_AUTHORITY,
+  POLICY_FILE_NAME,
+  type PolicyFile,
+  PolicyFileSchema,
+  type Rule,
+  writeDecision,
+} from "./authority/policy.ts";
 export {
   CONFIG_FILE_NAME,
   loadConfig,
   type ParseConfigOptions,
   parseConfig,
 } from "./config/load.ts";
-export type { Config, ToolProviderRef } from "./config/schema.ts";
+export type { Config, ModelConfig, ToolProviderRef } from "./config/schema.ts";
 export { LANGUAGES, type Language } from "./config/schema.ts";
 export { ERROR_CODES, type ErrorCode, isOpenshainError, OpenshainError } from "./errors.ts";
 export {
@@ -25,16 +49,20 @@ export type {
   UserPart,
 } from "./model/types.ts";
 export {
+  type CallOptions,
   type CreateRuntimeOptions,
   createRuntime,
   createToolCaller,
   createToolRegistry,
   MAX_TOOL_TEXT_CHARS,
+  type PendingApprovalResult,
+  REVIEW_DIR_NAME,
   type Runtime,
   type RuntimeProviders,
   type ToolSummary,
 } from "./runtime.ts";
 export { jsonSchemas, type SchemaName } from "./schemas.ts";
+export { ASK_USER, RUNTIME_PROVIDER_ID } from "./tool/ask-user.ts";
 export { loadToolModule } from "./tool/load-module.ts";
 export { RESERVED_PATHS, resolveWorkspacePath } from "./tool/paths.ts";
 export {
@@ -71,14 +99,28 @@ export {
   type EventType,
   eventFromFile,
   eventToFile,
+  isKnownEventType,
   type ModelUsage,
+  parsePayloadFile,
   payloadFileSchemas,
+  type ReviewPackage,
   type StopReason,
   TOOL_REJECTION_CODES,
   type ToolContent,
   type ToolRejectionCode,
   type UnknownEvent,
 } from "./work/events.ts";
+export {
+  countToolCalls,
+  type FailureReason,
+  type HistoryCall,
+  type PendingApproval,
+  type PendingQuestion,
+  pendingApprovals,
+  pendingQuestions,
+  type WorkHistory,
+  workHistory,
+} from "./work/history.ts";
 export { acquireLock, LOCK_FILE_NAME, type Lock } from "./work/lock.ts";
 export { buildProjection, type Projection, type ProjectionInput } from "./work/projection.ts";
 export {

package/src/runtime.ts

@@ -1,18 +1,28 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  type Authority,
+  evaluate,
+  loadAuthority,
+  OPEN_AUTHORITY,
+  type Rule,
+} from "./authority/policy.ts";
 import { loadConfig } from "./config/load.ts";
-import type { Config } from "./config/schema.ts";
+import type { Config, ModelConfig } from "./config/schema.ts";
 import { isOpenshainError, OpenshainError } from "./errors.ts";
 import type { ModelProvider } from "./model/types.ts";
 import { loadToolModule } from "./tool/load-module.ts";
 import type { HiddenTool } from "./tool/registry.ts";
 import { type RegisteredTool, ToolRegistry } from "./tool/registry.ts";
 import type { ToolCall, ToolDefinition, ToolProvider, ToolResult } from "./tool/types.ts";
-import type { ToolContent } from "./work/events.ts";
+import { uuidv7 } from "./uuid.ts";
+import type { Event, ReviewPackage, ToolContent } from "./work/events.ts";
 import { TOOL_REJECTION_CODES, type ToolRejectionCode } from "./work/events.ts";
-import { type WorkHandle, WorkStore } from "./work/store.ts";
+import { WORK_DIR_NAME, type WorkHandle, WorkStore } from "./work/store.ts";
 
 export interface RuntimeProviders {
   /** Model providers by the id used in openshain.yaml. */
-  models: Record<string, (model: Config["model"]) => ModelProvider>;
+  models: Record<string, (model: ModelConfig) => ModelProvider>;
   /** Tool providers by the id used in openshain.yaml. Modules are loaded from the config directly. */
   tools: Record<string, () => ToolProvider>;
 }
@@ -31,6 +41,9 @@ export interface ToolSummary {
 /** Longer tool output is cut here so that one tool cannot flood the model's context. */
 export const MAX_TOOL_TEXT_CHARS = 50_000;
 
+/** Where a work keeps the review packages a person sends to a reviewer. */
+export const REVIEW_DIR_NAME = "review";
+
 export interface Runtime {
   readonly workspaceRoot: string;
   readonly config: Config;
@@ -50,6 +63,12 @@ export async function createRuntime(options: CreateRuntimeOptions): Promise<Runt
   const { workspaceRoot, providers } = options;
   const config = await loadConfig(workspaceRoot, { modelProviders: Object.keys(providers.models) });
 
+  if (!config.model) {
+    throw new OpenshainError(
+      "config",
+      "this needs a model: add a model section to openshain.yaml (only the interactive CLI needs one)",
+    );
+  }
   const modelFactory = Object.hasOwn(providers.models, config.model.provider)
     ? providers.models[config.model.provider]
     : undefined;
@@ -66,6 +85,7 @@ export async function createRuntime(options: CreateRuntimeOptions): Promise<Runt
   }
 
   const registry = await createToolRegistry(workspaceRoot, config, providers.tools);
+  const authority = await loadAuthority(workspaceRoot);
   const works = new WorkStore(workspaceRoot);
   return {
     workspaceRoot,
@@ -75,7 +95,7 @@ export async function createRuntime(options: CreateRuntimeOptions): Promise<Runt
     tools: {
       list: () => registry.list().map(({ definition, providerId }) => ({ definition, providerId })),
       hidden: () => registry.hiddenTools(),
-      call: createToolCaller({ registry, config, workspaceRoot }),
+      call: createToolCaller({ registry, config, workspaceRoot, authority }),
     },
   };
 }
@@ -85,8 +105,32 @@ export function createToolCaller(input: {
   registry: ToolRegistry;
   config: Config;
   workspaceRoot: string;
-}): (work: WorkHandle, call: ToolCall) => Promise<ToolResult> {
-  return (work, call) => callTool({ ...input, work, call });
+  /**
+   * Who may do what. Pass a function when it can change while the server runs, as it does when
+   * a reviewer writes a decision. Omitted: the workspace is open, as one without authority/ is.
+   */
+  authority?: Authority | (() => Authority);
+}): (work: WorkHandle, call: ToolCall, options?: CallOptions) => Promise<ToolResult> {
+  const given = input.authority;
+  const current = typeof given === "function" ? given : () => given ?? OPEN_AUTHORITY;
+  return (work, call, options) =>
+    callTool({ ...input, authority: current(), work, call, ...options });
+}
+
+export interface CallOptions {
+  /** The approval that lets this call run: the policy is not consulted again. */
+  approvedBy?: string;
+}
+
+/** What a held call answers with: the client shows it to the person and the turn stops there. */
+export interface PendingApprovalResult {
+  pending: "approval" | "review";
+  approval_id: string;
+  rule_id: string;
+  approvers?: string[];
+  reviewer?: { role: string; name?: string };
+  /** For a review: why the policy asks for one, when a cited decision did not cover the call. */
+  why?: string;
 }
 
 /** Registers the tool providers the config names: the caller's factories by id, and modules from the workspace. Needs no model. */
@@ -115,8 +159,8 @@ export async function createToolRegistry(
 }
 
 /**
- * The one place that allows or refuses a call before it runs. At this stage it knows only
- * the allow lists; a later authority engine plugs in here.
+ * The one place that allows or refuses a call before it runs by name alone. What the workspace
+ * allows a call to do is decided after this, by the policy in `authority/`.
  */
 function authorize(
   registry: ToolRegistry,
@@ -137,10 +181,12 @@ async function callTool(input: {
   registry: ToolRegistry;
   config: Config;
   workspaceRoot: string;
+  authority: Authority;
   work: WorkHandle;
   call: ToolCall;
+  approvedBy?: string;
 }): Promise<ToolResult> {
-  const { registry, config, workspaceRoot, work, call } = input;
+  const { registry, config, workspaceRoot, authority, work, call } = input;
   const reject = async (code: ToolRejectionCode, reason: string): Promise<ToolResult> => {
     await work.append({
       type: "tool.rejected",
@@ -159,6 +205,72 @@ async function callTool(input: {
       `input does not match the schema of ${call.name}: ${validation.reason}`,
     );
   }
+  // The policy judges after the allow list, unless a person already approved this very call.
+  if (input.approvedBy === undefined) {
+    const path = pathOf(call.input);
+    const judged = evaluate(authority, {
+      tool: call.name,
+      effect: tool.definition.effect,
+      ...(path !== undefined && { path }),
+      principal: config.principal.id,
+      profession: config.profession.id,
+      workType: (await work.current()).type,
+      businessDate: businessDate(),
+    });
+    if (judged.kind === "deny") return reject("denied", judged.reason);
+    if (judged.kind === "approval_required" || judged.kind === "review_required") {
+      const review = judged.kind === "review_required";
+      const approvalId = `apr_${uuidv7()}`;
+      const approvers = judged.rule.approvers ?? [config.principal.id];
+      const declared = judged.rule.reviewer;
+      const reviewer = declared
+        ? { role: declared.role, ...(declared.name !== undefined && { name: declared.name }) }
+        : undefined;
+      await work.append({
+        type: "approval.requested",
+        payload: {
+          approvalId,
+          call: { callId: call.id, name: call.name, input: call.input },
+          ruleId: judged.rule.id,
+          kind: review ? "review" : "approval",
+          ...(review ? reviewer && { reviewer } : { approvers }),
+        },
+      });
+      if (review) {
+        const built = await reviewPackage(work, {
+          approvalId,
+          call,
+          rule: judged.rule,
+          principal: config.principal.id,
+        });
+        await work.append({ type: "review.requested", payload: { approvalId, package: built } });
+        // A copy the person can send to the reviewer, next to the work's own record.
+        const dir = join(workspaceRoot, WORK_DIR_NAME, work.id, REVIEW_DIR_NAME);
+        await mkdir(dir, { recursive: true });
+        await writeFile(join(dir, `${approvalId}.json`), `${JSON.stringify(built, null, 2)}\n`, {
+          flag: "wx",
+        });
+      }
+      await work.transition(
+        "waiting_approval",
+        `rule ${judged.rule.id} needs ${review ? "a review" : "approval"}`,
+      );
+      const held: PendingApprovalResult = {
+        pending: review ? "review" : "approval",
+        approval_id: approvalId,
+        rule_id: judged.rule.id,
+        ...(review ? reviewer && { reviewer } : { approvers }),
+        ...(review && judged.why !== undefined && { why: judged.why }),
+      };
+      return { content: [{ type: "json", value: held }] };
+    }
+    if (judged.kind === "allow" && judged.decision) {
+      await work.append({
+        type: "decision.applied",
+        payload: { callId: call.id, decisionId: judged.decision.id },
+      });
+    }
+  }
 
   await work.append({
     type: "tool.called",
@@ -197,6 +309,73 @@ async function callTool(input: {
   return result;
 }
 
+/**
+ * What the reviewer is asked to decide on, from the work's own record: the call, the tool calls
+ * that came before it, and the agent's last words as the proposal. Sources and company rules stay
+ * empty until knowledge is in.
+ */
+async function reviewPackage(
+  work: WorkHandle,
+  input: { approvalId: string; call: ToolCall; rule: Rule; principal: string },
+): Promise<ReviewPackage> {
+  const events = await work.events();
+  const facts: string[] = [];
+  let proposal = "";
+  for (const event of events) {
+    if (event.type === "tool.called") {
+      const { name, input: called } = (event as Event<"tool.called">).payload;
+      const path = pathOf(called);
+      facts.push(path === undefined ? name : `${name} ${path}`);
+    } else if (event.type === "model.completed") {
+      const text = (event as Event<"model.completed">).payload.content
+        .filter((part) => part.type === "text")
+        .map((part) => (part as { text: string }).text)
+        .join("\n")
+        .trim();
+      if (text !== "") proposal = text;
+    }
+  }
+  const current = await work.current();
+  return {
+    approvalId: input.approvalId,
+    workId: work.id,
+    action: {
+      name: input.rule.match.action?.toString() ?? input.call.name,
+      tool: input.call.name,
+      input: input.call.input,
+    },
+    facts,
+    sources: [],
+    companyRules: [],
+    proposal,
+    question:
+      input.rule.reason ??
+      `${current.objective} のために ${input.call.name} を実行してよいか、判断をお願いします。`,
+    requestedBy: input.principal,
+    requestedAt: new Date().toISOString(),
+  };
+}
+
+/** The path a call names, normalized to a workspace-relative posix path, when its input has one. */
+function pathOf(input: unknown): string | undefined {
+  const path = (input as { path?: unknown } | null)?.path;
+  if (typeof path !== "string" || path === "") return undefined;
+  const segments: string[] = [];
+  for (const segment of path.replaceAll("\\", "/").split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") segments.pop();
+    else segments.push(segment);
+  }
+  return segments.join("/");
+}
+
+/** Today's date on this machine's clock, YYYY-MM-DD. */
+function businessDate(): string {
+  const now = new Date();
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+
 function isRejectionCode(code: string): code is ToolRejectionCode {
   return (TOOL_REJECTION_CODES as readonly string[]).includes(code);
 }

package/src/schemas.ts

@@ -1,10 +1,16 @@
 import { z } from "zod";
+import { DelegationsFileSchema, PolicyFileSchema } from "./authority/policy.ts";
 import { ConfigFileSchema } from "./config/schema.ts";
 import type { JsonSchema } from "./tool/types.ts";
 import { EventFileSchema, payloadFileSchemas } from "./work/events.ts";
 import { WorkFileSchema } from "./work/work.ts";
 
-export type SchemaName = "config.v1" | "events.v1" | "work.v1";
+export type SchemaName =
+  | "config.v1"
+  | "events.v1"
+  | "work.v1"
+  | "authority-policy.v1"
+  | "authority-delegations.v1";
 
 /**
  * The JSON Schemas (draft 2020-12) of the files openshain reads and writes, derived from the zod
@@ -25,6 +31,16 @@ export function jsonSchemas(): Record<SchemaName, JsonSchema> {
       "work.json",
       "The state of a work as projected from its event log. Never the source of truth.",
     ),
+    "authority-policy.v1": describe(
+      PolicyFileSchema,
+      "authority/policy.yaml",
+      "The rules that judge tool calls: the first matching rule decides, else the default.",
+    ),
+    "authority-delegations.v1": describe(
+      DelegationsFileSchema,
+      "authority/delegations.yaml",
+      "Who the agent may act for, as which profession, and when.",
+    ),
   };
 }
 

package/src/tool/ask-user.ts

@@ -0,0 +1,25 @@
+import { ASK_USER_TOOL_NAME, type ToolDefinition } from "./types.ts";
+
+/** The provider id the runtime records for the tools it runs itself. */
+export const RUNTIME_PROVIDER_ID = "runtime";
+
+/** The one tool the runtime itself provides: stop and ask the person. */
+export const ASK_USER: Readonly<ToolDefinition> = Object.freeze({
+  name: ASK_USER_TOOL_NAME,
+  description:
+    "Ask the person you work for a question when you cannot proceed without their answer. Use it sparingly; prefer the workspace over guessing. The work waits until the answer is recorded with work_answer.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      question: {
+        type: "string",
+        minLength: 1,
+        maxLength: 10_000,
+        description: "The question, in the person's language.",
+      },
+    },
+    required: ["question"],
+    additionalProperties: false,
+  },
+  effect: "observe",
+});

package/src/tool/paths.ts

@@ -3,7 +3,7 @@ import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "no
 import { OpenshainError } from "../errors.ts";
 
 /** Paths the runtime keeps for itself. Tools may not read or write them. */
-export const RESERVED_PATHS = ["openshain.yaml", "work"] as const;
+export const RESERVED_PATHS = ["openshain.yaml", "work", "principals", "authority"] as const;
 
 const MAX_SYMLINK_HOPS = 32;
 

package/src/tool/types.ts

@@ -20,6 +20,12 @@ export const RESERVED_TOOL_NAMES: readonly string[] = [
   "work_list",
   "work_complete",
   "work_fail",
+  "work_answer",
+  "work_record",
+  "context",
+  "approval_list",
+  "approval_decide",
+  "review_decide",
   "work_run",
   "work_show",
 ];

package/src/work/events.ts

@@ -41,6 +41,9 @@ export const TOOL_REJECTION_CODES = [
   "reserved_path",
   "outside_workspace",
   "invalid_path",
+  "limit_reached",
+  "denied",
+  "rejected_by_person",
 ] as const;
 
 export type ToolRejectionCode = (typeof TOOL_REJECTION_CODES)[number];
@@ -71,8 +74,33 @@ export interface EventPayloads {
   "tool.rejected": { callId: string; name: string; code: ToolRejectionCode; reason: string };
   "human.input_requested": { callId: string; question: string };
   "human.input_provided": { callId: string; answer: string };
+  /** A tool call the policy holds for a person's or a reviewer's approval. The work waits. */
+  "approval.requested": {
+    approvalId: string;
+    call: { callId: string; name: string; input: unknown };
+    ruleId: string;
+    kind: "approval" | "review";
+    approvers?: string[];
+    reviewer?: { role: string; name?: string };
+  };
+  /** The package handed to the reviewer: the call, what the work established, and the question. */
+  "review.requested": { approvalId: string; package: ReviewPackage };
+  /** The reviewer's answer. A decision id when they wrote one; absent when they refused. */
+  "review.decided": { approvalId: string; decisionId?: string };
+  /** A call that ran because an approved decision covers it. */
+  "decision.applied": { callId: string; decisionId: string };
+  /** The answer to an approval: approve runs the call, reject refuses it, modify runs it with the reviewer's input. */
+  "approval.decided": {
+    approvalId: string;
+    decision: "approve" | "reject" | "modify";
+    by: string;
+    comment?: string;
+    modifiedInput?: unknown;
+  };
   /** What the person said in a session. Becomes a user message in the projection. */
   "human.message": { text: string };
+  /** A prompt command expanded for the model: its name, where it came from, and the text handed over. */
+  "prompt.expanded": { name: string; source: string; text: string };
   "usage.recorded":
     | { kind: "model_inference"; provider: string; model: string; usage: ModelUsage }
     | { kind: "tool_execution"; provider: string; usage: { durationMs: number } };
@@ -81,6 +109,23 @@ export interface EventPayloads {
   "work.failed": { reason: string; detail: string };
 }
 
+/** What a reviewer is asked to decide on, built from the work's own record. */
+export interface ReviewPackage {
+  approvalId: string;
+  workId: string;
+  action: { name: string; tool: string; input: unknown };
+  /** What the work established before this call: the tool calls it made. */
+  facts: string[];
+  /** Sources and company rules the work cited. Empty until knowledge is in. */
+  sources: { id: string; locator?: string; version?: string }[];
+  companyRules: { id: string; statement: string }[];
+  /** What the agent proposes, in its own words. */
+  proposal: string;
+  question: string;
+  requestedBy: string;
+  requestedAt: string;
+}
+
 export type EventType = keyof EventPayloads;
 
 interface Envelope {
@@ -178,7 +223,49 @@ export const payloadFileSchemas = {
   }),
   "human.input_requested": z.looseObject({ call_id: z.string(), question: z.string() }),
   "human.input_provided": z.looseObject({ call_id: z.string(), answer: z.string() }),
+  "approval.requested": z.looseObject({
+    approval_id: z.string(),
+    call: z.looseObject({ call_id: z.string(), name: z.string(), input: z.unknown() }),
+    rule_id: z.string(),
+    kind: z.enum(["approval", "review"]),
+    approvers: z.array(z.string()).optional(),
+    reviewer: z.looseObject({ role: z.string(), name: z.string().optional() }).optional(),
+  }),
+  "review.requested": z.looseObject({
+    approval_id: z.string(),
+    package: z.looseObject({
+      approval_id: z.string(),
+      work_id: z.string(),
+      action: z.looseObject({ name: z.string(), tool: z.string(), input: z.unknown() }),
+      facts: z.array(z.string()),
+      sources: z.array(
+        z.looseObject({
+          id: z.string(),
+          locator: z.string().optional(),
+          version: z.string().optional(),
+        }),
+      ),
+      company_rules: z.array(z.looseObject({ id: z.string(), statement: z.string() })),
+      proposal: z.string(),
+      question: z.string(),
+      requested_by: z.string(),
+      requested_at: z.iso.datetime(),
+    }),
+  }),
+  "review.decided": z.looseObject({
+    approval_id: z.string(),
+    decision_id: z.string().optional(),
+  }),
+  "decision.applied": z.looseObject({ call_id: z.string(), decision_id: z.string() }),
+  "approval.decided": z.looseObject({
+    approval_id: z.string(),
+    decision: z.enum(["approve", "reject", "modify"]),
+    by: z.string(),
+    comment: z.string().optional(),
+    modified_input: z.unknown().optional(),
+  }),
   "human.message": z.looseObject({ text: z.string() }),
+  "prompt.expanded": z.looseObject({ name: z.string(), source: z.string(), text: z.string() }),
   "usage.recorded": z.discriminatedUnion("kind", [
     z.looseObject({
       kind: z.literal("model_inference"),
@@ -309,6 +396,22 @@ export function eventFromFile(input: unknown): AnyEvent {
   } as Event;
 }
 
+/**
+ * Validates a payload given in the file form (snake_case, as in spec/schemas/events.v1.json) and
+ * returns it in the in-memory form. For events a client hands the runtime to record.
+ */
+export function parsePayloadFile<T extends EventType>(type: T, payload: unknown): EventPayloads[T] {
+  const parsed = payloadFileSchemas[type].safeParse(payload);
+  if (!parsed.success) {
+    throw new OpenshainError("invalid_event", `${type} payload: ${describeIssues(parsed.error)}`);
+  }
+  return payloadFromFile(type, parsed.data as FilePayload<T>);
+}
+
+export function isKnownEventType(type: string): type is EventType {
+  return isKnownType(type);
+}
+
 function isKnownType(type: string): type is EventType {
   return Object.hasOwn(payloadFileSchemas, type);
 }
@@ -435,6 +538,95 @@ const codecs: { [T in EventType]?: Codec<T> } = {
     toFile: (p) => ({ call_id: p.callId, answer: p.answer }),
     fromFile: (p) => ({ callId: p.call_id, answer: p.answer }),
   },
+  "approval.requested": {
+    toFile: (p) => ({
+      approval_id: p.approvalId,
+      call: { call_id: p.call.callId, name: p.call.name, input: p.call.input },
+      rule_id: p.ruleId,
+      kind: p.kind,
+      ...(p.approvers && { approvers: p.approvers }),
+      ...(p.reviewer && { reviewer: p.reviewer }),
+    }),
+    fromFile: (p) => ({
+      approvalId: p.approval_id,
+      call: { callId: p.call.call_id, name: p.call.name, input: p.call.input },
+      ruleId: p.rule_id,
+      kind: p.kind,
+      ...(p.approvers && { approvers: p.approvers }),
+      ...(p.reviewer && {
+        reviewer: {
+          role: p.reviewer.role,
+          ...(p.reviewer.name !== undefined && { name: p.reviewer.name }),
+        },
+      }),
+    }),
+  },
+  "review.requested": {
+    toFile: (p) => ({
+      approval_id: p.approvalId,
+      package: {
+        approval_id: p.package.approvalId,
+        work_id: p.package.workId,
+        action: p.package.action,
+        facts: p.package.facts,
+        sources: p.package.sources,
+        company_rules: p.package.companyRules,
+        proposal: p.package.proposal,
+        question: p.package.question,
+        requested_by: p.package.requestedBy,
+        requested_at: p.package.requestedAt,
+      },
+    }),
+    fromFile: (p) => ({
+      approvalId: p.approval_id,
+      package: {
+        approvalId: p.package.approval_id,
+        workId: p.package.work_id,
+        action: p.package.action,
+        facts: p.package.facts,
+        sources: p.package.sources.map((source) => ({
+          id: source.id,
+          ...(source.locator !== undefined && { locator: source.locator }),
+          ...(source.version !== undefined && { version: source.version }),
+        })),
+        companyRules: p.package.company_rules,
+        proposal: p.package.proposal,
+        question: p.package.question,
+        requestedBy: p.package.requested_by,
+        requestedAt: p.package.requested_at,
+      },
+    }),
+  },
+  "review.decided": {
+    toFile: (p) => ({
+      approval_id: p.approvalId,
+      ...(p.decisionId !== undefined && { decision_id: p.decisionId }),
+    }),
+    fromFile: (p) => ({
+      approvalId: p.approval_id,
+      ...(p.decision_id !== undefined && { decisionId: p.decision_id }),
+    }),
+  },
+  "decision.applied": {
+    toFile: (p) => ({ call_id: p.callId, decision_id: p.decisionId }),
+    fromFile: (p) => ({ callId: p.call_id, decisionId: p.decision_id }),
+  },
+  "approval.decided": {
+    toFile: (p) => ({
+      approval_id: p.approvalId,
+      decision: p.decision,
+      by: p.by,
+      ...(p.comment !== undefined && { comment: p.comment }),
+      ...(p.modifiedInput !== undefined && { modified_input: p.modifiedInput }),
+    }),
+    fromFile: (p) => ({
+      approvalId: p.approval_id,
+      decision: p.decision,
+      by: p.by,
+      ...(p.comment !== undefined && { comment: p.comment }),
+      ...(p.modified_input !== undefined && { modifiedInput: p.modified_input }),
+    }),
+  },
   "usage.recorded": {
     toFile: (p) =>
       p.kind === "tool_execution"