@sagmans/dsh-provider-extra 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,135 @@
1
+ import { PiAiAdapter } from '@deepseek-ai/dsh-llm-pi-ai';
2
+ import { LlmError, assertUsableApiKey, resolveImageAttachmentAccess } from '@deepseek-ai/dsh-llm';
3
+ import { codexAuth } from "./codex.js";
4
+ import { catalogDefault } from "./catalog-default.js";
5
+ import { mountLoginCommand } from "./login-host.js";
6
+ const PLUGIN_NAME = 'dsh-provider-extra';
7
+ const OWNER_COLLISION = 'CATALOG_OWNER_COLLISION';
8
+ /** Preflight prevents even an unrelated competing row from expanding managed membership. */
9
+ function assertCatalogOwnership(ctx, ownedRoutes = [], defaultOwner) {
10
+ const currentDefault = ctx.get('agentDefaultModel');
11
+ if ((currentDefault !== undefined && currentDefault !== defaultOwner)
12
+ || ctx.llm.listProviders().some(provider => !ownedRoutes.includes(provider.id))
13
+ || ctx.llm.listConfigurableProviders().length > 0) {
14
+ throw new LlmError('dsh-provider-extra: ' + OWNER_COLLISION + ': disable competing provider and agent-default-model rows in this opted-in profile before mounting catalog', OWNER_COLLISION);
15
+ }
16
+ }
17
+ /** Immutable closures also keep prepared and in-flight calls on their original revision. */
18
+ export function mountCatalog(ctx, snapshot, config) {
19
+ assertCatalogOwnership(ctx);
20
+ let ownershipError;
21
+ const requireOwnership = () => {
22
+ if (ownershipError !== undefined)
23
+ throw ownershipError;
24
+ };
25
+ const auth = codexAuth(() => ctx.get('credentials'));
26
+ const credentialId = (route) => {
27
+ const configured = snapshot.providers.get(route)?.auth;
28
+ return configured !== undefined && 'credentialProvider' in configured ? configured.credentialProvider : route;
29
+ };
30
+ const adapter = new PiAiAdapter({
31
+ profiles: () => { requireOwnership(); return snapshot.profiles; },
32
+ auth: {
33
+ ...auth,
34
+ // Route aliases must share the source provider's existing OAuth grant.
35
+ credentials: {
36
+ read: async (route) => {
37
+ requireOwnership();
38
+ try {
39
+ return await auth.credentials.read(credentialId(route));
40
+ }
41
+ finally {
42
+ requireOwnership();
43
+ }
44
+ },
45
+ modify: async (route, change) => {
46
+ requireOwnership();
47
+ try {
48
+ return await auth.credentials.modify(credentialId(route), current => {
49
+ // A rotated token must persist; the outer guard still blocks model dispatch.
50
+ requireOwnership();
51
+ return change(current);
52
+ });
53
+ }
54
+ finally {
55
+ requireOwnership();
56
+ }
57
+ },
58
+ delete: route => {
59
+ requireOwnership();
60
+ return auth.credentials.delete(credentialId(route));
61
+ },
62
+ list: async () => {
63
+ // Stored grants are part of the same owned membership: a conflicting
64
+ // composition must not report routes it can no longer dispatch to.
65
+ requireOwnership();
66
+ const stored = await auth.credentials.list();
67
+ return [...snapshot.providers.values()].flatMap(provider => {
68
+ if (provider.auth === undefined || !('credentialProvider' in provider.auth))
69
+ return [];
70
+ const record = stored.find(item => item.providerId === credentialId(provider.id));
71
+ return record === undefined ? [] : [{ ...record, providerId: provider.id }];
72
+ });
73
+ },
74
+ },
75
+ },
76
+ resolveApiKey: async (route) => {
77
+ // Prepared calls retain their snapshot and bypass profiles(); this gate
78
+ // stops a newly conflicting composition before credential-backed dispatch.
79
+ requireOwnership();
80
+ const configured = snapshot.providers.get(route);
81
+ if (configured === undefined)
82
+ throw new LlmError('dsh-provider-extra: unknown catalog route "' + route + '"', 'UNKNOWN_PROVIDER');
83
+ if (configured.auth === undefined || !('apiKeyRef' in configured.auth))
84
+ return undefined;
85
+ const ref = configured.auth.apiKeyRef;
86
+ const credentials = ctx.get('credentials');
87
+ const key = credentials === undefined ? process.env[ref] : (await credentials.resolve(ref))?.value;
88
+ requireOwnership();
89
+ if (key !== undefined && key.length > 0)
90
+ return assertUsableApiKey(key, PLUGIN_NAME, ref);
91
+ throw new LlmError('dsh-provider-extra: no credential for route "' + route + '"; its Config references ' + ref, 'MISSING_CREDENTIAL');
92
+ },
93
+ resolveAttachments: () => ctx.get('attachments'),
94
+ resolveImageAccess: (attachments, ref) => resolveImageAttachmentAccess(attachments, hostPath => ctx.get('fs')?.processPathFromHostPath(hostPath), ref),
95
+ onReplayDegrade: ({ provider, model, reason }) => {
96
+ ctx.logger.warn('dsh-provider-extra: unusable replay state for "' + provider + '/' + model + '" (' + reason + ')');
97
+ },
98
+ });
99
+ const routes = [...snapshot.profiles.keys()];
100
+ // The runtime rejects an empty registration; an explicitly empty catalog
101
+ // instead owns only the default contract, which reports NO_DEFAULT_MODEL.
102
+ if (routes.length > 0)
103
+ ctx.llm.registerAdapter(routes, adapter);
104
+ const defaults = catalogDefault(ctx, snapshot, requireOwnership);
105
+ ctx.provide('agentDefaultModel', defaults);
106
+ // Notifications follow registry commit: diagnose, never veto or mutate the
107
+ // other owner. Disposing this listener leaves retained valid calls intact.
108
+ const refreshOwnership = () => {
109
+ try {
110
+ assertCatalogOwnership(ctx, routes, defaults);
111
+ ownershipError = undefined;
112
+ }
113
+ catch (error) {
114
+ const previous = ownershipError;
115
+ ownershipError = error;
116
+ if (previous === undefined)
117
+ ctx.logger.error(error);
118
+ }
119
+ };
120
+ ctx.on('llm/adapters-updated', refreshOwnership);
121
+ refreshOwnership();
122
+ // A public update veto runs before disposal, so a competing late-mounted
123
+ // adapter cannot turn a refused reload into loss of the last valid catalog.
124
+ ctx.on('internal/update', (next, _noSave, proceed) => {
125
+ if (next.catalog !== undefined)
126
+ assertCatalogOwnership(ctx, routes, defaults);
127
+ return proceed();
128
+ });
129
+ mountLoginCommand(ctx, config, { catalog: snapshot, profiles: () => snapshot.profiles, requireOwnership });
130
+ ctx.inject(['settings'], (child) => {
131
+ const settings = child.get('settings');
132
+ if (typeof settings.configure === 'function')
133
+ child.effect(() => settings.configure({ auto: false }, ctx.fiber));
134
+ });
135
+ }
@@ -0,0 +1,65 @@
1
+ import { getSupportedThinkingLevels } from '@earendil-works/pi-ai';
2
+ import { buildCatalogProfile, catalogError, catalogMap, catalogRecord, catalogString, freezeCatalogValue } from "./catalog-routes.js";
3
+ const CONFIG_VERSION = 1;
4
+ const CONFIG_FIELDS = ['version', 'providers', 'default'];
5
+ const SELECTION_FIELDS = ['provider', 'model', 'reasoningEffort'];
6
+ /** Absence keeps legacy ownership separate from a managed empty catalog. */
7
+ export function compileCatalog(config) {
8
+ if (config === undefined)
9
+ return undefined;
10
+ const raw = catalogRecord(config, CONFIG_FIELDS, 'config');
11
+ if (raw.version !== CONFIG_VERSION)
12
+ catalogError('version', 'expected version 1');
13
+ if (!Array.isArray(raw.providers))
14
+ catalogError('providers', 'expected an explicit array');
15
+ const profiles = new Map();
16
+ for (const declaration of raw.providers) {
17
+ const profile = buildCatalogProfile(declaration);
18
+ if (profiles.has(profile.provider))
19
+ catalogError('providers', 'duplicate provider ' + profile.provider);
20
+ profiles.set(profile.provider, profile);
21
+ }
22
+ const normalized = structuredClone(raw);
23
+ const providers = catalogMap(normalized.providers.map(provider => [provider.id, provider]));
24
+ const aliases = new Map();
25
+ let count = 0;
26
+ for (const provider of normalized.providers) {
27
+ const routeAliases = new Map();
28
+ // Served models, not declarations: a filtered route owns ids it never spells out.
29
+ for (const model of profiles.get(provider.id).piProvider.getModels()) {
30
+ routeAliases.set(model.id, model.id);
31
+ count++;
32
+ }
33
+ for (const model of provider.models ?? []) {
34
+ for (const alias of model.aliases ?? [])
35
+ routeAliases.set(alias, model.id);
36
+ }
37
+ aliases.set(provider.id, routeAliases);
38
+ }
39
+ const resolveSelection = (input) => {
40
+ const candidate = catalogRecord(input, SELECTION_FIELDS, 'selection');
41
+ catalogString(candidate.provider, 'selection.provider');
42
+ catalogString(candidate.model, 'selection.model');
43
+ const modelId = aliases.get(candidate.provider)?.get(candidate.model);
44
+ if (modelId === undefined)
45
+ catalogError('selection', 'provider/model is outside the managed selection');
46
+ const model = profiles.get(candidate.provider).piProvider.getModels().find(model => model.id === modelId);
47
+ if ('reasoningEffort' in candidate && !getSupportedThinkingLevels(model).includes(candidate.reasoningEffort)) {
48
+ catalogError('selection.reasoningEffort', 'effort is not supported by the selected model');
49
+ }
50
+ return freezeCatalogValue({
51
+ provider: candidate.provider, model: modelId,
52
+ ...('reasoningEffort' in candidate ? { reasoningEffort: candidate.reasoningEffort } : {}),
53
+ });
54
+ };
55
+ if (count === 0) {
56
+ if (normalized.default !== null)
57
+ catalogError('default', 'empty catalog requires null');
58
+ }
59
+ else
60
+ normalized.default = resolveSelection(normalized.default);
61
+ return freezeCatalogValue({
62
+ config: normalized, profiles: catalogMap(profiles), providers,
63
+ selection: normalized.default, resolveSelection,
64
+ });
65
+ }
package/dist/codex.js CHANGED
@@ -14,6 +14,7 @@ import { defaultProviderAuthContext } from '@earendil-works/pi-ai';
14
14
  import { builtinProviders } from '@earendil-works/pi-ai/providers/all';
15
15
  import { credentialKey, credentialKeyId, credentialKeyScope, isCredentialKeySegment, } from '@deepseek-ai/dsh-credentials';
16
16
  import { LlmError, resolveRetryPolicy } from '@deepseek-ai/dsh-llm';
17
+ import { resolveExtraModels, selectWhitelistedModels } from "./extra-models.js";
17
18
  /** pi-ai catalog id of the ChatGPT-subscription provider this route serves. */
18
19
  export const CODEX_CATALOG_ID = 'openai-codex';
19
20
  /**
@@ -24,6 +25,14 @@ export const CODEX_CATALOG_ID = 'openai-codex';
24
25
  export const DEFAULT_CODEX_ROUTE_ID = CODEX_CATALOG_ID;
25
26
  /** Display name for selectors, matching pi-ai's subscription label. */
26
27
  export const DEFAULT_CODEX_DISPLAY_NAME = 'OpenAI Codex';
28
+ /**
29
+ * Transports pi-ai's Codex API accepts, as that API declares them. Named here
30
+ * because a profile pins one: the websocket path keeps a connection-scoped
31
+ * continuation cache, which some networks and proxies never let complete.
32
+ * Mirrors @earendil-works/pi-ai/dist/types.d.ts:41 (Transport); review this
33
+ * schema alongside dependency upgrades so added transports are not silently excluded.
34
+ */
35
+ export const CODEX_TRANSPORTS = ['sse', 'websocket', 'websocket-cached', 'auto'];
27
36
  /**
28
37
  * Record scope for the OAuth grant. Identical to dsh-llm-pi-ai's own scope,
29
38
  * which is what makes a grant written by the login script readable by core's
@@ -132,6 +141,20 @@ export class HarnessCredentialStore {
132
141
  await this.credentials()?.deleteRecord(recordKeyFor(providerId));
133
142
  }
134
143
  }
144
+ /**
145
+ * Stamp the pinned transport onto one request's stream options. pi-ai selects
146
+ * its Codex transport per request, so this is the only boundary where a profile
147
+ * can choose one; a route that pins none hands pi-ai's options through exactly
148
+ * as it received them.
149
+ * @param options - the per-request stream options pi-ai is about to dispatch.
150
+ * @param config - the route configuration.
151
+ * @returns the options with the transport pinned, or unchanged when none is.
152
+ */
153
+ export function withTransport(options, config) {
154
+ if (config.transport === undefined || options === undefined)
155
+ return options;
156
+ return { ...options, transport: config.transport };
157
+ }
135
158
  /**
136
159
  * The installed pi-ai catalog's Codex provider, whose API implementation,
137
160
  * OAuth auth, and model list this route reuses rather than reconstructing.
@@ -152,8 +175,8 @@ export function catalogCodex() {
152
175
  * catalog provider so its API implementation and OAuth quirks survive, while
153
176
  * identity and models answer to the route configuration.
154
177
  */
155
- function routeProvider(config, catalog) {
156
- const models = catalog.getModels().map(model => ({
178
+ function routeProvider(config, catalog, models) {
179
+ const routed = models.map(model => ({
157
180
  ...model,
158
181
  provider: config.provider,
159
182
  }));
@@ -164,9 +187,9 @@ function routeProvider(config, catalog) {
164
187
  id: config.provider,
165
188
  name: config.displayName,
166
189
  auth: catalog.auth,
167
- getModels: () => models,
168
- stream: (model, context, options) => catalog.stream(model, context, options),
169
- streamSimple: (model, context, options) => catalog.streamSimple(model, context, options),
190
+ getModels: () => routed,
191
+ stream: (model, context, options) => catalog.stream(model, context, withTransport(options, config)),
192
+ streamSimple: (model, context, options) => catalog.streamSimple(model, context, withTransport(options, config)),
170
193
  };
171
194
  }
172
195
  // The resolved profile defaults below mirror dsh-llm-pi-ai's config
@@ -188,6 +211,14 @@ const REQUEST_IMAGE_MAX_BYTES = 1024 * 1024;
188
211
  */
189
212
  export function buildCodexProfile(config) {
190
213
  const catalog = catalogCodex();
214
+ // Codex ships no fallback template: a sibling from another vendor's gateway
215
+ // would be dispatched as if the subscription served it, so a declaration
216
+ // that names none is reported instead of cloned.
217
+ const extras = resolveExtraModels(catalog.getModels(), config.extraModels ?? []);
218
+ // Selection runs last so a whitelist may name a declared extra exactly as it
219
+ // names a catalog model, and so a typo in either is refused here rather than
220
+ // served as a route quietly missing a model.
221
+ const models = selectWhitelistedModels(config.provider, [...catalog.getModels(), ...extras.models], config.models);
191
222
  return {
192
223
  provider: config.provider,
193
224
  displayName: config.displayName,
@@ -196,9 +227,9 @@ export function buildCodexProfile(config) {
196
227
  requestImagePixelBudget: REQUEST_IMAGE_PIXEL_BUDGET,
197
228
  requestImageMaxBytes: REQUEST_IMAGE_MAX_BYTES,
198
229
  retryPolicy: resolveRetryPolicy(undefined, 'dsh-provider-extra: openai-codex'),
199
- modelErrors: new Map(),
230
+ modelErrors: extras.modelErrors,
200
231
  configuredMaxTokens: new Map(),
201
- piProvider: routeProvider(config, catalog),
232
+ piProvider: routeProvider(config, catalog, models),
202
233
  };
203
234
  }
204
235
  /**
@@ -0,0 +1,93 @@
1
+ /**
2
+ * Declared models, shared by every route this plugin owns.
3
+ *
4
+ * Two declarations share this module. An extra adds an id the installed
5
+ * catalog predates, cloning a template sibling's wire behavior instead of
6
+ * restating it; a declaration that cannot resolve lands in the route's model
7
+ * diagnostics beside its serviceable models, because one mistyped template
8
+ * must not silence a whole route. A whitelist instead selects which of the
9
+ * resolved models a route serves, and refuses the whole route when it names an
10
+ * id nothing provides — a configuration typo there is a broken deployment, not
11
+ * a diagnosable one-model problem.
12
+ *
13
+ * @module dsh-provider-extra/extra-models
14
+ */
15
+ import { LlmError } from '@deepseek-ai/dsh-llm';
16
+ /**
17
+ * Resolve declared extras against the installed catalog. Later specs win over
18
+ * earlier ones by id, so a settings entry reshapes a shipped default under the
19
+ * same id; an id the catalog itself ships stays with the catalog.
20
+ * @param catalog - installed catalog models to clone wire behavior from.
21
+ * @param specs - declared extras, shipped defaults first.
22
+ * @param fallbackTemplate - catalog id used when a spec names no template; a
23
+ * route whose gateway serves no representative sibling omits it, so the
24
+ * omission is reported instead of cloned from an unrelated provider.
25
+ * @returns the resolved extras and per-model failure diagnostics.
26
+ */
27
+ export function resolveExtraModels(catalog, specs, fallbackTemplate) {
28
+ const models = [];
29
+ const modelErrors = new Map();
30
+ const shipped = new Set(catalog.map(model => model.id));
31
+ const byId = new Map();
32
+ for (const spec of specs)
33
+ byId.set(spec.id, spec);
34
+ for (const spec of byId.values()) {
35
+ if (spec.id.length === 0) {
36
+ modelErrors.set(spec.id, 'dsh-provider-extra: an extra model has an empty id');
37
+ continue;
38
+ }
39
+ if (shipped.has(spec.id))
40
+ continue;
41
+ const templateId = spec.template ?? fallbackTemplate;
42
+ if (templateId === undefined) {
43
+ modelErrors.set(spec.id, 'dsh-provider-extra: extra model "' + spec.id + '" names no template'
44
+ + ' and this route ships no default sibling to clone');
45
+ continue;
46
+ }
47
+ const template = catalog.find(model => model.id === templateId);
48
+ if (template === undefined) {
49
+ modelErrors.set(spec.id, 'dsh-provider-extra: extra model "' + spec.id + '" names template "' + templateId + '",'
50
+ + ' which the installed catalog does not describe');
51
+ continue;
52
+ }
53
+ models.push({ ...template, id: spec.id, name: spec.name ?? template.name });
54
+ }
55
+ return { models, modelErrors };
56
+ }
57
+ /**
58
+ * Narrow one route's resolved models to a declared whitelist and put them in
59
+ * the declared order. Absent means the route serves everything it resolved;
60
+ * present means exactly those ids, so the picker and the gateway agree.
61
+ * Resolution order — the installed catalog, then the route's shipped extras,
62
+ * then the declared ones — stays the authority on which id exists, and a
63
+ * whitelist may therefore name a catalog id, a shipped extra, or a declared
64
+ * extra.
65
+ * @param route - route id the refusal names.
66
+ * @param models - resolved catalog and extra models, in resolution order.
67
+ * @param whitelist - exact ids to serve, or undefined to serve every model.
68
+ * @returns the selected models in declared order.
69
+ * @throws {LlmError} when the whitelist names an id nothing resolves; failing
70
+ * the route loud is the only alternative that cannot silently serve less than
71
+ * the deployment asked for.
72
+ */
73
+ export function selectWhitelistedModels(route, models, whitelist) {
74
+ if (whitelist === undefined)
75
+ return [...models];
76
+ const byId = new Map(models.map(model => [model.id, model]));
77
+ const selected = [];
78
+ const seen = new Set();
79
+ for (const id of whitelist) {
80
+ // A repeated id is one model, kept at its first position: advertising the
81
+ // same id twice would offer the picker two entries no request distinguishes.
82
+ if (seen.has(id))
83
+ continue;
84
+ seen.add(id);
85
+ const model = byId.get(id);
86
+ if (model === undefined) {
87
+ throw new LlmError('dsh-provider-extra: route "' + route + '" declares model "' + id + '" in its model selection,'
88
+ + ' but neither the installed pi-ai catalog nor an extra model declaration provides it', 'UNKNOWN_MODEL');
89
+ }
90
+ selected.push(model);
91
+ }
92
+ return selected;
93
+ }