openshain 0.1.0

package/src/commands/run.ts

@@ -0,0 +1,137 @@
+import { pendingQuestions, runWork } from "@openshain/agent";
+import {
+  type AnyEvent,
+  createRuntime,
+  type Event,
+  type Runtime,
+  type RuntimeProviders,
+  type ToolContent,
+  type Work,
+  type WorkId,
+} from "@openshain/core";
+import { describeInput, truncate } from "../format.ts";
+import { failureLabel, rejectionLabel, statusLabel } from "../labels.ts";
+import { formatUsage, summarizeUsage } from "../usage.ts";
+
+export interface DriveOptions {
+  write: (line: string) => void;
+  /** Answers the model's questions. Without it, a question leaves the work waiting and the run ends. */
+  ask?: (question: string) => Promise<string>;
+  /** Stops the run. The work stays where it is and can be resumed. */
+  signal?: AbortSignal;
+}
+
+export interface RunOptions extends DriveOptions {
+  workspaceRoot: string;
+  providers: RuntimeProviders;
+  objective: string;
+}
+
+/** Creates a work for the request and drives it. Exit code 0 when the work completed. */
+export async function run(options: RunOptions): Promise<number> {
+  const runtime = await createRuntime({
+    workspaceRoot: options.workspaceRoot,
+    providers: options.providers,
+  });
+  const work = await runtime.works.create({
+    objective: options.objective,
+    principal: runtime.config.principal.id,
+    profession: runtime.config.profession.id,
+  });
+  options.write(`${work.id} を開始`);
+  return drive(runtime, work.id, options);
+}
+
+/** Drives a work from its current state, printing one line per tool call, and closes with the report. */
+export async function drive(
+  runtime: Runtime,
+  workId: WorkId,
+  options: DriveOptions,
+): Promise<number> {
+  const names = new Map<string, string>();
+  const done = await runWork(runtime, workId, {
+    ...(options.ask && { onInput: options.ask }),
+    ...(options.signal && { signal: options.signal }),
+    onEvent: (event) => {
+      const line = progressLine(event, names);
+      if (line) options.write(line);
+    },
+  });
+  const events = await runtime.works.events(workId);
+  for (const line of report(done, events)) options.write(line);
+  return done.status === "completed" ? 0 : 1;
+}
+
+/** One line for a tool call, a rejection or a failure; nothing for the other events. `names` maps call ids to tool names. */
+export function progressLine(event: AnyEvent, names: Map<string, string>): string | undefined {
+  switch (event.type) {
+    case "tool.called": {
+      const { callId, name, input } = (event as Event<"tool.called">).payload;
+      names.set(callId, name);
+      return `${name} ${describeInput(input)}`.trimEnd();
+    }
+    case "tool.rejected": {
+      const { name, code, reason } = (event as Event<"tool.rejected">).payload;
+      return `${name} は拒否されました。${rejectionLabel(code)}。${reason}`;
+    }
+    case "tool.completed": {
+      const { callId, content, isError } = (event as Event<"tool.completed">).payload;
+      if (!isError) return undefined;
+      return `${names.get(callId) ?? callId} は失敗しました。${truncate(firstLine(content))}`;
+    }
+    default:
+      return undefined;
+  }
+}
+
+function firstLine(content: ToolContent[]): string {
+  for (const part of content) {
+    if (part.type === "text") return part.text.split("\n")[0] ?? "";
+  }
+  return "";
+}
+
+/** The closing lines: what happened, what it cost, and who acts next. */
+export function report(work: Work, events: AnyEvent[]): string[] {
+  const lines: string[] = [];
+  switch (work.status) {
+    case "completed":
+      lines.push(`完了。${work.outcome?.summary ?? ""}`.trimEnd());
+      for (const artifact of work.outcome?.artifacts ?? []) {
+        lines.push(
+          `  書き込み ${artifact.path}${artifact.missing ? "  完了時には読めなかった" : ""}${artifact.claimed ? "  エージェントの申告(この Work の Tool は書いていない)" : ""}`,
+        );
+      }
+      break;
+    case "failed":
+      lines.push(
+        `失敗。${failureLabel(work.failure?.reason)}。${work.failure?.detail ?? ""}`.trimEnd(),
+      );
+      break;
+    case "waiting_input":
+      lines.push("利用者の入力を待っています。");
+      for (const { question } of pendingQuestions(events)) lines.push(`  質問 ${question}`);
+      break;
+    default:
+      lines.push(`状態は ${statusLabel(work.status)} です。`);
+  }
+  lines.push(formatUsage(summarizeUsage(events)));
+  lines.push(nextActor(work));
+  return lines;
+}
+
+export function nextActor(work: Work): string {
+  switch (work.status) {
+    case "completed":
+    case "cancelled":
+      return "次に動く人はいません。";
+    case "waiting_input":
+      return `次は利用者の番です。openshain work resume ${work.id} で質問に答えると続きます。`;
+    case "waiting_approval":
+      return "次は利用者の番です。承認が要ります。";
+    case "failed":
+      return "次は利用者の番です。原因を直して、もう一度依頼してください。";
+    default:
+      return "次は model の番です。";
+  }
+}

package/src/commands/tools.ts

@@ -0,0 +1,32 @@
+import { ASK_USER, RUNTIME_PROVIDER_ID } from "@openshain/agent";
+import { createToolRegistry, loadConfig, type RuntimeProviders } from "@openshain/core";
+
+export interface ToolsListOptions {
+  workspaceRoot: string;
+  providers: RuntimeProviders;
+  write: (line: string) => void;
+}
+
+/** Every tool the model can call in this workspace, and the ones the allow lists hide. Needs no model provider. */
+export async function toolsList({
+  workspaceRoot,
+  providers,
+  write,
+}: ToolsListOptions): Promise<void> {
+  const config = await loadConfig(workspaceRoot);
+  const registry = await createToolRegistry(workspaceRoot, config, providers.tools);
+  const rows: [string, string, string, string][] = registry
+    .list()
+    .map((t) => [t.definition.name, t.providerId, t.definition.effect, "許可"]);
+  rows.push([ASK_USER.name, RUNTIME_PROVIDER_ID, ASK_USER.effect, "許可"]);
+  for (const hidden of registry.hiddenTools()) {
+    rows.push([hidden.name, hidden.providerId, hidden.effect, "不許可"]);
+  }
+  const width = Math.max(...rows.map(([name]) => name.length));
+  const providerWidth = Math.max(...rows.map(([, provider]) => provider.length));
+  for (const [name, provider, effect, allowed] of rows) {
+    write(
+      `${name.padEnd(width)}  ${provider.padEnd(providerWidth)}  ${effect.padEnd(7)}  ${allowed}`,
+    );
+  }
+}

package/src/commands/work.ts

@@ -0,0 +1,137 @@
+import { pendingQuestions } from "@openshain/agent";
+import {
+  type AnyEvent,
+  createRuntime,
+  type Event,
+  isTerminal,
+  parseWorkId,
+  type RuntimeProviders,
+  SESSION_WORK_TYPE,
+  type Work,
+  WorkStore,
+} from "@openshain/core";
+import { describeInput, padDisplay } from "../format.ts";
+import { errorLabel, failureLabel, rejectionLabel, statusLabel } from "../labels.ts";
+import { formatUsage, summarizeUsage } from "../usage.ts";
+import { type DriveOptions, drive, nextActor } from "./run.ts";
+
+export interface WorkListOptions {
+  workspaceRoot: string;
+  write: (line: string) => void;
+}
+
+/** One line per work, oldest first. Works that cannot be read are reported, not hidden. */
+export async function workList({ workspaceRoot, write }: WorkListOptions): Promise<void> {
+  const { works, problems } = await new WorkStore(workspaceRoot).list();
+  if (works.length === 0 && problems.length === 0) {
+    write('Work はまだありません。openshain run "<依頼>" で始められます。');
+    return;
+  }
+  for (const work of works) {
+    write(
+      `${work.id}  ${padDisplay(statusLabel(work.status), 16)}  ${work.createdAt.slice(0, 16)}  ${shorten(work.objective)}`,
+    );
+  }
+  for (const { id, error } of problems) {
+    write(`${id}  読めない(${errorLabel(error.code) ?? error.code})  ${error.message}`);
+  }
+}
+
+export interface WorkShowOptions {
+  workspaceRoot: string;
+  id: string;
+  write: (line: string) => void;
+}
+
+/** Everything about one work: state, outcome, what the tools did, the usage, and who acts next. */
+export async function workShow({ workspaceRoot, id, write }: WorkShowOptions): Promise<void> {
+  const store = new WorkStore(workspaceRoot);
+  const workId = parseWorkId(id);
+  const work = await store.get(workId);
+  const events = await store.events(workId);
+  for (const line of describeWork(work, events)) write(line);
+}
+
+export function describeWork(work: Work, events: AnyEvent[]): string[] {
+  const lines = [
+    `${work.id}`,
+    `状態      ${statusLabel(work.status)}(${work.status})`,
+    `依頼      ${work.objective}`,
+    `作成      ${work.createdAt}`,
+  ];
+  if (work.agentName) lines.push(`名前      ${work.agentName}(社員エージェント)`);
+  if (work.startedAt) lines.push(`開始      ${work.startedAt}`);
+  if (work.completedAt) lines.push(`終了      ${work.completedAt}`);
+  if (work.outcome) {
+    lines.push(`結果      ${work.outcome.summary}`);
+    for (const artifact of work.outcome.artifacts)
+      lines.push(
+        `  書き込み ${artifact.path}  ${artifact.sha256.slice(0, 12)}${artifact.missing ? "  完了時には読めなかった" : ""}${artifact.claimed ? "  エージェントの申告(この Work の Tool は書いていない)" : ""}`,
+      );
+  }
+  if (work.failure) {
+    lines.push(`失敗      ${failureLabel(work.failure.reason)}。${work.failure.detail}`);
+  }
+  if (work.status === "waiting_input") {
+    for (const { question } of pendingQuestions(events)) lines.push(`質問      ${question}`);
+  }
+
+  const calls = toolLines(events);
+  if (calls.length > 0) {
+    lines.push("Tool");
+    for (const line of calls) lines.push(line);
+  }
+  lines.push(formatUsage(summarizeUsage(events)));
+  lines.push(nextActor(work));
+  return lines;
+}
+
+export interface WorkResumeOptions extends DriveOptions {
+  workspaceRoot: string;
+  providers: RuntimeProviders;
+  id: string;
+}
+
+/** Continues a work that stopped before its end, answering its questions when the caller can. */
+export async function workResume(options: WorkResumeOptions): Promise<number> {
+  const workId = parseWorkId(options.id);
+  const work = await new WorkStore(options.workspaceRoot).get(workId);
+  if (work.type === SESSION_WORK_TYPE) {
+    options.write(
+      `${work.id} は会話の記録のため、再開できません。会話は openshain で始め直してください。`,
+    );
+    return 1;
+  }
+  if (isTerminal(work.status)) {
+    options.write(`${work.id} は${statusLabel(work.status)}のため、再開できません。`);
+    return 1;
+  }
+  const runtime = await createRuntime({
+    workspaceRoot: options.workspaceRoot,
+    providers: options.providers,
+  });
+  return drive(runtime, workId, options);
+}
+
+/** One line per tool call, in log order, with its outcome when it was rejected or failed. */
+function toolLines(events: AnyEvent[]): string[] {
+  const lines = new Map<string, string>();
+  for (const event of events) {
+    if (event.type === "tool.called") {
+      const { callId, name, input } = (event as Event<"tool.called">).payload;
+      lines.set(callId, `  ${name} ${describeInput(input)}`.trimEnd());
+    } else if (event.type === "tool.rejected") {
+      const { callId, name, code } = (event as Event<"tool.rejected">).payload;
+      lines.set(callId, `${lines.get(callId) ?? `  ${name}`}  拒否(${rejectionLabel(code)})`);
+    } else if (event.type === "tool.completed") {
+      const { callId, isError } = (event as Event<"tool.completed">).payload;
+      if (isError) lines.set(callId, `${lines.get(callId) ?? `  ${callId}`}  失敗`);
+    }
+  }
+  return [...lines.values()];
+}
+
+function shorten(text: string): string {
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  return oneLine.length > 40 ? `${oneLine.slice(0, 39)}…` : oneLine;
+}

package/src/format.ts

@@ -0,0 +1,106 @@
+/** Display width in a terminal: East Asian wide and full-width characters take two columns. */
+export function displayWidth(text: string): number {
+  let width = 0;
+  for (const ch of text) width += isWide(ch.codePointAt(0) ?? 0) ? 2 : 1;
+  return width;
+}
+
+function isWide(code: number): boolean {
+  return (
+    (code >= 0x1100 && code <= 0x115f) ||
+    (code >= 0x2e80 && code <= 0xa4cf) ||
+    (code >= 0xac00 && code <= 0xd7a3) ||
+    (code >= 0xf900 && code <= 0xfaff) ||
+    (code >= 0xfe30 && code <= 0xfe4f) ||
+    (code >= 0xff00 && code <= 0xff60) ||
+    (code >= 0xffe0 && code <= 0xffe6) ||
+    (code >= 0x20000 && code <= 0x3fffd)
+  );
+}
+
+/** Pads with spaces to a display width, so columns line up with Japanese text in them. */
+export function padDisplay(text: string, width: number): string {
+  const missing = width - displayWidth(text);
+  return missing > 0 ? text + " ".repeat(missing) : text;
+}
+
+/** A tool input on one line: the path when there is one, nothing for a question, otherwise the JSON, shortened. */
+export function describeInput(input: unknown): string {
+  if (input && typeof input === "object") {
+    if ("path" in input) return String((input as { path: unknown }).path);
+    if ("question" in input) return "";
+  }
+  return truncate(JSON.stringify(input) ?? "");
+}
+
+export function truncate(text: string, max = 80): string {
+  return text.length > max ? `${text.slice(0, max - 3)}...` : text;
+}
+
+/**
+ * Text as it may reach a terminal: escape sequences and other control characters are dropped,
+ * newline and tab stay. Nothing a model says or a file contains can then move the cursor,
+ * retitle the window or write the clipboard. Invisible formatting characters (zero-width and
+ * bidirectional controls) go too, so a line cannot be made to read differently from what it is.
+ * A scan over the characters, not a regular expression, so the time is linear in the text.
+ */
+export function plain(text: string): string {
+  const chars = [...text];
+  let out = "";
+  let i = 0;
+  while (i < chars.length) {
+    const ch = chars[i] as string;
+    const code = ch.codePointAt(0) ?? 0;
+    if (code === ESC || code === CSI) i = afterSequence(chars, i);
+    else {
+      if (!isControl(code)) out += ch;
+      i += 1;
+    }
+  }
+  return out;
+}
+
+const ESC = 0x1b;
+const CSI = 0x9b;
+const BEL = 0x07;
+const ST = 0x9c;
+
+function isControl(code: number): boolean {
+  return (
+    (code < 0x20 && code !== 0x0a && code !== 0x09) ||
+    (code >= 0x7f && code <= 0x9f) ||
+    (code >= 0x200b && code <= 0x200f) ||
+    (code >= 0x202a && code <= 0x202e) ||
+    (code >= 0x2066 && code <= 0x2069) ||
+    code === 0xfeff
+  );
+}
+
+/** The index after the escape sequence that starts at `start`. An unfinished one runs to the end. */
+function afterSequence(chars: string[], start: number): number {
+  const at = (i: number) => chars[i]?.codePointAt(0) ?? -1;
+  const end = chars.length;
+  const opener = at(start) === CSI ? "[" : chars[start + 1];
+  let i = at(start) === CSI ? start + 1 : start + 2;
+  if (opener === "[") {
+    // CSI: parameter and intermediate bytes, then one final byte.
+    while (i < end && at(i) >= 0x20 && at(i) <= 0x3f) i += 1;
+    return Math.min(i + 1, end);
+  }
+  if (opener === "]" || opener === "P" || opener === "X" || opener === "^" || opener === "_") {
+    // OSC, DCS, SOS, PM, APC: a string that ends with BEL or ST.
+    while (i < end) {
+      if (at(i) === BEL || at(i) === ST) return i + 1;
+      if (at(i) === ESC && chars[i + 1] === "\\") return i + 2;
+      i += 1;
+    }
+    return end;
+  }
+  if (at(start + 1) >= 0x20 && at(start + 1) <= 0x2f) {
+    // Intermediate bytes, then one final byte.
+    while (i < end && at(i) >= 0x20 && at(i) <= 0x2f) i += 1;
+    return Math.min(i + 1, end);
+  }
+  // ESC and one final character.
+  return Math.min(i, end);
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+// openshain: Reference CLI agent for the openshain runtime
+export {
+  AGENTS_TEMPLATE,
+  CLAUDE_TEMPLATE,
+  CONFIG_TEMPLATE,
+  type InitOptions,
+  init,
+  MCP_TEMPLATE,
+} from "./commands/init.ts";
+export { type McpOptions, mcp } from "./commands/mcp.ts";
+export {
+  type DriveOptions,
+  drive,
+  nextActor,
+  type RunOptions,
+  report,
+  run,
+} from "./commands/run.ts";
+export { type ToolsListOptions, toolsList } from "./commands/tools.ts";
+export {
+  describeWork,
+  type WorkListOptions,
+  type WorkResumeOptions,
+  type WorkShowOptions,
+  workList,
+  workResume,
+  workShow,
+} from "./commands/work.ts";
+export {
+  ERROR_LABELS,
+  errorLabel,
+  FAILURE_LABELS,
+  failureLabel,
+  REJECTION_LABELS,
+  rejectionLabel,
+  STATUS_LABELS,
+  statusLabel,
+} from "./labels.ts";
+export { formatUsage, summarizeUsage, type UsageSummary } from "./usage.ts";
+export { findWorkspace } from "./workspace.ts";

package/src/labels.ts

@@ -0,0 +1,68 @@
+import type { FailureReason } from "@openshain/agent";
+import type { ErrorCode, ToolRejectionCode, WorkStatus } from "@openshain/core";
+
+/** The words shown for a work's status. The log keeps the original value. */
+export const STATUS_LABELS: Record<WorkStatus, string> = {
+  queued: "未着手",
+  in_progress: "進行中",
+  waiting_input: "利用者の入力待ち",
+  waiting_approval: "承認待ち",
+  waiting_external: "外部の応答待ち",
+  completed: "完了",
+  failed: "失敗",
+  cancelled: "取り消し",
+};
+
+/** Why a work failed, as a heading before the original detail. */
+export const FAILURE_LABELS: Record<FailureReason, string> = {
+  limit_reached: "上限到達",
+  model_refusal: "model の拒否",
+  model_error: "model のエラー",
+};
+
+/** Why a tool call was rejected, as a heading before the original reason. */
+export const REJECTION_LABELS: Record<ToolRejectionCode, string> = {
+  schema_mismatch: "schema に合わない入力",
+  unknown_tool: "知らない Tool",
+  not_allowed: "この workspace では不許可",
+  reserved_path: "予約されたパス",
+  outside_workspace: "workspace の外",
+  invalid_path: "不正なパス",
+};
+
+/** A heading for a runtime error, before the original message. */
+export const ERROR_LABELS: Record<ErrorCode, string> = {
+  auth: "認証の失敗",
+  network: "接続の失敗",
+  rate_limit: "呼び出し上限",
+  invalid_response: "解釈できない model の応答",
+  config: "設定の問題",
+  corrupt_log: "壊れた Work の記録",
+  invalid_transition: "進められない状態",
+  duplicate_tool: "同じ名前の Tool の重複",
+  invalid_id: "不正な id",
+  invalid_tool: "不正な Tool の定義",
+  invalid_path: "不正なパス",
+  lock_held: "別のプロセスが使用中",
+  not_found: "対象なし",
+  reserved_path: "予約されたパス",
+  outside_workspace: "workspace の外",
+  concurrent_write: "同時書き込み",
+  invalid_event: "記録できないイベント",
+};
+
+export function statusLabel(status: string): string {
+  return (STATUS_LABELS as Record<string, string>)[status] ?? status;
+}
+
+export function failureLabel(reason: string | undefined): string {
+  return reason ? ((FAILURE_LABELS as Record<string, string>)[reason] ?? reason) : "理由は不明";
+}
+
+export function rejectionLabel(code: string): string {
+  return (REJECTION_LABELS as Record<string, string>)[code] ?? code;
+}
+
+export function errorLabel(code: string): string | undefined {
+  return (ERROR_LABELS as Record<string, string>)[code];
+}