@dan-ai-studio/dshopencodego 0.1.63 → 0.1.64

package/lib/types/adapter.d.ts

@@ -18,6 +18,7 @@ import type { AttachmentStore, ImageAttachmentRef } from '@deepseek-ai/dsh-attac
 import { OpencodeGoCatalog } from './catalog/index.ts';
 import type { GoDoc } from './catalog/go-doc.ts';
 import type { OpencodeGoConfig } from './config.ts';
+import type { RequestRecorder } from './request-log/store.ts';
 import type { MeteredUsage } from './usage/meter.ts';
 /** Image machinery the adapter reads once per request. */
 export interface OpencodeGoImageAccess {
@@ -78,6 +79,12 @@ export interface OpencodeGoAdapterOptions {
         model: string;
         usage: MeteredUsage;
     }) => void;
+    /**
+     * Record one request's span. The recorder returns undefined unless the
+     * profile enabled the log, so a disabled log costs one call and one
+     * boolean read per request and constructs nothing.
+     */
+    readonly requestLog?: RequestRecorder;
 }
 /**
  * The single `opencode-go` route's adapter.

package/lib/types/config.d.ts

@@ -14,7 +14,9 @@
 import type { RetryPolicyConfig } from '@deepseek-ai/dsh-llm';
 import z from '@deepseek-ai/schemastery';
 import { DEFAULT_KEEP_ALIVE_TIMEOUT_MS, DEFAULT_KEEP_ALIVE_TIMEOUT_SECONDS, MAX_KEEP_ALIVE_TIMEOUT_MS, MAX_KEEP_ALIVE_TIMEOUT_SECONDS, TIMER_CEILING_MS } from './network/keep-alive.ts';
+import { DEFAULT_REQUEST_LOG_MAX_ENTRIES, MAX_REQUEST_LOG_MAX_ENTRIES, MIN_REQUEST_LOG_MAX_ENTRIES } from './request-log/limits.ts';
 export { DEFAULT_KEEP_ALIVE_TIMEOUT_MS, DEFAULT_KEEP_ALIVE_TIMEOUT_SECONDS, MAX_KEEP_ALIVE_TIMEOUT_MS, MAX_KEEP_ALIVE_TIMEOUT_SECONDS, TIMER_CEILING_MS, };
+export { DEFAULT_REQUEST_LOG_MAX_ENTRIES, MAX_REQUEST_LOG_MAX_ENTRIES, MIN_REQUEST_LOG_MAX_ENTRIES, };
 /** Credential reference resolving the OpenCode Go API key. */
 export declare const DEFAULT_API_KEY_ENV = "OPENCODE_GO_API_KEY";
 /** Requests and pickers share this cache lifetime; explicit discovery revalidates immediately. */
@@ -73,6 +75,23 @@ export interface OpencodeGoConfig {
      * The escape hatch for a model whose family rule guessed wrong.
      */
     modelProtocols: Record<string, string>;
+    /**
+     * Whether the per-request log records anything at all. Off by default: a
+     * disabled log changes nothing on the request path — not one extra
+     * allocation — because the recorder is never constructed.
+     */
+    requestLogEnabled: boolean;
+    /**
+     * Whether the request log also records pool lifecycle and full session
+     * identity. Debug only: the common log carries a truncated session and no
+     * pool events, which is enough to follow one conversation.
+     */
+    requestLogDebug: boolean;
+    /**
+     * How many request-log entries the Host keeps, oldest dropped first. Bounded
+     * so the log can never grow with the session.
+     */
+    requestLogMaxEntries: number;
     /**
      * Addresses a name should be sent to instead of the one the system
      * resolves, by host name. A name that is not listed keeps the system's

package/lib/types/network/pinning.d.ts

@@ -63,6 +63,21 @@ export declare function gatewayHostOf(baseURL: string): string;
  *   address it is pinned to.
  */
 export declare function resolveGatewayPin(pins: PinnedAddresses, baseURL: string): GatewayPin;
+/**
+ * Pool lifecycle observer. Pools live for minutes, so these events are rare
+ * by construction — observing them costs nothing on the request path.
+ */
+export interface PoolObserver {
+    /** A new pool was built for this key. */
+    create(key: string): void;
+    /** The pool for this key was closed. */
+    close(key: string): void;
+}
+/**
+ * Watch pool lifecycle. The request log sets this when its debug mode is on;
+ * unset it (or never set it) and the pool code reads exactly as before.
+ */
+export declare function observePool(next: PoolObserver | undefined): void;
 /**
  * Close the dispatcher, if one is open.
  *

package/lib/types/request-log/contract.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Wire contract for the request-log Remote.
+ *
+ * One reading: the bounded per-request log the Host keeps while the profile
+ * enables it. The viewer opens it on demand; nothing polls, so a closed
+ * viewer costs no wire traffic at all.
+ *
+ * @module @dan-ai-studio/dshopencodego/request-log/contract
+ */
+import type { RemoteResult, TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol';
+import type { RequestLogSnapshot } from './store.ts';
+export type { PoolLogEvent, RequestLogEntry, RequestLogSnapshot } from './store.ts';
+/** Validate a snapshot crossing the wire. */
+export declare function parseRequestLogSnapshot(value: unknown): RequestLogSnapshot;
+declare module '@deepseek-ai/dsh-typert-protocol' {
+    interface TypertRemoteNamespaceMap {
+        opencodeGoRequestLog: {
+            readLog(): Promise<RemoteResult<RequestLogSnapshot>>;
+        };
+    }
+}
+/** Remote methods this package owns, mounted together by the plugin. */
+export declare const requestLogRemote: TypertRemoteContribution;

package/lib/types/request-log/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The per-request log: public surface of the request-log module.
+ *
+ * @module @dan-ai-studio/dshopencodego/request-log
+ */
+export { OpencodeGoRequestLogService } from './service.ts';
+export type { RequestLogServiceOptions } from './service.ts';
+export { RequestLog } from './store.ts';
+export type { PoolLogEvent, RequestLogEntry, RequestLogGates, RequestLogSnapshot, RequestRecorder, RequestSpan, RequestStart, } from './store.ts';
+export { parseRequestLogSnapshot, requestLogRemote } from './contract.ts';

package/lib/types/request-log/limits.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Request-log bounds, shared by the schema and the settings page.
+ *
+ * These live apart from `config.ts` on purpose: the settings page must not
+ * drag the configuration module (and its Harness-only imports) into the
+ * browser bundle. Import from here on both sides instead.
+ *
+ * @module @dan-ai-studio/dshopencodego/request-log/limits
+ */
+/** Default request-log retention: enough to debug a session, small enough to never matter. */
+export declare const DEFAULT_REQUEST_LOG_MAX_ENTRIES = 200;
+/** Fewest request-log entries a profile may keep. */
+export declare const MIN_REQUEST_LOG_MAX_ENTRIES = 50;
+/** Most request-log entries a profile may keep; the buffer is bounded by design. */
+export declare const MAX_REQUEST_LOG_MAX_ENTRIES = 500;

package/lib/types/request-log/service.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Host half of the request-log Remote.
+ *
+ * The viewer opens the snapshot on demand and refreshes it when asked; the
+ * Host never pushes. A closed viewer therefore costs no wire traffic at all,
+ * and an open one costs one read per refresh.
+ *
+ * @module @dan-ai-studio/dshopencodego/request-log/service
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { RequestLog, RequestLogSnapshot } from './store.ts';
+/** Host inputs for the request-log service. */
+export interface RequestLogServiceOptions {
+    /** The bounded ring the adapter appends to. */
+    readonly log: RequestLog;
+    /** How many entries to keep; the ring trims to it on every read. */
+    readonly maxEntries: () => number;
+}
+/** Request-log Remote: one on-demand snapshot of the ring. */
+export declare class OpencodeGoRequestLogService extends TypertRemoteService {
+    private readonly options;
+    constructor(ctx: Context, options: RequestLogServiceOptions);
+    /** The current reading, trimmed to the configured bound first. */
+    readLog(): RequestLogSnapshot;
+}

package/lib/types/request-log/store.d.ts

@@ -0,0 +1,194 @@
+/**
+ * The per-request log: a bounded ring buffer owned by the Host.
+ *
+ * Everything here is inert unless the profile enables it. The recorder is
+ * constructed only when `requestLogEnabled` reads true, so a disabled log
+ * changes nothing on the request path — not one extra allocation. When
+ * enabled, one entry per completed or failed request is appended; the oldest
+ * entries are dropped past the configured bound, so the log can never grow
+ * with the session.
+ *
+ * Two facts are structural rather than conventional:
+ *
+ * - Authorization never enters a record. The recorder takes no headers
+ *   argument at all; the only header-derived value it stores is the session
+ *   id it is handed, already separated from the credential by the caller.
+ * - The session id is stored truncated (first 8 characters) unless debug
+ *   mode is on at record time. A truncated id groups one conversation's
+ *   requests without writing the full identity to the log.
+ *
+ * @module @dan-ai-studio/dshopencodego/request-log/store
+ */
+/** How many session-id characters the common (non-debug) log keeps. */
+export declare const SESSION_PREFIX_LENGTH = 8;
+/** One recorded request. Counts are provider-reported; timings are Host-measured. */
+export interface RequestLogEntry {
+    /** Monotonic sequence within this process; gaps mean nothing was recorded. */
+    readonly seq: number;
+    /** When the request started, in epoch milliseconds. */
+    readonly atMs: number;
+    /** The model id the request was made with. */
+    readonly model: string;
+    /** The session id, full in debug mode, truncated to {@link SESSION_PREFIX_LENGTH} otherwise. */
+    readonly session: string;
+    /** HTTP method used. */
+    readonly method: string;
+    /** Request URL without any credential (the key travels in a header). */
+    readonly url: string;
+    /** Response status when a response arrived; absent when the request never got one. */
+    readonly status?: number;
+    /** Provider-reported input tokens, when the terminal usage arrived. */
+    readonly inputTokens?: number;
+    /** Provider-reported output tokens, when the terminal usage arrived. */
+    readonly outputTokens?: number;
+    /** Provider-reported cache-read tokens, when positive. */
+    readonly cacheReadTokens?: number;
+    /** Wall time from request start to terminal event, in milliseconds. */
+    readonly durationMs?: number;
+    /** Wall time from request start to the first token delta, in milliseconds. */
+    readonly firstTokenMs?: number;
+    /** Whether the request completed. */
+    readonly ok: boolean;
+    /** Failure code (`TIMEOUT`, `TRANSPORT`, …) for a request that did not complete. */
+    readonly code?: string;
+    /** Connection-pool key the request ran under, when the pool is enabled. */
+    readonly poolKey?: string;
+    /** Request shape summary, so the log stays informative without bodies. */
+    readonly shape?: {
+        /** Number of conversation messages sent. */
+        readonly messages: number;
+        /** Whether any message carried image content. */
+        readonly hasImage: boolean;
+        /** Number of tool schemas sent. */
+        readonly tools: number;
+    };
+    /**
+     * Debug-only headers, allowlisted at record time: the session id and the
+     * user agent. Never the credential — the recorder takes no headers
+     * argument, so there is no path by which an `authorization` value could
+     * reach a record.
+     */
+    readonly headers?: {
+        readonly session?: string;
+        readonly userAgent?: string;
+    };
+}
+/** One pool lifecycle event. Rare by construction: pools live for minutes. */
+export interface PoolLogEvent {
+    readonly atMs: number;
+    readonly type: 'create' | 'close';
+    /** The pool key (`host@address@timeoutMs`). */
+    readonly key: string;
+}
+/** What the viewer reads: the entries plus the counters a rate needs. */
+export interface RequestLogSnapshot {
+    /** Newest first, at most the configured bound. */
+    readonly entries: readonly RequestLogEntry[];
+    /** Recent pool lifecycle, newest first, capped. */
+    readonly poolEvents: readonly PoolLogEvent[];
+    /** Requests recorded since boot, including ones since dropped. */
+    readonly totalRecords: number;
+    /** Requests dropped for exceeding the bound. */
+    readonly droppedRecords: number;
+    /** Sockets the gateway accepted since boot. */
+    readonly newConnections: number;
+    /** Pool key currently in force, if any request has run. */
+    readonly poolKey?: string;
+}
+/** Live gates the recorder reads at record time. */
+export interface RequestLogGates {
+    /** Whether any record is kept at all. */
+    readonly enabled: () => boolean;
+    /** Whether debug detail (full session, pool events) is kept. */
+    readonly debug: () => boolean;
+    /** How many entries to keep; the ring trims to it on every append. */
+    readonly maxEntries: () => number;
+}
+/**
+ * An in-flight request, handed back only when the log is enabled.
+ *
+ * Every method is cheap by construction: two `Date.now` reads and small
+ * integer arithmetic across the whole span. No serialization, no hashing,
+ * no body handling — the counts ride the usage chunk the adapter already
+ * holds, and the timings bracket work that already happened.
+ */
+export interface RequestSpan {
+    /** Mark the first token delta's arrival. Idempotent: only the first call counts. */
+    firstToken(): void;
+    /**
+     * Record the wire request line, from the fetch wrapper. Called at most
+     * once per span; a second call keeps the first, so retries never rewrite
+     * the original line.
+     */
+    request(method: string, url: string): void;
+    /** Mark the response status line's arrival. */
+    status(status: number): void;
+    /**
+     * Close the span and append its entry.
+     * @param ok - whether the request completed.
+     * @param code - failure code for a request that did not complete.
+     * @param usage - provider-reported counts, when the terminal usage arrived.
+     */
+    finish(ok: boolean, code?: string, usage?: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly cacheReadTokens?: number;
+    }): void;
+}
+/** Detail the adapter hands the recorder for one request. */
+export interface RequestStart {
+    readonly model: string;
+    readonly sessionId: string | undefined;
+    /** Fallback line, used only when the fetch wrapper never reported the real one. */
+    readonly method?: string;
+    readonly url?: string;
+    readonly messageCount: number;
+    readonly hasImage: boolean;
+    readonly toolCount: number;
+    /** Allowlisted request headers; the recorder never sees the credential. */
+    readonly headers: {
+        readonly session?: string;
+        readonly userAgent?: string;
+    };
+}
+/**
+ * One request's recorder. The adapter calls `start` once per stream; the
+ * span it returns (or undefined when the log is disabled) carries the rest.
+ */
+export interface RequestRecorder {
+    start(detail: RequestStart): RequestSpan | undefined;
+}
+/** Appends bounded per-request records for the lifetime of one Host process. */
+export declare class RequestLog {
+    private readonly gates;
+    private entries;
+    private poolEvents;
+    private seq;
+    private totalRecords;
+    private droppedRecords;
+    private newConnections;
+    private poolKey;
+    constructor(gates: RequestLogGates);
+    /**
+     * Count one accepted socket. Called from the diagnostics channel, not the
+     * request path, so its cost never lands on a request.
+     */
+    connectionOpened(): void;
+    /**
+     * Record one pool lifecycle event. Pools live for minutes, so this is rare
+     * by construction; still gated on debug so the common log stays request-only.
+     */
+    poolEvent(type: 'create' | 'close', key: string): void;
+    /**
+     * Begin one request's span, or nothing when the log is disabled.
+     *
+     * This is the single gate on the request path: a disabled log costs one
+     * method call and one boolean read, and constructs nothing.
+     */
+    start(detail: RequestStart): RequestSpan | undefined;
+    private append;
+    /** Shrink the ring to a new bound immediately; growing backfills nothing. */
+    setMaxEntries(bound: number): void;
+    /** The current reading, newest first. Computed lazily: nothing on the hot path. */
+    snapshot(): RequestLogSnapshot;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dan-ai-studio/dshopencodego",
-  "version": "0.1.63",
+  "version": "0.1.64",
   "description": "OpenCode Go provider for DeepSeek Harness: live gateway catalog, per-conversation session header, usage",
   "type": "module",
   "license": "MIT",