@bevel-software/platform-mcp-core 0.23.0 → 0.25.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.
Files changed (56) hide show
  1. package/dist/chain-example.d.ts +58 -0
  2. package/dist/chain-example.d.ts.map +1 -0
  3. package/dist/chain-example.js +259 -0
  4. package/dist/chain-example.js.map +1 -0
  5. package/dist/chain-runtime.d.ts +122 -0
  6. package/dist/chain-runtime.d.ts.map +1 -0
  7. package/dist/chain-runtime.js +352 -0
  8. package/dist/chain-runtime.js.map +1 -0
  9. package/dist/google-service-account/google-auth-http.protocol.d.ts +24 -0
  10. package/dist/google-service-account/google-auth-http.protocol.d.ts.map +1 -0
  11. package/dist/google-service-account/google-auth-http.protocol.js +47 -0
  12. package/dist/google-service-account/google-auth-http.protocol.js.map +1 -0
  13. package/dist/google-service-account/google-service-account.auth.d.ts +45 -0
  14. package/dist/google-service-account/google-service-account.auth.d.ts.map +1 -0
  15. package/dist/google-service-account/google-service-account.auth.js +153 -0
  16. package/dist/google-service-account/google-service-account.auth.js.map +1 -0
  17. package/dist/google-service-account/google-service-account.token-source.d.ts +28 -0
  18. package/dist/google-service-account/google-service-account.token-source.d.ts.map +1 -0
  19. package/dist/google-service-account/google-service-account.token-source.js +206 -0
  20. package/dist/google-service-account/google-service-account.token-source.js.map +1 -0
  21. package/dist/google-service-account/index.d.ts +5 -0
  22. package/dist/google-service-account/index.d.ts.map +1 -0
  23. package/dist/google-service-account/index.js +7 -0
  24. package/dist/google-service-account/index.js.map +1 -0
  25. package/dist/google-service-account/service-account-token.contract.d.ts +33 -0
  26. package/dist/google-service-account/service-account-token.contract.d.ts.map +1 -0
  27. package/dist/google-service-account/service-account-token.contract.js +14 -0
  28. package/dist/google-service-account/service-account-token.contract.js.map +1 -0
  29. package/dist/index.d.ts +6 -3
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/index.js +10 -3
  32. package/dist/index.js.map +1 -1
  33. package/dist/meta-tools.d.ts +100 -1
  34. package/dist/meta-tools.d.ts.map +1 -1
  35. package/dist/meta-tools.js +181 -53
  36. package/dist/meta-tools.js.map +1 -1
  37. package/dist/results.d.ts +20 -0
  38. package/dist/results.d.ts.map +1 -1
  39. package/dist/results.js +111 -1
  40. package/dist/results.js.map +1 -1
  41. package/dist/retired-tools.d.ts +0 -12
  42. package/dist/retired-tools.d.ts.map +1 -1
  43. package/dist/retired-tools.js +0 -22
  44. package/dist/retired-tools.js.map +1 -1
  45. package/package.json +3 -2
  46. package/src/chain-example.ts +315 -0
  47. package/src/chain-runtime.ts +382 -0
  48. package/src/google-service-account/google-auth-http.protocol.ts +62 -0
  49. package/src/google-service-account/google-service-account.auth.ts +161 -0
  50. package/src/google-service-account/google-service-account.token-source.ts +239 -0
  51. package/src/google-service-account/index.ts +15 -0
  52. package/src/google-service-account/service-account-token.contract.ts +38 -0
  53. package/src/index.ts +47 -2
  54. package/src/meta-tools.ts +212 -58
  55. package/src/results.ts +106 -1
  56. package/src/retired-tools.ts +0 -22
@@ -0,0 +1 @@
1
+ {"version":3,"file":"google-service-account.auth.js","sourceRoot":"","sources":["../../src/google-service-account/google-service-account.auth.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,28 @@
1
+ import { type GoogleServiceAccountAuth, type IServiceAccountTokenSource } from './service-account-token.contract.js';
2
+ /**
3
+ * Google's token endpoint. Fixed rather than read from the key's own
4
+ * `token_uri`, so a key cannot point the server at another host with a signed
5
+ * assertion in hand.
6
+ */
7
+ export declare const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
8
+ /**
9
+ * Mints and caches access tokens for Google service accounts: signs an RS256
10
+ * assertion with the key's private key, exchanges it at Google's token
11
+ * endpoint, and keeps the token until shortly before it expires. Concurrent
12
+ * calls for the same token share one exchange, and a failed exchange is
13
+ * answered from memory for a few seconds (or for Google's `Retry-After`), so
14
+ * an outage or a rate limit is not met with a fresh exchange on every call.
15
+ * Injected with `fetch` and a clock so suites answer for Google.
16
+ */
17
+ export declare class GoogleServiceAccountTokenSource implements IServiceAccountTokenSource {
18
+ private readonly fetchImpl;
19
+ private readonly now;
20
+ private readonly timeoutMs;
21
+ private readonly tokens;
22
+ private readonly failures;
23
+ private readonly inFlight;
24
+ constructor(fetchImpl?: typeof fetch, now?: () => number, timeoutMs?: number);
25
+ accessToken(auth: GoogleServiceAccountAuth): Promise<string>;
26
+ private exchange;
27
+ }
28
+ //# sourceMappingURL=google-service-account.token-source.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"google-service-account.token-source.d.ts","sourceRoot":"","sources":["../../src/google-service-account/google-service-account.token-source.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAChC,MAAM,qCAAqC,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,wCAAwC,CAAC;AA8BtE;;;;;;;;GAQG;AACH,qBAAa,+BAAgC,YAAW,0BAA0B;IAM9E,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAP5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;gBAG5C,SAAS,GAAE,OAAO,KAAa,EAC/B,GAAG,GAAE,MAAM,MAAiB,EAC5B,SAAS,GAAE,MAA2B;IAGnD,WAAW,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC;YA4BpD,QAAQ;CA+CvB"}
@@ -0,0 +1,206 @@
1
+ import { createHash, createSign } from 'node:crypto';
2
+ import { ServiceAccountAuthError, } from './service-account-token.contract.js';
3
+ /**
4
+ * Google's token endpoint. Fixed rather than read from the key's own
5
+ * `token_uri`, so a key cannot point the server at another host with a signed
6
+ * assertion in hand.
7
+ */
8
+ export const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
9
+ const JWT_BEARER_GRANT = 'urn:ietf:params:oauth:grant-type:jwt-bearer';
10
+ /** The longest assertion lifetime Google accepts. */
11
+ const ASSERTION_LIFETIME_S = 3600;
12
+ /** A token this close to expiry is replaced, so a call never leaves with one that dies on the way. */
13
+ const REFRESH_SKEW_MS = 60_000;
14
+ const REQUEST_TIMEOUT_MS = 10_000;
15
+ /** Tokens (and failures) kept at once. Each distinct key, scope set and subject is one entry. */
16
+ const MAX_CACHED_TOKENS = 256;
17
+ /** How long a failed exchange is answered from memory when Google names no `Retry-After`. */
18
+ const FAILURE_BACKOFF_MS = 5_000;
19
+ /** The longest a `Retry-After` from Google holds calls back, so a far-off value cannot park a tool for good. */
20
+ const MAX_FAILURE_BACKOFF_MS = 60_000;
21
+ /**
22
+ * Mints and caches access tokens for Google service accounts: signs an RS256
23
+ * assertion with the key's private key, exchanges it at Google's token
24
+ * endpoint, and keeps the token until shortly before it expires. Concurrent
25
+ * calls for the same token share one exchange, and a failed exchange is
26
+ * answered from memory for a few seconds (or for Google's `Retry-After`), so
27
+ * an outage or a rate limit is not met with a fresh exchange on every call.
28
+ * Injected with `fetch` and a clock so suites answer for Google.
29
+ */
30
+ export class GoogleServiceAccountTokenSource {
31
+ fetchImpl;
32
+ now;
33
+ timeoutMs;
34
+ tokens = new Map();
35
+ failures = new Map();
36
+ inFlight = new Map();
37
+ constructor(fetchImpl = fetch, now = Date.now, timeoutMs = REQUEST_TIMEOUT_MS) {
38
+ this.fetchImpl = fetchImpl;
39
+ this.now = now;
40
+ this.timeoutMs = timeoutMs;
41
+ }
42
+ async accessToken(auth) {
43
+ const key = parseServiceAccountKey(auth.credentials);
44
+ const scope = scopeString(auth.scopes);
45
+ const cacheKey = tokenCacheKey(key, scope, auth.subject);
46
+ const cached = this.tokens.get(cacheKey);
47
+ if (cached && cached.expiresAt - REFRESH_SKEW_MS > this.now())
48
+ return cached.accessToken;
49
+ const failed = this.failures.get(cacheKey);
50
+ if (failed && failed.retryAt > this.now())
51
+ throw failed.error;
52
+ const pending = this.inFlight.get(cacheKey);
53
+ if (pending)
54
+ return pending;
55
+ const exchange = this.exchange(key, scope, auth.subject, cacheKey)
56
+ .catch((err) => {
57
+ // Remembered per key, scope set and subject: a corrected key hashes to
58
+ // another entry, so fixing it is never held back by this.
59
+ if (err instanceof ServiceAccountAuthError) {
60
+ remember(this.failures, cacheKey, { error: err, retryAt: this.now() + err.retryAfterMs });
61
+ }
62
+ throw err;
63
+ })
64
+ .finally(() => this.inFlight.delete(cacheKey));
65
+ this.inFlight.set(cacheKey, exchange);
66
+ return exchange;
67
+ }
68
+ async exchange(key, scope, subject, cacheKey) {
69
+ const assertion = signAssertion(key, scope, subject, this.now());
70
+ let res;
71
+ try {
72
+ res = await this.fetchImpl(GOOGLE_TOKEN_URL, {
73
+ method: 'POST',
74
+ headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
75
+ body: new URLSearchParams({ grant_type: JWT_BEARER_GRANT, assertion }).toString(),
76
+ // Don't follow redirects: the assertion goes to Google's endpoint and nowhere else.
77
+ redirect: 'error',
78
+ signal: AbortSignal.timeout(this.timeoutMs),
79
+ });
80
+ }
81
+ catch (err) {
82
+ const reason = err instanceof Error && err.name === 'TimeoutError'
83
+ ? `timed out after ${this.timeoutMs}ms`
84
+ : err instanceof Error
85
+ ? err.message
86
+ : String(err);
87
+ throw new ServiceAccountAuthError(`Google's token endpoint could not be reached: ${reason}`);
88
+ }
89
+ // Whatever came back is read as an object of fields or as none. A body
90
+ // that is not JSON, and one that is JSON but no object (`null`, a number,
91
+ // a list), both carry no field to read: reading one off `null` would
92
+ // throw a TypeError instead of the refusal below, past the code that
93
+ // remembers a failure and says who was refused.
94
+ const parsed = await res.json().catch(() => null);
95
+ const body = (parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {});
96
+ if (!res.ok) {
97
+ // Google says why in `error` and `error_description` (a revoked key, a
98
+ // scope the account may not have, a subject without delegation); neither
99
+ // carries the key, so both are passed on.
100
+ const detail = [body.error, body.error_description].filter((v) => typeof v === 'string').join(': ');
101
+ throw new ServiceAccountAuthError(`Google refused the service account ${key.clientEmail} (HTTP ${res.status})${detail ? `: ${detail}` : ''}`, retryAfterMs(res.headers.get('retry-after'), this.now()));
102
+ }
103
+ const accessToken = typeof body.access_token === 'string' ? body.access_token : '';
104
+ if (!accessToken)
105
+ throw new ServiceAccountAuthError("Google's token response had no access_token");
106
+ const expiresIn = typeof body.expires_in === 'number' ? body.expires_in : ASSERTION_LIFETIME_S;
107
+ this.failures.delete(cacheKey);
108
+ remember(this.tokens, cacheKey, { accessToken, expiresAt: this.now() + expiresIn * 1000 });
109
+ return accessToken;
110
+ }
111
+ }
112
+ /**
113
+ * Keep `value` under `cacheKey`, dropping the oldest entry first when the map
114
+ * is full: a Map iterates in insertion order, and re-inserting moves an entry
115
+ * to the back.
116
+ */
117
+ function remember(map, cacheKey, value) {
118
+ map.delete(cacheKey);
119
+ if (map.size >= MAX_CACHED_TOKENS) {
120
+ const oldest = map.keys().next().value;
121
+ if (oldest !== undefined)
122
+ map.delete(oldest);
123
+ }
124
+ map.set(cacheKey, value);
125
+ }
126
+ /**
127
+ * How long to hold calls back after a refusal: Google's `Retry-After` (seconds
128
+ * or an HTTP date) when it sent one, capped, else the default backoff.
129
+ */
130
+ function retryAfterMs(header, now) {
131
+ if (!header)
132
+ return FAILURE_BACKOFF_MS;
133
+ const seconds = Number(header);
134
+ const ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(header) - now;
135
+ if (!Number.isFinite(ms) || ms <= 0)
136
+ return FAILURE_BACKOFF_MS;
137
+ return Math.min(ms, MAX_FAILURE_BACKOFF_MS);
138
+ }
139
+ /**
140
+ * The key as an admin is likely to have stored it: the JSON file Google
141
+ * issued, or that JSON in base64. Only the fields the assertion needs are
142
+ * kept, and no error quotes what was stored.
143
+ */
144
+ function parseServiceAccountKey(raw) {
145
+ const value = raw.trim();
146
+ let parsed;
147
+ try {
148
+ parsed = JSON.parse(value.startsWith('{') ? value : Buffer.from(value, 'base64').toString('utf8'));
149
+ }
150
+ catch {
151
+ throw new ServiceAccountAuthError('The service-account credentials are not a key JSON. Store the JSON file Google issued for the service account.');
152
+ }
153
+ const obj = (parsed ?? {});
154
+ const clientEmail = typeof obj.client_email === 'string' ? obj.client_email : '';
155
+ const privateKey = typeof obj.private_key === 'string' ? obj.private_key : '';
156
+ if (!clientEmail || !privateKey) {
157
+ throw new ServiceAccountAuthError('The service-account key JSON has no client_email or private_key. Store the JSON file Google issued for the service account.');
158
+ }
159
+ return {
160
+ clientEmail,
161
+ privateKey,
162
+ privateKeyId: typeof obj.private_key_id === 'string' ? obj.private_key_id : undefined,
163
+ };
164
+ }
165
+ /**
166
+ * The scopes as Google wants them: space-separated, each trimmed. UTCP keeps
167
+ * the template as written once it validates, so stray whitespace is cleaned
168
+ * here, whether it sits in a list entry or in a space-separated string.
169
+ */
170
+ function scopeString(scopes) {
171
+ const list = Array.isArray(scopes) ? scopes : [scopes];
172
+ return list
173
+ .flatMap((s) => s.split(/\s+/))
174
+ .filter(Boolean)
175
+ .join(' ');
176
+ }
177
+ /** One entry per key, scope set and subject. The private key is hashed so the cache holds no copy of it. */
178
+ function tokenCacheKey(key, scope, subject) {
179
+ const keyHash = createHash('sha256').update(key.privateKey).digest('hex');
180
+ return JSON.stringify([key.clientEmail, key.privateKeyId ?? '', keyHash, scope.split(' ').sort().join(' '), subject ?? '']);
181
+ }
182
+ /** The RS256 assertion Google exchanges for an access token. */
183
+ function signAssertion(key, scope, subject, now) {
184
+ const seconds = Math.floor(now / 1000);
185
+ const part = (value) => Buffer.from(JSON.stringify(value), 'utf8').toString('base64url');
186
+ const header = { alg: 'RS256', typ: 'JWT', ...(key.privateKeyId ? { kid: key.privateKeyId } : {}) };
187
+ const claims = {
188
+ iss: key.clientEmail,
189
+ scope,
190
+ aud: GOOGLE_TOKEN_URL,
191
+ iat: seconds,
192
+ exp: seconds + ASSERTION_LIFETIME_S,
193
+ ...(subject ? { sub: subject } : {}),
194
+ };
195
+ const body = `${part(header)}.${part(claims)}`;
196
+ let signature;
197
+ try {
198
+ signature = createSign('RSA-SHA256').update(body).end().sign(key.privateKey, 'base64url');
199
+ }
200
+ catch {
201
+ // What the key was is never quoted.
202
+ throw new ServiceAccountAuthError(`The private key of service account ${key.clientEmail} could not be read. It must be the PEM in the key JSON Google issued.`);
203
+ }
204
+ return `${body}.${signature}`;
205
+ }
206
+ //# sourceMappingURL=google-service-account.token-source.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"google-service-account.token-source.js","sourceRoot":"","sources":["../../src/google-service-account/google-service-account.token-source.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,5 @@
1
+ export { isGoogleServiceAccountAuth, findUnservedGoogleServiceAccountAuth, holdsLiteralGoogleServiceAccountKey, } from './google-service-account.auth.js';
2
+ export { GoogleAuthHttpProtocol, installGoogleServiceAccountAuth } from './google-auth-http.protocol.js';
3
+ export { GoogleServiceAccountTokenSource, GOOGLE_TOKEN_URL } from './google-service-account.token-source.js';
4
+ export { GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE, ServiceAccountAuthError, type GoogleServiceAccountAuth, type IServiceAccountTokenSource, } from './service-account-token.contract.js';
5
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/google-service-account/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,0BAA0B,EAC1B,oCAAoC,EACpC,mCAAmC,GACpC,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,+BAA+B,EAAE,MAAM,gCAAgC,CAAC;AACzG,OAAO,EAAE,+BAA+B,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC7G,OAAO,EACL,gCAAgC,EAChC,uBAAuB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,GAChC,MAAM,qCAAqC,CAAC"}
@@ -0,0 +1,7 @@
1
+ // Importing this module registers the `google_service_account` auth type with
2
+ // UTCP and puts the `http` protocol that acts on it in place of the stock one.
3
+ export { isGoogleServiceAccountAuth, findUnservedGoogleServiceAccountAuth, holdsLiteralGoogleServiceAccountKey, } from './google-service-account.auth.js';
4
+ export { GoogleAuthHttpProtocol, installGoogleServiceAccountAuth } from './google-auth-http.protocol.js';
5
+ export { GoogleServiceAccountTokenSource, GOOGLE_TOKEN_URL } from './google-service-account.token-source.js';
6
+ export { GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE, ServiceAccountAuthError, } from './service-account-token.contract.js';
7
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/google-service-account/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,+EAA+E;AAC/E,OAAO,EACL,0BAA0B,EAC1B,oCAAoC,EACpC,mCAAmC,GACpC,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,+BAA+B,EAAE,MAAM,gCAAgC,CAAC;AACzG,OAAO,EAAE,+BAA+B,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC7G,OAAO,EACL,gCAAgC,EAChC,uBAAuB,GAGxB,MAAM,qCAAqC,CAAC"}
@@ -0,0 +1,33 @@
1
+ /** The `auth_type` a `.tool` call template names to call a Google API as a service account. */
2
+ export declare const GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE = "google_service_account";
3
+ /**
4
+ * A call template's `auth` block for a Google service account, as it reaches
5
+ * the protocol: variables already substituted, so `credentials` holds the key
6
+ * itself rather than the `${VAR}` that named it.
7
+ */
8
+ export interface GoogleServiceAccountAuth {
9
+ auth_type: typeof GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE;
10
+ /** The service-account key JSON Google issued, or that JSON in base64. Normally `${VAR}`, filled from the Secrets Vault. */
11
+ credentials: string;
12
+ /** The OAuth scopes the token is for: one scope, a space-separated list, or an array. */
13
+ scopes: string | string[];
14
+ /** The user to act as under domain-wide delegation. Absent, the token is the service account's own. */
15
+ subject?: string;
16
+ }
17
+ /**
18
+ * Answers the one question a tool call has of a service account: which bearer
19
+ * token to send right now. How the token is minted and how long it is kept is
20
+ * the implementation's business.
21
+ */
22
+ export interface IServiceAccountTokenSource {
23
+ accessToken(auth: GoogleServiceAccountAuth): Promise<string>;
24
+ }
25
+ /** A service-account token could not be had. The message never carries the key. */
26
+ export declare class ServiceAccountAuthError extends Error {
27
+ /** How long the same token should not be asked for again. */
28
+ readonly retryAfterMs: number;
29
+ constructor(message: string,
30
+ /** How long the same token should not be asked for again. */
31
+ retryAfterMs?: number);
32
+ }
33
+ //# sourceMappingURL=service-account-token.contract.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"service-account-token.contract.d.ts","sourceRoot":"","sources":["../../src/google-service-account/service-account-token.contract.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,eAAO,MAAM,gCAAgC,2BAA2B,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,OAAO,gCAAgC,CAAC;IACnD,4HAA4H;IAC5H,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,uGAAuG;IACvG,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,WAAW,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9D;AAED,mFAAmF;AACnF,qBAAa,uBAAwB,SAAQ,KAAK;IAG9C,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,EAAE,MAAM;gBAF7B,OAAO,EAAE,MAAM;IACf,6DAA6D;IACpD,YAAY,GAAE,MAAc;CAKxC"}
@@ -0,0 +1,14 @@
1
+ /** The `auth_type` a `.tool` call template names to call a Google API as a service account. */
2
+ export const GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE = 'google_service_account';
3
+ /** A service-account token could not be had. The message never carries the key. */
4
+ export class ServiceAccountAuthError extends Error {
5
+ retryAfterMs;
6
+ constructor(message,
7
+ /** How long the same token should not be asked for again. */
8
+ retryAfterMs = 5_000) {
9
+ super(message);
10
+ this.retryAfterMs = retryAfterMs;
11
+ this.name = 'ServiceAccountAuthError';
12
+ }
13
+ }
14
+ //# sourceMappingURL=service-account-token.contract.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"service-account-token.contract.js","sourceRoot":"","sources":["../../src/google-service-account/service-account-token.contract.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,MAAM,CAAC,MAAM,gCAAgC,GAAG,wBAAwB,CAAC;AA0BzE,mFAAmF;AACnF,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAIrC;IAHX,YACE,OAAe;IACf,6DAA6D;IACpD,eAAuB,KAAK;QAErC,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,iBAAY,GAAZ,YAAY,CAAgB;QAGrC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF"}
package/dist/index.d.ts CHANGED
@@ -26,13 +26,16 @@
26
26
  * thing as session recovery, and stays each surface's own.
27
27
  */
28
28
  export { type ProxiedTool, toListedTool, sanitizeInputSchema, flattenManualTool, flattenDiscoveredTool, } from './proxied-tool.js';
29
- export { describeToolFailure, toCallToolResult, renderProgress, toolError, needsAuthorizationResult, MCP_IMAGE_RESULT_KIND, type McpImageResult, mcpImageResult, isMcpImageResult, omitImagePayloads, } from './results.js';
30
- export { CODE_MODE_META_TOOLS, META_TOOL_NAMES, CALL_TOOL_CHAIN_MAX_OUTPUT, type SpillPort, dispatchMetaTool, } from './meta-tools.js';
29
+ export { describeToolFailure, withTransportDetail, toCallToolResult, renderProgress, toolError, needsAuthorizationResult, MCP_IMAGE_RESULT_KIND, type McpImageResult, mcpImageResult, isMcpImageResult, omitImagePayloads, } from './results.js';
30
+ export { codeModeMetaTools, chainNamespaceExample, META_TOOL_NAMES, CALL_TOOL_CHAIN_MAX_OUTPUT, CALL_TOOL_CHAIN_NAME, CHAIN_FAILURES_RULE, CHAIN_LARGE_RESULTS_RULE, type CodeModeMetaToolsOptions, type SpillPort, dispatchMetaTool, } from './meta-tools.js';
31
+ export { CHAIN_RUNTIME_PRELUDE, CHAIN_TIMEOUT_DEFAULT_MS, CHAIN_TIMEOUT_MAX_MS, CHAIN_TIMEOUT_MIN_MS, type ChainNamespaces, type ToolChainOutcome, chainNamespaces, chainOutOfMemoryMessage, chainTimeoutMessage, describeChainFailure, runToolChain, unknownNamespaceMessage, withChainRuntime, } from './chain-runtime.js';
32
+ export { type ChainExample, type ChainExampleTool, chainExample, } from './chain-example.js';
31
33
  export { registerManual, dispatchToolCall } from './dispatch.js';
32
- export { RETIRED_TOOL_MESSAGES, RETIRED_TOOL_NAMES, retiredToolMessage, retiredToolInFailure, retiredToolChainFailure, } from './retired-tools.js';
34
+ export { RETIRED_TOOL_MESSAGES, RETIRED_TOOL_NAMES, retiredToolMessage, retiredToolInFailure, } from './retired-tools.js';
33
35
  export { isSessionLoss, installSessionRecovery, noteManualReregistered, type SessionRecoveryOptions, } from './session-recovery.js';
34
36
  export { type SkillSummary, type LoadedSkill, skillPromptText, } from './skills.js';
35
37
  export { utcpNamespacePrefix, utcpNamespacedKey, seedBevelHostedManualVars, } from './utcp-namespace.js';
36
38
  export { sanitizeIdentifier, utcpNameToTsInterfaceName, findToolByName, findToolsByNames, AmbiguousToolNameError, } from './code-mode-names.js';
37
39
  export { printable } from './printable.js';
40
+ export { GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE, GOOGLE_TOKEN_URL, GoogleAuthHttpProtocol, GoogleServiceAccountTokenSource, ServiceAccountAuthError, findUnservedGoogleServiceAccountAuth, holdsLiteralGoogleServiceAccountKey, installGoogleServiceAccountAuth, isGoogleServiceAccountAuth, type GoogleServiceAccountAuth, type IServiceAccountTokenSource, } from './google-service-account/index.js';
38
41
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,KAAK,WAAW,EAChB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,cAAc,EACnB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,0BAA0B,EAC1B,KAAK,SAAS,EACd,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,KAAK,WAAW,EAChB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,cAAc,EACnB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,SAAS,EACd,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAM3C,OAAO,EACL,gCAAgC,EAChC,gBAAgB,EAChB,sBAAsB,EACtB,+BAA+B,EAC/B,uBAAuB,EACvB,oCAAoC,EACpC,mCAAmC,EACnC,+BAA+B,EAC/B,0BAA0B,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,GAChC,MAAM,mCAAmC,CAAC"}
package/dist/index.js CHANGED
@@ -26,13 +26,20 @@
26
26
  * thing as session recovery, and stays each surface's own.
27
27
  */
28
28
  export { toListedTool, sanitizeInputSchema, flattenManualTool, flattenDiscoveredTool, } from './proxied-tool.js';
29
- export { describeToolFailure, toCallToolResult, renderProgress, toolError, needsAuthorizationResult, MCP_IMAGE_RESULT_KIND, mcpImageResult, isMcpImageResult, omitImagePayloads, } from './results.js';
30
- export { CODE_MODE_META_TOOLS, META_TOOL_NAMES, CALL_TOOL_CHAIN_MAX_OUTPUT, dispatchMetaTool, } from './meta-tools.js';
29
+ export { describeToolFailure, withTransportDetail, toCallToolResult, renderProgress, toolError, needsAuthorizationResult, MCP_IMAGE_RESULT_KIND, mcpImageResult, isMcpImageResult, omitImagePayloads, } from './results.js';
30
+ export { codeModeMetaTools, chainNamespaceExample, META_TOOL_NAMES, CALL_TOOL_CHAIN_MAX_OUTPUT, CALL_TOOL_CHAIN_NAME, CHAIN_FAILURES_RULE, CHAIN_LARGE_RESULTS_RULE, dispatchMetaTool, } from './meta-tools.js';
31
+ export { CHAIN_RUNTIME_PRELUDE, CHAIN_TIMEOUT_DEFAULT_MS, CHAIN_TIMEOUT_MAX_MS, CHAIN_TIMEOUT_MIN_MS, chainNamespaces, chainOutOfMemoryMessage, chainTimeoutMessage, describeChainFailure, runToolChain, unknownNamespaceMessage, withChainRuntime, } from './chain-runtime.js';
32
+ export { chainExample, } from './chain-example.js';
31
33
  export { registerManual, dispatchToolCall } from './dispatch.js';
32
- export { RETIRED_TOOL_MESSAGES, RETIRED_TOOL_NAMES, retiredToolMessage, retiredToolInFailure, retiredToolChainFailure, } from './retired-tools.js';
34
+ export { RETIRED_TOOL_MESSAGES, RETIRED_TOOL_NAMES, retiredToolMessage, retiredToolInFailure, } from './retired-tools.js';
33
35
  export { isSessionLoss, installSessionRecovery, noteManualReregistered, } from './session-recovery.js';
34
36
  export { skillPromptText, } from './skills.js';
35
37
  export { utcpNamespacePrefix, utcpNamespacedKey, seedBevelHostedManualVars, } from './utcp-namespace.js';
36
38
  export { sanitizeIdentifier, utcpNameToTsInterfaceName, findToolByName, findToolsByNames, AmbiguousToolNameError, } from './code-mode-names.js';
37
39
  export { printable } from './printable.js';
40
+ // Loading this package teaches UTCP `auth_type: google_service_account`, on
41
+ // both surfaces alike: the auth type validates and the `http` protocol mints
42
+ // the token. A side effect of the import, like the `@utcp/http` registration
43
+ // it builds on, so neither surface has a step to forget.
44
+ export { GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE, GOOGLE_TOKEN_URL, GoogleAuthHttpProtocol, GoogleServiceAccountTokenSource, ServiceAccountAuthError, findUnservedGoogleServiceAccountAuth, holdsLiteralGoogleServiceAccountKey, installGoogleServiceAccountAuth, isGoogleServiceAccountAuth, } from './google-service-account/index.js';
38
45
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EAErB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,0BAA0B,EAE1B,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,GAEvB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAGL,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EAErB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EAGxB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EAGpB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAGL,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,GAEvB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAGL,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,4EAA4E;AAC5E,6EAA6E;AAC7E,6EAA6E;AAC7E,yDAAyD;AACzD,OAAO,EACL,gCAAgC,EAChC,gBAAgB,EAChB,sBAAsB,EACtB,+BAA+B,EAC/B,uBAAuB,EACvB,oCAAoC,EACpC,mCAAmC,EACnC,+BAA+B,EAC/B,0BAA0B,GAG3B,MAAM,mCAAmC,CAAC"}
@@ -1,6 +1,105 @@
1
1
  import type { Tool as McpTool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
2
2
  import type { CodeModeUtcpClient } from '@utcp/code-mode';
3
- export declare const CODE_MODE_META_TOOLS: McpTool[];
3
+ import { type ChainExampleTool } from './chain-example.js';
4
+ /**
5
+ * Code-mode meta-tools exposed ALONGSIDE the direct tools. They let an external
6
+ * agent batch many Bevel calls into one isolated-vm run (`call_tool_chain`)
7
+ * instead of one MCP round-trip per call — the same efficiency our own agent
8
+ * gets. `call_tool_chain`'s description carries the code-mode protocol, so the
9
+ * client learns the convention from the tool itself; `list_tools`/`tools_info`
10
+ * are how it discovers what to call. There IS a system prompt over MCP now: the
11
+ * platform header and the admin's preamble arrive as `instructions` on the
12
+ * initialize handshake (see core-backend's modules/agent-instructions/compose.ts).
13
+ * The PROTOCOL stays in the description regardless, because several clients
14
+ * (claude.ai on the web, the Agent SDK, Cline) drop that field.
15
+ *
16
+ * What a chain DOES, though — to a failure, to a large result, to an image —
17
+ * is true of every call, and those rules are stated once, in the handshake
18
+ * instructions and in the platform-managed agent guide, rather than on each
19
+ * tool they cover. So on a surface that has those rules the chain description
20
+ * ends with the same pointer sentence every file tool ends with, composed
21
+ * where the tool is served and the guide's configured name is known
22
+ * (core-backend's mcp.service.ts; nothing here may spell `AGENTS.md`, since
23
+ * the name is a deployment setting). A client that drops `instructions` is
24
+ * then still told WHERE the rules are, which is what the guide is for.
25
+ * The standalone bridge in `hexis-mcp` passes no pointer and so serves the
26
+ * description WHOLE, rules included: it proxies a remote knowledge base and
27
+ * does not know that deployment's layout.
28
+ *
29
+ * Security is identical to the direct surface: the chain runs in an isolated-vm
30
+ * but calls tools with the CALLER's credentials against the external catalog —
31
+ * internal-only tools aren't in that catalog, so a chain can't reach them either.
32
+ *
33
+ * These three belong to whichever client holds the registry. A surface that
34
+ * registers ANOTHER Bevel MCP endpoint as one of its manuals therefore has to
35
+ * drop that endpoint's copies from the passthrough (see {@link META_TOOL_NAMES}):
36
+ * the remote trio describes the remote registry, and locally they must describe
37
+ * the merged one.
38
+ */
39
+ /** The chain tool's name, for the callers that single it out by name. */
40
+ export declare const CALL_TOOL_CHAIN_NAME = "call_tool_chain";
41
+ /**
42
+ * The namespace every example in the three descriptions is written against.
43
+ *
44
+ * It is NOT fixed text, because it is not the same name on every connection:
45
+ * the hosted endpoint registers the knowledge-base tools as `KNOWLEDGE_BASE`,
46
+ * while the local server registers the whole deployment as one `hexis` manual.
47
+ * A description that named the other one taught the agent a namespace the
48
+ * runtime had no binding for, and the example call it copied died of
49
+ * `ReferenceError` — which is how this was reported. So each surface passes
50
+ * the name it actually registers, and the examples are built from it.
51
+ *
52
+ * Sanitized the way the runtime sanitizes it, so the example is callable even
53
+ * when the registered manual's name is not a bare identifier: `@utcp/code-mode`
54
+ * exposes `global.<sanitized manual name>`, and an example spelled any other
55
+ * way would not run.
56
+ */
57
+ export declare function chainNamespaceExample(namespace: string): string;
58
+ /**
59
+ * What a chain does when it FAILS — one of the rules about a chain that are
60
+ * true of every call, not of how to write one.
61
+ *
62
+ * Exported as text because it is stated in ONE of two places, never both: in
63
+ * the rules every tool shares (the handshake instructions and the managed
64
+ * agent guide, see core-backend's `agent-instructions/shared-file-rules.ts`)
65
+ * on a surface that has them, and in the chain's own description on one that
66
+ * does not. The same sentences either way, so the rule cannot read differently
67
+ * depending on where an agent found it.
68
+ */
69
+ export declare const CHAIN_FAILURES_RULE = "Failures are answered, never dropped: a chain that throws comes back as an error carrying the reason, and one that outlives `timeout` (default 30000 ms, maximum 120000 ms) comes back saying so \u2014 raise `timeout` or split the work and run it again. Either way the connection stays open and your next call works as usual.";
70
+ /** What a chain does with a result too large to return. Placed as {@link CHAIN_FAILURES_RULE} is. */
71
+ export declare const CHAIN_LARGE_RESULTS_RULE = "Large results: if the combined result+logs exceed `max_output_size` (default 200000 chars) the full JSON is spilled to a shared store and you get back a `__tool_chain_spill__/\u2026` ref instead. Read it with `read_file` (pass that ref as `path` \u2014 `branch` is ignored \u2014 plus `offset`/`limit` to slice it), or better, re-run a narrower chain that returns only what you need.";
72
+ /** What a surface says about itself when it asks for the meta-tools. */
73
+ export interface CodeModeMetaToolsOptions {
74
+ /**
75
+ * The sentence that ends the chain's description on a surface whose
76
+ * knowledge base states the shared rules (see {@link callToolChainDescription}).
77
+ * Opaque text: the caller composes it, because it names the agent guide and
78
+ * that name is a deployment setting — nothing here may spell `AGENTS.md`.
79
+ * Absent, the description carries the chain's rules itself.
80
+ */
81
+ sharedRulesPointer?: string;
82
+ }
83
+ /**
84
+ * The three meta-tools, with every example written against the namespace this
85
+ * connection really exposes and a tool name its catalog really has.
86
+ *
87
+ * Built per listing rather than held as a module constant: both belong to the
88
+ * surface, and a description computed once and shared across surfaces is the
89
+ * fixed text this replaces. `tools` is the surface's catalog — pass every tool
90
+ * it serves, names AND input schemas, since the arguments in the example come
91
+ * from the schema (see `chainExample`).
92
+ *
93
+ * `list_tools` and `tools_info` describe the registry, not what a call does,
94
+ * so neither ever carried a shared rule and neither gains the pointer.
95
+ */
96
+ export declare function codeModeMetaTools(namespace: string, tools?: readonly ChainExampleTool[], options?: CodeModeMetaToolsOptions): McpTool[];
97
+ /**
98
+ * The meta-tool NAMES, which no namespace can change. Kept separate from
99
+ * {@link codeModeMetaTools} because every surface needs them to route a call
100
+ * and to keep a discovered copy out of its listing, and neither of those knows
101
+ * — or should need — the namespace.
102
+ */
4
103
  export declare const META_TOOL_NAMES: ReadonlySet<string>;
5
104
  /** Default cap on a `call_tool_chain` result's stringified size before it spills. */
6
105
  export declare const CALL_TOOL_CHAIN_MAX_OUTPUT = 200000;
@@ -1 +1 @@
1
- {"version":3,"file":"meta-tools.d.ts","sourceRoot":"","sources":["../src/meta-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,IAAI,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAC1F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAkC1D,eAAO,MAAM,oBAAoB,EAAE,OAAO,EAkCzC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAAoD,CAAC;AAErG,qFAAqF;AACrF,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAgBlD;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9D;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,CAAC,EAAE,SAAS,GAChB,OAAO,CAAC,cAAc,CAAC,CA+FzB"}
1
+ {"version":3,"file":"meta-tools.d.ts","sourceRoot":"","sources":["../src/meta-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,IAAI,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAC1F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,EAAmC,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAU5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,wUAA8W,CAAC;AAE/Y,qGAAqG;AACrG,eAAO,MAAM,wBAAwB,oYAC+U,CAAC;AAyCrX,wEAAwE;AACxE,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,SAAS,gBAAgB,EAAO,EACvC,OAAO,GAAE,wBAA6B,GACrC,OAAO,EAAE,CA0CX;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAA+D,CAAC;AAChH,qFAAqF;AACrF,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAgBlD;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9D;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,CAAC,EAAE,SAAS,GAChB,OAAO,CAAC,cAAc,CAAC,CAkHzB"}