@openshain/core 0.3.1 → 0.4.1

package/src/config/load.ts

@@ -1,8 +1,8 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { isNode, LineCounter, parseDocument } from "yaml";
 import { OpenshainError } from "../errors.ts";
 import { type Config, ConfigFileSchema, toConfig } from "./schema.ts";
+import { parseYamlFile } from "./yaml.ts";
 
 export const CONFIG_FILE_NAME = "openshain.yaml";
 
@@ -31,43 +31,8 @@ export async function loadConfig(
 
 export function parseConfig(text: string, options: ParseConfigOptions = {}): Config {
   const fileName = options.fileName ?? CONFIG_FILE_NAME;
-  const lineCounter = new LineCounter();
-  let doc: ReturnType<typeof parseDocument>;
-  let data: unknown;
-  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 as Error).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: readonly PropertyKey[]): { line: number; col: number } => {
-    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: readonly PropertyKey[], message: string): string => {
-    const { line, col } = locate(path);
-    const where = path.length === 0 ? "<root>" : path.map(String).join(".");
-    return `${fileName}:${line}:${col} ${where}: ${message}`;
-  };
-
-  const result = ConfigFileSchema.safeParse(data);
-  if (!result.success) {
-    const problems = result.error.issues.map((issue) => problem(issue.path, issue.message));
-    throw new OpenshainError("config", problems.join("\n"));
-  }
+  const { data, problem } = parseYamlFile(text, ConfigFileSchema, fileName);
+  const result = { data };
 
   const known = options.modelProviders;
   if (known && result.data.model && !known.includes(result.data.model.provider)) {
@@ -82,7 +47,3 @@ export function parseConfig(text: string, options: ParseConfigOptions = {}): Con
 
   return toConfig(result.data);
 }
-
-function firstLine(message: string): string {
-  return message.split("\n", 1)[0] ?? message;
-}

package/src/config/schema.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { hostTimezone, isTimezone } from "../time.ts";
 
 const identifier = z
   .string()
@@ -43,6 +44,16 @@ export const ConfigFileSchema = z.strictObject({
   company: z.strictObject({
     name: z.string().min(1).max(200),
     language: z.enum(LANGUAGES).default("ja"),
+    // The company's own clock decides every business date, so a workspace answers the same
+    // whether it runs on a laptop in Tokyo or in a container set to UTC.
+    // No default in the schema: it would bake the machine that generated it into the published
+    // JSON Schema. The fallback is applied when the file is turned into a Config.
+    timezone: z
+      .string()
+      .min(1)
+      .max(100)
+      .refine(isTimezone, "not a timezone name, such as Asia/Tokyo")
+      .optional(),
   }),
   principal: z.strictObject({ id: identifier, name: z.string().min(1).max(200) }),
   profession: z.strictObject({ id: identifier, instructions: z.string().min(1).max(100_000) }),
@@ -96,7 +107,7 @@ export interface ModelConfig {
 
 export interface Config {
   version: 1;
-  company: { name: string; language: Language };
+  company: { name: string; language: Language; timezone: string };
   principal: { id: string; name: string };
   profession: { id: string; instructions: string };
   /** The model the interactive CLI runs on. Absent when the workspace is used from other agents only. */
@@ -109,7 +120,11 @@ export interface Config {
 export function toConfig(file: ConfigFile): Config {
   return {
     version: file.version,
-    company: { name: file.company.name, language: file.company.language },
+    company: {
+      name: file.company.name,
+      language: file.company.language,
+      timezone: file.company.timezone ?? hostTimezone(),
+    },
     principal: { id: file.principal.id, name: file.principal.name },
     profession: { id: file.profession.id, instructions: file.profession.instructions },
     ...(file.model && {

package/src/config/yaml.ts

@@ -0,0 +1,60 @@
+import { isNode, LineCounter, parseDocument } from "yaml";
+import type { z } from "zod";
+import { OpenshainError } from "../errors.ts";
+
+/** Where a problem in a YAML file is, as `file:line:col path: message`. */
+export type Problem = (path: readonly PropertyKey[], message: string) => string;
+
+/**
+ * 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<T extends z.ZodType>(
+  text: string,
+  schema: T,
+  fileName: string,
+): { data: z.output<T>; problem: Problem } {
+  const lineCounter = new LineCounter();
+  let doc: ReturnType<typeof parseDocument>;
+  let data: unknown;
+  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 as Error).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: readonly PropertyKey[]): { line: number; col: number } => {
+    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: 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: string): string {
+  return message.split("\n", 1)[0] ?? message;
+}

package/src/index.ts

@@ -1,4 +1,28 @@
 // @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,
@@ -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 { businessDate, companyTime, hostTimezone, isTimezone } from "./time.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";
@@ -76,6 +104,7 @@ export {
   type ModelUsage,
   parsePayloadFile,
   payloadFileSchemas,
+  type ReviewPackage,
   type StopReason,
   TOOL_REJECTION_CODES,
   type ToolContent,
@@ -86,7 +115,9 @@ export {
   countToolCalls,
   type FailureReason,
   type HistoryCall,
+  type PendingApproval,
   type PendingQuestion,
+  pendingApprovals,
   pendingQuestions,
   type WorkHistory,
   workHistory,

package/src/runtime.ts

@@ -1,14 +1,25 @@
+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";
 import type { ModelProvider } from "./model/types.ts";
+import { businessDate } from "./time.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. */
@@ -31,6 +42,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 +86,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 +96,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 +106,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 +160,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 +182,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 +206,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(config.company.timezone),
+    });
+    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 +310,68 @@ 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 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/time.ts

@@ -0,0 +1,54 @@
+/**
+ * The company's clock. Every date the runtime judges against — a decision's effective days, a
+ * delegation's validity — is a date in the company's timezone, not in the host's. A workspace
+ * carried between a laptop in Tokyo and a container in UTC has to answer the same question the
+ * same way, so the timezone is part of the configuration rather than the environment.
+ */
+
+/** True when the name is a timezone this runtime knows (`Asia/Tokyo`, `UTC`, ...). */
+export function isTimezone(name: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: name });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The timezone of the machine, used when the configuration names none. */
+export function hostTimezone(): string {
+  const name = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  return name && isTimezone(name) ? name : "UTC";
+}
+
+/** The business date (`YYYY-MM-DD`) in the company's timezone. */
+export function businessDate(timezone: string, at: Date = new Date()): string {
+  // en-CA writes a date as YYYY-MM-DD.
+  return new Intl.DateTimeFormat("en-CA", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(at);
+}
+
+/** The moment as the company reads it: `2026-09-09T14:03:11+09:00`. */
+export function companyTime(timezone: string, at: Date = new Date()): string {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: timezone,
+    hour12: false,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    timeZoneName: "longOffset",
+  }).formatToParts(at);
+  const of = (type: Intl.DateTimeFormatPartTypes) =>
+    parts.find((part) => part.type === type)?.value ?? "";
+  // "GMT+09:00" for a zone with an offset, "GMT" for UTC itself.
+  const zone = of("timeZoneName").replace("GMT", "");
+  const hour = of("hour") === "24" ? "00" : of("hour");
+  return `${of("year")}-${of("month")}-${of("day")}T${hour}:${of("minute")}:${of("second")}${zone === "" ? "+00:00" : zone}`;
+}

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",
 ];