@dan-ai-studio/dshopencodego 0.1.54 → 0.1.56

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/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/go-doc-discovery.d.ts

@@ -24,6 +24,16 @@
  */
 /** A repository listing is large; the cap keeps a hostile response bounded. */
 export declare const DISCOVERY_MAX_BYTES: number;
+/**
+ * How long the repository listing waits before it is asked again.
+ *
+ * The listing is unauthenticated, and an unauthenticated GitHub API allows
+ * sixty requests an hour. The listing is also large — the provider's whole
+ * tree, thousands of entries. Asking it on every build would spend that
+ * budget on a provider that is merely unreachable, and would make every
+ * build slower for a question with the same answer.
+ */
+export declare const DISCOVERY_COOLDOWN_MS: number;
 /**
  * The repository paths a discovery run found.
  *
@@ -76,3 +86,21 @@ export declare function readCachedPaths(cacheDir: string | undefined): readonly
  * @returns the merged set, in the order it should be tried.
  */
 export declare function rememberPaths(cacheDir: string | undefined, discovered: readonly string[]): readonly string[];
+/**
+ * Whether the repository may be asked again.
+ *
+ * The question is worth at most an hour: a provider whose document has
+ * moved is found within the hour, and one that is merely down is not asked
+ * again every minute while it is down.
+ * @param cacheDir - the plugin's cache directory.
+ * @returns true when the repository may be asked.
+ */
+export declare function discoveryAllowed(cacheDir: string | undefined): boolean;
+/**
+ * Record that the repository was asked, whether or not it answered.
+ *
+ * The attempt is what the budget is spent on, so a question that came back
+ * empty counts as a question.
+ * @param cacheDir - the plugin's cache directory.
+ */
+export declare function rememberAttempt(cacheDir: string | undefined): void;

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

@@ -132,6 +132,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/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.54",
+  "version": "0.1.56",
   "description": "OpenCode Go provider for DeepSeek Harness: live gateway catalog, per-conversation session header, usage",
   "type": "module",
   "license": "MIT",