berry-agent 0.1.0-alpha.1

package/dist/memory/types.js

@@ -0,0 +1,140 @@
+/**
+ * core:memory 类型面（06 篇 §3/§5——记忆表族 + 合并三分支；批 18c-1）。
+ *
+ * 单向 DAG（02 §4.1 memory 席 deps = contracts + context + session + persist）：
+ * 四实边已全通（contracts 错误码注册 + persist SqliteDatabase/MigrationSpec +
+ * context canonical 根接线 + session/event 提取注入两路——18c-3/4/5 落码后
+ * 实况；拓扑边表四边在位执法）。
+ *
+ * 本文件钉死：kind 七值闭集、status 三值闭集、source_refs 溯源形、
+ * 候选/行形、三分支裁决结果、入库结局——契约先行的词汇面单源。
+ */
+/** kind 七值闭集单源（运行时校验消费——MEMORY_ENTRY_INVALID 判据之一） */
+export const MEMORY_KINDS = [
+    'preference',
+    'fact',
+    'convention',
+    'correction',
+    'failure',
+    'insight',
+    'profile',
+];
+/** 状态三值闭集单源 */
+export const MEMORY_STATUSES = ['active', 'dismissed', 'expired'];
+/* ---------------- 常量（缺省值单源——06 §3/§5 起草值） ---------------- */
+/** 模糊合并 Jaccard 阈值（Mercury 实证档 0.74——Jaccard 交并比钉死，落码定形注） */
+export const MEMORY_FUZZY_JACCARD_THRESHOLD = 0.74;
+/** 极性冲突去极性后 Jaccard 阈值（同主题判据——06 §5 分支 3） */
+export const MEMORY_POLARITY_JACCARD_THRESHOLD = 0.5;
+/** source_refs 并集去重上限（血缘继承同罩——06 §5 血缘继承段「50 条上限」） */
+export const MEMORY_SOURCE_REFS_CAP = 50;
+/** summary 硬帽（合并比较面与 FTS 索引面的合理量级——起草值随实测调） */
+export const MEMORY_SUMMARY_MAX_CHARS = 2_000;
+/** content 硬帽（注入用全文——与 summary 同律起草值） */
+export const MEMORY_CONTENT_MAX_CHARS = 64_000;
+/* 持有面/检索面常量（批 18c-2——06 §7 工具九件；起草值随实测调） */
+/** 检索行帽缺省 / 硬帽（memory_search） */
+export const MEMORY_SEARCH_DEFAULT_LIMIT = 10;
+export const MEMORY_SEARCH_MAX_LIMIT = 50;
+/** 访问日志流水面行帽缺省 / 硬帽（memory_access_log） */
+export const MEMORY_ACCESS_LOG_DEFAULT_LIMIT = 50;
+export const MEMORY_ACCESS_LOG_MAX_LIMIT = 200;
+/** 访问聚合面 top-N（「top-N 被用条目」——06 §7 access_log 行） */
+export const MEMORY_ACCESS_AGGREGATE_TOP_N = 20;
+/** 晋升搬家技能名词法（06 §7 forget 行 promotedToSkill——与技能侧 name 校验同源的纯字面量档） */
+export const MEMORY_SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** 晋升搬家技能名帽（≤64） */
+export const MEMORY_SKILL_NAME_MAX = 64;
+/** memory_read 最近变更腿行数（updated_at DESC） */
+export const MEMORY_RECENT_LIMIT = 5;
+/** 天 → 毫秒换算单源（ttl_days / expires_at 重算共用） */
+export const MEMORY_DAY_MS = 86_400_000;
+/* 注入面常量（批 18c-4——06 §6 两路；起草值随实测调） */
+/** 常驻简报段固定标记（memory/core 具名段的包裹锚——prompt 侧锚点） */
+export const MEMORY_BRIEF_MARKER = '<!-- memory:core -->';
+/** 常驻简报字符限额（约值——只约竞争面，frozen 免限额恒全收） */
+export const MEMORY_BRIEF_CHAR_LIMIT = 2000;
+/** 常驻简报竞争面行数帽（top N——「取 top N」的 N 值起草档） */
+export const MEMORY_BRIEF_TOP_N = 20;
+/** 未用强排除阈值天数（§5 效用维度——30 天管常驻面；frozen 免） */
+export const MEMORY_BRIEF_STALE_DAYS = 30;
+/** TTL 临近阈值天数（06 §6 条目行时效标注——p-1 批：expires_at 距今 ≤ 此值时注入行复合「TTL剩M天」段） */
+export const MEMORY_TTL_SOON_DAYS = 7;
+/** 按需检索 query 帽（当轮 user 消息作为检索 query 的资格条件——超长不入检） */
+export const MEMORY_RECALL_QUERY_MAX_CHARS = 200;
+/** 按需检索注入条数（top-k 缺省 3） */
+export const MEMORY_RECALL_TOP_K = 3;
+/** 按需检索 kind 优先重排候选池倍数（一次取款覆盖 kind 重排的候选面——起草值） */
+export const MEMORY_RECALL_POOL_FACTOR = 4;
+/** 检索注入自定义角色名（04 运行时骨架自定义角色机制——装配面包装 hidden/toLlm，件内只出常量与文本） */
+export const MEMORY_RECALL_ROLE = 'memory/recall';
+/* 周期路/整理面常量（批 18c-5——06 §4/§5/§4.1 起草值） */
+/** 周期路触发阈值：turn/end 计数（两阈值任一达标即触发后台 review） */
+export const MEMORY_REVIEW_TURN_THRESHOLD = 10;
+/** 周期路触发阈值：tool/call 计数 */
+export const MEMORY_REVIEW_TOOL_CALL_THRESHOLD = 15;
+/** 周期路审阅窗：最近 N 个 turn（fetchEvents 切片窗——窗内转录喂 LLM） */
+export const MEMORY_REVIEW_WINDOW_TURNS = 10;
+/** 周期路候选置信度缺省（弱于即时路纠正 0.7——review 是推断性提取） */
+export const MEMORY_REVIEW_CONFIDENCE = 0.6;
+/** consolidation 老化阈值天数（updated_at 超此入候选集） */
+export const MEMORY_CONSOLIDATION_STALE_DAYS = 90;
+/** owner 容量上限（TTL 可见行数超此 → 低分盈余入候选；**永不因满拒写**） */
+export const MEMORY_OWNER_CAPACITY = 500;
+/** consolidation 拍间最小间隔毫秒（anchor 护栏——防抖） */
+export const MEMORY_CONSOLIDATION_ANCHOR_MS = 5 * 60_000;
+/** decay 降权因子（confidence × factor——起草值随实测调） */
+export const MEMORY_DECAY_FACTOR = 0.7;
+/**
+ * polluted 判据缺省表（'*' 通配——06 §4.1 落码定形注起草值）：
+ * 'fetch'/'mcp' 精确名 + '*__*' = MCP 复合键全族（`server__tool`——服务器键
+ * 无下划线，'__' 子串即复合键指纹）。
+ */
+export const MEMORY_POLLUTION_DEFAULT_PATTERNS = ['fetch', 'mcp', '*__*'];
+/** review kind 五值闭集单源（TypeBox schema 构建消费） */
+export const REVIEW_KINDS = ['preference', 'fact', 'convention', 'failure', 'insight'];
+/** LLM 回复文本面提取（string 直取；块数组拼 text 块——结构兼容双形） */
+export function llmTextOf(content) {
+    if (typeof content === 'string')
+        return content;
+    return content
+        .filter((b) => b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('\n');
+}
+/* ---------------- 跨会话检索面（批 18c-6——06 §10 落码定形注五则） ---------------- */
+/** snippet 切窗：命中位前取字符数（06 §10 定形注②——前窗短后窗长） */
+export const MEMORY_SNIPPET_BEFORE = 16;
+/** snippet 切窗：命中位后取字符数（含命中词本身） */
+export const MEMORY_SNIPPET_AFTER = 48;
+/* ---------------- 晋升候选与简报差分常量（批 18c-7——06 §9.1/§6） ---------------- */
+/** 晋升候选 kind 集（§9.1——「反复命中才值得固化」的三 kind；preference/fact 等不点名） */
+export const MEMORY_PROMOTION_KINDS = ['failure', 'insight', 'convention'];
+/** 晋升候选行数帽（§9.1「取 top 3」——起草值随实测调） */
+export const MEMORY_PROMOTION_TOP_N = 3;
+/** 晋升候选判据：evidence_count 下限（≥2 = 反复命中；起草值随实测调） */
+export const MEMORY_PROMOTION_EVIDENCE_MIN = 2;
+/** 晋升候选判据：usage_count 下限（cite 是比 recall/search 流水更强的效用信号——单次即够格） */
+export const MEMORY_PROMOTION_USAGE_MIN = 1;
+/**
+ * 晋升候选判据：证据来源会话多样数下限（§9.1 跨会话维——2026-09-08 消化批；
+ * source_refs 溯源面纯派生零新账）。命名循冷读闸观察注：**证据来源**会话多样数，
+ * 非 cite 使用命中面——单会话重复命中多为同一任务重试，跨会话独立复现才是
+ * 可迁移策略（disjoint 泛化的个人化最小形态）。
+ */
+export const MEMORY_PROMOTION_DISTINCT_SESSIONS_MIN = 2;
+/** 简报差分纪元表容量帽（per-session epochs Map LRU——§6 差分纪律；被逐纪元下一请求懒派生） */
+export const MEMORY_DIFF_EPOCHS_LRU = 256;
+/** 回看缓存容量帽（per-session 最近 assistant 文本 Map LRU——§4 即时路第二动作；帽族同 §6 epochs 256） */
+export const MEMORY_LAST_ASSISTANT_TEXT_LRU = 256;
+/* ---------------- 持有面收口与导入导出（批 18c-8——06 §3 落码定形注） ---------------- */
+/**
+ * 访问日志滚动窗口天数（06 §3 访问日志条「留存 = 滚动窗口（起草 90 天）」单源）：
+ * 流水是可丢弃审计面——窗口清扫只删 memory_access 行，聚合列
+ * usage_count/last_used_at 不随清扫回退。
+ */
+export const MEMORY_ACCESS_WINDOW_DAYS = 90;
+/** 导出文件 magic 串（对外声明值位——品牌词例外律；持久互操作标识第一天定死） */
+export const MEMORY_EXPORT_MAGIC = 'berry-agent-memory';
+/** 导出格式版本（formatVersion 非 version——版本链语境下 version 会被读成数据版本） */
+export const MEMORY_EXPORT_FORMAT_VERSION = 2;

package/dist/obs/codes.js

@@ -0,0 +1,38 @@
+/**
+ * obs 域错误码注册（02 §5.3 OBS_ 族批 18b 明列两码；03 §10.8 错误码族条款；
+ * 2026-09-08 e-2 观测腿批扩 SESSION_OBSERVE_DENIED——module 段 obs，与
+ * SESSION_ 族操控四码〔module 段 conversation〕分域并存〔02 §5.3 跨功能域
+ * 共用前缀注〕）。
+ *
+ * 两码分层：OBS_DB_OPEN_FAILED 管开库/建链失败（fail-loud——派生库坏
+ * 不拖垮宿主：构造即抛、由装载面降级跳件）；OBS_ROLLUP_CORRUPT 管查询
+ * 命中坏行（fail-loud 拒误读，同 PERSIST_DATA_CORRUPT 律——派生物宁弃
+ * 读不误读，重算即修复）。
+ * SESSION_OBSERVE_DENIED 管跨树观测门拒（03 §4.6 v1 首批第五枚
+ * sessions.observe-cross——CREDENTIALS_NAMESPACE_DENIED 同构门检拒码
+ * 先例；obs 会话维工具族 execute 内执法）。
+ * 本文件由模块公开面 index.ts 引入（注册纪律：import 发生才注册）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'OBS_DB_OPEN_FAILED',
+        module: 'obs',
+        description: 'rollup 自管库开库/建链失败 fail-loud（03 §10.8——派生库坏不拖垮宿主：构造即抛、由装载面降级跳件；含 schema 版本高于本件的拒开档与 dispose 后再调用的拒用档）',
+    },
+    {
+        code: 'OBS_ROLLUP_CORRUPT',
+        module: 'obs',
+        description: '查询命中 rollup 坏行（计数/桶值非数或负数）——fail-loud 拒误读，同 PERSIST_DATA_CORRUPT 律（派生物重算即修复）',
+    },
+    {
+        code: 'SESSION_OBSERVE_DENIED',
+        module: 'obs',
+        description: '跨树观测未开门拒（03 §4.6 v1 首批第五枚 sessions.observe-cross 门检执法——obs 会话维工具族跨树目标/全会话枚举；树内 self/tree 两档零开门〔03 §10.8 可见性分轴——观测轴树内白给〕；CREDENTIALS_NAMESPACE_DENIED 同构先例）',
+    },
+    {
+        code: 'SESSION_OBSERVE_SCOPE_INVALID',
+        module: 'obs',
+        description: '活体订阅作用域坏形拒（04 §6 e-2——ctx.events.subscribeSessionLifecycle 的 scope self/tree 档缺 sessionId 锚、或 scope 非三值词面；fail-loud 拒不静默降档——静默升 all 档等价于绕门）',
+    },
+]);

package/dist/obs/db.js

@@ -0,0 +1,115 @@
+/**
+ * obs — rollup 自管库 DDL 与开库（03 §10.8 rollup 表族条款）。
+ *
+ * 库文件 = `<dataDir>/data/obs/rollup.db`（路径由装配面算好传入——本件
+ * 不解析数据目录梯子）。开库经 persist 公开面 openAuxDatabase（物理卫生
+ * 三拍单源）；schema 主权归本件：PRAGMA user_version 自管（本库文件私有
+ * ——与主库 user_version 门禁物理分立不串档）。
+ *
+ * 版本编舞：0（全新/空）→ 单事务建全表 + 落 v1；1 → 直通；>1 → 拒开
+ * （OBS_DB_OPEN_FAILED——旧程序开新库宁拒不误读，openStore 的
+ * PERSIST_SCHEMA_TOO_NEW 同律）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { openAuxDatabase } from '../persist/index.js';
+/** rollup schema 版本（本件唯一版本位——自管，随表族演进递增） */
+export const OBS_SCHEMA_VERSION = 1;
+/**
+ * rollup 表族 DDL（两粒度三表一视图一元表；桶列恒 UTC 整点/整日对齐的
+ * epoch ms——存储客观、时区换算归呈现层）。
+ *
+ * - events_hour/events_day：全 durable 事件类型按桶计数（PRIMARY KEY
+ *   (bucket, event_type)——脏桶重算 DELETE+INSERT 的替换单元）；
+ * - usage_hour/usage_day：llm/usage 计量聚合（token 原始值；四桶必列 +
+ *   两可选列缺省 0——行级非空，坏行的拒读判据在查询面）；
+ * - deprecation_rollup_hour 视图：plugin/deprecation-used 单型投影
+ *   （03 §2 命名兑现零第二张表）；
+ * - obs_meta：水位与告警冷却键值位。
+ */
+const CANONICAL_DDL = `
+CREATE TABLE events_hour (
+  bucket INTEGER NOT NULL,
+  event_type TEXT NOT NULL,
+  count INTEGER NOT NULL,
+  PRIMARY KEY (bucket, event_type)
+);
+CREATE TABLE usage_hour (
+  bucket INTEGER NOT NULL,
+  calls INTEGER NOT NULL,
+  input INTEGER NOT NULL,
+  output INTEGER NOT NULL,
+  cache_read INTEGER NOT NULL,
+  cache_write INTEGER NOT NULL,
+  cache_write_1h INTEGER NOT NULL DEFAULT 0,
+  reasoning INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (bucket)
+);
+CREATE TABLE events_day (
+  bucket INTEGER NOT NULL,
+  event_type TEXT NOT NULL,
+  count INTEGER NOT NULL,
+  PRIMARY KEY (bucket, event_type)
+);
+CREATE TABLE usage_day (
+  bucket INTEGER NOT NULL,
+  calls INTEGER NOT NULL,
+  input INTEGER NOT NULL,
+  output INTEGER NOT NULL,
+  cache_read INTEGER NOT NULL,
+  cache_write INTEGER NOT NULL,
+  cache_write_1h INTEGER NOT NULL DEFAULT 0,
+  reasoning INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (bucket)
+);
+CREATE VIEW deprecation_rollup_hour AS
+  SELECT bucket, count FROM events_hour WHERE event_type = 'plugin/deprecation-used';
+CREATE TABLE obs_meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+/**
+ * 打开 rollup 库（开库 + 版本编舞；失败抛 OBS_DB_OPEN_FAILED——装载面
+ * 降级跳件）。
+ * @param dbPath 库文件路径（':memory:' 支持——测试位）
+ * @param warn 告警面（透传 openAuxDatabase——权限修复/WAL 降级）
+ */
+export function openRollupDatabase(dbPath, warn = (message) => console.error(message)) {
+    let db;
+    try {
+        db = openAuxDatabase(dbPath, { warn });
+    }
+    catch (err) {
+        // 开库/建链失败 fail-loud（03 §10.8——不拖垮宿主由装载面消费本码降级）
+        throw new BaseError('OBS_DB_OPEN_FAILED', `rollup 库开库失败（${dbPath}）：${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? { cause: err } : undefined);
+    }
+    const row = db.pragma('user_version', { simple: true });
+    const version = typeof row === 'number' ? row : 0;
+    try {
+        if (version > OBS_SCHEMA_VERSION) {
+            db.close();
+            throw new BaseError('OBS_DB_OPEN_FAILED', `rollup 库 ${dbPath} 的 user_version=${version} 高于本件 head=${OBS_SCHEMA_VERSION}（旧程序开新库拒开——宁拒不误读）`);
+        }
+        if (version === 0) {
+            // 全新库单事务建链（原子性——openStore 冷启动同律）
+            const bootstrap = db.transaction(() => {
+                db.exec(CANONICAL_DDL);
+                db.pragma(`user_version = ${OBS_SCHEMA_VERSION}`);
+            });
+            bootstrap();
+        }
+    }
+    catch (err) {
+        // 建链中途失败：关库再抛 OBS 码（不留半开句柄）
+        try {
+            db.close();
+        }
+        catch {
+            /* close 自身失败不掩原错误 */
+        }
+        if (err instanceof BaseError)
+            throw err;
+        throw new BaseError('OBS_DB_OPEN_FAILED', `rollup 库建链失败（${dbPath}）：${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? { cause: err } : undefined);
+    }
+    return db;
+}

package/dist/obs/index.js

@@ -0,0 +1,20 @@
+/**
+ * obs 模块公开面（L4 观测面——02 §4.1 席 #24；机制真源 03 §10.8）。
+ *
+ * 本批落码（批 18b）：rollup 自管库（经 persist aux 面开库——主库零
+ * schema 残迹、可禁用 = 文件不在场）+ 两粒度三表一视图 + 水位−1h 重叠窗
+ * 幂等摄取 + 闭日物化 + 告警「只通知不执法」（hasAudience 前置不耗冷却）
+ * + obs_query 只读工具。装载态集成（mount config alerts 注入 / 事件面
+ * 直传 Store / notify·audience 接 ctx.ui / 工具注册）归批 12 装配面。
+ *
+ * e-2 观测腿（2026-09-08——03 §10.8 会话维扩展）：SessionView 会话维视图
+ * （尾条推导粗状态 + parent_id 链树判定 + list/read/trace/status 四数据
+ * 面——纯派生读零自管库）；会话维工具族与 host 接线随 e2-2/e2-4 笔。
+ */
+import './codes.js';
+export { createObsService } from './service.js';
+export { createObsQueryTool } from './tool.js';
+export { createSessionView } from './session-view.js';
+export { createSessionTools, OBSERVE_CROSS_CAPABILITY } from './session-tools.js';
+export { OBS_SCHEMA_VERSION } from './db.js';
+export { aggregateHours, hourBucketMs, dayBucketMs, bucketClosed, HOUR_MS, DAY_MS } from './rollup.js';

package/dist/obs/rollup.js

@@ -0,0 +1,61 @@
+/** 小时毫秒 */
+export const HOUR_MS = 3_600_000;
+/** 日毫秒 */
+export const DAY_MS = 86_400_000;
+/** 取事件时刻所在 UTC 小时桶起点 */
+export function hourBucketMs(timeMs) {
+    return Math.floor(timeMs / HOUR_MS) * HOUR_MS;
+}
+/** 取事件时刻所在 UTC 日桶起点 */
+export function dayBucketMs(timeMs) {
+    return Math.floor(timeMs / DAY_MS) * DAY_MS;
+}
+/** 桶是否已闭合（桶终点 <= now——日物化只做闭日） */
+export function bucketClosed(bucketMs, nowMs, spanMs) {
+    return bucketMs + spanMs <= nowMs;
+}
+/** llm/usage 事件载荷 usage 桶字段（宽收防御——坏形按缺席折 0 不误读） */
+function usageNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+/**
+ * 单遍聚合事件流 → 小时桶计数 + llm/usage 用量累计（全 durable 事件类型
+ * 入计数；用量只认 llm/usage 型）。扫描窗按小时边界对齐时本函数产物即
+ * 各桶的完整真值——脏桶 DELETE+INSERT 整体替换即幂等自愈。
+ */
+export function aggregateHours(events) {
+    const counts = new Map();
+    const usage = new Map();
+    const touchedBuckets = new Set();
+    for (const event of events) {
+        const bucket = hourBucketMs(event.time);
+        touchedBuckets.add(bucket);
+        // 计数面：全类型（事件类型缺字坏行按 '(unknown)' 归一——计数不丢行）
+        const eventType = typeof event.type === 'string' && event.type !== '' ? event.type : '(unknown)';
+        let byType = counts.get(bucket);
+        if (!byType) {
+            byType = new Map();
+            counts.set(bucket, byType);
+        }
+        byType.set(eventType, (byType.get(eventType) ?? 0) + 1);
+        // 用量面：只认 llm/usage（05 §1.1 载荷形——usage 四桶必落、两可选上报才落）
+        if (eventType === 'llm/usage') {
+            const data = event.data;
+            const buckets = data && typeof data === 'object' ? data.usage : undefined;
+            const raw = buckets && typeof buckets === 'object' ? buckets : {};
+            let agg = usage.get(bucket);
+            if (!agg) {
+                agg = { calls: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cacheWrite1h: 0, reasoning: 0 };
+                usage.set(bucket, agg);
+            }
+            agg.calls += 1;
+            agg.input += usageNumber(raw.input);
+            agg.output += usageNumber(raw.output);
+            agg.cacheRead += usageNumber(raw.cacheRead);
+            agg.cacheWrite += usageNumber(raw.cacheWrite);
+            agg.cacheWrite1h += usageNumber(raw.cacheWrite1h);
+            agg.reasoning += usageNumber(raw.reasoning);
+        }
+    }
+    return { counts, usage, touchedBuckets };
+}