@mastra/factory 0.26.0-alpha.3 → 0.27.0-alpha.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 (41) hide show
  1. package/README.md +10 -0
  2. package/dist/factory.d.ts.map +1 -1
  3. package/dist/factory.js +7 -3
  4. package/dist/factory.js.map +1 -1
  5. package/dist/integrations/gitlab/default-rules.d.ts +1 -1
  6. package/dist/integrations/gitlab/default-rules.d.ts.map +1 -1
  7. package/dist/routes/contracts.d.ts +54 -1
  8. package/dist/routes/contracts.d.ts.map +1 -1
  9. package/dist/routes/contracts.js +54 -1
  10. package/dist/routes/contracts.js.map +1 -1
  11. package/dist/routes/knowledge.d.ts +12 -228
  12. package/dist/routes/knowledge.d.ts.map +1 -1
  13. package/dist/routes/knowledge.js +207 -1045
  14. package/dist/routes/knowledge.js.map +1 -1
  15. package/dist/routes/skills.d.ts +9 -0
  16. package/dist/routes/skills.d.ts.map +1 -1
  17. package/dist/routes/skills.js +145 -4
  18. package/dist/routes/skills.js.map +1 -1
  19. package/dist/routes/surface.d.ts +2 -0
  20. package/dist/routes/surface.d.ts.map +1 -1
  21. package/dist/routes/surface.js +7 -5
  22. package/dist/routes/surface.js.map +1 -1
  23. package/dist/session/org-seed.d.ts +1 -1
  24. package/dist/session/org-seed.js.map +1 -1
  25. package/dist/skills/catalog.d.ts +28 -3
  26. package/dist/skills/catalog.d.ts.map +1 -1
  27. package/dist/skills/catalog.js +51 -8
  28. package/dist/skills/catalog.js.map +1 -1
  29. package/dist/storage/domains/audit/actions.d.ts +1 -0
  30. package/dist/storage/domains/audit/actions.d.ts.map +1 -1
  31. package/dist/storage/domains/audit/actions.js +2 -1
  32. package/dist/storage/domains/audit/actions.js.map +1 -1
  33. package/dist/storage/domains/skill-overrides/base.d.ts +56 -0
  34. package/dist/storage/domains/skill-overrides/base.d.ts.map +1 -0
  35. package/dist/storage/domains/skill-overrides/base.js +157 -0
  36. package/dist/storage/domains/skill-overrides/base.js.map +1 -0
  37. package/dist/workspace.d.ts +13 -1
  38. package/dist/workspace.d.ts.map +1 -1
  39. package/dist/workspace.js +94 -17
  40. package/dist/workspace.js.map +1 -1
  41. package/package.json +12 -12
@@ -1,1126 +1,288 @@
1
1
  import { Route } from "./route.js";
2
2
  import { registerApiRoute } from "@mastra/core/server";
3
- import { KnowledgeUnsupportedCapabilityError, canonicalizeKnowledgeScope, isKnowledgeScopeVisible, knowledgeScopeKey, parseKnowledgeWikilinks } from "@mastra/core/storage";
3
+ import { KnowledgeDeclarationError, listKnowledgeTreeChildren, readKnowledgePage, readKnowledgePageActivity, readKnowledgePageGraph, readKnowledgeScopeGrants, searchKnowledgeExplorerPages } from "@mastra/core/knowledge";
4
+ import { streamSSE } from "hono/streaming";
4
5
  // src/routes/knowledge.ts
5
- /** Reserved node that anchors pinned records (see subconscious/pinned.ts). */
6
- const PINNED_NODE_NAME = "pinned";
7
- /** Hover-card budget for record text shipped in the graph payload. */
8
- const RECORD_TEXT_LIMIT = 240;
9
- function truncateRecordText(text) {
10
- return text.length > RECORD_TEXT_LIMIT ? `${text.slice(0, 239)}…` : text;
11
- }
12
6
  const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
13
- /** Authorized visible events returned per activity page. */
14
- const ACTIVITY_PAGE_SIZE = 25;
15
- /** Events fetched per `listActivity` batch while filling a visible page. */
16
- const ACTIVITY_BATCH = 100;
17
- /** Hard scan cap so a huge hidden backlog cannot spin the request. */
18
- const ACTIVITY_SCAN_CAP = 1e3;
19
- /** Maximum visible nodes inspected for non-prefix name matches. */
20
- const SEARCH_SCAN_CAP = 1e3;
21
- /** Compact result window returned to the search popover. */
22
- const SEARCH_RESULT_LIMIT = 20;
23
- /** Prevent an unbounded query string from reaching storage. */
7
+ /** Ids and cursors are opaque, but bounded so an unbounded query string never reaches storage. */
8
+ const ID_LIMIT = 256;
24
9
  const SEARCH_QUERY_LIMIT = 128;
25
- /** Scope nodes returned per parent while lazily expanding the tree. */
26
- const SCOPE_PAGE_SIZE = 25;
27
- /** Bound storage pressure while calculating direct-member counts. */
28
- const SCOPE_COUNT_CONCURRENCY = 8;
29
- const DEFAULT_LIMITS = {
30
- maxNodes: 500,
31
- maxRecords: 2e3,
32
- maxFallbackLookups: 100,
33
- maxOrgScopePages: 10
34
- };
35
- function loose(c) {
36
- return c;
37
- }
38
- function deepestRung(scope) {
39
- let rung = "org";
40
- for (const entry of scope) {
41
- const ns = entry.slice(0, entry.indexOf(":"));
42
- if (ns === "thread") return "thread";
43
- if (ns === "resource") rung = "resource";
44
- }
45
- return rung;
46
- }
10
+ const MAX_PAGE_LIMIT = 100;
11
+ const MAX_GRAPH_PAGES = 500;
12
+ /** Comment frames only: proxies drop an idle stream. */
13
+ const EVENTS_KEEPALIVE_MS = 25e3;
47
14
  /**
48
- * True when `scope` is a prefix of the active view scope — the content lives
49
- * inside the current org + project boundary. Structural member lenses use
50
- * this to keep sibling-project knowledge out of a project-scoped view.
15
+ * The read scope is resolved when the stream opens. Closing it after this long makes the browser reconnect,
16
+ * which re-checks membership and the read scope, so a revoked member stops hearing about changes.
51
17
  */
52
- function withinViewBoundary(scope, viewScope) {
53
- return scope.length <= viewScope.length && scope.every((entry, index) => entry === viewScope[index]);
54
- }
55
- function directScopeMemberCounts({ members, hasMore }, childScopeCount, viewScope, maxNodes) {
56
- const contentNodeCount = members.filter((member) => !member.isScope && Array.isArray(member.scope) && withinViewBoundary(member.scope, viewScope)).length;
57
- const directMemberCount = childScopeCount + contentNodeCount;
58
- return {
59
- memberCount: Math.min(directMemberCount, maxNodes),
60
- memberCountTruncated: directMemberCount > maxNodes || hasMore,
61
- contentNodeCount,
62
- childScopeCount
63
- };
18
+ const EVENTS_MAX_AGE_MS = 3e5;
19
+ function boundedId(value) {
20
+ if (value === void 0) return void 0;
21
+ const trimmed = value.trim();
22
+ return trimmed && trimmed.length <= ID_LIMIT ? trimmed : void 0;
64
23
  }
65
- function compareScopeNodes(a, b) {
66
- return a.name.localeCompare(b.name) || a.id.localeCompare(b.id);
24
+ function boundedLimit(value, max) {
25
+ if (value === void 0) return void 0;
26
+ const parsed = Number(value);
27
+ return Number.isInteger(parsed) && parsed >= 1 && parsed <= max ? parsed : null;
67
28
  }
68
29
  /**
69
- * Scopes in one org (the org scope and everything beneath it), filtered and paged in storage.
70
- * Reads at most `maxPages` pages; `truncated` is true when scopes remain past that point.
30
+ * The ids of a change this caller may see, or null when they may see none of it. Events carry ids only, so
31
+ * readability is checked against the store now: a page moved out of reach is withheld, but the scope it
32
+ * left still tells the caller to refresh.
71
33
  */
72
- async function listOrgScopeNodes(store, orgId, maxPages) {
73
- const scopes = [];
74
- let cursor;
75
- for (let page = 0; page < maxPages; page += 1) {
76
- const result = await store.listScopeNodes({
77
- withinAddress: `org:${orgId}`,
78
- cursor
79
- });
80
- scopes.push(...result.scopes);
81
- if (!result.nextCursor) return {
82
- scopes,
83
- truncated: false
84
- };
85
- cursor = result.nextCursor;
86
- }
34
+ async function visibleChange(store, read, event) {
35
+ const readable = async (id) => id !== void 0 && (read === "all" || await store.getPage({
36
+ id,
37
+ read
38
+ }) !== null);
39
+ const scopeId = "scopeId" in event ? event.scopeId : void 0;
40
+ const fromScopeId = "fromScopeId" in event ? event.fromScopeId : void 0;
41
+ const [page, scope, fromScope] = await Promise.all([
42
+ readable(event.pageId),
43
+ readable(scopeId),
44
+ readable(fromScopeId)
45
+ ]);
46
+ if (!page && !scope && !fromScope) return null;
87
47
  return {
88
- scopes,
89
- truncated: true
48
+ kind: event.kind,
49
+ op: event.op,
50
+ ...page ? { pageId: event.pageId } : {},
51
+ ...scope ? { scopeId } : {},
52
+ at: event.at.toISOString()
90
53
  };
91
54
  }
92
- /** One scope node, only if it is in the org. Independent of how many scopes the org has. */
93
- async function findOrgScopeNode(store, orgId, scopeNodeId) {
94
- const { scopes } = await store.listScopeNodes({
95
- withinAddress: `org:${orgId}`,
96
- ids: [scopeNodeId],
97
- limit: 1
98
- });
99
- return scopes[0];
100
- }
101
- function knowledgeSearchRank(name, query) {
102
- const normalized = name.toLocaleLowerCase();
103
- if (normalized === query) return 0;
104
- if (normalized.startsWith(query)) return 1;
105
- return 2;
106
- }
107
55
  /**
108
- * What a scope node is, for labels: the rung name for vouched identity scopes, otherwise the
109
- * stored kind, or "topic" for structural scopes created without one. Matches the scope list.
56
+ * Adds a scope page's declared `displayLabel` with the address's `$params` filled in (`'$orgId policy'`
57
+ * → `'acme policy'`); declarations live in config, not storage.
110
58
  */
111
- function scopeKindLabel(address, kind) {
112
- if (address.startsWith("org:")) return "org";
113
- if (address.startsWith("resource:")) return "project";
114
- if (address.startsWith("thread:")) return "session";
115
- return kind || "topic";
116
- }
117
- /** The thread id of a session (`thread:<id>`) scope node, or undefined for any other scope. */
118
- function sessionThreadId(node) {
119
- return node.address.startsWith("thread:") ? boundedThreadId(node.address.slice(7)) : void 0;
59
+ function withDisplayLabel(knowledge, page) {
60
+ if (!page.isScope || !page.address) return page;
61
+ const displayLabel = knowledge.scopeLabel(page.address);
62
+ return displayLabel ? {
63
+ ...page,
64
+ displayLabel
65
+ } : page;
120
66
  }
121
- function boundedThreadId(raw) {
122
- if (!raw) return void 0;
123
- const trimmed = raw.trim();
124
- return trimmed.length > 0 && trimmed.length <= 512 ? trimmed : void 0;
67
+ function loose(c) {
68
+ return c;
125
69
  }
126
- /**
127
- * In-record + capped-fallback wikilink resolver, shared by both endpoints.
128
- * Resolution uses the store's own algorithm: a descending-prefix walk over the
129
- * record's canonical scope matching canonical name + exact scope key at each
130
- * prefix, so an edge never depends on whether the target landed in the window.
131
- */
132
- var WikilinkResolver = class {
133
- /** exact `${scopeKey}\u0000${lowerName}` → node, from the fetched window. */
134
- #inWindow = /* @__PURE__ */ new Map();
135
- #windowIds = /* @__PURE__ */ new Set();
136
- /** `${recordScopeKey}\u0000${lowerName}` → fallback result (null = dangling). */
137
- #fallbackCache = /* @__PURE__ */ new Map();
138
- #fallbackLookups = 0;
139
- #store;
140
- #maxFallbackLookups;
141
- outOfWindow = /* @__PURE__ */ new Map();
142
- cappedNames = [];
143
- #cappedSeen = /* @__PURE__ */ new Set();
144
- constructor(store, nodes, maxFallbackLookups) {
145
- this.#store = store;
146
- this.#maxFallbackLookups = maxFallbackLookups;
147
- for (const node of nodes) {
148
- this.#inWindow.set(`${knowledgeScopeKey(node.scope)}\u0000${node.name.trim().toLocaleLowerCase()}`, node);
149
- this.#windowIds.add(node.id);
150
- }
151
- }
152
- inWindowId(id) {
153
- return this.#windowIds.has(id);
154
- }
155
- /** Resolve a wikilink name from a knowledge record's scope. Returns the node or null (dangling/capped). */
156
- async resolve(name, recordScope) {
157
- const canonical = canonicalizeKnowledgeScope(recordScope);
158
- const lower = name.trim().toLocaleLowerCase();
159
- for (let length = canonical.length; length > 0; length--) {
160
- const hit = this.#inWindow.get(`${knowledgeScopeKey(canonical.slice(0, length))}\u0000${lower}`);
161
- if (hit) return hit;
162
- }
163
- const cacheKey = `${knowledgeScopeKey(canonical)}\u0000${lower}`;
164
- if (this.#fallbackCache.has(cacheKey)) return this.#trackOutOfWindow(this.#fallbackCache.get(cacheKey) ?? null);
165
- if (this.#fallbackLookups >= this.#maxFallbackLookups) {
166
- if (!this.#cappedSeen.has(lower) && this.cappedNames.length < 100) {
167
- this.#cappedSeen.add(lower);
168
- this.cappedNames.push(name.trim());
169
- } else if (!this.#cappedSeen.has(lower)) this.#cappedSeen.add(lower);
170
- return null;
171
- }
172
- this.#fallbackLookups += 1;
173
- let resolved = null;
174
- try {
175
- resolved = await this.#store.resolveNode({
176
- name,
177
- scope: canonical
178
- });
179
- } catch {
180
- resolved = null;
181
- }
182
- this.#fallbackCache.set(cacheKey, resolved);
183
- return this.#trackOutOfWindow(resolved);
184
- }
185
- #trackOutOfWindow(node) {
186
- if (node && !this.#windowIds.has(node.id)) this.outOfWindow.set(node.id, {
187
- id: node.id,
188
- name: node.name,
189
- scope: node.scope,
190
- rung: deepestRung(node.scope)
191
- });
192
- return node;
193
- }
194
- get cappedCount() {
195
- return this.#cappedSeen.size;
196
- }
197
- };
198
70
  var KnowledgeRoutes = class extends Route {
199
- #limits;
200
- constructor(deps) {
201
- super(deps);
202
- this.#limits = {
203
- ...DEFAULT_LIMITS,
204
- ...deps.limits
205
- };
206
- }
207
- /** Resolve the `(orgId, userId)` tenant or a ready-to-return error response. */
208
- async #resolveTenant(c) {
71
+ /** Tenant, org-owned project, Knowledge runtime and the caller's read scope: the one seam every route shares. */
72
+ async #resolveView(c) {
209
73
  await this.deps.auth.ensureUser(c);
210
74
  const tenant = this.deps.auth.tenant(c);
211
75
  if (!tenant) return { response: c.json({ error: "unauthorized" }, 401) };
212
76
  if (!tenant.orgId) return { response: c.json({
213
77
  error: "organization_required",
214
- message: "The knowledge graph requires an organization."
78
+ message: "Knowledge requires an organization."
215
79
  }, 403) };
216
- return {
217
- orgId: tenant.orgId,
218
- userId: tenant.userId
219
- };
220
- }
221
- /**
222
- * Resolve tenant + org-owned project + knowledge store + the active view's
223
- * query scope. The ONE seam both endpoints share, so the default/thread view
224
- * scope and the pin rungs cannot drift between them.
225
- *
226
- * threadId validation runs a single `listRecordsBySource` lookup with
227
- * `limit: 1` AT THE CANDIDATE SCOPE `[org, resource, thread:<id>]` — the
228
- * store's own visibility predicate is the authorization: the thread's own
229
- * records (equal scope key) and its project/org captures (prefix) match, while
230
- * a cross-org thread's records match nothing → zero rows → 404.
231
- */
232
- async #resolveView(c) {
233
- const tenant = await this.#resolveTenant(c);
234
- if ("response" in tenant) return tenant;
235
80
  const projectId = c.req.param("id");
236
81
  if (!projectId || !UUID_RE.test(projectId)) return { response: c.json({ error: "Project not found" }, 404) };
237
- const { projects } = this.deps;
238
- await projects.ensureReady();
239
- const project = await projects.get({
82
+ await this.deps.projects.ensureReady();
83
+ if (!await this.deps.projects.get({
240
84
  orgId: tenant.orgId,
241
85
  id: projectId
242
- });
243
- if (!project) return { response: c.json({ error: "Project not found" }, 404) };
86
+ })) return { response: c.json({ error: "Project not found" }, 404) };
244
87
  let knowledge;
245
88
  let store;
246
89
  try {
247
- const key = this.deps.defaultKnowledgeKey ?? "default";
248
- knowledge = await this.deps.knowledge(key);
90
+ knowledge = await this.deps.knowledge(this.deps.defaultKnowledgeKey ?? "default");
249
91
  store = knowledge ? await knowledge.getStorage() : void 0;
250
92
  } catch {
251
93
  store = void 0;
252
94
  }
253
- if (!store || !knowledge) return { response: c.json({
95
+ if (!knowledge || !store) return { response: c.json({
254
96
  error: "knowledge_unavailable",
255
97
  message: "The configured Knowledge runtime is unavailable."
256
98
  }, 503) };
257
- const defaultScope = [`org:${tenant.orgId}`, `resource:${projectId}`];
258
- const resourceRungScope = defaultScope;
259
- const threadId = boundedThreadId(c.req.query("threadId"));
260
- if (c.req.query("threadId") !== void 0 && !threadId) return { response: c.json({ error: "thread_not_found" }, 404) };
261
- if (!threadId) return {
262
- ...tenant,
263
- factoryProjectId: projectId,
264
- factoryProjectName: project.name,
265
- knowledge,
266
- store,
267
- view: "project",
268
- scope: defaultScope,
269
- pinRungs: [{
270
- rung: "resource",
271
- scope: resourceRungScope
272
- }]
273
- };
274
- const candidateScope = [...defaultScope, `thread:${threadId}`];
275
- if ((await store.knowledgeBySource({
276
- sourceThreadId: threadId,
277
- scope: candidateScope,
278
- limit: 1
279
- })).records.length === 0) return { response: c.json({ error: "thread_not_found" }, 404) };
280
- return {
281
- ...tenant,
282
- factoryProjectId: projectId,
283
- factoryProjectName: project.name,
284
- knowledge,
285
- store,
286
- view: "thread",
287
- threadId,
288
- scope: candidateScope,
289
- pinRungs: [{
290
- rung: "resource",
291
- scope: resourceRungScope
292
- }, {
293
- rung: "thread",
294
- scope: candidateScope
295
- }]
296
- };
297
- }
298
- #selectedView(view, level) {
299
- const projectView = {
300
- orgId: view.orgId,
301
- userId: view.userId,
302
- factoryProjectId: view.factoryProjectId,
303
- factoryProjectName: view.factoryProjectName,
304
- knowledge: view.knowledge,
305
- store: view.store,
306
- view: "project"
307
- };
308
- if (level === "org") return {
309
- ...projectView,
310
- scope: view.scope.slice(0, 1),
311
- pinRungs: []
312
- };
313
- if (level === "resource") return {
314
- ...projectView,
315
- scope: view.scope.slice(0, 2),
316
- pinRungs: view.pinRungs.filter((rung) => rung.rung === "resource")
317
- };
318
- if (level === "thread" && view.threadId) return view;
319
- }
320
- /**
321
- * Host-vouched identity chain: the org → project → session rungs this
322
- * request resolved are materialized as ordinary scope nodes linked by
323
- * membership edges, so the sidebar tree is built from scopes that EXIST —
324
- * never from the declared structure plan or the rung config. Materialization
325
- * is create-only and deduped by address (existing nodes keep their declared
326
- * names/parents), so the steady state is a no-op skip. No companion scope is
327
- * created here or anywhere automatically. A vouch failure never fails the read —
328
- * the tree simply serves the scopes that already exist.
329
- */
330
- async #vouchIdentityScopes(view) {
331
- const orgAddress = `org:${view.orgId}`;
332
- const resourceAddress = `resource:${view.factoryProjectId}`;
333
- const chain = [
334
- {
335
- address: orgAddress,
336
- contextualScopeAddress: orgAddress
337
- },
338
- {
339
- address: resourceAddress,
340
- name: view.factoryProjectName,
341
- contextualScopeAddress: orgAddress,
342
- parentAddresses: [orgAddress]
343
- },
344
- ...view.threadId ? [{
345
- address: `thread:${view.threadId}`,
346
- contextualScopeAddress: resourceAddress,
347
- parentAddresses: [resourceAddress]
348
- }] : []
349
- ];
350
- let existing;
351
99
  try {
352
- const { scopes } = await view.store.listScopeNodes({ addresses: chain.map((link) => link.address) });
353
- existing = new Set(scopes.map((node) => node.address));
100
+ return {
101
+ knowledge,
102
+ store,
103
+ read: await knowledge.readScopeFor([`org:${tenant.orgId}`, `project:${projectId}`])
104
+ };
354
105
  } catch (error) {
355
- if (error instanceof KnowledgeUnsupportedCapabilityError) return;
106
+ if (error instanceof KnowledgeDeclarationError) return { response: c.json({
107
+ error: "knowledge_misconfigured",
108
+ message: error.message
109
+ }, 500) };
356
110
  throw error;
357
111
  }
358
- for (const link of chain) {
359
- if (existing.has(link.address)) continue;
360
- await view.knowledge.materializeScope(link).catch(() => void 0);
361
- }
362
- }
363
- /**
364
- * Session scopes are listed only under the viewed project, and only when the `threadId`
365
- * drill-down would accept them (a visible record captured in that session), so no listing
366
- * exposes a session id the drill-down would reject. Returns the ids of hidden session nodes.
367
- * With `probe: false` only the cheap project check runs; callers probe the bounded page they return.
368
- */
369
- async #hiddenSessionIds(view, nodes, projectNodeId, { probe }) {
370
- const hidden = /* @__PURE__ */ new Set();
371
- const projectScope = [`org:${view.orgId}`, `resource:${view.factoryProjectId}`];
372
- const sessions = [];
373
- for (const node of nodes) {
374
- if (!node.address.startsWith("thread:")) continue;
375
- const threadId = sessionThreadId(node);
376
- if (!threadId || !projectNodeId || !node.parentIds.includes(projectNodeId)) hidden.add(node.id);
377
- else if (probe && threadId !== view.threadId) sessions.push({
378
- id: node.id,
379
- threadId
380
- });
381
- }
382
- for (let index = 0; index < sessions.length; index += SCOPE_COUNT_CONCURRENCY) await Promise.all(sessions.slice(index, index + SCOPE_COUNT_CONCURRENCY).map(async ({ id, threadId }) => {
383
- const { records } = await view.store.knowledgeBySource({
384
- sourceThreadId: threadId,
385
- scope: [...projectScope, `thread:${threadId}`],
386
- limit: 1
387
- });
388
- if (records.length === 0) hidden.add(id);
389
- }));
390
- return hidden;
391
- }
392
- /**
393
- * Display names for session scopes, resolved at read time from the thread's current title
394
- * (never stored on the scope node, where it would go stale). Keyed by scope node id.
395
- */
396
- async #sessionNames(nodes) {
397
- const names = /* @__PURE__ */ new Map();
398
- const sessions = nodes.flatMap((node) => {
399
- const threadId = node.address.startsWith("thread:") ? node.address.slice(7) : "";
400
- return threadId ? [{
401
- id: node.id,
402
- threadId
403
- }] : [];
404
- });
405
- for (let index = 0; index < sessions.length; index += SCOPE_COUNT_CONCURRENCY) await Promise.all(sessions.slice(index, index + SCOPE_COUNT_CONCURRENCY).map(async ({ id, threadId }) => {
406
- let title;
407
- try {
408
- title = (await this.deps.threadTitle?.(threadId))?.trim();
409
- } catch {}
410
- names.set(id, title || `session ${threadId.slice(0, 8)}`);
411
- }));
412
- return names;
413
- }
414
- /** Reserved `pinned` node ids at the active view's rungs (one exact-scope lookup per rung). */
415
- async #pinnedNodeIds(view) {
416
- const out = [];
417
- for (const { rung, scope } of view.pinRungs) {
418
- const node = await view.store.getNodeByName({
419
- name: PINNED_NODE_NAME,
420
- scope
421
- });
422
- if (node && !node.mergedInto) out.push({
423
- rung,
424
- id: node.id
425
- });
426
- }
427
- return out;
428
- }
429
- /** Non-deleted pinned records for the given pinned-node ids, visible in the view. */
430
- async #pinnedRecords(view, pinnedNodeIds) {
431
- const out = [];
432
- for (const { rung, id } of pinnedNodeIds) {
433
- const { records } = await view.store.listKnowledgeAbout({
434
- node: id,
435
- scope: view.scope,
436
- limit: 200
437
- });
438
- for (const record of records) out.push({
439
- rung,
440
- record
441
- });
442
- }
443
- return out;
444
112
  }
445
113
  routes() {
114
+ const badRequest = (c, message) => c.json({
115
+ error: "bad_request",
116
+ message
117
+ }, 400);
446
118
  return [
447
- registerApiRoute("/web/factory/projects/:id/knowledge/scopes", {
119
+ registerApiRoute("/web/factory/projects/:id/knowledge/tree", {
448
120
  method: "GET",
449
121
  requiresAuth: false,
450
- handler: async (c) => {
451
- const view = await this.#resolveView(loose(c));
122
+ handler: async (raw) => {
123
+ const c = loose(raw);
124
+ const view = await this.#resolveView(c);
452
125
  if ("response" in view) return view.response;
453
- await this.#vouchIdentityScopes(view);
454
- let scopeNodes;
455
- let nextCursor;
456
- const childCursors = {};
457
- let storedScopeNodes = [];
458
- let scopesTruncated = false;
459
- try {
460
- ({scopes: storedScopeNodes, truncated: scopesTruncated} = await listOrgScopeNodes(view.store, view.orgId, this.#limits.maxOrgScopePages));
461
- const projectNodeId = storedScopeNodes.find((node) => node.address === `resource:${view.factoryProjectId}`)?.id;
462
- const foreignSessions = await this.#hiddenSessionIds(view, storedScopeNodes, projectNodeId, { probe: false });
463
- storedScopeNodes = storedScopeNodes.filter((node) => !foreignSessions.has(node.id));
464
- const scopeNodeById = new Map(storedScopeNodes.map((node) => [node.id, node]));
465
- const childScopeCountByParent = /* @__PURE__ */ new Map();
466
- for (const node of storedScopeNodes) for (const parentId of node.parentIds) childScopeCountByParent.set(parentId, (childScopeCountByParent.get(parentId) ?? 0) + 1);
467
- const parentId = loose(c).req.query("parentId");
468
- const cursor = loose(c).req.query("cursor");
469
- if (parentId && !UUID_RE.test(parentId)) return c.json({ error: "invalid_scope_parent" }, 400);
470
- if (cursor && !UUID_RE.test(cursor)) return c.json({ error: "invalid_scope_cursor" }, 400);
471
- if (parentId && !scopeNodeById.has(parentId)) return c.json({ error: "scope_not_found" }, 404);
472
- const siblings = storedScopeNodes.filter((node) => parentId ? node.parentIds.includes(parentId) : node.parentIds.length === 0).sort(compareScopeNodes);
473
- const cursorIndex = cursor ? siblings.findIndex((node) => node.id === cursor) : -1;
474
- if (cursor && cursorIndex < 0) return c.json({ error: "invalid_scope_cursor" }, 400);
475
- const pageStart = cursorIndex + 1;
476
- const siblingPage = siblings.slice(pageStart, pageStart + SCOPE_PAGE_SIZE);
477
- if (pageStart + siblingPage.length < siblings.length) nextCursor = siblingPage.at(-1)?.id;
478
- const returnedById = new Map(siblingPage.map((node) => [node.id, node]));
479
- if (!parentId) {
480
- const addFirstChildPage = (parent) => {
481
- const children = storedScopeNodes.filter((node) => node.parentIds.includes(parent.id)).sort(compareScopeNodes);
482
- const returnedChildren = [];
483
- for (const child of children.slice(0, SCOPE_PAGE_SIZE)) {
484
- if (returnedById.size >= this.#limits.maxNodes) break;
485
- returnedById.set(child.id, child);
486
- returnedChildren.push(child);
487
- }
488
- if (returnedChildren.length < children.length) {
489
- const lastChild = returnedChildren.at(-1);
490
- if (lastChild) childCursors[parent.id] = lastChild.id;
491
- }
492
- };
493
- for (const root of siblingPage) addFirstChildPage(root);
494
- const identityAddresses = /* @__PURE__ */ new Set([
495
- `org:${view.orgId}`,
496
- `resource:${view.factoryProjectId}`,
497
- ...view.threadId ? [`thread:${view.threadId}`] : []
498
- ]);
499
- const includeWithParents = (node) => {
500
- if (returnedById.has(node.id) || returnedById.size >= this.#limits.maxNodes) return;
501
- for (const ancestorId of node.parentIds) {
502
- const ancestor = scopeNodeById.get(ancestorId);
503
- if (ancestor) includeWithParents(ancestor);
504
- }
505
- returnedById.set(node.id, node);
506
- };
507
- for (const node of storedScopeNodes) if (identityAddresses.has(node.address)) includeWithParents(node);
508
- const projectNode = projectNodeId ? scopeNodeById.get(projectNodeId) : void 0;
509
- if (projectNode && returnedById.has(projectNode.id)) addFirstChildPage(projectNode);
510
- }
511
- const unreadableSessions = await this.#hiddenSessionIds(view, [...returnedById.values()], projectNodeId, { probe: true });
512
- for (const id of unreadableSessions) returnedById.delete(id);
513
- scopeNodes = [];
514
- const returnedNodes = [...returnedById.values()].sort(compareScopeNodes);
515
- for (let index = 0; index < returnedNodes.length; index += SCOPE_COUNT_CONCURRENCY) {
516
- const batch = returnedNodes.slice(index, index + SCOPE_COUNT_CONCURRENCY);
517
- scopeNodes.push(...await Promise.all(batch.map(async (node) => {
518
- const members = await view.store.listScopeMembers({
519
- scopeNodeId: node.id,
520
- limit: this.#limits.maxNodes
521
- });
522
- return {
523
- ...node,
524
- ...node.address === `resource:${view.factoryProjectId}` ? { name: view.factoryProjectName } : {},
525
- ...directScopeMemberCounts(members, childScopeCountByParent.get(node.id) ?? 0, view.scope, this.#limits.maxNodes)
526
- };
527
- })));
528
- }
529
- const sessionNames = await this.#sessionNames(scopeNodes);
530
- scopeNodes = scopeNodes.map((node) => ({
531
- ...node,
532
- kind: scopeKindLabel(node.address, node.kind),
533
- ...sessionNames.has(node.id) ? { name: sessionNames.get(node.id) } : {}
534
- }));
535
- } catch (error) {
536
- if (!(error instanceof KnowledgeUnsupportedCapabilityError)) throw error;
537
- scopeNodes = void 0;
538
- }
539
- const scopeNodeByAddress = new Map(storedScopeNodes.map((node) => [node.address, node]));
540
- const threadRoot = view.threadId ? scopeNodeByAddress.get(`thread:${view.threadId}`) : void 0;
541
- const threadRootName = threadRoot ? (await this.#sessionNames([threadRoot])).get(threadRoot.id) : void 0;
542
- const rungs = [
543
- {
544
- level: "org",
545
- id: view.orgId,
546
- available: true
547
- },
548
- {
549
- level: "resource",
550
- id: view.factoryProjectId,
551
- available: true
552
- },
553
- ...view.threadId ? [{
554
- level: "thread",
555
- id: view.threadId,
556
- available: true
557
- }] : []
558
- ];
126
+ const parentId = boundedId(c.req.query("parentId"));
127
+ const cursor = boundedId(c.req.query("cursor"));
128
+ const limit = boundedLimit(c.req.query("limit"), MAX_PAGE_LIMIT);
129
+ if (limit === null) return badRequest(c, `limit must be an integer from 1 to ${MAX_PAGE_LIMIT}.`);
130
+ const level = await listKnowledgeTreeChildren(view.store, {
131
+ parentId: parentId ?? null,
132
+ read: view.read,
133
+ cursor,
134
+ limit
135
+ });
559
136
  return c.json({
560
- roots: rungs.map((rung) => {
561
- const match = scopeNodeByAddress.get(`${rung.level}:${rung.id}`);
562
- const name = match?.address === `resource:${view.factoryProjectId}` ? view.factoryProjectName : match && rung.level === "thread" ? threadRootName : match?.name;
563
- return match ? {
564
- ...rung,
565
- scopeNodeId: match.id,
566
- name
567
- } : rung;
568
- }),
569
- defaultLevel: "resource",
570
- ...scopeNodes ? { scopeNodes } : {},
571
- ...nextCursor ? { nextCursor } : {},
572
- ...Object.keys(childCursors).length > 0 ? { childCursors } : {},
573
- ...scopesTruncated ? { truncated: true } : {}
137
+ ...level,
138
+ pages: level.pages.map((page) => withDisplayLabel(view.knowledge, page))
574
139
  });
575
140
  }
576
141
  }),
577
- registerApiRoute("/web/factory/projects/:id/knowledge/search", {
142
+ registerApiRoute("/web/factory/projects/:id/knowledge/pages/:pageId", {
578
143
  method: "GET",
579
144
  requiresAuth: false,
580
- handler: async (c) => {
581
- const view = await this.#resolveView(loose(c));
145
+ handler: async (raw) => {
146
+ const c = loose(raw);
147
+ const view = await this.#resolveView(c);
582
148
  if ("response" in view) return view.response;
583
- const query = (loose(c).req.query("q") ?? "").trim().slice(0, SEARCH_QUERY_LIMIT).toLocaleLowerCase();
584
- if (query.length < 2) return c.json({
585
- results: [],
586
- truncated: false
149
+ const pageId = boundedId(c.req.param("pageId"));
150
+ if (!pageId) return c.json({ error: "page_not_found" }, 404);
151
+ const noteLimit = boundedLimit(c.req.query("noteLimit"), MAX_PAGE_LIMIT);
152
+ if (noteLimit === null) return badRequest(c, `noteLimit must be an integer from 1 to ${MAX_PAGE_LIMIT}.`);
153
+ const page = await readKnowledgePage(view.store, {
154
+ pageId,
155
+ read: view.read,
156
+ noteCursor: boundedId(c.req.query("noteCursor")),
157
+ noteLimit
587
158
  });
588
- const scanLimit = Math.min(SEARCH_SCAN_CAP, this.#limits.maxNodes);
589
- const [prefixNodes, scannedNodes] = await Promise.all([view.store.listNodes({
590
- scope: view.scope,
591
- namePrefix: query,
592
- limit: 21
593
- }), view.store.listNodes({
594
- scope: view.scope,
595
- limit: scanLimit
596
- })]);
597
- const contentById = /* @__PURE__ */ new Map();
598
- for (const node of [...prefixNodes, ...scannedNodes]) {
599
- if (node.isScope || !Array.isArray(node.scope) || !withinViewBoundary(node.scope, view.scope) || !node.name.toLocaleLowerCase().includes(query)) continue;
600
- contentById.set(node.id, node);
601
- }
602
- let structuralScopes = [];
603
- let scopesTruncated = false;
604
- try {
605
- const orgScopes = await listOrgScopeNodes(view.store, view.orgId, this.#limits.maxOrgScopePages);
606
- scopesTruncated = orgScopes.truncated;
607
- structuralScopes = orgScopes.scopes.filter((node) => (!node.address.startsWith("thread:") || sessionThreadId(node) === view.threadId) && node.name.toLocaleLowerCase().includes(query));
608
- } catch (error) {
609
- if (!(error instanceof KnowledgeUnsupportedCapabilityError)) throw error;
610
- }
611
- const scopeSessionNames = await this.#sessionNames(structuralScopes);
612
- const results = [...structuralScopes.map((scopeNode) => {
613
- const rung = scopeNode.address === `org:${view.orgId}` ? "org" : scopeNode.address === `resource:${view.factoryProjectId}` ? "resource" : view.threadId && scopeNode.address === `thread:${view.threadId}` ? "thread" : null;
614
- return {
615
- id: scopeNode.id,
616
- name: scopeNode.address === `resource:${view.factoryProjectId}` ? view.factoryProjectName : scopeSessionNames.get(scopeNode.id) ?? scopeNode.name,
617
- kind: scopeKindLabel(scopeNode.address, scopeNode.kind),
618
- type: "scope",
619
- rung,
620
- address: scopeNode.address,
621
- ...scopeNode.description ? { description: scopeNode.description } : {}
622
- };
623
- }), ...[...contentById.values()].map((node) => {
624
- const rung = deepestRung(node.scope);
625
- const threadId = rung === "thread" ? node.scope.find((address) => address.startsWith("thread:"))?.slice(7) : void 0;
626
- return {
627
- id: node.id,
628
- name: node.name,
629
- kind: node.kind,
630
- type: "node",
631
- rung,
632
- ...threadId ? { threadId } : {}
633
- };
634
- })].sort((a, b) => knowledgeSearchRank(a.name, query) - knowledgeSearchRank(b.name, query) || a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
159
+ if (!page) return c.json({ error: "page_not_found" }, 404);
160
+ const label = (entry) => withDisplayLabel(view.knowledge, entry);
635
161
  return c.json({
636
- results: results.slice(0, SEARCH_RESULT_LIMIT),
637
- truncated: scopesTruncated || results.length > SEARCH_RESULT_LIMIT || prefixNodes.length > SEARCH_RESULT_LIMIT || scannedNodes.length >= scanLimit
162
+ ...page,
163
+ page: label(page.page),
164
+ ancestors: page.ancestors.map(label),
165
+ related: page.related.map(label)
638
166
  });
639
167
  }
640
168
  }),
641
- registerApiRoute("/web/factory/projects/:id/knowledge/subgraph", {
169
+ registerApiRoute("/web/factory/projects/:id/knowledge/graph", {
642
170
  method: "GET",
643
171
  requiresAuth: false,
644
- handler: async (c) => {
645
- const resolved = await this.#resolveView(loose(c));
646
- if ("response" in resolved) return resolved.response;
647
- const scopeNodeId = loose(c).req.query("scopeNodeId");
648
- if (scopeNodeId !== void 0) {
649
- if (!UUID_RE.test(scopeNodeId)) return c.json({ error: "scope_not_found" }, 404);
650
- const limits = this.#limits;
651
- const { store } = resolved;
652
- let storedRoot;
653
- try {
654
- storedRoot = await findOrgScopeNode(store, resolved.orgId, scopeNodeId);
655
- } catch (error) {
656
- if (error instanceof KnowledgeUnsupportedCapabilityError) return c.json({ error: "scope_not_found" }, 404);
657
- throw error;
658
- }
659
- if (!storedRoot) return c.json({ error: "scope_not_found" }, 404);
660
- const { scopes: scopeNodes, truncated: scopesTruncated } = await listOrgScopeNodes(store, resolved.orgId, limits.maxOrgScopePages);
661
- const rootSessionName = (await this.#sessionNames([storedRoot])).get(storedRoot.id);
662
- const root = storedRoot.address === `resource:${resolved.factoryProjectId}` ? {
663
- ...storedRoot,
664
- name: resolved.factoryProjectName
665
- } : rootSessionName ? {
666
- ...storedRoot,
667
- name: rootSessionName
668
- } : storedRoot;
669
- if (storedRoot.address.startsWith("thread:")) {
670
- const projectNodeId = scopeNodes.find((node) => node.address === `resource:${resolved.factoryProjectId}`)?.id;
671
- if ((await this.#hiddenSessionIds(resolved, [storedRoot], projectNodeId, { probe: true })).has(storedRoot.id)) return c.json({ error: "scope_not_found" }, 404);
672
- }
673
- const otherSessionIds = new Set(scopeNodes.filter((node) => node.address.startsWith("thread:") && sessionThreadId(node) !== resolved.threadId).map((node) => node.id));
674
- const fetched = await store.listScopeMembers({
675
- scopeNodeId,
676
- limit: limits.maxNodes
677
- });
678
- const bounded = fetched.members.filter((node) => node.isScope && !otherSessionIds.has(node.id) || !node.isScope && Array.isArray(node.scope) && withinViewBoundary(node.scope, resolved.scope));
679
- let truncated = scopesTruncated || fetched.hasMore || bounded.length > limits.maxNodes;
680
- const members = bounded.slice(0, limits.maxNodes);
681
- const contentMembers = members.filter((node) => !node.isScope && Array.isArray(node.scope));
682
- const childScopeCountByParent = /* @__PURE__ */ new Map();
683
- for (const node of scopeNodes) for (const parentId of node.parentIds) childScopeCountByParent.set(parentId, (childScopeCountByParent.get(parentId) ?? 0) + 1);
684
- const scopeCountsById = /* @__PURE__ */ new Map([[root.id, directScopeMemberCounts(fetched, childScopeCountByParent.get(root.id) ?? 0, resolved.scope, limits.maxNodes)]]);
685
- const memberScopes = members.filter((node) => node.isScope);
686
- for (let index = 0; index < memberScopes.length; index += SCOPE_COUNT_CONCURRENCY) {
687
- const batch = memberScopes.slice(index, index + SCOPE_COUNT_CONCURRENCY);
688
- await Promise.all(batch.map(async (node) => {
689
- const directMembers = await store.listScopeMembers({
690
- scopeNodeId: node.id,
691
- limit: limits.maxNodes
692
- });
693
- scopeCountsById.set(node.id, directScopeMemberCounts(directMembers, childScopeCountByParent.get(node.id) ?? 0, resolved.scope, limits.maxNodes));
694
- }));
695
- }
696
- const recordWindow = [];
697
- for (const node of contentMembers) {
698
- if (recordWindow.length > limits.maxRecords) break;
699
- const { records } = await store.listKnowledgeAbout({
700
- node: node.id,
701
- scope: node.scope,
702
- limit: limits.maxRecords + 1 - recordWindow.length
703
- });
704
- recordWindow.push(...records);
705
- }
706
- recordWindow.sort((a, b) => b.id.localeCompare(a.id));
707
- if (recordWindow.length > limits.maxRecords) {
708
- truncated = true;
709
- recordWindow.length = limits.maxRecords;
710
- }
711
- const resolver = new WikilinkResolver(store, contentMembers, limits.maxFallbackLookups);
712
- const edges = [];
713
- const graphRecords = [];
714
- const edgeSeen = /* @__PURE__ */ new Set();
715
- const recordCounts = /* @__PURE__ */ new Map();
716
- for (const record of recordWindow) {
717
- recordCounts.set(record.node, (recordCounts.get(record.node) ?? 0) + 1);
718
- const nodeIds = [record.node];
719
- for (const name of parseKnowledgeWikilinks(record.text)) {
720
- const target = await resolver.resolve(name, record.scope);
721
- if (!target) continue;
722
- if (target.id === record.node) continue;
723
- if (!resolver.inWindowId(target.id)) continue;
724
- if (!nodeIds.includes(target.id)) nodeIds.push(target.id);
725
- const key = `${record.node}\u0000${target.id}`;
726
- if (edgeSeen.has(key)) continue;
727
- edgeSeen.add(key);
728
- edges.push({
729
- id: `wikilink:${record.node}:${target.id}`,
730
- source: record.node,
731
- target: target.id,
732
- type: "wikilink",
733
- recordId: record.id
734
- });
735
- }
736
- graphRecords.push({
737
- id: record.id,
738
- nodeIds,
739
- pinned: false,
740
- text: truncateRecordText(record.text)
741
- });
742
- }
743
- for (const member of members) edges.push({
744
- id: `contains:${root.id}:${member.id}`,
745
- source: root.id,
746
- target: member.id,
747
- type: "contains"
748
- });
749
- const scopeAddressById = new Map(scopeNodes.map((node) => [node.id, node.address]));
750
- const memberSessionNames = await this.#sessionNames(members.flatMap((node) => {
751
- const address = node.isScope ? scopeAddressById.get(node.id) : void 0;
752
- return address ? [{
753
- id: node.id,
754
- address
755
- }] : [];
756
- }));
757
- const rootRow = await store.getNode(root.id);
758
- const activity = await store.listActivity({
759
- scope: resolved.scope,
760
- limit: 1
761
- });
762
- const payload = {
763
- view: resolved.view,
764
- ...resolved.threadId ? { threadId: resolved.threadId } : {},
765
- nodes: [{
766
- id: root.id,
767
- name: root.name,
768
- kind: scopeKindLabel(root.address, root.kind),
769
- ...root.description ? { description: root.description } : {},
770
- scope: null,
771
- rung: null,
772
- isScope: true,
773
- pinned: false,
774
- recordCount: 0,
775
- ...scopeCountsById.get(root.id),
776
- ...rootRow ? {
777
- createdAt: rootRow.createdAt.toISOString(),
778
- updatedAt: rootRow.updatedAt.toISOString()
779
- } : {}
780
- }, ...members.map((node) => {
781
- const nodeScope = Array.isArray(node.scope) ? node.scope : null;
782
- const address = node.isScope ? scopeAddressById.get(node.id) : void 0;
783
- return {
784
- id: node.id,
785
- name: memberSessionNames.get(node.id) ?? node.name,
786
- kind: node.isScope ? scopeKindLabel(address ?? "", node.kind) : node.kind,
787
- ...node.description ? { description: node.description } : {},
788
- scope: nodeScope,
789
- rung: nodeScope ? deepestRung(nodeScope) : null,
790
- ...node.isScope ? {
791
- isScope: true,
792
- ...scopeCountsById.get(node.id)
793
- } : {},
794
- pinned: false,
795
- recordCount: recordCounts.get(node.id) ?? 0,
796
- createdAt: node.createdAt.toISOString(),
797
- updatedAt: node.updatedAt.toISOString()
798
- };
799
- })],
800
- edges,
801
- records: graphRecords,
802
- truncated,
803
- outOfWindow: [...resolver.outOfWindow.values()],
804
- unresolvedCapped: {
805
- count: resolver.cappedCount,
806
- names: resolver.cappedNames
807
- },
808
- pinCensus: {
809
- resource: 0,
810
- thread: null
811
- },
812
- version: activity[0]?.id ?? null
813
- };
814
- return c.json(payload);
815
- }
816
- const view = this.#selectedView(resolved, loose(c).req.query("scopeLevel"));
817
- if (!view) return c.json({ error: "scope_not_found" }, 404);
818
- const { store, scope } = view;
819
- const limits = this.#limits;
820
- const fetched = (await store.listNodes({
821
- scope,
822
- limit: limits.maxNodes + 1
823
- })).filter((node) => Array.isArray(node.scope));
824
- let truncated = fetched.length > limits.maxNodes;
825
- const pinnedNodeIds = await this.#pinnedNodeIds(view);
826
- const pinnedNodeIdSet = new Set(pinnedNodeIds.map((p) => p.id));
827
- const nodes = fetched.slice(0, limits.maxNodes).filter((node) => !pinnedNodeIdSet.has(node.id));
828
- const recordWindow = [];
829
- for (const node of nodes) {
830
- if (recordWindow.length > limits.maxRecords) break;
831
- const { records } = await store.listKnowledgeAbout({
832
- node: node.id,
833
- scope,
834
- limit: limits.maxRecords + 1 - recordWindow.length
835
- });
836
- recordWindow.push(...records);
837
- }
838
- recordWindow.sort((a, b) => b.id.localeCompare(a.id));
839
- if (recordWindow.length > limits.maxRecords) {
840
- truncated = true;
841
- recordWindow.length = limits.maxRecords;
842
- }
843
- const resolver = new WikilinkResolver(store, nodes, limits.maxFallbackLookups);
844
- const edges = [];
845
- const graphRecords = [];
846
- const edgeSeen = /* @__PURE__ */ new Set();
847
- const recordCounts = /* @__PURE__ */ new Map();
848
- for (const record of recordWindow) {
849
- recordCounts.set(record.node, (recordCounts.get(record.node) ?? 0) + 1);
850
- const nodeIds = [record.node];
851
- for (const name of parseKnowledgeWikilinks(record.text)) {
852
- const target = await resolver.resolve(name, record.scope);
853
- if (!target) continue;
854
- if (target.id === record.node) continue;
855
- if (!resolver.inWindowId(target.id)) continue;
856
- if (!nodeIds.includes(target.id)) nodeIds.push(target.id);
857
- const key = `${record.node}\u0000${target.id}`;
858
- if (edgeSeen.has(key)) continue;
859
- edgeSeen.add(key);
860
- edges.push({
861
- id: `wikilink:${record.node}:${target.id}`,
862
- source: record.node,
863
- target: target.id,
864
- type: "wikilink",
865
- recordId: record.id
866
- });
867
- }
868
- graphRecords.push({
869
- id: record.id,
870
- nodeIds,
871
- pinned: false,
872
- text: truncateRecordText(record.text)
873
- });
874
- }
875
- const pinnedRecords = await this.#pinnedRecords(view, pinnedNodeIds);
876
- const accented = /* @__PURE__ */ new Set();
877
- for (const { record } of pinnedRecords) {
878
- const targets = [];
879
- for (const name of parseKnowledgeWikilinks(record.text)) {
880
- const target = await resolver.resolve(name, record.scope);
881
- if (target && resolver.inWindowId(target.id) && !targets.includes(target.id)) targets.push(target.id);
882
- }
883
- graphRecords.push({
884
- id: record.id,
885
- nodeIds: targets,
886
- pinned: true,
887
- text: truncateRecordText(record.text)
888
- });
889
- if (targets.length === 1) {
890
- accented.add(targets[0]);
891
- continue;
892
- }
893
- for (let a = 0; a < targets.length; a += 1) for (let b = a + 1; b < targets.length; b += 1) {
894
- const key = `${targets[a]}\u0000${targets[b]}\u0000pin`;
895
- if (edgeSeen.has(key)) continue;
896
- edgeSeen.add(key);
897
- edges.push({
898
- id: `pin:${record.id}:${targets[a]}:${targets[b]}`,
899
- source: targets[a],
900
- target: targets[b],
901
- type: "wikilink",
902
- recordId: record.id,
903
- pinned: true
904
- });
905
- }
906
- }
907
- const pinCensus = {
908
- resource: pinnedRecords.filter((p) => p.rung === "resource").length,
909
- thread: view.view === "thread" ? pinnedRecords.filter((p) => p.rung === "thread").length : null
910
- };
911
- const activity = await store.listActivity({
912
- scope,
913
- limit: 1
172
+ handler: async (raw) => {
173
+ const c = loose(raw);
174
+ const view = await this.#resolveView(c);
175
+ if ("response" in view) return view.response;
176
+ const maxPages = boundedLimit(c.req.query("maxPages"), MAX_GRAPH_PAGES);
177
+ if (maxPages === null) return badRequest(c, `maxPages must be an integer from 1 to ${MAX_GRAPH_PAGES}.`);
178
+ const graph = await readKnowledgePageGraph(view.store, {
179
+ read: view.read,
180
+ rootId: boundedId(c.req.query("rootId")) ?? null,
181
+ ...maxPages ? { limits: { maxPages } } : {}
182
+ });
183
+ if (!graph) return c.json({ error: "page_not_found" }, 404);
184
+ const grants = await readKnowledgeScopeGrants(view.store, {
185
+ pages: graph.pages,
186
+ read: view.read,
187
+ grantsFor: (scope) => view.knowledge.scopeGrants(scope)
188
+ });
189
+ return c.json({
190
+ ...graph,
191
+ pages: graph.pages.map((page) => withDisplayLabel(view.knowledge, page)),
192
+ grants: grants.map((grant) => {
193
+ const principalLabel = view.knowledge.scopeLabel(grant.principal);
194
+ return principalLabel ? {
195
+ ...grant,
196
+ principalLabel
197
+ } : grant;
198
+ })
914
199
  });
915
- const payload = {
916
- view: view.view,
917
- ...view.threadId ? { threadId: view.threadId } : {},
918
- nodes: nodes.map((node) => ({
919
- id: node.id,
920
- name: node.name,
921
- kind: node.kind,
922
- ...node.description ? { description: node.description } : {},
923
- scope: node.scope,
924
- rung: deepestRung(node.scope),
925
- pinned: accented.has(node.id),
926
- recordCount: recordCounts.get(node.id) ?? 0,
927
- createdAt: node.createdAt.toISOString(),
928
- updatedAt: node.updatedAt.toISOString()
929
- })),
930
- edges,
931
- records: graphRecords,
932
- truncated,
933
- outOfWindow: [...resolver.outOfWindow.values()],
934
- unresolvedCapped: {
935
- count: resolver.cappedCount,
936
- names: resolver.cappedNames
937
- },
938
- pinCensus,
939
- version: activity[0]?.id ?? null
940
- };
941
- return c.json(payload);
942
200
  }
943
201
  }),
944
- registerApiRoute("/web/factory/projects/:id/knowledge/nodes/:nodeId", {
202
+ registerApiRoute("/web/factory/projects/:id/knowledge/search", {
945
203
  method: "GET",
946
204
  requiresAuth: false,
947
- handler: async (c) => {
948
- const resolved = await this.#resolveView(loose(c));
949
- if ("response" in resolved) return resolved.response;
950
- const nodeId = loose(c).req.param("nodeId");
951
- if (!nodeId || nodeId.length > 512) return c.json({ error: "node_not_found" }, 404);
952
- const view = this.#selectedView(resolved, loose(c).req.query("scopeLevel"));
953
- if (!view) return c.json({ error: "scope_not_found" }, 404);
954
- const { store, scope } = view;
955
- const node = await store.getNode(nodeId);
956
- if (!node?.scope || !isKnowledgeScopeVisible(node.scope, scope)) return c.json({ error: "node_not_found" }, 404);
957
- const pinnedNodeIds = await this.#pinnedNodeIds(view);
958
- const pinnedNodeIdSet = new Set(pinnedNodeIds.map((p) => p.id));
959
- const [owned, mentioning] = await Promise.all([store.listKnowledgeAbout({
960
- node: node.id,
961
- scope,
962
- limit: 200
963
- }), store.listKnowledgeMentioning({
964
- node: node.id,
965
- scope,
966
- limit: 200
967
- })]);
968
- const seen = /* @__PURE__ */ new Set();
969
- const records = [];
970
- const push = (record, relation) => {
971
- if (seen.has(record.id)) return;
972
- seen.add(record.id);
973
- records.push({
974
- id: record.id,
975
- node: record.node,
976
- relation,
977
- text: record.text,
978
- scope: record.scope,
979
- rung: deepestRung(record.scope),
980
- sourceThreadId: record.sourceThreadId,
981
- capturedAt: record.capturedAt.toISOString(),
982
- ...record.when ? { when: record.when.toISOString() } : {},
983
- pinned: pinnedNodeIdSet.has(record.node),
984
- ...record.metadata ? { metadata: record.metadata } : {}
985
- });
986
- };
987
- for (const record of [...owned.records].sort((a, b) => b.id.localeCompare(a.id))) push(record, "owned");
988
- for (const record of [...mentioning.records].sort((a, b) => b.id.localeCompare(a.id))) push(record, "mentions");
989
- const payload = {
990
- node: {
991
- id: node.id,
992
- name: node.name,
993
- kind: node.kind,
994
- content: node.content ?? "",
995
- ...node.description ? { description: node.description } : {},
996
- scope: node.scope,
997
- rung: deepestRung(node.scope),
998
- createdAt: node.createdAt.toISOString(),
999
- updatedAt: node.updatedAt.toISOString()
1000
- },
1001
- records
1002
- };
1003
- return c.json(payload);
205
+ handler: async (raw) => {
206
+ const c = loose(raw);
207
+ const view = await this.#resolveView(c);
208
+ if ("response" in view) return view.response;
209
+ const query = (c.req.query("q") ?? "").trim();
210
+ if (!query) return c.json({ results: [] });
211
+ if (query.length > SEARCH_QUERY_LIMIT) return badRequest(c, `q must be at most ${SEARCH_QUERY_LIMIT} characters.`);
212
+ const limit = boundedLimit(c.req.query("limit"), MAX_PAGE_LIMIT);
213
+ if (limit === null) return badRequest(c, `limit must be an integer from 1 to ${MAX_PAGE_LIMIT}.`);
214
+ const scopeIds = c.req.queries("scopeId")?.flatMap((id) => boundedId(id) ?? []);
215
+ const results = await searchKnowledgeExplorerPages(view.store, {
216
+ query,
217
+ read: view.read,
218
+ ...scopeIds?.length ? { scopeIds } : {},
219
+ limit
220
+ });
221
+ return c.json({ results: results.map((hit) => ({
222
+ ...hit,
223
+ page: withDisplayLabel(view.knowledge, hit.page)
224
+ })) });
1004
225
  }
1005
226
  }),
1006
- registerApiRoute("/web/factory/projects/:id/knowledge/activity", {
227
+ registerApiRoute("/web/factory/projects/:id/knowledge/events", {
1007
228
  method: "GET",
1008
229
  requiresAuth: false,
1009
- handler: async (c) => {
1010
- const resolved = await this.#resolveView(loose(c));
1011
- if ("response" in resolved) return resolved.response;
1012
- const scopeNodeId = loose(c).req.query("scopeNodeId");
1013
- let view;
1014
- let memberIds;
1015
- let membersTruncated = false;
1016
- if (scopeNodeId !== void 0) {
1017
- if (!UUID_RE.test(scopeNodeId)) return c.json({ error: "scope_not_found" }, 404);
1018
- let scopeNode;
230
+ handler: async (raw) => {
231
+ const c = loose(raw);
232
+ const view = await this.#resolveView(c);
233
+ if ("response" in view) return view.response;
234
+ const { knowledge, store, read } = view;
235
+ return streamSSE(c, async (stream) => {
236
+ const closed = new Promise((resolve) => stream.onAbort(resolve));
237
+ let queue = Promise.resolve();
238
+ const unsubscribe = knowledge.onChange((event) => {
239
+ queue = queue.then(async () => {
240
+ if (stream.aborted) return;
241
+ const change = await visibleChange(store, read, event).catch(() => null);
242
+ if (!change || stream.aborted) return;
243
+ try {
244
+ await stream.writeSSE({
245
+ event: "change",
246
+ data: JSON.stringify(change)
247
+ });
248
+ } catch {}
249
+ });
250
+ });
251
+ const keepalive = setInterval(() => {
252
+ if (!stream.aborted) stream.write(": ping\n\n");
253
+ }, EVENTS_KEEPALIVE_MS);
254
+ let expire;
1019
255
  try {
1020
- scopeNode = await findOrgScopeNode(resolved.store, resolved.orgId, scopeNodeId);
1021
- } catch (error) {
1022
- if (error instanceof KnowledgeUnsupportedCapabilityError) return c.json({ error: "scope_not_found" }, 404);
1023
- throw error;
256
+ await stream.write(": connected\n\n");
257
+ await Promise.race([closed, new Promise((resolve) => expire = setTimeout(resolve, EVENTS_MAX_AGE_MS))]);
258
+ } finally {
259
+ clearTimeout(expire);
260
+ clearInterval(keepalive);
261
+ unsubscribe();
1024
262
  }
1025
- if (!scopeNode) return c.json({ error: "scope_not_found" }, 404);
1026
- const { members, hasMore } = await resolved.store.listScopeMembers({
1027
- scopeNodeId,
1028
- limit: this.#limits.maxNodes
1029
- });
1030
- membersTruncated = hasMore || members.length > this.#limits.maxNodes;
1031
- memberIds = new Set(members.slice(0, this.#limits.maxNodes).filter((member) => !member.isScope).map((member) => member.id));
1032
- view = resolved;
1033
- } else {
1034
- const selected = this.#selectedView(resolved, loose(c).req.query("scopeLevel"));
1035
- if (!selected) return c.json({ error: "scope_not_found" }, 404);
1036
- view = selected;
1037
- }
1038
- const cursor = loose(c).req.query("cursor");
1039
- if (cursor && cursor.length > 128) return c.json({ error: "invalid_activity_cursor" }, 400);
1040
- const { items: activity, scanCursor } = await this.#visibleActivity(view, memberIds, cursor, 26);
1041
- const visiblePage = activity.slice(0, ACTIVITY_PAGE_SIZE);
1042
- const lastVisible = visiblePage.at(-1);
1043
- const payload = {
1044
- events: visiblePage.map(({ event, node }) => {
1045
- const rung = deepestRung(node.scope);
1046
- const threadId = rung === "thread" ? node.scope.find((address) => address.startsWith("thread:"))?.slice(7) : void 0;
1047
- return {
1048
- id: event.id,
1049
- action: event.action,
1050
- recordType: event.recordType,
1051
- ...event.recordType === "record" ? { recordId: event.recordId } : {},
1052
- scope: event.scope,
1053
- node: {
1054
- id: node.id,
1055
- name: node.name,
1056
- rung,
1057
- ...threadId ? { threadId } : {}
1058
- },
1059
- createdAt: event.createdAt.toISOString()
1060
- };
1061
- }),
1062
- ...activity.length > ACTIVITY_PAGE_SIZE && lastVisible ? { nextCursor: lastVisible.event.id } : scanCursor ? { nextCursor: scanCursor } : {},
1063
- ...membersTruncated ? { truncated: true } : {}
1064
- };
1065
- return c.json(payload);
263
+ });
264
+ }
265
+ }),
266
+ registerApiRoute("/web/factory/projects/:id/knowledge/activity", {
267
+ method: "GET",
268
+ requiresAuth: false,
269
+ handler: async (raw) => {
270
+ const c = loose(raw);
271
+ const view = await this.#resolveView(c);
272
+ if ("response" in view) return view.response;
273
+ const limit = boundedLimit(c.req.query("limit"), MAX_PAGE_LIMIT);
274
+ if (limit === null) return badRequest(c, `limit must be an integer from 1 to ${MAX_PAGE_LIMIT}.`);
275
+ return c.json(await readKnowledgePageActivity(view.store, {
276
+ read: view.read,
277
+ scopeId: boundedId(c.req.query("scopeId")),
278
+ pageId: boundedId(c.req.query("pageId")),
279
+ cursor: boundedId(c.req.query("cursor")),
280
+ limit
281
+ }));
1066
282
  }
1067
283
  })
1068
284
  ];
1069
285
  }
1070
- /**
1071
- * Newest-first activity page where EVERY returned event targets a node
1072
- * visible in the view. Visibility is decided BEFORE window shaping: hidden
1073
- * rows are skipped entirely (no action/type/id/time metadata leaks) and a
1074
- * hidden backlog can never displace visible events from the window.
1075
- * When the scan cap stops the walk before the stream ends, `scanCursor` is
1076
- * the last scanned event so the caller can continue past hidden rows.
1077
- */
1078
- async #visibleActivity(view, memberIds, cursor, limit) {
1079
- const out = [];
1080
- const nodes = /* @__PURE__ */ new Map();
1081
- const getNode = (id) => {
1082
- let node = nodes.get(id);
1083
- if (!node) {
1084
- node = view.store.getNode(id);
1085
- nodes.set(id, node);
1086
- }
1087
- return node;
1088
- };
1089
- let after = cursor;
1090
- let scanned = 0;
1091
- let exhausted = false;
1092
- while (out.length < limit && scanned < ACTIVITY_SCAN_CAP) {
1093
- const batch = await view.store.listActivity({
1094
- scope: view.scope,
1095
- after,
1096
- limit: ACTIVITY_BATCH
1097
- });
1098
- if (batch.length === 0) {
1099
- exhausted = true;
1100
- break;
1101
- }
1102
- for (const event of batch) {
1103
- after = event.id;
1104
- scanned += 1;
1105
- let targetNode;
1106
- if (event.recordType === "node") targetNode = await getNode(event.recordId);
1107
- else {
1108
- const record = await view.store.getKnowledge({ id: event.recordId });
1109
- targetNode = record ? await getNode(record.node) : null;
1110
- if (record && !isKnowledgeScopeVisible(record.scope, view.scope)) targetNode = null;
1111
- }
1112
- if (targetNode?.scope && isKnowledgeScopeVisible(targetNode.scope, view.scope) && (memberIds === void 0 || memberIds.has(targetNode.id))) out.push({
1113
- event,
1114
- node: targetNode
1115
- });
1116
- if (out.length >= limit || scanned >= ACTIVITY_SCAN_CAP) break;
1117
- }
1118
- }
1119
- return {
1120
- items: out,
1121
- ...!exhausted && out.length < limit && scanned >= ACTIVITY_SCAN_CAP && after ? { scanCursor: after } : {}
1122
- };
1123
- }
1124
286
  };
1125
287
  export { KnowledgeRoutes };
1126
288