@dan-ai-studio/dshopencodego 0.1.55 → 0.1.57

package/lib/types/adapter.d.ts

@@ -59,6 +59,14 @@ export interface OpencodeGoAdapterOptions {
      * discovery per start and nothing else.
      */
     readonly cacheDir?: string;
+    /**
+     * The fetch every gateway request is made through.
+     *
+     * A factory rather than a function: the pin follows the configuration, and
+     * the configuration is live. A request made after a pin was set goes to
+     * the pinned address without the adapter being rebuilt.
+     */
+    readonly fetch?: () => typeof fetch;
     /**
      * Observe the provider's own usage for one completed call. This is the only
      * honest source of token counts: the gateway's `/usage` endpoint reports

package/lib/types/catalog/constants.d.ts

@@ -43,6 +43,11 @@ export declare const METADATA_RETRY_DELAY_MS = 1500;
  * Five minutes is short enough that a service that comes back is picked up
  * soon, and long enough that a service that stays down is asked once, not
  * once per request.
+ *
+ * This is also the ceiling on how long an outage costs. A failed refresh
+ * keeps the age of the last reading that succeeded, so the TTL stays expired
+ * and the next call after this window tries again — a gateway that comes back
+ * is noticed within five minutes, not within a whole TTL.
  */
 export declare const BACKGROUND_RETRY_BACKOFF_MS: number;
 /** Response caps: the listing is tiny, the metadata document is not. */

package/lib/types/catalog/gateway.d.ts

@@ -11,10 +11,15 @@
 export declare function readModelIds(body: unknown): readonly string[];
 /**
  * Fetch the ids the gateway currently advertises.
+ *
+ * The request goes through the given fetch, so a gateway pinned to one
+ * address is read from that address — and, when that address is gone, from
+ * the address the system would have chosen.
  * @param baseURL - normalized gateway base without a trailing slash.
  * @param signal - caller cancellation, if any.
+ * @param request - the fetch to use; the system's own when none is given.
  * @returns the advertised ids in endpoint order, deduplicated.
  * @throws {LlmError} `DISCOVERY_FAILED` when the endpoint is unreachable, not
  *   OK, or does not answer a model listing.
  */
-export declare function fetchModelIds(baseURL: string, signal?: AbortSignal): Promise<readonly string[]>;
+export declare function fetchModelIds(baseURL: string, signal?: AbortSignal, request?: typeof fetch): Promise<readonly string[]>;

package/lib/types/catalog/index.d.ts

@@ -91,6 +91,16 @@ export interface CatalogSnapshot {
      * one that is true now.
      */
     readonly factsCachedAt?: number;
+    /**
+     * When the content of this snapshot was obtained.
+     *
+     * It is the age of the *knowledge*, not of the attempt: a snapshot that
+     * could not be rebuilt keeps the age of the last reading that succeeded,
+     * because that is when the content became true. Stamping it with the time
+     * of the failure instead would make a failed refresh look like a fresh one,
+     * and the TTL that governs the next attempt would then be measured from
+     * the failure rather than from the last thing that was actually known.
+     */
     readonly fetchedAtMs: number;
 }
 /** Observers the plugin logs through. */
@@ -132,6 +142,14 @@ export interface CatalogOptions {
      * nothing else.
      */
     readonly cacheDir?: string;
+    /**
+     * The fetch the gateway listing is read through.
+     *
+     * A factory rather than a function: the pin follows the configuration, and
+     * the configuration is live. A catalogue built before a pin was set must
+     * read the next listing from the pinned address without being rebuilt.
+     */
+    readonly fetch?: () => typeof fetch;
 }
 /**
  * One gateway's catalog. Requests reuse a cached snapshot; explicit discovery

package/lib/types/catalog/reading.d.ts

@@ -48,7 +48,7 @@ export interface CatalogReading {
      * worse than one that admits it.
      */
     readonly cached?: boolean;
-    /** When the underlying snapshot was built. */
+    /** When the content behind this reading was obtained. */
     readonly fetchedAtMs: number;
     /**
      * Where the per-model allowances came from: the provider's live document, or

package/lib/types/config.d.ts

@@ -63,6 +63,12 @@ export interface OpencodeGoConfig {
      * The escape hatch for a model whose family rule guessed wrong.
      */
     modelProtocols: Record<string, string>;
+    /**
+     * 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
+     * own resolution, and so keeps its own fallback.
+     */
+    pinnedAddresses: Record<string, string>;
     /**
      * Retry policy for this route, owned here and executed by the optional
      * `dsh-llm-retry` plugin. Absent leaves the host's own default in force.

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

@@ -0,0 +1,32 @@
+/**
+ * Wire contract for the network Remote.
+ *
+ * One reading, answering one question: which address is the gateway sent to
+ * right now, and did that address survive its first request?
+ *
+ * A spent address is not a failure the user has to fix — the requests are
+ * being served by the system's own resolution, and this says so.
+ *
+ * @module @dan-ai-studio/dshopencodego/network/contract
+ */
+import type { RemoteResult, TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol';
+/** The gateway's name and the address it is pinned to. */
+export interface NetworkReading {
+    /** The gateway's name. */
+    readonly host: string;
+    /** The address the name is pinned to; absent when nothing is pinned. */
+    readonly address?: string;
+    /** Whether the pinned address was found to be gone. */
+    readonly failed?: boolean;
+}
+/** Validate a network reading crossing the wire. */
+export declare function parseNetworkReading(value: unknown): NetworkReading;
+declare module '@deepseek-ai/dsh-typert-protocol' {
+    interface TypertRemoteNamespaceMap {
+        opencodeGoNetwork: {
+            readNetwork(): Promise<RemoteResult<NetworkReading>>;
+        };
+    }
+}
+/** Remote methods this package owns, mounted together by the plugin. */
+export declare const networkRemote: TypertRemoteContribution;

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

@@ -0,0 +1,97 @@
+/**
+ * Pinning a name to an address.
+ *
+ * A name that the system resolves may reach an edge that is far away, and
+ * a far edge costs every request. Pinning the name to another address of the
+ * same network sends it to a different edge instead.
+ *
+ * The certificate is still checked against the name: only the resolution
+ * changes, never the name the server is asked to prove. That is why this
+ * is a lookup and not a redirect.
+ *
+ * Only the gateway's own name is pinned. Every other name — the metadata
+ * registry, the provider's documentation — keeps the system's own
+ * resolution, including its fallback, its cache, and whatever the host's
+ * resolver decides.
+ *
+ * A pin that cannot be reached is not the end of the request. The address may
+ * be gone, and the name may still be served perfectly well by the address the
+ * system would have chosen — so the request is sent again, that way, and the
+ * answer is the one the caller gets. A wrong address must never cost more
+ * than no address at all, so the pin is remembered as spent and the rest of
+ * the requests go straight to the system's resolution.
+ *
+ * @module @dan-ai-studio/dshopencodego/network/pinning
+ */
+/** A name and the address it should be sent to. */
+export type PinnedAddresses = Readonly<Record<string, string>>;
+/**
+ * The gateway's own name and the address it is pinned to.
+ *
+ * An absent address is the whole point of the type: nothing is pinned, and
+ * every request goes to the system's own resolution, untouched.
+ */
+export interface GatewayPin {
+    /** The gateway's name, lowercased. */
+    readonly host: string;
+    /** The address the name is sent to; absent when nothing is pinned. */
+    readonly address?: string;
+}
+/**
+ * The gateway's own name, as the configured endpoint states it.
+ *
+ * The endpoint is where every request of this plugin goes, so its name is
+ * the only one worth pinning: a name nobody here asks for has no request to
+ * redirect.
+ * @param baseURL - the configured gateway base.
+ * @returns the lowercased host, or an empty string when the endpoint is not
+ *   a URL this plugin can parse.
+ */
+export declare function gatewayHostOf(baseURL: string): string;
+/**
+ * The pin that applies to the configured gateway.
+ *
+ * A pin for another name is not this plugin's business: the endpoint is what
+ * this plugin asks for, and a name that is not the endpoint's is never on
+ * the path of a request. An address that is not an address is a typo worth
+ * ignoring rather than a crash in the middle of a request, and ignoring it
+ * means the request goes to the system's resolution — which is exactly what
+ * an unconfigured plugin does.
+ * @param pins - the configured pins.
+ * @param baseURL - the configured gateway base.
+ * @returns the gateway's name and, when one is configured and usable, the
+ *   address it is pinned to.
+ */
+export declare function resolveGatewayPin(pins: PinnedAddresses, baseURL: string): GatewayPin;
+/**
+ * Close the dispatcher, if one is open.
+ *
+ * The plugin's own lifetime is the host's, so this is only for a test or
+ * a shutdown that wants the sockets gone now.
+ */
+export declare function closeDispatcher(): Promise<void>;
+/**
+ * Whether the pinned address was already found to be gone.
+ *
+ * A spent address is not tried again: the request that proved it gone is
+ * the one that paid for it, and every later request would pay the same price
+ * for the same answer.
+ * @param pin - the pin.
+ * @returns true when the address was found to be gone.
+ */
+export declare function isPinSpent(pin: GatewayPin): boolean;
+/**
+ * A fetch that sends the gateway's name to the pinned address.
+ *
+ * A request for another name is sent exactly as it would have been: the
+ * dispatcher only answers the name it was given, and the rest keep the
+ * system's own resolution.
+ *
+ * A pinned address that cannot be reached is not the end of the request.
+ * The address may be gone, and the name may still be served perfectly well
+ * by the address the system would have chosen — so the request is sent
+ * again, that way, and the answer is the one the caller gets.
+ * @param pin - the gateway's name and its pinned address.
+ * @returns the fetch to use.
+ */
+export declare function gatewayFetch(pin: GatewayPin): typeof fetch;

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

@@ -0,0 +1,27 @@
+/**
+ * Host half of the network Remote.
+ *
+ * The page needs to know which address the gateway is sent to, and whether
+ * that address is still working: a pin that was found to be gone leaves the
+ * requests on the system's own resolution, and a page that kept showing the
+ * old address would claim a speed the plugin is no longer delivering.
+ *
+ * @module @dan-ai-studio/dshopencodego/network/service
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { NetworkReading } from './contract.ts';
+/** Host inputs for the network service. */
+export interface NetworkServiceOptions {
+    /** Current gateway base URL. */
+    readonly baseURL: () => string;
+    /** The configured pins, by host name. */
+    readonly pinnedAddresses: () => Readonly<Record<string, string>>;
+}
+/** The network Remote: the gateway's name, its pin, and that pin's health. */
+export declare class OpencodeGoNetworkService extends TypertRemoteService {
+    private readonly options;
+    constructor(ctx: Context, options: NetworkServiceOptions);
+    /** The gateway's name and its pin, as the configuration states them. */
+    readNetwork(): Promise<NetworkReading>;
+}

package/lib/types/usage/service.d.ts

@@ -22,6 +22,14 @@ export interface UsageServiceOptions {
     readonly resolveApiKey: () => Promise<string | undefined>;
     /** The process-lifetime meter fed by the adapter. */
     readonly meter: UsageMeter;
+    /**
+     * The fetch the usage read is made through.
+     *
+     * A factory rather than a function: the pin follows the configuration, and
+     * the configuration is live. A read made after a pin was set goes to the
+     * pinned address without the service being rebuilt.
+     */
+    readonly fetch?: () => typeof fetch;
 }
 /**
  * Decide what one failed read means for the client.

package/lib/types/usage/windows.d.ts

@@ -40,6 +40,14 @@ interface UsageReadOptions {
     /** Opaque identity of the endpoint and credential pair, when known. */
     readonly source?: string;
     readonly signal?: AbortSignal;
+    /**
+     * The fetch to use.
+     *
+     * The read goes to the gateway, so a gateway pinned to one address is read
+     * from that address — and, when that address is gone, from the address the
+     * system would have chosen.
+     */
+    readonly request?: typeof fetch;
 }
 /**
  * Read the account's usage windows.

package/package.json

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