unbrowse 3.1.0-experiments.995f8bb → 3.1.0-experiments.9cbcb13

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 (105) hide show
  1. package/dist/cli.js +79 -33
  2. package/dist/index.js +2 -6
  3. package/dist/mcp.js +73 -22
  4. package/dist/server.js +25994 -0
  5. package/package.json +1 -2
  6. package/vendor/kuri/manifest.json +1 -1
  7. package/runtime-src/agent-outcome.ts +0 -166
  8. package/runtime-src/analytics-session.ts +0 -55
  9. package/runtime-src/api/browse-index.ts +0 -343
  10. package/runtime-src/api/browse-session.ts +0 -572
  11. package/runtime-src/api/browse-submit-prereqs.ts +0 -48
  12. package/runtime-src/api/browse-submit.ts +0 -1184
  13. package/runtime-src/api/routes.ts +0 -1833
  14. package/runtime-src/auth/browser-cookies.ts +0 -423
  15. package/runtime-src/auth/index.ts +0 -535
  16. package/runtime-src/auth/runtime.ts +0 -116
  17. package/runtime-src/browser/index.ts +0 -659
  18. package/runtime-src/browser/types.ts +0 -41
  19. package/runtime-src/build-info.generated.ts +0 -6
  20. package/runtime-src/capture/index.ts +0 -1929
  21. package/runtime-src/capture/prefetch.ts +0 -95
  22. package/runtime-src/capture/rsc.ts +0 -45
  23. package/runtime-src/cli/shortcuts.ts +0 -273
  24. package/runtime-src/cli.ts +0 -1734
  25. package/runtime-src/client/graph-client.ts +0 -100
  26. package/runtime-src/client/index.ts +0 -1425
  27. package/runtime-src/debug-trace.ts +0 -18
  28. package/runtime-src/domain.ts +0 -38
  29. package/runtime-src/execution/index.ts +0 -3407
  30. package/runtime-src/execution/retry.ts +0 -46
  31. package/runtime-src/execution/robots.ts +0 -167
  32. package/runtime-src/execution/search-forms.ts +0 -188
  33. package/runtime-src/execution/token-resolver.ts +0 -135
  34. package/runtime-src/extraction/index.ts +0 -1507
  35. package/runtime-src/foundry/publish-bundle.ts +0 -392
  36. package/runtime-src/graph/agent-augment.ts +0 -315
  37. package/runtime-src/graph/index.ts +0 -1532
  38. package/runtime-src/graph/local-fixtures.ts +0 -393
  39. package/runtime-src/graph/local-harness.ts +0 -646
  40. package/runtime-src/graph/planner.ts +0 -411
  41. package/runtime-src/graph/session.ts +0 -294
  42. package/runtime-src/graph/trace-store.ts +0 -136
  43. package/runtime-src/impact-log.ts +0 -227
  44. package/runtime-src/index.ts +0 -24
  45. package/runtime-src/indexer/index.ts +0 -465
  46. package/runtime-src/intent-match.ts +0 -1515
  47. package/runtime-src/kuri/client.ts +0 -1839
  48. package/runtime-src/logger.ts +0 -30
  49. package/runtime-src/marketplace/index.ts +0 -111
  50. package/runtime-src/mcp.ts +0 -1911
  51. package/runtime-src/orchestrator/browser-agent.ts +0 -374
  52. package/runtime-src/orchestrator/dag-advisor.ts +0 -59
  53. package/runtime-src/orchestrator/dag-feedback.ts +0 -257
  54. package/runtime-src/orchestrator/first-pass-action.ts +0 -403
  55. package/runtime-src/orchestrator/index.ts +0 -4480
  56. package/runtime-src/orchestrator/passive-publish.ts +0 -187
  57. package/runtime-src/orchestrator/timing-economics.ts +0 -80
  58. package/runtime-src/payments/cascade.ts +0 -137
  59. package/runtime-src/payments/index.ts +0 -270
  60. package/runtime-src/payments/lobster-pay.ts +0 -182
  61. package/runtime-src/payments/wallet.ts +0 -98
  62. package/runtime-src/publish/review-context.ts +0 -93
  63. package/runtime-src/publish/sanitize.ts +0 -197
  64. package/runtime-src/publish/schema-review.ts +0 -192
  65. package/runtime-src/publish-admission.ts +0 -388
  66. package/runtime-src/ratelimit/index.ts +0 -23
  67. package/runtime-src/reverse-engineer/bundle-scanner.ts +0 -127
  68. package/runtime-src/reverse-engineer/description-prompt.ts +0 -213
  69. package/runtime-src/reverse-engineer/index.ts +0 -1551
  70. package/runtime-src/reverse-engineer/token-sources.ts +0 -379
  71. package/runtime-src/router.ts +0 -17
  72. package/runtime-src/routing-telemetry.ts +0 -395
  73. package/runtime-src/runtime/browser-access.ts +0 -11
  74. package/runtime-src/runtime/browser-auth.ts +0 -12
  75. package/runtime-src/runtime/browser-host.ts +0 -48
  76. package/runtime-src/runtime/lifecycle.ts +0 -17
  77. package/runtime-src/runtime/local-server.ts +0 -311
  78. package/runtime-src/runtime/paths.ts +0 -99
  79. package/runtime-src/runtime/setup.ts +0 -251
  80. package/runtime-src/runtime/supervisor.ts +0 -69
  81. package/runtime-src/runtime/update-hints.ts +0 -351
  82. package/runtime-src/server.ts +0 -100
  83. package/runtime-src/session-logs.ts +0 -142
  84. package/runtime-src/settings.ts +0 -221
  85. package/runtime-src/single-binary.ts +0 -143
  86. package/runtime-src/site-policy.ts +0 -54
  87. package/runtime-src/stale-cleanup-runner.ts +0 -144
  88. package/runtime-src/stale-cleanup.ts +0 -133
  89. package/runtime-src/telemetry-attribution.ts +0 -120
  90. package/runtime-src/telemetry.ts +0 -253
  91. package/runtime-src/template-params.ts +0 -141
  92. package/runtime-src/transform/drift.ts +0 -60
  93. package/runtime-src/transform/index.ts +0 -277
  94. package/runtime-src/types/index.ts +0 -1
  95. package/runtime-src/types/skill.ts +0 -931
  96. package/runtime-src/vault/index.ts +0 -196
  97. package/runtime-src/verification/auth-gate.ts +0 -8
  98. package/runtime-src/verification/candidates.ts +0 -27
  99. package/runtime-src/verification/index.ts +0 -120
  100. package/runtime-src/verification/matrix.ts +0 -30
  101. package/runtime-src/version.ts +0 -148
  102. package/runtime-src/workflow/artifact.ts +0 -161
  103. package/runtime-src/workflow/compile.ts +0 -808
  104. package/runtime-src/workflow/publish.ts +0 -225
  105. package/runtime-src/workflow/runtime.ts +0 -213
@@ -1,1532 +0,0 @@
1
- import type {
2
- AgentAvailableOperation,
3
- AgentPrefetchOperation,
4
- AgentSkillChunkView,
5
- AgentWorkflowDagOperation,
6
- AgentWorkflowDagView,
7
- EndpointDescriptor,
8
- EndpointSemanticDescriptor,
9
- OperationBinding,
10
- ResponseSchema,
11
- SkillChunk,
12
- SkillManifest,
13
- SkillOperationEdge,
14
- SkillOperationGraph,
15
- SkillOperationNode,
16
- } from "../types/index.js";
17
- import { normalizeQueryBindingKey } from "../template-params.js";
18
-
19
- function normalizeTokenText(text: string): string {
20
- return text
21
- .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
22
- .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
23
- .replace(/([a-zA-Z])(\d)/g, "$1 $2")
24
- .replace(/(\d)([a-zA-Z])/g, "$1 $2");
25
- }
26
-
27
- function tokenize(text: string): string[] {
28
- return normalizeTokenText(text).toLowerCase().replace(/[^a-z0-9]+/g, " ").split(/\s+/).filter(Boolean);
29
- }
30
-
31
- function unique<T>(items: T[]): T[] {
32
- return [...new Set(items)];
33
- }
34
-
35
- function singularize(word: string): string {
36
- if (word.endsWith("ies") && word.length > 4) return `${word.slice(0, -3)}y`;
37
- if (word.endsWith("ses") || word.endsWith("ges") || word.endsWith("zes")) return word.slice(0, -2);
38
- if (word.endsWith("s") && !word.endsWith("ss") && word.length > 3) return word.slice(0, -1);
39
- return word;
40
- }
41
-
42
- function pluralize(word: string): string {
43
- if (word === "person") return "people";
44
- if (word === "repository") return "repositories";
45
- if (word === "status") return "statuses";
46
- if (word.endsWith("y") && word.length > 2 && !/[aeiou]y$/.test(word)) return `${word.slice(0, -1)}ies`;
47
- if (/(s|x|z|ch|sh)$/.test(word)) return `${word}es`;
48
- if (word.endsWith("s")) return word;
49
- return `${word}s`;
50
- }
51
-
52
- function humanizeToken(token: string): string {
53
- return normalizeTokenText(token.replace(/[{}]/g, "").replace(/[_-]+/g, " ")).toLowerCase().trim();
54
- }
55
-
56
- function stripFileExtension(segment: string): string {
57
- return segment.replace(/\.[a-z0-9]{1,8}$/i, "");
58
- }
59
-
60
- function sanitizeBindingName(raw: string): string {
61
- return raw
62
- .replace(/[^a-zA-Z0-9_]+/g, "_")
63
- .replace(/^_+|_+$/g, "")
64
- .replace(/_+/g, "_")
65
- .toLowerCase();
66
- }
67
-
68
- function isStructuralPathSegment(segment?: string): boolean {
69
- if (!segment) return true;
70
- return /^(api|v\d+|www|en|es|fr|de|ja|zh|ko|latest|dex|search)$/i.test(segment);
71
- }
72
-
73
- function looksLikeAcademicYear(segment: string): boolean {
74
- return /^\d{4}-\d{4}$/.test(segment);
75
- }
76
-
77
- function looksLikeCodeIdentifier(segment: string): boolean {
78
- return /^[A-Z]{2,}\d[A-Z0-9]*$/i.test(segment) && /[A-Z]/.test(segment) && /\d/.test(segment);
79
- }
80
-
81
- function inferPathBindingName(candidate: NonNullable<EndpointDescriptor["_path_binding_candidates"]>[number]): string {
82
- const value = stripFileExtension(candidate.observed_value);
83
- const prev = sanitizeBindingName(candidate.preceding_segment ?? "");
84
-
85
- if (looksLikeAcademicYear(value)) return "academic_year";
86
- if ((prev === "semester" || prev === "semesters") && /^\d{1,2}$/.test(value)) return "semester";
87
- if ((prev === "module" || prev === "modules") && looksLikeCodeIdentifier(value)) return "module_code";
88
- if ((prev === "course" || prev === "courses") && looksLikeCodeIdentifier(value)) return "course_code";
89
- if ((prev === "class" || prev === "classes") && looksLikeCodeIdentifier(value)) return "class_code";
90
-
91
- if (!isStructuralPathSegment(prev)) {
92
- const singular = sanitizeBindingName(singularize(prev));
93
- if (singular) return singular;
94
- }
95
-
96
- if (candidate.placeholder_hint === "urn") return "urn";
97
- if (candidate.placeholder_hint === "list") return "list";
98
- return "id";
99
- }
100
-
101
- function ensureUniqueBindingName(name: string, usedNames: Set<string>): string {
102
- const base = sanitizeBindingName(name) || "id";
103
- let unique = base;
104
- let counter = 2;
105
- while (usedNames.has(unique)) unique = `${base}_${counter++}`;
106
- usedNames.add(unique);
107
- return unique;
108
- }
109
-
110
- function replaceTemplateBinding(urlTemplate: string, from: string, to: string): string {
111
- const escaped = from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
112
- return urlTemplate.replace(new RegExp(`\\{${escaped}\\}`, "g"), `{${to}}`);
113
- }
114
-
115
- export function resolveEndpointPathBindings(endpoint: EndpointDescriptor): EndpointDescriptor {
116
- const candidates = endpoint._path_binding_candidates ?? [];
117
- if (candidates.length === 0) return endpoint;
118
-
119
- let urlTemplate = endpoint.url_template;
120
- const nextPathParams = { ...(endpoint.path_params ?? {}) };
121
- const candidatePlaceholders = new Set(candidates.map((candidate) => candidate.placeholder));
122
- const usedNames = new Set<string>([
123
- ...Object.keys(nextPathParams).filter((key) => !candidatePlaceholders.has(key) && !/^path_\d+$/.test(key)),
124
- ...Array.from(urlTemplate.matchAll(/\{([^}]+)\}/g)).map((match) => match[1]).filter((key) => !candidatePlaceholders.has(key) && !/^path_\d+$/.test(key)),
125
- ]);
126
-
127
- for (const candidate of candidates) {
128
- const oldKey = candidate.placeholder;
129
- const newKey = ensureUniqueBindingName(inferPathBindingName(candidate), usedNames);
130
- if (oldKey === newKey) {
131
- usedNames.add(newKey);
132
- continue;
133
- }
134
- urlTemplate = replaceTemplateBinding(urlTemplate, oldKey, newKey);
135
- if (Object.prototype.hasOwnProperty.call(nextPathParams, oldKey)) {
136
- nextPathParams[newKey] = nextPathParams[oldKey];
137
- delete nextPathParams[oldKey];
138
- }
139
- }
140
-
141
- return {
142
- ...endpoint,
143
- url_template: urlTemplate,
144
- ...(Object.keys(nextPathParams).length > 0 ? { path_params: nextPathParams } : { path_params: undefined }),
145
- };
146
- }
147
-
148
- function compactExample(value: unknown, depth = 0): unknown {
149
- if (depth > 2 || value == null) return value;
150
- if (Array.isArray(value)) {
151
- return value.slice(0, 2).map((item) => compactExample(item, depth + 1));
152
- }
153
- if (typeof value === "object") {
154
- const entries = Object.entries(value as Record<string, unknown>).slice(0, 8);
155
- return Object.fromEntries(entries.map(([k, v]) => [k, compactExample(v, depth + 1)]));
156
- }
157
- if (typeof value === "string" && value.length > 160) return `${value.slice(0, 157)}...`;
158
- return value;
159
- }
160
-
161
- function flattenFields(value: unknown, prefix = "", out: string[] = []): string[] {
162
- if (value == null) return out;
163
- if (Array.isArray(value)) {
164
- if (value.length > 0) flattenFields(value[0], `${prefix}[]`, out);
165
- return out;
166
- }
167
- if (typeof value !== "object") {
168
- if (prefix) out.push(prefix);
169
- return out;
170
- }
171
- for (const [key, next] of Object.entries(value as Record<string, unknown>).slice(0, 10)) {
172
- const path = prefix ? `${prefix}.${key}` : key;
173
- if (next && typeof next === "object") flattenFields(next, path, out);
174
- else out.push(path);
175
- }
176
- return out;
177
- }
178
-
179
- function summarizeSchemaFields(schema?: ResponseSchema): string[] {
180
- if (!schema) return [];
181
- if (schema.properties) {
182
- const out: string[] = [];
183
- for (const [key, val] of Object.entries(schema.properties)) {
184
- out.push(key);
185
- if (val.properties) {
186
- for (const nested of Object.keys(val.properties).slice(0, 5)) out.push(`${key}.${nested}`);
187
- } else if (val.items?.properties) {
188
- for (const nested of Object.keys(val.items.properties).slice(0, 5)) out.push(`${key}[].${nested}`);
189
- }
190
- }
191
- return out;
192
- }
193
- if (schema.items?.properties) {
194
- return Object.keys(schema.items.properties).map((key) => `[].${key}`);
195
- }
196
- return [];
197
- }
198
-
199
- function inferActionKind(text: string): string {
200
- if (/\b(feed|timeline|stream|inbox)\b/.test(text)) return "timeline";
201
- if (/\b(search|find|lookup)\b/.test(text)) return "search";
202
- if (/\b(list|browse|index|catalog|channels|guilds|messages|posts|repos|repositories)\b/.test(text)) return "list";
203
- if (/\b(trending|top|latest|popular|hot)\b/.test(text)) return "trending";
204
- if (/\b(status|health|incident|maintenance)\b/.test(text)) return "status";
205
- if (/\b(create|post|send|submit)\b/.test(text)) return "create";
206
- if (/\b(update|patch|edit)\b/.test(text)) return "update";
207
- if (/\b(delete|remove)\b/.test(text)) return "delete";
208
- if (/\b(detail|details|info|profile|show|get)\b/.test(text)) return "detail";
209
- return "fetch";
210
- }
211
-
212
- function inferResourceKind(text: string, urlTemplate?: string): string {
213
- const pathHint = inferPathResourceHint(urlTemplate);
214
- if (pathHint) return pathHint;
215
- if (/\b(form|dropdown|select|option|field)\b/.test(text)) return "form";
216
- if (/\bpeople\b/.test(text)) return "person";
217
- if (/\b(feed|timeline|stream|home|update|updates|commentary|actor|socialdetail)\b/.test(text)) return "post";
218
- const candidates = [
219
- "channel", "guild", "message", "thread", "conversation", "repo", "repository",
220
- "profile", "person", "user", "post", "comment", "listing", "document", "issue", "job",
221
- "article", "video", "product", "event", "notification", "topic", "status", "form", "option",
222
- "referral", "promotion", "entitlement", "billing", "payment", "preference", "setting",
223
- "experiment", "assignment", "config",
224
- ];
225
- for (const candidate of candidates) {
226
- if (new RegExp(`\\b${candidate}s?\\b`).test(text)) return candidate;
227
- }
228
- return "resource";
229
- }
230
-
231
- function inferNegativeTags(text: string): string[] {
232
- const tags: string[] = [];
233
- if (/\b(experiment|assignment|fingerprint|feature)\b/.test(text)) tags.push("experiment");
234
- if (/\b(status|incident|maintenance)\b/.test(text)) tags.push("status");
235
- if (/\b(config|settings|manifest|bootstrap)\b/.test(text)) tags.push("config");
236
- if (/\b(auth|login|csrf|session|oauth|bearer|authorization)\b|access[_-]?token|refresh[_-]?token|id[_-]?token/.test(text)) tags.push("auth");
237
- if (/\b(telemetry|analytics|metrics|science|beacon|tracking)\b/.test(text)) tags.push("telemetry");
238
- if (/\b(thirdparty|syncs?|clientsignal|impression|tracklix)\b/.test(text)) tags.push("telemetry");
239
- if (/\b(helper|launcher|onboarding|setup)\b/.test(text)) tags.push("helper");
240
- if (/\b(allowlist|pagekey|controlurn)\b/.test(text)) tags.push("helper");
241
- if (/\b(recommendation|recommendations|suggested|sidebar)\b/.test(text)) tags.push("recommendation");
242
- if (/\b(settings|preferences|badge_count|counts|counter)\b/.test(text)) tags.push("settings");
243
- if (/\b(message|messaging|dm|conversation|mailbox|inbox)\b/.test(text)) tags.push("messaging");
244
- if (/\b(promoted|promotion|ads?)\b/.test(text)) tags.push("ads");
245
- if (/\b(affinit|promotions?|referrals?|entitlements?|billing|subscriptions?|collectibles?|gifts?|perk)\b/.test(text)) tags.push("adjacent");
246
- return unique(tags);
247
- }
248
-
249
- function inferPathResourceHint(urlTemplate?: string): string | null {
250
- if (!urlTemplate) return null;
251
- try {
252
- const pathname = new URL(urlTemplate).pathname;
253
- const generic = new Set([
254
- "api", "graphql", "rpc", "rest", "v1", "v2", "v3", "v4", "v5", "v6", "v7", "v8", "v9",
255
- "users", "user", "me", "@me", "self", "app", "apps", "i",
256
- ]);
257
- const candidates = new Set([
258
- "channel", "guild", "message", "thread", "conversation", "repo", "repository",
259
- "profile", "person", "user", "post", "comment", "listing", "document", "issue", "job",
260
- "article", "video", "product", "event", "notification", "topic", "status", "form", "option",
261
- "referral", "promotion", "entitlement", "billing", "payment", "preference", "setting",
262
- "experiment", "assignment", "config",
263
- ]);
264
- const segments = pathname.split("/").filter(Boolean);
265
- for (let i = segments.length - 1; i >= 0; i--) {
266
- const raw = humanizeToken(segments[i] ?? "");
267
- const token = singularize(raw);
268
- if (!token || generic.has(token)) continue;
269
- if (/^\d+$/.test(token) || /^[0-9a-f-]{8,}$/.test(token) || /^(true|false)$/.test(token)) continue;
270
- if (/^\{.+\}$/.test(segments[i] ?? "")) continue;
271
- if (token === "server") return "guild";
272
- if (candidates.has(token)) return token;
273
- }
274
- } catch {
275
- return null;
276
- }
277
- return null;
278
- }
279
-
280
- function fieldLeaf(field: string): string {
281
- return field.replace(/\[\]/g, "").split(".").pop()?.toLowerCase() ?? "";
282
- }
283
-
284
- function summarizeDescriptionFields(fields: string[]): string[] {
285
- const labels: string[] = [];
286
- const seen = new Set<string>();
287
- for (const field of fields) {
288
- const leaf = fieldLeaf(field);
289
- if (!leaf || seen.has(leaf)) continue;
290
- if (/^(data|item|items|result|results|response|entry|entries|node|nodes|edge|edges|payload|value|values|__typename|type|flags?)$/.test(leaf)) continue;
291
- let label = "";
292
- if (/(^|_)id$/.test(leaf) || leaf === "id") label = "ids";
293
- else if (leaf === "name" || /_name$/.test(leaf)) label = "names";
294
- else if (leaf === "title") label = "titles";
295
- else if (/^(username|screen_name|handle|login|slug|public_identifier)$/.test(leaf)) label = "handles";
296
- else if (/^(content|body|text|message)$/.test(leaf)) label = "content";
297
- else if (/^(description|headline|summary)$/.test(leaf)) label = leaf === "headline" ? "headlines" : `${leaf}s`;
298
- else if (/^(status|indicator|state)$/.test(leaf)) label = "status";
299
- else if (/^(price|amount|value|score)$/.test(leaf)) label = leaf === "value" ? "values" : `${leaf}s`;
300
- else if (/(_count|count|total)$/.test(leaf)) label = "counts";
301
- else if (/^(created_at|updated_at|timestamp|date)$/.test(leaf)) label = "timestamps";
302
- else label = humanizeToken(leaf);
303
- if (seen.has(label)) continue;
304
- seen.add(leaf);
305
- seen.add(label);
306
- labels.push(label);
307
- if (labels.length >= 3) break;
308
- }
309
- return labels;
310
- }
311
-
312
- function joinLabels(labels: string[]): string {
313
- if (labels.length <= 1) return labels[0] ?? "";
314
- if (labels.length === 2) return `${labels[0]} and ${labels[1]}`;
315
- return `${labels[0]}, ${labels[1]}, and ${labels[2]}`;
316
- }
317
-
318
- function descriptionSubject(resourceKind: string, actionKind: string, text: string): string {
319
- const pathHint = inferPathResourceHint(text);
320
- const base = resourceKind && resourceKind !== "resource" ? resourceKind : (pathHint ?? "resource");
321
- const normalized = base === "repo" ? "repository" : base;
322
- return ["search", "list", "timeline", "trending"].includes(actionKind) ? pluralize(normalized) : normalized;
323
- }
324
-
325
- function isCapturedArtifactDescription(description?: string): boolean {
326
- const normalized = normalizeTokenText(description ?? "").toLowerCase().trim();
327
- return /^captured (?:search form |page )?artifact for\b/.test(normalized);
328
- }
329
-
330
- function isGenericDescription(description?: string): boolean {
331
- const normalized = normalizeTokenText(description ?? "").toLowerCase().trim();
332
- if (!normalized) return true;
333
- if (isCapturedArtifactDescription(normalized)) return true;
334
- if (/^(search form|page content) for\b/.test(normalized)) return true;
335
- if (/^returns details for\b/.test(normalized)) return true;
336
- if (/^returns [a-z0-9 ]+ data\b/.test(normalized)) return true;
337
- if (/\bwith data\b/.test(normalized)) return true;
338
- if (/\busing (?:variables|queryid|decorationid)\b/.test(normalized)) return true;
339
- if (/^searches [a-z0-9 ]+ with\b/.test(normalized) && /\b(elements|data|queryid)\b/.test(normalized)) return true;
340
- return false;
341
- }
342
-
343
- function classifyDescriptionInput(description?: string): {
344
- source: "agent" | "auto" | "missing";
345
- warning?: string;
346
- } {
347
- const normalized = normalizeTokenText(description ?? "").trim();
348
- if (!normalized) {
349
- return {
350
- source: "missing",
351
- warning: "Description missing. Review before trusting or publishing.",
352
- };
353
- }
354
- if (isCapturedArtifactDescription(normalized)) {
355
- return {
356
- source: "auto",
357
- warning: "Auto-generated from a captured page artifact. Review before trusting or publishing.",
358
- };
359
- }
360
- if (isGenericDescription(normalized)) {
361
- return {
362
- source: "auto",
363
- warning: "Auto-generated description. Review before trusting or publishing.",
364
- };
365
- }
366
- return { source: "agent" };
367
- }
368
-
369
- export function getEndpointDescriptionMetadata(endpoint: Pick<EndpointDescriptor, "description" | "semantic">): {
370
- display: string;
371
- source: "agent" | "auto" | "missing";
372
- needs_review: boolean;
373
- warning?: string;
374
- } {
375
- const input = classifyDescriptionInput(endpoint.description);
376
- // Trust the LLM augmenter's semantic layer when it has run.
377
- const agentAugmented = endpoint.semantic?.description_source === "agent";
378
- // Schema-grounded auto descriptions (with real response fields) don't need
379
- // external LLM review — the calling agent IS the LLM that reviews them.
380
- const schemaGrounded = !!(endpoint.semantic?.example_fields?.length || endpoint.semantic?.response_summary);
381
- const display = (input.source === "agent" || agentAugmented
382
- ? endpoint.semantic?.description_out ?? endpoint.description ?? ""
383
- : endpoint.semantic?.description_out ?? endpoint.description ?? "").trim();
384
- const source = display ? (input.source === "agent" || agentAugmented ? "agent" : "auto") : "missing";
385
- return {
386
- display,
387
- source,
388
- needs_review: source === "missing" || (source === "auto" && !schemaGrounded),
389
- ...(source !== "agent" && !schemaGrounded
390
- ? { warning: input.warning ?? "Auto-generated description. Review before trusting or publishing." }
391
- : {}),
392
- };
393
- }
394
-
395
- function buildSemanticDescription(
396
- endpoint: EndpointDescriptor,
397
- actionKind: string,
398
- resourceKind: string,
399
- fields: string[],
400
- ): string {
401
- const subject = descriptionSubject(resourceKind, actionKind, endpoint.url_template);
402
- let description: string;
403
- switch (actionKind) {
404
- case "search":
405
- description = `Searches ${subject}`;
406
- break;
407
- case "timeline":
408
- description = `Returns ${subject} timeline`;
409
- break;
410
- case "trending":
411
- description = `Returns trending ${subject}`;
412
- break;
413
- case "detail":
414
- description = `Returns ${subject} details`;
415
- break;
416
- case "status":
417
- description = resourceKind === "status" ? "Returns status" : `Returns ${subject} status`;
418
- break;
419
- case "create":
420
- description = `Creates ${subject}`;
421
- break;
422
- case "update":
423
- description = `Updates ${subject}`;
424
- break;
425
- case "delete":
426
- description = `Deletes ${subject}`;
427
- break;
428
- default:
429
- description = `Returns ${subject}`;
430
- break;
431
- }
432
- const fieldLabels = summarizeDescriptionFields(fields);
433
- return fieldLabels.length > 0 ? `${description} with ${joinLabels(fieldLabels)}` : description;
434
- }
435
-
436
- function inferBindingSemanticType(key: string): string {
437
- if (key === "academic_year") return "academic_year";
438
- if (key === "semester") return "semester";
439
- if (/^(module|course|class)_code$/.test(key)) return key;
440
- if (key.endsWith("_id") || key === "id" || key === "urn") return "identifier";
441
- return "input";
442
- }
443
-
444
- function inferRequires(endpoint: EndpointDescriptor): OperationBinding[] {
445
- const requires: OperationBinding[] = [];
446
- const seen = new Set<string>();
447
- const add = (key: string, source: string, required = true) => {
448
- if (!key || seen.has(key) || key === "endpoint_id") return;
449
- seen.add(key);
450
- requires.push({
451
- key,
452
- required,
453
- source,
454
- semantic_type: inferBindingSemanticType(key),
455
- });
456
- };
457
- for (const key of Object.keys(endpoint.path_params ?? {})) add(key, "path_params", false);
458
- for (const key of Object.keys(endpoint.query ?? {})) add(normalizeQueryBindingKey(key), "query", false);
459
- for (const match of endpoint.url_template.matchAll(/\{([^}]+)\}/g)) add(match[1], "url_template");
460
- return requires;
461
- }
462
-
463
- function inferProvidesFromFields(fields: string[], resourceKind: string): OperationBinding[] {
464
- const provides: OperationBinding[] = [];
465
- const seen = new Set<string>();
466
- const add = (key: string, semanticType: string) => {
467
- if (!key || seen.has(key)) return;
468
- seen.add(key);
469
- provides.push({ key, semantic_type: semanticType, source: "response" });
470
- };
471
- const addFormBinding = (key: string) => {
472
- add(key, `${key}_option`);
473
- add(`${key}_value`, `${key}_option_value`);
474
- };
475
- const inferFormBindingKey = (field: string): string | null => {
476
- const normalized = field.replace(/\[\]/g, "");
477
- const match = normalized.match(/(?:^|\.)([a-z0-9_]+?)(?:_options?|_dropdowns?|_select)?\.(?:options?|choices?)\.(?:value|label)$/i)
478
- ?? normalized.match(/(?:^|\.)([a-z0-9_]+?)(?:_options?|_dropdowns?|_select)?\.(?:value|label)$/i);
479
- if (!match) return null;
480
- const key = singularize(match[1].toLowerCase())
481
- .replace(/^(field|form|filter)_/, "")
482
- .replace(/_(field|form|filter)$/, "");
483
- if (!key || ["option", "options", "choice", "choices", "value", "label"].includes(key)) return null;
484
- return key;
485
- };
486
- const resourceAliases: Record<string, string[]> = {
487
- repository: ["repo", "repository"],
488
- repo: ["repo", "repository"],
489
- person: ["person", "profile", "user", "member"],
490
- profile: ["profile", "user", "member", "person"],
491
- user: ["user", "profile", "member", "person"],
492
- post: ["post", "status", "tweet"],
493
- topic: ["topic", "trend"],
494
- listing: ["listing", "item", "product"],
495
- guild: ["guild", "server"],
496
- channel: ["channel", "conversation", "thread"],
497
- message: ["message", "post"],
498
- };
499
- const aliases = resourceAliases[resourceKind] ?? [resourceKind];
500
- for (const field of fields) {
501
- const key = field.replace(/\[\]/g, "").split(".").pop() ?? field;
502
- if (/(^|_)(id)$/.test(key)) add(key, `${resourceKind}_identifier`);
503
- else if (/_id$/.test(key)) add(key, `${key.replace(/_id$/, "")}_identifier`);
504
- else if (/^(rest_id|public_identifier|entity_urn|urn|slug|screen_name|username|handle)$/.test(key)) {
505
- add(key, `${resourceKind}_identifier`);
506
- for (const alias of aliases) add(`${alias}_id`, `${alias}_identifier`);
507
- } else if (/^(full_name|name|title)$/.test(key)) {
508
- for (const alias of aliases) add(`${alias}_name`, `${alias}_name`);
509
- } else if (/^(url|link|canonical_url)$/.test(key)) {
510
- for (const alias of aliases) add(`${alias}_url`, `${alias}_url`);
511
- } else if (/^(query|q|keyword|keywords|search_term)$/.test(key)) {
512
- add("query", "query_text");
513
- } else if (/^(owner|owner_login|login|author|author_username|author_screen_name)$/.test(key)) {
514
- add(key, `${resourceKind}_owner`);
515
- add("owner", `${resourceKind}_owner`);
516
- } else if (/^(repo|repository|repo_name|repository_name)$/.test(key)) {
517
- add("repo", "repository_name");
518
- } else if (/^(domain|hostname|host)$/.test(key)) {
519
- add("domain", "domain");
520
- } else if (/(slug|name|title|url|path)$/.test(key)) add(key, key);
521
-
522
- const formKey = inferFormBindingKey(field);
523
- if (formKey) addFormBinding(formKey);
524
- }
525
- if (!seen.has(`${resourceKind}_id`) && fields.some((field) => /(^|\.)(id|rest_id|public_identifier|urn)(\.|$)/.test(field))) {
526
- add(`${resourceKind}_id`, `${resourceKind}_identifier`);
527
- for (const alias of aliases) add(`${alias}_id`, `${alias}_identifier`);
528
- }
529
- if ((resourceKind === "repository" || aliases.includes("repository")) && fields.some((field) => /(full_name|name|title)/.test(field))) {
530
- add("repo", "repository_name");
531
- add("repository_name", "repository_name");
532
- }
533
- if ((resourceKind === "profile" || aliases.includes("profile")) && fields.some((field) => /(public_identifier|slug|username|handle|name)/.test(field))) {
534
- add("public_identifier", "profile_identifier");
535
- add("profile_id", "profile_identifier");
536
- }
537
- if ((resourceKind === "topic" || aliases.includes("topic")) && fields.some((field) => /(name|title|trend|topic)/.test(field))) {
538
- add("topic_name", "topic_name");
539
- }
540
- if ((resourceKind === "channel" || aliases.includes("channel")) && fields.some((field) => /(id|name|channel)/.test(field))) {
541
- add("channel_id", "channel_identifier");
542
- add("channel_name", "channel_name");
543
- }
544
- if (resourceKind === "form") {
545
- for (const field of fields) {
546
- const formKey = inferFormBindingKey(field);
547
- if (formKey) addFormBinding(formKey);
548
- }
549
- }
550
- return provides.slice(0, 8);
551
- }
552
-
553
- function semanticText(endpoint: EndpointDescriptor): string {
554
- return [
555
- endpoint.method,
556
- endpoint.url_template,
557
- endpoint.description ?? "",
558
- ...(endpoint.semantic?.example_fields ?? []),
559
- ].join(" ");
560
- }
561
-
562
- function bindingIdentity(binding: OperationBinding): string {
563
- return [
564
- binding.key,
565
- binding.source ?? "",
566
- binding.semantic_type ?? "",
567
- binding.type ?? "",
568
- binding.required ? "1" : "0",
569
- ].join("|");
570
- }
571
-
572
- const BINDING_ENTITY_ALIASES: Record<string, string> = {
573
- repo: "repository",
574
- repository: "repository",
575
- owner: "repository",
576
- profile: "profile",
577
- person: "profile",
578
- member: "profile",
579
- user: "profile",
580
- account: "profile",
581
- org: "company",
582
- organization: "company",
583
- company: "company",
584
- listing: "listing",
585
- item: "listing",
586
- product: "listing",
587
- guild: "guild",
588
- server: "guild",
589
- channel: "channel",
590
- conversation: "channel",
591
- thread: "channel",
592
- post: "post",
593
- tweet: "post",
594
- status: "post",
595
- update: "post",
596
- topic: "topic",
597
- trend: "topic",
598
- };
599
-
600
- function isGenericBindingKey(key: string | undefined): boolean {
601
- if (!key) return true;
602
- return /^(id|ids|url|urls|page|cursor|offset|limit|slug(?:_\d+)?|pathname|domain|query|q|type|name)$/.test(key);
603
- }
604
-
605
- const PAGINATION_KEYS = new Set(["cursor", "page", "offset", "page_token", "next_cursor", "after", "before", "start", "next_page", "continuation_token", "skip", "from", "scroll_id"]);
606
- function isPaginationBindingKey(key: string): boolean {
607
- return PAGINATION_KEYS.has(key) || /^(next_|prev_|previous_)/.test(key) || /_cursor$/.test(key);
608
- }
609
-
610
- function classifyEdgeKind(source: SkillOperationNode, target: SkillOperationNode, bindingKey: string): SkillOperationEdge["kind"] {
611
- if (source.operation_id === target.operation_id && isPaginationBindingKey(bindingKey)) return "pagination";
612
- const LIST_ACTIONS = new Set(["list", "search", "timeline", "trending", "feed"]);
613
- const DETAIL_ACTIONS = new Set(["detail", "fetch"]);
614
- if (LIST_ACTIONS.has(source.action_kind) && DETAIL_ACTIONS.has(target.action_kind) && source.resource_kind === target.resource_kind && source.resource_kind !== "resource") return "parent_child";
615
- if (target.auth_required && /^(auth|login|token|session|oauth)$/.test(source.action_kind)) return "auth";
616
- return "dependency";
617
- }
618
-
619
- function isGenericSemanticType(type: string | undefined): boolean {
620
- if (!type) return true;
621
- return /^(identifier|input|resource|value|string|number|flag)$/.test(type);
622
- }
623
-
624
- function canonicalBindingEntity(entity?: string): string | undefined {
625
- if (!entity) return undefined;
626
- const normalized = singularize(entity.toLowerCase().replace(/[^a-z0-9_]+/g, "_"));
627
- return BINDING_ENTITY_ALIASES[normalized] ?? normalized;
628
- }
629
-
630
- function bindingValueKind(binding: OperationBinding): string | undefined {
631
- const semanticType = binding.semantic_type?.toLowerCase();
632
- const key = binding.key.toLowerCase();
633
- if (semanticType === "query_text" || /^(q|query|keyword|keywords|search_term)$/.test(key)) return "query";
634
- if (
635
- semanticType === "identifier" ||
636
- /_identifier$/.test(semanticType ?? "") ||
637
- /(^|_)(id|identifier|urn)$/.test(key) ||
638
- /^(public_identifier|entity_urn|rest_id)$/.test(key)
639
- ) return "identifier";
640
- if (/_name$/.test(semanticType ?? "") || /^(name|full_name|title)$/.test(key)) return "name";
641
- if (/_url$/.test(semanticType ?? "") || /^(url|link|canonical_url|path)$/.test(key)) return "url";
642
- if (/_option_value$/.test(semanticType ?? "") || /_value$/.test(key)) return "option_value";
643
- if (/_option$/.test(semanticType ?? "")) return "option";
644
- if (/_owner$/.test(semanticType ?? "") || /^(owner|owner_login|author|author_username|author_screen_name)$/.test(key)) return "owner";
645
- return undefined;
646
- }
647
-
648
- function bindingEntityKind(binding: OperationBinding): string | undefined {
649
- const semanticType = binding.semantic_type?.toLowerCase();
650
- if (semanticType && !isGenericSemanticType(semanticType)) {
651
- const semanticMatch = semanticType.match(/^(.*)_(identifier|name|url|owner|option|option_value)$/);
652
- if (semanticMatch) return canonicalBindingEntity(semanticMatch[1]);
653
- if (semanticType === "query_text") return "query";
654
- }
655
-
656
- const key = binding.key.toLowerCase();
657
- if (/^(public_identifier|profile_id|member_id|person_id|user_id|account_id|screen_name|username|handle)$/.test(key)) {
658
- return "profile";
659
- }
660
- if (/^(repo|repo_id|repository|repository_id|repository_name|owner|owner_login)$/.test(key)) {
661
- return "repository";
662
- }
663
- if (/^(company_id|organization_id|org_id|company_name|organization_name)$/.test(key)) {
664
- return "company";
665
- }
666
- if (/^(listing_id|item_id|product_id|listing_name|product_name)$/.test(key)) {
667
- return "listing";
668
- }
669
- if (/^(channel_id|conversation_id|thread_id|channel_name)$/.test(key)) {
670
- return "channel";
671
- }
672
- if (/^(guild_id|server_id|guild_name|server_name)$/.test(key)) {
673
- return "guild";
674
- }
675
- if (/^(post_id|tweet_id|status_id|update_id|post_url)$/.test(key)) {
676
- return "post";
677
- }
678
- if (/^(topic_id|topic_name|trend_id|trend_name)$/.test(key)) {
679
- return "topic";
680
- }
681
-
682
- const stripped = key
683
- .replace(/^(public|entity|canonical|selected|current)_/, "")
684
- .replace(/_(id|identifier|name|url|slug|urn|value|option|owner)$/, "");
685
- if (!stripped || isGenericBindingKey(stripped)) return undefined;
686
- return canonicalBindingEntity(stripped);
687
- }
688
-
689
- function bindingFamilyKey(binding: OperationBinding): string | undefined {
690
- const entity = bindingEntityKind(binding);
691
- const valueKind = bindingValueKind(binding);
692
- if (!entity || !valueKind) return undefined;
693
- return `${entity}:${valueKind}`;
694
- }
695
-
696
- function bindingLeafAliases(binding: OperationBinding): string[] {
697
- const key = binding.key.toLowerCase();
698
- const aliases = new Set<string>([key]);
699
- const entity = bindingEntityKind(binding);
700
- const valueKind = bindingValueKind(binding);
701
-
702
- if (valueKind === "identifier") {
703
- aliases.add("id");
704
- if (entity === "profile") {
705
- for (const alias of ["user_id", "profile_id", "member_id", "account_id", "public_identifier", "rest_id", "screen_name", "username", "handle"]) {
706
- aliases.add(alias);
707
- }
708
- }
709
- if (entity === "repository") {
710
- for (const alias of ["repo_id", "repository_id", "id"]) aliases.add(alias);
711
- }
712
- if (entity === "listing") {
713
- for (const alias of ["listing_id", "item_id", "product_id", "id"]) aliases.add(alias);
714
- }
715
- if (entity === "company") {
716
- for (const alias of ["company_id", "organization_id", "org_id", "id"]) aliases.add(alias);
717
- }
718
- }
719
-
720
- if (valueKind === "name") {
721
- aliases.add("name");
722
- aliases.add("title");
723
- }
724
-
725
- if (valueKind === "url") {
726
- aliases.add("url");
727
- aliases.add("link");
728
- aliases.add("canonical_url");
729
- }
730
-
731
- return [...aliases];
732
- }
733
-
734
- function normalizeObservedScalar(value: unknown): string | null {
735
- if (typeof value === "number") {
736
- return Number.isFinite(value) ? String(value) : null;
737
- }
738
- if (typeof value !== "string") return null;
739
- const trimmed = value.trim();
740
- if (!trimmed) return null;
741
- if (trimmed.length < 4 && !/^\d+$/.test(trimmed)) return null;
742
- const lowered = trimmed.toLowerCase();
743
- if (["true", "false", "null", "undefined", "nan"].includes(lowered)) return null;
744
- if (/^[a-z_]+$/i.test(trimmed) && trimmed.length < 8) return null;
745
- return /^\d+$/.test(trimmed) ? trimmed : lowered;
746
- }
747
-
748
- function collectBindingObservedValues(
749
- value: unknown,
750
- binding: OperationBinding,
751
- out = new Set<string>(),
752
- prefix = "",
753
- ): Set<string> {
754
- if (value == null) return out;
755
- if (Array.isArray(value)) {
756
- for (const item of value.slice(0, 8)) {
757
- collectBindingObservedValues(item, binding, out, `${prefix}[]`);
758
- }
759
- return out;
760
- }
761
- if (typeof value !== "object") {
762
- const normalized = normalizeObservedScalar(value);
763
- if (normalized && prefix) {
764
- const leaf = prefix.replace(/\[\]/g, "").split(".").pop()?.toLowerCase() ?? "";
765
- if (bindingLeafAliases(binding).includes(leaf)) out.add(normalized);
766
- }
767
- return out;
768
- }
769
-
770
- for (const [key, next] of Object.entries(value as Record<string, unknown>).slice(0, 24)) {
771
- const path = prefix ? `${prefix}.${key}` : key;
772
- collectBindingObservedValues(next, binding, out, path);
773
- }
774
- return out;
775
- }
776
-
777
- function hasObservedValueOverlap(
778
- source: SkillOperationNode,
779
- target: SkillOperationNode,
780
- provided: OperationBinding,
781
- required: OperationBinding,
782
- ): boolean {
783
- const sourceValues = collectBindingObservedValues(source.example_response_compact, provided);
784
- const targetValues = collectBindingObservedValues(target.example_request, required);
785
- if (sourceValues.size === 0 || targetValues.size === 0) return false;
786
- for (const value of sourceValues) {
787
- if (targetValues.has(value)) return true;
788
- }
789
- return false;
790
- }
791
-
792
- function observedValueMatchConfidence(
793
- source: SkillOperationNode,
794
- target: SkillOperationNode,
795
- provided: OperationBinding,
796
- required: OperationBinding,
797
- ): number {
798
- if (!hasObservedValueOverlap(source, target, provided, required)) return 0;
799
-
800
- let confidence = 0.72;
801
- const providedFamily = bindingFamilyKey(provided);
802
- const requiredFamily = bindingFamilyKey(required);
803
- if (providedFamily && requiredFamily && providedFamily === requiredFamily) confidence += 0.1;
804
-
805
- const sourceEntity = bindingEntityKind(provided);
806
- const targetEntity = bindingEntityKind(required);
807
- if (sourceEntity && targetEntity && sourceEntity === targetEntity) confidence += 0.06;
808
-
809
- if (source.resource_kind === target.resource_kind && source.resource_kind !== "resource") confidence += 0.05;
810
- if (provided.key === required.key && !isGenericBindingKey(required.key)) confidence += 0.04;
811
-
812
- return Math.min(confidence, 0.88);
813
- }
814
-
815
- function potentialBindingMatchConfidence(
816
- source: SkillOperationNode,
817
- target: SkillOperationNode,
818
- provided: OperationBinding,
819
- required: OperationBinding,
820
- ): number {
821
- const providedFamily = bindingFamilyKey(provided);
822
- const requiredFamily = bindingFamilyKey(required);
823
- if (!providedFamily || !requiredFamily || providedFamily !== requiredFamily) return 0;
824
-
825
- const entity = bindingEntityKind(required);
826
- const valueKind = bindingValueKind(required);
827
- if (!entity || !valueKind) return 0;
828
- if (isGenericBindingKey(required.key) && isGenericBindingKey(provided.key)) return 0;
829
-
830
- let confidence = 0.62;
831
- if (source.resource_kind === target.resource_kind && source.resource_kind !== "resource") confidence += 0.08;
832
- if (source.resource_kind === entity || target.resource_kind === entity) confidence += 0.05;
833
- if (source.method === "GET" && target.method === "GET") confidence += 0.03;
834
- return Math.min(confidence, 0.78);
835
- }
836
-
837
- function mergeBindings(primary: OperationBinding[] = [], secondary: OperationBinding[] = []): OperationBinding[] {
838
- const merged: OperationBinding[] = [];
839
- const seen = new Set<string>();
840
- for (const binding of [...primary, ...secondary]) {
841
- const id = bindingIdentity(binding);
842
- if (seen.has(id)) continue;
843
- seen.add(id);
844
- merged.push(binding);
845
- }
846
- return merged;
847
- }
848
-
849
- function semanticSupportScore(text: string, label?: string): number {
850
- if (!label) return -1;
851
- const tokens = unique(tokenize(label).map(singularize));
852
- if (tokens.length === 0) return -1;
853
- let score = 0;
854
- for (const token of tokens) {
855
- if (new RegExp(`\\b${token}\\b`).test(text)) score += 2;
856
- }
857
- return score;
858
- }
859
-
860
- function chooseSemanticKind(
861
- existing: string | undefined,
862
- inferred: string | undefined,
863
- text: string,
864
- genericKinds: Set<string>,
865
- ): string {
866
- if (!existing) return inferred ?? "";
867
- if (!inferred || existing === inferred) return existing;
868
-
869
- const existingLower = existing.toLowerCase();
870
- const inferredLower = inferred.toLowerCase();
871
- const existingGeneric = genericKinds.has(existingLower);
872
- const inferredGeneric = genericKinds.has(inferredLower);
873
-
874
- if (existingGeneric && !inferredGeneric) return inferred;
875
-
876
- const existingSupport = semanticSupportScore(text, existingLower);
877
- const inferredSupport = semanticSupportScore(text, inferredLower);
878
-
879
- if (inferredGeneric && !existingGeneric) {
880
- return existingSupport > inferredSupport ? existing : inferred;
881
- }
882
-
883
- if (inferredSupport !== existingSupport) return inferredSupport > existingSupport ? inferred : existing;
884
- return inferred;
885
- }
886
-
887
- export function inferEndpointSemantic(
888
- endpoint: EndpointDescriptor,
889
- opts?: {
890
- sampleResponse?: unknown;
891
- sampleRequest?: unknown;
892
- observedAt?: string;
893
- sampleRequestUrl?: string;
894
- },
895
- ): EndpointSemanticDescriptor {
896
- const fields = unique([
897
- ...summarizeSchemaFields(endpoint.response_schema),
898
- ...flattenFields(compactExample(opts?.sampleResponse ?? endpoint.semantic?.example_response_compact)),
899
- ]).slice(0, 20);
900
- const text = normalizeTokenText(`${semanticText(endpoint)} ${fields.join(" ")}`).toLowerCase();
901
- const actionKind = inferActionKind(text);
902
- const resourceKind = inferResourceKind(text, endpoint.url_template);
903
- const requires = inferRequires(endpoint);
904
- const provides = inferProvidesFromFields(fields, resourceKind);
905
- const negativeTags = inferNegativeTags(text);
906
- const generatedDescription = buildSemanticDescription(endpoint, actionKind, resourceKind, fields);
907
- const descriptionInput = classifyDescriptionInput(endpoint.description);
908
- const descriptionOut = descriptionInput.source === "agent"
909
- ? endpoint.description
910
- : generatedDescription;
911
- const descriptionIn = requires.length > 0
912
- ? `Requires ${requires.map((binding) => binding.key).join(", ")}`
913
- : "No additional inputs required";
914
- const descriptionSource: "agent" | "auto" | "missing" =
915
- descriptionInput.source === "agent"
916
- ? "agent"
917
- : (descriptionOut ? "auto" : "missing");
918
-
919
- return {
920
- action_kind: actionKind,
921
- resource_kind: resourceKind,
922
- description_in: descriptionIn,
923
- description_out: descriptionOut,
924
- description_source: descriptionSource,
925
- description_needs_review: descriptionSource !== "agent",
926
- ...(descriptionSource !== "agent"
927
- ? { description_warning: descriptionInput.warning ?? "Auto-generated description. Review before trusting or publishing." }
928
- : {}),
929
- response_summary: fields.slice(0, 8).join(", "),
930
- example_request: compactExample(opts?.sampleRequest),
931
- example_response_compact: compactExample(opts?.sampleResponse ?? endpoint.semantic?.example_response_compact),
932
- example_fields: fields,
933
- requires,
934
- provides,
935
- negative_tags: negativeTags,
936
- confidence: fields.length > 0 ? 0.8 : 0.4,
937
- observed_at: opts?.observedAt,
938
- sample_request_url: opts?.sampleRequestUrl,
939
- auth_required: !!(
940
- endpoint.auth_tokens?.length ||
941
- Object.keys(endpoint.headers_template ?? {}).some((h) => /auth|csrf|token|bearer/i.test(h))
942
- ),
943
- };
944
- }
945
- export function resolveEndpointSemantic(
946
- endpoint: EndpointDescriptor,
947
- opts?: {
948
- sampleResponse?: unknown;
949
- sampleRequest?: unknown;
950
- observedAt?: string;
951
- sampleRequestUrl?: string;
952
- },
953
- ): EndpointSemanticDescriptor {
954
- const existing = endpoint.semantic;
955
- const inferred = inferEndpointSemantic(endpoint, {
956
- sampleResponse: opts?.sampleResponse ?? existing?.example_response_compact,
957
- sampleRequest: opts?.sampleRequest ?? existing?.example_request,
958
- observedAt: opts?.observedAt ?? existing?.observed_at,
959
- sampleRequestUrl: opts?.sampleRequestUrl ?? existing?.sample_request_url,
960
- });
961
- const supportText = normalizeTokenText([
962
- endpoint.method,
963
- endpoint.url_template,
964
- endpoint.description ?? "",
965
- existing?.description_out ?? "",
966
- inferred.description_out ?? "",
967
- existing?.response_summary ?? "",
968
- inferred.response_summary ?? "",
969
- ...(existing?.example_fields ?? []),
970
- ...(inferred.example_fields ?? []),
971
- ].join(" ")).toLowerCase();
972
-
973
- return {
974
- ...existing,
975
- ...inferred,
976
- action_kind: chooseSemanticKind(existing?.action_kind, inferred.action_kind, supportText, new Set(["fetch"])),
977
- resource_kind: chooseSemanticKind(existing?.resource_kind, inferred.resource_kind, supportText, new Set(["resource"])),
978
- description_in: inferred.description_in || existing?.description_in,
979
- description_out: inferred.description_out || existing?.description_out,
980
- description_source: inferred.description_source || existing?.description_source,
981
- description_needs_review: inferred.description_needs_review ?? existing?.description_needs_review,
982
- description_warning: inferred.description_warning || existing?.description_warning,
983
- response_summary: inferred.response_summary || existing?.response_summary,
984
- example_request: opts?.sampleRequest ?? existing?.example_request ?? inferred.example_request,
985
- example_response_compact: opts?.sampleResponse ?? existing?.example_response_compact ?? inferred.example_response_compact,
986
- example_fields: unique([...(inferred.example_fields ?? []), ...(existing?.example_fields ?? [])]).slice(0, 20),
987
- requires: mergeBindings(existing?.requires, inferred.requires),
988
- provides: mergeBindings(existing?.provides, inferred.provides),
989
- negative_tags: [...(inferred.negative_tags ?? [])],
990
- confidence: Math.max(existing?.confidence ?? 0, inferred.confidence ?? 0),
991
- observed_at: opts?.observedAt ?? existing?.observed_at ?? inferred.observed_at,
992
- sample_request_url: opts?.sampleRequestUrl ?? existing?.sample_request_url ?? inferred.sample_request_url,
993
- auth_required: existing?.auth_required ?? inferred.auth_required ?? false,
994
- };
995
- }
996
-
997
- function buildOperationNode(endpoint: EndpointDescriptor): SkillOperationNode {
998
- const semantic = resolveEndpointSemantic(endpoint);
999
- const normalizedRequires = (() => {
1000
- const byBinding = new Map<string, OperationBinding>();
1001
- for (const binding of semantic.requires ?? []) {
1002
- const pathParamValue = (endpoint.path_params as Record<string, string> | undefined)?.[binding.key];
1003
- const defaultedPathParam =
1004
- binding.source === "path_params" &&
1005
- typeof pathParamValue === "string" && pathParamValue !== "";
1006
- const normalized = defaultedPathParam ? { ...binding, required: false } : binding;
1007
- const id = [normalized.key, normalized.source ?? "", normalized.semantic_type ?? ""].join("|");
1008
- const existing = byBinding.get(id);
1009
- if (!existing) {
1010
- byBinding.set(id, normalized);
1011
- continue;
1012
- }
1013
- byBinding.set(id, {
1014
- ...existing,
1015
- required: existing.required && normalized.required,
1016
- });
1017
- }
1018
- return [...byBinding.values()];
1019
- })();
1020
- return {
1021
- operation_id: endpoint.endpoint_id,
1022
- endpoint_id: endpoint.endpoint_id,
1023
- method: endpoint.method,
1024
- url_template: endpoint.url_template,
1025
- trigger_url: endpoint.trigger_url,
1026
- action_kind: semantic.action_kind,
1027
- resource_kind: semantic.resource_kind,
1028
- description_in: semantic.description_in,
1029
- description_out: semantic.description_out,
1030
- response_summary: semantic.response_summary,
1031
- requires: normalizedRequires,
1032
- provides: semantic.provides ?? [],
1033
- negative_tags: semantic.negative_tags ?? [],
1034
- example_request: semantic.example_request,
1035
- example_response_compact: semantic.example_response_compact,
1036
- example_fields: semantic.example_fields ?? [],
1037
- confidence: semantic.confidence ?? 0.5,
1038
- observed_at: semantic.observed_at,
1039
- auth_required: semantic.auth_required ?? false,
1040
- };
1041
- }
1042
-
1043
- function operationScore(op: SkillOperationNode, intent?: string): number {
1044
- if (!intent) return 0;
1045
- const intentTokens = tokenize(intent);
1046
- const opTokens = tokenize([
1047
- op.action_kind,
1048
- op.resource_kind,
1049
- op.description_out ?? "",
1050
- op.response_summary ?? "",
1051
- ...(op.example_fields ?? []),
1052
- ].join(" "));
1053
- let score = 0;
1054
- for (const token of intentTokens) if (opTokens.includes(singularize(token))) score += 2;
1055
- score -= operationSoftPenalty(op, intent);
1056
- return score;
1057
- }
1058
-
1059
- function intentHasAny(intent: string | undefined, patterns: string[]): boolean {
1060
- if (!intent) return false;
1061
- const lowered = intent.toLowerCase();
1062
- return patterns.some((pattern) => lowered.includes(pattern));
1063
- }
1064
-
1065
- function operationTextBlob(op: SkillOperationNode): string {
1066
- return [
1067
- op.method,
1068
- op.url_template,
1069
- op.trigger_url ?? "",
1070
- op.action_kind,
1071
- op.resource_kind,
1072
- op.description_in ?? "",
1073
- op.description_out ?? "",
1074
- op.response_summary ?? "",
1075
- ...(op.example_fields ?? []),
1076
- ...(op.negative_tags ?? []),
1077
- ].join(" ").toLowerCase();
1078
- }
1079
-
1080
- export function isOperationHardExcluded(op: SkillOperationNode, intent?: string): boolean {
1081
- const text = operationTextBlob(op);
1082
- const tags = new Set(op.negative_tags ?? []);
1083
- if (tags.has("telemetry") || tags.has("ads")) return true;
1084
- if (tags.has("experiment") && !intentHasAny(intent, ["experiment", "feature flag", "assignment"])) return true;
1085
- if (tags.has("auth") && !intentHasAny(intent, ["auth", "login", "session", "token", "csrf"])) return true;
1086
- if (tags.has("status") && !intentHasAny(intent, ["status", "health", "incident", "maintenance"])) return true;
1087
- if (tags.has("config") && !intentHasAny(intent, ["config", "setting", "settings", "preference", "preferences"])) return true;
1088
- if (/\b(intercom|ping|beacon|track|tracking|telemetry|metrics|log\.json|promoted_content)\b/.test(text)) return true;
1089
- return false;
1090
- }
1091
-
1092
- export function operationSoftPenalty(op: SkillOperationNode, intent?: string): number {
1093
- const text = operationTextBlob(op);
1094
- const tags = new Set(op.negative_tags ?? []);
1095
- let penalty = 0;
1096
- if (tags.has("helper")) penalty += 6;
1097
- if (tags.has("recommendation") && !intentHasAny(intent, ["recommend", "suggest", "sidebar"])) penalty += 7;
1098
- if (tags.has("settings") && !intentHasAny(intent, ["setting", "settings", "preference", "preferences"])) penalty += 8;
1099
- if (tags.has("messaging") && !intentHasAny(intent, ["message", "dm", "conversation", "mailbox", "inbox", "channel"])) penalty += 6;
1100
- if (tags.has("adjacent")) penalty += 6;
1101
- if (/\b(helper|recommendation|sidebar|badge(?:_count)?|notification(?:s)?|verifiedorg|subscription|preferences?|settings?)\b/.test(text)) penalty += 5;
1102
- return penalty;
1103
- }
1104
-
1105
- function parseObservedTime(value?: string): number | null {
1106
- if (!value) return null;
1107
- const trimmed = value.trim();
1108
- if (!trimmed) return null;
1109
- if (/^\d+$/.test(trimmed)) {
1110
- const numeric = Number(trimmed);
1111
- if (!Number.isFinite(numeric)) return null;
1112
- return trimmed.length <= 10 ? numeric * 1000 : numeric;
1113
- }
1114
- const parsed = new Date(trimmed).getTime();
1115
- return Number.isFinite(parsed) ? parsed : null;
1116
- }
1117
-
1118
- function isBefore(lhs?: string, rhs?: string): boolean {
1119
- const left = parseObservedTime(lhs);
1120
- const right = parseObservedTime(rhs);
1121
- if (left == null || right == null) return true;
1122
- return left <= right;
1123
- }
1124
-
1125
- export function buildSkillOperationGraph(endpoints: EndpointDescriptor[]): SkillOperationGraph {
1126
- const operations = endpoints.map(buildOperationNode);
1127
- const edges: SkillOperationEdge[] = [];
1128
- const seenEdges = new Set<string>();
1129
- for (const target of operations) {
1130
- for (const required of target.requires) {
1131
- for (const source of operations) {
1132
- if (source.operation_id === target.operation_id && !isPaginationBindingKey(required.key)) continue;
1133
- const directMatch = source.provides.find((provided) => {
1134
- const exactKeyMatch = provided.key === required.key && !isGenericBindingKey(required.key);
1135
- const semanticMatch =
1136
- !!provided.semantic_type &&
1137
- !!required.semantic_type &&
1138
- provided.semantic_type === required.semantic_type &&
1139
- !isGenericSemanticType(required.semantic_type);
1140
- const paginationSelfMatch =
1141
- source.operation_id === target.operation_id &&
1142
- provided.key === required.key &&
1143
- isPaginationBindingKey(required.key);
1144
- return exactKeyMatch || semanticMatch || paginationSelfMatch;
1145
- });
1146
- if (source.operation_id !== target.operation_id && !isBefore(source.observed_at, target.observed_at)) continue;
1147
- const potentialMatch = !directMatch
1148
- ? source.provides
1149
- .map((provided) => ({
1150
- provided,
1151
- confidence: potentialBindingMatchConfidence(source, target, provided, required),
1152
- }))
1153
- .filter((candidate) => candidate.confidence > 0)
1154
- .sort((a, b) => b.confidence - a.confidence)[0]
1155
- : undefined;
1156
- const observedValueMatch = source.provides
1157
- .map((provided) => ({
1158
- provided,
1159
- confidence: observedValueMatchConfidence(source, target, provided, required),
1160
- }))
1161
- .filter((candidate) => candidate.confidence > 0)
1162
- .sort((a, b) => b.confidence - a.confidence)[0];
1163
- const match = directMatch ?? observedValueMatch?.provided ?? potentialMatch?.provided;
1164
- if (!match) continue;
1165
- const edgeId = `${source.operation_id}:${target.operation_id}:${required.key}`;
1166
- if (seenEdges.has(edgeId)) continue;
1167
- seenEdges.add(edgeId);
1168
- const exactMatch = match.key === required.key;
1169
- const corroboratedHintConfidence =
1170
- observedValueMatch && (!directMatch || observedValueMatch.provided.key === directMatch.key)
1171
- ? observedValueMatch.confidence
1172
- : 0;
1173
- edges.push({
1174
- edge_id: edgeId,
1175
- from_operation_id: source.operation_id,
1176
- to_operation_id: target.operation_id,
1177
- binding_key: required.key,
1178
- kind: directMatch
1179
- ? (exactMatch ? classifyEdgeKind(source, target, required.key) : "hint")
1180
- : "hint",
1181
- confidence: directMatch
1182
- ? (exactMatch ? 0.9 : Math.max(0.6, corroboratedHintConfidence))
1183
- : (observedValueMatch?.confidence ?? potentialMatch?.confidence ?? 0.6),
1184
- });
1185
- }
1186
- }
1187
- }
1188
-
1189
- // Operations that are targets of dependency edges are not entry points
1190
- const dependencyTargets = new Set(
1191
- edges.filter((e) => e.kind === "dependency").map((e) => e.to_operation_id),
1192
- );
1193
- const entryOperationIds = operations
1194
- .filter(
1195
- (operation) =>
1196
- !dependencyTargets.has(operation.operation_id) &&
1197
- (operation.requires.length === 0 ||
1198
- operation.requires.every(
1199
- (binding) => binding.source === "query" || binding.source === "path_params",
1200
- )),
1201
- )
1202
- .map((operation) => operation.operation_id);
1203
-
1204
- return {
1205
- generated_at: new Date().toISOString(),
1206
- entry_operation_ids: entryOperationIds,
1207
- operations,
1208
- edges,
1209
- };
1210
- }
1211
-
1212
- export function ensureSkillOperationGraph(skill: SkillManifest): SkillOperationGraph {
1213
- if (skill.operation_graph?.operations?.length) {
1214
- // Rebuild if stored graph is stale (doesn't cover all endpoints)
1215
- const graphOpIds = new Set(skill.operation_graph.operations.map((op) => op.operation_id));
1216
- const allCovered = skill.endpoints.every((ep) => graphOpIds.has(ep.endpoint_id));
1217
- if (allCovered) return skill.operation_graph;
1218
- }
1219
- return buildSkillOperationGraph(skill.endpoints);
1220
- }
1221
-
1222
- export function knownBindingsFromInputs(
1223
- params: Record<string, unknown> = {},
1224
- contextUrl?: string,
1225
- ): Record<string, unknown> {
1226
- const known: Record<string, unknown> = { ...params };
1227
- if (!contextUrl) return known;
1228
- try {
1229
- const url = new URL(contextUrl);
1230
- known.url = contextUrl;
1231
- known.domain = url.hostname;
1232
- known.pathname = url.pathname;
1233
- let index = 1;
1234
- for (const seg of url.pathname.split("/").filter(Boolean)) {
1235
- known[`slug_${index++}`] = seg;
1236
- }
1237
- for (const [key, value] of url.searchParams.entries()) {
1238
- if (known[key] == null) known[key] = value;
1239
- const normalized = normalizeQueryBindingKey(key);
1240
- if (known[normalized] == null) known[normalized] = value;
1241
- }
1242
- } catch { /* ignore */ }
1243
- return known;
1244
- }
1245
-
1246
- export function isRunnable(operation: SkillOperationNode, bindings: Record<string, unknown>): boolean {
1247
- return operation.requires.every((binding) => {
1248
- if (!binding.required) return true;
1249
- const value = bindings[binding.key];
1250
- return value != null && value !== "";
1251
- });
1252
- }
1253
-
1254
- function isPrefetchableEdgeKind(kind: SkillOperationEdge["kind"]): boolean {
1255
- return kind === "dependency" || kind === "parent_child" || kind === "pagination";
1256
- }
1257
-
1258
- function buildEffectiveBindings(
1259
- operation: SkillOperationNode,
1260
- knownBindings: Record<string, unknown>,
1261
- ): Record<string, unknown> {
1262
- const effectiveBindings: Record<string, unknown> = { ...knownBindings };
1263
- for (const binding of operation.provides) {
1264
- if (effectiveBindings[binding.key] == null) {
1265
- effectiveBindings[binding.key] = binding.example_value ?? `__from_${operation.operation_id}__`;
1266
- }
1267
- }
1268
- return effectiveBindings;
1269
- }
1270
-
1271
- export function getOperationPrefetchTargets(
1272
- graph: SkillOperationGraph,
1273
- resolvedOperationId: string,
1274
- knownBindings: Record<string, unknown>,
1275
- limit = 3,
1276
- ): Array<{
1277
- operation: SkillOperationNode;
1278
- edge: SkillOperationEdge;
1279
- reason: string;
1280
- }> {
1281
- const resolvedOperation = graph.operations.find((operation) => operation.operation_id === resolvedOperationId);
1282
- if (!resolvedOperation) return [];
1283
-
1284
- const effectiveBindings = buildEffectiveBindings(resolvedOperation, knownBindings);
1285
- const candidates: Array<{
1286
- operation: SkillOperationNode;
1287
- edge: SkillOperationEdge;
1288
- reason: string;
1289
- }> = [];
1290
-
1291
- for (const edge of graph.edges) {
1292
- if (edge.from_operation_id !== resolvedOperationId) continue;
1293
- if (!isPrefetchableEdgeKind(edge.kind)) continue;
1294
-
1295
- const targetOperation = graph.operations.find((operation) => operation.operation_id === edge.to_operation_id);
1296
- if (!targetOperation) continue;
1297
- if (targetOperation.method !== "GET") continue;
1298
- if (!isRunnable(targetOperation, effectiveBindings)) continue;
1299
-
1300
- candidates.push({
1301
- operation: targetOperation,
1302
- edge,
1303
- reason: `${resolvedOperation.action_kind} ${resolvedOperation.resource_kind} -> ${targetOperation.action_kind} ${targetOperation.resource_kind} via ${edge.binding_key}`,
1304
- });
1305
- }
1306
-
1307
- return candidates
1308
- .sort((a, b) => b.edge.confidence - a.edge.confidence)
1309
- .slice(0, Math.max(0, limit));
1310
- }
1311
-
1312
- /**
1313
- * Compute the set of reachable operation IDs given current known bindings.
1314
- *
1315
- * An operation is reachable (A_reachable) if:
1316
- * 1. It has no required bindings (entry point), OR
1317
- * 2. All its required bindings are present in knownBindings, OR
1318
- * 3. All its required bindings can be transitively satisfied — either
1319
- * directly from knownBindings or from the provides of another
1320
- * reachable operation.
1321
- *
1322
- * Uses a fixpoint computation: starts with directly-runnable operations,
1323
- * then iteratively adds operations whose requirements are met by the
1324
- * accumulated provides of the reachable set, until no new operations
1325
- * are added.
1326
- */
1327
- export function computeReachableEndpoints(
1328
- graph: SkillOperationGraph,
1329
- knownBindings: Record<string, unknown>,
1330
- ): Set<string> {
1331
- const reachable = new Set<string>();
1332
- if (!graph.operations || graph.operations.length === 0) return reachable;
1333
-
1334
- // Seed: operations that are directly runnable with current bindings
1335
- for (const op of graph.operations) {
1336
- if (isRunnable(op, knownBindings)) {
1337
- reachable.add(op.operation_id);
1338
- }
1339
- }
1340
-
1341
- // Fixpoint expansion: iterate until stable
1342
- let changed = true;
1343
- while (changed) {
1344
- changed = false;
1345
- // Collect all binding keys provided by currently reachable operations
1346
- const availableKeys = new Set<string>(Object.keys(knownBindings));
1347
- for (const op of graph.operations) {
1348
- if (!reachable.has(op.operation_id)) continue;
1349
- for (const provided of op.provides) {
1350
- availableKeys.add(provided.key);
1351
- }
1352
- }
1353
-
1354
- // Check each non-reachable operation
1355
- for (const op of graph.operations) {
1356
- if (reachable.has(op.operation_id)) continue;
1357
- const allSatisfied = op.requires.every((binding) => {
1358
- if (!binding.required) return true;
1359
- // Check direct bindings first
1360
- const directValue = knownBindings[binding.key];
1361
- if (directValue != null && directValue !== "") return true;
1362
- // Check if any reachable operation provides this key
1363
- return availableKeys.has(binding.key);
1364
- });
1365
- if (allSatisfied) {
1366
- reachable.add(op.operation_id);
1367
- changed = true;
1368
- }
1369
- }
1370
- }
1371
-
1372
- return reachable;
1373
- }
1374
-
1375
- export function getSkillChunk(
1376
- skill: SkillManifest,
1377
- opts?: {
1378
- intent?: string;
1379
- seed_operation_id?: string;
1380
- known_bindings?: Record<string, unknown>;
1381
- max_operations?: number;
1382
- include_full_relevant_graph?: boolean;
1383
- },
1384
- ): SkillChunk {
1385
- const graph = ensureSkillOperationGraph(skill);
1386
- const known = opts?.known_bindings ?? {};
1387
- const filtered = graph.operations.filter((operation) => !isOperationHardExcluded(operation, opts?.intent));
1388
- const candidateOps = filtered.length > 0 ? filtered : graph.operations;
1389
- const maxOperations = opts?.include_full_relevant_graph
1390
- ? Math.max(1, candidateOps.length)
1391
- : (opts?.max_operations ?? 6);
1392
- const scored = [...candidateOps].sort((a, b) => operationScore(b, opts?.intent) - operationScore(a, opts?.intent));
1393
- const seedIds = opts?.seed_operation_id
1394
- ? [opts.seed_operation_id]
1395
- : scored.slice(0, Math.max(1, Math.min(3, scored.length))).map((op) => op.operation_id);
1396
- const queue = [...seedIds];
1397
- const seen = new Set<string>(seedIds);
1398
- while (queue.length > 0 && seen.size < maxOperations) {
1399
- const current = queue.shift()!;
1400
- for (const edge of graph.edges) {
1401
- if (edge.from_operation_id !== current && edge.to_operation_id !== current) continue;
1402
- const neighbor = edge.from_operation_id === current ? edge.to_operation_id : edge.from_operation_id;
1403
- if (seen.has(neighbor)) continue;
1404
- seen.add(neighbor);
1405
- queue.push(neighbor);
1406
- if (seen.size >= maxOperations) break;
1407
- }
1408
- }
1409
- const operations = graph.operations.filter((operation) => seen.has(operation.operation_id) && !isOperationHardExcluded(operation, opts?.intent));
1410
- const edges = graph.edges.filter((edge) => seen.has(edge.from_operation_id) && seen.has(edge.to_operation_id));
1411
- const visibleOperations = operations.length > 0 ? operations : graph.operations.filter((operation) => seen.has(operation.operation_id));
1412
- const availableOperationIds = operations
1413
- .filter((operation) => isRunnable(operation, known))
1414
- .sort((a, b) => operationScore(b, opts?.intent) - operationScore(a, opts?.intent))
1415
- .map((operation) => operation.operation_id);
1416
- const missingBindings = unique(
1417
- visibleOperations.flatMap((operation) =>
1418
- operation.requires
1419
- .filter((binding) => binding.required && (known[binding.key] == null || known[binding.key] === ""))
1420
- .map((binding) => binding.key)
1421
- )
1422
- );
1423
- return {
1424
- skill_id: skill.skill_id,
1425
- intent: opts?.intent,
1426
- available_operation_ids: availableOperationIds,
1427
- missing_bindings: missingBindings,
1428
- operations: visibleOperations,
1429
- edges,
1430
- };
1431
- }
1432
-
1433
- function summarizeBindingKeys(bindings: OperationBinding[] | undefined): string[] {
1434
- return unique((bindings ?? []).map((binding) => binding.key));
1435
- }
1436
-
1437
- function readableOperationTitle(operation: SkillOperationNode): string {
1438
- const action = operation.action_kind.replace(/_/g, " ");
1439
- const resource = operation.resource_kind.replace(/_/g, " ");
1440
- return `${action} ${resource}`.trim();
1441
- }
1442
-
1443
- function toAgentAvailableOperation(operation: SkillOperationNode): AgentAvailableOperation {
1444
- const required = summarizeBindingKeys(operation.requires);
1445
- const yields = summarizeBindingKeys(operation.provides);
1446
- return {
1447
- operation_id: operation.operation_id,
1448
- method: operation.method,
1449
- action_kind: operation.action_kind,
1450
- resource_kind: operation.resource_kind,
1451
- title: readableOperationTitle(operation),
1452
- why_available: required.length === 0
1453
- ? "Runnable now; no missing dependencies."
1454
- : `Runnable now; required bindings already known: ${required.join(", ")}.`,
1455
- url_template: operation.url_template,
1456
- requires: required,
1457
- yields,
1458
- example_request: operation.example_request,
1459
- example_response_compact: operation.example_response_compact,
1460
- };
1461
- }
1462
-
1463
- function toAgentPrefetchOperation(
1464
- target: { operation: SkillOperationNode; edge: SkillOperationEdge; reason: string },
1465
- ): AgentPrefetchOperation {
1466
- return {
1467
- operation_id: target.operation.operation_id,
1468
- endpoint_id: target.operation.endpoint_id,
1469
- method: target.operation.method,
1470
- action_kind: target.operation.action_kind,
1471
- resource_kind: target.operation.resource_kind,
1472
- reason: target.reason,
1473
- binding_key: target.edge.binding_key,
1474
- edge_kind: target.edge.kind,
1475
- confidence: target.edge.confidence,
1476
- };
1477
- }
1478
-
1479
- export function toAgentWorkflowDagView(
1480
- chunk: SkillChunk,
1481
- graph: SkillOperationGraph,
1482
- knownBindings: Record<string, unknown> = {},
1483
- ): AgentWorkflowDagView {
1484
- const runnableOperationIds = new Set(chunk.available_operation_ids);
1485
- const operations: AgentWorkflowDagOperation[] = chunk.operations.map((operation) => ({
1486
- operation_id: operation.operation_id,
1487
- endpoint_id: operation.endpoint_id,
1488
- method: operation.method,
1489
- action_kind: operation.action_kind,
1490
- resource_kind: operation.resource_kind,
1491
- title: readableOperationTitle(operation),
1492
- url_template: operation.url_template,
1493
- description_out: operation.description_out,
1494
- requires: summarizeBindingKeys(operation.requires),
1495
- yields: summarizeBindingKeys(operation.provides),
1496
- runnable: runnableOperationIds.has(operation.operation_id),
1497
- prefetch_get_operations: getOperationPrefetchTargets(graph, operation.operation_id, knownBindings)
1498
- .filter((target) => chunk.operations.some((candidate) => candidate.operation_id === target.operation.operation_id))
1499
- .map(toAgentPrefetchOperation),
1500
- }));
1501
-
1502
- return {
1503
- skill_id: chunk.skill_id,
1504
- intent: chunk.intent,
1505
- missing_bindings: chunk.missing_bindings,
1506
- suggested_next_operation_id: chunk.available_operation_ids[0],
1507
- operations,
1508
- edges: chunk.edges.map((edge) => ({
1509
- edge_id: edge.edge_id,
1510
- from_operation_id: edge.from_operation_id,
1511
- to_operation_id: edge.to_operation_id,
1512
- binding_key: edge.binding_key,
1513
- kind: edge.kind,
1514
- confidence: edge.confidence,
1515
- })),
1516
- };
1517
- }
1518
-
1519
- export function toAgentSkillChunkView(chunk: SkillChunk): AgentSkillChunkView {
1520
- const availableOperations = chunk.available_operation_ids
1521
- .map((operationId) => chunk.operations.find((operation) => operation.operation_id === operationId))
1522
- .filter((operation): operation is SkillOperationNode => !!operation)
1523
- .map(toAgentAvailableOperation);
1524
-
1525
- return {
1526
- skill_id: chunk.skill_id,
1527
- intent: chunk.intent,
1528
- missing_bindings: chunk.missing_bindings,
1529
- suggested_next_operation_id: availableOperations[0]?.operation_id,
1530
- available_operations: availableOperations,
1531
- };
1532
- }