@dsh-edge/dsh-edge-agent 0.0.0-stage → 0.1.2

package/lib/dsh-adapter/host-llm-trace.js

@@ -0,0 +1,344 @@
+/**
+ * host-llm-trace — §7.144 记录**宿主 provider** 发出的 LLM 调用
+ *
+ * ## 为什么需要这个模块（主人现场发现）
+ *
+ * 主人在 Edge 面板看到「本轮走云端了，但 LLM 调用里没有云端模型」。查审计链
+ * 得到的硬事实是：那一轮**确实**判成了 CLOUD（jev 置信 0.83 < 门限 0.85 →
+ * 落到本地 LLM 分类器 → `llm-classified:cloud`），但整轮**零条**
+ * `llm.cloud.*` 事件 —— 只有 `llm.local.*`。
+ *
+ * 原因不是路由错了，是**观测漏了一跳**：
+ *
+ * - `config/edge.json` 的 `llm.cloud` 是 **delegate 模式**（`baseUrl` 空 +
+ *   `delegate: true`，§7.100）：CLOUD 请求**转发给宿主 profile 已配置的模型
+ *   提供商**（桌面 GUI 里选的那个，如 `qwen-token-plan-cn`），凭据全归宿主。
+ * - 于是主对话的请求**不经过本项目的 cloud adapter** ⇒ 没有 `llm.cloud.*`
+ *   审计事件，也没有 trace ⇒ 面板里云端模型整条缺席。
+ * - 面板是诚实的（它没编造），但**不完整** —— 主人看到的是「没发生过」，
+ *   实际是「没被记下来」。这正是 §7.129 最怕的那种误导：不是显示了一件
+ *   没发生的事，而是**漏显示**了一件真发生的事。
+ *
+ * ## 补在哪一跳
+ *
+ * 宿主的 `llm/stream` 事件带**完整信封**（`GenerateOptions`：provider /
+ * model / messages / system / tools / …），响应侧带**完整 chunk 流**
+ * （text-delta / block-end / tool-call-delta / usage / finish）。所以宿主
+ * provider 的这一跳**本来就完全可观测** —— 只是没人接。
+ *
+ * 本模块提供那一跳的记录能力；接线在 `input-guard` 的 `llm/stream` 钩子
+ * （那里已经握有 sessionId → 会话状态的映射，能区分「边缘会话」与「标准
+ * 模式会话」）。
+ *
+ * ## 与 adapter 记的那几条如何不重复
+ *
+ * 本项目自管两个池，provider 名固定：
+ *
+ * - `local-llm`（local adapter 注册名）
+ * - `cloud-llm`（cloud adapter 注册名；delegate 模式下它把请求**再**转发给
+ *   宿主 provider，那一跳的 provider 名是宿主自己的 ⇒ 正好被这里记到）
+ *
+ * 凡是 provider 属于自管池的调用，**adapter 自己已经记过**（REQ + RESP），
+ * 这里跳过 —— 否则面板上会出现同一通调用记两遍。
+ *
+ * ## 记什么
+ *
+ * | 侧 | 内容 |
+ * |---|---|
+ * | REQ | 宿主看到的信封：provider / model / messages / system / tools / 参数 |
+ * | RESP | 完整正文（block-end 优先）+ 工具调用 + finish reason + usage |
+ *
+ * `body` 快照是**宿主层信封**，不是 provider 的 wire body —— 后者在 adapter
+ * 内部，宿主这一跳看不见。面板上 provider/model 字段会显示宿主 provider
+ * 名（如 `qwen-token-plan-cn/deepseek-v4.1-flash`），一眼能认出「这是云端
+ * 模型那一条」。
+ *
+ * @module dsh-edge-agent/host-llm-trace
+ */
+import { buildRequestTrace, buildResponseTrace, emitTrace, } from './llm-trace.js';
+/* ── provider 判据 ───────────────────────────────────────────────────────── */
+/**
+ * 本项目自管池的 provider 名（adapter 注册名）。
+ *
+ * 这两个名字来自 adapter 的注册表（cloud adapter 的 `providers` 默认
+ * `['cloud-llm']`），不是配置项 —— 改成别的名字会破坏 §7.100 的 delegate
+ * 语义，所以这里写死成常量。
+ */
+export const OWN_POOL_PROVIDERS = ['local-llm', 'cloud-llm'];
+/**
+ * §7.171 (2026-11-10): 「本地池 delegate 转发」标记。
+ *
+ * `local-llm` 走 delegate 时会把请求转发给宿主提供商（§7.171 新增），转发时
+ * `provider` 变成了**目标** provider（不再是 `local-llm`）⇒ `host-egress-guard`
+ * 会把它当成「宿主原生 provider 的出网那一跳」⇒ 按 §7.131 口径裁掉本地段历史。
+ *
+ * 但本地池的口径恰恰相反：**带全部历史**（§7.131 的不对称规则第一条）。
+ * ⇒ 转发时打这个标记，出网守卫看到它就放行（不裁）。
+ *
+ * 打在 options 上是安全的：宿主 `LlmRuntime.stream` 走
+ * `{...options, ...resolvedConfig}` 的 spread（`@deepseek-ai/dsh-llm`
+ * `lib/index.js` 的 `adapterStream`），未知字段原样透传，不会被拒。
+ *
+ * 住在这里（而不是 adapter 里）是因为**打标的一方与读标的一方分属两个模块**：
+ * `cloud-llm-adapter.ts`（打）↔ `host-egress-guard.ts`（读）。与
+ * `OWN_POOL_PROVIDERS` 同处一地 —— 自有池相关的判据只有这一份事实源。
+ */
+export const LOCAL_POOL_FORWARD_MARKER = '__edgeLocalPoolForward';
+/**
+ * 这个 provider 是不是本项目自己管的池？
+ *
+ * 是 ⇒ adapter 已经记过这次调用，这里必须跳过（否则同一通调用记两遍）。
+ * 否 ⇒ 宿主自己的 provider（delegate 出去的云池），**这里要补记**。
+ */
+export function isOwnPoolProvider(provider, own = OWN_POOL_PROVIDERS) {
+    if (typeof provider !== 'string' || provider.length === 0)
+        return false;
+    return own.includes(provider);
+}
+/**
+ * 构造宿主调用的 request trace。
+ *
+ * `rawBody` 记的是**宿主层信封**（provider / model / messages / system /
+ * tools / 参数）—— 宿主这一跳能看到的全部。provider 的 wire body 在 adapter
+ * 内部，从这里看不见（那一侧由 adapter 自己记）。
+ */
+export function buildHostRequestTrace(input) {
+    const r = input.request;
+    return buildRequestTrace({
+        sessionId: r.sessionId,
+        provider: r.provider,
+        model: r.model,
+        system: r.system,
+        messages: r.messages,
+        tools: r.tools,
+        params: r.params,
+        rawBody: {
+            provider: r.provider,
+            model: r.model,
+            messages: r.messages,
+            ...(r.system !== undefined ? { system: r.system } : {}),
+            ...(r.tools !== undefined ? { tools: r.tools } : {}),
+            ...(r.params !== undefined ? { params: r.params } : {}),
+        },
+        config: input.config,
+    });
+}
+/**
+ * 单次响应累积的字符上限。
+ *
+ * 观测路径不能变成故障源：异常大的响应（长文档粘贴 + 长工具回显）不能把
+ * 内存吃穿。超过上限后只保留前面这段，并在 trace 里如实标注（正文长度仍
+ * 按**真实**长度报，不假装完整）。
+ */
+const MAX_ACCUM_CHARS = 200_000;
+/**
+ * 从宿主的 chunk 流里累积一次响应。
+ *
+ * 正文优先取 `block-end` 的 `block.text`（宿主在 block 结束时给的是**全文**
+ * 比逐个 text-delta 拼更准）；拿不到才回落累积 delta。
+ */
+export class HostResponseAccumulator {
+    text = '';
+    textTruncated = false;
+    calls = new Map();
+    finishReason;
+    usage;
+    /** 吃掉一个 chunk。永不抛 —— 畸形 chunk 直接忽略。 */
+    push(chunk) {
+        if (chunk === null || typeof chunk !== 'object')
+            return;
+        const c = chunk;
+        switch (c.type) {
+            case 'text-delta': {
+                if (typeof c.text === 'string')
+                    this.appendText(c.text);
+                return;
+            }
+            case 'block-end': {
+                const block = c.block;
+                if (block && block.type === 'text' && typeof block.text === 'string') {
+                    // block-end 给的是**整块正文** —— 直接覆盖累积值（多 block 时以
+                    // 最后一个文本 block 为准；agent-loop 的回答基本是单块）。
+                    this.text = block.text.slice(0, MAX_ACCUM_CHARS);
+                    this.textTruncated = block.text.length > MAX_ACCUM_CHARS;
+                }
+                return;
+            }
+            case 'tool-call-delta': {
+                const index = typeof c.index === 'number' ? c.index : this.calls.size;
+                const cur = this.calls.get(index) ?? { name: '', args: '' };
+                if (typeof c.id === 'string' && c.id.length > 0)
+                    cur.id = c.id;
+                if (typeof c.name === 'string' && c.name.length > 0)
+                    cur.name = c.name;
+                if (typeof c.argumentsDelta === 'string') {
+                    cur.args = (cur.args + c.argumentsDelta).slice(0, MAX_ACCUM_CHARS);
+                }
+                this.calls.set(index, cur);
+                return;
+            }
+            case 'usage': {
+                const u = c.usage;
+                if (u && typeof u === 'object') {
+                    const inputTokens = typeof u.inputTokens === 'number' ? u.inputTokens : undefined;
+                    const outputTokens = typeof u.outputTokens === 'number' ? u.outputTokens : undefined;
+                    this.usage = {
+                        promptTokens: inputTokens,
+                        completionTokens: outputTokens,
+                        totalTokens: inputTokens !== undefined && outputTokens !== undefined
+                            ? inputTokens + outputTokens
+                            : undefined,
+                    };
+                }
+                return;
+            }
+            case 'finish': {
+                // 宿主的 FinishReason 是**对象**（{ kind: 'stop' } / { kind: 'tool-calls' } …），
+                // 直接 stringify 会变成 '{"kind":"stop"}' —— 面板上难看且不可比。优先取 kind。
+                const reason = c.reason;
+                if (typeof reason === 'string')
+                    this.finishReason = reason;
+                else if (reason !== null && typeof reason === 'object') {
+                    const kind = reason.kind;
+                    this.finishReason = typeof kind === 'string' ? kind : safeStringify(reason);
+                }
+                else if (reason !== undefined)
+                    this.finishReason = safeStringify(reason);
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    appendText(text) {
+        if (this.text.length >= MAX_ACCUM_CHARS) {
+            this.textTruncated = true;
+            return;
+        }
+        const room = MAX_ACCUM_CHARS - this.text.length;
+        if (text.length > room) {
+            this.text += text.slice(0, room);
+            this.textTruncated = true;
+            return;
+        }
+        this.text += text;
+    }
+    /** 当前累积结果。 */
+    snapshot() {
+        const toolCalls = [...this.calls.entries()]
+            .sort((a, b) => a[0] - b[0])
+            .map(([, v]) => {
+            const call = { name: v.name };
+            if (v.id !== undefined)
+                call.id = v.id;
+            if (v.args.length > 0)
+                call.arguments = v.args;
+            return call;
+        });
+        const out = { content: this.text, toolCalls };
+        if (this.finishReason !== undefined)
+            out.finishReason = this.finishReason;
+        if (this.usage !== undefined)
+            out.usage = this.usage;
+        return out;
+    }
+    /** 累积时是否撞到上限（面板据此说明正文不全）。 */
+    get truncated() {
+        return this.textTruncated;
+    }
+}
+/** 构造宿主调用的 response trace。 */
+export function buildHostResponseTrace(input) {
+    const s = input.snapshot;
+    return buildResponseTrace({
+        sessionId: input.sessionId,
+        provider: input.provider,
+        model: input.model,
+        durationMs: input.durationMs,
+        finishReason: s.finishReason,
+        content: s.content,
+        toolCalls: s.toolCalls,
+        usage: s.usage,
+        rawBody: {
+            content: s.content,
+            tool_calls: s.toolCalls,
+            finish_reason: s.finishReason,
+            usage: s.usage,
+        },
+        config: input.config,
+    });
+}
+/**
+ * 一次宿主 provider 调用的记录器。
+ *
+ * 构造即记 REQ；`wrap()` 包住 chunk 流，流结束时记 RESP。REQ/RESP 共用
+ * 同一个 callId ⇒ 面板上仍然「上请求、下响应」成对显示。
+ */
+export class HostCallRecorder {
+    options;
+    accumulator = new HostResponseAccumulator();
+    startedAt = Date.now();
+    responseEmitted = false;
+    constructor(options) {
+        this.options = options;
+        try {
+            const { sink, config, request, callId } = options;
+            if (!config.enabled || !config.includeRequest)
+                return;
+            const trace = buildHostRequestTrace({ request, config });
+            emitTrace(sink, 'REQ', 'host-llm-trace LLM_REQUEST', trace, undefined, {
+                toolCount: request.tools?.length ?? 0,
+                callId,
+            });
+        }
+        catch { /* 观测失败不拖垮主链路 */ }
+    }
+    /** 包住 chunk 流：边转发边累积，流结束记 RESP。 */
+    async *wrap(stream) {
+        try {
+            for await (const chunk of stream) {
+                try {
+                    this.accumulator.push(chunk);
+                }
+                catch { /* 单个 chunk 畸形不影响主链路 */ }
+                yield chunk;
+            }
+        }
+        finally {
+            this.emitResponse();
+        }
+    }
+    emitResponse() {
+        if (this.responseEmitted)
+            return;
+        this.responseEmitted = true;
+        try {
+            const { sink, config, request, callId } = this.options;
+            if (!config.enabled || !config.includeResponse)
+                return;
+            const trace = buildHostResponseTrace({
+                sessionId: request.sessionId,
+                provider: request.provider,
+                model: request.model,
+                snapshot: this.accumulator.snapshot(),
+                durationMs: Date.now() - this.startedAt,
+                config,
+            });
+            emitTrace(sink, 'RESP', 'host-llm-trace LLM_RESPONSE', trace, undefined, {
+                toolCount: request.tools?.length ?? 0,
+                callId,
+            });
+        }
+        catch { /* 观测失败不拖垮主链路 */ }
+    }
+}
+/* ── 小工具 ───────────────────────────────────────────────────────────────── */
+/** 永不抛的 stringify（finish reason 可能是对象）。 */
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return '[unserializable]';
+    }
+}

package/lib/dsh-adapter/http-api-routes.d.ts

@@ -0,0 +1,61 @@
+/**
+ * http-api-routes — pure route table for the dsh-edge-agent HTTP API.
+ *
+ * Why a separate module? Adding new endpoints used to mean appending a
+ * branch to `handleRequest()`'s if/else chain. With ~13 endpoints, that
+ * chain got long enough to make the dispatcher itself hard to read —
+ * and impossible to test in isolation. Extracting route definitions lets:
+ *
+ *   1. unit tests pin the exact set of routes + their auth/summary;
+ *   2. the dispatcher shrink to a generic "match → check auth → invoke";
+ *   3. OpenAPI spec generation iterate the same source of truth.
+ *
+ * Design choices:
+ *   - Patterns use `{name}` placeholders. The matcher compiles each
+ *     pattern into a RegExp once (at first match) and caches it.
+ *   - Auth is `public` (no bearer) or `bearer` (require `Authorization`).
+ *     We deliberately do NOT expose CORS / origin checks here — the
+ *     dual-entry architecture document keeps CORS as a v2 concern
+ *     (docs/dual-entry-architecture.md §7.1).
+ *   - The handler signature is intentionally minimal: `(ctx, params)`.
+ *     All HTTP plumbing (reqId, start, body, accessLog) is built into
+ *     `ctx` so handlers don't have to know about the dispatcher.
+ *
+ * @module dsh-edge-agent/http-api-routes
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export type RouteMethod = 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
+export type Auth = 'public' | 'bearer';
+/** Pre-parsed JSON body for routes that opt-in via `body`. `undefined`
+ *  for routes that don't need a body (GET/DELETE). The dispatcher parses
+ *  the body lazily — only when the matched route declares `body: 'json'`. */
+export type RouteBody = any;
+export interface RouteContext {
+    req: IncomingMessage;
+    res: ServerResponse;
+    reqId: string;
+    start: number;
+    body: RouteBody;
+}
+export interface RouteDef {
+    method: RouteMethod;
+    /** Path pattern with `{name}` placeholders, e.g. `/v1/sessions/{id}/cancel`. */
+    pattern: string;
+    auth: Auth;
+    /** Set to `'json'` for routes that accept a JSON body. The dispatcher
+     *  parses the body BEFORE invoking the handler. */
+    body?: 'json';
+    /** Free-form summary used by OpenAPI spec generation. */
+    summary: string;
+    /** Async handler. Receives the per-request context and the matched
+     *  path params (empty object when the pattern has no placeholders). */
+    handler: (ctx: RouteContext, params: Record<string, string>) => Promise<void> | void;
+}
+/** Match a `(method, path)` pair against the route table. Returns the
+ *  matched route and the extracted path params, or `undefined` when
+ *  nothing matches. */
+export declare function findRoute(routes: readonly RouteDef[], method: string, path: string): {
+    route: RouteDef;
+    params: Record<string, string>;
+} | undefined;
+//# sourceMappingURL=http-api-routes.d.ts.map

package/lib/dsh-adapter/http-api-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-api-routes.d.ts","sourceRoot":"","sources":["../../src/dsh-adapter/http-api-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAA;AAErE,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAEtC;;6EAE6E;AAC7E,MAAM,MAAM,SAAS,GAAG,GAAG,CAAA;AAE3B,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,eAAe,CAAA;IACpB,GAAG,EAAE,cAAc,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,SAAS,CAAA;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,WAAW,CAAA;IACnB,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,IAAI,CAAA;IACV;uDACmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAA;IACf;2EACuE;IACvE,OAAO,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACrF;AA2BD;;uBAEuB;AACvB,wBAAgB,SAAS,CACvB,MAAM,EAAE,SAAS,QAAQ,EAAE,EAC3B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,SAAS,CA4BjE"}

package/lib/dsh-adapter/http-api-routes.js

@@ -0,0 +1,79 @@
+/**
+ * http-api-routes — pure route table for the dsh-edge-agent HTTP API.
+ *
+ * Why a separate module? Adding new endpoints used to mean appending a
+ * branch to `handleRequest()`'s if/else chain. With ~13 endpoints, that
+ * chain got long enough to make the dispatcher itself hard to read —
+ * and impossible to test in isolation. Extracting route definitions lets:
+ *
+ *   1. unit tests pin the exact set of routes + their auth/summary;
+ *   2. the dispatcher shrink to a generic "match → check auth → invoke";
+ *   3. OpenAPI spec generation iterate the same source of truth.
+ *
+ * Design choices:
+ *   - Patterns use `{name}` placeholders. The matcher compiles each
+ *     pattern into a RegExp once (at first match) and caches it.
+ *   - Auth is `public` (no bearer) or `bearer` (require `Authorization`).
+ *     We deliberately do NOT expose CORS / origin checks here — the
+ *     dual-entry architecture document keeps CORS as a v2 concern
+ *     (docs/dual-entry-architecture.md §7.1).
+ *   - The handler signature is intentionally minimal: `(ctx, params)`.
+ *     All HTTP plumbing (reqId, start, body, accessLog) is built into
+ *     `ctx` so handlers don't have to know about the dispatcher.
+ *
+ * @module dsh-edge-agent/http-api-routes
+ */
+const patternCache = new WeakMap();
+function compilePattern(route) {
+    const cached = patternCache.get(route);
+    if (cached)
+        return cached;
+    const paramNames = [];
+    // Escape regex metachars except for `{...}` placeholders, which we
+    // turn into `([^/]+)` capture groups. The placeholder regex is
+    // deliberately restrictive — it won't accept path segments containing
+    // slashes, which matches URL semantics for our resource ids.
+    const escaped = route.pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\\\{([a-zA-Z_][a-zA-Z0-9_]*)\\\}/g, (_m, name) => {
+        paramNames.push(name);
+        return '([^/]+)';
+    });
+    const regex = new RegExp(`^${escaped}$`);
+    const compiled = { regex, paramNames };
+    patternCache.set(route, compiled);
+    return compiled;
+}
+/** Match a `(method, path)` pair against the route table. Returns the
+ *  matched route and the extracted path params, or `undefined` when
+ *  nothing matches. */
+export function findRoute(routes, method, path) {
+    for (const route of routes) {
+        if (route.method !== method)
+            continue;
+        const { regex, paramNames } = compilePattern(route);
+        const m = regex.exec(path);
+        if (!m)
+            continue;
+        const params = {};
+        for (let i = 0; i < paramNames.length; i++) {
+            // `decodeURIComponent` throws URIError on malformed percent-escapes
+            // ('%zz'), and `new URL()` preserves such sequences verbatim in
+            // `pathname`. The matcher runs OUTSIDE any try/catch in the
+            // dispatcher (and the server callback drops the promise), so an
+            // unhandled URIError would take the whole process down — a remote
+            // DoS for anyone holding a token. Decode defensively: an undecodable
+            // param keeps its raw form and the request continues (the handler
+            // then answers 404/400 on an unknown id rather than crashing).
+            const raw = m[i + 1];
+            let decoded = raw;
+            try {
+                decoded = decodeURIComponent(raw);
+            }
+            catch {
+                decoded = raw;
+            }
+            params[paramNames[i]] = decoded;
+        }
+        return { route, params };
+    }
+    return undefined;
+}

package/lib/dsh-adapter/http-api-sessions.d.ts

@@ -0,0 +1,105 @@
+/**
+ * http-api-sessions — soft-dep wrapper around the `sessions` plugin
+ * (`@deepseek-ai/dsh-session-persistence-jsonl`). Provides a stable
+ * surface for the http-api endpoints (`/v1/sessions/{cancel,rename,
+ * fork,...}`) without hard-binding to the upstream plugin's exact API.
+ *
+ * Why a wrapper layer?
+ *   - The upstream `sessions` plugin's API may grow with each DSH
+ *     release. The wrapper freezes a v1-stable contract:
+ *       createSession / getSession / listSessions /
+ *       renameSession / forkSession / cancelSession / deleteSession
+ *   - Soft-dep pattern: if the `sessions` plugin isn't registered
+ *     (older test profiles, minimal config), the wrapper falls back
+ *     to in-memory metadata. This keeps tests simple and decouples
+ *     from boot-order races.
+ *   - Title rename needs a `payload` map the upstream plugin doesn't
+ *     expose directly. The wrapper stores titles as audit-log entries
+ *     keyed by `payload.sessionId + payload.title` (cheap, recoverable
+ *     across restarts, and already persisted by the audit-log plugin).
+ *
+ * @module dsh-edge-agent/http-api-sessions
+ */
+export interface SessionMetadata {
+    sessionId: string;
+    /** Display title (rename-able). May be null for sessions that haven't
+     *  been renamed. */
+    title: string | null;
+    createdAt: number;
+    lastAccessedAt: number;
+    /** Optional provider/model hint captured at session creation time.
+     *  Stored as opaque strings — http-api doesn't enforce they match
+     *  a registered provider. */
+    provider?: string;
+    model?: string;
+}
+export interface SessionCreateInput {
+    sessionId?: string;
+    provider?: string;
+    model?: string;
+    /** Optional realm tag (LOCAL / CLOUD / SANITIZED). Used by the realm-
+     *  skill-bridge layer to filter skill catalogs. Stored here for
+     *  diagnostic / restore purposes. */
+    realm?: string;
+}
+export interface SessionForkInput {
+    /** Source session id to fork from. */
+    sourceSessionId: string;
+    /** Optional new session id; defaults to a fresh UUID. */
+    newSessionId?: string;
+}
+export interface HttpApiSessions {
+    /** Create a new session record. Returns the assigned sessionId. */
+    createSession(input?: SessionCreateInput): Promise<{
+        sessionId: string;
+    }>;
+    /** Read a session's metadata. Returns null if not found. */
+    getSession(sessionId: string): Promise<SessionMetadata | null>;
+    /** List all sessions known to this wrapper. Newest-first by
+     *  lastAccessedAt. */
+    listSessions(): Promise<SessionMetadata[]>;
+    /** Update the human-readable title. */
+    renameSession(sessionId: string, title: string): Promise<void>;
+    /** Fork: copy a session's history under a new sessionId. The source
+     *  session is left untouched. Returns the new sessionId. */
+    forkSession(input: SessionForkInput): Promise<{
+        sessionId: string;
+        sourceSessionId: string;
+    }>;
+    /** Cancel: best-effort signal that the session's turn should abort.
+     *  The actual abort is performed by the http-api service (which holds
+     *  the AgentHandle). The wrapper just records intent. */
+    cancelSession(sessionId: string): Promise<void>;
+    /** Delete: remove the session record entirely. Returns true if a
+     *  record was deleted, false if no such session existed. */
+    deleteSession(sessionId: string): Promise<boolean>;
+}
+/** Soft-dep constructor: pass the cordis context; the wrapper will
+ *  duck-type `ctx.sessions` or `ctx.get?.('sessions')` lazily on each
+ *  call. This keeps boot-order races from breaking http-api. */
+export declare class HttpApiSessionsImpl implements HttpApiSessions {
+    private cordisCtx;
+    /** In-memory metadata fallback when the upstream plugin is absent. */
+    private readonly memory;
+    /** Recently-deleted session ids we want to remember briefly so a
+     *  post-cancel /v1/sessions/{id} doesn't immediately return 200.
+     *  Cleared on a timer so it doesn't grow unbounded. */
+    private readonly tombstone;
+    constructor(cordisCtx: any);
+    /** Lazy upstream plugin lookup. Returns null when the plugin isn't
+     *  registered (older profiles / tests). */
+    private upstream;
+    createSession(input?: SessionCreateInput): Promise<{
+        sessionId: string;
+    }>;
+    getSession(sessionId: string): Promise<SessionMetadata | null>;
+    listSessions(): Promise<SessionMetadata[]>;
+    renameSession(sessionId: string, title: string): Promise<void>;
+    forkSession(input: SessionForkInput): Promise<{
+        sessionId: string;
+        sourceSessionId: string;
+    }>;
+    cancelSession(sessionId: string): Promise<void>;
+    deleteSession(sessionId: string): Promise<boolean>;
+}
+//# sourceMappingURL=http-api-sessions.d.ts.map

package/lib/dsh-adapter/http-api-sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-api-sessions.d.ts","sourceRoot":"","sources":["../../src/dsh-adapter/http-api-sessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB;wBACoB;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,CAAA;IACtB;;iCAE6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;yCAEqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,eAAe,EAAE,MAAM,CAAA;IACvB,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,aAAa,CAAC,KAAK,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACzE,4DAA4D;IAC5D,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAA;IAC9D;0BACsB;IACtB,YAAY,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAAA;IAC1C,uCAAuC;IACvC,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9D;gEAC4D;IAC5D,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC7F;;6DAEyD;IACzD,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C;gEAC4D;IAC5D,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACnD;AAeD;;gEAEgE;AAChE,qBAAa,mBAAoB,YAAW,eAAe;IAQ7C,OAAO,CAAC,SAAS;IAP7B,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAC5D;;2DAEuD;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;gBAE1B,SAAS,EAAE,GAAG;IAElC;+CAC2C;IAC3C,OAAO,CAAC,QAAQ;IAaV,aAAa,CAAC,KAAK,GAAE,kBAAuB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAoB7E,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAW9D,YAAY,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAa1C,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9D,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IAe7F,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/C,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAWzD"}