berry-agent 0.1.0-alpha.1

package/dist/obs/service.js

@@ -0,0 +1,363 @@
+/**
+ * obs — 服务面（03 §10.8 增量摄取/告警条款的编舞位）。
+ *
+ * refresh() 单入口三段：①增量摄取（水位−1h 重叠窗扫事件流 → 脏桶整窗重查
+ * 重算替换——幂等自愈）②闭日物化（日桶只在日闭合后从小时桶聚合落账，
+ * 重算幂等）③告警评估（只通知不执法 + hasAudience 前置不耗冷却）。
+ * 已知边界（如实注记，不虚构保证）：时钟回拨超 1h 重叠窗的旧事件不回补
+ * ——单写者 append-only 事件流的 time 单调性使其实际不发生。
+ *
+ * 聚合呈现两维分立（07 §4.2）：本件数据面只有会话客观态聚合；用户已读
+ * 游标不入观测库（住通道侧本地状态）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { openRollupDatabase } from './db.js';
+import { aggregateHours, bucketClosed, DAY_MS, dayBucketMs, HOUR_MS, hourBucketMs } from './rollup.js';
+/** 摄取水位 obs_meta 键（上次扫描推进到的 now 毫秒） */
+const META_WATERMARK = 'ingest_watermark_ms';
+/** 重叠窗（迟到事件/时钟回拨自愈面——1 小时） */
+const OVERLAP_MS = HOUR_MS;
+/** 告警冷却缺省（规则小时粒度——冷却缺省与粒度对齐） */
+const DEFAULT_COOLDOWN_MS = HOUR_MS;
+/** 扫描页参数（与 Store.queryEvents 硬帽一致；页数护栏防坏游标死循环） */
+const SCAN_PAGE_LIMIT = 10_000;
+const SCAN_PAGE_GUARD = 1_000;
+/** 查询行帽（缺省 100、硬帽 1000——模型消费面） */
+const QUERY_LIMIT_DEFAULT = 100;
+const QUERY_LIMIT_MAX = 1_000;
+/**
+ * LIKE 前缀转义（03 §10.8 u-1 RP5 尾通配——u-4 落码）：族前缀按字面匹配，
+ * `\` `%` `_` 三元前置反斜杠——LIKE 元字符不放大匹配面（未转义的 `_` 会
+ * 单字符通配误中，如 `plug_n/*` 误中 `plugAn/x`，破坏族语义）。
+ */
+function escapeLikePrefix(prefix) {
+    return prefix.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+/** createObsService 工厂（装载面/测试唯一入口） */
+export function createObsService(deps) {
+    return new ObsServiceImpl(deps);
+}
+/** 服务实现（类私有——外界只经 ObsService 面） */
+class ObsServiceImpl {
+    db;
+    events;
+    notify;
+    audience;
+    alerts;
+    clock;
+    warn;
+    timer;
+    disposed = false;
+    constructor(deps) {
+        // 开库即抛 OBS_DB_OPEN_FAILED（fail-loud——装载面降级跳件消费）
+        this.db = openRollupDatabase(deps.dbPath, deps.warn);
+        this.events = deps.events;
+        this.notify = deps.notify;
+        this.audience = deps.audience;
+        this.alerts = deps.alerts ?? [];
+        this.clock = deps.clock ?? (() => Date.now());
+        this.warn = deps.warn ?? ((message) => console.error(message));
+        const refreshMs = deps.refreshMs ?? 60_000;
+        if (refreshMs > 0) {
+            // 自驱挂钟（obs deps 无 scheduler 边——件内自持合法；dispose 注销。
+            // 定时腿异常不炸进程：吞进 warn，下一拍重试）
+            this.timer = setInterval(() => {
+                try {
+                    this.refresh();
+                }
+                catch (err) {
+                    this.warn(`[obs] 自驱 refresh 失败（下一拍重试）：${err instanceof Error ? err.message : String(err)}`);
+                }
+            }, refreshMs);
+            // unref：观测挂钟不锚进程生命周期（诊断形装载本件后进程可自然退
+            // ——dump-config/plugins-list :memory: 同构纪律；长驻形不受影响，
+            // 收口恒走 dispose 注销）
+            this.timer.unref?.();
+        }
+    }
+    refresh() {
+        this.ensureOpen();
+        const now = this.clock();
+        const prevWatermark = this.readMetaNumber(META_WATERMARK) ?? 0;
+        // ① 增量摄取：水位−1h 重叠窗、窗起点下取整到小时边界——窗内每桶被
+        // 完整重扫，产物即各桶完整真值（当前桶覆盖到 now 为止，恰为「事件
+        // 至此」的正确计数；迟到在 1h 窗内的旧桶下一拍整窗重算自愈）
+        const scanSince = hourBucketMs(Math.max(0, prevWatermark - OVERLAP_MS));
+        const aggregation = this.scanEvents(scanSince, now);
+        // ②③ 同事务落账（摄取替换 + 闭日物化 + 水位推进——单事务幂等）
+        const write = this.db.transaction(() => {
+            this.replaceHourBuckets(aggregation);
+            this.materializeClosedDays(aggregation.touchedBuckets, prevWatermark, now);
+            // 水位只进不退（时钟回拨不回吃扫描窗——下拍以旧水位+重叠窗续扫）
+            this.setMeta(META_WATERMARK, String(Math.max(prevWatermark, now)));
+        });
+        write();
+        // 告警评估挂 refresh 尾（03 §10.8——只通知不执法）
+        this.evaluateAlerts(now);
+    }
+    query(input) {
+        this.ensureOpen();
+        const granularity = input.granularity === 'day' ? 'day' : 'hour';
+        const metric = input.metric === 'usage' ? 'usage' : 'events';
+        const limit = Math.min(Math.max(1, input.limit ?? QUERY_LIMIT_DEFAULT), QUERY_LIMIT_MAX);
+        // 窗口对齐到桶边界（from/to 都是「含」语义）
+        const span = granularity === 'day' ? DAY_MS : HOUR_MS;
+        const from = input.from !== undefined ? Math.floor(input.from / span) * span : undefined;
+        const to = input.to !== undefined ? Math.floor(input.to / span) * span : undefined;
+        if (metric === 'usage') {
+            const table = granularity === 'day' ? 'usage_day' : 'usage_hour';
+            const clauses = [];
+            const params = [];
+            if (from !== undefined) {
+                clauses.push('bucket >= ?');
+                params.push(from);
+            }
+            if (to !== undefined) {
+                clauses.push('bucket <= ?');
+                params.push(to);
+            }
+            params.push(limit);
+            const rows = this.db
+                .prepare(`SELECT bucket, calls, input, output, cache_read, cache_write, cache_write_1h, reasoning
+           FROM ${table}${clauses.length > 0 ? ` WHERE ${clauses.join(' AND ')}` : ''}
+           ORDER BY bucket ASC LIMIT ?`)
+                .all(...params);
+            return rows.map((row) => this.toUsageRow(row, table));
+        }
+        const table = granularity === 'day' ? 'events_day' : 'events_hour';
+        const clauses = [];
+        const params = [];
+        if (from !== undefined) {
+            clauses.push('bucket >= ?');
+            params.push(from);
+        }
+        if (to !== undefined) {
+            clauses.push('bucket <= ?');
+            params.push(to);
+        }
+        if (input.eventType !== undefined) {
+            // 尾通配形（03 §10.8 u-1 RP5 定形——u-4 落码扩形）：`<族前缀>/*` 一次
+            // 取全族计数（如 compaction/*——四词族一次可达）；语法限定尾 `/*` 一形
+            // 非任意 glob。LIKE ESCAPE '\' + 前缀转义保字面；hour/day 两表同路
+            // （table 变量切换——本分支单码点覆盖两粒度）。非尾通配的含 '*' 形
+            // 落精确匹配零行（诚实空不炸——工具面 schema pattern 段已前置拒，
+            // 此处兜底即防御纵深）
+            if (input.eventType.endsWith('/*')) {
+                clauses.push("event_type LIKE ? ESCAPE '\\'");
+                params.push(`${escapeLikePrefix(input.eventType.slice(0, -1))}%`);
+            }
+            else {
+                clauses.push('event_type = ?');
+                params.push(input.eventType);
+            }
+        }
+        params.push(limit);
+        const rows = this.db
+            .prepare(`SELECT bucket, event_type, count FROM ${table}${clauses.length > 0 ? ` WHERE ${clauses.join(' AND ')}` : ''} ORDER BY bucket ASC, event_type ASC LIMIT ?`)
+            .all(...params);
+        return rows.map((row) => this.toEventsRow(row, table));
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.timer !== undefined)
+            clearInterval(this.timer);
+        this.db.close();
+    }
+    /* ---------------- 私有腿 ---------------- */
+    /** dispose 后拒用（fail-loud——归 OBS_DB_OPEN_FAILED 族：库已闭） */
+    ensureOpen() {
+        if (this.disposed) {
+            throw new BaseError('OBS_DB_OPEN_FAILED', 'obs 服务已 dispose——refresh/query 拒用');
+        }
+    }
+    /** 页游标遍历事件流（untilMs 含 now——不吞 now 时刻事件） */
+    scanEvents(scanSince, now) {
+        const collected = [];
+        let cursor = null;
+        for (let page = 0; page < SCAN_PAGE_GUARD; page++) {
+            const result = this.events.queryEvents({
+                sinceMs: scanSince,
+                untilMs: now,
+                limit: SCAN_PAGE_LIMIT,
+                ...(cursor !== null ? { cursor } : {}),
+            });
+            collected.push(...result.events);
+            if (result.nextCursor === null)
+                break;
+            cursor = result.nextCursor;
+        }
+        return aggregateHours(collected);
+    }
+    /** 脏桶整体替换（DELETE+INSERT——幂等自愈的执法位） */
+    replaceHourBuckets(aggregation) {
+        const delEvents = this.db.prepare('DELETE FROM events_hour WHERE bucket = ?');
+        const delUsage = this.db.prepare('DELETE FROM usage_hour WHERE bucket = ?');
+        const insEvents = this.db.prepare('INSERT INTO events_hour (bucket, event_type, count) VALUES (?, ?, ?)');
+        const insUsage = this.db.prepare('INSERT INTO usage_hour (bucket, calls, input, output, cache_read, cache_write, cache_write_1h, reasoning) VALUES (?, ?, ?, ?, ?, ?, ?, ?)');
+        for (const bucket of aggregation.touchedBuckets) {
+            delEvents.run(bucket);
+            delUsage.run(bucket);
+            const byType = aggregation.counts.get(bucket);
+            if (byType) {
+                for (const [eventType, count] of byType)
+                    insEvents.run(bucket, eventType, count);
+            }
+            const usage = aggregation.usage.get(bucket);
+            if (usage) {
+                insUsage.run(bucket, usage.calls, usage.input, usage.output, usage.cacheRead, usage.cacheWrite, usage.cacheWrite1h, usage.reasoning);
+            }
+        }
+    }
+    /**
+     * 闭日物化：候选 = 本拍触达桶的日 + 水位以来跨过的日（末拍后闭日的桶
+     * 无新事件也要物化）。只做闭日（bucketClosed——当前日在飞不落），从
+     * 小时桶表聚合重算（DELETE+INSERT 幂等）。
+     */
+    materializeClosedDays(touchedHourBuckets, prevWatermark, now) {
+        const candidates = new Set();
+        for (const bucket of touchedHourBuckets)
+            candidates.add(dayBucketMs(bucket));
+        if (prevWatermark > 0) {
+            // 水位以来跨过的日（首拍 prevWatermark=0 不走全史迭代——触达桶的日
+            // 已覆盖有数据的日）
+            for (let day = dayBucketMs(prevWatermark); day <= dayBucketMs(now); day += DAY_MS) {
+                candidates.add(day);
+            }
+        }
+        const delEvents = this.db.prepare('DELETE FROM events_day WHERE bucket = ?');
+        const delUsage = this.db.prepare('DELETE FROM usage_day WHERE bucket = ?');
+        const insEvents = this.db.prepare('INSERT INTO events_day (bucket, event_type, count) VALUES (?, ?, ?)');
+        const selEvents = this.db.prepare('SELECT event_type, SUM(count) AS count FROM events_hour WHERE bucket >= ? AND bucket < ? GROUP BY event_type');
+        const insUsage = this.db.prepare('INSERT INTO usage_day (bucket, calls, input, output, cache_read, cache_write, cache_write_1h, reasoning) VALUES (?, ?, ?, ?, ?, ?, ?, ?)');
+        const selUsage = this.db.prepare(`SELECT SUM(calls) AS calls, SUM(input) AS input, SUM(output) AS output, SUM(cache_read) AS cache_read,
+              SUM(cache_write) AS cache_write, SUM(cache_write_1h) AS cache_write_1h, SUM(reasoning) AS reasoning
+       FROM usage_hour WHERE bucket >= ? AND bucket < ?`);
+        for (const day of candidates) {
+            if (!bucketClosed(day, now, DAY_MS))
+                continue;
+            delEvents.run(day);
+            delUsage.run(day);
+            for (const row of selEvents.all(day, day + DAY_MS)) {
+                const typed = row;
+                const eventType = typeof typed.event_type === 'string' ? typed.event_type : '(unknown)';
+                const count = typeof typed.count === 'number' && Number.isFinite(typed.count) ? typed.count : 0;
+                insEvents.run(day, eventType, count);
+            }
+            const usage = selUsage.get(day, day + DAY_MS);
+            // 全天零行时 SUM 全 NULL——不落 usage_day 行（无调用日无行）
+            if (usage && typeof usage.calls === 'number') {
+                const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+                insUsage.run(day, usage.calls, num(usage.input), num(usage.output), num(usage.cache_read), num(usage.cache_write), num(usage.cache_write_1h), num(usage.reasoning));
+            }
+        }
+    }
+    /** 告警评估（refresh 尾；hasAudience 前置——无观众整跳且不耗冷却） */
+    evaluateAlerts(now) {
+        if (this.alerts.length === 0)
+            return;
+        // 观众探针前置（03 §10.8）：false 时跳过整次评估——冷却不烧、观众回场
+        // 仍可响（07 §4.3 无头不耗告警冷却原句语义）
+        if (!this.audience.hasAudience())
+            return;
+        const bucket = hourBucketMs(now);
+        const row = this.db.prepare('SELECT input, output FROM usage_hour WHERE bucket = ?').get(bucket);
+        const mainBillable = row && typeof row.input === 'number' && typeof row.output === 'number' ? row.input + row.output : 0;
+        this.alerts.forEach((rule, index) => {
+            // v1 单规则种：未知种跳过 + warn（配置校验主责在装载面——此处防御
+            // 不炸宿主）；坏阈值（非正数）同理跳过
+            if (rule.kind !== 'token_spend_hourly') {
+                this.warn(`[obs] 跳过未知告警规则种：${String(rule.kind)}（规则 #${index}）`);
+                return;
+            }
+            if (!(rule.thresholdTokens > 0)) {
+                this.warn(`[obs] 跳过坏阈值告警规则（thresholdTokens=${String(rule.thresholdTokens)}，规则 #${index}）`);
+                return;
+            }
+            if (mainBillable < rule.thresholdTokens)
+                return;
+            // 冷却判定（per-规则 lastFiredAt；notify 失败不烧冷却——下一拍重试）
+            const cooldownMs = rule.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+            const key = `alert:${index}:lastFiredAt`;
+            const lastFiredAt = this.readMetaNumber(key) ?? 0;
+            if (now - lastFiredAt < cooldownMs)
+                return;
+            try {
+                // ObsNotifyFace 面（词面独立——notify(message, opts) 单方法）
+                this.notify.notify(`[obs] 当前小时 token 花销 ${mainBillable} 已超阈值 ${rule.thresholdTokens}（主计费桶 input+output；cache 桶不计）`, { level: 'warn' });
+            }
+            catch (err) {
+                this.warn(`[obs] 告警通知失败（不烧冷却，下一拍重试）：${err instanceof Error ? err.message : String(err)}`);
+                return;
+            }
+            this.setMeta(key, String(now));
+        });
+    }
+    /** obs_meta 读（字符串值；缺席 null） */
+    readMeta(key) {
+        const row = this.db.prepare('SELECT value FROM obs_meta WHERE key = ?').get(key);
+        return row && typeof row.value === 'string' ? row.value : null;
+    }
+    /** obs_meta 数值读（坏值折 null——水位/冷却只信合法数） */
+    readMetaNumber(key) {
+        const raw = this.readMeta(key);
+        if (raw === null)
+            return null;
+        const value = Number(raw);
+        return Number.isFinite(value) ? value : null;
+    }
+    /** obs_meta 写（upsert） */
+    setMeta(key, value) {
+        this.db
+            .prepare('INSERT INTO obs_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value')
+            .run(key, value);
+    }
+    /** 事件行拒误读校验（坏行 = OBS_ROLLUP_CORRUPT——派生物宁弃读不误读） */
+    toEventsRow(row, table) {
+        const typed = row;
+        if (typeof typed.bucket !== 'number' ||
+            !Number.isInteger(typed.bucket) ||
+            typed.bucket < 0 ||
+            typeof typed.event_type !== 'string' ||
+            typeof typed.count !== 'number' ||
+            !Number.isFinite(typed.count) ||
+            typed.count < 0) {
+            throw new BaseError('OBS_ROLLUP_CORRUPT', `${table} 命中坏行（拒误读——重算即修复）：${JSON.stringify(row)}`);
+        }
+        return { bucket: typed.bucket, eventType: typed.event_type, count: typed.count };
+    }
+    /** 用量行拒误读校验（同上律——七列全数且非负） */
+    toUsageRow(row, table) {
+        const typed = row;
+        const fields = ['bucket', 'calls', 'input', 'output', 'cache_read', 'cache_write', 'cache_write_1h', 'reasoning'];
+        for (const field of fields) {
+            const value = typed[field];
+            if (typeof value !== 'number' ||
+                !Number.isFinite(value) ||
+                value < 0 ||
+                (field === 'bucket' && !Number.isInteger(value))) {
+                throw new BaseError('OBS_ROLLUP_CORRUPT', `${table} 命中坏行（拒误读——重算即修复）：${JSON.stringify(row)}`);
+            }
+        }
+        return {
+            bucket: typed.bucket,
+            calls: typed.calls,
+            input: typed.input,
+            output: typed.output,
+            cacheRead: typed.cache_read,
+            cacheWrite: typed.cache_write,
+            cacheWrite1h: typed.cache_write_1h,
+            reasoning: typed.reasoning,
+            // 命中率派生列（RP5——查询期派生零 rollup 列）：桶内聚合比值；分母零
+            // = 无 token 流 → null（诚实缺席非 0%）
+            hitRate: (() => {
+                const input = typed.input;
+                const cacheRead = typed.cache_read;
+                const cacheWrite = typed.cache_write;
+                const denominator = input + cacheRead + cacheWrite;
+                return denominator > 0 ? cacheRead / denominator : null;
+            })(),
+        };
+    }
+}

package/dist/obs/session-tools.js

@@ -0,0 +1,282 @@
+/**
+ * obs — 会话维工具族（03 §10.8 会话维扩展——e-2 观测腿 + e-3 环境自感；
+ * 宿主固定工具族四件 `session_list` / `session_read` / `session_trace` /
+ * `session_status`，`session_` 前缀保留字〔03 §2.7〕的宿主侧落位）。
+ *
+ * **可见性分轴执法**（03 §10.8——观测轴）：
+ *  - 树内（self 同 id / parent_id 链同根——SessionView.isSameTree 单源）
+ *    零开门白给；
+ *  - 跨树/全会话维枚举与读走高危面 `sessions.observe-cross` 门检
+ *    （03 §4.6 v1 首批第五枚——adjudicateCapabilityDoor；拒 =
+ *    SESSION_OBSERVE_DENIED〔02 §5.3 e-2 补登〕）；门开后逐次
+ *    capability/used 审计 seam（05 §1.1——真发射位 U3 批已接线
+ *    audit_events）。
+ *  - session_list 的门未开形 = 只列树内会话（枚举本身即跨树信息——
+ *    「枚举与读」同门同码防旁路）。
+ *
+ * **行为律带出**（立题档 §六「问当事人 vs 查档案」——oh-my-pi 先例：
+ * 判断隔壁会话在做什么优先直接向当事会话发消息，档案查询归本工具族；
+ * 提示词层面带出不立条款）：写进 session_read/session_trace description。
+ *
+ * **e-3 环境自感**（普查候选 E——03 §10.8 session_status 条并入注）：
+ * session_status 扩工具清单（整形后有效可见集）/ 能力门态快照（闭门
+ * 附诊断 reason——与执行时拒绝 message 同源）/ 负面能力声明文案
+ * （hermes「你没有 X——不要承诺」防幻觉负向清单）三段；数据经 env
+ * 窄面注入（装配现场事实非 durable 派生——与 SessionView 分立）。
+ *
+ * 恒挂载律（03 §2.2 第十一面同款）：工具族模型可见清单恒在，不随门开合
+ * 动态挂载——门检在 execute 内执法。per-session 闭包由装配位构造
+ * （callerSessionId 注入——todoTool 换装 seam 同构先例）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { adjudicateCapabilityDoor } from '../contracts/api.js';
+import { Type } from 'typebox';
+/** 观测轴高危面名（03 §4.6 v1 首批第五枚——拉取/订阅两形态一枚统摄） */
+export const OBSERVE_CROSS_CAPABILITY = 'sessions.observe-cross';
+/** createSessionTools 工厂（装载位/测试唯一入口）——四件定义数组 */
+export function createSessionTools(deps) {
+    const { view, callerSessionId } = deps;
+    /** 跨树门检 + 开门后审计（执法序：树内白给前置由调用侧判，此处只管跨树档） */
+    const enforceCrossTreeDoor = (verb, targetSessionId) => {
+        const verdict = adjudicateCapabilityDoor(deps.getOpens(), OBSERVE_CROSS_CAPABILITY);
+        if (!verdict.ok) {
+            throw new BaseError('SESSION_OBSERVE_DENIED', `${verdict.message}（调用方会话 ${callerSessionId}${targetSessionId !== undefined ? `，目标 ${targetSessionId}` : ''}）`);
+        }
+        // 开门后逐次审计（core: 豁免面不适用于模型工具道——caller 恒为会话模型）
+        deps.onCapabilityUsed?.({
+            capability: OBSERVE_CROSS_CAPABILITY,
+            callerSessionId,
+            verb,
+            ...(targetSessionId !== undefined ? { targetSessionId } : {}),
+        });
+    };
+    /** 树内判定（self 同 id 特例天然含于 isSameTree） */
+    const inOwnTree = (targetSessionId) => view.isSameTree(targetSessionId, callerSessionId);
+    return [
+        {
+            name: 'session_list',
+            description: '列出本进程在管会话清单（id/标题/血缘 origin·parentId/在飞粗状态/近次模型/updatedAt）。' +
+                '默认只列本会话血缘树内会话；跨树/全会话维枚举需高危面 sessions.observe-cross 开门（未开门时跨树会话不呈现）。' +
+                '在飞粗状态由事件流尾条推导（idle = 回合闭合 / running = 回合进行中 / waiting-approval = 等待用户审批 / paused = 预算停靠——预算帽尽停靠、回充唤醒）。',
+            parameters: Type.Object({}, { additionalProperties: false }),
+            effect: 'read',
+            execute: async () => guard(async () => {
+                const summaries = view.listSessions();
+                // 可见性分轴：门未开只列树内（含 self）；门开全列——先探门再裁
+                const door = adjudicateCapabilityDoor(deps.getOpens(), OBSERVE_CROSS_CAPABILITY);
+                const visible = door.ok ? summaries : summaries.filter((row) => inOwnTree(row.id));
+                if (door.ok) {
+                    deps.onCapabilityUsed?.({ capability: OBSERVE_CROSS_CAPABILITY, callerSessionId, verb: 'session_list' });
+                }
+                if (visible.length === 0) {
+                    return { content: [{ type: 'text', text: '（无可见会话——进程内无在管会话，或跨树会话未开门不呈现）' }] };
+                }
+                const header = 'id  title  origin  parent  live  model  updatedAt';
+                const lines = visible.map(summaryLine);
+                return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
+            }),
+        },
+        {
+            name: 'session_read',
+            description: '读取指定会话事件流尾部窗口（有帽有界——缺省 50 条、上限 200 条，含事件类型/序号/摘要）。' +
+                '树内会话（本会话及其血缘树）直接可读；跨树会话需高危面 sessions.observe-cross 开门。' +
+                '行为律：判断隔壁会话当前在做什么，优先直接向当事会话发消息确认（对话协作同人类）；' +
+                '本工具面向历史档案核查与事后回溯。',
+            parameters: Type.Object({
+                sessionId: Type.String({ description: '目标会话 id' }),
+                limit: Type.Optional(Type.Number({ description: '尾窗条数（缺省 50、硬帽 200）' })),
+            }, { additionalProperties: false }),
+            effect: 'read',
+            execute: async (args) => guard(async () => {
+                // schema 段已校验（typebox String）——execute 层直断窄读
+                const sessionId = args.sessionId;
+                if (!inOwnTree(sessionId))
+                    enforceCrossTreeDoor('session_read', sessionId);
+                const window = typeof args.limit === 'number' ? view.readTail(sessionId, { limit: args.limit }) : view.readTail(sessionId);
+                if (!window.exists) {
+                    return { content: [{ type: 'text', text: `（目标会话 ${sessionId} 无对应行——查无此档）` }] };
+                }
+                if (window.items.length === 0) {
+                    return { content: [{ type: 'text', text: '（目标会话零事件——空档案）' }] };
+                }
+                const lines = window.items.map((item) => `${item.seq}  ${item.time}  ${item.type}  ${item.summary}`);
+                return { content: [{ type: 'text', text: ['seq  time  type  summary', ...lines].join('\n') }] };
+            }),
+        },
+        {
+            name: 'session_trace',
+            description: '查询指定会话当前进行态（在飞粗状态 + 当前回合尾窗 20 条 + 在飞工具清单）。' +
+                '树内会话直接可查；跨树会话需高危面 sessions.observe-cross 开门。' +
+                '行为律：判断隔壁会话当前在做什么，优先直接向当事会话发消息确认；本工具面向状态核查。',
+            parameters: Type.Object({ sessionId: Type.String({ description: '目标会话 id' }) }, { additionalProperties: false }),
+            effect: 'read',
+            execute: async (args) => guard(async () => {
+                const sessionId = args.sessionId; // schema 段已校验——直断窄读
+                if (!inOwnTree(sessionId))
+                    enforceCrossTreeDoor('session_trace', sessionId);
+                const report = view.trace(sessionId);
+                if (!report.exists) {
+                    return { content: [{ type: 'text', text: `（目标会话 ${sessionId} 无对应行——查无此档）` }] };
+                }
+                const head = `live=${report.live}  inflight=${report.inflightTools.length > 0 ? report.inflightTools.join(',') : '（无）'}`;
+                const lines = report.recent.map((item) => `${item.seq}  ${item.time}  ${item.type}  ${item.summary}`);
+                return { content: [{ type: 'text', text: [head, 'seq  time  type  summary', ...lines].join('\n') }] };
+            }),
+        },
+        {
+            name: 'session_status',
+            description: '查询自身坐标与环境自感（「我是谁在哪、有什么、没有什么」）：本会话 id、血缘 origin 与父会话、' +
+                '工作区根、在飞粗状态、近次模型，以及可用工具清单（整形后有效可见集）、能力门态快照（高危面开/闭与' +
+                '闭门理由）、负面能力声明（未开门面/无工作区等「不要承诺」负向清单——防幻觉）、工具策略表快照' +
+                '（allow/deny 条目 + 整名族干跑裁决——装配期快照，/approval explain 为活体试解析）。' +
+                '零参数——目标恒为本会话（树内 self 档，零开门）。',
+            parameters: Type.Object({}, { additionalProperties: false }),
+            effect: 'read',
+            execute: async () => guard(async () => {
+                const status = view.selfStatus(callerSessionId);
+                const lines = [
+                    `sessionId=${status.sessionId}`,
+                    `origin=${status.origin}`,
+                    `parent=${status.parentId ?? '（根会话）'}`,
+                    `workspaceRoot=${status.workspaceRoot ?? '（无工作区）'}`,
+                    `live=${status.live}`,
+                    `model=${status.model ?? '（未发起请求）'}`,
+                ];
+                // e-3 环境自感三段（env 缺席 = 基础坐标档——段整体不呈现，诚实降级不虚构）
+                if (deps.env !== undefined) {
+                    const listing = deps.env.listTools();
+                    lines.push(`tools(${listing.length})=${listing.map((entry) => entry.name).join(', ')}`);
+                    const doors = deps.env.doorStates();
+                    lines.push('capability-doors:');
+                    for (const door of doors) {
+                        lines.push(doorLine(door));
+                    }
+                    const negatives = negativeLines(doors, status.workspaceRoot);
+                    lines.push('negative-capabilities:', ...negatives);
+                    // ap-3 第四段：工具策略表（toolPolicy 缺席 = 段不呈现——与 doorStates
+                    // 同缺席语义；装配期快照诚实，/approval entries/explain 才是活体面）
+                    const policy = deps.env.toolPolicy?.();
+                    if (policy !== undefined) {
+                        lines.push(...policyLines(policy));
+                    }
+                }
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            }),
+        },
+    ];
+}
+/** 门态行（能力自省快照——闭门附诊断 reason：与执行时拒绝 message 同源，先查后用） */
+function doorLine(door) {
+    const state = door.open ? 'open' : 'closed';
+    if (door.open)
+        return `  ${door.capability}=${state}（${door.scope}）`;
+    return `  ${door.capability}=${state}（${door.reason ?? '未开门'}）——${door.scope}`;
+}
+/**
+ * 负面能力声明文案（hermes「你没有 X——不要承诺」防幻觉负向清单；
+ * 普查候选 E D4 缺缝③）。v1 两锚：闭门面（对应操作将被拒）+ 无工作区
+ * （文件工具结构性不可用）。全开 + 有工作区 = 显式「无缺失」收口行
+ * （负向清单的价值在显式闭合——「查过且无」不等于「没查」）。
+ */
+function negativeLines(doors, workspaceRoot) {
+    const lines = [];
+    for (const door of doors) {
+        if (!door.open)
+            lines.push(`  - ${door.capability} 未开门——${door.scope}将被拒，不要承诺对应操作`);
+    }
+    if (workspaceRoot === undefined) {
+        lines.push('  - 本会话无工作区根——文件读写工具不可用，不要承诺文件操作');
+    }
+    if (lines.length === 0)
+        lines.push('  （无——当前能力面无缺失声明）');
+    return lines;
+}
+/** 清单行文本（列对齐——模型消费面） */
+function summaryLine(row) {
+    return [
+        row.id,
+        row.title ?? '（无标题）',
+        row.origin,
+        row.parentId ?? '-',
+        row.live,
+        row.model ?? '-',
+        String(row.updatedAt),
+    ].join('  ');
+}
+/**
+ * 实参绑定族工具名（write/edit/bash——条目命中依赖调用实参〔路径/命令〕，
+ * 整名干跑恒 miss 不可判；字面 = host 工具词汇非 safety 域逻辑——obs 零
+ * safety 依赖〔DAG〕，此处仅作呈现分族，判定真源在注入的 dryRun 闭包）。
+ */
+const ARG_BOUND_TOOLS = new Set(['write', 'edit', 'bash']);
+/**
+ * 工具策略表段渲染（ap-3 第四段——03 §10.8 ap-3 定形注）：① 条目清单全列
+ * （装配期快照 + 载体路径注明）；② 整名族条目经 dryRun（守门行同一
+ * matchToolPolicy 注入）干跑呈行——deny/allow 命中含条目序与 reason，无
+ * 命中不占行；③ 实参绑定族（fs/bash）计数注记指路 /approval explain——
+ * 不假报无命中（诚实分形）。
+ */
+function policyLines(policy) {
+    const lines = [`tool-policy(${policy.entries.length}) [装配期快照 path=${policy.path}]:`];
+    if (policy.entries.length === 0) {
+        lines.push('  （空——无任何条目）');
+        return lines;
+    }
+    for (const entry of policy.entries) {
+        const bits = [`[${entry.index}]`, `tool=${entry.tool}`];
+        if (entry.pattern !== undefined)
+            bits.push(`pattern=${entry.pattern}`);
+        bits.push(`decision=${entry.decision}`);
+        if (entry.effect !== undefined)
+            bits.push(`effect=${entry.effect}`);
+        if (entry.reason !== undefined)
+            bits.push(`reason=${entry.reason}`);
+        if (entry.expiresAt !== undefined)
+            bits.push(`expiresAt=${new Date(entry.expiresAt).toISOString()}`);
+        lines.push(`  ${bits.join(' ')}`);
+    }
+    // ② 整名族干跑（每工具三档并列；同条目命中的档合并呈一行「全档」）
+    const wholeNameTools = [...new Set(policy.entries.filter((e) => !ARG_BOUND_TOOLS.has(e.tool)).map((e) => e.tool))];
+    const argBoundCount = policy.entries.filter((e) => ARG_BOUND_TOOLS.has(e.tool)).length;
+    if (wholeNameTools.length > 0) {
+        lines.push('  整名族干跑（装配期快照 + 守门行同一判定函数）：');
+        for (const tool of wholeNameTools) {
+            const hits = ['read', 'write', 'exec']
+                .map((effect) => ({ effect, hit: policy.dryRun(tool, effect) }))
+                .filter((h) => h.hit !== undefined);
+            if (hits.length === 0)
+                continue; // 无命中不占行（如 allow 条目已过期）
+            const sameEntry = hits.every((h) => h.hit.index === hits[0].hit.index);
+            const verdict = (hit) => hit.decision === 'deny'
+                ? `policy-deny:${hit.index}（硬拒——任何面不可翻转）`
+                : `policy-allow:${hit.index}（免问放行）`;
+            if (sameEntry) {
+                const tiers = hits.length === 3 ? '全档' : hits.map((h) => h.effect).join('/');
+                lines.push(`    ${tool}: ${tiers}命中 ${verdict(hits[0].hit)}`);
+            }
+            else {
+                for (const { effect, hit } of hits)
+                    lines.push(`    ${tool}: ${effect}档命中 ${verdict(hit)}`);
+            }
+        }
+    }
+    // ③ 实参绑定族计数注记（不假报无命中——指路活体试解析）
+    if (argBoundCount > 0) {
+        lines.push(`  （另 ${argBoundCount} 条 write/edit/bash 族条目逐调用裁决——命中依赖路径/命令实参，/approval explain <tool> [pattern] 试解析）`);
+    }
+    return lines;
+}
+/** 统一异常编码（03 §2.3——BaseError 携码前置披露；obs_query 同款先例） */
+async function guard(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        const code = error instanceof BaseError ? error.code : undefined;
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: 'text', text: code ? `[${code}] ${message}` : message }],
+            isError: true,
+        };
+    }
+}