@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.
- package/README.md +95 -14
- package/dist/catalog-default.js +39 -0
- package/dist/catalog-protocols.js +15 -0
- package/dist/catalog-routes.js +369 -0
- package/dist/catalog-runtime.js +135 -0
- package/dist/catalog.js +65 -0
- package/dist/codex.js +38 -7
- package/dist/extra-models.js +93 -0
- package/dist/index.js +108 -141
- package/dist/login-attempt.js +29 -7
- package/dist/login-choice.js +25 -14
- package/dist/login-command.js +16 -9
- package/dist/login-contract.js +3 -1
- package/dist/login-host.js +196 -0
- package/dist/login-verify.js +10 -5
- package/dist/opencode-go.js +10 -41
- package/docs/catalog-v1.example.json +40 -0
- package/docs/catalog.md +218 -0
- package/package.json +3 -1
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
import { credentialRef } from '@deepseek-ai/dsh-credentials';
|
|
2
|
+
import { LlmError, assertUsableApiKey } from '@deepseek-ai/dsh-llm';
|
|
3
|
+
import { createModels } from '@earendil-works/pi-ai';
|
|
4
|
+
import { builtinProviders } from '@earendil-works/pi-ai/providers/all';
|
|
5
|
+
import { codexAuth, recordKeyFor } from "./codex.js";
|
|
6
|
+
import { createLoginCommand } from "./login-command.js";
|
|
7
|
+
import { StoredCredentialError } from "./login-contract.js";
|
|
8
|
+
import { declareProviderRoute, declaredCredentialRef } from "./login-route.js";
|
|
9
|
+
import { PendingCredentialStore, proveApiKey } from "./login-verify.js";
|
|
10
|
+
const PLUGIN_NAME = 'dsh-provider-extra';
|
|
11
|
+
const GO_SOURCE = 'opencode-go';
|
|
12
|
+
const CODEX_SOURCE = 'openai-codex';
|
|
13
|
+
const MISSING_STORE = 'This composition has no writable credentials service; mount dsh-credentials-local before signing in.';
|
|
14
|
+
const READ_ONLY = 'The configured credential is read-only; change its supplying source before signing in.';
|
|
15
|
+
/** Profile headers are adapter-owned defaults, so direct proof must carry them too. */
|
|
16
|
+
function loginProvider(profile, fallback) {
|
|
17
|
+
const provider = profile?.piProvider ?? fallback;
|
|
18
|
+
if (profile?.headers === undefined)
|
|
19
|
+
return provider;
|
|
20
|
+
return { ...provider,
|
|
21
|
+
stream: (model, context, options) => provider.stream(model, context, { ...options, headers: { ...profile.headers, ...options?.headers } }),
|
|
22
|
+
streamSimple: (model, context, options) => provider.streamSimple(model, context, { ...options, headers: { ...profile.headers, ...options?.headers } }), };
|
|
23
|
+
}
|
|
24
|
+
/** Managed membership and legacy catalog discovery deliberately choose different target sets. */
|
|
25
|
+
function loginTargets(ctx, config, routes) {
|
|
26
|
+
const profiles = routes.profiles();
|
|
27
|
+
if (routes.catalog !== undefined) {
|
|
28
|
+
return [...routes.catalog.providers.values()].map(route => ({
|
|
29
|
+
id: route.id, provider: profiles.get(route.id).piProvider, auth: route.auth, served: true,
|
|
30
|
+
}));
|
|
31
|
+
}
|
|
32
|
+
return builtinProviders().map(source => {
|
|
33
|
+
const profile = source.id === GO_SOURCE ? profiles.get(config.routeId)
|
|
34
|
+
: source.id === CODEX_SOURCE ? profiles.get(config.codexRouteId) : undefined;
|
|
35
|
+
// The plugin's Go adapter resolves its Config reference before considering any provider record.
|
|
36
|
+
const ref = source.id === GO_SOURCE ? config.apiKeyEnv
|
|
37
|
+
: source.id === CODEX_SOURCE && profile !== undefined ? undefined : declaredCredentialRef(ctx.get('settings'), source.id);
|
|
38
|
+
// Legacy Codex aliases intentionally own a separate record; their command must use that same address.
|
|
39
|
+
const credentialProvider = source.id === CODEX_SOURCE && profile !== undefined ? profile.provider : source.id;
|
|
40
|
+
return { id: source.id, provider: loginProvider(profile, source), served: profile !== undefined,
|
|
41
|
+
auth: ref === undefined ? { credentialProvider } : { apiKeyRef: ref },
|
|
42
|
+
};
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
/** A named reference can hold only one API key, never an OAuth grant. */
|
|
46
|
+
function choicesFor(targets) {
|
|
47
|
+
return targets.flatMap(target => {
|
|
48
|
+
const choices = [];
|
|
49
|
+
const oauth = target.provider.auth?.oauth;
|
|
50
|
+
if (target.auth !== undefined && 'credentialProvider' in target.auth && oauth?.login !== undefined) {
|
|
51
|
+
choices.push({ providerId: target.id, providerName: target.provider.name, authType: 'oauth', methodLabel: oauth.loginLabel ?? oauth.name });
|
|
52
|
+
}
|
|
53
|
+
const apiKey = target.provider.auth?.apiKey;
|
|
54
|
+
if (apiKey?.login !== undefined) {
|
|
55
|
+
choices.push({ providerId: target.id, providerName: target.provider.name, authType: 'api_key', methodLabel: apiKey.name });
|
|
56
|
+
}
|
|
57
|
+
return choices;
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
/** Checking writability before a prompt avoids obtaining grants the composition cannot retain. */
|
|
61
|
+
async function writableStore(ctx, target) {
|
|
62
|
+
const credentials = ctx.get('credentials');
|
|
63
|
+
if (credentials === undefined)
|
|
64
|
+
throw new LlmError(MISSING_STORE, 'NO_CREDENTIAL_STORE');
|
|
65
|
+
if (target.auth === undefined)
|
|
66
|
+
throw new LlmError('This route names no credential to store', 'UNSUPPORTED_CREDENTIAL');
|
|
67
|
+
if ('apiKeyRef' in target.auth) {
|
|
68
|
+
if (typeof credentials.set !== 'function' || typeof credentials.describe !== 'function') {
|
|
69
|
+
throw new LlmError(MISSING_STORE, 'NO_CREDENTIAL_STORE');
|
|
70
|
+
}
|
|
71
|
+
if (!(await credentials.describe(target.auth.apiKeyRef)).writable)
|
|
72
|
+
throw new LlmError(READ_ONLY, 'READ_ONLY_CREDENTIAL');
|
|
73
|
+
}
|
|
74
|
+
else {
|
|
75
|
+
if (typeof credentials.modifyRecord !== 'function' || typeof credentials.readRecord !== 'function') {
|
|
76
|
+
throw new LlmError(MISSING_STORE, 'NO_CREDENTIAL_STORE');
|
|
77
|
+
}
|
|
78
|
+
const info = await credentials.describeRecord?.(recordKeyFor(target.auth.credentialProvider));
|
|
79
|
+
if (info?.writable === false)
|
|
80
|
+
throw new LlmError(READ_ONLY, 'READ_ONLY_CREDENTIAL');
|
|
81
|
+
}
|
|
82
|
+
return credentials;
|
|
83
|
+
}
|
|
84
|
+
/** OAuth crosses the durability boundary before any later cancellation or ownership verdict. */
|
|
85
|
+
async function authenticate(target, method, credentials, interaction, guard) {
|
|
86
|
+
const auth = codexAuth(() => credentials);
|
|
87
|
+
const signal = interaction.signal ?? new AbortController().signal;
|
|
88
|
+
signal.throwIfAborted();
|
|
89
|
+
guard();
|
|
90
|
+
if (method === 'oauth' && target.auth !== undefined && 'credentialProvider' in target.auth) {
|
|
91
|
+
// The flow owns cancellation until it returns a grant; then persistence owns completion.
|
|
92
|
+
const grant = await target.provider.auth.oauth.login({ ...interaction, signal });
|
|
93
|
+
await auth.credentials.modify(target.auth.credentialProvider, async () => grant);
|
|
94
|
+
return;
|
|
95
|
+
}
|
|
96
|
+
const pending = createModels({ credentials: new PendingCredentialStore(), authContext: auth.authContext });
|
|
97
|
+
pending.setProvider(target.provider);
|
|
98
|
+
const credential = await pending.login(target.provider.id, 'api_key', interaction);
|
|
99
|
+
guard();
|
|
100
|
+
await proveApiKey(pending, target.provider.id, signal);
|
|
101
|
+
signal.throwIfAborted();
|
|
102
|
+
guard();
|
|
103
|
+
if (target.auth !== undefined && 'apiKeyRef' in target.auth) {
|
|
104
|
+
if (credential.type !== 'api_key' || credential.key === undefined) {
|
|
105
|
+
throw new LlmError('This login did not return a single API key for ' + target.auth.apiKeyRef, 'UNSUPPORTED_CREDENTIAL');
|
|
106
|
+
}
|
|
107
|
+
const ref = credentialRef(target.auth.apiKeyRef);
|
|
108
|
+
const key = assertUsableApiKey(credential.key, PLUGIN_NAME, ref);
|
|
109
|
+
// set() is atomic but not cancellable; once it starts, report the resulting durable state.
|
|
110
|
+
await credentials.set(ref, key);
|
|
111
|
+
try {
|
|
112
|
+
if ((await credentials.resolve(ref))?.value !== key) {
|
|
113
|
+
throw new Error(ref + ' does not resolve to the saved key.');
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
catch (error) {
|
|
117
|
+
throw new StoredCredentialError('The credential was stored, but readback failed: ' + (error instanceof Error ? error.message : String(error)));
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
else {
|
|
121
|
+
if (target.auth === undefined)
|
|
122
|
+
throw new LlmError('This route names no credential to store', 'UNSUPPORTED_CREDENTIAL');
|
|
123
|
+
await auth.credentials.modify(target.auth.credentialProvider, async () => {
|
|
124
|
+
// A queued record update can still stop before its locked mutation begins.
|
|
125
|
+
signal.throwIfAborted();
|
|
126
|
+
guard();
|
|
127
|
+
return credential;
|
|
128
|
+
});
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
/** Both modes share the attended conversation without sharing route-declaration authority. */
|
|
132
|
+
export function mountLoginCommand(ctx, config, routes) {
|
|
133
|
+
if (!config.loginCommandEnabled)
|
|
134
|
+
return;
|
|
135
|
+
ctx.inject(['commands'], commandCtx => {
|
|
136
|
+
const targets = () => loginTargets(ctx, config, routes);
|
|
137
|
+
const targetFor = (id) => {
|
|
138
|
+
const target = targets().find(target => target.id === id);
|
|
139
|
+
if (target === undefined)
|
|
140
|
+
throw new Error('The configured sign-in route is no longer available: ' + id);
|
|
141
|
+
return target;
|
|
142
|
+
};
|
|
143
|
+
const guard = routes.requireOwnership ?? (() => { });
|
|
144
|
+
const host = {
|
|
145
|
+
choices: () => choicesFor(targets()),
|
|
146
|
+
login: async (choice, interaction) => {
|
|
147
|
+
guard();
|
|
148
|
+
const target = targetFor(choice.providerId);
|
|
149
|
+
const credentials = await writableStore(ctx, target);
|
|
150
|
+
await authenticate(target, choice.authType, credentials, interaction, guard);
|
|
151
|
+
try {
|
|
152
|
+
guard();
|
|
153
|
+
}
|
|
154
|
+
catch (error) {
|
|
155
|
+
throw new StoredCredentialError('The credential was stored, but the route is unavailable: ' + (error instanceof Error ? error.message : String(error)));
|
|
156
|
+
}
|
|
157
|
+
if (routes.catalog !== undefined || target.served)
|
|
158
|
+
return 'present';
|
|
159
|
+
if (interaction.signal?.aborted)
|
|
160
|
+
return 'unavailable';
|
|
161
|
+
return declareProviderRoute(ctx.get('settings'), target.id);
|
|
162
|
+
},
|
|
163
|
+
stored: async (id) => {
|
|
164
|
+
const target = targetFor(id);
|
|
165
|
+
const credentials = ctx.get('credentials');
|
|
166
|
+
if (target.auth === undefined)
|
|
167
|
+
return undefined;
|
|
168
|
+
if ('apiKeyRef' in target.auth) {
|
|
169
|
+
return (await credentials?.resolve(target.auth.apiKeyRef)) === undefined ? undefined : 'api_key';
|
|
170
|
+
}
|
|
171
|
+
const record = await credentials?.readRecord(recordKeyFor(target.auth.credentialProvider));
|
|
172
|
+
return record === undefined ? undefined : record.kind === 'api-key' ? 'api_key' : 'oauth';
|
|
173
|
+
},
|
|
174
|
+
reference: async (id) => {
|
|
175
|
+
const target = targetFor(id);
|
|
176
|
+
if (target.auth === undefined || !('apiKeyRef' in target.auth))
|
|
177
|
+
return undefined;
|
|
178
|
+
const ref = target.auth.apiKeyRef;
|
|
179
|
+
const credentials = ctx.get('credentials');
|
|
180
|
+
if (credentials === undefined)
|
|
181
|
+
return { ref, ...(process.env[ref] ? { source: 'env' } : {}) };
|
|
182
|
+
const info = await credentials.describe(ref);
|
|
183
|
+
return { ref, ...(info.configured && info.source !== undefined ? { source: info.source } : {}) };
|
|
184
|
+
},
|
|
185
|
+
ask: async (request) => {
|
|
186
|
+
const userQuestions = ctx.get('userQuestions');
|
|
187
|
+
if (userQuestions === undefined)
|
|
188
|
+
throw new Error('dsh-provider-extra: this composition mounts no session UI that can ask the sign-in questions');
|
|
189
|
+
return userQuestions.ask({ questions: [...request.questions], agent: request.agent,
|
|
190
|
+
...(request.signal === undefined ? {} : { signal: request.signal }) });
|
|
191
|
+
},
|
|
192
|
+
};
|
|
193
|
+
commandCtx.commands.register(createLoginCommand(host, config.loginCommandName));
|
|
194
|
+
ctx.logger.info('dsh-provider-extra: /' + config.loginCommandName + ' signs in configured credentials');
|
|
195
|
+
});
|
|
196
|
+
}
|
package/dist/login-verify.js
CHANGED
|
@@ -7,6 +7,8 @@ const PROBE_TIMEOUT_MS = 20_000;
|
|
|
7
7
|
const PROBE_TIMEOUT = 'the provider did not answer in time';
|
|
8
8
|
/** Prefix that turns a provider's own words into the sentence a human reads. */
|
|
9
9
|
const REJECTED_PREFIX = 'the provider did not accept this API key: ';
|
|
10
|
+
/** No model means no evidence, not a provider rejection or a successful proof. */
|
|
11
|
+
const NO_MODELS_PREFIX = 'cannot verify this API key: no models are available for provider ';
|
|
10
12
|
/**
|
|
11
13
|
* A credential store that forgets.
|
|
12
14
|
*
|
|
@@ -38,13 +40,16 @@ export class PendingCredentialStore {
|
|
|
38
40
|
* Throws the provider's own explanation when it refuses, so the human can tell
|
|
39
41
|
* a mistyped key from a key that lacks a plan or a region.
|
|
40
42
|
*/
|
|
41
|
-
export async function proveApiKey(models, providerId) {
|
|
43
|
+
export async function proveApiKey(models, providerId, signal) {
|
|
44
|
+
signal?.throwIfAborted();
|
|
42
45
|
const model = models.getModels(providerId)[0];
|
|
43
|
-
// A provider with no catalog model cannot be asked anything, and refusing a
|
|
44
|
-
// key nothing has disproved would block a sign-in that may be perfectly good.
|
|
45
46
|
if (model === undefined)
|
|
46
|
-
|
|
47
|
-
const
|
|
47
|
+
throw new Error(NO_MODELS_PREFIX + providerId);
|
|
48
|
+
const deadline = AbortSignal.timeout(PROBE_TIMEOUT_MS);
|
|
49
|
+
const probeSignal = signal === undefined ? deadline : AbortSignal.any([signal, deadline]);
|
|
50
|
+
const answer = await models.completeSimple(model, { messages: [{ role: 'user', content: PROBE_PROMPT, timestamp: Date.now() }] }, { maxTokens: PROBE_MAX_TOKENS, signal: probeSignal });
|
|
51
|
+
// A transport may finish despite cancellation; that answer must not authorize a key write.
|
|
52
|
+
probeSignal.throwIfAborted();
|
|
48
53
|
if (answer.stopReason !== 'error' && answer.stopReason !== 'aborted')
|
|
49
54
|
return;
|
|
50
55
|
throw new Error(REJECTED_PREFIX + (answer.errorMessage ?? PROBE_TIMEOUT));
|
package/dist/opencode-go.js
CHANGED
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
import { defaultProviderAuthContext } from '@earendil-works/pi-ai';
|
|
16
16
|
import { builtinProviders } from '@earendil-works/pi-ai/providers/all';
|
|
17
17
|
import { resolveRetryPolicy } from '@deepseek-ai/dsh-llm';
|
|
18
|
+
import { resolveExtraModels, selectWhitelistedModels } from "./extra-models.js";
|
|
18
19
|
/** pi-ai catalog id of the OpenCode Go provider this route mirrors. */
|
|
19
20
|
export const OPENCODE_GO_PROVIDER_ID = 'opencode-go';
|
|
20
21
|
/** Routing header the OpenCode Go gateway requires on every model request. */
|
|
@@ -31,42 +32,6 @@ export const DEFAULT_EXTRA_MODEL_TEMPLATE = 'deepseek-v4-flash';
|
|
|
31
32
|
const DEFAULT_EXTRA_MODELS = [
|
|
32
33
|
{ id: DEEPSEEK_V41_FLASH_ID, name: DEEPSEEK_V41_FLASH_NAME, template: DEFAULT_EXTRA_MODEL_TEMPLATE },
|
|
33
34
|
];
|
|
34
|
-
/**
|
|
35
|
-
* Resolve declared extras against the installed catalog. Later specs win over
|
|
36
|
-
* earlier ones by id, so a settings entry reshapes the shipped default under
|
|
37
|
-
* the same id; an id the catalog itself ships stays with the catalog.
|
|
38
|
-
* Failures land in `modelErrors` beside serviceable models instead of
|
|
39
|
-
* refusing the route, because one mistyped template must not silence the
|
|
40
|
-
* other twenty-seven.
|
|
41
|
-
* @param catalog - installed catalog models to clone wire behavior from.
|
|
42
|
-
* @param specs - declared extras, shipped defaults first.
|
|
43
|
-
* @returns the resolved extras and per-model failure diagnostics.
|
|
44
|
-
*/
|
|
45
|
-
export function resolveExtraModels(catalog, specs) {
|
|
46
|
-
const models = [];
|
|
47
|
-
const modelErrors = new Map();
|
|
48
|
-
const shipped = new Set(catalog.map(model => model.id));
|
|
49
|
-
const byId = new Map();
|
|
50
|
-
for (const spec of specs)
|
|
51
|
-
byId.set(spec.id, spec);
|
|
52
|
-
for (const spec of byId.values()) {
|
|
53
|
-
if (spec.id.length === 0) {
|
|
54
|
-
modelErrors.set(spec.id, 'dsh-provider-extra: an extra model has an empty id');
|
|
55
|
-
continue;
|
|
56
|
-
}
|
|
57
|
-
if (shipped.has(spec.id))
|
|
58
|
-
continue;
|
|
59
|
-
const templateId = spec.template ?? DEFAULT_EXTRA_MODEL_TEMPLATE;
|
|
60
|
-
const template = catalog.find(model => model.id === templateId);
|
|
61
|
-
if (template === undefined) {
|
|
62
|
-
modelErrors.set(spec.id, `dsh-provider-extra: extra model "${spec.id}" names template "${templateId}",`
|
|
63
|
-
+ ' which the installed catalog does not describe');
|
|
64
|
-
continue;
|
|
65
|
-
}
|
|
66
|
-
models.push({ ...template, id: spec.id, name: spec.name ?? template.name });
|
|
67
|
-
}
|
|
68
|
-
return { models, modelErrors };
|
|
69
|
-
}
|
|
70
35
|
// The resolved profile defaults below mirror dsh-llm-pi-ai's config resolution,
|
|
71
36
|
// which does not export them; drift is caught by that package's own tests.
|
|
72
37
|
/** Default maximum idle interval while an adapter stream read is outstanding. */
|
|
@@ -119,11 +84,11 @@ function withRoutingHeader(options, config) {
|
|
|
119
84
|
* every dispatch path funnels through them with the request's own options.
|
|
120
85
|
* @param config - the route configuration.
|
|
121
86
|
* @param catalog - the installed catalog provider to reuse.
|
|
122
|
-
* @param
|
|
87
|
+
* @param resolved - catalog and extra models already resolved and selected.
|
|
123
88
|
* @returns the provider to register into the adapter's model collection.
|
|
124
89
|
*/
|
|
125
|
-
function routeProvider(config, catalog,
|
|
126
|
-
const models =
|
|
90
|
+
function routeProvider(config, catalog, resolved) {
|
|
91
|
+
const models = resolved.map(model => ({
|
|
127
92
|
...model,
|
|
128
93
|
...config.baseURL === undefined ? {} : { baseUrl: config.baseURL },
|
|
129
94
|
provider: config.provider,
|
|
@@ -146,7 +111,11 @@ function routeProvider(config, catalog, extras) {
|
|
|
146
111
|
*/
|
|
147
112
|
export function buildOpenCodeGoProfile(config) {
|
|
148
113
|
const catalog = catalogOpenCodeGo();
|
|
149
|
-
const extras = resolveExtraModels(catalog.getModels(), [...DEFAULT_EXTRA_MODELS, ...(config.extraModels ?? [])]);
|
|
114
|
+
const extras = resolveExtraModels(catalog.getModels(), [...DEFAULT_EXTRA_MODELS, ...(config.extraModels ?? [])], DEFAULT_EXTRA_MODEL_TEMPLATE);
|
|
115
|
+
// Selection runs last so a whitelist may name a shipped or declared extra
|
|
116
|
+
// exactly as it names a catalog model, and so a typo in either is refused
|
|
117
|
+
// here rather than served as a route quietly missing a model.
|
|
118
|
+
const models = selectWhitelistedModels(config.provider, [...catalog.getModels(), ...extras.models], config.models);
|
|
150
119
|
return {
|
|
151
120
|
provider: config.provider,
|
|
152
121
|
displayName: config.displayName,
|
|
@@ -158,7 +127,7 @@ export function buildOpenCodeGoProfile(config) {
|
|
|
158
127
|
retryPolicy: resolveRetryPolicy(undefined, 'dsh-provider-extra: opencode-go'),
|
|
159
128
|
modelErrors: extras.modelErrors,
|
|
160
129
|
configuredMaxTokens: new Map(),
|
|
161
|
-
piProvider: routeProvider(config, catalog,
|
|
130
|
+
piProvider: routeProvider(config, catalog, models),
|
|
162
131
|
};
|
|
163
132
|
}
|
|
164
133
|
/**
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
{
|
|
2
|
+
"catalog": {
|
|
3
|
+
"version": 1,
|
|
4
|
+
"providers": [
|
|
5
|
+
{
|
|
6
|
+
"id": "example-route",
|
|
7
|
+
"name": "Example provider",
|
|
8
|
+
"source": "openai",
|
|
9
|
+
"auth": {
|
|
10
|
+
"apiKeyRef": "EXAMPLE_API_KEY"
|
|
11
|
+
},
|
|
12
|
+
"models": [
|
|
13
|
+
{
|
|
14
|
+
"id": "example-model",
|
|
15
|
+
"name": "Example model",
|
|
16
|
+
"metadata": {
|
|
17
|
+
"api": "openai-responses",
|
|
18
|
+
"reasoning": false,
|
|
19
|
+
"input": [
|
|
20
|
+
"text"
|
|
21
|
+
],
|
|
22
|
+
"cost": {
|
|
23
|
+
"input": 0,
|
|
24
|
+
"output": 0,
|
|
25
|
+
"cacheRead": 0,
|
|
26
|
+
"cacheWrite": 0
|
|
27
|
+
},
|
|
28
|
+
"contextWindow": 8192,
|
|
29
|
+
"maxTokens": 1024
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
]
|
|
33
|
+
}
|
|
34
|
+
],
|
|
35
|
+
"default": {
|
|
36
|
+
"provider": "example-route",
|
|
37
|
+
"model": "example-model"
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
}
|
package/docs/catalog.md
ADDED
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
# Managed catalog configuration
|
|
2
|
+
|
|
3
|
+
Provider-extra remains optional. TUI needs only the host's LLM and default-model contracts.
|
|
4
|
+
Without `catalog`, provider-extra keeps its existing additive routes, settings overlays, and login command.
|
|
5
|
+
With `catalog`, the profile Config becomes the only owner of model membership and the default.
|
|
6
|
+
|
|
7
|
+
## Activate one profile
|
|
8
|
+
|
|
9
|
+
1. Back up the profile patch and legacy settings before migration.
|
|
10
|
+
2. Copy your validated `catalog` object into the existing `dsh-provider-extra` row's `config`.
|
|
11
|
+
3. Disable competing provider rows and `agent-default-model` in that profile only.
|
|
12
|
+
4. Restart the profile after a successful build.
|
|
13
|
+
|
|
14
|
+
Do not modify global bundles or ordinary profiles. Do not remove the core `llm` service.
|
|
15
|
+
Disable native adapters and the generic `llm-pi-ai` row, including dormant generic provider directories.
|
|
16
|
+
For example, a profile with these row IDs needs these overrides:
|
|
17
|
+
|
|
18
|
+
```yaml
|
|
19
|
+
- id: llm-deepseek
|
|
20
|
+
disabled: true
|
|
21
|
+
- id: llm-openai
|
|
22
|
+
disabled: true
|
|
23
|
+
- id: llm-anthropic
|
|
24
|
+
disabled: true
|
|
25
|
+
- id: llm-pi-ai
|
|
26
|
+
disabled: true
|
|
27
|
+
- id: agent-default-model
|
|
28
|
+
disabled: true
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Inspect the composed profile for additional provider rows or different IDs.
|
|
32
|
+
Mount provider-extra after those rows so its preflight can detect existing owners.
|
|
33
|
+
Preflight rejects any existing adapter, provider directory, or default owner before registering managed routes.
|
|
34
|
+
It never disables another plugin. The public registry cannot veto a later unrelated adapter or directory registration.
|
|
35
|
+
The public `llm/adapters-updated` notification detects that conflict immediately and logs `CATALOG_OWNER_COLLISION`.
|
|
36
|
+
Managed model listing, selection resolution, request preparation, default reads and saves, and new dispatch fail closed while the conflict exists, and the adapter's own credential hooks check ownership as well. The sign-in command's status and route choices read metadata only, and signing in refuses to start while the conflict exists.
|
|
37
|
+
A captured request checks ownership before and after API-key or OAuth grant lookup.
|
|
38
|
+
OAuth modification checks again before entering the store and its locked updater, then after completion.
|
|
39
|
+
A successful refresh already started under valid ownership persists its rotated grant, even if a conflict appears before completion.
|
|
40
|
+
The completion guard then rejects model dispatch; it never rolls back authentication or discards the rotated token.
|
|
41
|
+
Public pi-ai can normalize OAuth store failures to `PI_AI_ERROR`; their message retains the unmistakable `CATALOG_OWNER_COLLISION` detail.
|
|
42
|
+
Requests already past all credential gates continue with their captured generation; topology changes do not cancel in-flight work.
|
|
43
|
+
The plugin keeps its valid snapshot and registrations intact, then recovers when competing rows disappear.
|
|
44
|
+
It logs once per transition into conflict, not once per failed operation.
|
|
45
|
+
Unrelated global rows remain observable through the public registry; the plugin never filters or rewrites that directory.
|
|
46
|
+
Therefore activation must remove competing rows from the entire profile, not only the earlier rows.
|
|
47
|
+
|
|
48
|
+
Managed mode does not install the legacy settings section or declare generic routes during sign-in.
|
|
49
|
+
Where supported, it disables automatic settings projection for its own Config.
|
|
50
|
+
The existing sign-in command uses the selected catalog routes and their configured credential references.
|
|
51
|
+
Credentials remain separate from configuration. The attended CLI supports Codex only.
|
|
52
|
+
|
|
53
|
+
## Version 1 shape
|
|
54
|
+
|
|
55
|
+
[Shape example](catalog-v1.example.json) validates with synthetic `example-` identifiers and illustrative metadata.
|
|
56
|
+
Its model does not identify a real endpoint model. Replace the model, metadata, and credential reference before dispatch.
|
|
57
|
+
The supported `openai` source illustrates the schema; it is not a recommended provider selection.
|
|
58
|
+
The plugin reads the profile Config, not this example or another catalog file.
|
|
59
|
+
|
|
60
|
+
- `catalog.version`: required integer `1`.
|
|
61
|
+
- `catalog.providers`: required ordered array of selected routes.
|
|
62
|
+
- `catalog.default`: one `{ provider, model, reasoningEffort? }` selection, or `null` when no models are selected.
|
|
63
|
+
- Provider `id`: unique route ID used by the host.
|
|
64
|
+
- Provider `name`: explicit display name.
|
|
65
|
+
- Provider `source`: any backend the installed pi-ai catalog provides (`openai`, `openai-codex`, `anthropic`, `zai`, a gateway, …); an id nothing installs rejects the candidate.
|
|
66
|
+
Omit it to declare your own endpoint instead.
|
|
67
|
+
- Provider `api`: wire protocol of a route that names no `source`; required there and rejected beside `source`.
|
|
68
|
+
This build implements `anthropic-messages`, `azure-openai-responses`, `google-generative-ai`, `mistral-conversations`, `openai-completions`, and `openai-responses`.
|
|
69
|
+
A declared protocol also supplies every model's `metadata.api`.
|
|
70
|
+
- Provider `auth`: optional. Exactly one of `{ apiKeyRef }` or `{ credentialProvider }` when present.
|
|
71
|
+
Absent means the route carries no key of its own, as a local endpoint does.
|
|
72
|
+
`credentialProvider` needs an installed `source` to own the grant.
|
|
73
|
+
- `apiKeyRef`: host credential reference, not a secret value. Without a credential service, the route reads that environment variable.
|
|
74
|
+
- `credentialProvider`: the source provider ID. Route aliases share that source's existing `llm-pi-ai` credential record.
|
|
75
|
+
- Provider `models`: ordered selection entries; each requires a wire `id` and explicit `name`. Declare exactly one of `models` and `filter`.
|
|
76
|
+
- Provider `filter`: `{ include?, exclude? }` patterns over the installed `source` catalog. `*` is the only wildcard; every other character matches itself.
|
|
77
|
+
An absent `include` starts from every installed model, and each match keeps its installed ID, name, cost, capacity, protocol, and endpoint.
|
|
78
|
+
Matches keep installed order; the route serves them minus `exclude`.
|
|
79
|
+
Curating with `filter` needs an installed `source`; `models: []` remains the explicit empty selection.
|
|
80
|
+
- Model `aliases`: optional unique selector inputs. Aliases never create additional listing rows.
|
|
81
|
+
- Model `template`: optional explicit installed model ID from the same source.
|
|
82
|
+
- Model `metadata`: optional public pi-ai model facts. Overrides apply even when pi-ai already ships the requested ID.
|
|
83
|
+
- Model `defaultMaxTokens`: optional explicit request default, used only when the request supplies no output cap.
|
|
84
|
+
It must be a positive safe integer no greater than the resolved model capacity.
|
|
85
|
+
- Provider `baseURL`: required when no installed `source` is named, an optional override otherwise; no embedded credentials or fragments.
|
|
86
|
+
- Provider `headers`: optional static HTTP headers. Keep secrets in credential references.
|
|
87
|
+
- Provider `transport`: optional Codex transport: `sse`, `websocket`, `websocket-cached`, or `auto`.
|
|
88
|
+
- Provider `fallbackSessionId`: optional OpenCode Go identity for requests without a session ID.
|
|
89
|
+
|
|
90
|
+
Unknown fields, duplicate IDs or aliases, unknown sources or protocols, missing endpoints, malformed metadata and patterns, and unsupported default effort reject the whole candidate.
|
|
91
|
+
Omitting `catalog` differs from `providers: []`. Empty provider or model arrays select nothing; they never expand a source catalog.
|
|
92
|
+
An empty provider list requires `default: null`. A nonempty model selection requires one valid default.
|
|
93
|
+
A selected route with `models: []` remains empty even when pi-ai ships models for its source.
|
|
94
|
+
|
|
95
|
+
### Model metadata
|
|
96
|
+
|
|
97
|
+
Known models inherit facts from their installed source unless explicitly overridden.
|
|
98
|
+
An explicit template retains the requested wire ID and name; it does not rename a sibling silently.
|
|
99
|
+
Templates express operator intent, not endpoint support or verified capability equivalence.
|
|
100
|
+
|
|
101
|
+
An unknown model without a template requires all these metadata fields:
|
|
102
|
+
|
|
103
|
+
- `api`: a protocol the installed source implements, or the route's declared `api`.
|
|
104
|
+
- `reasoning`: boolean.
|
|
105
|
+
- `input`: nonempty list of `text` and/or `image`.
|
|
106
|
+
- `cost`: finite nonnegative `input`, `output`, `cacheRead`, and `cacheWrite` rates.
|
|
107
|
+
- `contextWindow` and `maxTokens`: positive safe integers.
|
|
108
|
+
|
|
109
|
+
Optional `thinkingLevelMap` maps supported levels to wire values; `null` disables a level.
|
|
110
|
+
Levels are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
|
|
111
|
+
Protocol-compatible `compat` overrides and model `headers` are validated before mounting.
|
|
112
|
+
The public exported TypeScript contracts define the accepted metadata subset.
|
|
113
|
+
`metadata.maxTokens` describes model capacity; it does not impose a request output cap.
|
|
114
|
+
Migrate an explicit legacy generic `models[].maxTokens` request default into `defaultMaxTokens` as well.
|
|
115
|
+
Never infer `defaultMaxTokens` from an inherited capability. An explicit per-request cap still takes precedence.
|
|
116
|
+
|
|
117
|
+
## Shared snapshot and persistence
|
|
118
|
+
|
|
119
|
+
Public `compileCatalog(config)` returns a detached, immutable snapshot, or `undefined` for absence.
|
|
120
|
+
Public `buildCatalogProfile(provider)` constructs a validated route through installed pi-ai delegates.
|
|
121
|
+
No private generic resolver is used.
|
|
122
|
+
The snapshot supplies listings, exact model resolution, prepared dispatch, and `agentDefaultModel.currentSelection()`.
|
|
123
|
+
On the pinned host matrix, the catalog default contributes only provider and model to new sessions.
|
|
124
|
+
That host ignores `catalog.default.reasoningEffort`; choose reasoning effort in the session surface.
|
|
125
|
+
`resolveSelection()` canonicalizes aliases for defaults and saves; host calls use listed wire IDs.
|
|
126
|
+
An empty catalog's `currentSelection()` rejects with `NO_DEFAULT_MODEL`.
|
|
127
|
+
|
|
128
|
+
Go delegates preserve `x-opencode-session` from the live session, with the configured fallback for sessionless calls.
|
|
129
|
+
Codex keeps OAuth grant refresh and the explicitly pinned transport. It never uses an API-key override.
|
|
130
|
+
|
|
131
|
+
`saveSelection(next)` validates the selection before any write.
|
|
132
|
+
Where `configEditor.edit(owner.fiber.entry, updater)` exists, it changes only `catalog.default` in the same Config.
|
|
133
|
+
The updater preserves other fields and revalidates membership against the editor's current locked configuration.
|
|
134
|
+
The promise awaits the editor's validation, persistence, and reconciliation.
|
|
135
|
+
Failures propagate without publishing a local-only default.
|
|
136
|
+
Hosts without an addressable entry and that editor reject with `CONFIG_PERSISTENCE_UNAVAILABLE`.
|
|
137
|
+
The released `0.1.5-rc.2` host has no verified canonical editor; edit its profile patch explicitly.
|
|
138
|
+
No fallback writes legacy `agent-default-model` settings or another file.
|
|
139
|
+
|
|
140
|
+
The catalog is nonvolatile. Successful edits follow the host's normal plugin restart lifecycle.
|
|
141
|
+
Schema validation runs before Loader disposal, preserving valid state on an invalid reload.
|
|
142
|
+
A pre-disposal update check also retains that state if a competing adapter appeared after activation.
|
|
143
|
+
Prepared calls retain their captured adapter revision across successful reloads.
|
|
144
|
+
External lifecycle failures and startup ordering still depend on the host; parent runtime tests cover profile reconciliation.
|
|
145
|
+
|
|
146
|
+
## Migration inputs
|
|
147
|
+
|
|
148
|
+
Migration is explicit. Installation never activates a catalog or edits a live home.
|
|
149
|
+
Use the composed profile, declared templates, credential references, and current default as migration inputs.
|
|
150
|
+
Read legacy settings only to identify previously effective values. Resolve conflicting owners before activation.
|
|
151
|
+
Preserve unrelated rows, comments, credentials, and preferences.
|
|
152
|
+
Keep backups until restart, rollback, membership, and default persistence checks pass.
|
|
153
|
+
|
|
154
|
+
A model template expresses operator intent, not verified endpoint compatibility.
|
|
155
|
+
Zero cost metadata means unknown pricing, not free inference.
|
|
156
|
+
Test selected models separately with authorized credentials before adopting another profile.
|
|
157
|
+
Keep personal model selections outside the package and repository fixtures.
|
|
158
|
+
|
|
159
|
+
## Clone-only development setup
|
|
160
|
+
|
|
161
|
+
This source-checkout command prepares a new private clone without launching a profile.
|
|
162
|
+
It never authenticates, contacts a model, or writes the source home.
|
|
163
|
+
The clone can contain copied credentials. Keep it private and never commit it.
|
|
164
|
+
|
|
165
|
+
1. Install this checkout's dependencies and supply an existing profile to clone.
|
|
166
|
+
2. Prepare a private JSON file containing only your complete `{"catalog": {...}}` Config.
|
|
167
|
+
3. Supply the existing generic dogfood helper as an explicit development-tool path.
|
|
168
|
+
4. Choose a nonexistent clone path whose parent already exists.
|
|
169
|
+
5. Run:
|
|
170
|
+
|
|
171
|
+
```sh
|
|
172
|
+
pnpm catalog:setup \
|
|
173
|
+
--helper /path/to/run-plugin-from-worktree.sh \
|
|
174
|
+
--source-home /path/to/source-home \
|
|
175
|
+
--home /path/to/new-private-clone \
|
|
176
|
+
--profile web \
|
|
177
|
+
--catalog /private/path/catalog-config.json \
|
|
178
|
+
[--allow-row ROW_ID]...
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
`--catalog` is required. There is no packaged selection or implicit model set.
|
|
182
|
+
Setup refuses a row whose name reads like a model provider unless `--allow-row ROW_ID` asserts that
|
|
183
|
+
row registers no provider and no default owner. A real home carries such rows, and setup cannot see
|
|
184
|
+
row provenance, so the flag keeps the check fail-closed instead of guessing; failure output names the
|
|
185
|
+
row and prints the flag to use. Boot-time `CATALOG_OWNER_COLLISION` stays authoritative either way.
|
|
186
|
+
The shape example validates, but its synthetic model cannot serve requests; replace it with your own selection.
|
|
187
|
+
The helper is optional development tooling, not a provider runtime dependency.
|
|
188
|
+
A checkout of the independent TUI currently carries it under:
|
|
189
|
+
|
|
190
|
+
```text
|
|
191
|
+
.agents/skills/dsh-tui-dogfood/scripts/run-plugin-from-worktree.sh
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Use the generic helper, not the TUI-specific wrapper.
|
|
195
|
+
The command builds this provider checkout and relinks only this package in the fresh clone.
|
|
196
|
+
It uses the locally installed development harness by default.
|
|
197
|
+
To select another installed harness, add `--dsh /absolute/path/to/dsh/lib/bin.js`.
|
|
198
|
+
Pass the actual JavaScript bin, not a shell launcher. Setup prints the matching launch command.
|
|
199
|
+
|
|
200
|
+
Setup appends JSON flow-map sequence rows to the clone's profile patch.
|
|
201
|
+
It retains all original patch bytes and uses the selected host's public parser and composition API.
|
|
202
|
+
It disables recognized native adapters, the generic pi-ai adapter, and the default owner by their actual composed IDs.
|
|
203
|
+
It preserves the core LLM service and unrelated configuration.
|
|
204
|
+
The command checks the resolved provider module and isolated catalog listing/default APIs before replacing the clone patch.
|
|
205
|
+
|
|
206
|
+
Success means `composition-verified`, not verified runtime ownership or authentication.
|
|
207
|
+
Setup does not boot arbitrary profile plugins or infer their service ownership.
|
|
208
|
+
Boot-time `CATALOG_OWNER_COLLISION` remains authoritative, including for late-mounted plugins.
|
|
209
|
+
Launch only the printed clone command, then use sign-in status to inspect authentication.
|
|
210
|
+
The released host can still reject persistent default saves with `CONFIG_PERSISTENCE_UNAVAILABLE`.
|
|
211
|
+
No setup path writes legacy defaults as a fallback.
|
|
212
|
+
|
|
213
|
+
Setup refuses existing or overlapping homes, unsafe clone files, and unresolved or mismatched provider builds.
|
|
214
|
+
It also refuses unknown provider-like rows, opaque nested/include rows, and missing or duplicate core/catalog owners.
|
|
215
|
+
Profile patches must accept appended block-sequence rows; flow arrays and closed YAML documents require manual clone-only setup.
|
|
216
|
+
Home-level overrides must not counteract the catalog or disabled owner rows.
|
|
217
|
+
A refusal leaves the source home unchanged and never reports success.
|
|
218
|
+
A failed setup can leave a private clone for inspection; choose another new path for the next attempt.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sagmans/dsh-provider-extra",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Extra LLM provider routes for DeepSeek Harness: OpenCode Go with per-session x-opencode-session routing, and OpenAI Codex over ChatGPT-subscription OAuth.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"deepseek-harness",
|
|
@@ -26,6 +26,7 @@
|
|
|
26
26
|
},
|
|
27
27
|
"files": [
|
|
28
28
|
"dist",
|
|
29
|
+
"docs",
|
|
29
30
|
"cordis.patch.yml",
|
|
30
31
|
"README.md"
|
|
31
32
|
],
|
|
@@ -55,6 +56,7 @@
|
|
|
55
56
|
}
|
|
56
57
|
},
|
|
57
58
|
"scripts": {
|
|
59
|
+
"catalog:setup": "node tools/catalog-setup.mjs",
|
|
58
60
|
"codex:login": "node --import tsx/esm src/login-cli.ts",
|
|
59
61
|
"test": "node --import tsx/esm --test \"tests/*.spec.ts\"",
|
|
60
62
|
"typecheck": "tsc --noEmit",
|