@agentproto/llm-endpoint 0.10.0 → 0.11.1

package/dist/index.d.ts

@@ -228,6 +228,146 @@ interface ConfigurableUpstream {
     pathPrefix: string;
 }
 
+/**
+ * Harness fit check — whether an agent harness's known first-request token
+ * size fits inside an inference endpoint's LOADED context, checked BEFORE a
+ * session is spawned against it. A harness with a big tool-preamble (e.g.
+ * claude-code) can otherwise be spawned blind against a small local model and
+ * die with an opaque upstream 400/500 minutes later.
+ *
+ * Dependency-free and side-effect-free at import time, like `connectors.ts`/
+ * `endpoints.ts`/`packs.ts` — both `@agentproto/cli` and `@agentproto/runtime`
+ * import this directly, so it stays a pure leaf module.
+ */
+type FitVerdict = 'fits' | 'no-fit' | 'unknown';
+interface HarnessFirstRequestSize {
+    /** Measured (or best-known) first-request token count for this harness. */
+    tokens: number;
+    /** Where the number came from — printed alongside it in `doctor`/PR bodies
+     *  so a stale or unmeasured figure is never mistaken for a fresh one. */
+    source: string;
+}
+/**
+ * First-request token size per harness/adapter slug — the size of the FIRST
+ * request a fresh session of that harness sends (tool defs + system preamble
+ * + the first user turn), before any real conversation has accumulated.
+ *
+ * `claude-sdk`'s figure predates SPIKE-A (not re-measured there, carried over
+ * from the design doc's "deferred mode" measurement). `pi`'s figure
+ * SUPERSEDES an earlier ~2k design-doc estimate once SPIKE-A actually
+ * measured it against a real endpoint. Harnesses absent from this table
+ * (e.g. `opencode`) have never been measured — callers must treat that as
+ * `unknown` (see {@link checkHarnessFit}), never guess a number.
+ */
+declare const HARNESS_FIRST_REQUEST_SIZE: Readonly<Record<string, HarnessFirstRequestSize>>;
+/** Default headroom: the endpoint's loaded ctx must be at least
+ *  `requiredTokens / (1 - DEFAULT_HEADROOM_RATIO)` — i.e. the first request
+ *  may use at most `1 - DEFAULT_HEADROOM_RATIO` of the loaded ctx. Matches
+ *  the plan's own worked example (36k required, 25% headroom ⇒ "ctx >= 48k",
+ *  since 36000 / 0.75 = 48000). */
+declare const DEFAULT_HEADROOM_RATIO = 0.25;
+interface FitCheckInput {
+    /** Adapter/harness slug, e.g. "claude-code", "pi". */
+    harness: string;
+    /** The endpoint's loaded ctx (from a connector's `listModels().loadedCtx`),
+     *  or `undefined` when the runtime doesn't expose one (e.g. Ollama). */
+    loadedCtx: number | undefined;
+    /** Fraction of the loaded ctx to hold back as headroom. Default 25%. */
+    headroomRatio?: number;
+    /** Human label for the endpoint, used in the actionable message — e.g.
+     *  `"lmstudio@win-pc"`. Defaults to a generic phrase when omitted. */
+    endpointLabel?: string;
+}
+interface FitCheckResult {
+    verdict: FitVerdict;
+    /** The harness's known first-request size, when known. */
+    requiredTokens?: number;
+    /** The endpoint's loaded ctx, echoed back, when known. */
+    loadedCtx?: number;
+    /** The effective minimum loaded ctx this harness needs at the applied
+     *  headroom — `requiredTokens / (1 - headroomRatio)`, rounded up. */
+    thresholdTokens?: number;
+    headroomRatio: number;
+    /** Actionable, human-readable explanation — present on `no-fit` and
+     *  `unknown` (absent on `fits`, nothing to explain). */
+    message?: string;
+}
+/**
+ * Compare a harness's known first-request size against an endpoint's loaded
+ * ctx. Never throws. Returns `unknown` (never blocks a caller on its own —
+ * see the plan's "`unknown` must not block but must warn" rule) when either
+ * the harness's size or the endpoint's loaded ctx isn't known; `no-fit` with
+ * an actionable message when the harness's first request would not fit
+ * inside the loaded ctx at the requested headroom; `fits` otherwise.
+ */
+declare function checkHarnessFit(input: FitCheckInput): FitCheckResult;
+
+/**
+ * pi wiring — generate/update the matching provider entries in
+ * `~/.pi/agent/models.json` (the `pi` harness's own model registry) from the
+ * configured named endpoints + their connectors, so a locally loaded model
+ * is usable from `pi` without a hand edit.
+ *
+ * Lives in `@agentproto/llm-endpoint` (not `@agentproto/cli`, where it
+ * started) so BOTH the CLI (`agentproto llm endpoints sync-pi`) and the
+ * daemon (`packages/runtime`'s `inference` session-binding, which must
+ * sync before spawning a `pi` session against a local endpoint) can call it
+ * directly — `packages/runtime` never depends on `@agentproto/cli`.
+ *
+ * Two rules drive the shape of this: `contextWindow` must be the model's
+ * LOADED context (what's actually usable right now), never its max — a
+ * stale max value is what caused `~/.pi/agent/models.json` to drift out of
+ * sync by hand in practice; and this must never clobber a user's own
+ * hand-added provider/model entries. One connector (Ollama) never reports a
+ * loaded context size at all — `DEFAULT_CONTEXT_FALLBACK` below covers that
+ * gap with a conservative guess rather than treating a genuinely loaded
+ * model as nothing-to-sync. Ownership of what THIS module wrote is
+ * tracked in a side ledger (`~/.agentproto/pi-models-managed.json`), never
+ * inferred from `models.json`'s own content — that keeps "is this ours" a
+ * recorded fact instead of a guess, and means no extra marker field has to
+ * ride along in a file `pi` itself parses.
+ */
+interface PiModelEntry {
+    id: string;
+    name: string;
+    reasoning: boolean;
+    input: string[];
+    contextWindow: number;
+    maxTokens: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+}
+declare function resolvePiModelsFilePath(): string;
+declare function resolvePiLedgerFilePath(): string;
+interface PiSyncEntry {
+    providerId: string;
+    baseUrl: string;
+    action: 'added' | 'updated' | 'unchanged' | 'skipped-no-loaded-models';
+    modelIds: string[];
+}
+interface PiSyncResult {
+    modelsPath: string;
+    ledgerPath: string;
+    entries: PiSyncEntry[];
+}
+interface PiSyncOptions {
+    dryRun?: boolean;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Regenerate every configured named endpoint's provider entry in pi's
+ * `models.json` from its connector's LIVE loaded models. Never touches a
+ * provider id with no configured endpoint (nothing to regenerate it from),
+ * and within a touched provider, only ever adds/updates/removes the model
+ * ids THIS module previously wrote (per the ledger) — any other model in
+ * that same provider (hand-added by the user) is left exactly as-is.
+ */
+declare function syncPiModels(opts?: PiSyncOptions): Promise<PiSyncResult>;
+
 interface ToolTrimOptions {
     provider: string;
     queryTools: string | null;
@@ -501,4 +641,4 @@ declare const server: node_http.Server<typeof IncomingMessage, typeof ServerResp
 /** Démarre le proxy sur `port` (défaut : {@link PORT}). Renvoie le serveur en écoute. */
 declare function start(port?: number): node_http.Server<typeof IncomingMessage, typeof ServerResponse>;
 
-export { CANONICAL_UPSTREAMS, CONNECTORS, CONNECTOR_IDS, type ConfigurableUpstream, type Connector, type ConnectorId, type ConnectorModel, type ConnectorModelState, type ConnectorQuirks, DEFAULT_LOCAL_PORTS, type EndpointConfig, type EndpointDefaultRequestFields, type EndpointsFileLoad, type ForgeUpstream, type ModelRouteContext, type ToolTrimOptions, type UpstreamCredential, type UpstreamSource, type UpstreamStatus, type UpstreamTestResult, adaptAnthropicToOpenAI, buildUpstreamAuthHeaders, buildWafRuleExpression, collectUpstreamStatuses, connectorById, describeUpstreamStatus, detectConnector, extractEdgeToken, extractInboundToken, getConfiguredEndpoints, isAuthorized, isCanonicalUpstream, isConnectorId, isCredentialAllowedOnOpenAiSurface, isEdgeAuthorized, isEmptyAnthropicTurn, isPublicModelListPath, normalizeProxyPath, openaiJsonToAnthropic, parseAccessTokens, parseEndpointsConfig, readEndpointsFromDisk, resetConfiguredEndpointsCache, resolveEmptyTurnRetries, resolveEndpointsFilePath, resolveForgeBaseUrl, resolveModelRoute, resolveNebiusBaseUrl, resolveUpstreamCredential, server, start, stripThinkingFromAnthropicJson, testUpstream, trimTools };
+export { CANONICAL_UPSTREAMS, CONNECTORS, CONNECTOR_IDS, type ConfigurableUpstream, type Connector, type ConnectorId, type ConnectorModel, type ConnectorModelState, type ConnectorQuirks, DEFAULT_HEADROOM_RATIO, DEFAULT_LOCAL_PORTS, type EndpointConfig, type EndpointDefaultRequestFields, type EndpointsFileLoad, type FitCheckInput, type FitCheckResult, type FitVerdict, type ForgeUpstream, HARNESS_FIRST_REQUEST_SIZE, type HarnessFirstRequestSize, type ModelRouteContext, type PiModelEntry, type PiSyncEntry, type PiSyncOptions, type PiSyncResult, type ToolTrimOptions, type UpstreamCredential, type UpstreamSource, type UpstreamStatus, type UpstreamTestResult, adaptAnthropicToOpenAI, buildUpstreamAuthHeaders, buildWafRuleExpression, checkHarnessFit, collectUpstreamStatuses, connectorById, describeUpstreamStatus, detectConnector, extractEdgeToken, extractInboundToken, getConfiguredEndpoints, isAuthorized, isCanonicalUpstream, isConnectorId, isCredentialAllowedOnOpenAiSurface, isEdgeAuthorized, isEmptyAnthropicTurn, isPublicModelListPath, normalizeProxyPath, openaiJsonToAnthropic, parseAccessTokens, parseEndpointsConfig, readEndpointsFromDisk, resetConfiguredEndpointsCache, resolveEmptyTurnRetries, resolveEndpointsFilePath, resolveForgeBaseUrl, resolveModelRoute, resolveNebiusBaseUrl, resolvePiLedgerFilePath, resolvePiModelsFilePath, resolveUpstreamCredential, server, start, stripThinkingFromAnthropicJson, syncPiModels, testUpstream, trimTools };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { createServer, request } from 'http';
 import { request as request$1 } from 'https';
 import { readFileSync } from 'fs';
-import path, { resolve } from 'path';
+import path, { resolve, join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { randomBytes, createHash } from 'crypto';
 import { getAuthProfile, KeychainStore } from '@agentproto/auth';
@@ -1838,6 +1838,176 @@ function parseUpstreamUrl(value) {
   return { hostname: parsed.hostname, port, protocol, pathPrefix };
 }
 
+// src/harness-fit.ts
+var HARNESS_FIRST_REQUEST_SIZE = {
+  "claude-code": {
+    tokens: 35925,
+    source: "SPIKE-A-RESULTS.md \u2014 two real runs against a local endpoint, 35,925/35,924 tokens (2026-09-27)"
+  },
+  "claude-sdk": {
+    tokens: 18200,
+    source: 'INFERENCE-ENDPOINTS-DESIGN.md \u2014 "deferred mode" measurement (2026-09-27); not re-measured in SPIKE-A, may be stale'
+  },
+  pi: {
+    tokens: 7504,
+    source: "SPIKE-A-RESULTS.md \u2014 real cross-device runs, 7,466-7,504 tokens (2026-09-27); supersedes an earlier ~2k design-doc estimate"
+  }
+};
+var DEFAULT_HEADROOM_RATIO = 0.25;
+function checkHarnessFit(input) {
+  const headroomRatio = input.headroomRatio ?? DEFAULT_HEADROOM_RATIO;
+  const label = input.endpointLabel ?? "this endpoint";
+  const size = HARNESS_FIRST_REQUEST_SIZE[input.harness];
+  if (!size) {
+    return {
+      verdict: "unknown",
+      headroomRatio,
+      message: `"${input.harness}"'s first-request size has not been measured \u2014 proceeding without a fit check. If the spawn fails with a context-overflow error against ${label}, that is why.`
+    };
+  }
+  const requiredTokens = size.tokens;
+  const thresholdTokens = Math.ceil(requiredTokens / (1 - headroomRatio));
+  if (input.loadedCtx === void 0) {
+    return {
+      verdict: "unknown",
+      requiredTokens,
+      thresholdTokens,
+      headroomRatio,
+      message: `${label}'s loaded context size is unknown (this runtime doesn't report it) \u2014 proceeding without a fit check. "${input.harness}" needs ~${formatK(requiredTokens)} tokens for its first request.`
+    };
+  }
+  if (input.loadedCtx >= thresholdTokens) {
+    return { verdict: "fits", requiredTokens, loadedCtx: input.loadedCtx, thresholdTokens, headroomRatio };
+  }
+  return {
+    verdict: "no-fit",
+    requiredTokens,
+    loadedCtx: input.loadedCtx,
+    thresholdTokens,
+    headroomRatio,
+    message: `"${input.harness}" needs ~${formatK(requiredTokens)} tokens for its first request, ${label} has ${formatK(input.loadedCtx)} loaded: use a harness with a smaller first request (e.g. pi), or reload the model with ctx >= ${formatK(thresholdTokens)}.`
+  };
+}
+function formatK(tokens) {
+  return `${Math.round(tokens / 1e3)}k`;
+}
+var DEFAULT_MAX_TOKENS = 8192;
+var DEFAULT_CONTEXT_FALLBACK = 4096;
+function resolvePiModelsFilePath() {
+  const override = process.env.AGENTPROTO_PI_MODELS_FILE?.trim();
+  if (override) return override;
+  return join(homedir(), ".pi", "agent", "models.json");
+}
+function resolvePiLedgerFilePath() {
+  const override = process.env.AGENTPROTO_PI_LEDGER_FILE?.trim();
+  if (override) return override;
+  return join(homedir(), ".agentproto", "pi-models-managed.json");
+}
+function isRecord2(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+async function readJsonFile(path2, fallback) {
+  let raw;
+  try {
+    raw = await readFile(path2, "utf-8");
+  } catch {
+    return fallback;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+async function readPiModelsFile(path2) {
+  const parsed = await readJsonFile(path2, { providers: {} });
+  if (!isRecord2(parsed) || !isRecord2(parsed.providers)) return { providers: {} };
+  const providers = {};
+  for (const [id, raw] of Object.entries(parsed.providers)) {
+    if (!isRecord2(raw) || typeof raw.baseUrl !== "string" || typeof raw.api !== "string" || typeof raw.apiKey !== "string") continue;
+    providers[id] = { baseUrl: raw.baseUrl, api: raw.api, apiKey: raw.apiKey, models: Array.isArray(raw.models) ? raw.models : [] };
+  }
+  return { providers };
+}
+async function readLedger(path2) {
+  const parsed = await readJsonFile(path2, { managed: {} });
+  if (!isRecord2(parsed) || !isRecord2(parsed.managed)) return { managed: {} };
+  const managed = {};
+  for (const [id, ids] of Object.entries(parsed.managed)) {
+    if (Array.isArray(ids)) managed[id] = ids.filter((x) => typeof x === "string");
+  }
+  return { managed };
+}
+async function writeJsonFile(path2, value) {
+  await mkdir(dirname(path2), { recursive: true });
+  await writeFile(path2, `${JSON.stringify(value, null, 2)}
+`);
+}
+function resolveApiKeyValue(endpoint) {
+  if (endpoint.apiKeyEnv) {
+    const value = process.env[endpoint.apiKeyEnv];
+    if (value) return value;
+  }
+  return "not-needed";
+}
+async function buildDesiredModels(endpoint, fetchImpl) {
+  const connectorId = endpoint.connector ?? "openai-compatible";
+  const connector = connectorById(connectorId);
+  if (!connector) return [];
+  const models = await connector.listModels(endpoint.baseUrl, fetchImpl);
+  return models.filter((m) => m.state === "loaded").map((m) => ({
+    id: m.id,
+    name: `${m.id} (${connector.label})`,
+    reasoning: false,
+    input: ["text"],
+    // `loadedCtx` is only absent for a connector (Ollama) whose API never
+    // reports it — see DEFAULT_CONTEXT_FALLBACK above.
+    contextWindow: typeof m.loadedCtx === "number" ? m.loadedCtx : DEFAULT_CONTEXT_FALLBACK,
+    maxTokens: DEFAULT_MAX_TOKENS,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+  }));
+}
+async function syncPiModels(opts = {}) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const modelsPath = resolvePiModelsFilePath();
+  const ledgerPath = resolvePiLedgerFilePath();
+  const endpoints = getConfiguredEndpoints();
+  const piFile = await readPiModelsFile(modelsPath);
+  const ledger = await readLedger(ledgerPath);
+  const entries = [];
+  const nextManaged = { ...ledger.managed };
+  for (const endpoint of endpoints) {
+    const desired = await buildDesiredModels(endpoint, fetchImpl);
+    const previouslyManaged = new Set(ledger.managed[endpoint.id] ?? []);
+    const existingProvider = piFile.providers[endpoint.id];
+    const keptUserModels = (existingProvider?.models ?? []).filter((m) => !previouslyManaged.has(m.id));
+    if (desired.length === 0 && !existingProvider) {
+      entries.push({ providerId: endpoint.id, baseUrl: endpoint.baseUrl, action: "skipped-no-loaded-models", modelIds: [] });
+      continue;
+    }
+    const newModels = [...keptUserModels, ...desired];
+    const unchanged = existingProvider !== void 0 && existingProvider.baseUrl === endpoint.baseUrl && JSON.stringify([...existingProvider.models].sort((a, b) => a.id.localeCompare(b.id))) === JSON.stringify([...newModels].sort((a, b) => a.id.localeCompare(b.id)));
+    piFile.providers[endpoint.id] = {
+      baseUrl: endpoint.baseUrl,
+      api: "openai-completions",
+      apiKey: resolveApiKeyValue(endpoint),
+      models: newModels
+    };
+    nextManaged[endpoint.id] = desired.map((m) => m.id);
+    entries.push({
+      providerId: endpoint.id,
+      baseUrl: endpoint.baseUrl,
+      action: unchanged ? "unchanged" : existingProvider ? "updated" : "added",
+      modelIds: desired.map((m) => m.id)
+    });
+  }
+  if (!opts.dryRun) {
+    await writeJsonFile(modelsPath, piFile);
+    await writeJsonFile(ledgerPath, { managed: nextManaged });
+  }
+  return { modelsPath, ledgerPath, entries };
+}
+
 // src/index.ts
 var PORT = Number(process.env.LLM_ENDPOINT_PORT ?? process.env.PORT ?? 18090);
 var _mergedPackIdsCache = null;
@@ -3919,6 +4089,6 @@ function start(port = PORT) {
   });
 }
 
-export { CANONICAL_UPSTREAMS, CONNECTORS, CONNECTOR_IDS, DEFAULT_LOCAL_PORTS, adaptAnthropicToOpenAI, buildUpstreamAuthHeaders, buildWafRuleExpression, collectUpstreamStatuses, connectorById, describeUpstreamStatus, detectConnector, extractEdgeToken, extractInboundToken, getConfiguredEndpoints, isAuthorized, isCanonicalUpstream, isConnectorId, isCredentialAllowedOnOpenAiSurface, isEdgeAuthorized, isEmptyAnthropicTurn, isPublicModelListPath, normalizeProxyPath, openaiJsonToAnthropic, parseAccessTokens, parseEndpointsConfig, readEndpointsFromDisk, resetConfiguredEndpointsCache, resolveEmptyTurnRetries, resolveEndpointsFilePath, resolveForgeBaseUrl, resolveModelRoute, resolveNebiusBaseUrl, resolveUpstreamCredential, server, start, stripThinkingFromAnthropicJson, testUpstream, trimTools };
+export { CANONICAL_UPSTREAMS, CONNECTORS, CONNECTOR_IDS, DEFAULT_HEADROOM_RATIO, DEFAULT_LOCAL_PORTS, HARNESS_FIRST_REQUEST_SIZE, adaptAnthropicToOpenAI, buildUpstreamAuthHeaders, buildWafRuleExpression, checkHarnessFit, collectUpstreamStatuses, connectorById, describeUpstreamStatus, detectConnector, extractEdgeToken, extractInboundToken, getConfiguredEndpoints, isAuthorized, isCanonicalUpstream, isConnectorId, isCredentialAllowedOnOpenAiSurface, isEdgeAuthorized, isEmptyAnthropicTurn, isPublicModelListPath, normalizeProxyPath, openaiJsonToAnthropic, parseAccessTokens, parseEndpointsConfig, readEndpointsFromDisk, resetConfiguredEndpointsCache, resolveEmptyTurnRetries, resolveEndpointsFilePath, resolveForgeBaseUrl, resolveModelRoute, resolveNebiusBaseUrl, resolvePiLedgerFilePath, resolvePiModelsFilePath, resolveUpstreamCredential, server, start, stripThinkingFromAnthropicJson, syncPiModels, testUpstream, trimTools };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map