@1agents/session-reader 0.3.0 → 0.4.0

package/README.md

@@ -22,7 +22,9 @@ npm install -g @1agents/session-reader  # 作为 1session 命令
 npx @1agents/session-reader list      # 不安装直接用
 ```
 
-要求 Node.js >= 22.5（依赖内置的 `node:sqlite`），零运行时依赖。
+要求 Node.js >= 22.5（依赖内置的 `node:sqlite`）。
+唯一的运行时依赖是自家的 [`@1agents/dreammate-network`](https://github.com/scottzx/dreammate-network)
+——L0 协议定义，12 kB，本身零依赖——`npm install` 会自动带上，不需要单独装。
 
 ## 内置 skill：一条命令装到三家智能体
 
@@ -402,6 +404,52 @@ $ 1session graph ca8325e1
 
 运行时捕获：若环境注入了 `SESSION_READER_CALLER_SESSION`，调用当下就直接落边（`observed / runtime:caller-env`），无需事后从历史里恢复。
 
+## `1session serve`：接入 DreamMate Network
+
+把本地 Read Plane 原样暴露成网络能力——`1session overview <id>` 成为 `sessions.read`。
+**不重新实现索引与事实层**，只是换一个调用入口。不引第三方 HTTP 框架，只用 `node:http`。
+
+```bash
+1session serve                                  # 默认 127.0.0.1:7777
+1session serve --host 100.x.x.x --token <t>     # 暴露到 tailnet
+```
+
+```
+GET /manifest              Node Manifest（dreammate-network node.schema.json）
+GET /health
+GET /v1/node               同 /manifest，本 Service 前缀下的同一份文档
+GET /v1/sessions           ?limit&scope&since&provider
+GET /v1/sessions/:id       会话概要
+GET /v1/sessions/:id/turns 逐轮概要
+GET /v1/search             ?q=&scope=&since=&limit=&provider=&kind=&regex=&case=
+GET /v1/graph/:id          会话之间的引用关系
+```
+
+声明的能力：`sessions.list` `sessions.read` `sessions.turns` `sessions.search` `sessions.graph`。
+
+每个会话都带上网络内的地址：
+
+```
+session://<node>/<runtime>/<session_id>
+session://Scott-Mac.local/claude/87f7a60a-a86e-49c5-b711-e463156a5420
+```
+
+**读取即落边。** 请求带 `X-Caller-Session: <调用方会话>` 时，读取当下就写入
+`调用方 --references--> 目标`，与 CLI 的 `SESSION_READER_CALLER_SESSION` 是同一条路径。
+两端都必须是本地已索引的会话，否则静默跳过——悬空边比没有边更糟。
+
+**节点身份**落在 `~/.1agents/session-reader/node.json`，首次启动生成，重启不变；
+`DREAMMATE_NODE_ID` / `DREAMMATE_NODE_NAME` / `DREAMMATE_TAILSCALE_NAME` 可覆盖。
+
+**只读、且默认只监听 loopback。** 会话原文含源码、shell 历史和恰好滚过屏幕的密钥，
+所以走出本机必须是一个刻意动作：显式 `--host`，并且最好配 `--token`（`Authorization: Bearer`）。
+非 loopback 且无 token 时启动会告警。非 GET 一律 405。
+
+> 协议定义来自 [`@1agents/dreammate-network`](https://github.com/scottzx/dreammate-network)（L0）。
+> `src/serve/node.ts` 直接 import 它的类型，不再本地抄一份——单向依赖 L2 → L0 是允许的，
+> 而共用同一份定义才谈得上「公共语言」。**schema 是唯一事实源，改类型先去改那个包。**
+> `/manifest` 的 `metadata.protocol_version` 报告本服务遵循的协议版本。
+
 ## 测试
 
 ```bash

package/dist/bin/1session.js

@@ -24,6 +24,8 @@ const USAGE = `1session — cross-agent session Read Plane
   1session workspace [path] [--since 24h] [--limit <n>] [--digest] [--focus <f>] [--json]
   1session index [<session-id>] [--all] [--scope <path>|cwd|global] [--force] [--since 30d]  建立/刷新索引
   1session graph <session-id> [--json]                 会话之间的引用关系
+  1session serve [--port 7777] [--host 127.0.0.1] [--token <t>]
+                          起 HTTP Service，把本机会话接入 DreamMate Network
   1session skill install|status|uninstall [--agent claude,codex,antigravity]
                           [--copy] [--force] [--dry-run] [--json]  装到三家智能体的 skills 目录
   1session search <query> [--scope <path>|cwd|global] [--since 24h] [--limit n] [--provider name]
@@ -423,6 +425,18 @@ async function main() {
                 : `${row.id} 尚无关系边（没有任何会话通过 1session 查过它，它也没查过别人）`);
             break;
         }
+        case 'serve': {
+            const { serve } = await import('../src/serve/http.js');
+            await serve({
+                port: num(flags.port) ?? 7777,
+                ...(str(flags.host) ? { host: str(flags.host) } : {}),
+                ...(str(flags.token) ? { token: str(flags.token) } : {}),
+                ...(str(flags['base-url']) ? { baseUrl: str(flags['base-url']) } : {}),
+            });
+            // The server owns the process from here; nothing after this resolves.
+            await new Promise(() => { });
+            break;
+        }
         case 'skill': {
             const { describeState, installSkill, skillStatus, uninstallSkill, bundledSkillDir, } = await import('../src/skill.js');
             const agents = str(flags.agent)

package/dist/src/index.d.ts

@@ -18,3 +18,5 @@ export { captureRuntimeEdge, deriveEdges, edgeEvidence, edgesOf, invocationsOf,
 export { deriveFacts } from './store/facts.js';
 export { EDGE_VERSION, EXTRACTOR_VERSION, PARSER_VERSION, SCHEMA_VERSION, } from './store/schema.js';
 export { SKILL_NAME, agentTargets, bundledSkillDir, describeState, installSkill, skillStatus, uninstallSkill, type AgentStatus, type AgentTarget, type EntryState, type InstallMode, type InstallOptions, type InstallResult, type SkillAgent, type UninstallResult, } from './skill.js';
+export { buildManifest, nodeIdentity, nodeIdentityPath, sessionUri, SESSION_CAPABILITIES, type AccessDescriptor, type NetworkService, type NodeManifest, } from './serve/node.js';
+export { createServer, serve, type ServeOptions } from './serve/http.js';

package/dist/src/index.js

@@ -16,3 +16,5 @@ export { captureRuntimeEdge, deriveEdges, edgeEvidence, edgesOf, invocationsOf,
 export { deriveFacts } from './store/facts.js';
 export { EDGE_VERSION, EXTRACTOR_VERSION, PARSER_VERSION, SCHEMA_VERSION, } from './store/schema.js';
 export { SKILL_NAME, agentTargets, bundledSkillDir, describeState, installSkill, skillStatus, uninstallSkill, } from './skill.js';
+export { buildManifest, nodeIdentity, nodeIdentityPath, sessionUri, SESSION_CAPABILITIES, } from './serve/node.js';
+export { createServer, serve } from './serve/http.js';

package/dist/src/serve/http.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `1session serve` — session-reader 作为 DreamMate Network 的第一个标准 Service。
+ *
+ * 它把本地 Read Plane 原样暴露成网络能力：`1session overview <id>` 成为
+ * `sessions.read`。**不重新实现索引与事实层**，只是换一个调用入口。
+ *
+ * 零运行时依赖：只用 node:http。
+ */
+import http from 'node:http';
+export interface ServeOptions {
+    port?: number;
+    /**
+     * Defaults to loopback. Session transcripts contain source code, shell
+     * history and whatever secrets happened to scroll past, so going beyond this
+     * machine has to be a deliberate act — pass the tailnet address explicitly.
+     */
+    host?: string;
+    /** When set, every request must carry it as `Authorization: Bearer <token>`. */
+    token?: string;
+    /** Advertised base url, when behind a proxy or a different tailnet name. */
+    baseUrl?: string;
+}
+export declare function createServer(options?: ServeOptions): http.Server;
+export declare function serve(options?: ServeOptions): Promise<http.Server>;

package/dist/src/serve/http.js

@@ -0,0 +1,181 @@
+/**
+ * `1session serve` — session-reader 作为 DreamMate Network 的第一个标准 Service。
+ *
+ * 它把本地 Read Plane 原样暴露成网络能力：`1session overview <id>` 成为
+ * `sessions.read`。**不重新实现索引与事实层**，只是换一个调用入口。
+ *
+ * 零运行时依赖：只用 node:http。
+ */
+import http from 'node:http';
+import { listRecentSessions, loadSession } from '../resolver.js';
+import { buildOverview } from '../overview.js';
+import { summarizeTurns } from '../turns.js';
+import { searchSessions } from '../search.js';
+import { canonicalizePath } from '../util/paths.js';
+import { buildManifest, nodeIdentity, sessionUri } from './node.js';
+const json = (res, status, body) => {
+    const payload = JSON.stringify(body, null, 2);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(payload),
+    });
+    res.end(payload);
+};
+const q = (ctx, name) => ctx.url.searchParams.get(name) ?? undefined;
+const qn = (ctx, name) => {
+    const raw = q(ctx, name);
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : undefined;
+};
+/**
+ * `?scope=` is a path whose subtree is included; omitting it means the whole
+ * machine. The CLI defaults to the cwd instead, which is meaningless for a
+ * long-running server.
+ */
+const scopeOf = (ctx) => {
+    const scope = q(ctx, 'scope');
+    return scope && scope !== 'global' ? canonicalizePath(scope) : undefined;
+};
+/** Records `caller --references--> target` while the read is happening. */
+async function noteRead(verb, target, caller) {
+    if (!caller)
+        return;
+    try {
+        const { openStore } = await import('../store/db.js');
+        const { captureRuntimeEdge } = await import('../store/edges.js');
+        captureRuntimeEdge(await openStore(), verb, target, caller);
+    }
+    catch {
+        // An edge is a nice-to-have; never fail the read over it.
+    }
+}
+async function route(ctx) {
+    const { pathname } = ctx.url;
+    const identity = nodeIdentity();
+    if (pathname === '/health') {
+        return { status: 200, body: { status: 'ok', node_id: identity.node_id, service: 'session-registry' } };
+    }
+    // `/manifest` is the network-wide contract; `/v1/node` is the same document
+    // under this service's own prefix.
+    if (pathname === '/manifest' || pathname === '/v1/node') {
+        return { status: 200, body: buildManifest(ctx.url.origin) };
+    }
+    if (pathname === '/v1/sessions') {
+        const refs = await listRecentSessions({
+            limit: qn(ctx, 'limit') ?? 20,
+            workspace: scopeOf(ctx),
+            since: q(ctx, 'since'),
+            provider: q(ctx, 'provider'),
+            useIndex: true,
+        });
+        return {
+            status: 200,
+            body: {
+                node: identity.name,
+                sessions: refs.map((ref) => ({ ...ref, uri: sessionUri(identity.name, ref.provider, ref.id) })),
+            },
+        };
+    }
+    const detail = /^\/v1\/sessions\/([^/]+)(\/turns)?$/.exec(pathname);
+    if (detail) {
+        const id = decodeURIComponent(detail[1]);
+        const wantTurns = detail[2] !== undefined;
+        const session = await loadSession(id, { useIndex: true });
+        await noteRead(wantTurns ? 'turns' : 'overview', id, ctx.caller);
+        const uri = sessionUri(identity.name, session.ref.provider, session.ref.id);
+        return wantTurns
+            ? { status: 200, body: { uri, turns: summarizeTurns(session) } }
+            : { status: 200, body: { uri, ...buildOverview(session) } };
+    }
+    if (pathname === '/v1/search') {
+        const query = q(ctx, 'q') ?? q(ctx, 'query');
+        if (!query)
+            return { status: 400, body: { error: 'missing ?q=' } };
+        const hits = await searchSessions(query, {
+            workspace: scopeOf(ctx),
+            since: q(ctx, 'since'),
+            limit: qn(ctx, 'limit'),
+            provider: q(ctx, 'provider'),
+            kinds: q(ctx, 'kind')?.split(',').map((k) => k.trim()).filter(Boolean),
+            regex: q(ctx, 'regex') === 'true',
+            caseSensitive: q(ctx, 'case') === 'true',
+            context: qn(ctx, 'context'),
+            maxPerSession: qn(ctx, 'max-hits'),
+            useIndex: true,
+        });
+        return {
+            status: 200,
+            body: {
+                query,
+                total: hits.reduce((sum, hit) => sum + hit.totalMatches, 0),
+                hits: hits.map((hit) => ({
+                    ...hit,
+                    uri: sessionUri(identity.name, hit.session.provider, hit.session.id),
+                })),
+            },
+        };
+    }
+    const graph = /^\/v1\/graph\/([^/]+)$/.exec(pathname);
+    if (graph) {
+        const id = decodeURIComponent(graph[1]);
+        const { openStore } = await import('../store/db.js');
+        const { edgeEvidence, edgesOf } = await import('../store/edges.js');
+        const { findSessionRow } = await import('../store/read.js');
+        await loadSession(id, { useIndex: true }); // make sure it is indexed first
+        await noteRead('graph', id, ctx.caller);
+        const db = await openStore();
+        const row = findSessionRow(db, id);
+        if (!row)
+            return { status: 404, body: { error: `session not found: ${id}` } };
+        const edges = edgesOf(db, row.id).map((edge) => ({
+            ...edge,
+            evidence: edgeEvidence(db, edge.from, edge.to, edge.relation),
+        }));
+        return { status: 200, body: { session: row.id, edges } };
+    }
+    return { status: 404, body: { error: `no route: ${pathname}` } };
+}
+export function createServer(options = {}) {
+    return http.createServer((req, res) => {
+        void (async () => {
+            try {
+                if (req.method !== 'GET' && req.method !== 'HEAD') {
+                    return json(res, 405, { error: 'read-only service: GET only' });
+                }
+                const url = new URL(req.url ?? '/', options.baseUrl ?? `http://${req.headers.host ?? 'localhost'}`);
+                if (options.token) {
+                    const bearer = /^Bearer (.+)$/.exec(req.headers.authorization ?? '')?.[1];
+                    if (bearer !== options.token)
+                        return json(res, 401, { error: 'unauthorized' });
+                }
+                const caller = req.headers['x-caller-session'];
+                const { status, body } = await route({
+                    url,
+                    caller: typeof caller === 'string' ? caller : undefined,
+                });
+                json(res, status, body);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                // A bad session id reads as "not found", not as a server fault.
+                json(res, /not found|missing|no session/i.test(message) ? 404 : 500, { error: message });
+            }
+        })();
+    });
+}
+export async function serve(options = {}) {
+    const host = options.host ?? '127.0.0.1';
+    const server = createServer(options);
+    await new Promise((resolve) => server.listen(options.port ?? 7777, host, resolve));
+    const { port } = server.address();
+    const identity = nodeIdentity();
+    console.log(`1session serve — node ${identity.name} (${identity.node_id})`);
+    console.log(`  http://${host}:${port}/manifest`);
+    console.log(`  capabilities: sessions.list, sessions.read, sessions.turns, sessions.search, sessions.graph`);
+    if (host !== '127.0.0.1' && host !== 'localhost' && !options.token) {
+        console.warn(`  ⚠️  绑定在 ${host} 且未设置 --token：会话原文（代码、shell 历史、密钥）将对该网络开放。`);
+    }
+    return server;
+}

package/dist/src/serve/node.d.ts

@@ -0,0 +1,26 @@
+import { PROTOCOL_VERSION, type AccessDescriptor, type NodeManifest, type Service as NetworkService, type SessionURI } from '@1agents/dreammate-network';
+export { PROTOCOL_VERSION };
+export type { AccessDescriptor, NetworkService, NodeManifest };
+/** Where the node identity is kept, next to the index db. */
+export declare function nodeIdentityPath(): string;
+interface StoredIdentity {
+    node_id: string;
+    name: string;
+    type: string;
+}
+/**
+ * A stable node id that survives restarts, generated on first use and kept in
+ * `~/.1agents/session-reader/node.json`.
+ *
+ * `DREAMMATE_NODE_ID` / `DREAMMATE_NODE_NAME` override it without touching the
+ * file, which is what a container or a second instance on one host wants.
+ */
+export declare function nodeIdentity(): StoredIdentity;
+/**
+ * The capabilities this Service answers for. Names are the network-facing
+ * spelling of the CLI verbs: `1session overview` is `sessions.read`.
+ */
+export declare const SESSION_CAPABILITIES: readonly ["sessions.list", "sessions.read", "sessions.turns", "sessions.search", "sessions.graph"];
+export declare function buildManifest(baseUrl: string): NodeManifest;
+/** `session://<node>/<runtime>/<session_id>` — the network-wide address of one session. */
+export declare function sessionUri(nodeName: string, provider: string, id: string): SessionURI;

package/dist/src/serve/node.js

@@ -0,0 +1,89 @@
+/**
+ * Node identity and Manifest — session-reader 作为 DreamMate Network 的第一个标准 Service。
+ *
+ * 协议类型直接来自 L0 包 `@1agents/dreammate-network`，不再本地抄一份：
+ * 单向依赖 L2 → L0 是允许的，而共用同一份定义才谈得上「公共语言」。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { PROTOCOL_VERSION, } from '@1agents/dreammate-network';
+export { PROTOCOL_VERSION };
+/* ---------- 身份 ---------- */
+/** Where the node identity is kept, next to the index db. */
+export function nodeIdentityPath() {
+    return path.join(os.homedir(), '.1agents', 'session-reader', 'node.json');
+}
+const PLATFORM_TYPE = {
+    darwin: 'macos',
+    linux: 'linux',
+    win32: 'windows',
+};
+/**
+ * A stable node id that survives restarts, generated on first use and kept in
+ * `~/.1agents/session-reader/node.json`.
+ *
+ * `DREAMMATE_NODE_ID` / `DREAMMATE_NODE_NAME` override it without touching the
+ * file, which is what a container or a second instance on one host wants.
+ */
+export function nodeIdentity() {
+    const type = PLATFORM_TYPE[process.platform] ?? process.platform;
+    const envId = process.env.DREAMMATE_NODE_ID?.trim();
+    const envName = process.env.DREAMMATE_NODE_NAME?.trim();
+    if (envId && envName)
+        return { node_id: envId, name: envName, type };
+    const file = nodeIdentityPath();
+    let stored = {};
+    try {
+        stored = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        // First run, or an unreadable file we are about to overwrite.
+    }
+    if (!stored.node_id) {
+        stored = { node_id: `node_${randomUUID().replace(/-/g, '').slice(0, 12)}`, name: os.hostname(), type };
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, `${JSON.stringify(stored, null, 2)}\n`);
+    }
+    return {
+        node_id: envId ?? stored.node_id,
+        name: envName ?? stored.name ?? os.hostname(),
+        type,
+    };
+}
+/* ---------- Manifest ---------- */
+/**
+ * The capabilities this Service answers for. Names are the network-facing
+ * spelling of the CLI verbs: `1session overview` is `sessions.read`.
+ */
+export const SESSION_CAPABILITIES = [
+    'sessions.list',
+    'sessions.read',
+    'sessions.turns',
+    'sessions.search',
+    'sessions.graph',
+];
+export function buildManifest(baseUrl) {
+    const identity = nodeIdentity();
+    return {
+        ...identity,
+        tailscale_name: process.env.DREAMMATE_TAILSCALE_NAME?.trim() ?? identity.name,
+        online: true,
+        metadata: { protocol_version: PROTOCOL_VERSION },
+        services: [
+            {
+                id: 'session-registry',
+                name: 'session-reader',
+                kind: 'session_registry',
+                capabilities: [...SESSION_CAPABILITIES],
+                resources: [{ scheme: 'session', description: 'session://<node>/<runtime>/<session_id>' }],
+                access: [{ protocol: 'http', base_url: `${baseUrl}/v1` }],
+            },
+        ],
+    };
+}
+/** `session://<node>/<runtime>/<session_id>` — the network-wide address of one session. */
+export function sessionUri(nodeName, provider, id) {
+    return `session://${nodeName}/${provider}/${id}`;
+}

package/dist/src/store/edges.d.ts

@@ -27,7 +27,13 @@ export declare function deriveEdges(db: DatabaseSync, id: string, session: Norma
  * Injected by a hook or the ACP context as `SESSION_READER_CALLER_SESSION`;
  * absent everywhere else, in which case nothing is written.
  */
-export declare function captureRuntimeEdge(db: DatabaseSync, verb: string, target: string): void;
+export declare function captureRuntimeEdge(db: DatabaseSync, verb: string, target: string, 
+/**
+ * Who is doing the reading. Defaults to the CLI's injected caller; `1session
+ * serve` passes the `X-Caller-Session` header instead, so one process can
+ * serve several callers without going through the environment.
+ */
+callerId?: string | undefined): void;
 export interface EdgeView {
     from: string;
     to: string;

package/dist/src/store/edges.js

@@ -102,8 +102,14 @@ export function deriveEdges(db, id, session) {
  * Injected by a hook or the ACP context as `SESSION_READER_CALLER_SESSION`;
  * absent everywhere else, in which case nothing is written.
  */
-export function captureRuntimeEdge(db, verb, target) {
-    const caller = process.env.SESSION_READER_CALLER_SESSION?.trim();
+export function captureRuntimeEdge(db, verb, target, 
+/**
+ * Who is doing the reading. Defaults to the CLI's injected caller; `1session
+ * serve` passes the `X-Caller-Session` header instead, so one process can
+ * serve several callers without going through the environment.
+ */
+callerId = process.env.SESSION_READER_CALLER_SESSION) {
+    const caller = callerId?.trim();
     const relation = VERB_RELATION[verb];
     if (!caller || !relation)
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agents/session-reader",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Read Plane: cross-agent session discovery, turn inspection, workspace aggregation and distillation from raw local session files.",
   "keywords": [
     "claude-code",
@@ -55,5 +55,8 @@
     "@types/node": "^22.10.2",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "@1agents/dreammate-network": "^0.1.0"
   }
 }