@openshain/core 0.3.1 → 0.4.0

package/src/runtime.ts

@@ -1,3 +1,12 @@
+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, ModelConfig } from "./config/schema.ts";
 import { isOpenshainError, OpenshainError } from "./errors.ts";
@@ -6,9 +15,10 @@ 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. */
@@ -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;
@@ -72,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,
@@ -81,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 }),
     },
   };
 }
@@ -91,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. */
@@ -121,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,
@@ -143,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",
@@ -165,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",
@@ -203,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/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

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

package/src/work/events.ts

@@ -42,6 +42,8 @@ export const TOOL_REJECTION_CODES = [
   "outside_workspace",
   "invalid_path",
   "limit_reached",
+  "denied",
+  "rejected_by_person",
 ] as const;
 
 export type ToolRejectionCode = (typeof TOOL_REJECTION_CODES)[number];
@@ -72,6 +74,29 @@ 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. */
@@ -84,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 {
@@ -181,6 +223,47 @@ 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", [
@@ -455,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"

package/src/work/history.ts

@@ -44,6 +44,28 @@ export function pendingQuestions(events: readonly AnyEvent[]): PendingQuestion[]
     .map((e) => ({ callId: e.payload.callId, question: e.payload.question }));
 }
 
+export interface PendingApproval {
+  approvalId: string;
+  call: { callId: string; name: string; input: unknown };
+  ruleId: string;
+  kind: "approval" | "review";
+  approvers?: string[];
+  reviewer?: { role: string; name?: string };
+}
+
+/** The approvals of the work that have no decision yet, oldest first. */
+export function pendingApprovals(events: readonly AnyEvent[]): PendingApproval[] {
+  const decided = new Set(
+    events
+      .filter((e): e is Event<"approval.decided"> => e.type === "approval.decided")
+      .map((e) => e.payload.approvalId),
+  );
+  return events
+    .filter((e): e is Event<"approval.requested"> => e.type === "approval.requested")
+    .filter((e) => !decided.has(e.payload.approvalId))
+    .map((e) => ({ ...e.payload }));
+}
+
 export interface HistoryCall {
   callId: string;
   name: string;
@@ -59,6 +81,8 @@ export interface WorkHistory {
   /** Calls that were started but have no result: the work stopped while they ran. */
   unfinished: HistoryCall[];
   pending: PendingQuestion[];
+  /** Calls held for approval that nobody has decided on yet. */
+  approvals: PendingApproval[];
   toolCalls: number;
   /** Model calls recorded on the work, for a client that counts them against a limit. */
   modelCalls: number;
@@ -90,6 +114,7 @@ export function workHistory(events: readonly AnyEvent[]): WorkHistory {
     calls,
     unfinished: calls.filter((c) => c.isError === undefined && c.rejected === undefined),
     pending: pendingQuestions(events),
+    approvals: pendingApprovals(events),
     toolCalls: countToolCalls(events),
     modelCalls: events.filter((e) => e.type === "model.requested").length,
   };

package/src/work/projection.ts

@@ -35,12 +35,24 @@ export function buildProjection(input: ProjectionInput): Projection {
     first?.type === "work.created" ? (first as Event<"work.created">).payload.agentName : undefined;
   const system = [
     config.profession.instructions.trim(),
-    `この会社は ${config.company.name}。`,
-    `依頼する人は ${config.principal.name}(${config.principal.id})。あなたはこの人の代理として働き、この人と話す。あなた自身は ${config.principal.name} ではなく、この会社で働く社員エージェントで、名乗るならそう名乗る。`,
-    ...(agentName
-      ? [`あなたの名前は ${agentName}。名乗るときはこの名前と、社員エージェントであることを言う。`]
-      : []),
-    "件数、合計、検索の結果は Tool が返した値をそのまま使い、自分で数えたり合計したりしない。各ターンの最後に Runtime が「残り model 呼び出し N 回、Tool 呼び出し M 回」という 1 行を user message として追加する。これは残量の通知で、返事は要らない。依頼が終わったら、何をしたかを要約して終える。",
+    [
+      "# 立場",
+      `この会社は ${config.company.name}。依頼する人は ${config.principal.name}(${config.principal.id})。あなたはこの人の代理として働き、この人と話す。あなた自身は ${config.principal.name} ではなく、この会社で働く社員エージェント。`,
+      ...(agentName
+        ? [
+            `あなたの名前は ${agentName}。名乗るときはこの名前と、社員エージェントであることを言う。`,
+          ]
+        : []),
+      "",
+      "# 数字と事実",
+      "件数、合計、検索の結果は Tool が返した値をそのまま使う。自分で数え直したり足し直したりしない。日付と時刻は context を呼んで確かめ、推測しない。",
+      "",
+      "# 残り回数",
+      "各ターンの最後に「残り model 呼び出し N 回、Tool 呼び出し M 回」という 1 行が user message として届く。残量の通知なので、返事は要らない。",
+      "",
+      "# 終わり方",
+      "依頼が終わったら、何をしたかと結果の数字を書いて終える。",
+    ].join("\n"),
   ].join("\n\n");
 
   const messages: ModelMessage[] = [];