@openshain/core 0.2.0 → 0.4.0

package/dist/work/events.js

@@ -7,6 +7,9 @@ export const TOOL_REJECTION_CODES = [
     "reserved_path",
     "outside_workspace",
     "invalid_path",
+    "limit_reached",
+    "denied",
+    "rejected_by_person",
 ];
 // ---------------------------------------------------------------------------
 // File-side schemas (snake_case). These are the on-disk contract.
@@ -82,7 +85,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", [
         z.looseObject({
             kind: z.literal("model_inference"),
@@ -202,6 +245,20 @@ export function eventFromFile(input) {
         payload: payloadFromFile(file.type, payload.data),
     };
 }
+/**
+ * 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(type, payload) {
+    const parsed = payloadFileSchemas[type].safeParse(payload);
+    if (!parsed.success) {
+        throw new OpenshainError("invalid_event", `${type} payload: ${describeIssues(parsed.error)}`);
+    }
+    return payloadFromFile(type, parsed.data);
+}
+export function isKnownEventType(type) {
+    return isKnownType(type);
+}
 function isKnownType(type) {
     return Object.hasOwn(payloadFileSchemas, type);
 }
@@ -325,6 +382,95 @@ const codecs = {
         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"
             ? { kind: p.kind, provider: p.provider, usage: { duration_ms: p.usage.durationMs } }

package/dist/work/history.d.ts

@@ -0,0 +1,57 @@
+import type { AnyEvent } from "./events.ts";
+/** Why a client gives up on a work, as recorded in `work.failed`. */
+export type FailureReason = "limit_reached" | "model_refusal" | "model_error";
+/**
+ * Counts the tool calls of a work the way the limits do: every call the runtime started, plus
+ * every rejection that never became a call. A rejection of a started call is not a second call.
+ */
+export declare function countToolCalls(events: readonly AnyEvent[]): number;
+export interface PendingQuestion {
+    callId: string;
+    question: string;
+}
+/**
+ * The questions of the work that have no answer yet, oldest first. Call ids of questions are
+ * minted by the runtime, so the whole log is searched: a client recording its own model turns
+ * must not hide a question.
+ */
+export declare function pendingQuestions(events: readonly AnyEvent[]): PendingQuestion[];
+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 declare function pendingApprovals(events: readonly AnyEvent[]): PendingApproval[];
+export interface HistoryCall {
+    callId: string;
+    name: string;
+    /** The path the call named, when its input had one. */
+    path?: string;
+    /** Present once the call has a result; absent while it is still open. */
+    isError?: boolean;
+    rejected?: string;
+}
+export interface WorkHistory {
+    calls: HistoryCall[];
+    /** 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;
+}
+/** What a client needs to pick a work up where it stopped. Built from the log alone. */
+export declare function workHistory(events: readonly AnyEvent[]): WorkHistory;

package/dist/work/history.js

@@ -0,0 +1,81 @@
+/**
+ * Counts the tool calls of a work the way the limits do: every call the runtime started, plus
+ * every rejection that never became a call. A rejection of a started call is not a second call.
+ */
+export function countToolCalls(events) {
+    let count = 0;
+    let started = new Set();
+    for (const event of events) {
+        if (event.type === "model.completed")
+            started = new Set();
+        else if (event.type === "tool.called") {
+            started.add(event.payload.callId);
+            count += 1;
+        }
+        else if (event.type === "tool.rejected") {
+            if (!started.has(event.payload.callId))
+                count += 1;
+        }
+    }
+    return count;
+}
+/**
+ * The questions of the work that have no answer yet, oldest first. Call ids of questions are
+ * minted by the runtime, so the whole log is searched: a client recording its own model turns
+ * must not hide a question.
+ */
+export function pendingQuestions(events) {
+    const answered = new Set(events
+        .filter((e) => e.type === "human.input_provided")
+        .map((e) => e.payload.callId));
+    return events
+        .filter((e) => e.type === "human.input_requested")
+        .filter((e) => !answered.has(e.payload.callId))
+        .map((e) => ({ callId: e.payload.callId, question: e.payload.question }));
+}
+/** The approvals of the work that have no decision yet, oldest first. */
+export function pendingApprovals(events) {
+    const decided = new Set(events
+        .filter((e) => e.type === "approval.decided")
+        .map((e) => e.payload.approvalId));
+    return events
+        .filter((e) => e.type === "approval.requested")
+        .filter((e) => !decided.has(e.payload.approvalId))
+        .map((e) => ({ ...e.payload }));
+}
+/** What a client needs to pick a work up where it stopped. Built from the log alone. */
+export function workHistory(events) {
+    const calls = [];
+    const byId = new Map();
+    for (const event of events) {
+        if (event.type === "tool.called") {
+            const { callId, name, input } = event.payload;
+            const path = input?.path;
+            const call = { callId, name, ...(typeof path === "string" && { path }) };
+            calls.push(call);
+            byId.set(callId, call);
+        }
+        else if (event.type === "tool.completed") {
+            const { callId, isError } = event.payload;
+            const call = byId.get(callId);
+            if (call)
+                call.isError = isError;
+        }
+        else if (event.type === "tool.rejected") {
+            const { callId, name, code } = event.payload;
+            const call = byId.get(callId);
+            if (call)
+                call.rejected = code;
+            else
+                calls.push({ callId, name, rejected: code });
+        }
+    }
+    return {
+        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/dist/work/projection.js

@@ -12,12 +12,24 @@ export function buildProjection(input) {
     const agentName = first?.type === "work.created" ? first.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 = [];
     const pushUserPart = (part) => {
@@ -39,6 +51,9 @@ export function buildProjection(input) {
             case "human.message":
                 pushUserPart({ type: "text", text: event.payload.text });
                 break;
+            case "prompt.expanded":
+                pushUserPart({ type: "text", text: event.payload.text });
+                break;
             case "model.completed": {
                 const content = event.payload.content
                     .filter((part) => part.type !== "opaque" || part.provider === input.providerId)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openshain/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Contracts (provider interfaces), fundamental objects, and the work runtime",
   "keywords": [
     "openshain",
@@ -30,7 +30,8 @@
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "exports": {
     ".": {