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

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

@@ -0,0 +1,173 @@
+/**
+ * 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
+ */
+import { randomUUID } from 'node:crypto';
+const TITLE_KIND = 'session.title'; // used by /v1/audit filtering
+/** 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 class HttpApiSessionsImpl {
+    cordisCtx;
+    /** In-memory metadata fallback when the upstream plugin is absent. */
+    memory = new Map();
+    /** 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. */
+    tombstone = new Set();
+    constructor(cordisCtx) {
+        this.cordisCtx = cordisCtx;
+    }
+    /** Lazy upstream plugin lookup. Returns null when the plugin isn't
+     *  registered (older profiles / tests). */
+    upstream() {
+        const ctx = this.cordisCtx;
+        const direct = ctx?.sessions;
+        if (direct && typeof direct === 'object')
+            return direct;
+        if (typeof ctx?.get === 'function') {
+            try {
+                const v = ctx.get('sessions');
+                if (v && typeof v === 'object')
+                    return v;
+            }
+            catch { /* plugin missing — soft-fail */ }
+        }
+        return null;
+    }
+    async createSession(input = {}) {
+        const sessionId = input.sessionId ?? randomUUID();
+        const now = Date.now();
+        const meta = {
+            sessionId,
+            title: null,
+            createdAt: now,
+            lastAccessedAt: now,
+            provider: input.provider,
+            model: input.model,
+        };
+        this.memory.set(sessionId, meta);
+        this.tombstone.delete(sessionId);
+        const up = this.upstream();
+        if (up?.create) {
+            try {
+                await up.create({ sessionId, provider: meta.provider, model: meta.model, createdAt: meta.createdAt, lastAccessedAt: meta.lastAccessedAt, title: meta.title });
+            }
+            catch { /* upstream best-effort */ }
+        }
+        return { sessionId };
+    }
+    async getSession(sessionId) {
+        const up = this.upstream();
+        if (up?.get) {
+            try {
+                const raw = await up.get(sessionId);
+                if (raw && typeof raw === 'object')
+                    return normalize(raw, sessionId);
+            }
+            catch { /* fall through to memory */ }
+        }
+        return this.memory.get(sessionId) ?? null;
+    }
+    async listSessions() {
+        const up = this.upstream();
+        if (up?.list) {
+            try {
+                const list = await up.list();
+                if (Array.isArray(list))
+                    return list.map((r) => normalize(r)).sort(byLastAccessedDesc);
+            }
+            catch { /* fall through */ }
+        }
+        return Array.from(this.memory.values())
+            .filter((m) => !this.tombstone.has(m.sessionId))
+            .sort(byLastAccessedDesc);
+    }
+    async renameSession(sessionId, title) {
+        const meta = this.memory.get(sessionId);
+        if (meta)
+            meta.title = title;
+        const up = this.upstream();
+        if (up?.update) {
+            try {
+                await up.update(sessionId, { title });
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    async forkSession(input) {
+        const source = await this.getSession(input.sourceSessionId);
+        const sessionId = input.newSessionId ?? randomUUID();
+        const now = Date.now();
+        const forked = source
+            ? { ...source, sessionId, title: null, createdAt: now, lastAccessedAt: now }
+            : { sessionId, title: null, createdAt: now, lastAccessedAt: now };
+        this.memory.set(sessionId, forked);
+        const up = this.upstream();
+        if (up?.create) {
+            try {
+                await up.create({ sessionId, forkedFrom: input.sourceSessionId, provider: forked.provider, model: forked.model, createdAt: forked.createdAt, lastAccessedAt: forked.lastAccessedAt });
+            }
+            catch { /* best-effort */ }
+        }
+        return { sessionId, sourceSessionId: input.sourceSessionId };
+    }
+    async cancelSession(sessionId) {
+        // Cancel is a marker, not a state change. The http-api service holds
+        // the live AgentHandle and is the only thing that can actually abort
+        // a running turn. Here we record the intent so /v1/audit shows it.
+        const up = this.upstream();
+        if (up?.update) {
+            try {
+                await up.update(sessionId, { canceledAt: Date.now() });
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    async deleteSession(sessionId) {
+        const existed = this.memory.delete(sessionId);
+        this.tombstone.add(sessionId);
+        // Clear the tombstone after 60s so the id can be re-used later.
+        setTimeout(() => this.tombstone.delete(sessionId), 60_000).unref?.();
+        const up = this.upstream();
+        if (up?.delete) {
+            try {
+                await up.delete(sessionId);
+            }
+            catch { /* best-effort */ }
+        }
+        return existed;
+    }
+}
+function normalize(raw, fallbackId) {
+    const r = raw;
+    return {
+        sessionId: r.sessionId ?? (fallbackId ?? ''),
+        title: r.title ?? null,
+        createdAt: typeof r.createdAt === 'number' ? r.createdAt : Date.now(),
+        lastAccessedAt: typeof r.lastAccessedAt === 'number' ? r.lastAccessedAt : Date.now(),
+        provider: r.provider,
+        model: r.model,
+    };
+}
+function byLastAccessedDesc(a, b) {
+    return b.lastAccessedAt - a.lastAccessedAt;
+}

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

@@ -0,0 +1,221 @@
+/**
+ * http-api — exposes an HTTP server from the parent DSH process so that
+ * external consumers (mobile apps, third-party services) can talk to a
+ * running agent. Optional S13 plugin.
+ *
+ * @module dsh-edge-agent/http-api
+ */
+import { Service } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+export declare const name = "http-api";
+export declare const inject: readonly ["agents", "intentRouter", "auditLog", "tdBus", "realmSkillBridge", "edgeTools"];
+export interface Config {
+    host: string;
+    port: number;
+    /** Bearer token required for all requests. */
+    bearerToken?: string;
+    /** Session idle timeout in ms. Sessions not accessed within this are cleaned up. 0 = disabled. */
+    sessionIdleTimeoutMs: number;
+    /** Maximum active sessions. LRU eviction when exceeded. 0 = unlimited. */
+    maxActiveSessions: number;
+    /** Max JSON body bytes accepted by POST endpoints. Defense-in-depth against
+     *  malicious clients sending unbounded bodies (the old `readJsonBody`
+     *  appended every chunk into a single string with no upper bound, letting
+     *  a remote attacker OOM the edge agent). Default 1 MiB; set to 0 to
+     *  disable the cap (NOT recommended in production). */
+    maxRequestBodyBytes: number;
+}
+export declare const Config: Schema<Config>;
+export interface HttpApiService {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    isRunning(): boolean;
+    endpoint(): string;
+}
+export declare class HttpApiServiceImpl extends Service {
+    private cordisCtx;
+    private config;
+    private agents;
+    private auditLog;
+    private server;
+    private readonly sessions;
+    /** Per-session ring buffer for multi-turn context. See RecentMessage for
+     *  schema. Lives outside `sessions` so pushRecentMessage can accept writes
+     *  before ensureSession() finishes (first-turn user message). */
+    private readonly sessionBuffers;
+    private running;
+    private intentRouter;
+    private realmSkillBridge;
+    private tdBus;
+    private cleanupTimer;
+    /** Soft-dep wrapper for the upstream `sessions` plugin. See
+     *  `./http-api-sessions.ts`. Constructed lazily in `start()` so the
+     *  upstream plugin has time to register (boot-order race). */
+    private sessionsHelper;
+    constructor(cordisCtx: any, config: Config, agents: any, auditLog: any, tdBus?: any);
+    /** Route table — built once at construction so handlers can reference
+     *  the service via `this`. See `./http-api-routes.ts` for the matcher. */
+    private readonly routes;
+    /** Emit an audit-log entry (silent no-op if missing or wrong API). */
+    private audit;
+    /** One-line access log (visible in /tmp/dsh.log via stdout exporter).
+     *
+     *  §7.123 (2026-10-27): wrapped in try/catch + optional chaining, the same
+     *  pattern the §7.46.5 chat lines already use. This helper runs on EVERY
+     *  request, so an unguarded `this.ctx.logger?.info?.(...)` meant a logger
+     *  that throws (full disk, a formatter bug, a broken exporter) turned
+     *  every HTTP call into a 500 — the observability path took the data path
+     *  down with it. A log line must never be able to fail a request. */
+    private accessLog;
+    /**
+     * §7.123 (2026-10-27): logger call that can never throw.
+     *
+     * A logger is not a trusted dependency: a full disk, a broken exporter or
+     * a formatter bug makes `logger.info(...)` throw. On the request path that
+     * turned a successful chat into a 500 (see `ensureSession`'s "Creating
+     * agent" line, which sat unguarded in the middle of session creation).
+     * Observability must never be able to fail the data path.
+     */
+    private safeLog;
+    /** Append a recent-message entry to the session's ring buffer. Evicts
+     *  oldest entries when the buffer exceeds MAX_RECENT_MESSAGES_PER_SESSION.
+     *  Trims text to 200 chars to bound prompt size (intent-router further
+     *  truncates per-message inside the historyBlock). Always accepts the
+     *  push — the buffer map is independent of SessionRecord, so it can be
+     *  written to before ensureSession() finishes (first-turn user message)
+     *  or after handleDeleteSession() drops the session (orphan cleanup
+     *  happens on the next sweep). */
+    private pushRecentMessage;
+    /** Read a snapshot of the session's recent-message ring buffer.
+     *  Returns [] if the session has no history yet. The caller MUST take
+     *  this snapshot BEFORE pushing the current user message — the router
+     *  embeds the snapshot as the "history" block and appends the current
+     *  query itself. */
+    private getPriorRecentMessages;
+    /** Drop the buffer for a session. Called from handleDeleteSession,
+     *  cleanupExpiredSessions, evictLeastRecentSession, and stop().
+     *
+     *  也负责清除 sanitizer 的会话映射表——那张表里存的是**明文 PII**，
+     *  若只删 buffer 不 purge，PII 会一直驻留在堆里直到进程退出
+     *  （2026-08-30 修复）。软依赖 + best-effort：sanitizer 未注册或
+     *  purge 失败都不能影响会话删除本身。 */
+    private dropSessionBuffer;
+    /**
+     * Resolve the actual provider + model to use for a given intent verdict.
+     * Falls back to the legacy hardcoded pair (`local-llm` /
+     * `cloud-llm` plus env-overridable model) when:
+     *   - `modelRouter` is not registered on the cordis context (boot-order
+     *     race: http-api boots before model-router in some configs)
+     *   - `modelRouter.resolve` is unavailable
+     *   - the lookup throws (defensive: never let router failure break a
+     *     chat round-trip)
+     *
+     * Soft-dep pattern (no `inject`) — same as intent-router, because
+     * http-api boots ahead of model-router in the canonical plugin order.
+     * Extracted as a module-level pure function so unit tests can exercise
+     * the resolution matrix without standing up a full HttpApiServiceImpl.
+     */
+    private resolveRoute;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    isRunning(): boolean;
+    endpoint(): string;
+    private handleRequest;
+    /** Dispatch helper — builds the RouteContext (parsing the body only
+     *  when the route declares `body: 'json'`), invokes the handler, and
+     *  maps thrown errors to the right HTTP status code (mirrors the
+     *  original if/else chain's error semantics). */
+    private invokeRoute;
+    private checkAuth;
+    private handleChat;
+    private handleChatStream;
+    private handleListSessions;
+    /** GET /v1/models — returns the dispatcher's provider catalog. Backed
+     *  by `modelRouter.listDetailed()`; falls back to a hardcoded pair
+     *  when the router isn't registered (boot-order race; mirrors
+     *  `resolveRoute()`'s soft-dep pattern at line ~1440).
+     *
+     *  Soft-dep: cordis throws on `ctx.<name>` when the row isn't in
+     *  `inject`, so wrap the lookup in try/catch and fall back. */
+    private handleListModels;
+    /** GET /v1/audit?since=&until=&kind=&level=&sessionId=&limit= — query
+     *  the audit-log. The audit-log API already supports level/kind/sinceMs/
+     *  untilMs/limit; we additionally filter on `payload.sessionId` post-
+     *  hoc because sessionId lives in payload (audit entries don't have a
+     *  first-class sessionId field — they're `(level, kind, source, payload)`
+     *  records). Limit defaults to 50, hard cap 500, to keep response size
+     *  bounded — the audit-log JSONL can be very large for long-running
+     *  deployments.
+     *
+     *  Path leakage: this endpoint NEVER returns the audit file path —
+     *  only structured entries. Operators wanting to inspect the raw JSONL
+     *  should use the existing file-system route (the audit-log's config
+     *  already publishes its root). */
+    private handleListAudit;
+    private handleGetSession;
+    private handleDeleteSession;
+    /** POST /v1/sessions/{id}/cancel — best-effort cancel of any in-flight
+     *  turn on this session. Currently implemented by disposing the live
+     *  AgentHandle (same as DELETE); the session record is removed from
+     *  the in-memory map but persisted metadata is retained so /v1/sessions
+     *  still shows the historical record. Returns 202 Accepted to signal
+     *  async semantics (the actual abort may race the next chunk). */
+    private handleCancelSession;
+    /** POST /v1/sessions/{id}/rename — body `{ title }`. Updates the
+     *  human-readable title in the persistence layer; the in-memory map
+     *  is intentionally not the source of truth (titles survive restarts). */
+    private handleRenameSession;
+    /** POST /v1/sessions/{id}/fork — body `{ atMessageIndex? }` (optional
+     *  index into the recent-message ring buffer to fork from; defaults
+     *  to "everything"). Creates a fresh session record and copies the
+     *  source's recent messages (truncated at the requested index) into
+     *  the new session's ring buffer. The live AgentHandle is NOT copied —
+     *  the forked session starts fresh; the next followup() on it spins
+     *  up a new agent. This is the same semantics as the DSH webui's
+     *  `sessions.fork` RPC. Returns 201 Created with the new sessionId. */
+    private handleForkSession;
+    /**
+     * Resolve the preset id one new session will run under and the `setup` hook
+     * that mounts it. Returns `{}` when the deployment has no agent-presets
+     * roster (bare dsh CLI without dsh-agent-presets installed) — agents then
+     * run on the host composition, which is the pre-preset behaviour.
+     *
+     * Mirrors dsh-tui's `composePreset()` (lib/types/dsh-adapter/presets.js:35).
+     * The original signature is in dsh-tui's private module surface, so we
+     * inline a minimal version here: `resolve()` (exact roster match) +
+     * `mount(agentCtx, id)` are the two public calls every implementation
+     * exposes.
+     */
+    private composeAgentPreset;
+    private ensureSession;
+    /**
+     * Clean up sessions that have been idle longer than sessionIdleTimeoutMs.
+     * Called periodically by the cleanup timer.
+     */
+    private cleanupExpiredSessions;
+    /**
+     * Evict the least-recently-used session to make room for a new one.
+     * Called when maxActiveSessions is reached.
+     */
+    private evictLeastRecentSession;
+    private readJsonBody;
+    private getOpenApiSpec;
+    /** Build the route table — public + bearer-auth. Returns an array of
+     *  RouteDef entries; the dispatcher (handleRequest) walks it to
+     *  resolve method+path → handler. Built once at construction; the
+     *  table is therefore stable across the service's lifetime, which
+     *  lets future optimization (route hot-reload, per-route metrics) hook
+     *  in at a single construction site. */
+    private buildRoutes;
+}
+/**
+ * Pure (exported for unit tests) route resolver. See the inline comment
+ * in HttpApiServiceImpl#resolveRoute for the soft-dep / fail-open contract.
+ */
+export declare function resolveRoute(ctx: any, isLocal: boolean): {
+    provider: string;
+    model: string;
+    resolved: boolean;
+};
+export declare function apply(ctx: any, config: Config): Promise<() => Promise<void>>;
+//# sourceMappingURL=http-api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http-api.d.ts","sourceRoot":"","sources":["../../src/dsh-adapter/http-api.ts"],"names":[],"mappings":"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"}