@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/capabilities/incident-log.js

@@ -1,100 +1,170 @@
-import { appendFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+/**
+ * 进程级事故日志(D-NEW):同步、durable 的 JSONL 诊断记录。
+ *
+ * `uncaughtExceptionMonitor` 只观察 fatal 事故并留下证据；宿主仍决定
+ * 是否退出。GoTry 不吞掉 fatal 事件、不调用 process.exit、也不隐式重启。
+ * 工具 execute 的业务失败仍由 guardToolExecute 转成结构化失败返回。
+ *
+ * §11 状态面同步:事故日志是 gotry-state/incidents.jsonl,
+ * 用户可见、可清理。
+ */
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { pathToFileURL } from 'node:url';
+/** 解析 gotry-state 绝对路径(stateRoot 可相对也可绝对) */
 export function resolveIncidentsPath(stateRoot, filename = 'incidents.jsonl') {
-    const root = isAbsolute(stateRoot) ? stateRoot : join(process.cwd(), stateRoot);
+    const root = isAbsolute(stateRoot)
+        ? stateRoot
+        : join(process.cwd(), stateRoot);
     return join(root, 'gotry-state', filename);
 }
 function ensureDir(path) {
     const dir = dirname(path);
-    if (!existsSync(dir)) mkdirSync(dir, {
-        recursive: true
-    });
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
 }
 let installed = false;
 let logPath = null;
+let activeMonitor = null;
+function safeErrorMessage(value) {
+    try {
+        if (value instanceof Error)
+            return typeof value.message === 'string' ? value.message : '[error-without-message]';
+        if (typeof value === 'string')
+            return value;
+        if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint' || typeof value === 'symbol')
+            return String(value);
+        const json = JSON.stringify(value);
+        return typeof json === 'string' ? json : '[unprintable-error]';
+    }
+    catch {
+        return '[unprintable-error]';
+    }
+}
+function safeErrorStack(value) {
+    try {
+        const stack = value?.stack;
+        return typeof stack === 'string' ? stack : '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * 写入一条事故并 fsync。整个 append 使用同一个 fd，并保证所有失败路径
+ * 都尝试 close；返回 true 只表示写入、fsync、close 全部成功。
+ */
 export function recordIncident(inc, stateRoot) {
-    const target = stateRoot ? resolveIncidentsPath(stateRoot) : logPath ?? resolveIncidentsPath('.');
+    const target = stateRoot ? resolveIncidentsPath(stateRoot) : (logPath ?? resolveIncidentsPath('.'));
+    let fd;
+    let closeAttempted = false;
     try {
         ensureDir(target);
-        appendFileSync(target, JSON.stringify(inc) + '\n', {
-            flag: 'a'
-        });
-        const fd = require('node:fs').openSync(target, 'a');
-        require('node:fs').fsyncSync(fd);
-        require('node:fs').closeSync(fd);
+        fd = openSync(target, 'a');
+        writeFileSync(fd, JSON.stringify(inc) + '\n', { encoding: 'utf8' });
+        fsyncSync(fd);
+        closeAttempted = true;
+        closeSync(fd);
+        fd = undefined;
         return true;
-    } catch  {
+    }
+    catch {
+        // 事故处理中的诊断失败绝不能再次抛出。
         return false;
     }
+    finally {
+        if (fd !== undefined && !closeAttempted) {
+            closeAttempted = true;
+            try {
+                closeSync(fd);
+            }
+            catch { /* best effort close on a failed write */ }
+        }
+    }
 }
+/**
+ * 安装进程级事故观察器。只挂 monitor，不改变 Node/dsh 的 fatal 行为。
+ * 进程整个生命周期仅生效一次；disposer 供宿主卸载和测试使用。
+ */
 export function installProcessGuards(stateRoot, labels) {
-    if (installed) return ()=>{};
+    if (installed)
+        return () => { };
     installed = true;
     logPath = resolveIncidentsPath(stateRoot);
-    const uncaughtHandler = (err, origin)=>{
-        recordIncident({
-            ts: new Date().toISOString(),
-            kind: 'uncaughtException',
-            message: (err?.message ?? String(err)).slice(0, 2000),
-            stack: (err?.stack ?? '').slice(0, 4000),
-            source: labels?.uncaughtException ?? String(origin)
-        }, stateRoot);
-    };
-    const rejectionHandler = (reason, promise)=>{
-        const msg = reason instanceof Error ? reason.message : String(reason);
-        const stack = reason instanceof Error ? reason.stack ?? '' : '';
-        recordIncident({
-            ts: new Date().toISOString(),
-            kind: 'unhandledRejection',
-            message: msg.slice(0, 2000),
-            stack: stack.slice(0, 4000),
-            source: labels?.unhandledRejection ?? 'promise'
-        }, stateRoot);
+    const monitor = (err, origin) => {
+        try {
+            const kind = origin === 'unhandledRejection' ? 'unhandledRejection' : 'uncaughtException';
+            const source = kind === 'unhandledRejection'
+                ? (labels?.unhandledRejection ?? 'promise')
+                : (labels?.uncaughtException ?? origin);
+            recordIncident({
+                ts: new Date().toISOString(),
+                kind,
+                message: safeErrorMessage(err).slice(0, 2000),
+                stack: safeErrorStack(err).slice(0, 4000),
+                source,
+            }, stateRoot);
+        }
+        catch {
+            // Formatting must never replace the original fatal event. Keep a final
+            // plain fallback attempt for diagnostics, while the host retains control.
+            try {
+                recordIncident({
+                    ts: new Date().toISOString(),
+                    kind: origin === 'unhandledRejection' ? 'unhandledRejection' : 'uncaughtException',
+                    message: '[incident-observer-fallback]',
+                    source: 'incident-observer',
+                }, stateRoot);
+            }
+            catch { /* observer is strictly best effort */ }
+        }
     };
-    process.on('uncaughtException', uncaughtHandler);
-    process.on('unhandledRejection', rejectionHandler);
-    return ()=>{
-        process.off('uncaughtException', uncaughtHandler);
-        process.off('unhandledRejection', rejectionHandler);
+    process.on('uncaughtExceptionMonitor', monitor);
+    activeMonitor = monitor;
+    let active = true;
+    return () => {
+        if (!active)
+            return;
+        active = false;
+        if (activeMonitor !== monitor)
+            return;
+        process.off('uncaughtExceptionMonitor', monitor);
         installed = false;
+        logPath = null;
+        activeMonitor = null;
     };
 }
+/**
+ * 工具执行面异常隔离(D-NEW gotry 侧收尾):dsh 的一个工具 execute 抛错/拒绝
+ * 会沿 cordis 传到主循环,拖垮整个会话。包装后:降级为结构化错误返回给 LLM、
+ * 事故落盘,永不向上抛。落盘失败也不抛(双保险,仍返回结构化错误)。
+ */
 export function guardToolExecute(name, stateRoot, execute) {
-    return async (args, exec)=>{
+    return async (args, exec) => {
         try {
             return await execute(args, exec);
-        } catch (e) {
-            const err = e instanceof Error ? e : new Error(String(e));
+        }
+        catch (e) {
+            const message = safeErrorMessage(e);
             recordIncident({
                 ts: new Date().toISOString(),
                 kind: 'tool_execute_error',
-                message: `${name}: ${err.message}`.slice(0, 2000),
-                stack: (err.stack ?? '').slice(0, 4000),
-                source: name
+                message: `${name}: ${message}`.slice(0, 2000),
+                stack: safeErrorStack(e).slice(0, 4000),
+                source: name,
             }, stateRoot);
             const failure = {
                 ok: false,
-                summary: `gotry_${name} 内部错误(已隔离,会话继续): ${err.message.slice(0, 300)}`,
-                evidence: `[incident:tool_execute_error@${new Date().toISOString()}]`
+                summary: `gotry_${name} 内部错误(已隔离,会话继续): ${message.slice(0, 300)}`,
+                evidence: `[incident:tool_execute_error@${new Date().toISOString()}]`,
             };
             return failure;
         }
     };
 }
-if (import.meta.url === `file://${fileURLToPath(import.meta.url)}` && process.argv[2] === '--smoke') {
+/** CLI 调试:最小 fatal 子进程会留下事故证据并按 Node 原生语义非零退出。 */
+if (process.argv[1] !== undefined && pathToFileURL(process.argv[1]).href === import.meta.url && process.argv[2] === '--smoke') {
     const stateRoot = process.argv[3] ?? '.';
-    installProcessGuards(stateRoot, {
-        uncaughtException: 'smoke',
-        unhandledRejection: 'smoke'
-    });
-    writeFileSync(resolveIncidentsPath(stateRoot) + '.smoke', 'ok');
-    setTimeout(()=>Promise.reject(new Error('intentional smoke-rejection')), 50);
-    setTimeout(()=>{
-        console.log('SMOKE OK');
-        process.exit(0);
-    }, 500);
+    installProcessGuards(stateRoot, { uncaughtException: 'smoke', unhandledRejection: 'smoke' });
+    setTimeout(() => { throw new Error('intentional smoke-uncaught'); }, 50);
 }
-
-
-//# sourceURL=ts/capabilities/incident-log.ts

package/dist/capabilities/model-override.js

@@ -1,18 +1,38 @@
+/**
+ * LLM_MODEL 会话面覆盖(issue #77)。
+ *
+ * dsh settings 分层:schema 默认 < composition 配置(cordis patch)< 用户层
+ *(~/.dsh/settings.yaml)。bin/gotry-inner.js 已把 LLM_MODEL 注入 composition
+ * 层(agent-default-model 默认模型 + llm-deepseek 目录),但用户在 dsh web UI
+ * 选过模型时,用户层压过 composition 层——单靠 patch,.env 承诺仍落空。
+ *
+ * 这里在 agent/request 瀑布(dsh-agent-loop 每次发起 LLM 请求前解析
+ * provider/model 的闸口,dsh-agent installModelSelection 也在此处施加选择)挂
+ * 监听,post-next 覆盖 provider/model:本插件随 cordis patch 在根组装载,先于
+ * 任何 agent 创建;瀑布按注册序嵌套(先注册 = 最外层,post-next 最后生效),
+ * 因此显式 .env 意图压过一切持久层选择。内存态零持久化,进程退即散,不改写
+ * 用户 ~/.dsh 设置。
+ *
+ * GOTRY_LLM_MODEL 未设置时不挂监听:默认路径(组合配置或用户 web 设置)面不变。
+ *
+ * @module gotry/capabilities/model-override
+ */
 export const MODEL_OVERRIDE_ENV = 'GOTRY_LLM_MODEL';
+/**
+ * 挂载模型覆盖;返回是否实际挂载(未设环境变量或 ctx 无事件总线时为 false)。
+ * provider 固定 deepseek-official:llm-deepseek 是 gotry 组合里唯一持有
+ * DEEPSEEK_API_KEY/DEEPSEEK_BASE_URL 映射凭证的 provider 路由。
+ */
 export function installModelOverride(ctx, env = process.env) {
     const model = env[MODEL_OVERRIDE_ENV];
-    if (!model || typeof ctx.on !== 'function') return false;
-    ctx.on('agent/request', async (_payload, next)=>{
+    if (!model || typeof ctx.on !== 'function')
+        return false;
+    ctx.on('agent/request', async (_payload, next) => {
         const resolved = await next();
+        // 与 installModelSelection 同语义:选中项无 effort 时清掉继承值,回落
+        // provider 默认推理档——不把上一个模型的 effort 错配到被覆盖的模型上
         const { reasoningEffort: _inherited, ...rest } = resolved;
-        return {
-            ...rest,
-            provider: 'deepseek-official',
-            model
-        };
+        return { ...rest, provider: 'deepseek-official', model };
     });
     return true;
 }
-
-
-//# sourceURL=ts/capabilities/model-override.ts

package/dist/capabilities/opensky.js

@@ -1,33 +1,46 @@
+/**
+ * OpenSky 实时观测桥(免费匿名,~400 credits/天,~4 req/s burst):
+ * 查某 callsign 的飞机是否在 ADS-B 网络的当前观测里——航线层的实时印证。
+ *
+ * 契约(与 weather.ts / hbcli.ts 同构):
+ *   - 永不抛错:网络失败/超时/解析失败一律降级返回;
+ *   - 三值语义:命中=强肯定;查空≠证伪(ADS-B 覆盖有限,降权不排除);服务不可用=无结论;
+ *   - 证据链:成功 [实时API:opensky@ts];失败 [实时API:opensky@error@ts]。
+ *
+ * 接口面(2026-08 实际可达,匿名路径):
+ *   GET /api/states/all  — 当前全球 ADS-B 状态,~10000 架
+ *   GET /api/states/all?icao24=<hex>  — 单飞机
+ *   /api/flights/airport 历史查 = 需鉴权(匿名 403)
+ *
+ * 数据意义:与 OpenFlights 骨架(通航性)+ 静态班次包(班期时刻) 三值互补——
+ *   OpenFlights = 历史上是否通航过(offline)
+ *   flights_2026.json = 调研估算的班次时刻
+ *   OpenSky = 该 callsign 的飞机「现在」是否在观测网络里(实时刻正飞)
+ *
+ * v0.0.1-rc.3 +: 之前是 scripts/opensky-check.ts 一次性 CLI(M2 时设计为 7 天窗
+ * 历史校验,但匿名路径实际不可达),现升级为能力层封装 + dsh 插件工具。
+ */
 const BASE = 'https://opensky-network.org/api';
 async function fetchOpenSky(url, timeoutMs) {
     const ctrl = new AbortController();
-    const timer = setTimeout(()=>ctrl.abort(), timeoutMs);
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
     try {
         const res = await fetch(url, {
             signal: ctrl.signal,
-            headers: {
-                Accept: 'application/json',
-                'User-Agent': 'gotry/0.0.1-rc.3 (+https://github.com/Danceiny/gotry)'
-            }
+            headers: { Accept: 'application/json', 'User-Agent': 'gotry/0.0.1-rc.3 (+https://github.com/Danceiny/gotry)' },
         });
-        if (!res.ok) return {
-            ok: false,
-            error: `opensky HTTP ${res.status}${res.status === 429 ? ' (rate limited, 400 credits/day anonymous)' : ''}`
-        };
-        return {
-            ok: true,
-            data: await res.json()
-        };
-    } catch (e) {
-        return {
-            ok: false,
-            error: e.message.slice(0, 200)
-        };
-    } finally{
+        if (!res.ok)
+            return { ok: false, error: `opensky HTTP ${res.status}${res.status === 429 ? ' (rate limited, 400 credits/day anonymous)' : ''}` };
+        return { ok: true, data: await res.json() };
+    }
+    catch (e) {
+        return { ok: false, error: e.message.slice(0, 200) };
+    }
+    finally {
         clearTimeout(timer);
     }
 }
-const upper = (s)=>s.trim().toUpperCase();
+const upper = (s) => s.trim().toUpperCase();
 export async function verifyFlight(query) {
     const started = Date.now();
     const ts = new Date().toISOString();
@@ -38,37 +51,35 @@ export async function verifyFlight(query) {
     if (!r.ok) {
         return {
             verdict: 'unavailable',
-            callsign: cs,
-            airport,
-            sampleSize: 0,
-            hits: [],
+            callsign: cs, airport,
+            sampleSize: 0, hits: [],
             evidence: `[实时API:opensky@error@${ts}] ${r.error}`,
             via: 'opensky-error',
-            latencyMs,
-            error: r.error
+            latencyMs, error: r.error,
         };
     }
+    // /api/states/all → { time, states: Array<17 元素数组> }
+    // [0 icao24, 1 callsign, 2 origin_country, 3 time_position, 4 last_contact,
+    //  5 lon, 6 lat, 7 baro_altitude, 8 on_ground, ...]
     const rawStates = (r.data ?? {}).states ?? [];
-    const observed = rawStates.filter((row)=>(row[1] ?? '').trim().toUpperCase().includes(cs)).map((row)=>({
-            icao24: String(row[0] ?? ''),
-            callsign: (row[1] ?? '').trim() || null,
-            lastSeen: Number(row[4] ?? 0),
-            firstSeen: Number(row[4] ?? 0),
-            estArrivalAirport: airport
-        }));
+    const observed = rawStates
+        .filter(row => (row[1] ?? '').trim().toUpperCase().includes(cs))
+        .map(row => ({
+        icao24: String(row[0] ?? ''),
+        callsign: (row[1] ?? '').trim() || null,
+        lastSeen: Number(row[4] ?? 0),
+        firstSeen: Number(row[4] ?? 0),
+        estArrivalAirport: airport,
+    }));
     const verdict = observed.length > 0 ? 'observed' : 'not_observed';
-    const evidence = observed.length > 0 ? `[实时API:opensky@${ts}] ✅ 全球 ADS-B 当前观测命中 ${cs} (${observed.length} 架)` : `[实时API:opensky@${ts}] ○ 当前 ADS-B 全球观测列表未见 ${cs}(ADS-B 覆盖有限,不作否定结论)`;
+    const evidence = observed.length > 0
+        ? `[实时API:opensky@${ts}] ✅ 全球 ADS-B 当前观测命中 ${cs} (${observed.length} 架)`
+        : `[实时API:opensky@${ts}] ○ 当前 ADS-B 全球观测列表未见 ${cs}(ADS-B 覆盖有限,不作否定结论)`;
     return {
-        verdict,
-        callsign: cs,
-        airport,
+        verdict, callsign: cs, airport,
         sampleSize: rawStates.length,
-        hits: observed,
-        evidence,
+        hits: observed, evidence,
         via: 'opensky',
-        latencyMs
+        latencyMs,
     };
 }
-
-
-//# sourceURL=ts/capabilities/opensky.ts

package/dist/capabilities/resilience.js

@@ -1,23 +1,45 @@
+/**
+ * 外部依赖韧性原语(issue #16 采纳,ADR-18):effect_interpreter.v1 解译器层的横切面。
+ *
+ * 对外通道的三类故障形态在此归一一处,能力层 handler(永不抛错契约)零改写:
+ *   - 指数退避重试 withRetry:只对「瞬时类失败」按策略重试,不改变单次失败语义;
+ *   - 断路器 CircuitBreaker:closed→open→half-open,连续失败达阈值即熔断,
+ *     冷却后放行单探测——保护配额与上游,拒绝也是显式结构化观察(不抛错);
+ *
+ * 策略边界(issue #16 三个解译器主张在本仓的保守落法,详见 docs/design/effect-interpreter.md):
+ *   - 重试只属于被判定「值得重试」的瞬时失败;风控/挑战/限流类上游明确说「不」的
+ *     失败(如 FlyAI Sentinel)永不重试——重试是放大器,不是修复器;
+ *   - 断路器状态是进程内瞬态(同 session-search 节律闸的先例),重启即重置;
+ *     不把瞬态熔断写盘成持久资产。
+ */
+/** 第 failedAttempt 次失败后的等待时长(纯函数,单测锁定 500→1000→2000 封顶链) */
 export function backoffDelayMs(policy, failedAttempt) {
     const raw = policy.baseDelayMs * 2 ** (Math.max(1, failedAttempt) - 1);
     return Math.min(raw, policy.maxDelayMs);
 }
-const defaultSleep = (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * 带指数退避的受控重试:handler 本身永不抛错(能力层契约),这里兼容抛错的
+ * 「裸调用方」——异常按 isRetryable(result=null, error) 判定后并入同一计数。
+ * 重试只针对瞬时失败;上限到点即返回最后结果,永不向上抛。
+ */
 export async function withRetry(fn, policy, onBackoff) {
     const sleep = policy.sleep ?? defaultSleep;
     const maxAttempts = Math.max(1, policy.maxAttempts);
     let attempts = 0;
     let backoffMs = 0;
-    for(;;){
+    for (;;) {
         attempts += 1;
         let result = null;
         let error = null;
         try {
             result = await fn();
-        } catch (e) {
+        }
+        catch (e) {
             error = e;
         }
-        const retryable = policy.isRetryable?.(result, error) ?? (error != null || result?.ok === false);
+        const retryable = policy.isRetryable?.(result, error)
+            ?? (error != null || result?.ok === false);
         if (attempts < maxAttempts && retryable) {
             const delay = backoffDelayMs(policy, attempts);
             onBackoff?.(attempts, delay);
@@ -25,20 +47,22 @@ export async function withRetry(fn, policy, onBackoff) {
             await sleep(delay);
             continue;
         }
-        return {
-            result,
-            error,
-            attempts,
-            backoffMs
-        };
+        return { result, error, attempts, backoffMs };
     }
 }
+/**
+ * 断路器(每效应一个实例):
+ *   closed    常态放行;连续失败达 failureThreshold → open;
+ *   open      拒绝(new attempts=0,.fail-fast 保护上游/配额);冷却满 openMs → half-open;
+ *   half-open 仅放行单个探测:onSuccess → closed 清零;onFailure → 重新 open(冷却重启)。
+ * 「失败」按效应的 isFailure 语义计数(一次调用一次计数,重试耗尽才计,非每 attempt)。
+ */
 export class CircuitBreaker {
     o;
     consecutiveFailures = 0;
     openedAt = 0;
     probeInFlight = false;
-    constructor(o){
+    constructor(o) {
         this.o = o;
     }
     threshold() {
@@ -48,35 +72,32 @@ export class CircuitBreaker {
         return (this.o.now ?? Date.now)();
     }
     state() {
-        if (this.openedAt > 0 && this.now() - this.openedAt >= this.o.openMs) return 'half-open';
-        if (this.openedAt > 0) return 'open';
+        if (this.openedAt > 0 && this.now() - this.openedAt >= this.o.openMs)
+            return 'half-open';
+        if (this.openedAt > 0)
+            return 'open';
         return 'closed';
     }
+    /** 发起一次调用前问闸:open 回 {allowed:false}(调用方须返回显式降级观察,不重试) */
     canAttempt() {
         const s = this.state();
-        if (s === 'closed') return {
-            allowed: true,
-            state: s
-        };
-        if (s === 'open') return {
-            allowed: false,
-            state: s
-        };
-        if (this.probeInFlight) return {
-            allowed: false,
-            state: s
-        };
+        if (s === 'closed')
+            return { allowed: true, state: s };
+        if (s === 'open')
+            return { allowed: false, state: s };
+        // half-open:单探测语义——已有探测在途拒其余并发
+        if (this.probeInFlight)
+            return { allowed: false, state: s };
         this.probeInFlight = true;
-        return {
-            allowed: true,
-            state: s
-        };
+        return { allowed: true, state: s };
     }
+    /** 一次解译调用成功(非 isFailure)——清零;half-open 探测成功即回 closed */
     onSuccess() {
         this.consecutiveFailures = 0;
         this.openedAt = 0;
         this.probeInFlight = false;
     }
+    /** 一次解译调用失败(含重试耗尽)——半开探测失败 = 重新开闸 */
     onFailure() {
         this.probeInFlight = false;
         this.consecutiveFailures += 1;
@@ -85,6 +106,3 @@ export class CircuitBreaker {
         }
     }
 }
-
-
-//# sourceURL=ts/capabilities/resilience.ts