@maci0/dsh-chatjimmy 0.11.4

package/lib/protocol.js

@@ -0,0 +1,172 @@
+/**
+ * Wire translation between the harness request vocabulary and the
+ * chatjimmy.ai HTTP API reconstructed in `API.md`.
+ *
+ * Everything here is pure so it can be tested without a harness or a network.
+ *
+ * @module dsh-chatjimmy/protocol
+ */
+/** Opening marker of the trailing generation-stats block. */
+export const STATS_OPEN = '<|stats|>';
+/** Closing marker of the trailing generation-stats block. */
+export const STATS_CLOSE = '<|/stats|>';
+/** Flatten a block tree to the plain text the wire can carry. */
+function blockText(block) {
+    switch (block.type) {
+        case 'text':
+        case 'reasoning':
+            return typeof block.text === 'string' ? block.text : '';
+        case 'tool-call':
+            // The service has no tool protocol. Render the call as prose so a
+            // cross-provider history still reads as a conversation.
+            return `[tool call] ${String(block.name)}(${String(block.arguments)})`;
+        default:
+            // Images and files are already projected to text for a text-only route
+            // by LlmRuntime; anything else unknown is dropped rather than guessed.
+            return '';
+    }
+}
+/** Flatten a block list to plain text. */
+export function flatten(blocks) {
+    return blocks.map(blockText).join('');
+}
+/**
+ * Build the exact request body for one model call: history is flattened to
+ * text, every system-role message is hoisted into the single `systemPrompt`
+ * slot, and the caller's `system` text leads it.
+ */
+export function buildChatRequest(options, config) {
+    const systemParts = [];
+    const messages = [];
+    for (const message of options.messages) {
+        const text = flatten(message.content);
+        if (message.role === 'system' || message.role === 'developer') {
+            if (text.length > 0)
+                systemParts.push(text);
+            continue;
+        }
+        if (text.length === 0)
+            continue;
+        // The wire accepts user/assistant turns only, so a tool result rides the
+        // user turn (the harness's own adapters do the same for a provider with no
+        // tool role), labelled so it does not read as the user's own words.
+        if (message.role === 'tool')
+            messages.push({ role: 'user', content: `[tool result] ${text}` });
+        else
+            messages.push({ role: message.role, content: text });
+    }
+    if (options.system !== undefined && options.system.length > 0)
+        systemParts.unshift(options.system);
+    return {
+        messages,
+        chatOptions: {
+            selectedModel: options.model.length > 0 ? options.model : config.model,
+            systemPrompt: systemParts.join('\n\n'),
+            topK: config.topK,
+        },
+        attachment: null,
+    };
+}
+/** Parse the stats payload, returning undefined for malformed JSON. */
+export function parseStats(raw) {
+    try {
+        const value = JSON.parse(raw);
+        return typeof value === 'object' && value !== null ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True when a stats `reason` reports the backend's own context-limit refusal.
+ * @param reason - the stats `reason` field, when present.
+ */
+export function isContextLimitReason(reason) {
+    return typeof reason === 'string' && /max\s+context\s+limit\s+\d+\s+reached/i.test(reason);
+}
+/** A token counter, or undefined when the stats did not carry a usable one. */
+function counter(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/**
+ * Map backend token counters onto harness usage.
+ * @param stats - parsed stats, when the stream carried them.
+ * @returns disjoint harness counts (the provider reports no cache split), or
+ *   undefined when the stats carry neither prompt nor output counter. The total
+ *   is the provider's own, else the sum when both parts are known, else omitted.
+ */
+export function mapUsage(stats) {
+    const input = counter(stats?.prefill_tokens);
+    const output = counter(stats?.decode_tokens);
+    if (input === undefined && output === undefined)
+        return undefined;
+    const total = counter(stats?.total_tokens)
+        ?? (input === undefined || output === undefined ? undefined : input + output);
+    return { inputTokens: input ?? 0, outputTokens: output ?? 0, ...total === undefined ? {} : { totalTokens: total } };
+}
+/**
+ * Splits the generated text from the trailing `<|stats|>…<|/stats|>` block
+ * without ever emitting a partial marker.
+ *
+ * The backend appends the block to the same byte stream as the completion, so a
+ * reader that forwarded chunks verbatim would leak `{"prefill_tokens":…}` into
+ * the model's visible answer. Text is held back only as far as a marker could
+ * still be forming, so time-to-first-token is unaffected.
+ */
+export class StatsStreamFilter {
+    #buffer = '';
+    #stats;
+    #closed = false;
+    /**
+     * Absorb one decoded chunk.
+     * @param text - newly decoded text.
+     * @returns the prefix that is certainly completion text.
+     */
+    push(text) {
+        if (this.#closed || text.length === 0)
+            return '';
+        this.#buffer += text;
+        const open = this.#buffer.indexOf(STATS_OPEN);
+        if (open < 0) {
+            // No marker yet: hold back only what a split marker could consume.
+            const keep = STATS_OPEN.length - 1;
+            if (this.#buffer.length <= keep)
+                return '';
+            const emit = this.#buffer.slice(0, this.#buffer.length - keep);
+            this.#buffer = this.#buffer.slice(-keep);
+            return emit;
+        }
+        const emit = this.#buffer.slice(0, open);
+        const rest = this.#buffer.slice(open);
+        const close = rest.indexOf(STATS_CLOSE);
+        if (close < 0) {
+            this.#buffer = rest;
+            return emit;
+        }
+        this.#stats = parseStats(rest.slice(STATS_OPEN.length, close));
+        this.#buffer = '';
+        this.#closed = true;
+        return emit;
+    }
+    /**
+     * Release whatever the stream ended with.
+     * @returns residual completion text; empty when the body ended on the marker.
+     */
+    flush() {
+        if (this.#closed || this.#buffer.length === 0)
+            return '';
+        // A full opening marker was seen, so nothing still buffered is completion
+        // text: a block the body cut short must not be printed as the answer.
+        if (this.#buffer.startsWith(STATS_OPEN)) {
+            this.#buffer = '';
+            return '';
+        }
+        const emit = this.#buffer;
+        this.#buffer = '';
+        return emit;
+    }
+    /** Stats the stream carried, when the sentinel was complete. */
+    get stats() {
+        return this.#stats;
+    }
+}

package/lib/types/adapter.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Provider adapter for the chatjimmy.ai chat API (see `API.md` at the
+ * repository root for the reconstructed wire contract).
+ *
+ * The service is text-in/text-out: it accepts no tool schemas, no images, no
+ * sampling parameters, and returns one plain-text stream. This adapter is
+ * therefore honest about being a text-only route: it advertises
+ * `inputModalities: ['text']` so `LlmRuntime` projects files and images to
+ * placeholder text before dispatch, and it ignores every tool field rather than
+ * pretending the model can call them.
+ *
+ * @module dsh-chatjimmy/adapter
+ */
+import { CONTEXT_WINDOW_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm';
+import type { ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm';
+import { type ChatJimmyConfig } from './protocol.ts';
+import type { GenerateOptions, LlmAdapterLike, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, PreparedAdapterCall, StreamChunk } from './host.ts';
+/** Stable failure used when the backend answers with a zero-byte stream body. */
+export { CONTEXT_WINDOW_EXCEEDED_CODE };
+/** Injectable fetch, so the adapter is testable without a network. */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/**
+ * Duck-typed adapter over `POST /api/chat`.
+ *
+ * `LlmRuntime` reaches adapters through plain method calls, so this object
+ * needs no harness base class. The plugin's only runtime dependency on
+ * `@deepseek-ai/*` is `@deepseek-ai/dsh-llm`'s pure helpers
+ * (`attributionHeaders()` and `resolveRetryPolicy()`), never its error classes
+ * or adapter base class.
+ */
+export declare class ChatJimmyAdapter implements LlmAdapterLike {
+    #private;
+    /**
+     * @param config - the resolved configuration this adapter serves, or a
+     * provider that resolves it on every read. The plugin passes the live
+     * provider, so a settings edit (the Plugins card, `/alias`-style patch
+     * writes) reaches the next request without remounting the adapter; a plain
+     * value keeps the snapshot behavior for direct callers and tests.
+     * @param fetchImpl - transport override for tests.
+     */
+    constructor(config: ChatJimmyConfig | (() => ChatJimmyConfig), fetchImpl?: FetchLike);
+    /** {@inheritDoc LlmAdapterLike.providerInfo} */
+    providerInfo(provider: string): LlmProviderInfo;
+    /**
+     * The provider-owned retry policy from configuration, already resolved, or
+     * `undefined` to leave the harness's normal defaults in place.
+     *
+     * This and {@link imageRequestPricing} exist because `LlmRuntime` calls them
+     * on every dispatch. A harness `LlmAdapter` subclass inherits them; a
+     * duck-typed adapter must supply them or the very first registration throws
+     * `adapter.providerRetryPolicy is not a function`.
+     */
+    providerRetryPolicy(_provider: string): ResolvedRetryPolicy | undefined;
+    /** No route charges visual tokens: this adapter is text-only. */
+    imageRequestPricing(_provider: string, _model: string): undefined;
+    /**
+     * The advertised catalog. `/api/models` serves exactly one entry, so it is
+     * mirrored from configuration instead of costing a round trip on every model
+     * picker open. The id stays advisory: any id is accepted on the wire.
+     */
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    /** {@inheritDoc LlmAdapterLike.resolveModel} */
+    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    /** {@inheritDoc LlmAdapterLike.prepareCall} */
+    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
+    /**
+     * Stream one completion. Everything the service sends is completion text up
+     * to the trailing stats block, which {@link StatsStreamFilter} removes; the
+     * block is then reported as harness usage.
+     *
+     * A zero-byte body with HTTP 200 is the service's signature for a request
+     * that overflowed the context window: the response headers are already
+     * committed as `text/event-stream`, so the backend's refusal cannot be
+     * delivered as an error status. That case is reported as
+     * `CONTEXT_WINDOW_EXCEEDED` rather than as an empty completion.
+     */
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}

package/lib/types/host.d.ts

@@ -0,0 +1,177 @@
+/**
+ * The slice of the DeepSeek Harness host surface this plugin uses, declared
+ * structurally.
+ *
+ * Like the other plugins under `~/dsh-plugins`, this package declares the host
+ * surface it consumes rather than depending on the harness's own classes: its
+ * one runtime `@deepseek-ai/*` dependency is `@deepseek-ai/dsh-llm`'s pure
+ * `attributionHeaders()` / `resolveRetryPolicy()` helpers. The harness reaches
+ * its adapters through plain method calls on the registered object (there is
+ * no `instanceof LlmAdapter` check anywhere in `LlmRuntime`), so a duck-typed
+ * adapter is a supported shape, not a workaround.
+ *
+ * Each declaration here is deliberately narrowed to what this adapter reads or
+ * emits. Mirroring a foreign API in full is not documentation: a field we never
+ * touch is a field whose absence goes unnoticed, which is how the missing
+ * `providerRetryPolicy` reached an integration test instead of a compiler.
+ * Widen a declaration when the adapter starts using it, not before.
+ *
+ * @module dsh-chatjimmy/host
+ */
+/** Disposer returned by every host registration. */
+type Disposable = () => void;
+/** Content block the harness may hand us in request history. */
+export type ContentBlock = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'reasoning';
+    readonly text: string;
+} | {
+    readonly type: 'tool-call';
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: string;
+} | {
+    readonly type: string;
+    readonly [key: string]: unknown;
+};
+/** One message in a fully-assembled request. */
+interface Message {
+    readonly id: string;
+    /**
+     * Every role the harness really sends. Narrowing this to the three the wire
+     * accepts is what let `tool` and `developer` turns reach the service
+     * verbatim, so the union stays complete and `buildChatRequest` does the
+     * projection the wire needs.
+     */
+    readonly role: 'system' | 'developer' | 'user' | 'assistant' | 'tool';
+    readonly content: readonly ContentBlock[];
+    /** Id of the call a `tool`-role message answers. */
+    readonly toolCallId?: string;
+}
+/** A single model request, narrowed to the fields this adapter reads. */
+export interface GenerateOptions {
+    readonly model: string;
+    readonly messages: readonly Message[];
+    readonly system?: string;
+    /**
+     * Stop sequences. The service has no wire slot for them, so the adapter
+     * refuses a request that sets any (`UNSUPPORTED_OPTION`) instead of
+     * generating past where the caller asked it to stop. Tool schemas,
+     * `temperature`, and `maxTokens` are declared capability limits in
+     * `README.md` and stay dropped.
+     */
+    readonly stop?: readonly string[];
+    readonly signal?: AbortSignal;
+}
+/** Token accounting for one model call. */
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens?: number;
+}
+/** Stable provider-neutral failure shape. */
+export interface LlmFailure {
+    readonly message: string;
+    readonly code: string;
+    readonly status?: number;
+    /** Positive provider-requested retry delay in milliseconds. */
+    readonly providerRetryAfterMs?: number;
+}
+/** Why a model response stopped. */
+export type FinishReason = {
+    readonly kind: 'stop';
+} | {
+    readonly kind: 'max-tokens';
+} | {
+    readonly kind: 'error';
+    readonly failure: LlmFailure;
+} | {
+    readonly kind: 'aborted';
+    readonly failure: LlmFailure;
+};
+/** The two chunk shapes this adapter emits, plus the terminal pair. */
+export type StreamChunk = {
+    readonly type: 'block-start';
+    readonly index: number;
+    readonly blockType: string;
+} | {
+    readonly type: 'text-delta';
+    readonly index: number;
+    readonly text: string;
+} | {
+    readonly type: 'block-end';
+    readonly index: number;
+    readonly block: ContentBlock;
+} | {
+    readonly type: 'usage';
+    readonly usage: TokenUsage;
+} | {
+    readonly type: 'finish';
+    readonly reason: FinishReason;
+};
+/** Display metadata for one adapter-owned provider route. */
+export interface LlmProviderInfo {
+    readonly id: string;
+    readonly name: string;
+}
+/** One adapter-advertised model. */
+export interface LlmModelInfo {
+    readonly provider: string;
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly inputModalities?: readonly string[];
+}
+/** Exact-route model metadata resolved by its owning adapter. */
+export interface LlmResolvedModelInfo extends LlmModelInfo {
+    readonly context?: {
+        readonly contextWindow: number;
+    };
+}
+/** What `prepareCall` binds: exact model metadata plus one-generation dispatch. */
+export interface PreparedAdapterCall {
+    readonly model: LlmResolvedModelInfo;
+    readonly stream: (options: GenerateOptions) => AsyncIterable<StreamChunk>;
+}
+/**
+ * The adapter face `ctx.llm.registerAdapter()` consumes. Every member is called
+ * by the harness at runtime; nothing about the object must be a harness class.
+ *
+ * The list is the full public surface of the harness `LlmAdapter` base class,
+ * including the members that only have defaults there. `LlmRuntime` reads
+ * `providerRetryPolicy` while registering the adapter and `imageRequestPricing`
+ * during a token-meter measurement, so a duck-typed adapter that omits either
+ * throws instead of falling back to the base-class default.
+ */
+export interface LlmAdapterLike {
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(provider: string): unknown;
+    imageRequestPricing(provider: string, model: string): unknown;
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+/** The `ctx.llm` seam, narrowed to the one call this plugin makes. */
+interface LlmServiceLike {
+    registerAdapter(providers: string[], adapter: LlmAdapterLike): Disposable;
+}
+/** The host context slice this plugin touches. */
+export interface HostContext {
+    readonly llm: LlmServiceLike;
+    readonly logger: {
+        info(message: unknown): void;
+        warn(message: unknown): void;
+    };
+    /**
+     * Subscribe to a host event. This plugin watches `loader/volatile-update`,
+     * which is what a settings write emits once the live row references moved.
+     * @param event - the event name.
+     * @param listener - the callback.
+     * @returns the disposer that removes this listener.
+     */
+    on(event: 'loader/volatile-update', listener: () => void): Disposable;
+}
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,125 @@
+/**
+ * dsh-chatjimmy: use the chatjimmy.ai model inside DeepSeek Harness.
+ *
+ * One capability: an `ctx.llm` provider adapter for the reconstructed chat API
+ * (see `API.md`). Registering it makes the route selectable in the Web client's
+ * model picker, because `buildModelCatalog()` enumerates `ctx.llm.listProviders()`
+ * and asks each adapter for `listModels()` / `resolveModel()`.
+ *
+ * See README.md for the known limits: the service has no tool-calling, no
+ * image input, and a 6144-token total context.
+ *
+ * @module dsh-chatjimmy
+ */
+import type { Volatile } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import type { RetryPolicyConfig } from '@deepseek-ai/dsh-llm';
+import type { ChatJimmyConfig } from './protocol.ts';
+import type { HostContext } from './host.ts';
+/** Plugin name as it appears in the loader. */
+export declare const name = "chatjimmy";
+/** The `ctx.llm` provider route this adapter owns. */
+export declare const PROVIDER = "chatjimmy";
+/** The one service this plugin needs mounted. */
+export declare const inject: string[];
+/**
+ * Configuration this plugin's row resolves to, as `apply` receives it.
+ *
+ * Every field a user may edit is `volatile()`, and the loader hands a volatile
+ * field a live reference rather than a value: the schema's own output type,
+ * `Volatile<T>`. Reading `.get()` at use time is what makes an edit from the
+ * Plugins card reach the next request without remounting the route.
+ */
+export interface Config {
+    /** Deployment origin. Defaults to `https://chatjimmy.ai`. Volatile: editable from the Plugins card. */
+    readonly baseUrl: Volatile<string>;
+    /** Model id sent as `chatOptions.selectedModel`. Defaults to `llama3.1-8B`. Volatile. */
+    readonly model: Volatile<string>;
+    /** Forwarded as `chatOptions.topK`. The site's own client sends 8. Volatile. */
+    readonly topK: Volatile<number>;
+    /**
+     * Total context window in tokens used for call-config validation. Measured
+     * against the live service at 6144 (prompt + completion). Volatile.
+     */
+    readonly contextWindow: Volatile<number>;
+    /**
+     * Per-read stream idle watchdog in milliseconds; a stream that produces
+     * nothing for this long ends with the `TIMEOUT` failure. Volatile.
+     */
+    readonly streamIdleTimeoutMs: Volatile<number>;
+    /**
+     * Provider-owned retry policy for this route, in the harness
+     * `RetryPolicyConfig` shape (`{ mode: 'normal' | 'always', … }`). Absent
+     * leaves the harness's own normal defaults. Patch-only: a policy is an
+     * operator's decision, not a form field.
+     */
+    readonly retryPolicy?: RetryPolicyConfig;
+}
+/** Raw row values, as a profile patch states them and as tests pass them. */
+export type Options = {
+    [K in keyof Config]?: Config[K] extends Volatile<infer T> ? T : Config[K];
+};
+/**
+ * Row schema as Cordis resolves it: defaults live here, so a deployment only
+ * states what it changes.
+ *
+ * Every field a user may edit is `volatile()`: the settings document accepts
+ * only volatile paths, and the browser half's card edits exactly these. The
+ * adapter resolves the row per read, so an edit lands on the next request
+ * instead of waiting for a remount. `retryPolicy` stays ordinary
+ * configuration: patch-only, as its docs say.
+ */
+export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
+    baseUrl: Schema<string, string, "volatile-defined">;
+    model: Schema<string, string, "volatile-defined">;
+    topK: Schema<number, number, "volatile-defined">;
+    contextWindow: Schema<number, number, "volatile-defined">;
+    streamIdleTimeoutMs: Schema<number, number, "volatile-defined">;
+    retryPolicy: import("@deepseek-ai/schemastery").default<RetryPolicyConfig>;
+}>>, Schemastery.ObjectT<NoInfer<{
+    baseUrl: Schema<string, string, "volatile-defined">;
+    model: Schema<string, string, "volatile-defined">;
+    topK: Schema<number, number, "volatile-defined">;
+    contextWindow: Schema<number, number, "volatile-defined">;
+    streamIdleTimeoutMs: Schema<number, number, "volatile-defined">;
+    retryPolicy: import("@deepseek-ai/schemastery").default<RetryPolicyConfig>;
+}>>, "plain">;
+/**
+ * Validate and normalize one configuration row.
+ *
+ * The row is fed back through the exported `Config` schema, which is the one
+ * source of the defaults and the numeric bounds. Cordis already ran the same
+ * schema before `apply`, so this only makes `resolveConfig` usable on its own.
+ * What the schema cannot express is checked here: invalid values throw rather
+ * than being silently defaulted, because a typo'd base URL would otherwise
+ * present as an opaque transport failure on the first message.
+ *
+ * @param config - raw row configuration.
+ * @returns the resolved adapter configuration.
+ */
+export declare function resolveConfig(config?: Options): ChatJimmyConfig;
+/**
+ * Read the live row out of the references the loader resolved.
+ *
+ * Every editable field arrives as a `Volatile<T>`; this is the one place that
+ * turns them back into the plain values the schema and the adapter understand,
+ * so a caller cannot forget one.
+ *
+ * @param config - the resolved row.
+ * @returns plain row values, with absent references left undefined.
+ */
+export declare function liveOptions(config: Config): Options;
+/**
+ * Mount the adapter.
+ *
+ * The adapter is handed the resolver itself, not one resolved row: every
+ * configurable field is `volatile()`, so a settings write from the Plugins
+ * card changes what the next request uses without remounting the provider
+ * route (which would drop the model picker's selection). The row is resolved
+ * once here anyway, so an unusable one still fails at mount the way a
+ * non-volatile row would.
+ *
+ * @param ctx - host context; `ctx.llm` must be mounted (`inject` guarantees it).
+ * @param config - this plugin's row configuration.
+ */
+export declare function apply(ctx: HostContext, config: Config): void;

package/lib/types/protocol.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Wire translation between the harness request vocabulary and the
+ * chatjimmy.ai HTTP API reconstructed in `API.md`.
+ *
+ * Everything here is pure so it can be tested without a harness or a network.
+ *
+ * @module dsh-chatjimmy/protocol
+ */
+import type { RetryPolicyConfig } from '@deepseek-ai/dsh-llm';
+import type { ContentBlock, GenerateOptions, TokenUsage } from './host.ts';
+/** Opening marker of the trailing generation-stats block. */
+export declare const STATS_OPEN = "<|stats|>";
+/** Closing marker of the trailing generation-stats block. */
+export declare const STATS_CLOSE = "<|/stats|>";
+/** One wire message chatjimmy accepts. */
+interface WireMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+/** The body `POST /api/chat` expects. */
+interface ChatRequestBody {
+    messages: WireMessage[];
+    chatOptions: {
+        selectedModel: string;
+        systemPrompt: string;
+        topK: number;
+    };
+    attachment: null;
+}
+/** The stats fields this adapter reads; the payload carries more. */
+export interface ChatStats {
+    prefill_tokens?: number;
+    decode_tokens?: number;
+    total_tokens?: number;
+    done_reason?: string;
+    reason?: string;
+    [key: string]: unknown;
+}
+/** Resolved adapter configuration. */
+export interface ChatJimmyConfig {
+    baseUrl: string;
+    model: string;
+    topK: number;
+    contextWindow: number;
+    /** Per-read idle watchdog: a stream that produces nothing for this long fails with `TIMEOUT`. */
+    streamIdleTimeoutMs: number;
+    /**
+     * Provider-owned retry policy, reported to the harness at registration. Absent
+     * means the harness's own normal defaults.
+     */
+    retryPolicy?: RetryPolicyConfig;
+}
+/** Flatten a block list to plain text. */
+export declare function flatten(blocks: readonly ContentBlock[]): string;
+/**
+ * Build the exact request body for one model call: history is flattened to
+ * text, every system-role message is hoisted into the single `systemPrompt`
+ * slot, and the caller's `system` text leads it.
+ */
+export declare function buildChatRequest(options: GenerateOptions, config: ChatJimmyConfig): ChatRequestBody;
+/** Parse the stats payload, returning undefined for malformed JSON. */
+export declare function parseStats(raw: string): ChatStats | undefined;
+/**
+ * True when a stats `reason` reports the backend's own context-limit refusal.
+ * @param reason - the stats `reason` field, when present.
+ */
+export declare function isContextLimitReason(reason: unknown): boolean;
+/**
+ * Map backend token counters onto harness usage.
+ * @param stats - parsed stats, when the stream carried them.
+ * @returns disjoint harness counts (the provider reports no cache split), or
+ *   undefined when the stats carry neither prompt nor output counter. The total
+ *   is the provider's own, else the sum when both parts are known, else omitted.
+ */
+export declare function mapUsage(stats: ChatStats | undefined): TokenUsage | undefined;
+/**
+ * Splits the generated text from the trailing `<|stats|>…<|/stats|>` block
+ * without ever emitting a partial marker.
+ *
+ * The backend appends the block to the same byte stream as the completion, so a
+ * reader that forwarded chunks verbatim would leak `{"prefill_tokens":…}` into
+ * the model's visible answer. Text is held back only as far as a marker could
+ * still be forming, so time-to-first-token is unaffected.
+ */
+export declare class StatsStreamFilter {
+    #private;
+    /**
+     * Absorb one decoded chunk.
+     * @param text - newly decoded text.
+     * @returns the prefix that is certainly completion text.
+     */
+    push(text: string): string;
+    /**
+     * Release whatever the stream ended with.
+     * @returns residual completion text; empty when the body ended on the marker.
+     */
+    flush(): string;
+    /** Stats the stream carried, when the sentinel was complete. */
+    get stats(): ChatStats | undefined;
+}
+export {};

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "chatjimmy",
+    "description": "Text provider adapter for chatjimmy.ai."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "chatjimmy",
+    "description": "chatjimmy.ai 的文本模型适配器。"
+  }
+}