cortico 0.1.0

package/src/core/generation.ts

@@ -0,0 +1,118 @@
+import type { QuoteTime } from '../providers/pricebook.ts';
+import type { ModelSpec } from './types.ts';
+import type { Request, Response, StreamEvent, Usage } from '../protocol/open-responses/index.ts';
+import type { ContextRecord, ItemOrigin } from '../protocol/open-responses/context.ts';
+
+/** Missing meters remain null. Native details are retained for future reconciliation. */
+export interface TokenMeters {
+  input: number | null;
+  output: number | null;
+  total: number | null;
+  cachedInput: number | null;
+  uncachedInput: number | null;
+  reasoning: number | null;
+  details?: Record<string, { quantity: number | null; unit: string }>;
+  native: Record<string, unknown> | null;
+}
+export type Meter = Exclude<keyof TokenMeters, 'native' | 'details'> | `detail:${string}`;
+export interface PriceRule { meter: Meter; perMillion: number; unit?: string; }
+export interface PriceSnapshot {
+  id: string;
+  currency: string;
+  basis: 'marginal' | 'equivalent';
+  rules: PriceRule[];
+  inputBands?: Array<{ from: number; rules: PriceRule[] }>;
+  serviceTiers?: Record<string, { rules: PriceRule[]; inputBands?: Array<{ from: number; rules: PriceRule[] }> }>;
+  source: string;
+  capturedAt: string;
+}
+export interface Charge {
+  quote: PriceSnapshot;
+  amount: number | null;
+  knownAmount: number;
+  missing: Array<Meter | 'serviceTier'>;
+  lines: Array<{ meter: Meter; unit: string; quantity: number | null; perMillion: number; amount: number | null }>;
+}
+export interface ProviderAttempt {
+  id: string;
+  generationId: string;
+  ordinal: number;
+  origin: ItemOrigin;
+  startedAt: string;
+  elapsedMs: number;
+  requestId: string | null;
+  responseId: string | null;
+  outcome: 'completed' | 'incomplete' | 'failed' | 'aborted' | 'discarded';
+  status: number | null;
+  serviceTier: string | null;
+  requestedServiceTier?: string | null;
+  purpose?: 'generation' | 'diagnostic';
+  meters: TokenMeters;
+  charges: Charge[];
+}
+export interface GenerateOptions {
+  signal?: AbortSignal;
+  onEvent?: (event: StreamEvent) => void;
+  role?: string;
+  sessionId?: string;
+  /** Local context retains output reasoning and media references alongside the request Items. */
+  context?: readonly ContextRecord[];
+  nativeSpec?: ModelSpec;
+  origin?: ItemOrigin;
+  quote?: (at: QuoteTime) => readonly PriceSnapshot[];
+  /** Diagnostic requests use a single attempt and cannot recursively diagnose. */
+  diagnostic?: boolean;
+}
+export interface Generation {
+  response: Response;
+  origin: ItemOrigin;
+  attempts: ProviderAttempt[];
+}
+export interface ResponseClient {
+  respond(request: Request, options?: GenerateOptions): Promise<Generation>;
+  /** A fork captures its provider binding once, before its first request. */
+  bind?(): ResponseClient;
+}
+export class GenerationError extends Error {
+  constructor(message: string, readonly attempts: ProviderAttempt[], readonly partial: Response | null,
+    readonly origin: ItemOrigin, readonly status = 0, readonly body = '', options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'GenerationError';
+  }
+}
+export function unknownMeters(): TokenMeters {
+  return { input: null, output: null, total: null, cachedInput: null, uncachedInput: null, reasoning: null, native: null };
+}
+export function standardUsage(meters: TokenMeters): Usage | null {
+  const { input, output, total, cachedInput, reasoning } = meters;
+  if (input === null || output === null || total === null || cachedInput === null || reasoning === null) return null;
+  return { input_tokens: input, output_tokens: output, total_tokens: total,
+    input_tokens_details: { cached_tokens: cachedInput }, output_tokens_details: { reasoning_tokens: reasoning } };
+}
+export function priceUsage(meters: TokenMeters, quotes: readonly PriceSnapshot[], serviceTier: string | null = null): Charge[] {
+  return quotes.map(quote => {
+    const missing: Charge['missing'] = [];
+    let schedule: Pick<PriceSnapshot, 'rules' | 'inputBands'> = quote;
+    if (quote.serviceTiers) {
+      if (serviceTier === null || !quote.serviceTiers[serviceTier]) missing.push('serviceTier');
+      else schedule = quote.serviceTiers[serviceTier];
+    }
+    let rules = schedule.rules;
+    if (schedule.inputBands?.length) {
+      if (meters.input === null) missing.push('input');
+      else for (const band of schedule.inputBands) if (meters.input >= band.from) rules = band.rules;
+    }
+    const unresolvedSchedule = missing.length > 0;
+    const lines = rules.map(rule => {
+      const detail = rule.meter.startsWith('detail:') ? meters.details?.[rule.meter.slice(7)] : undefined;
+      const quantity = rule.meter.startsWith('detail:') ? detail?.quantity ?? null : meters[rule.meter as Exclude<Meter, `detail:${string}`>];
+      const unit = rule.unit ?? 'token';
+      const known = !unresolvedSchedule && (!detail || detail.unit === unit);
+      const amount = known && rule.perMillion === 0 ? 0 : known && quantity !== null ? quantity * rule.perMillion / 1e6 : null;
+      if (amount === null && !unresolvedSchedule) missing.push(rule.meter);
+      return { meter: rule.meter, unit, quantity, perMillion: rule.perMillion, amount };
+    });
+    const knownAmount = lines.reduce((sum, line) => sum + (line.amount ?? 0), 0);
+    return { quote: structuredClone(quote), amount: missing.length ? null : knownAmount, knownAmount, missing: [...new Set(missing)], lines };
+  });
+}

package/src/core/instance-lock.ts

@@ -0,0 +1,215 @@
+/**
+ * 单实例锁按 dataDir 隔离，防止同一数据目录被多个进程并发写入。
+ * 使用 wx 排他创建；陈旧锁通过临时文件、rename 和读回核对接管，竞争失败则拒绝启动。
+ * force 仅放行当前进程，不取得锁所有权，退出时不删除其他实例的锁。锁 startedAt 早于本机开机时刻时按陈旧锁处理，避免 PID 复用误判。
+ * verify 检测锁丢失或被接管并报告 error；丢失时补写，被接管时不争抢。
+ */
+import { closeSync, existsSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, writeSync } from 'node:fs';
+import { uptime } from 'node:os';
+import { join } from 'node:path';
+import type { Logger } from './types.ts';
+import { nullLogger } from './util.ts';
+
+export const INSTANCE_LOCK_FILE = 'instance.lock';
+
+const VERIFY_INTERVAL_MS = 60_000;
+
+interface LockPayload {
+  pid: number;
+  startedAt: string;
+  argv: string[];
+}
+
+export interface InstanceLock {
+  /** 锁文件路径(诊断用) */
+  readonly file: string;
+  /** 使用 force 跳过占用检查时不取得锁所有权。 */
+  readonly owns: boolean;
+  /**
+   * 锁缺失时尝试重写；所有权记录变化时仅报告。
+   * 同一异常状态只报一次，恢复后允许再次报告。
+   */
+  verify(): void;
+  /** 释放:只删自己写的那把锁 */
+  release(): void;
+}
+
+/** signal 0 检查进程存在性和权限，不发送实际信号。 */
+function isAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM 说明进程存在，但当前进程无权向其发送信号。
+    return (e as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/**
+ * 启动时刻早于本机开机时刻时，存活的同号 PID 也不视为原锁所有者。
+ * 无法解析启动时刻时仅检查 PID。
+ */
+function ownerStillRunning(p: LockPayload): boolean {
+  if (!isAlive(p.pid)) return false;
+  const startedAt = Date.parse(p.startedAt);
+  if (Number.isNaN(startedAt)) return true;
+  const bootedAt = Date.now() - uptime() * 1000;
+  return startedAt >= bootedAt;
+}
+
+function readPayload(file: string): LockPayload | null {
+  try {
+    const raw = JSON.parse(readFileSync(file, 'utf8')) as Partial<LockPayload>;
+    if (!Number.isInteger(raw.pid)) return null;
+    return {
+      pid: raw.pid as number,
+      startedAt: typeof raw.startedAt === 'string' ? raw.startedAt : '(未记录)',
+      argv: Array.isArray(raw.argv) ? raw.argv.map(String) : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** 排他创建；仅 EEXIST 返回 false，其他错误抛出。 */
+function createExclusive(file: string, payload: LockPayload): boolean {
+  let fd: number;
+  try {
+    fd = openSync(file, 'wx');
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'EEXIST') return false;
+    throw e;
+  }
+  try {
+    writeSync(fd, JSON.stringify(payload, null, 2), null, 'utf8');
+  } finally {
+    closeSync(fd);
+  }
+  return true;
+}
+
+/** 通过临时文件替换陈旧锁；读回 PID 核对所有权，替换或核对失败返回 false。 */
+function takeOver(file: string, payload: LockPayload): boolean {
+  const tmp = `${file}.${payload.pid}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
+    renameSync(tmp, file);
+  } catch {
+    try { rmSync(tmp); } catch { /* 临时文件删不掉不影响判定 */ }
+    return false;
+  }
+  return readPayload(file)?.pid === payload.pid;
+}
+
+/**
+ * 占用锁对应的进程仍存在时拒绝启动，错误包含 PID 与启动时刻。
+ * force 可跳过检查并记录错误；该进程不取得锁所有权，退出时不删除锁。
+ */
+export function acquireInstanceLock(
+  dataDir: string,
+  opts: { force?: boolean; log?: Logger } = {},
+): InstanceLock {
+  const log = opts.log ?? nullLogger();
+  const file = join(dataDir, INSTANCE_LOCK_FILE);
+  const mine: LockPayload = {
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    argv: process.argv.slice(1),
+  };
+
+  let owns = createExclusive(file, mine);
+  if (!owns) {
+    const existing = readPayload(file);
+    if (existing && ownerStillRunning(existing)) {
+      if (!opts.force) {
+        throw new Error(
+          `数据目录的锁记录指向运行中的进程(pid ${existing.pid},记录的启动时刻 ${existing.startedAt})。` +
+          `请检查锁记录及对应进程；需跳过占用检查时使用 --force-second-instance。锁文件:${file}`,
+        );
+      }
+      log.error("锁记录对应的进程仍存在；已按 --force-second-instance 跳过检查，未取得锁所有权", {
+        otherPid: existing.pid,
+        otherStartedAt: existing.startedAt,
+        file,
+      });
+    } else {
+      // 锁无法读取，或其记录不满足存活所有者条件。
+      owns = takeOver(file, mine);
+      if (owns) {
+        log.warn("已接管无法读取或已失效的实例锁", {
+          stalePid: existing?.pid ?? null,
+          staleStartedAt: existing?.startedAt ?? null,
+          unreadable: existing === null,
+          file,
+        });
+      } else {
+        // 替换或读回核对失败，当前进程未获得锁所有权。
+        const winner = readPayload(file);
+        if (!opts.force) {
+          throw new Error(
+            `未取得数据目录的锁所有权(当前锁记录 PID: ${winner?.pid ?? '未知'})。` +
+            `请检查锁记录及对应进程；需跳过占用检查时使用 --force-second-instance。锁文件:${file}`,
+          );
+        }
+        log.error("获取实例锁失败；已按 --force-second-instance 跳过检查，未取得锁所有权", {
+          otherPid: winner?.pid ?? null,
+          file,
+        });
+      }
+    }
+  }
+
+  let released = false;
+  /** 同一异常状态只报告一次；所有权恢复后重置。 */
+  let breachReported = false;
+
+  const verify = (): void => {
+    if (released || !owns) return;
+    const now = existsSync(file) ? readPayload(file) : null;
+    if (now?.pid === mine.pid) {
+      breachReported = false;
+      return;
+    }
+    if (breachReported) return;
+    breachReported = true;
+    if (now === null) {
+      // 缺失或无法读取的锁尝试重写，结果随日志报告。
+      const rewritten = createExclusive(file, mine) || takeOver(file, mine);
+      log.error("实例锁缺失或无法读取，已尝试重写；结果见 rewritten", {
+        file,
+        rewritten,
+      });
+      return;
+    }
+    // 不覆盖已变化的所有权记录。
+    log.error("实例锁的所有权记录已变化", {
+      minePid: mine.pid,
+      nowPid: now.pid,
+      nowStartedAt: now.startedAt,
+      file,
+    });
+  };
+
+  const timer = owns ? setInterval(verify, VERIFY_INTERVAL_MS) : null;
+  timer?.unref?.();
+
+  const release = (): void => {
+    if (released) return;
+    released = true;
+    if (timer) clearInterval(timer);
+    // 释放时移除退出钩子，避免重复获取锁时累积监听器。
+    process.off('exit', release);
+    if (!owns) return;
+    // 仅删除仍记录当前 PID 的锁。
+    const now = existsSync(file) ? readPayload(file) : null;
+    if (now?.pid !== mine.pid) return;
+    try {
+      rmSync(file);
+    } catch {
+      // 删除失败后由下次启动检查该锁。
+    }
+  };
+  process.on('exit', release);
+  return { file, owns, verify, release };
+}

package/src/core/ipc-logger.ts

@@ -0,0 +1,105 @@
+/**
+ * 子进程通过 IPC 发送 LogNote，父进程写入日志。
+ * 日志关联字段在子进程的异步作用域读取；时间使用子进程的 epoch 毫秒值，
+ * 由父进程按配置时区格式化。
+ */
+import type { LogAnchorFields, LogEmitOptions, LogError, Logger, LogLevel } from './types.ts';
+import { currentAnchors } from './log-context.ts';
+import { normalizeError, nowIso } from './util.ts';
+
+export interface LogNote extends LogAnchorFields {
+  kind: 'log';
+  level: LogLevel;
+  area: string;
+  msg: string;
+  event?: string;
+  durMs?: number;
+  data?: unknown;
+  err?: LogError;
+  /** 子进程侧的 epoch 毫秒 */
+  atMs: number;
+}
+
+const ANCHOR_KEYS = ['sess', 'round', 'resp', 'call', 'ev', 'task'] as const;
+
+export function createIpcLogger(send: (note: LogNote) => void, area = ''): Logger {
+  const emit = (level: LogLevel, msg: string, opts?: LogEmitOptions): void => {
+    const anchors = currentAnchors();
+    const note: LogNote = { kind: 'log', level, area, msg, atMs: Date.now() };
+    if (opts?.event !== undefined) note.event = opts.event;
+    if (opts?.durMs !== undefined) note.durMs = opts.durMs;
+    for (const key of ANCHOR_KEYS) {
+      const value = opts?.[key] ?? anchors[key];
+      if (value !== undefined) (note as unknown as Record<string, unknown>)[key] = value;
+    }
+    let data = opts?.data;
+    let err = opts?.err;
+    if (data instanceof Error) { err ??= data; data = undefined; }
+    else if (data && typeof data === 'object' && !Array.isArray(data)) {
+      const bag = data as Record<string, unknown>;
+      const carried = bag.err instanceof Error ? bag.err : bag.error instanceof Error ? bag.error : undefined;
+      if (carried) {
+        err ??= carried;
+        const { err: _e, error: _error, ...rest } = bag;
+        data = Object.keys(rest).length ? rest : undefined;
+      }
+    }
+    if (data !== undefined) {
+      try { JSON.stringify(data); } catch { data = String(data); }
+      note.data = data;
+    }
+    if (err !== undefined) note.err = normalizeError(err);
+    send(note);
+  };
+  return {
+    trace: (m, d) => emit('trace', m, { data: d }),
+    debug: (m, d) => emit('debug', m, { data: d }),
+    info: (m, d) => emit('info', m, { data: d }),
+    warn: (m, d) => emit('warn', m, { data: d }),
+    error: (m, d) => emit('error', m, { data: d }),
+    emit,
+    child: (sub) => createIpcLogger(send, area ? `${area}.${sub}` : sub),
+  };
+}
+
+/** 主进程侧:把子进程的 note 按原字段落到 World 的 logger 下。 */
+export function emitLogNote(root: Logger, note: LogNote, timezone: string): void {
+  const target = note.area ? root.child(note.area) : root;
+  const { kind: _kind, level, area: _area, msg, atMs, ...rest } = note;
+  target.emit(level, msg, { ...rest, ts: nowIso(timezone, new Date(atMs)) });
+}
+
+/** 把一个输出流按行落日志;跨 chunk 的半行拼起来,空行不记。 */
+export function logLines(
+  stream: NodeJS.ReadableStream | null | undefined,
+  log: Logger,
+  level: LogLevel,
+  event: string,
+): void {
+  if (!stream) return;
+  let carry = '';
+  stream.on('data', (chunk: Buffer | string) => {
+    const text = carry + chunk.toString();
+    const lines = text.split(/\r?\n/);
+    carry = lines.pop() ?? '';
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed) log.emit(level, trimmed, { event });
+    }
+  });
+  stream.on('end', () => {
+    const trimmed = carry.trim();
+    carry = '';
+    if (trimmed) log.emit(level, trimmed, { event });
+  });
+}
+
+/** sidecar 的 stdout / stderr 进运行日志:区域 `<World>.stdio`,stdout 记 debug、stderr 记 warn。 */
+export function logChildStdio(
+  child: { stdout?: NodeJS.ReadableStream | null; stderr?: NodeJS.ReadableStream | null },
+  log: Logger,
+): void {
+  const stdio = log.child('stdio');
+  logLines(child.stdout, stdio, 'debug', 'stdout');
+  logLines(child.stderr, stdio, 'warn', 'stderr');
+}

package/src/core/language.ts

@@ -0,0 +1,62 @@
+/**
+ * Console text uses the language supplied with each browser request.
+ * The initial default uses a recognized config.language, then CORTICO_LANGUAGE,
+ * then the system locale. Chinese locales select zh; other nonempty locales select en;
+ * an unavailable locale falls back to zh. The environment/locale result is cached once.
+ * The browser can override the initial <html lang> value and sends its choice in the
+ * console language header or query parameter. Panels receive ConsolePanelContext.language.
+ * Owners render request text in that language; missing translations use Chinese.
+ * This setting does not select or translate model-facing text.
+ */
+export type Language = 'zh' | 'en';
+
+export const LANGUAGES: readonly Language[] = ['zh', 'en'];
+
+export function isLanguage(value: unknown): value is Language {
+  return value === 'zh' || value === 'en';
+}
+
+/** BCP 47 / POSIX tag → language. Empty input is "unknown", not English. */
+export function languageOfLocale(tag: string | null | undefined): Language | undefined {
+  const t = (tag ?? '').trim().toLowerCase();
+  if (!t) return undefined;
+  return t === 'zh' || t.startsWith('zh-') || t.startsWith('zh_') ? 'zh' : 'en';
+}
+
+/** Pure form of the system read, for tests. */
+export function detectLanguage(
+  env: Record<string, string | undefined>,
+  locale: string | null | undefined,
+): Language {
+  const forced = env.CORTICO_LANGUAGE;
+  if (isLanguage(forced)) return forced;
+  return languageOfLocale(locale) ?? 'zh';
+}
+
+let systemMemo: Language | undefined;
+
+/** The environment/locale read, performed once and then fixed for the process lifetime. */
+export function systemLanguage(): Language {
+  if (systemMemo === undefined) {
+    // `process` is reached through globalThis so this file also type-checks under the DOM lib.
+    const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {};
+    let locale: string | undefined;
+    try {
+      locale = Intl.DateTimeFormat().resolvedOptions().locale;
+    } catch {
+      locale = undefined;
+    }
+    systemMemo = detectLanguage(env, locale);
+  }
+  return systemMemo;
+}
+
+/** A configured value wins over the system read; anything unrecognised is ignored. */
+export function resolveLanguage(configured: unknown): Language {
+  return isLanguage(configured) ? configured : systemLanguage();
+}
+
+/** Select a language table; the type requires English to have the same keys as Chinese. */
+export function pick<T>(language: Language, table: { readonly zh: T; readonly en: T }): T {
+  return language === 'en' ? table.en : table.zh;
+}

package/src/core/log-context.ts

@@ -0,0 +1,38 @@
+/** 轮次和工具调用边界设置日志关联字段；Logger 写入时从异步作用域读取。 */
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export interface LogAnchors {
+  /** session 声明 id。 */
+  sess?: string;
+  /** 主循环轮次,进程内单调 */
+  round?: number;
+  /** 本轮的 response id */
+  resp?: string;
+  /** 正在执行的 tool_call id */
+  call?: string;
+  /** 事件游标 */
+  ev?: number;
+  /** World 任务号 */
+  task?: number;
+}
+
+const storage = new AsyncLocalStorage<LogAnchors>();
+
+/** 在 fn 及其派生的异步操作中合并关联字段；新字段覆盖同名继承值。 */
+export function withAnchors<T>(anchors: LogAnchors, fn: () => T): T {
+  return storage.run({ ...storage.getStore(), ...anchors }, fn);
+}
+
+/** 修改最近一次 withAnchors 建立的作用域；没有作用域时不修改。 */
+export function setAnchors(patch: LogAnchors): void {
+  const current = storage.getStore();
+  if (!current) return;
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) delete (current as Record<string, unknown>)[key];
+    else (current as Record<string, unknown>)[key] = value;
+  }
+}
+
+export function currentAnchors(): LogAnchors {
+  return storage.getStore() ?? {};
+}