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

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 (49) hide show
  1. package/dist/web/assets/{index-DvkJiX-L.js → index-BDCkW4Ii.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/src/agent-tools/graph-definitions.js +4 -4
  28. package/src/agent-tools/interface-definitions.js +2 -1
  29. package/src/agents/turn-receipt.js +15 -8
  30. package/src/graphiti/federated-application.js +49 -60
  31. package/src/graphiti/human-review-channel.js +9 -5
  32. package/src/graphiti/knowledge-item-edit.js +7 -4
  33. package/src/graphiti/knowledge-reader.js +46 -0
  34. package/src/graphiti/knowledge-tags.js +12 -1
  35. package/src/graphiti/provider-client.js +13 -21
  36. package/src/graphiti/publication-draft-capture.js +28 -0
  37. package/src/graphiti/session-knowledge-migration.js +7 -3
  38. package/src/graphiti/session-records.js +26 -15
  39. package/src/graphiti/turn-receipt-delivery.js +5 -2
  40. package/src/graphiti/writing-taste-profile-workflow.js +13 -7
  41. package/src/http/api-router.js +2 -1
  42. package/src/http/graph-api-router.js +13 -10
  43. package/src/http/knowledge-item-api-router.js +17 -4
  44. package/src/http/knowledge-tags-api-router.js +21 -9
  45. package/src/http/session-records-api-router.js +7 -3
  46. package/src/knowledge-owner-reads/console-port.js +51 -0
  47. package/src/knowledge-tags/console-port.js +3 -2
  48. package/src/presence/windows-helper-pin.js +1 -1
  49. package/src/server.js +8 -1
@@ -15,19 +15,43 @@ from .models import (
15
15
  SubscriptionRecord,
16
16
  )
17
17
  from .provider_values import json_object, native_datetime, now_utc, stable_uuid
18
- from .publication_source_copies import publication_source_identity
18
+ from .publication_source_copies import PLAIN, PROJECT_AGENT, draft_sources, publication_source_identity
19
19
  from .knowledge_source_fence import require_source_available
20
20
  from .knowledge_versions import lock_knowledge
21
21
  from .store_transactions import query_store_transaction
22
22
  from .publication_submission import decide_submission
23
23
  from .publication_submission_models import PublicationSubmissionDecision
24
24
 
25
+ # An FLA's own knowledge stays in the personal graph; Node refuses to queue it
26
+ # for a team project and so does the Provider (0.20.1).
27
+ _PROJECT_AGENT_KNOWLEDGE = {'code': 'project_agent_knowledge_personal_only',
28
+ 'message': 'Project Agent knowledge can only be captured in the personal graph'}
29
+
30
+
31
+ def _draft_identity(space, draft) -> dict:
32
+ """A stored draft's source identity; older drafts derive it from the payload."""
33
+ return {**publication_source_identity(space['group_id'], json_object(draft.get('payload'))),
34
+ **json_object(draft.get('source_identity'))}
35
+
25
36
 
26
37
  class StorePublication:
38
+ async def _project_agent_drafts(self, actor, space, drafts) -> set[int]:
39
+ """The positions among these drafts a reader without the human-review
40
+ proof may not see: every one whose source is not positively plain
41
+ work. A draft of an FLA's work (made before the Provider refused them),
42
+ and one whose source is erased or was never recorded here, is the
43
+ person's alone, its body, source and submission metadata alike; the
44
+ console's port lists, reads, submits and settles it."""
45
+ if actor.get('_human_review_verified') is True:
46
+ return set()
47
+ owners = await draft_sources(self, space, [_draft_identity(space, draft) for draft in drafts])
48
+ return {index for index, owner in enumerate(owners) if owner != PLAIN}
49
+
27
50
  async def decide_publication_submission(self, actor, personal_space_id, draft_id, decision):
28
51
  """Internal submission protocol; every transition serializes with erasure."""
29
52
  self._require_personal()
30
53
  space = await self.authorize(actor, personal_space_id, 'maintainer')
54
+ await self._refuse_project_agent_draft(actor, space, draft_id, decision.decision)
31
55
  refusal = None
32
56
  async with query_store_transaction(self) as scoped:
33
57
  await lock_knowledge(scoped, space)
@@ -62,9 +86,13 @@ class StorePublication:
62
86
  await require_source_available(scoped, space, episode_id=identity.get('episode_id'),
63
87
  source_application=identity.get('source_application'), session_id=identity.get('session_id'),
64
88
  source_turn_id=identity.get('source_turn_id'))
89
+ if (await draft_sources(scoped, space, [identity])) == [PROJECT_AGENT]:
90
+ raise HTTPException(status_code=422, detail=_PROJECT_AGENT_KNOWLEDGE)
65
91
  records, _, _ = await scoped.runtime.driver.execute_query(
66
92
  '''
67
93
  MATCH (space:FuliSpace {id: $personal_space_id, kind: 'personal'})
94
+ OPTIONAL MATCH (stored:FuliPublicationDraft {id: $id})
95
+ WITH space, stored IS NOT NULL AS existed
68
96
  MERGE (draft:FuliPublicationDraft {id: $id})
69
97
  ON CREATE SET draft.personal_space_id = $personal_space_id,
70
98
  draft.target_project_id = $target_project_id,
@@ -74,7 +102,7 @@ class StorePublication:
74
102
  draft.source_identity = $source_identity,
75
103
  draft.created_at = $created_at
76
104
  MERGE (space)-[:HAS_PUBLICATION_DRAFT]->(draft)
77
- RETURN draft
105
+ RETURN draft, existed
78
106
  ''',
79
107
  personal_space_id=request.personal_space_id,
80
108
  id=draft_id,
@@ -84,7 +112,14 @@ class StorePublication:
84
112
  source_identity=json.dumps(identity, sort_keys=True, separators=(',', ':')),
85
113
  created_at=created_at,
86
114
  )
87
- return self._publication_draft(records[0]['draft'])
115
+ draft = dict(records[0]['draft'])
116
+ # A retry of a key already drafted gets the stored draft back unchanged, so it is judged by
117
+ # the STORED row's provenance, not the request's. One this caller may not read is answered
118
+ # exactly as a draft that does not exist, whatever the request claims about its source: a
119
+ # self-reported identity is no proof that it is the same create (0.20.1).
120
+ if records[0]['existed'] and await self._project_agent_drafts(actor, space, [draft]):
121
+ raise HTTPException(status_code=404, detail='publication draft not found')
122
+ return self._publication_draft(draft)
88
123
 
89
124
  async def list_publication_drafts(
90
125
  self,
@@ -107,10 +142,11 @@ class StorePublication:
107
142
  status=draft_status,
108
143
  routing_='r',
109
144
  )
110
- return [self._publication_draft({**dict(record['draft']), 'source_identity': json.dumps({
111
- **publication_source_identity(space['group_id'], json_object(record['draft'].get('payload'))),
112
- **json_object(record['draft'].get('source_identity'))})}, metadata_only=metadata_only)
113
- for record in records]
145
+ drafts = [dict(record['draft']) for record in records]
146
+ hidden = await self._project_agent_drafts(actor, space, drafts)
147
+ return [self._publication_draft({**draft, 'source_identity': json.dumps(_draft_identity(space, draft))},
148
+ metadata_only=metadata_only)
149
+ for index, draft in enumerate(drafts) if index not in hidden]
114
150
 
115
151
  async def get_publication_draft(
116
152
  self,
@@ -119,7 +155,30 @@ class StorePublication:
119
155
  draft_id: str,
120
156
  ) -> PublicationDraftRecord:
121
157
  self._require_personal()
122
- await self.authorize(actor, personal_space_id, 'reader')
158
+ space = await self.authorize(actor, personal_space_id, 'reader')
159
+ draft = await self._stored_draft(space, draft_id)
160
+ if draft is None or await self._project_agent_drafts(actor, space, [draft]):
161
+ raise HTTPException(status_code=404, detail='publication draft not found')
162
+ return self._publication_draft(draft)
163
+
164
+ async def _refuse_project_agent_draft(self, actor, space, draft_id, decision: str) -> None:
165
+ """A decision on a draft whose source is not positively plain work: to
166
+ a caller without the human-review proof it does not exist, so no reply
167
+ carries its body, source or attempt. The person's console decides it;
168
+ a draft of an FLA's work it settles, keeps or ignores, but never starts
169
+ publishing. A missing draft is left to the decision's own answer."""
170
+ draft = await self._stored_draft(space, draft_id)
171
+ if draft is None:
172
+ return
173
+ [owner] = await draft_sources(self, space, [_draft_identity(space, draft)])
174
+ if owner == PLAIN:
175
+ return
176
+ if actor.get('_human_review_verified') is not True:
177
+ raise HTTPException(status_code=404, detail='publication draft not found')
178
+ if owner == PROJECT_AGENT and decision == 'begin_submit_public':
179
+ raise HTTPException(status_code=422, detail=_PROJECT_AGENT_KNOWLEDGE)
180
+
181
+ async def _stored_draft(self, space, draft_id) -> dict | None:
123
182
  records, _, _ = await self.runtime.driver.execute_query(
124
183
  '''
125
184
  MATCH (:FuliSpace {id: $personal_space_id, kind: 'personal'})-
@@ -127,13 +186,11 @@ class StorePublication:
127
186
  (draft:FuliPublicationDraft {id: $draft_id})
128
187
  RETURN draft
129
188
  ''',
130
- personal_space_id=personal_space_id,
189
+ personal_space_id=space['id'],
131
190
  draft_id=draft_id,
132
191
  routing_='r',
133
192
  )
134
- if not records:
135
- raise HTTPException(status_code=404, detail='publication draft not found')
136
- return self._publication_draft(records[0]['draft'])
193
+ return dict(records[0]['draft']) if records else None
137
194
 
138
195
  async def decide_publication_draft(
139
196
  self,
@@ -146,6 +203,7 @@ class StorePublication:
146
203
  return await self.decide_publication_submission(actor, personal_space_id, draft_id, decision)
147
204
  self._require_personal()
148
205
  space = await self.authorize(actor, personal_space_id, 'maintainer')
206
+ await self._refuse_project_agent_draft(actor, space, draft_id, decision.decision)
149
207
  records, _, _ = await self.runtime.driver.execute_query(
150
208
  '''
151
209
  MATCH (:FuliSpace {id: $personal_space_id, kind: 'personal'})-
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "fuli-graph-provider"
3
- version = "0.20.0b13"
3
+ version = "0.20.0b14"
4
4
  description = "Graphiti-backed personal and shared project provider for Fuli."
5
5
  requires-python = ">=3.12"
6
6
  dependencies = [
Binary file
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "fuli-context",
3
- "version": "0.20.0-beta.13",
3
+ "version": "0.20.0-beta.14",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "fuli-context",
9
- "version": "0.20.0-beta.13",
9
+ "version": "0.20.0-beta.14",
10
10
  "license": "Apache-2.0",
11
11
  "dependencies": {
12
12
  "@a2a-js/sdk": "1.3.0",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fuli-context",
3
- "version": "0.20.0-beta.13",
3
+ "version": "0.20.0-beta.14",
4
4
  "description": "Local-first collaboration relationship graph for AI agents.",
5
5
  "type": "module",
6
6
  "files": [
@@ -383,9 +383,9 @@ export const GRAPH_TOOL_DEFINITIONS = [
383
383
  },
384
384
  {
385
385
  name: 'resolve_deferred_preference_conflict',
386
- description: 'Resolve one AI-deferred conflict from get_collaboration_preferences only when the current task needs that preference. Compare both confirmed sides with their evidence and current context before choosing. Updates effective knowledge, preserves revision history, and permanently marks prior conflict as resolved by AI. Use merge with canonical item and merged instruction, keep_left/keep_right to retain one side, or split_scope to move one side to an exact personal project.',
386
+ description: 'Resolve one AI-deferred conflict from get_collaboration_preferences only when the current task needs that preference. Compare both confirmed sides with their evidence and current context before choosing. Updates effective knowledge, preserves revision history, and permanently marks prior conflict as resolved by AI. Use merge with canonical item and merged instruction, keep_left/keep_right to retain one side, or split_scope to move one side to an exact personal project. An FLA names projectAgentId and personalProjectId.',
387
387
  inputSchema: objectSchema({
388
- personalSpaceId: id,
388
+ personalSpaceId: id, personalProjectId: nullableStringSchema(), projectAgentId: nullableStringSchema(),
389
389
  conflictId: boundedString(1024),
390
390
  resolution: enumSchema([
391
391
  'merge', 'keep_left', 'keep_right', 'split_scope'
@@ -621,11 +621,11 @@ export const GRAPH_TOOL_DEFINITIONS = [
621
621
  },
622
622
  {
623
623
  name: 'get_knowledge_graph',
624
- description: 'Return a bounded node-edge graph for a personal space, one exact local personal project, or a team-shared project.',
624
+ description: 'Return a bounded node-edge graph for a personal space, one exact local personal project, or a team-shared project. An FLA sees its own knowledge only with projectAgentId and personalProjectId.',
625
625
  inputSchema: objectSchema({
626
626
  spaceId: id,
627
627
  providerUrl: nullableStringSchema(),
628
- personalProjectId: nullableStringSchema(),
628
+ personalProjectId: nullableStringSchema(), projectAgentId: nullableStringSchema(),
629
629
  limit: integerSchema({ minimum: 1, maximum: 2000 })
630
630
  }, ['spaceId'])
631
631
  },
@@ -184,9 +184,10 @@ export const AGENT_INTERFACE_DEFINITIONS = [
184
184
  {
185
185
  name: 'defer_preference_conflict',
186
186
  title: 'WRITE · Defer preference conflict',
187
- description: 'Defer one exact preference conflict without resolving either side. The conflict remains visible for later review.',
187
+ description: 'Defer one exact preference conflict without resolving either side. The conflict remains visible for later review. An FLA names projectAgentId and personalProjectId.',
188
188
  inputSchema: objectSchema({
189
189
  personalSpaceId: id,
190
+ personalProjectId: nullableStringSchema(), projectAgentId: nullableStringSchema(),
190
191
  conflictId: { ...stringSchema(), minLength: 1, maxLength: 1024 },
191
192
  preferenceKey: label,
192
193
  preferenceScope: enumSchema(['global', 'project']),
@@ -1,4 +1,5 @@
1
1
  import { receiptConsoleUrl, receiptSummary, receiptText, sessionRecordsUrl } from './identity-receipt.js';
2
+ import { providerReaderFields } from '../graphiti/knowledge-reader.js';
2
3
 
3
4
  // The per-turn receipt (rec#20): after a turn's checkpoint saved knowledge, the
4
5
  // reply tail lists every item that turn actually created or replaced, read back
@@ -34,10 +35,12 @@ function turnReceiptListUrl(application, episodeIds) {
34
35
  // The receipt of saved capture results: null when nothing substantive changed.
35
36
  // memory is the Agent working-memory write this checkpoint made, if any.
36
37
  // session: { sourceApplication, sessionId } of the turn, for the session link.
38
+ // reader: the turn's FLA (knowledge-reader.js), or null for a plain session.
37
39
  export async function readTurnReceipt(application, captureResults, { memory = null, agentName = null,
38
- heading = '本轮沉淀', session = null } = {}) {
40
+ heading = '本轮沉淀', session = null, reader = null } = {}) {
39
41
  const episodeIds = savedEpisodeIds(captureResults);
40
- const { entries } = episodeIds.length ? await readEpisodeReceipts(application, episodeIds) : { entries: [] };
42
+ const { entries } = episodeIds.length ? await readEpisodeReceipts(application, episodeIds, { reader })
43
+ : { entries: [] };
41
44
  return renderTurnReceipt(application, entries, { episodeIds, memory, agentName, heading, session });
42
45
  }
43
46
 
@@ -52,19 +55,23 @@ export function renderTurnReceipt(application, entries, { episodeIds, memory = n
52
55
 
53
56
  // What the episodes created or replaced, read in the Provider's batches and
54
57
  // merged, so a late receipt of several turns and its full list read the same.
55
- export async function readEpisodeReceipts(application, episodeIds) {
58
+ // An Agent's receipt reads as its reader and leaves out every other FLA's
59
+ // items; the console's full list passes read, its human-review port.
60
+ export async function readEpisodeReceipts(application, episodeIds, {
61
+ reader = null, read = body => application.personal.readTurnReceipt({ ...body, ...providerReaderFields(reader) })
62
+ } = {}) {
56
63
  const entries = new Map();
57
64
  let unchanged = 0;
58
65
  const deletions = new Set();
59
66
  for (let start = 0; start < episodeIds.length; start += EPISODES_PER_READ) {
60
- const read = await application.personal.readTurnReceipt({ personal_space_id: application.config.personal.spaceId,
67
+ const batch = await read({ personal_space_id: application.config.personal.spaceId,
61
68
  episode_ids: episodeIds.slice(start, start + EPISODES_PER_READ) });
62
- if (!Array.isArray(read?.entries)) throw new TypeError('Provider did not return the turn receipt');
63
- for (const entry of read.entries) entries.set(`${entry.item_kind}:${entry.item_id}`, entry);
64
- unchanged += read.unchanged_count ?? 0;
69
+ if (!Array.isArray(batch?.entries)) throw new TypeError('Provider did not return the turn receipt');
70
+ for (const entry of batch.entries) entries.set(`${entry.item_kind}:${entry.item_id}`, entry);
71
+ unchanged += batch.unchanged_count ?? 0;
65
72
  // What a person hard-deleted since (rec#5 C9), each delete once even when
66
73
  // its sources span two reads.
67
- for (const id of read.deletion_ids ?? []) deletions.add(id);
74
+ for (const id of batch.deletion_ids ?? []) deletions.add(id);
68
75
  }
69
76
  return { entries: [...entries.values()], unchanged_count: unchanged, deleted_count: deletions.size };
70
77
  }
@@ -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
+ }
@@ -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