fuli-context 0.25.0 → 0.25.2

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 (42) hide show
  1. package/README.md +1 -1
  2. package/README.zh-CN.md +1 -1
  3. package/dist/web/assets/{CopyFixPrompt-CErC3Paj.js → CopyFixPrompt-CVFYWDSt.js} +1 -1
  4. package/dist/web/assets/{OverviewPage-DFW3Ua0Z.js → OverviewPage-_9e2idJR.js} +1 -1
  5. package/dist/web/assets/{SettingsPage-BVIU7iFS.js → SettingsPage-bLssMIz6.js} +1 -1
  6. package/dist/web/assets/{index-C7IVLf_v.js → index-C2VDC1uO.js} +3 -3
  7. package/dist/web/assets/{version-1lwoVj6f.js → version-lXtOG8uf.js} +1 -1
  8. package/dist/web/index.html +3 -3
  9. package/docs/agent-roundtable.md +8 -1
  10. package/docs/client-connections.md +4 -0
  11. package/graph-provider/pyproject.toml +1 -1
  12. package/native/win32/fuli-win-helper.exe +0 -0
  13. package/npm-shrinkwrap.json +2 -2
  14. package/package.json +1 -1
  15. package/packages/roundtable/src/roundtable/delivery-state.js +1 -1
  16. package/packages/roundtable/src/roundtable/service.js +15 -2
  17. package/packages/roundtable/src/roundtable/store.js +33 -4
  18. package/packages/roundtable/src/roundtable/wake-claim-release.js +88 -0
  19. package/packages/roundtable/src/roundtable/wake.js +3 -1
  20. package/skills/capturing-session-knowledge/SKILL.md +4 -4
  21. package/skills/operating-fuli/SKILL.md +1 -1
  22. package/src/agent-tools/graph-handlers.js +5 -3
  23. package/src/agent-tools/project-agent-tool-definitions.js +1 -1
  24. package/src/agents/call-source.js +11 -0
  25. package/src/agents/claude-desktop/code-tab-token-source.js +26 -0
  26. package/src/agents/lifecycle-failure.js +6 -5
  27. package/src/agents/lifecycle-message.js +15 -4
  28. package/src/agents/token-usage-resolver.js +8 -0
  29. package/src/conversations/current-task-lookup.js +2 -3
  30. package/src/graphiti/checkpoint-provider-outage.js +23 -0
  31. package/src/graphiti/local-runtimes.js +4 -1
  32. package/src/graphiti/provider-outage.js +20 -0
  33. package/src/graphiti/task-context-entry.js +9 -1
  34. package/src/graphiti/task-entry-preferences.js +1 -1
  35. package/src/graphiti/task-entry-provider-outage.js +25 -0
  36. package/src/graphiti/task-knowledge-checkpoint.js +1 -1
  37. package/src/graphiti/task-scene.js +1 -1
  38. package/src/judgment/backend.js +8 -2
  39. package/src/mcp/create-mcp-server.js +7 -4
  40. package/src/presence/windows-helper-pin.js +1 -1
  41. package/src/whats-new/lines/0.25.1.json +13 -0
  42. package/src/whats-new/lines/0.25.2.json +13 -0
@@ -224,7 +224,14 @@ honors both sender and recipient admission boundaries. Per-message delivery
224
224
  receipts advance only a contiguous target cursor, so a newer member cannot erase
225
225
  older unread history it was not allowed to see. Durable execution claims keep
226
226
  one wake active per Agent; subsequent rooms wait for completion notifications.
227
- Unknown execution or unconfirmed cleanup keeps its safety hold.
227
+ A claim its console lost (nothing ended it within an hour) is released only on
228
+ evidence: the process recorded when spawn() returned has ended or its PID now names
229
+ another process, and on POSIX no member of its process group is left (the woken
230
+ client leads its own group; Windows has none, so only that process is checked). A
231
+ running or unknown process, or a group that still answers, keeps the hold. A claim
232
+ with no recorded PID, a claim from before processes were recorded, and a reused PID
233
+ whose group still answers are released a day after they began. Its ask returns to
234
+ the inbox. Unconfirmed cleanup keeps its safety hold.
228
235
 
229
236
  ## Group discussions (#FLG, rec#55)
230
237
 
@@ -325,6 +325,10 @@ It does not start FULI:
325
325
  - after 3 automatic starts within 10 minutes, until you start FULI yourself.
326
326
 
327
327
  In those cases the hooks' "Fuli context is unavailable" text says which one applies.
328
+ When a hook itself fails, the same text names the error code, the rule that refused the call (never
329
+ the values it was given) and the FULI version the hook ran, for example
330
+ `the hook failed: validation (Task preference scope is immutable; …) in FULI 0.25.2`;
331
+ a refusal from the graph service shows only its HTTP status.
328
332
  `FULI_CONSOLE_AUTOSTART=off` in a client's environment turns it off for that client's sessions.
329
333
 
330
334
  ## Remote clients
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "fuli-graph-provider"
3
- version = "0.25.0"
3
+ version = "0.25.2"
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.25.0",
3
+ "version": "0.25.2",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "fuli-context",
9
- "version": "0.25.0",
9
+ "version": "0.25.2",
10
10
  "license": "Apache-2.0",
11
11
  "dependencies": {
12
12
  "@agentclientprotocol/sdk": "1.5.0",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fuli-context",
3
- "version": "0.25.0",
3
+ "version": "0.25.2",
4
4
  "description": "Local-first collaboration relationship graph for AI agents.",
5
5
  "type": "module",
6
6
  "files": [
@@ -12,7 +12,7 @@ const INBOX = 'sees it in its inbox when its next task starts (task-entry agent_
12
12
  const NOT_STARTED = {
13
13
  execution_claimed: ({ name, blockedBy }) => `FULI started no session: an earlier message to ${name}`
14
14
  + (blockedBy?.messageId ? ` (${blockedBy.messageId}${blockedBy.since ? `, since ${blockedBy.since}` : ''})` : '')
15
- + ' still owns its one wake, and FULI never runs two at once.',
15
+ + ' still owns its one wake, and FULI never runs two at once. If that wake was lost (its console stopped), it is released once its process has ended, checked from an hour after it began.',
16
16
  cleanup_unconfirmed: ({ name }) => `FULI started no session: ${name}'s previously woken process has not been confirmed to end.`,
17
17
  chat_waiting: ({ name }) => `FULI started no session: ${name} is already waiting in this chat.`,
18
18
  no_client: ({ name, clients }) => clients.length
@@ -1,4 +1,5 @@
1
1
  import { waitForChatChange } from './chat-wait.js';
2
+ import { createWakeClaimRelease } from './wake-claim-release.js';
2
3
  import { createHash, randomUUID } from 'node:crypto';
3
4
  import { projectAddress, resolveProjectAddress, resolveProjectLead, verifiedProjectFolder } from './project-target.js';
4
5
  import { observeReturnedMemory, taskContextHash } from './memory-observation.js';
@@ -29,6 +30,9 @@ export function createAgentRoundtable({ host, peer = null, openStore, wake = wak
29
30
  // Boot-anchor evidence recorded with a cleanup hold. Production records none
30
31
  // (null) until a separately verified proof exists; release stays disabled.
31
32
  bootEvidence = async () => null, now = Date.now,
33
+ // Which recorded wake processes still run (wake-claim-release.js); null = cannot tell.
34
+ inspectProcess = async () => null,
35
+ groupAlive = undefined,
32
36
  // The installed desktop app of a client, or null. Runtimes pass
33
37
  // createDesktopApps (agents/desktop-registry.js); without it every ask wakes headlessly.
34
38
  desktopApp = () => null }) {
@@ -39,6 +43,7 @@ export function createAgentRoundtable({ host, peer = null, openStore, wake = wak
39
43
  const refreshes = new Map();
40
44
  let refreshOffset = 0;
41
45
  const store = new Proxy({}, { get: (_target, property) => (opened ??= openStore())[property] });
46
+ const wakeClaims = createWakeClaimRelease({ store, inspectProcess, groupAlive, now });
42
47
 
43
48
  async function sender({ taskContextToken, sourceApplication }) {
44
49
  if (!taskContextToken) return { agent: null, client: sourceApplication ?? 'other', session: null, projectId: null };
@@ -196,7 +201,8 @@ export function createAgentRoundtable({ host, peer = null, openStore, wake = wak
196
201
  try {
197
202
  grant = await issueGrant(delivery, timeoutMs / 1000);
198
203
  answer = await wake({ client: delivery.client, sessionId: delivery.sessionId, cwd: delivery.cwd,
199
- timeoutMs, prompt, delegationToken: grant.token, peerDepth, signal, onSpawn, readOnly,
204
+ timeoutMs, prompt, delegationToken: grant.token, peerDepth, signal, readOnly,
205
+ onSpawn: (pid) => { wakeClaims.recordSpawn(ask.id, pid); onSpawn?.(pid); },
200
206
  onSession: session => host.sealDelegation({ token: grant.token, sessionId: session }) });
201
207
  const verified = answer.sessionId && await host.verifyDelegation({ token: grant.token, sessionId: answer.sessionId });
202
208
  if (!verified?.redeemed) throw Object.assign(new Error('The receiving session did not restore the Agent'),
@@ -294,6 +300,7 @@ export function createAgentRoundtable({ host, peer = null, openStore, wake = wak
294
300
  // with the reason, so the recipient still sees it when it next works.
295
301
  async function wakeAsk({ thread, ask, target, targets, noTargets, prompt, timeoutMs, signal, issueGrant, replyTo,
296
302
  chatWakeChatId = null, readOnly = false }) {
303
+ await wakeClaims.release(spaceId(), target.agentId);
297
304
  const claim = store.claimExecution(spaceId(), target.agentId, ask.id, { chatWakeChatId });
298
305
  if (!claim.claimed) {
299
306
  // Recorded so the thread and get_agent_message_status say why no client has it.
@@ -451,6 +458,7 @@ export function createAgentRoundtable({ host, peer = null, openStore, wake = wak
451
458
  from: { agentId: `peer:${device.nodeId.slice(0, 16)}:${assertion.from.agentId}`, name: `${assertion.from.name} · ${device.name}`,
452
459
  client: assertion.from.client ?? 'other' },
453
460
  to: { agentId: target.agentId, name: label(target) } });
461
+ await wakeClaims.release(share.spaceId, target.agentId);
454
462
  const execution = store.claimExecution(share.spaceId, target.agentId, ask.id);
455
463
  if (!execution.claimed) {
456
464
  store.updateMessage(ask.id, { status: 'failed', error: execution.reason });
@@ -538,6 +546,8 @@ export function createAgentRoundtable({ host, peer = null, openStore, wake = wak
538
546
  }
539
547
 
540
548
  async function cancelAsk(ask) {
549
+ // A wake its console lost, whose process has ended, no longer answers; its ask is back in the inbox.
550
+ if (ask.status === 'delivering' && !peer?.hasSent(ask.id) && await wakeClaims.release(spaceId(), ask.to_agent)) ask = store.getMessage(ask.id);
541
551
  if (peer?.hasSent(ask.id)) {
542
552
  if (!REMOTE_PENDING.has(ask.status)) return remoteView(ask);
543
553
  return remoteView(applyRemote(ask.id, await peer.cancel(ask.id)));
@@ -666,7 +676,10 @@ export function createAgentRoundtable({ host, peer = null, openStore, wake = wak
666
676
  };
667
677
  // False when an earlier run of this Agent may still be running (a cleanup hold).
668
678
  const waitUntilIdle = async (agentId, signal) => {
669
- const state = await waitForChatChange(() => store.executionState(spaceId(), agentId),
679
+ const state = await waitForChatChange(async () => {
680
+ await wakeClaims.release(spaceId(), agentId);
681
+ return store.executionState(spaceId(), agentId);
682
+ },
670
683
  { store: store.chat, signal, ready: state => state.held || !state.busy });
671
684
  return !state.held;
672
685
  };
@@ -50,6 +50,12 @@ export const ROUNDTABLE_FORMAT = sqliteFormat({
50
50
  id: 'roundtable/6-reply-delivery', to: 6, kind: 'add-columns', table: 'messages',
51
51
  summary: 'whether each reply reached the Agent that asked, and through which tool',
52
52
  columns: { delivery_status: 'TEXT', delivered_via: 'TEXT', delivered_at: 'TEXT' }
53
+ }, {
54
+ // The process a claim started, so a claim its console lost is released only
55
+ // once that process is gone (wake-claim-release.js). Older claims carry none.
56
+ id: 'roundtable/7-wake-process', to: 7, kind: 'add-columns', table: 'messages',
57
+ summary: 'which process each roundtable wake started, so a lost wake is released only after it ended',
58
+ columns: { wake_process_evidence: 'TEXT', wake_pid: 'TEXT', wake_pid_identity: 'TEXT' }
53
59
  }],
54
60
  pragmas: 'PRAGMA journal_mode = WAL;'
55
61
  });
@@ -57,9 +63,9 @@ export const ROUNDTABLE_FORMAT = sqliteFormat({
57
63
  // Every Agent-to-Agent exchange is kept as a thread of messages so people can
58
64
  // see who talked to whom, through which client, and what was said. The file
59
65
  // is shared by the console and every client's MCP process.
60
- export function createRoundtableStore(path = ':memory:') {
66
+ export function createRoundtableStore(path = ':memory:', { clock = () => new Date() } = {}) {
61
67
  const database = openFormattedDatabase(path, ROUNDTABLE_FORMAT);
62
- const now = () => new Date().toISOString();
68
+ const now = () => clock().toISOString();
63
69
  const chat = createChatStore(database, path);
64
70
  const attention = createAttentionInboxStore(database, chat);
65
71
  const discussions = createGroupDiscussionStore(database, chat);
@@ -159,8 +165,8 @@ export function createRoundtableStore(path = ':memory:') {
159
165
  const state = this.executionState(spaceId, agentId, askId);
160
166
  if (state.held) return { claimed: false, reason: 'cleanup_unconfirmed' };
161
167
  if (state.busy) return { claimed: false, reason: 'execution_claimed', blockedBy: state.claim };
162
- const claimed = database.prepare(`UPDATE messages SET execution_claim = 'active', execution_claimed_at = ?
163
- WHERE id = ? AND execution_claim IS NULL`).run(now(), askId).changes === 1;
168
+ const claimed = database.prepare(`UPDATE messages SET execution_claim = 'active', execution_claimed_at = ?,
169
+ wake_process_evidence = '1' WHERE id = ? AND execution_claim IS NULL`).run(now(), askId).changes === 1;
164
170
  return claimed ? { claimed: true } : { claimed: false, reason: 'execution_claimed' };
165
171
  });
166
172
  },
@@ -176,6 +182,29 @@ export function createRoundtableStore(path = ':memory:') {
176
182
  return { busy: Boolean(active), claim: active ? { messageId: active.id, since: active.execution_claimed_at } : null,
177
183
  held: blocking.some(row => row.cleanup_status === 'unconfirmed' && row.cleanup_released_at === null) };
178
184
  },
185
+ // The process this claim started, recorded at spawn; its identity follows once read.
186
+ recordWakeProcess(askId, pid, identity = null) {
187
+ database.prepare(`UPDATE messages SET wake_pid = ?, wake_pid_identity = coalesce(?, wake_pid_identity)
188
+ WHERE id = ? AND execution_claim = 'active'`).run(String(pid), identity, askId);
189
+ },
190
+ // Active claims of this Agent made before the cutoff, with no cleanup hold.
191
+ claimsBefore(spaceId, agentId, cutoff) {
192
+ return database.prepare(`SELECT m.id, m.execution_claimed_at, m.wake_process_evidence, m.wake_pid, m.wake_pid_identity
193
+ FROM messages m JOIN threads t ON t.id = m.thread_id
194
+ WHERE t.space_id = ? AND m.to_agent = ? AND m.kind = 'ask' AND m.execution_claim = 'active'
195
+ AND m.execution_claimed_at < ? AND (m.cleanup_status IS NULL OR m.cleanup_status != 'unconfirmed')`)
196
+ .all(spaceId, agentId, cutoff);
197
+ },
198
+ // A released claim's ask goes back to the inbox, so it can be read or cancelled.
199
+ expireClaim(askId) {
200
+ const expired = database.prepare(`UPDATE messages SET execution_claim = 'expired',
201
+ status = CASE WHEN status = 'delivering' THEN 'queued' ELSE status END,
202
+ error = CASE WHEN status = 'delivering' THEN 'wake_expired' ELSE error END, updated_at = ?
203
+ WHERE id = ? AND execution_claim = 'active' AND (cleanup_status IS NULL OR cleanup_status != 'unconfirmed')`)
204
+ .run(now(), askId).changes === 1;
205
+ if (expired) chat.publishChanges();
206
+ return expired;
207
+ },
179
208
  // Only after the owned process was observed to end, or never started. An
180
209
  // unconfirmed cleanup leaves the claim active until a proof releases it.
181
210
  finishExecution(askId) {
@@ -0,0 +1,88 @@
1
+ // A claim stays active until its wake ends (store.finishExecution). When the
2
+ // console restarts or crashes mid-wake nothing ends it, and the Agent could
3
+ // never be woken again (rec#97). A claim old enough that no live console still
4
+ // waits on it is released only on evidence that no process of it is running:
5
+ // the recorded process is gone, or its PID now belongs to another process, and
6
+ // on POSIX no member of its process group is left (the woken client leads its
7
+ // own group, wake.js; descendants outlive their leader). A process still
8
+ // running, a group that still answers, or an OS that cannot be asked keeps the
9
+ // hold: a woken client can outlive its console. Windows keeps no group, so the
10
+ // recorded process alone is checked there.
11
+ // A claim with no PID (its console was lost between the claim and the spawn),
12
+ // a claim written before processes were recorded, and a reused PID whose group
13
+ // still answers cannot be proven either way; they are released a day after
14
+ // they began, long after their delegation expired.
15
+
16
+ // The longest wake waits 15 minutes and is then stopped; an hour leaves margin.
17
+ export const WAKE_CLAIM_TTL_MS = 60 * 60 * 1000;
18
+ export const LEGACY_CLAIM_TTL_MS = 24 * 60 * 60 * 1000;
19
+ // A claim whose process is still running is asked about again at most this often.
20
+ const RECHECK_MS = 60 * 1000;
21
+
22
+ // inspectProcess(pids) -> Map<pid, { identity }> of the PIDs that exist, or null
23
+ // when the OS could not be asked (agent-services/process-identity.js).
24
+ // groupAlive(pgid) -> true while any process of the group exists, false when
25
+ // none does, null when the OS could not tell.
26
+ export function createWakeClaimRelease({ store, inspectProcess = async () => null, groupAlive = processGroupAlive,
27
+ now = Date.now }) {
28
+ const checked = new Map();
29
+
30
+ async function released(claim) {
31
+ const age = now() - Date.parse(claim.execution_claimed_at);
32
+ const unproven = age >= LEGACY_CLAIM_TTL_MS;
33
+ if (claim.wake_process_evidence !== '1' || !claim.wake_pid) return unproven;
34
+ const pid = Number(claim.wake_pid);
35
+ const running = await inspectProcess([pid]).catch(() => null);
36
+ if (!running) return false;
37
+ const current = running.get(pid);
38
+ const reused = Boolean(current && claim.wake_pid_identity && current.identity
39
+ && String(current.identity) !== claim.wake_pid_identity);
40
+ if (current && !reused) return false;
41
+ const group = groupAlive(pid);
42
+ if (group === false) return true;
43
+ // A group that still answers may be the woken client's descendants, or the
44
+ // reused PID's own group: only the second is left to the day's limit.
45
+ return group === true && reused && unproven;
46
+ }
47
+
48
+ // Releases what the evidence allows; the number of claims released.
49
+ async function release(spaceId, agentId) {
50
+ // A remote run is ended by its device's answer (applyRemote); this device sees no process of it.
51
+ if (String(agentId).startsWith('peer:')) return 0;
52
+ let count = 0;
53
+ for (const claim of store.claimsBefore(spaceId, agentId, new Date(now() - WAKE_CLAIM_TTL_MS).toISOString())) {
54
+ if (now() - (checked.get(claim.id) ?? -Infinity) < RECHECK_MS) continue;
55
+ checked.set(claim.id, now());
56
+ if (await released(claim) && store.expireClaim(claim.id)) {
57
+ count += 1;
58
+ checked.delete(claim.id);
59
+ }
60
+ }
61
+ return count;
62
+ }
63
+
64
+ // Recorded synchronously at spawn, so a console lost right after still knows the PID.
65
+ function recordSpawn(askId, pid) {
66
+ if (!Number.isSafeInteger(pid) || pid <= 0) return;
67
+ store.recordWakeProcess(askId, pid);
68
+ void inspectProcess([pid]).then((found) => {
69
+ const identity = found?.get(pid)?.identity;
70
+ if (identity) store.recordWakeProcess(askId, pid, String(identity));
71
+ }).catch(() => {});
72
+ }
73
+
74
+ return { release, recordSpawn };
75
+ }
76
+
77
+ // The woken client leads its own process group on POSIX (detached, wake.js).
78
+ // Signal 0 only asks whether any member exists.
79
+ export function processGroupAlive(pgid, { platform = process.platform, kill = process.kill } = {}) {
80
+ if (platform === 'win32') return false;
81
+ try {
82
+ kill(-pgid, 0);
83
+ return true;
84
+ } catch (error) {
85
+ if (error?.code === 'ESRCH') return false;
86
+ return error?.code === 'EPERM' ? true : null;
87
+ }
88
+ }
@@ -96,7 +96,9 @@ export function runProcess(command, args, { cwd, env, input, timeoutMs, maxOutpu
96
96
  const child = spawn(command, args, { cwd, env, shell: false, windowsHide: true,
97
97
  detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'ignore'] });
98
98
  const closed = new Promise((resolve) => child.once('close', resolve));
99
- child.once('spawn', () => onSpawn?.());
99
+ // The PID is known as soon as spawn() returns: record it before anything can
100
+ // lose the console, not on the later spawn event (rec#97).
101
+ if (Number.isSafeInteger(child.pid)) onSpawn?.(child.pid);
100
102
  let output = '', pending = '', bytes = 0, settled = false, childClosed = false;
101
103
  const decoder = new StringDecoder('utf8');
102
104
  const callbacks = new Set();
@@ -27,9 +27,9 @@ directory. It also uses the submitted prompt transiently for bounded automatic p
27
27
  recall and never returns that prompt; it keeps it on this computer only so `run_delegated_action`
28
28
  can check words relayed as the person's decision in the same turn, until the task checkpoints. Apply the returned `task_knowledge_recall` and
29
29
  preferences, then retain the opaque task token for any required checkpoint;
30
- do not redundantly call `get_collaboration_preferences`. If a FULI call refuses that token as
31
- begun in another client (for example a `claude_code` hook token through a FULI connection that
32
- runs as `claude`), call `get_collaboration_preferences` through that connection once and pass
30
+ do not redundantly call `get_collaboration_preferences`. Claude Desktop's FULI connection
31
+ (`claude`) accepts its Code tab's `claude_code` hook tokens. If a FULI call refuses that token as
32
+ begun in another client, call `get_collaboration_preferences` through that connection once and pass
33
33
  its token to every call made through it, checkpoint included; never retry the refused token.
34
34
 
35
35
  After a FULI update an open session can still have a FULI MCP connection on the older version.
@@ -66,7 +66,7 @@ remains unverified even if the preference fallback and task-summary checkpoint s
66
66
 
67
67
  ## Mandatory reply identity
68
68
 
69
- Every final user-visible reply MUST include the current task’s `agent_receipt.markdown` unchanged exactly once. This includes greetings, status-only replies, failures, `retain_nothing`, and capture-disabled tasks. The receipt is independent of whether a memory checkpoint was saved. Never substitute a client name, configured peer, or an earlier task’s owner. If a legacy/unavailable entry supplies no receipt, explicitly state that the FULI Agent identity is unavailable. A receipt with no authorized owner already supplies the correct neutral text.
69
+ Every final user-visible reply MUST include the current task’s `agent_receipt.markdown` unchanged exactly once. This includes greetings, status-only replies, failures, `retain_nothing`, and capture-disabled tasks. The receipt is independent of whether a memory checkpoint was saved. Never substitute a client name, configured peer, or an earlier task’s owner. If a legacy/unavailable entry supplies no receipt, explicitly state that the FULI Agent identity is unavailable. When `get_collaboration_preferences` returns `status: preferences_unavailable` (FULI's graph service did not answer), follow its `guidance`: continue without FULI preferences, retry it once before any FULI write or the final reply, and never reuse an earlier token. When `checkpoint_task_knowledge` returns `status: checkpoint_incomplete`, retry it once with exactly the same arguments (FULI may already keep the first input; changed wording is refused) and do not claim the task was saved until it returns `checkpointed`. A receipt with no authorized owner already supplies the correct neutral text.
70
70
 
71
71
  Apply only `effective_preferences`. Personal-global preferences apply in every user task;
72
72
  project-scoped preferences layer on only for the exact selected project. Do not apply items
@@ -104,7 +104,7 @@ Read each returned worker's `context.agent.profile.allowedClients` and `executor
104
104
 
105
105
  ## Mandatory reply identity
106
106
 
107
- Every final user-visible reply MUST include the current task’s `agent_receipt.markdown` unchanged exactly once. This includes greetings, status-only replies, failures, `retain_nothing`, and capture-disabled tasks. The receipt is independent of whether a memory checkpoint was saved. Never substitute a client name, configured peer, or an earlier task’s owner. If a legacy/unavailable entry supplies no receipt, explicitly state that the FULI Agent identity is unavailable. A receipt with no authorized owner already supplies the correct neutral text.
107
+ Every final user-visible reply MUST include the current task’s `agent_receipt.markdown` unchanged exactly once. This includes greetings, status-only replies, failures, `retain_nothing`, and capture-disabled tasks. The receipt is independent of whether a memory checkpoint was saved. Never substitute a client name, configured peer, or an earlier task’s owner. If a legacy/unavailable entry supplies no receipt, explicitly state that the FULI Agent identity is unavailable. When `get_collaboration_preferences` returns `status: preferences_unavailable` (FULI's graph service did not answer), follow its `guidance`: continue without FULI preferences, retry it once before any FULI write or the final reply, and never reuse an earlier token. When `checkpoint_task_knowledge` returns `status: checkpoint_incomplete`, retry it once with exactly the same arguments (FULI may already keep the first input; changed wording is refused) and do not claim the task was saved until it returns `checkpointed`. A receipt with no authorized owner already supplies the correct neutral text.
108
108
 
109
109
  A `FULI 迁移已确认:…` line in the entry receipt means the person already confirmed, in the console, moving this session's temporary-project items: it says how many moved and how many still wait there. Do not ask them to confirm it again; continue the work. The line is information only and grants nothing. A `FULI 待迁移` line is the opposite: the move still waits on the linked page.
110
110
 
@@ -16,6 +16,8 @@ import { OLD_DATA_HANDLERS } from '../old-data/agent-tools.js';
16
16
  import { REPLY_ECHO_HANDLERS } from '../graphiti/reply-echo-agent-tool.js';
17
17
  import { OCCUPATION_KIT_HANDLERS } from '../occupation-plugins/agent-tools.js';
18
18
  import { agentNamingStyleAnswer } from '../agent-naming/naming-style.js';
19
+ import { withProviderOutageEntry } from '../graphiti/task-entry-provider-outage.js';
20
+ import { withCheckpointOutageStatus } from '../graphiti/checkpoint-provider-outage.js';
19
21
 
20
22
  // These tools read or change the two local stores that can retain deleted
21
23
  // knowledge. Provider-only reads and unrelated tools remain available.
@@ -117,13 +119,13 @@ const HANDLERS = Object.freeze({
117
119
  begin_task_context: (app, input) => app.beginTaskContext(input),
118
120
  read_task_preferences: (app, input) => app.readTaskPreferences(input),
119
121
  checkpoint_task_knowledge: (app, input) =>
120
- app.checkpointTaskKnowledge(input),
122
+ withCheckpointOutageStatus(app.checkpointTaskKnowledge(input)),
121
123
  verify_task_checkpoint: (app, input) => app.verifyTaskCheckpoint(input),
122
- get_collaboration_preferences: (app, input) => app.getCollaborationPreferences({
124
+ get_collaboration_preferences: (app, input) => withProviderOutageEntry(app.getCollaborationPreferences({
123
125
  ...input,
124
126
  agentInvocation: true,
125
127
  agentToolName: 'get_collaboration_preferences'
126
- }),
128
+ })),
127
129
  get_user_taste_skill: (app, input) => app.getUserTasteSkill(input),
128
130
  resolve_deferred_preference_conflict: (app, input) =>
129
131
  app.resolveDeferredPreferenceConflict({
@@ -193,7 +193,7 @@ export const PROJECT_AGENT_TOOL_DEFINITIONS = [
193
193
  {
194
194
  name: 'record_project_agent_task_activity',
195
195
  title: 'WRITE · Record task activity',
196
- description: 'Record real task/worker activity and optional source-labelled cumulative token usage; never estimate. workerStatus requires workerId and agentId. Supply actualExecutorId, actualModelProvider, actualModel together only with matching authorized preflight evidence; otherwise omit all three, report observed workerRuntime, and explain mismatch in summary. Terminal activity with valid actual execution automatically records routing outcome.',
196
+ description: 'Record real task/worker activity and optional source-labelled cumulative token usage of agentId (none is collected without it); never estimate. workerStatus requires workerId and agentId. Supply actualExecutorId, actualModelProvider, actualModel together only with authorized preflight evidence; otherwise omit all three, report observed workerRuntime and explain mismatch in summary. Valid terminal execution records routing outcome.',
197
197
  inputSchema: projectAgentTaskActivityInput
198
198
  },
199
199
  {
@@ -0,0 +1,11 @@
1
+ import { DESKTOP_SOURCE, desktopCallSource } from './claude-desktop/code-tab-token-source.js';
2
+
3
+ // The client one MCP call runs as. A connection runs as the client it was
4
+ // started for, except where that client's process also serves another
5
+ // client's sessions: Claude Desktop's serves its Code tab (rec#107).
6
+ const RESOLVERS = Object.freeze({ [DESKTOP_SOURCE]: desktopCallSource });
7
+
8
+ export async function callSourceApplication(app, sourceApplication, input) {
9
+ const resolve = RESOLVERS[sourceApplication];
10
+ return resolve ? resolve(app, input) : sourceApplication;
11
+ }
@@ -0,0 +1,26 @@
1
+ import { ProviderRequestError } from '../../graphiti/provider-client.js';
2
+
3
+ // rec#107. Claude Desktop runs FULI from its own configuration as one MCP
4
+ // process (`--source-application claude`), and that process can also serve a
5
+ // session in its Code tab, whose prompt hook is Claude Code's and begins the
6
+ // task as `claude_code`. Every call carrying that hook's token was refused as
7
+ // another client's, and the connection could begin no task of its own (it
8
+ // proves no native session), so the Agent could neither checkpoint nor answer
9
+ // on the roundtable. A call through this connection that carries a token the
10
+ // Provider holds for `claude_code` runs as `claude_code`; any other call, and
11
+ // every token of another client, keeps `claude`.
12
+ export const DESKTOP_SOURCE = 'claude';
13
+ const CODE_TAB_SOURCE = 'claude_code';
14
+
15
+ export async function desktopCallSource(app, input) {
16
+ const token = input?.taskContextToken;
17
+ if (typeof token !== 'string' || !token || typeof app?.taskContextRegistry?.context !== 'function') return DESKTOP_SOURCE;
18
+ try {
19
+ await app.taskContextRegistry.context(token, CODE_TAB_SOURCE);
20
+ return CODE_TAB_SOURCE;
21
+ } catch (error) {
22
+ // 404: not a Code-tab token (this client's own, superseded or unknown); the call decides as itself.
23
+ if (error instanceof ProviderRequestError && error.status === 404) return DESKTOP_SOURCE;
24
+ throw error;
25
+ }
26
+ }
@@ -1,21 +1,22 @@
1
1
  import { dirname } from 'node:path';
2
2
 
3
3
  import { diagnosticEventLog } from '../diagnostics/event-log.js';
4
- import { errorCode } from '../diagnostics/safe-event.js';
4
+ import { errorCode, failureReason } from '../diagnostics/safe-event.js';
5
5
  import { resolveGraphRuntimeOptions } from '../graphiti/runtime-config.js';
6
6
  import { hookFailureCause } from './lifecycle-message.js';
7
7
  import { consoleAutostartNotice } from '../local-runtime/console-autostart-record.js';
8
8
 
9
9
  // A lifecycle hook that failed records it in the data directory's diagnostics
10
- // log (rec#73), with the same cause its client was shown and the session as
11
- // correlation. Common to every Agent's hook; each passes its own client and
12
- // event. Never throws: the hook's answer is already decided.
10
+ // log (rec#73), with its cause and the session as correlation. Common to
11
+ // every Agent's hook; each passes its own client and event. Never throws:
12
+ // the hook's answer is already decided.
13
13
  export function recordHookFailure({ runtimeConfigPath, client, event, error, sessionId = null, startedAt = null,
14
14
  now = Date.now }) {
15
15
  if (typeof runtimeConfigPath !== 'string' || !runtimeConfigPath) return false;
16
16
  return diagnosticEventLog(dirname(runtimeConfigPath)).record({
17
17
  component: 'hook', operation: `${client}.${event ?? 'unknown'}`, outcome: 'failed',
18
- code: errorCode(error), reason: hookFailureCause(error),
18
+ // A controlled error's message names the refused field or rule without its value (rec#85).
19
+ code: errorCode(error), reason: failureReason(error, hookFailureCause(error)),
19
20
  durationMs: Number.isFinite(startedAt) ? Math.round(now() - startedAt) : null,
20
21
  correlationId: typeof sessionId === 'string' ? sessionId : null
21
22
  });
@@ -1,15 +1,26 @@
1
- import { errorCode } from '../diagnostics/safe-event.js';
1
+ import { errorCode, failureReason } from '../diagnostics/safe-event.js';
2
+ import { FULI_VERSION } from '../package-metadata.js';
3
+ import { singleLineExcerpt } from '../text/single-line.js';
2
4
 
3
5
  // Every listed rule fetch is a model round trip (Codex re-sends its whole
4
6
  // prompt each time), so ordinary tasks must not read the shared rules at all.
5
7
  // A call that carries its task token is decided by that session; without one
6
8
  // it may be refused while another session of the client is off (rec#5 C3b).
7
9
  // Why a lifecycle hook failed, as far as it is safe to say (rec#85): an error's
8
- // code or class, which are fixed identifiers. Never its message, which may carry
9
- // a prompt, path or credential.
10
+ // code or class, which are fixed identifiers; a controlled error's message,
11
+ // which names the refused rule without the values it was given; and the
12
+ // version the hook ran, so a report tells an old install from a regression.
13
+ // Never another error's message, which may carry a prompt, path or credential.
14
+ // A Provider refusal is controlled too, but its message relays the Provider's
15
+ // own detail, which may echo what was sent: it says only its HTTP status.
10
16
  export function hookFailureCause(error) {
11
17
  const code = errorCode(error);
12
- return code ? `the hook failed: ${code}` : 'the hook failed';
18
+ const rule = error?.name === 'ProviderRequestError' ? providerStatus(error) : failureReason(error, null);
19
+ return `${code ? `the hook failed: ${code}` : 'the hook failed'}${rule ? ` (${singleLineExcerpt(rule, 160)})` : ''} in FULI ${FULI_VERSION}`;
20
+ }
21
+
22
+ function providerStatus(error) {
23
+ return Number.isInteger(error.status) && error.status >= 100 && error.status <= 599 ? `HTTP ${error.status}` : null;
13
24
  }
14
25
 
15
26
  export const PASS_TASK_TOKEN = 'Pass taskContextToken to every FULI call. ';
@@ -80,6 +80,10 @@ export async function enrichProjectAgentTaskActivity(input = {}, resolver = DEFA
80
80
  const explicitTokenUsage = (Object.hasOwn(input, 'tokenUsage') && input.tokenUsage !== undefined) ||
81
81
  (Object.hasOwn(input, 'token_usage') && input.token_usage !== undefined);
82
82
  if (explicitTokenUsage) return input;
83
+ // Usage belongs to a participating Agent. A report without one (a
84
+ // coordinator's status line) collects none: the Provider refuses usage
85
+ // without its Agent, and the reporter's own session is not the task's (rec#85).
86
+ if (!nonEmptyText(input.agentId ?? input.agent_id)) return input;
83
87
 
84
88
  const resolve = typeof resolver === 'function' ? resolver : resolver?.resolve;
85
89
  if (typeof resolve !== 'function') return input;
@@ -145,3 +149,7 @@ function safeSessionId(value) {
145
149
  !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(normalized)) return null;
146
150
  return normalized;
147
151
  }
152
+
153
+ function nonEmptyText(value) {
154
+ return typeof value === 'string' && value.trim() !== '';
155
+ }
@@ -1,4 +1,5 @@
1
1
  import { ProviderRequestError } from '../graphiti/provider-client.js';
2
+ import { isProviderOutage } from '../graphiti/provider-outage.js';
2
3
 
3
4
  // Only this first, read-only lookup can be deferred before a scope is known.
4
5
  // Each real HTTP attempt is bounded; writes and later handoff operations are
@@ -30,9 +31,7 @@ export async function lookupTranscriptTask(application, input, sourceApplication
30
31
  code: 'current_task_endpoint_unavailable',
31
32
  reason: 'Visible transcript synchronization is not available on this Fuli provider version' } };
32
33
  }
33
- const transient = ['provider_unavailable', 'provider_timeout'].includes(error.code)
34
- || (error.code === 'provider_http_5xx' && [502, 503, 504].includes(error.status));
35
- if (!transient) throw error;
34
+ if (!isProviderOutage(error)) throw error;
36
35
  if (attempt === 1) return { failure: { status: 'unsaved', entryBlocked: true,
37
36
  code: 'current_task_lookup_unavailable',
38
37
  reason: 'Visible transcript synchronization is temporarily unavailable after bounded retries; native history remains available for a later verified task entry' } };
@@ -0,0 +1,23 @@
1
+ import { recoverProviderOutage } from './provider-outage.js';
2
+
3
+ // rec#39: the first checkpoint call binds its input, so a call the Graph
4
+ // Provider never answered finishes only when resent unchanged. Say so instead
5
+ // of a bare timeout, which led Agents to retry with new wording and be refused.
6
+ const GUIDANCE = 'This checkpoint did not finish because FULI\'s graph service did not answer. ' +
7
+ 'FULI may already keep its input, so retry checkpoint_task_knowledge with exactly the same arguments; changed wording is refused. ' +
8
+ 'Until a retry returns checkpointed, do not claim the task was saved; end with the entry agent_receipt. ' +
9
+ 'If the retry fails again, say in one line that FULI could not save this task yet.';
10
+
11
+ export function checkpointIncomplete(error) {
12
+ return {
13
+ status: 'checkpoint_incomplete',
14
+ reason: error.code,
15
+ checkpoint_required: true,
16
+ retry: { tool: 'checkpoint_task_knowledge', same_input: true, attempts: 1 },
17
+ guidance: GUIDANCE
18
+ };
19
+ }
20
+
21
+ export function withCheckpointOutageStatus(checkpoint) {
22
+ return recoverProviderOutage(checkpoint, checkpointIncomplete);
23
+ }
@@ -36,6 +36,7 @@ import { createSessionPreferenceDelivery } from '../conversations/preference-ses
36
36
  import { createSessionPromptSentences } from './session-prompt-sentences.js';
37
37
  import { diagnosticEventLog } from '../diagnostics/event-log.js';
38
38
  import { nativeChoiceAnswers } from '../agents/choice-answers.js';
39
+ import { createProcessInspector } from '../agent-services/process-identity.js';
39
40
 
40
41
  // The local stores and runtimes an application opened from a runtime
41
42
  // directory owns. Adding one means opening it here and closing it below.
@@ -116,7 +117,9 @@ export function openLocalRuntimes(app, { runtimeConfigPath, paths, env, fetchImp
116
117
  env,
117
118
  // Asks to a Codex FLA go to its inbox conversation in the Codex app when that app is installed.
118
119
  desktopApp: createDesktopApps({ env }),
119
- openStore: () => createRoundtableStore(join(dataDir, 'agent-roundtable.sqlite'))
120
+ openStore: () => createRoundtableStore(join(dataDir, 'agent-roundtable.sqlite')),
121
+ // A wake claim its console lost is released only once its process has ended.
122
+ inspectProcess: createProcessInspector().inspect
120
123
  });
121
124
  }
122
125
 
@@ -0,0 +1,20 @@
1
+ import { ProviderRequestError } from './provider-client.js';
2
+
3
+ // The Graph Provider did not answer (not running, restarting, or a gateway in
4
+ // front of it failed): a later attempt may succeed. A refusal or a bad request
5
+ // is an answer and never counts.
6
+ export function isProviderOutage(error) {
7
+ if (!(error instanceof ProviderRequestError)) return false;
8
+ return ['provider_unavailable', 'provider_timeout'].includes(error.code)
9
+ || (error.code === 'provider_http_5xx' && [502, 503, 504].includes(error.status));
10
+ }
11
+
12
+ // Runs work; an outage becomes recover(error)'s bounded answer, anything else fails as before.
13
+ export async function recoverProviderOutage(work, recover) {
14
+ try {
15
+ return await work;
16
+ } catch (error) {
17
+ if (isProviderOutage(error)) return recover(error);
18
+ throw error;
19
+ }
20
+ }
@@ -23,6 +23,7 @@ export async function beginTaskContext(application, {
23
23
  sourceSessionId = null,
24
24
  projectAgentId = null,
25
25
  workKind,
26
+ promptScene,
26
27
  workflow,
27
28
  requiredCapabilities = []
28
29
  }) {
@@ -40,8 +41,15 @@ export async function beginTaskContext(application, {
40
41
  if (existingTask && personalProjectId && existingTask.personalProjectId !== personalProjectId) {
41
42
  throw validationError('Task context belongs to another project');
42
43
  }
44
+ // A scene a hook read from the prompt (task-scene.js) is a hint: it scopes a
45
+ // new task only. Codex runs the prompt hook again, with the same turn_id, for
46
+ // input that arrives while the turn runs (an async question's reply, a
47
+ // steering message: codex-rs/core/src/hook_runtime.rs inspect_pending_input);
48
+ // that input keeps the scene its turn entered with (rec#85). An explicit
49
+ // workKind is still refused when it differs. Only the hooks send promptScene,
50
+ // in-process; it is not part of the MCP tool schema.
43
51
  const preferenceScope = existingTask ? taskPreferenceScope(existingTask.preferenceScope)
44
- : taskPreferenceScope({ version: 1, work_kind: workKind ?? null, workflow: workflow ?? null });
52
+ : taskPreferenceScope({ version: 1, work_kind: workKind ?? promptScene ?? null, workflow: workflow ?? null });
45
53
  if (!preferenceScope) throw validationError('Task preference scope is unknown; legacy recovery cannot guess preference dimensions');
46
54
  if (existingTask && ((workKind !== undefined && workKind !== preferenceScope.work_kind) ||
47
55
  (workflow !== undefined && workflow !== preferenceScope.workflow))) {