@openshain/core 0.2.0 → 0.4.0

package/dist/config/yaml.js

@@ -0,0 +1,49 @@
+import { isNode, LineCounter, parseDocument } from "yaml";
+import { OpenshainError } from "../errors.js";
+/**
+ * Parses a YAML file against a zod schema. Every problem is reported with its line and column
+ * and the path of the field, so that a person can fix the file. Returns the data together with
+ * `problem`, for checks the caller adds after parsing.
+ */
+export function parseYamlFile(text, schema, fileName) {
+    const lineCounter = new LineCounter();
+    let doc;
+    let data;
+    try {
+        doc = parseDocument(text, { lineCounter });
+        data = doc.errors.length > 0 ? undefined : doc.toJS();
+    }
+    catch (cause) {
+        // yaml refuses resource-exhaustion documents (alias bombs) with a plain error
+        throw new OpenshainError("config", `${fileName}: ${cause.message}`, { cause });
+    }
+    if (doc.errors.length > 0) {
+        const lines = doc.errors.map((error) => {
+            const pos = error.linePos?.[0] ?? { line: 0, col: 0 };
+            return `${fileName}:${pos.line}:${pos.col} ${firstLine(error.message)}`;
+        });
+        throw new OpenshainError("config", lines.join("\n"));
+    }
+    const locate = (path) => {
+        for (let i = path.length; i >= 0; i--) {
+            const node = i === 0 ? doc.contents : doc.getIn(path.slice(0, i), true);
+            if (isNode(node) && node.range)
+                return lineCounter.linePos(node.range[0]);
+        }
+        return { line: 1, col: 1 };
+    };
+    const problem = (path, message) => {
+        const { line, col } = locate(path);
+        const where = path.length === 0 ? "<root>" : path.map(String).join(".");
+        return `${fileName}:${line}:${col} ${where}: ${message}`;
+    };
+    const result = schema.safeParse(data);
+    if (!result.success) {
+        const problems = result.error.issues.map((issue) => problem(issue.path, issue.message));
+        throw new OpenshainError("config", problems.join("\n"));
+    }
+    return { data: result.data, problem };
+}
+function firstLine(message) {
+    return message.split("\n", 1)[0] ?? message;
+}

package/dist/index.d.ts

@@ -1,11 +1,13 @@
+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 { type EventId, newEventId, newWorkId, parseEventId, parseWorkId, type WorkId, } from "./ids.ts";
 export type { ModelDescription, ModelMessage, ModelProvider, ModelRequest, ModelResponse, UserPart, } from "./model/types.ts";
-export { type CreateRuntimeOptions, createRuntime, createToolCaller, createToolRegistry, MAX_TOOL_TEXT_CHARS, type Runtime, type RuntimeProviders, type ToolSummary, } from "./runtime.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 { type HiddenTool, type RegisteredTool, type RegisterOptions, ToolRegistry, } from "./tool/registry.ts";
@@ -14,7 +16,8 @@ export { compileInputValidator, type InputValidation } from "./tool/validate.ts"
 export { uuidv7 } from "./uuid.ts";
 export { verifyArtifact } from "./work/artifacts.ts";
 export { EVENTS_FILE_NAME, EventLog, type NewEvent } from "./work/event-log.ts";
-export { type AnyEvent, type Artifact, type AssistantPart, canonical, type Event, type EventFile, EventFileSchema, type EventPayloads, type EventType, eventFromFile, eventToFile, type ModelUsage, payloadFileSchemas, type StopReason, TOOL_REJECTION_CODES, type ToolContent, type ToolRejectionCode, type UnknownEvent, } from "./work/events.ts";
+export { type AnyEvent, type Artifact, type AssistantPart, canonical, type Event, type EventFile, EventFileSchema, type EventPayloads, 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 { type CreateWorkInput, type ListResult, WORK_DIR_NAME, WORK_FILE_NAME, type WorkHandle, WorkStore, } from "./work/store.ts";

package/dist/index.js

@@ -1,10 +1,12 @@
 // @openshain/core: Contracts (provider interfaces), fundamental objects, and the work runtime
+export { AUTHORITY_DIR_NAME, DECISION_KINDS, DECISIONS_DIR_NAME, DELEGATIONS_FILE_NAME, DecisionFileSchema, DelegationsFileSchema, evaluate, loadAuthority, matchGlob, OPEN_AUTHORITY, POLICY_FILE_NAME, PolicyFileSchema, writeDecision, } from "./authority/policy.js";
 export { CONFIG_FILE_NAME, loadConfig, parseConfig, } from "./config/load.js";
 export { LANGUAGES } from "./config/schema.js";
 export { ERROR_CODES, isOpenshainError, OpenshainError } from "./errors.js";
 export { newEventId, newWorkId, parseEventId, parseWorkId, } from "./ids.js";
-export { createRuntime, createToolCaller, createToolRegistry, MAX_TOOL_TEXT_CHARS, } from "./runtime.js";
+export { createRuntime, createToolCaller, createToolRegistry, MAX_TOOL_TEXT_CHARS, REVIEW_DIR_NAME, } from "./runtime.js";
 export { jsonSchemas } from "./schemas.js";
+export { ASK_USER, RUNTIME_PROVIDER_ID } from "./tool/ask-user.js";
 export { loadToolModule } from "./tool/load-module.js";
 export { RESERVED_PATHS, resolveWorkspacePath } from "./tool/paths.js";
 export { ToolRegistry, } from "./tool/registry.js";
@@ -13,7 +15,8 @@ export { compileInputValidator } from "./tool/validate.js";
 export { uuidv7 } from "./uuid.js";
 export { verifyArtifact } from "./work/artifacts.js";
 export { EVENTS_FILE_NAME, EventLog } from "./work/event-log.js";
-export { canonical, EventFileSchema, eventFromFile, eventToFile, payloadFileSchemas, TOOL_REJECTION_CODES, } from "./work/events.js";
+export { canonical, EventFileSchema, eventFromFile, eventToFile, isKnownEventType, parsePayloadFile, payloadFileSchemas, TOOL_REJECTION_CODES, } from "./work/events.js";
+export { countToolCalls, pendingApprovals, pendingQuestions, workHistory, } from "./work/history.js";
 export { acquireLock, LOCK_FILE_NAME } from "./work/lock.js";
 export { buildProjection } from "./work/projection.js";
 export { WORK_DIR_NAME, WORK_FILE_NAME, WorkStore, } from "./work/store.js";

package/dist/runtime.d.ts

@@ -1,4 +1,5 @@
-import type { Config } from "./config/schema.ts";
+import { type Authority } from "./authority/policy.ts";
+import type { Config, ModelConfig } from "./config/schema.ts";
 import type { ModelProvider } from "./model/types.ts";
 import type { HiddenTool } from "./tool/registry.ts";
 import { ToolRegistry } from "./tool/registry.ts";
@@ -6,7 +7,7 @@ import type { ToolCall, ToolDefinition, ToolProvider, ToolResult } from "./tool/
 import { 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>;
 }
@@ -21,6 +22,8 @@ export interface ToolSummary {
 }
 /** Longer tool output is cut here so that one tool cannot flood the model's context. */
 export declare const MAX_TOOL_TEXT_CHARS = 50000;
+/** Where a work keeps the review packages a person sends to a reviewer. */
+export declare const REVIEW_DIR_NAME = "review";
 export interface Runtime {
     readonly workspaceRoot: string;
     readonly config: Config;
@@ -41,6 +44,28 @@ export declare function createToolCaller(input: {
     registry: ToolRegistry;
     config: Config;
     workspaceRoot: string;
-}): (work: WorkHandle, call: ToolCall) => Promise<ToolResult>;
+    /**
+     * 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>;
+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. */
 export declare function createToolRegistry(workspaceRoot: string, config: Config, tools: RuntimeProviders["tools"]): Promise<ToolRegistry>;

package/dist/runtime.js

@@ -1,15 +1,24 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { evaluate, loadAuthority, OPEN_AUTHORITY, } from "./authority/policy.js";
 import { loadConfig } from "./config/load.js";
 import { isOpenshainError, OpenshainError } from "./errors.js";
 import { loadToolModule } from "./tool/load-module.js";
 import { ToolRegistry } from "./tool/registry.js";
+import { uuidv7 } from "./uuid.js";
 import { TOOL_REJECTION_CODES } from "./work/events.js";
-import { WorkStore } from "./work/store.js";
+import { WORK_DIR_NAME, WorkStore } from "./work/store.js";
 /** 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";
 /** Builds a runtime for one workspace from its config and the providers the caller knows. */
 export async function createRuntime(options) {
     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;
@@ -22,6 +31,7 @@ export async function createRuntime(options) {
         throw new OpenshainError("config", `model ${description.provider}/${description.model} cannot call tools; openshain needs a model with tool support`);
     }
     const registry = await createToolRegistry(workspaceRoot, config, providers.tools);
+    const authority = await loadAuthority(workspaceRoot);
     const works = new WorkStore(workspaceRoot);
     return {
         workspaceRoot,
@@ -31,13 +41,15 @@ export async function createRuntime(options) {
         tools: {
             list: () => registry.list().map(({ definition, providerId }) => ({ definition, providerId })),
             hidden: () => registry.hiddenTools(),
-            call: createToolCaller({ registry, config, workspaceRoot }),
+            call: createToolCaller({ registry, config, workspaceRoot, authority }),
         },
     };
 }
 /** The tool call pipeline on its own: authorize, validate, run, record. For callers that need no model, such as the MCP server. */
 export function createToolCaller(input) {
-    return (work, call) => callTool({ ...input, work, call });
+    const given = input.authority;
+    const current = typeof given === "function" ? given : () => given ?? OPEN_AUTHORITY;
+    return (work, call, options) => callTool({ ...input, authority: current(), work, call, ...options });
 }
 /** Registers the tool providers the config names: the caller's factories by id, and modules from the workspace. Needs no model. */
 export async function createToolRegistry(workspaceRoot, config, tools) {
@@ -58,8 +70,8 @@ export async function createToolRegistry(workspaceRoot, config, tools) {
     return registry;
 }
 /**
- * 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, call) {
     const tool = registry.get(call.name);
@@ -74,7 +86,7 @@ function authorize(registry, call) {
         : { ok: false, code: "unknown_tool", reason: `unknown tool "${call.name}"` };
 }
 async function callTool(input) {
-    const { registry, config, workspaceRoot, work, call } = input;
+    const { registry, config, workspaceRoot, authority, work, call } = input;
     const reject = async (code, reason) => {
         await work.append({
             type: "tool.rejected",
@@ -90,6 +102,70 @@ async function callTool(input) {
     if (!validation.ok) {
         return reject("schema_mismatch", `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 = {
+                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",
         payload: { callId: call.id, provider: tool.providerId, name: call.name, input: call.input },
@@ -127,6 +203,72 @@ 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, input) {
+    const events = await work.events();
+    const facts = [];
+    let proposal = "";
+    for (const event of events) {
+        if (event.type === "tool.called") {
+            const { name, input: called } = event.payload;
+            const path = pathOf(called);
+            facts.push(path === undefined ? name : `${name} ${path}`);
+        }
+        else if (event.type === "model.completed") {
+            const text = event.payload.content
+                .filter((part) => part.type === "text")
+                .map((part) => part.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) {
+    const path = input?.path;
+    if (typeof path !== "string" || path === "")
+        return undefined;
+    const segments = [];
+    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() {
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
 function isRejectionCode(code) {
     return TOOL_REJECTION_CODES.includes(code);
 }

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import type { JsonSchema } from "./tool/types.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
  * schemas that validate them. `spec/schemas/` holds this output; `bun run schemas` regenerates it.

package/dist/schemas.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { DelegationsFileSchema, PolicyFileSchema } from "./authority/policy.js";
 import { ConfigFileSchema } from "./config/schema.js";
 import { EventFileSchema, payloadFileSchemas } from "./work/events.js";
 import { WorkFileSchema } from "./work/work.js";
@@ -13,6 +14,8 @@ export function jsonSchemas() {
         "config.v1": describe(ConfigFileSchema, "openshain.yaml", "The company workspace manifest as written on disk."),
         "events.v1": eventsSchema(),
         "work.v1": describe(WorkFileSchema, "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/dist/tool/ask-user.d.ts

@@ -0,0 +1,5 @@
+import { type ToolDefinition } from "./types.ts";
+/** The provider id the runtime records for the tools it runs itself. */
+export declare const RUNTIME_PROVIDER_ID = "runtime";
+/** The one tool the runtime itself provides: stop and ask the person. */
+export declare const ASK_USER: Readonly<ToolDefinition>;

package/dist/tool/ask-user.js

@@ -0,0 +1,22 @@
+import { ASK_USER_TOOL_NAME } from "./types.js";
+/** 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 = 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/dist/tool/paths.d.ts

@@ -1,5 +1,5 @@
 /** Paths the runtime keeps for itself. Tools may not read or write them. */
-export declare const RESERVED_PATHS: readonly ["openshain.yaml", "work"];
+export declare const RESERVED_PATHS: readonly ["openshain.yaml", "work", "principals", "authority"];
 /**
  * Turns a tool-supplied relative path into an absolute path inside the workspace.
  *

package/dist/tool/paths.js

@@ -2,7 +2,7 @@ import { lstat, readlink, realpath } from "node:fs/promises";
 import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { OpenshainError } from "../errors.js";
 /** Paths the runtime keeps for itself. Tools may not read or write them. */
-export const RESERVED_PATHS = ["openshain.yaml", "work"];
+export const RESERVED_PATHS = ["openshain.yaml", "work", "principals", "authority"];
 const MAX_SYMLINK_HOPS = 32;
 /**
  * Turns a tool-supplied relative path into an absolute path inside the workspace.

package/dist/tool/types.js

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

package/dist/work/events.d.ts

@@ -43,7 +43,7 @@ export interface ModelUsage {
     /** The part of outputTokens spent on reasoning. */
     reasoningTokens?: number;
 }
-export declare const TOOL_REJECTION_CODES: readonly ["schema_mismatch", "unknown_tool", "not_allowed", "reserved_path", "outside_workspace", "invalid_path"];
+export declare const TOOL_REJECTION_CODES: readonly ["schema_mismatch", "unknown_tool", "not_allowed", "reserved_path", "outside_workspace", "invalid_path", "limit_reached", "denied", "rejected_by_person"];
 export type ToolRejectionCode = (typeof TOOL_REJECTION_CODES)[number];
 export interface EventPayloads {
     "work.created": {
@@ -106,10 +106,55 @@ export interface EventPayloads {
         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;
@@ -135,6 +180,33 @@ export interface EventPayloads {
         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 {
     v: 1;
@@ -232,9 +304,12 @@ export declare const payloadFileSchemas: {
         call_id: z.ZodString;
         name: z.ZodString;
         code: z.ZodEnum<{
+            denied: "denied";
             invalid_path: "invalid_path";
+            limit_reached: "limit_reached";
             not_allowed: "not_allowed";
             outside_workspace: "outside_workspace";
+            rejected_by_person: "rejected_by_person";
             reserved_path: "reserved_path";
             schema_mismatch: "schema_mismatch";
             unknown_tool: "unknown_tool";
@@ -249,9 +324,77 @@ export declare const payloadFileSchemas: {
         call_id: z.ZodString;
         answer: z.ZodString;
     }, z.core.$loose>;
+    "approval.requested": z.ZodObject<{
+        approval_id: z.ZodString;
+        call: z.ZodObject<{
+            call_id: z.ZodString;
+            name: z.ZodString;
+            input: z.ZodUnknown;
+        }, z.core.$loose>;
+        rule_id: z.ZodString;
+        kind: z.ZodEnum<{
+            approval: "approval";
+            review: "review";
+        }>;
+        approvers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        reviewer: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+    "review.requested": z.ZodObject<{
+        approval_id: z.ZodString;
+        package: z.ZodObject<{
+            approval_id: z.ZodString;
+            work_id: z.ZodString;
+            action: z.ZodObject<{
+                name: z.ZodString;
+                tool: z.ZodString;
+                input: z.ZodUnknown;
+            }, z.core.$loose>;
+            facts: z.ZodArray<z.ZodString>;
+            sources: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                locator: z.ZodOptional<z.ZodString>;
+                version: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+            company_rules: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                statement: z.ZodString;
+            }, z.core.$loose>>;
+            proposal: z.ZodString;
+            question: z.ZodString;
+            requested_by: z.ZodString;
+            requested_at: z.ZodISODateTime;
+        }, z.core.$loose>;
+    }, z.core.$loose>;
+    "review.decided": z.ZodObject<{
+        approval_id: z.ZodString;
+        decision_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    "decision.applied": z.ZodObject<{
+        call_id: z.ZodString;
+        decision_id: z.ZodString;
+    }, z.core.$loose>;
+    "approval.decided": z.ZodObject<{
+        approval_id: z.ZodString;
+        decision: z.ZodEnum<{
+            approve: "approve";
+            modify: "modify";
+            reject: "reject";
+        }>;
+        by: z.ZodString;
+        comment: z.ZodOptional<z.ZodString>;
+        modified_input: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
     "human.message": z.ZodObject<{
         text: z.ZodString;
     }, z.core.$loose>;
+    "prompt.expanded": z.ZodObject<{
+        name: z.ZodString;
+        source: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$loose>;
     "usage.recorded": z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"model_inference">;
         provider: z.ZodString;
@@ -308,4 +451,10 @@ export declare function eventToFile(event: AnyEvent): EventFile;
  */
 export declare function canonical(value: unknown, insideData?: boolean, seen?: WeakSet<object>): unknown;
 export declare function eventFromFile(input: unknown): AnyEvent;
+/**
+ * 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 declare function parsePayloadFile<T extends EventType>(type: T, payload: unknown): EventPayloads[T];
+export declare function isKnownEventType(type: string): type is EventType;
 export {};