fuli-context 0.20.0-beta.13 → 0.20.0-beta.15

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 (62) hide show
  1. package/dist/web/assets/{index-DvkJiX-L.js → index-GEnfRzSe.js} +1 -1
  2. package/dist/web/index.html +1 -1
  3. package/graph-provider/fuli_graph/app.py +16 -11
  4. package/graph-provider/fuli_graph/graph_query.py +30 -2
  5. package/graph-provider/fuli_graph/knowledge_audit.py +9 -1
  6. package/graph-provider/fuli_graph/knowledge_item_routes.py +10 -6
  7. package/graph-provider/fuli_graph/knowledge_item_view.py +41 -12
  8. package/graph-provider/fuli_graph/knowledge_item_view_models.py +3 -3
  9. package/graph-provider/fuli_graph/knowledge_review.py +47 -10
  10. package/graph-provider/fuli_graph/knowledge_search.py +18 -22
  11. package/graph-provider/fuli_graph/knowledge_session_migration.py +14 -4
  12. package/graph-provider/fuli_graph/knowledge_session_migration_models.py +2 -2
  13. package/graph-provider/fuli_graph/knowledge_tag_routes.py +7 -5
  14. package/graph-provider/fuli_graph/knowledge_tags.py +8 -4
  15. package/graph-provider/fuli_graph/knowledge_visibility.py +195 -0
  16. package/graph-provider/fuli_graph/models.py +12 -2
  17. package/graph-provider/fuli_graph/preference_conflicts.py +50 -4
  18. package/graph-provider/fuli_graph/publication_source_copies.py +36 -0
  19. package/graph-provider/fuli_graph/session_records.py +33 -13
  20. package/graph-provider/fuli_graph/session_records_models.py +4 -2
  21. package/graph-provider/fuli_graph/store_knowledge.py +5 -1
  22. package/graph-provider/fuli_graph/store_publication.py +70 -12
  23. package/graph-provider/pyproject.toml +1 -1
  24. package/native/win32/fuli-win-helper.exe +0 -0
  25. package/npm-shrinkwrap.json +2 -2
  26. package/package.json +1 -1
  27. package/skills/capturing-session-knowledge/references/retrieval.md +6 -0
  28. package/src/agent-tools/graph-definitions.js +4 -4
  29. package/src/agent-tools/interface-definitions.js +2 -1
  30. package/src/agent-tools/session-fuli-gate.js +55 -26
  31. package/src/agent-tools.js +2 -4
  32. package/src/agents/claude-code/lifecycle-hook.js +4 -3
  33. package/src/agents/codex/lifecycle-hook.js +4 -3
  34. package/src/agents/lifecycle-message.js +18 -0
  35. package/src/agents/turn-receipt.js +15 -8
  36. package/src/app/agent-request-context.js +18 -0
  37. package/src/graphiti/capture-notice.js +4 -1
  38. package/src/graphiti/federated-application.js +49 -60
  39. package/src/graphiti/human-review-channel.js +9 -5
  40. package/src/graphiti/knowledge-item-edit.js +7 -4
  41. package/src/graphiti/knowledge-reader.js +46 -0
  42. package/src/graphiti/knowledge-result-budget.js +63 -12
  43. package/src/graphiti/knowledge-tags.js +12 -1
  44. package/src/graphiti/provider-client.js +13 -21
  45. package/src/graphiti/publication-draft-capture.js +28 -0
  46. package/src/graphiti/session-knowledge-migration.js +7 -3
  47. package/src/graphiti/session-layer-decision.js +28 -6
  48. package/src/graphiti/session-records.js +26 -15
  49. package/src/graphiti/turn-receipt-delivery.js +5 -2
  50. package/src/graphiti/writing-taste-profile-workflow.js +13 -7
  51. package/src/http/api-router.js +2 -1
  52. package/src/http/graph-api-router.js +13 -10
  53. package/src/http/knowledge-item-api-router.js +17 -4
  54. package/src/http/knowledge-tags-api-router.js +21 -9
  55. package/src/http/session-records-api-router.js +7 -3
  56. package/src/knowledge-owner-reads/console-port.js +51 -0
  57. package/src/knowledge-tags/console-port.js +3 -2
  58. package/src/mcp/preference-delivery.js +7 -4
  59. package/src/mcp/provider-task-context-registry.js +15 -0
  60. package/src/mcp/tool-result.js +3 -3
  61. package/src/presence/windows-helper-pin.js +1 -1
  62. package/src/server.js +8 -1
@@ -103,6 +103,8 @@ import { resolveTaskEntryProject } from './task-entry-project-scope.js';
103
103
  import { createSessionPreferenceDelivery } from '../conversations/preference-session.js';
104
104
  import { transcriptCaptureLedger } from '../conversations/transcript-capture-gap.js';
105
105
  import { getWritingTasteProfile as getWritingTasteProfileWorkflow } from './writing-taste-profile-workflow.js';
106
+ import { providerReaderFields, taskKnowledgeReader } from './knowledge-reader.js';
107
+ import { queuePublicationDraft } from './publication-draft-capture.js';
106
108
  import { knowledgeTags } from './knowledge-tags.js';
107
109
  import { withSharedProjectList } from './shared-project-list.js';
108
110
 
@@ -266,19 +268,7 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
266
268
  const result = await this.personal.commit(commit);
267
269
  return { route: 'personal', ...result };
268
270
  }
269
- const draft = await this.personal.createPublicationDraft({
270
- personal_space_id: this.config.personal.spaceId,
271
- target_project_id: input.spaceId,
272
- provider_url: workspace.providerUrl,
273
- episode
274
- });
275
- return {
276
- route: 'personal_review',
277
- status: draft.status,
278
- draftId: draft.id,
279
- projectId: input.spaceId,
280
- providerUrl: workspace.providerUrl
281
- };
271
+ return queuePublicationDraft(this, { input, workspace, episode });
282
272
  }
283
273
 
284
274
  async recordWorkflowTransitionObservation(input) {
@@ -371,9 +361,9 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
371
361
  };
372
362
  }
373
363
 
374
- async getWritingTasteProfile(input = {}) {
364
+ async getWritingTasteProfile(input = {}, ownerReads = null) {
375
365
  this.#assertActivePersonalSpace(input.personalSpaceId);
376
- return getWritingTasteProfileWorkflow(this, input);
366
+ return getWritingTasteProfileWorkflow(this, input, ownerReads);
377
367
  }
378
368
 
379
369
  async #resolvePreferenceProject({ personalProjectId, projectPath }) {
@@ -476,26 +466,27 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
476
466
  });
477
467
  }
478
468
 
469
+ // An Agent reads as its FLA (projectAgentId) or a plain session: no other FLA's knowledge. Only the
470
+ // console passes ownerReads (src/knowledge-owner-reads) for the person's full read; an MCP call cannot.
479
471
  async getKnowledgeGraph({
480
472
  spaceId,
481
473
  providerUrl = null,
482
474
  personalProjectId = null,
475
+ projectAgentId = null,
483
476
  limit = 500,
484
477
  offset = null,
485
478
  agentInvocation = false,
486
479
  agentToolName = 'get_knowledge_graph',
487
480
  sourceApplication = null
488
- }) {
481
+ }, ownerReads = null) {
489
482
  if (!providerUrl) {
490
483
  if (spaceId !== this.config.personal.spaceId) {
491
484
  throw new TypeError('A configured providerUrl is required for a team-shared project graph');
492
485
  }
493
- const result = await this.personal.graph(
494
- spaceId,
495
- limit,
496
- personalProjectId,
497
- offset
498
- );
486
+ const result = ownerReads
487
+ ? await ownerReads.graph({ spaceId, limit, personalProjectId, offset })
488
+ : await this.personal.graph(spaceId, limit, personalProjectId, offset,
489
+ projectAgentId ? { personalProjectId, projectAgentId } : null);
499
490
  if (agentInvocation) {
500
491
  await this.#recordAgentViews([
501
492
  ...result.nodes.map(({ id }) => ({ item_id: id, item_kind: 'entity' })),
@@ -637,22 +628,20 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
637
628
  return knowledgeTags(this, operation, input);
638
629
  }
639
630
 
640
- async listPreferenceConflicts({
641
- personalSpaceId,
642
- status = null,
643
- limit = 500
644
- }) {
631
+ // An Agent reads as a plain session: no conflict naming an FLA's own item (an FLA meets those in its
632
+ // task context). Only the console passes ownerReads (src/knowledge-owner-reads) for the full list.
633
+ async listPreferenceConflicts({ personalSpaceId, status = null, limit = 500 }, ownerReads = null) {
645
634
  this.#assertActivePersonalSpace(personalSpaceId);
646
- return this.personal.listPreferenceConflicts(
647
- personalSpaceId,
648
- status,
649
- limit
650
- );
635
+ return ownerReads
636
+ ? ownerReads.preferenceConflicts({ personalSpaceId, status, limit })
637
+ : this.personal.listPreferenceConflicts(personalSpaceId, status, limit);
651
638
  }
652
639
 
653
- async deferPreferenceConflict(input) {
640
+ // A conflict naming an item its reader may not see answers as missing: an Agent names its FLA
641
+ // (projectAgentId) or reads as a plain session; the console's defer and completion pass ownerReads.
642
+ async deferPreferenceConflict(input, ownerReads = null) {
654
643
  this.#assertActivePersonalSpace(input.personalSpaceId);
655
- return this.personal.deferPreferenceConflict({
644
+ const body = {
656
645
  personal_space_id: input.personalSpaceId,
657
646
  conflict_id: input.conflictId,
658
647
  preference_key: input.preferenceKey,
@@ -664,13 +653,16 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
664
653
  right_item_kind: input.rightItemKind,
665
654
  reason: input.reason,
666
655
  operation_actor: input.operationActor ?? 'human'
667
- });
656
+ };
657
+ return ownerReads ? ownerReads.deferPreferenceConflict(body)
658
+ : this.personal.deferPreferenceConflict({ ...body, ...providerReaderFields(taskKnowledgeReader(input)) });
668
659
  }
669
660
 
670
661
  async resolveDeferredPreferenceConflict(input) {
671
662
  this.#assertActivePersonalSpace(input.personalSpaceId);
672
663
  assertSafeKnowledgeMutation(input);
673
664
  return this.personal.resolvePreferenceConflict(input.conflictId, {
665
+ ...providerReaderFields(taskKnowledgeReader(input)),
674
666
  personal_space_id: input.personalSpaceId,
675
667
  resolution: input.resolution,
676
668
  reason: input.reason,
@@ -682,14 +674,12 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
682
674
  });
683
675
  }
684
676
 
685
- async completePreferenceConflict(input) {
677
+ async completePreferenceConflict(input, ownerReads = null) {
686
678
  this.#assertActivePersonalSpace(input.personalSpaceId);
687
- return this.personal.completePreferenceConflict(input.conflictId, {
688
- personal_space_id: input.personalSpaceId,
689
- resolution: input.resolution,
690
- reason: input.reason,
691
- operation_actor: input.operationActor ?? 'human'
692
- });
679
+ const body = { personal_space_id: input.personalSpaceId, resolution: input.resolution, reason: input.reason,
680
+ operation_actor: input.operationActor ?? 'human' };
681
+ return ownerReads ? ownerReads.completePreferenceConflict(input.conflictId, body)
682
+ : this.personal.completePreferenceConflict(input.conflictId, body);
693
683
  }
694
684
 
695
685
  async confirmKnowledgeBatch(input) {
@@ -988,19 +978,17 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
988
978
  );
989
979
  }
990
980
 
991
- async listPersonalReviewQueue(input = {}) {
981
+ // An Agent's list leaves out a draft of an FLA's work (made before the Provider refused them);
982
+ // only the console passes ownerReads (src/knowledge-owner-reads) for the person's full list.
983
+ async listPersonalReviewQueue(input = {}, ownerReads = null) {
992
984
  const personalSpaceId = input.personalSpaceId ?? this.config.personal.spaceId;
993
985
  if (personalSpaceId !== this.config.personal.spaceId) {
994
986
  throw new TypeError('Personal review must use the active personal space');
995
987
  }
996
- await this.reconcilePersonalSubmissions();
997
- return {
998
- personalSpaceId,
999
- drafts: await this.personal.listPublicationDrafts(
1000
- personalSpaceId,
1001
- input.status ?? 'pending'
1002
- )
1003
- };
988
+ await this.reconcilePersonalSubmissions({}, ownerReads);
989
+ const status = input.status ?? 'pending';
990
+ return { personalSpaceId, drafts: ownerReads ? await ownerReads.publicationDrafts({ personalSpaceId, status })
991
+ : await this.personal.listPublicationDrafts(personalSpaceId, status) };
1004
992
  }
1005
993
 
1006
994
  async readRoleSuggestions({ limit } = {}) {
@@ -1009,21 +997,22 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
1009
997
  return this.roleSuggestions.list({ personalSpaceId, limit });
1010
998
  }
1011
999
 
1012
- reconcilePersonalSubmissions(options = {}) {
1013
- return reconcilePublicSubmissions({ personal: this.personal, workspaceFor: url => this.#workspace(url),
1014
- spaceId: this.config.personal.spaceId }, options);
1000
+ // ownerReads: the console's port, which alone lists and settles a draft of an FLA's work.
1001
+ reconcilePersonalSubmissions(options = {}, ownerReads = null) {
1002
+ return reconcilePublicSubmissions({ personal: ownerReads?.submissions ?? this.personal,
1003
+ workspaceFor: url => this.#workspace(url), spaceId: this.config.personal.spaceId }, options);
1015
1004
  }
1016
1005
 
1017
- async reviewPersonalDraft(input) {
1006
+ // ownerReads: the console's port; an Agent decides only a draft of positively plain work.
1007
+ async reviewPersonalDraft(input, ownerReads = null) {
1018
1008
  input = parsePersonalDraftDecision(input);
1019
1009
  const personalSpaceId = this.config.personal.spaceId;
1010
+ const personal = ownerReads?.submissions ?? this.personal;
1020
1011
  if (input.decision !== 'submit_public') {
1021
- return this.personal.decidePublicationDraft(personalSpaceId, input.draftId, {
1022
- decision: input.decision,
1023
- shared_proposal_id: null
1024
- });
1012
+ return personal.decidePublicationDraft(personalSpaceId, input.draftId, { decision: input.decision,
1013
+ shared_proposal_id: null });
1025
1014
  }
1026
- return submitPersonalDraft({ personal: this.personal, workspaceFor: url => this.#workspace(url),
1015
+ return submitPersonalDraft({ personal, workspaceFor: url => this.#workspace(url),
1027
1016
  spaceId: personalSpaceId, draftId: input.draftId });
1028
1017
  }
1029
1018
 
@@ -8,6 +8,9 @@ import { ProviderRequestError } from './provider-client.js';
8
8
  // operations that change real data on their word: a confirmed data format
9
9
  // migration (rec#17 D-09), a hard delete (rec#5 C9) and a change of where
10
10
  // knowledge applies, one item or a session's batch (rec#20, rec#11 D-22).
11
+ // The console's full reads of knowledge (graph, item, receipt, session
12
+ // records) take it too; without it the provider reads as an Agent and hides
13
+ // every FLA's own knowledge (src/knowledge-owner-reads).
11
14
  // Those provider routes also take the human-review token, which only the
12
15
  // provider's environment file in the data directory holds; an Agent's access
13
16
  // token alone is refused. Like D-21 this proves the local console, not that a
@@ -18,7 +21,7 @@ import { ProviderRequestError } from './provider-client.js';
18
21
 
19
22
  const REQUEST_TIMEOUT_MS = 30_000;
20
23
 
21
- // send(path, body, { review, timeoutMs }) -> { ok, status, payload }
24
+ // send(path, body, { review, timeoutMs, method }) -> { ok, status, payload }; a GET sends no body.
22
25
  export function personalHumanReviewChannel(dataDir, {
23
26
  fetchImpl = fetch,
24
27
  readText = (path) => readFileSync(path, 'utf8')
@@ -37,12 +40,13 @@ export function personalHumanReviewChannel(dataDir, {
37
40
  if (!token) throw new TypeError('The graph provider has no human-review channel; run fuli setup again');
38
41
  return token;
39
42
  };
40
- return async (path, body, { review = false, timeoutMs = REQUEST_TIMEOUT_MS } = {}) => {
43
+ return async (path, body, { review = false, timeoutMs = REQUEST_TIMEOUT_MS, method = 'POST' } = {}) => {
41
44
  const { providerUrl, accessToken } = connection();
42
- const headers = { authorization: `Bearer ${accessToken}`, 'content-type': 'application/json',
45
+ const headers = { authorization: `Bearer ${accessToken}`,
46
+ ...(method === 'GET' ? {} : { 'content-type': 'application/json' }),
43
47
  ...(review ? { 'x-fuli-human-review-token': reviewToken() } : {}) };
44
- const response = await fetchImpl(`${providerUrl}${path}`, { method: 'POST', headers,
45
- body: JSON.stringify(body ?? {}), signal: AbortSignal.timeout(timeoutMs) });
48
+ const response = await fetchImpl(`${providerUrl}${path}`, { method, headers,
49
+ ...(method === 'GET' ? {} : { body: JSON.stringify(body ?? {}) }), signal: AbortSignal.timeout(timeoutMs) });
46
50
  const payload = await response.json().catch(() => ({}));
47
51
  return { ok: response.ok, status: response.status, payload };
48
52
  };
@@ -3,6 +3,7 @@ import { requiredString, uniqueTextArray } from '../validation/values.js';
3
3
  import { MAX_LIST_EPISODES, readEpisodeReceipts } from '../agents/turn-receipt.js';
4
4
 
5
5
  // One knowledge item as the console's quick edit reads and moves it (rec#20).
6
+ // No MCP or Agent tool module calls these; the console passes its ports.
6
7
  // This host only checks and maps the request: the Provider reads the item back,
7
8
  // authorizes every project and FLA, and refuses an edit from a stale version.
8
9
  // A receipt link opens this flow; the link itself grants nothing.
@@ -11,19 +12,21 @@ const ITEM_KINDS = new Set(['entity', 'relationship']);
11
12
  const SCOPES = new Set(['global', 'projects', 'agent']);
12
13
  const MAX_SCOPE_PROJECTS = 16;
13
14
 
14
- export function readKnowledgeItem(application, input) {
15
+ // ownerReads: the console's port for the person's full reads, every FLA's
16
+ // items included (src/knowledge-owner-reads).
17
+ export function readKnowledgeItem(application, ownerReads, input) {
15
18
  const ref = itemRef(application, input);
16
- return application.personal.readKnowledgeItemView({ ...ref,
19
+ return ownerReads.itemView({ ...ref,
17
20
  ...(input.queryTags === undefined ? {} : { query_tags: input.queryTags }) });
18
21
  }
19
22
 
20
23
  // Everything one turn's episodes created or replaced, for the full list a
21
24
  // long receipt links to.
22
- export function readTurnReceiptItems(application, { personalSpaceId, episodeIds }) {
25
+ export function readTurnReceiptItems(application, ownerReads, { personalSpaceId, episodeIds }) {
23
26
  activeSpace(application, personalSpaceId);
24
27
  const episodes = uniqueTextArray(episodeIds, 'episodeIds', MAX_LIST_EPISODES);
25
28
  if (!episodes.length) invalid('episodes names at least one saved episode');
26
- return readEpisodeReceipts(application, episodes);
29
+ return readEpisodeReceipts(application, episodes, { read: ownerReads.turnReceipt });
27
30
  }
28
31
 
29
32
  // scopeConsole: the console port that sends it on the human-review channel (src/knowledge-scope).
@@ -0,0 +1,46 @@
1
+ // Who reads personal knowledge from the Provider (graph-provider
2
+ // knowledge_visibility.py). Knowledge an FLA wrote, and a preference given to
3
+ // one FLA, is that FLA's: an Agent reads it only as that FLA, in its project.
4
+ // An Agent read names the FLA of its task, or nothing for a plain session;
5
+ // the Provider authorizes the FLA it names. The person's full read is the
6
+ // console's alone and takes its human-review port (src/knowledge-owner-reads).
7
+
8
+ // The reader of a task: its FLA in its project, or null for a plain session.
9
+ export function taskKnowledgeReader(task) {
10
+ return task?.projectAgentId
11
+ ? { personalProjectId: task.personalProjectId ?? null, projectAgentId: task.projectAgentId }
12
+ : null;
13
+ }
14
+
15
+ // The reader as the Provider's request fields; a plain session names none.
16
+ export function providerReaderFields(reader) {
17
+ return reader?.projectAgentId
18
+ ? { reader_project_id: reader.personalProjectId, reader_agent_id: reader.projectAgentId }
19
+ : {};
20
+ }
21
+
22
+ // The Provider's graph read, for an Agent's reader or (none) the console's port.
23
+ export function graphReadPath(spaceId, { limit, personalProjectId = null, offset = null, reader = null }) {
24
+ const query = new URLSearchParams({ limit: String(limit) });
25
+ if (personalProjectId) query.set('personal_project_id', personalProjectId);
26
+ if (offset !== null) query.set('offset', String(offset));
27
+ for (const [key, value] of Object.entries(providerReaderFields(reader))) query.set(key, value);
28
+ return `/v1/spaces/${encodeURIComponent(spaceId)}/graph?${query}`;
29
+ }
30
+
31
+ // The Provider's preference conflicts. An Agent's read is a plain session's and
32
+ // leaves out every conflict naming an FLA's own item; the console's port reads all.
33
+ export function preferenceConflictsPath(personalSpaceId, { status = null, limit = 500, offset = 0 }) {
34
+ const query = new URLSearchParams({ personal_space_id: personalSpaceId, limit: String(limit) });
35
+ if (status) query.set('status', status);
36
+ if (offset) query.set('offset', String(offset));
37
+ return `/v1/preference-conflicts?${query}`;
38
+ }
39
+
40
+ // The Provider's publication drafts. An Agent's read leaves out a draft of an
41
+ // FLA's work, made before the Provider refused them; the console's port reads all.
42
+ export function publicationDraftsPath(personalSpaceId, { status = 'pending', metadataOnly = false } = {}) {
43
+ const query = new URLSearchParams({ personal_space_id: personalSpaceId, status });
44
+ if (metadataOnly) query.set('metadata_only', 'true');
45
+ return `/v1/publication-drafts?${query}`;
46
+ }
@@ -5,19 +5,30 @@ import { utf8Preview } from '../text/utf8-preview.js';
5
5
 
6
6
  export const AUTOMATIC_RECALL_BYTES = 4 * 1024;
7
7
  export const SEARCH_PAGE_BYTES = 8 * 1024;
8
+ const QUERY_PREVIEW_BYTES = 160;
9
+ const PROJECT_ID_LIST_BYTES = 512;
10
+ const PROJECT_ID_LISTS = ['searchedPersonalProjectIds', 'requestedProjectIds', 'searchedProjectIds', 'failedProjectIds'];
11
+ // What a search call derives from its scope rather than from one query's
12
+ // results. A compound search states each once when every query shares it.
13
+ const CALL_SCOPE_FIELDS = ['retrievalGuidance', 'noMatchSourceMarker', 'personalGlobalIncluded',
14
+ 'personalProjectScope', 'projectAgentId', ...PROJECT_ID_LISTS, 'project_ids_omitted', 'partial',
15
+ 'subscriptions_omitted'];
8
16
  const jsonBytes = value => Buffer.byteLength(JSON.stringify(value));
17
+ // Bounded by the bytes a page sends: JSON escaping turns a control character
18
+ // into six bytes and a quote or backslash into two.
19
+ const jsonPreview = (text, limit) => utf8Preview(text, limit, jsonBytes);
9
20
 
10
21
  function itemPreview(item, textBytes) {
11
22
  const result = { ...item };
12
23
  delete result.attributes;
13
24
  for (const key of ['name', 'type', 'source_entity', 'target_entity', 'relationship', 'fact', 'summary']) {
14
25
  if (typeof result[key] !== 'string') continue;
15
- const limited = utf8Preview(result[key], ['fact', 'summary'].includes(key) ? textBytes : 160);
26
+ const limited = jsonPreview(result[key], ['fact', 'summary'].includes(key) ? textBytes : 160);
16
27
  if (limited !== result[key]) result.text_truncated = true;
17
28
  result[key] = limited;
18
29
  }
19
30
  const sources = Array.isArray(item.source_uris) ? item.source_uris : [];
20
- result.source_uris = sources.filter(uri => typeof uri === 'string' && Buffer.byteLength(uri) <= 768).slice(0, 2);
31
+ result.source_uris = sources.filter(uri => typeof uri === 'string' && jsonBytes(uri) <= 768).slice(0, 2);
21
32
  if (sources.length > result.source_uris.length) result.source_uris_omitted = sources.length - result.source_uris.length;
22
33
  return result;
23
34
  }
@@ -85,21 +96,28 @@ export function budgetKnowledgeSearch(value, { cursor, context, consoleUrl,
85
96
  if (!Number.isSafeInteger(index) || !Number.isSafeInteger(offset) || index >= entries.length
86
97
  || offset >= Array.from(entries[index].serialized).length) throw staleCursor();
87
98
  }
88
- const whole = { ...value, retrieval_budget: { limit_bytes: SEARCH_PAGE_BYTES, complete: true } };
99
+ const whole = { ...(compound ? sharedScope(value, value.results) : value),
100
+ retrieval_budget: { limit_bytes: SEARCH_PAGE_BYTES, complete: true } };
89
101
  if (!cursor && jsonBytes(whole) <= SEARCH_PAGE_BYTES) return whole;
90
- const bases = groups.map(searchMetadata);
102
+ const top = compound ? sharedScope(searchMetadata(value), groups.map(searchMetadata)) : null;
103
+ const bases = compound ? top.results : [searchMetadata(value)];
91
104
  const selected = [];
92
105
  const render = (nextIndex, nextOffset = 0) => {
93
106
  const rendered = bases.map((base, group) => {
94
107
  const local = selected.filter(entry => entry.group === group);
108
+ const total_items = lists[group].length;
109
+ // A query with nothing on this page names itself and its count only;
110
+ // its details come with the page that carries its records.
111
+ if (compound && !local.length) return compactGroup(base, total_items);
95
112
  const facts = local.filter(entry => entry.kind === 'facts').map(entry => entry.view);
96
113
  const entities = local.filter(entry => entry.kind === 'entities').map(entry => entry.view);
97
- return { ...base, facts, entities, sourceMarker: marker({ facts, entities }, consoleUrl),
98
- noMatchSourceMarker: marker({}, consoleUrl) };
114
+ const view = { ...base, facts, entities, sourceMarker: marker({ facts, entities }, consoleUrl) };
115
+ return compound ? { ...view, total_items } : { ...view, noMatchSourceMarker: marker({}, consoleUrl) };
99
116
  });
100
117
  const next = nextIndex < entries.length ? encode(nextIndex, nextOffset) : null;
101
- return { ...(compound ? { ...searchMetadata(value), results: rendered } : rendered[0]),
102
- retrieval_budget: { limit_bytes: SEARCH_PAGE_BYTES, complete: !next, returned_items: selected.length },
118
+ return { ...(compound ? { ...top, noMatchSourceMarker: marker({}, consoleUrl), results: rendered } : rendered[0]),
119
+ retrieval_budget: { limit_bytes: SEARCH_PAGE_BYTES, complete: !next, returned_items: selected.length,
120
+ total_items: entries.length },
103
121
  ...(next ? { next_cursor: next, continuation_tool: 'fuli_call', continuation_tool_name: toolName,
104
122
  continuation_guidance: 'Repeat the same search and scope with next_cursor as cursor through fuli_call; do not widen scope.' } : {}) };
105
123
  };
@@ -142,24 +160,57 @@ function identityPreview(item) {
142
160
  .filter(key => item[key] !== undefined).map(key => [key, item[key]]));
143
161
  }
144
162
 
163
+ // Fields every query group shares move to the top level once; a field that
164
+ // differs between queries stays on each group.
165
+ function sharedScope(top, groups) {
166
+ const shared = CALL_SCOPE_FIELDS.filter(key => groups.length && !(key in top) && key in groups[0]
167
+ && groups.every(group => key in group && JSON.stringify(group[key]) === JSON.stringify(groups[0][key])));
168
+ return { ...top, ...Object.fromEntries(shared.map(key => [key, groups[0][key]])),
169
+ results: groups.map(group => Object.fromEntries(Object.entries(group).filter(([key]) => !shared.includes(key)))) };
170
+ }
171
+
172
+ function compactGroup(base, total_items) {
173
+ return { query: base.query, total_items,
174
+ ...Object.fromEntries(CALL_SCOPE_FIELDS.filter(key => key in base).map(key => [key, base[key]])) };
175
+ }
176
+
177
+ // Scope lists are informational: a continuation re-runs the search from its
178
+ // own input, so a page may name a prefix and count the rest.
179
+ function boundedIds(ids) {
180
+ const kept = [];
181
+ for (const id of ids) {
182
+ if (jsonBytes([...kept, id]) > PROJECT_ID_LIST_BYTES) break;
183
+ kept.push(id);
184
+ }
185
+ return kept;
186
+ }
187
+
145
188
  function searchMetadata(value) {
146
189
  const { facts, entities, results, sourceMarker, noMatchSourceMarker, subscriptions,
147
190
  relatedProjectSuggestions, related_project_suggestions, ...rest } = value;
148
191
  const result = { ...rest };
149
- if (typeof result.query === 'string') result.query = utf8Preview(result.query, 256);
192
+ if (typeof result.query === 'string') result.query = jsonPreview(result.query, QUERY_PREVIEW_BYTES);
150
193
  if (subscriptions?.length) result.subscriptions_omitted = subscriptions.length;
194
+ for (const key of PROJECT_ID_LISTS) {
195
+ if (!Array.isArray(result[key])) continue;
196
+ const kept = boundedIds(result[key]);
197
+ if (kept.length < result[key].length) {
198
+ result.project_ids_omitted = { ...result.project_ids_omitted, [key]: result[key].length - kept.length };
199
+ }
200
+ result[key] = kept;
201
+ }
151
202
  for (const [key, items] of [['relatedProjectSuggestions', relatedProjectSuggestions],
152
203
  ['related_project_suggestions', related_project_suggestions]]) {
153
204
  if (!Array.isArray(items)) continue;
154
205
  result[key] = items.slice(0, 3).map(item => ({ ...item,
155
- project_name: typeof item.project_name === 'string' ? utf8Preview(item.project_name, 160) : item.project_name,
156
- reason: typeof item.reason === 'string' ? utf8Preview(item.reason, 256) : item.reason }));
206
+ project_name: typeof item.project_name === 'string' ? jsonPreview(item.project_name, 160) : item.project_name,
207
+ reason: typeof item.reason === 'string' ? jsonPreview(item.reason, 256) : item.reason }));
157
208
  if (items.length > 3) result.related_suggestions_omitted = items.length - 3;
158
209
  }
159
210
  // Detailed suggestions remain available on focused queries. Permission flags
160
211
  // and exact confirmed_search targets above are retained, never inferred.
161
212
  for (const key of ['relatedProjectGuidance', 'related_project_guidance']) {
162
- if (typeof result[key] === 'string') result[key] = utf8Preview(result[key], 512);
213
+ if (typeof result[key] === 'string') result[key] = jsonPreview(result[key], 512);
163
214
  }
164
215
  return result;
165
216
  }
@@ -15,6 +15,7 @@ const ROUTES = Object.freeze({
15
15
  create: 'create', add_alias: 'aliases', attach: 'attach', detach: 'detach'
16
16
  });
17
17
  const CHANGES = new Set(['create', 'add_alias', 'attach', 'detach']);
18
+ const ACROSS_PROJECTS = new Set(['metrics', 'vocabulary', 'detail', 'governance_preview']);
18
19
  // What an Agent may ask the person for; the person also removes aliases and relates tags.
19
20
  const PROPOSALS = new Set(['approve', 'merge', 'split', 'retire', 'undo']);
20
21
  // revive: the person's create of a retired word that would drop something comes back as a preview.
@@ -84,6 +85,16 @@ export async function personKnowledgeTagChange(application, tagsConsole, input)
84
85
  : result;
85
86
  }
86
87
 
88
+ // The owner's console view across every project: vocabulary, detail, metrics
89
+ // and a governance preview. It lists and counts the links of every FLA's own
90
+ // knowledge, so the Provider answers it only on the human-review channel
91
+ // tagsConsole sends on; an Agent reads its own scope (allProjects false).
92
+ export function readTagsAcrossProjects(application, tagsConsole, operation, input) {
93
+ if (!ACROSS_PROJECTS.has(operation)) throw new TypeError(`Unknown knowledge tag read: ${operation}`);
94
+ activeSpace(application, input.personalSpaceId);
95
+ return tagsConsole.send(ROUTES[operation], { ...scope(input), ...BODIES[operation]({ ...input, allProjects: true }) });
96
+ }
97
+
87
98
  // The person's governance, applied naming the digest of the preview they saw.
88
99
  export function applyTagGovernance(application, tagsConsole, input) {
89
100
  if (!GOVERNANCE.has(input.change)) invalid('change must be a tag governance change');
@@ -129,7 +140,7 @@ function changedBy(input) {
129
140
 
130
141
  function activeSpace(application, personalSpaceId) {
131
142
  if (personalSpaceId !== application.config.personal.spaceId) {
132
- invalid('Tags are changed in the active personal space');
143
+ invalid('Tags are read and changed in the active personal space');
133
144
  }
134
145
  }
135
146
 
@@ -1,5 +1,6 @@
1
1
  import { ApplicationError } from '../app/application-error.js';
2
2
  import { activeAgentRequestSignal } from '../app/agent-request-context.js';
3
+ import { graphReadPath, preferenceConflictsPath, publicationDraftsPath } from './knowledge-reader.js';
3
4
  import { preferenceTaskSession } from './preference-task-scope.js';
4
5
  import { afterProjectWrite, sharedProjectList } from './shared-project-list.js';
5
6
 
@@ -637,10 +638,8 @@ export class GraphitiProviderClient {
637
638
  method: 'POST', body: { personal_space_id: personalSpaceId }
638
639
  });
639
640
  }
640
- // rec#20: authoritative item views and a turn's receipt.
641
- readKnowledgeItemView(input) {
642
- return this.#request('/v1/knowledge/item-views', { method: 'POST', body: input });
643
- }
641
+ // rec#20: a turn's receipt as an Agent reads it (knowledge-reader.js). The
642
+ // console's item views and full reads use its own port (src/knowledge-owner-reads).
644
643
  readTurnReceipt(input) {
645
644
  return this.#request('/v1/knowledge/turn-receipts', { method: 'POST', body: input });
646
645
  }
@@ -648,8 +647,10 @@ export class GraphitiProviderClient {
648
647
  readSessionRecords(input) {
649
648
  return this.#request('/v1/session-records', { method: 'POST', body: input });
650
649
  }
651
- // rec#20 part 2: what a session's temporary project holds. Scope writes go
652
- // through the console's human-review channel (src/knowledge-scope).
650
+ // rec#20 part 2: what a session's temporary project holds, as an Agent's
651
+ // offer reads it (knowledge-reader.js). The console's page reads it through
652
+ // its own port (src/knowledge-owner-reads); scope writes go through the
653
+ // console's human-review channel (src/knowledge-scope).
653
654
  previewSessionMigration(input) {
654
655
  return this.#request('/v1/knowledge/session-migrations/preview', { method: 'POST', body: input });
655
656
  }
@@ -669,9 +670,7 @@ export class GraphitiProviderClient {
669
670
  return this.#request('/v1/publication-drafts', { method: 'POST', body: input });
670
671
  }
671
672
  listPublicationDrafts(personalSpaceId, status = 'pending', { metadataOnly = false, ...options } = {}) {
672
- const query = new URLSearchParams({ personal_space_id: personalSpaceId, status });
673
- if (metadataOnly) query.set('metadata_only', 'true');
674
- return this.#request(`/v1/publication-drafts?${query}`, options);
673
+ return this.#request(publicationDraftsPath(personalSpaceId, { status, metadataOnly }), options);
675
674
  }
676
675
  getPublicationDraft(personalSpaceId, draftId) {
677
676
  const query = new URLSearchParams({ personal_space_id: personalSpaceId });
@@ -864,14 +863,9 @@ export class GraphitiProviderClient {
864
863
  method: 'POST', body: input
865
864
  });
866
865
  }
866
+ // An Agent's read, as a plain session; the console's full list uses its own port (src/knowledge-owner-reads).
867
867
  listPreferenceConflicts(personalSpaceId, status = null, limit = 500, offset = 0) {
868
- const query = new URLSearchParams({
869
- personal_space_id: personalSpaceId,
870
- limit: String(limit)
871
- });
872
- if (status) query.set('status', status);
873
- if (offset) query.set('offset', String(offset));
874
- return this.#request(`/v1/preference-conflicts?${query}`);
868
+ return this.#request(preferenceConflictsPath(personalSpaceId, { status, limit, offset }));
875
869
  }
876
870
  resolvePreferenceConflict(conflictId, input) {
877
871
  return this.#request(
@@ -939,11 +933,9 @@ export class GraphitiProviderClient {
939
933
  }
940
934
  return this.#request(`/v1/collaboration-preferences?${query}`);
941
935
  }
942
- graph(spaceId, limit = 500, personalProjectId = null, offset = null) {
943
- const query = new URLSearchParams({ limit: String(limit) });
944
- if (personalProjectId) query.set('personal_project_id', personalProjectId);
945
- if (offset !== null) query.set('offset', String(offset));
946
- return this.#request(`/v1/spaces/${encodeURIComponent(spaceId)}/graph?${query}`);
936
+ // An Agent's read (knowledge-reader.js): reader names its FLA, or null for a plain session.
937
+ graph(spaceId, limit = 500, personalProjectId = null, offset = null, reader = null) {
938
+ return this.#request(graphReadPath(spaceId, { limit, personalProjectId, offset, reader }));
947
939
  }
948
940
 
949
941
  // A long-running client (an MCP server) outlives a token rotation, for
@@ -0,0 +1,28 @@
1
+ import { receiptConsoleUrl } from '../agents/identity-receipt.js';
2
+ import { ProviderRequestError } from './provider-client.js';
3
+
4
+ // A capture for a team project waits as a local pre-review draft until the
5
+ // person submits it from the console's publish queue. The Provider answers a
6
+ // create that meets an existing draft this caller may not read exactly as a
7
+ // missing draft (0.20.1): a team-only draft is the person's alone, and a
8
+ // self-reported source is no proof that it is the same create. A 404 here
9
+ // proves nothing either way (a retry after a lost reply, or any other miss),
10
+ // so the capture is reported unconfirmed: neither saved nor lost, no cause guessed.
11
+ const UNCONFIRMED = 'Cannot confirm whether this capture was saved; check the publish queue in the FULI console.';
12
+
13
+ export async function queuePublicationDraft(application, { input, workspace, episode }) {
14
+ const queued = { route: 'personal_review', projectId: input.spaceId, providerUrl: workspace.providerUrl };
15
+ try {
16
+ const draft = await application.personal.createPublicationDraft({
17
+ personal_space_id: application.config.personal.spaceId,
18
+ target_project_id: input.spaceId,
19
+ provider_url: workspace.providerUrl,
20
+ episode
21
+ });
22
+ return { ...queued, status: draft.status, draftId: draft.id };
23
+ } catch (error) {
24
+ if (!(error instanceof ProviderRequestError && error.status === 404)) throw error;
25
+ return { ...queued, status: 'unconfirmed', message: UNCONFIRMED,
26
+ reviewUrl: `${receiptConsoleUrl(application)}/public-projects` };
27
+ }
28
+ }
@@ -1,6 +1,7 @@
1
1
  import { ApplicationError, ApplicationErrorCode } from '../app/application-error.js';
2
2
  import { receiptConsoleUrl } from '../agents/identity-receipt.js';
3
3
  import { requiredString } from '../validation/values.js';
4
+ import { providerReaderFields, taskKnowledgeReader } from './knowledge-reader.js';
4
5
  import { isTemporaryProjectId } from './temporary-project-scope.js';
5
6
 
6
7
  // rec#20 part 2: what a host session saved while nobody chose where it applies
@@ -20,10 +21,12 @@ const MAX_PROJECT_ID = 128;
20
21
  const MAX_ITEMS = 100;
21
22
 
22
23
  // One page of the held items, oldest first; offset is where the page starts.
23
- export function readSessionMigration(application, input) {
24
+ // ownerReads: the console's port (src/knowledge-owner-reads), so the person's
25
+ // page lists and counts every FLA's held items.
26
+ export function readSessionMigration(application, ownerReads, input) {
24
27
  const offset = input.offset === null || input.offset === undefined || input.offset === '' ? 0 : Number(input.offset);
25
28
  if (!Number.isInteger(offset) || offset < 0) invalid('offset must be where a page of held items starts');
26
- return application.personal.previewSessionMigration({ ...target(application, input), include_items: true, offset });
29
+ return ownerReads.sessionMigration({ ...target(application, input), include_items: true, offset });
27
30
  }
28
31
 
29
32
  // scopeConsole: the console port that sends it on the human-review channel (src/knowledge-scope).
@@ -56,11 +59,12 @@ export function sessionMigrationLine(application, task, { heldCount = null } = {
56
59
  }
57
60
 
58
61
  // The entry's offer once a session links to a formal project; never blocks the entry.
62
+ // It reads as the task's FLA or plain session, so another FLA's held items are not counted.
59
63
  export async function sessionMigrationOffer(application, task) {
60
64
  if (!formalTask(task)) return null;
61
65
  try {
62
66
  const pending = await application.personal.previewSessionMigration({ ...providerTarget(application, task),
63
- include_items: false });
67
+ include_items: false, ...providerReaderFields(taskKnowledgeReader(task)) });
64
68
  if (!(pending?.held_count > 0) || pending.linked_task_count > 1) return null;
65
69
  return sessionMigrationLine(application, task, { heldCount: pending.held_count });
66
70
  } catch {