@pulsarinteractive/geniustasker 0.1.0-beta.1 → 0.1.0-beta.11

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 (68) hide show
  1. package/CHANGELOG.md +88 -0
  2. package/CONTRIBUTING.md +72 -0
  3. package/LICENSE +21 -0
  4. package/LICENSES/Apache-2.0.txt +202 -0
  5. package/README.md +47 -370
  6. package/SECURITY.md +14 -0
  7. package/THIRD_PARTY_NOTICES.md +15 -0
  8. package/docs/ARCHITECTURE.md +144 -0
  9. package/docs/CHATGPT.md +86 -0
  10. package/docs/CLI.md +444 -0
  11. package/docs/DOCUMENTATION_SYNC.md +144 -0
  12. package/docs/INTEGRATIONS.md +62 -0
  13. package/docs/LIMITS.md +62 -0
  14. package/docs/MEMORY.md +38 -0
  15. package/docs/OPENAI.md +21 -0
  16. package/docs/OPENAI_PUBLICATION.md +22 -0
  17. package/docs/PLANNING.md +79 -0
  18. package/docs/PROJECT_FILTERS.md +77 -0
  19. package/docs/RELEASING.md +23 -0
  20. package/docs/TESTING.md +52 -0
  21. package/docs/WORKFLOWS.md +37 -0
  22. package/examples/codex.toml +3 -0
  23. package/examples/mcp.json +8 -0
  24. package/mcp.json +10 -0
  25. package/package.json +45 -9
  26. package/plugin.json +24 -0
  27. package/remote/tool-catalog.json +1374 -0
  28. package/remote/workflows.json +67 -0
  29. package/skills/geniustasker/SKILL.md +49 -116
  30. package/skills/geniustasker/agents/openai.yaml +4 -0
  31. package/skills/geniustasker/references/collaboration.md +70 -0
  32. package/skills/geniustasker/references/incremental-reads.md +16 -0
  33. package/skills/geniustasker/references/profiles.md +22 -0
  34. package/skills/geniustasker/references/project-reads.md +43 -0
  35. package/skills/geniustasker-documentation/SKILL.md +39 -0
  36. package/skills/geniustasker-documentation/agents/openai.yaml +4 -0
  37. package/skills/geniustasker-documentation/references/structure.md +29 -0
  38. package/skills/geniustasker-graph/SKILL.md +31 -0
  39. package/skills/geniustasker-graph/agents/openai.yaml +4 -0
  40. package/skills/geniustasker-media/SKILL.md +33 -0
  41. package/skills/geniustasker-media/agents/openai.yaml +4 -0
  42. package/skills/geniustasker-memory/SKILL.md +120 -0
  43. package/skills/geniustasker-memory/agents/openai.yaml +4 -0
  44. package/skills/geniustasker-memory/references/knowledge-workflows.md +57 -0
  45. package/skills/geniustasker-planning/SKILL.md +28 -0
  46. package/skills/geniustasker-planning/agents/openai.yaml +4 -0
  47. package/src/changes.mjs +104 -28
  48. package/src/cli.mjs +453 -77
  49. package/src/client.mjs +210 -34
  50. package/src/command-catalog.mjs +545 -263
  51. package/src/commands.mjs +225 -53
  52. package/src/documentation-graph.mjs +251 -0
  53. package/src/documentation-store.mjs +589 -0
  54. package/src/documentation-sync.mjs +517 -0
  55. package/src/documentation.mjs +136 -0
  56. package/src/errors.mjs +55 -12
  57. package/src/knowledge.mjs +109 -0
  58. package/src/login.mjs +190 -47
  59. package/src/mcp.mjs +310 -43
  60. package/src/media.mjs +307 -0
  61. package/src/presentation.d.mts +1 -0
  62. package/src/presentation.mjs +12 -0
  63. package/src/profiles.mjs +123 -32
  64. package/src/read-cache.mjs +111 -0
  65. package/src/recovery.mjs +80 -0
  66. package/src/store.mjs +101 -26
  67. package/src/transport.mjs +182 -33
  68. package/src/workflows.mjs +9 -0
package/src/commands.mjs CHANGED
@@ -1,3 +1,4 @@
1
+ import { retryAt, requireRetryReady } from './recovery.mjs';
1
2
  import { randomUUID } from 'node:crypto';
2
3
  import { constants } from 'node:fs';
3
4
  import { open } from 'node:fs/promises';
@@ -7,108 +8,279 @@ import catalog from './command-catalog.mjs';
7
8
  import { CredentialStore } from './store.mjs';
8
9
  import { AgentError, fail, safeError } from './errors.mjs';
9
10
 
10
- export const operationIdSchema = z.string().regex(/^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$/);
11
- const identifier = z.string().min(1).max(128).regex(/^[^\u0000-\u001f]+$/u);
12
- export const commandSchema = z.object({
13
- operationId: operationIdSchema, issuedAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
14
- scope: z.string().max(256).regex(/^(project|memory):[^\u0000-\u001f]+$/u),
15
- epoch: identifier, id: identifier, expectedRevision: z.string().regex(/^[1-9][0-9]{0,15}$/).nullable(),
16
- kind: z.enum(Object.keys(catalog.commands)), data: z.record(z.string(), z.json()),
17
- }).strict();
11
+ export const operationIdSchema = z
12
+ .string()
13
+ .regex(/^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$/);
14
+ const identifier = z
15
+ .string()
16
+ .min(1)
17
+ .max(128)
18
+ // eslint-disable-next-line no-control-regex -- Reject control characters in untrusted input.
19
+ .regex(/^[^\u0000-\u001f]+$/u);
20
+ export const commandSchema = z
21
+ .object({
22
+ operationId: operationIdSchema,
23
+ issuedAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
24
+ scope: z
25
+ .string()
26
+ .max(256)
27
+ // eslint-disable-next-line no-control-regex -- Reject control characters in untrusted input.
28
+ .regex(/^(project|memory):[^\u0000-\u001f]+$/u),
29
+ epoch: identifier,
30
+ id: identifier,
31
+ expectedRevision: z
32
+ .string()
33
+ .regex(/^[1-9][0-9]{0,15}$/)
34
+ .nullable(),
35
+ kind: z.enum(Object.keys(catalog.commands)),
36
+ data: z.record(z.string(), z.json()),
37
+ })
38
+ .strict();
18
39
  export const draftSchema = commandSchema.omit({ operationId: true, issuedAt: true });
19
- const canonical = value => JSON.stringify(value, (_, item) => item && typeof item === 'object' && !Array.isArray(item)
20
- ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item);
40
+ const canonical = (value) =>
41
+ JSON.stringify(value, (_, item) =>
42
+ item && typeof item === 'object' && !Array.isArray(item)
43
+ ? Object.fromEntries(
44
+ Object.keys(item)
45
+ .sort()
46
+ .map((key) => [key, item[key]]),
47
+ )
48
+ : item,
49
+ );
21
50
  const checked = (schema, value) => {
22
51
  const parsed = schema.safeParse(value);
23
- if (!parsed.success) fail('invalid_arguments', 'The command does not match its schema. Use commands describe; do not supply credentials or server-owned fields.');
52
+ if (!parsed.success) {
53
+ fail(
54
+ 'invalid_arguments',
55
+ 'The command does not match its schema. Use commands describe; do not supply credentials or server-owned fields.',
56
+ );
57
+ }
24
58
  return parsed.data;
25
59
  };
60
+ /** Validate the public envelope, generated field allowlist and resource scope. */
26
61
  export function validateCommand(value) {
27
- const command = checked(commandSchema, value), definition = catalog.commands[command.kind];
28
- if (Buffer.byteLength(JSON.stringify(command)) > catalog.maxCommandBytes ||
29
- Object.keys(command.data).some(key => !definition.fields.includes(key)) ||
30
- (definition.create ? command.expectedRevision !== null : command.expectedRevision === null))
31
- fail('invalid_arguments', 'Use the declared command fields and size limit. Creation requires a null revision; other commands require the current record revision.');
62
+ const command = checked(commandSchema, value),
63
+ definition = catalog.commands[command.kind];
64
+ if (
65
+ Buffer.byteLength(JSON.stringify(command)) > catalog.maxCommandBytes ||
66
+ Object.keys(command.data).some((key) => !definition.fields.includes(key)) ||
67
+ (definition.create ? command.expectedRevision !== null : command.expectedRevision === null)
68
+ ) {
69
+ fail(
70
+ 'invalid_arguments',
71
+ 'Use the declared command fields and size limit. Creation requires a null revision; other commands require the current record revision.',
72
+ );
73
+ }
32
74
  const prefix = definition.module.startsWith('Memory/') ? 'memory:' : 'project:';
33
- if (!command.scope.startsWith(prefix) || definition.module.endsWith('/$') && command.id !== command.scope.slice(prefix.length)) fail('invalid_arguments', 'The command must target the matching project or memory scope.');
34
- if (command.kind === 'ticket.plan' && command.id !== command.scope.slice(8))
35
- fail('invalid_arguments', 'ticket.plan targets the project ID and root revision; changes carry each task expectedVersion.');
75
+ if (
76
+ !command.scope.startsWith(prefix) ||
77
+ (definition.module.endsWith('/$') && command.id !== command.scope.slice(prefix.length))
78
+ ) {
79
+ fail('invalid_arguments', 'The command must target the matching project or memory scope.');
80
+ }
81
+ if (
82
+ ['memory.create', 'project.create'].includes(command.kind) &&
83
+ (!/^[a-f\d]{8}-[a-f\d]{4}-4[a-f\d]{3}-[89ab][a-f\d]{3}-[a-f\d]{12}$/i.test(command.id) ||
84
+ command.epoch !== command.id)
85
+ ) {
86
+ fail(
87
+ 'invalid_arguments',
88
+ 'Create a space with a UUID v4 as id and the same initial epoch. Use project:<id> or memory:<id> as appropriate; keep source identifiers in page sourceId.',
89
+ );
90
+ }
91
+ if (command.kind === 'ticket.plan' && command.id !== command.scope.slice(8)) {
92
+ fail(
93
+ 'invalid_arguments',
94
+ 'ticket.plan targets the project ID and root revision; changes carry each task expectedVersion.',
95
+ );
96
+ }
36
97
  return command;
37
98
  }
38
- export function describeCommands() { return { ...catalog, envelope: z.toJSONSchema(commandSchema), draft: z.toJSONSchema(draftSchema),
39
- recovery: 'Retain operationId, issuedAt and the complete body. Retry an uncertain write unchanged; reread before creating a new edit after a conflict.' }; }
99
+ export function describeCommands() {
100
+ return {
101
+ ...catalog,
102
+ envelope: z.toJSONSchema(commandSchema),
103
+ draft: z.toJSONSchema(draftSchema),
104
+ recovery:
105
+ 'Retain operationId, issuedAt and the complete body. Retry an uncertain write unchanged; reread before creating a new edit after a conflict.',
106
+ };
107
+ }
108
+ /** Read one bounded regular JSON file, rejecting symlinks and non-file inputs. */
40
109
  export async function readCommandFile(path) {
41
- if (typeof path !== 'string') fail('invalid_arguments', 'Supply --file with a JSON command or draft.');
110
+ if (typeof path !== 'string') {
111
+ fail('invalid_arguments', 'Supply --file with a JSON command or draft.');
112
+ }
42
113
  let handle;
43
114
  try {
44
115
  handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
45
116
  const stat = await handle.stat();
46
- if (!stat.isFile() || stat.size > catalog.maxCommandBytes) fail('invalid_arguments', 'Use a regular JSON file no larger than 32 KiB.');
47
- const bytes = Buffer.alloc(catalog.maxCommandBytes + 1), result = await handle.read(bytes, 0, bytes.length, 0);
48
- if (result.bytesRead > catalog.maxCommandBytes) fail('invalid_arguments', 'Command file exceeds 32 KiB.');
117
+ if (!stat.isFile() || stat.size > catalog.maxCommandBytes) {
118
+ fail(
119
+ 'invalid_arguments',
120
+ `Use a regular JSON file no larger than ${catalog.maxCommandBytes} bytes.`,
121
+ );
122
+ }
123
+ const bytes = Buffer.alloc(catalog.maxCommandBytes + 1),
124
+ result = await handle.read(bytes, 0, bytes.length, 0);
125
+ if (result.bytesRead > catalog.maxCommandBytes) {
126
+ fail('invalid_arguments', `Command file exceeds ${catalog.maxCommandBytes} bytes.`);
127
+ }
49
128
  return JSON.parse(bytes.subarray(0, result.bytesRead).toString('utf8'));
50
129
  } catch (error) {
51
- if (error instanceof AgentError) throw error;
130
+ if (error instanceof AgentError) {
131
+ throw error;
132
+ }
52
133
  fail('invalid_arguments', 'Could not read a regular, valid JSON command file.');
53
- } finally { await handle?.close(); }
134
+ } finally {
135
+ await handle?.close();
136
+ }
54
137
  }
55
- const binding = session => ({ origin: session.origin, connectionId: session.connection_id, profileId: session.profile_id, sessionId: session.session_id });
56
- const receiptSchema = z.object({ operationId: operationIdSchema, scope: z.string(), kind: z.string(), epoch: z.string(), cursor: z.string(),
57
- items: z.array(z.object({ id: z.string(), revision: z.string(), collection: z.string(), deleted: z.boolean() }).strict()),
58
- affectedCollections: z.array(z.string()),
59
- }).strict();
138
+ const binding = (session) => ({
139
+ origin: session.origin,
140
+ connectionId: session.connection_id,
141
+ profileId: session.profile_id,
142
+ sessionId: session.session_id,
143
+ });
144
+ const receiptSchema = z
145
+ .object({
146
+ operationId: operationIdSchema,
147
+ scope: z.string(),
148
+ kind: z.string(),
149
+ epoch: z.string(),
150
+ cursor: z.string(),
151
+ items: z.array(
152
+ z
153
+ .object({
154
+ id: z.string(),
155
+ revision: z.string(),
156
+ collection: z.string(),
157
+ deleted: z.boolean(),
158
+ })
159
+ .strict(),
160
+ ),
161
+ affectedCollections: z.array(z.string()),
162
+ })
163
+ .strict();
60
164
 
61
165
  /** A journal is bound to one authenticated terminal identity. Persist the full
62
166
  * request before the network call, never regenerate a UUID after a timeout.
63
167
  * It contains private project text but no access/refresh tokens. A process crash
64
168
  * leaves its operation lock for explicit recovery after all clients stop. */
65
169
  export class CommandJournal {
66
- constructor(client) { this.client = client; }
170
+ constructor(client) {
171
+ this.client = client;
172
+ }
67
173
  store(id) {
68
174
  checked(operationIdSchema, id);
69
- return new CredentialStore({ directory: join(this.client.store.directory, 'operations', this.client.store.context), context: id, maxBytes: 524288 });
175
+ return new CredentialStore({
176
+ directory: join(this.client.store.directory, 'operations', this.client.store.context),
177
+ context: id,
178
+ maxBytes: 524288,
179
+ });
70
180
  }
71
181
  async prepare(draft) {
72
- const input = validateCommand({ ...checked(draftSchema, draft), operationId: randomUUID(), issuedAt: Date.now() });
73
- const identity = binding(await this.client.session()), store = this.store(input.operationId);
74
- await store.locked(() => store.write({ formatVersion: 1, binding: identity, input, state: 'prepared' }), this.client.transport.signal);
182
+ const input = validateCommand({
183
+ ...checked(draftSchema, draft),
184
+ operationId: randomUUID(),
185
+ issuedAt: Date.now(),
186
+ });
187
+ const identity = binding(await this.client.session()),
188
+ store = this.store(input.operationId);
189
+ await store.locked(
190
+ () => store.write({ formatVersion: 1, binding: identity, input, state: 'prepared' }),
191
+ this.client.transport.signal,
192
+ );
75
193
  return { operationId: input.operationId, state: 'prepared', request: input };
76
194
  }
77
195
  async inspect(id) {
78
196
  const row = await this.store(id).read();
79
- if (!row || row.formatVersion !== 1 || row.input?.operationId !== id) fail('operation_not_found', 'This context has no valid local operation with that ID.');
80
- return { operationId: id, source: 'local_journal', state: row.state, request: row.input, ...(row.receipt ? { receipt: row.receipt } : {}), ...(row.error ? { error: row.error } : {}) };
197
+ if (!row || row.formatVersion !== 1 || row.input?.operationId !== id) {
198
+ fail('operation_not_found', 'This context has no valid local operation with that ID.');
199
+ }
200
+ return {
201
+ operationId: id,
202
+ source: 'local_journal',
203
+ state: row.state,
204
+ request: row.input,
205
+ ...(row.receipt ? { receipt: row.receipt } : {}),
206
+ ...(row.error ? { error: row.error } : {}),
207
+ ...(row.retryAt ? { retryAt: row.retryAt } : {}),
208
+ };
81
209
  }
82
210
  async execute(value) {
83
- const input = validateCommand(value), store = this.store(input.operationId);
211
+ const input = validateCommand(value),
212
+ store = this.store(input.operationId);
84
213
  return store.locked(async () => {
85
214
  // Capture token and identity together under the refresh lock. A later
86
215
  // logout/login cannot turn this pending operation into another profile.
87
- const session = await this.client.authorizedSession(), identity = binding(session);
216
+ const localSession = await this.client.session(),
217
+ identity = binding(localSession);
88
218
  let row = await store.read();
89
- if (row && (row.formatVersion !== 1 || canonical(row.binding) !== canonical(identity)))
90
- fail('operation_identity_mismatch', 'This operation belongs to another connection, profile, session or environment.', { remediation: 'Inspect it locally and reread current records. Do not replay it through a replacement login.' });
91
- if (row && canonical(row.input) !== canonical(input))
92
- fail('idempotency_mismatch', 'The operation ID already belongs to a different immutable request.', { status: 409, remediation: 'Use commands inspect, then retry the saved operation.' });
93
- if (row?.state === 'confirmed') return { source: 'local_receipt', receipt: row.receipt };
219
+ if (row && (row.formatVersion !== 1 || canonical(row.binding) !== canonical(identity))) {
220
+ fail(
221
+ 'operation_identity_mismatch',
222
+ 'This operation belongs to another connection, profile, session or environment.',
223
+ {
224
+ remediation:
225
+ 'Inspect it locally and reread current records. Do not replay it through a replacement login.',
226
+ },
227
+ );
228
+ }
229
+ if (row && canonical(row.input) !== canonical(input)) {
230
+ fail(
231
+ 'idempotency_mismatch',
232
+ 'The operation ID already belongs to a different immutable request.',
233
+ { status: 409, remediation: 'Use commands inspect, then retry the saved operation.' },
234
+ );
235
+ }
236
+ if (row?.state === 'confirmed') {
237
+ return { source: 'local_receipt', receipt: row.receipt };
238
+ }
239
+ requireRetryReady(row?.retryAt);
240
+ const session = await this.client.authorizedSession();
241
+ if (canonical(binding(session)) !== canonical(identity)) {
242
+ fail('operation_identity_mismatch', 'The connection changed before transmission.');
243
+ }
94
244
  row = { formatVersion: 1, binding: identity, input, state: 'uncertain' };
95
245
  await store.write(row);
96
246
  try {
97
- const receipt = await this.client.transport.request('/api/agents/v1/commands', { method: 'POST', json: input, token: session.access_token });
98
- if (!receiptSchema.safeParse(receipt).success || ['operationId', 'scope', 'kind', 'epoch'].some(key => receipt[key] !== input[key]))
99
- fail('invalid_response', 'The command receipt was invalid. The server may have committed.', { execution: 'unknown', remediation: 'Retry the identical saved operation.' });
247
+ const receipt = await this.client.transport.request('/api/agents/v1/commands', {
248
+ method: 'POST',
249
+ json: input,
250
+ token: session.access_token,
251
+ });
252
+ if (
253
+ !receiptSchema.safeParse(receipt).success ||
254
+ ['operationId', 'scope', 'kind', 'epoch'].some((key) => receipt[key] !== input[key])
255
+ ) {
256
+ fail(
257
+ 'invalid_response',
258
+ 'The command receipt was invalid. The server may have committed.',
259
+ { execution: 'unknown', remediation: 'Retry the identical saved operation.' },
260
+ );
261
+ }
100
262
  await store.write({ ...row, state: 'confirmed', receipt });
101
263
  return { source: 'server', receipt };
102
264
  } catch (error) {
103
265
  const safe = safeError(error);
104
- const result = new AgentError(safe.code, safe.message, { status: safe.status, retryable: safe.retryable, remediation: safe.remediation,
105
- execution: 'unknown', ...safe.details, operationId: input.operationId });
266
+ const result = new AgentError(safe.code, safe.message, {
267
+ status: safe.status,
268
+ retryable: safe.retryable,
269
+ remediation: safe.remediation,
270
+ execution: 'unknown',
271
+ ...safe.details,
272
+ operationId: input.operationId,
273
+ });
106
274
  // The uncertainty marker is already durable. Preserve the useful original
107
275
  // error/operation ID even if disk pressure prevents saving diagnostics.
108
- await store.write({ ...row, error: result.toJSON() }).catch(() => {});
276
+ await store
277
+ .write({ ...row, retryAt: retryAt(result), error: result.toJSON() })
278
+ .catch(() => {});
109
279
  throw result;
110
280
  }
111
281
  }, this.client.transport.signal);
112
282
  }
113
- async retry(id) { return this.execute((await this.inspect(id)).request); }
283
+ async retry(id) {
284
+ return this.execute((await this.inspect(id)).request);
285
+ }
114
286
  }
@@ -0,0 +1,251 @@
1
+ import * as z from 'zod/v4';
2
+ import { readChanges } from './changes.mjs';
3
+ import { fail } from './errors.mjs';
4
+ const id = z.string().regex(/^[a-zA-Z0-9_-]{1,128}$/);
5
+ const recordSchema = z.object({
6
+ id,
7
+ revision: z.string().regex(/^[0-9]+$/),
8
+ data: z.record(z.string(), z.unknown()),
9
+ });
10
+ const parse = (schema, value) => {
11
+ const result = schema.safeParse(value);
12
+ if (!result.success) {
13
+ fail('invalid_response', 'The Graph source format is invalid.');
14
+ }
15
+ return result.data;
16
+ };
17
+ const contextOf = (tree) => ({ epoch: tree.epoch, checkpoint: tree.checkpoint });
18
+ const equivalentAccess = (before, tree) =>
19
+ before?.epoch === tree.epoch && before.accessRevision === tree.accessRevision;
20
+ const escape = (value) =>
21
+ String(value)
22
+ .replace(/[\r\n]/g, ' ')
23
+ .replace(/[\\`*_[\]<>|]/g, '\\$&');
24
+
25
+ async function graphCollection(client, scope, collection, tree, previous, cursor, downloads) {
26
+ const records = new Map((previous ?? []).map((record) => [record.id, record]));
27
+ if (cursor) {
28
+ try {
29
+ for (let count = 0; count < 1000; count++) {
30
+ const page = await readChanges(client, { scope, collection, cursor });
31
+ if (page.epoch !== tree.epoch || page.omittedIds.length) {
32
+ fail('incomplete_documentation', 'The Graph change response is incomplete.');
33
+ }
34
+ for (const item of page.items) {
35
+ if (item.kind === 'remove') {
36
+ records.delete(item.id);
37
+ } else {
38
+ records.set(
39
+ item.id,
40
+ parse(recordSchema, { id: item.id, revision: item.revision, data: item.data }),
41
+ );
42
+ }
43
+ }
44
+ cursor = page.nextCursor;
45
+ if (!page.hasMore) {
46
+ return { items: [...records.values()], cursor };
47
+ }
48
+ }
49
+ fail('documentation_capacity', 'The Graph change window exceeds its request budget.');
50
+ } catch (error) {
51
+ if (!['reset_required', 'agent_change_history_expired'].includes(error.code)) {
52
+ throw error;
53
+ }
54
+ records.clear(); // Explicit server reset: replace from a fresh bounded inventory.
55
+ }
56
+ }
57
+ let after;
58
+ for (let count = 0; count < 1000; count++) {
59
+ const query = { scope, collection, after, ...contextOf(tree) };
60
+ const key = JSON.stringify(query),
61
+ bucket = downloads.graphBucket(tree);
62
+ const cached = await downloads.read(scope, bucket, key, 8388608);
63
+ const page = cached
64
+ ? JSON.parse(cached.toString('utf8'))
65
+ : await client.get('resources', query);
66
+ if (
67
+ page.scope !== scope ||
68
+ page.collection !== collection ||
69
+ page.epoch !== tree.epoch ||
70
+ page.checkpoint !== tree.checkpoint ||
71
+ !Array.isArray(page.items) ||
72
+ page.items.length > 50 ||
73
+ !Array.isArray(page.omittedIds) ||
74
+ page.omittedIds.length
75
+ ) {
76
+ fail('incomplete_documentation', 'The Graph inventory is incomplete.');
77
+ }
78
+ for (const item of page.items) {
79
+ const record = parse(recordSchema, item);
80
+ if (records.has(record.id)) {
81
+ fail('invalid_response', 'The Graph inventory repeated an item.');
82
+ }
83
+ records.set(record.id, record);
84
+ }
85
+ if (!cached) {
86
+ await downloads.put(scope, bucket, key, Buffer.from(JSON.stringify(page)));
87
+ }
88
+ if (!page.nextAfter) {
89
+ if (!page.changeCursor) {
90
+ fail('invalid_response', 'The Graph inventory has no incremental cursor.');
91
+ }
92
+ return { items: [...records.values()], cursor: page.changeCursor };
93
+ }
94
+ if (page.nextAfter === after || page.nextAfter !== page.items.at(-1)?.id) {
95
+ fail('invalid_response', 'The Graph inventory cursor did not advance.');
96
+ }
97
+ after = page.nextAfter;
98
+ }
99
+ fail('documentation_capacity', 'The Graph inventory exceeds its request budget.');
100
+ }
101
+
102
+ export async function exportGraph(client, store, source, tree, previous, state, assets, downloads) {
103
+ if (!source.graph) {
104
+ return;
105
+ }
106
+ const file = `${source.scope.replace(':', '-')}/graph.json`;
107
+ const oldBytes =
108
+ previous?.graph && equivalentAccess(previous, tree)
109
+ ? await store.readPrevious(previous.graph.file)
110
+ : null;
111
+ const oldIndex = oldBytes ? JSON.parse(oldBytes.toString('utf8')) : null;
112
+ let old = oldIndex;
113
+ if (oldIndex?.formatVersion === 2) {
114
+ old = { nodes: [], edges: [] };
115
+ for (const collection of ['nodes', 'edges']) {
116
+ const chunks = oldIndex.chunks?.[collection];
117
+ if (!Array.isArray(chunks) || chunks.length > 300) {
118
+ fail('invalid_documentation_manifest', 'The Graph chunk index is invalid.');
119
+ }
120
+ for (const path of chunks) {
121
+ const bytes = await store.readPrevious(path);
122
+ if (!bytes) {
123
+ fail('invalid_documentation_manifest', 'A tracked Graph chunk is missing.');
124
+ }
125
+ const chunk = JSON.parse(bytes.toString('utf8'));
126
+ if (!Array.isArray(chunk) || chunk.length > 100) {
127
+ fail('invalid_documentation_manifest', 'A Graph chunk exceeds its bound.');
128
+ }
129
+ old[collection].push(...chunk.map((record) => parse(recordSchema, record)));
130
+ }
131
+ }
132
+ }
133
+ const nodes = await graphCollection(
134
+ client,
135
+ source.scope,
136
+ 'nodes',
137
+ tree,
138
+ old?.nodes,
139
+ old && previous.graph.nodesCursor,
140
+ downloads,
141
+ );
142
+ const edges = await graphCollection(
143
+ client,
144
+ source.scope,
145
+ 'edges',
146
+ tree,
147
+ old?.edges,
148
+ old && previous.graph.edgesCursor,
149
+ downloads,
150
+ );
151
+ if (nodes.items.length > 10000 || edges.items.length > 30000) {
152
+ fail('documentation_capacity', 'The Graph exceeds its source capacity.');
153
+ }
154
+ const ids = new Set(nodes.items.map((node) => node.id));
155
+ if (edges.items.some((edge) => !ids.has(edge.data.source) || !ids.has(edge.data.target))) {
156
+ fail(
157
+ 'read_context_changed',
158
+ 'The Graph has missing endpoints; refresh its source before exporting.',
159
+ );
160
+ }
161
+ for (const node of nodes.items) {
162
+ if (node.data.imageAssetId) {
163
+ assets.add(parse(id, node.data.imageAssetId));
164
+ }
165
+ }
166
+ // Bounded portable chunks keep large Graphs out of one enormous JSON/Markdown
167
+ // file. Borrowed references remain identities, never cached source bodies.
168
+ const notice =
169
+ '> Automatically generated from GeniusTasker. Edit through the [MCP](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/DOCUMENTATION_SYNC.md), then sync again.';
170
+ const footer = `Source scope: \`${source.scope}\` · Epoch: \`${tree.epoch}\` · Checkpoint: \`${tree.checkpoint}\``;
171
+ const overview = [
172
+ notice,
173
+ '',
174
+ `# ${escape(tree.title)} — Graph`,
175
+ '',
176
+ 'Linked Memory content is resolved online with current permissions. These files preserve this Graph’s own notes and qualified relations.',
177
+ '',
178
+ ];
179
+ const chunks = { nodes: [], edges: [] };
180
+ for (const [collection, records] of [
181
+ ['nodes', nodes.items],
182
+ ['edges', edges.items],
183
+ ]) {
184
+ records.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
185
+ for (let offset = 0; offset < records.length; offset += 100) {
186
+ const part = records.slice(offset, offset + 100),
187
+ name = `graph/${collection}-${String(offset / 100).padStart(4, '0')}`;
188
+ const path = `${source.scope.replace(':', '-')}/${name}`;
189
+ chunks[collection].push(path + '.json');
190
+ await store.put(path + '.json', JSON.stringify(part, null, 2) + '\n');
191
+ const text = [
192
+ notice,
193
+ '',
194
+ `# ${collection === 'nodes' ? 'Nodes' : 'Relations'} ${offset + 1}–${offset + part.length}`,
195
+ '',
196
+ ];
197
+ for (const record of part) {
198
+ if (collection === 'nodes') {
199
+ text.push(
200
+ `## ${escape(record.data.title ?? record.id)}`,
201
+ '',
202
+ String(record.data.text ?? record.data.summary ?? ''),
203
+ '',
204
+ );
205
+ for (const ref of record.data.references ?? []) {
206
+ text.push(
207
+ `- Memory reference: \`${escape(ref.scope)}\` / \`${escape(ref.pageId)}\`${ref.blockId ? ' / `' + escape(ref.blockId) + '`' : ''} (resolve current access)`,
208
+ );
209
+ }
210
+ } else {
211
+ text.push(
212
+ `## ${escape(record.data.label || record.data.relation)}`,
213
+ '',
214
+ `\`${escape(record.data.source)}\` → \`${escape(record.data.target)}\` · ${escape(record.data.certainty)}`,
215
+ '',
216
+ String(record.data.note ?? ''),
217
+ '',
218
+ );
219
+ }
220
+ text.push(
221
+ `Source ID: \`${record.id}\` · Revision: \`${record.revision}\` · Updated: ${escape(record.data.updated ?? 'unknown')} · Author: ${escape(record.data.lastEditor ?? record.data.creator ?? 'unknown')}`,
222
+ '',
223
+ );
224
+ }
225
+ text.push('', '---', '', footer, '');
226
+ await store.put(path + '.md', text.join('\n'));
227
+ overview.push(
228
+ `- [${collection === 'nodes' ? 'Nodes' : 'Relations'} ${offset + 1}–${offset + part.length}](${name}.md) · [JSON](${name}.json)`,
229
+ );
230
+ }
231
+ }
232
+ overview.push('', '---', '', footer, '');
233
+ await store.put(file.replace('.json', '.md'), overview.join('\n'));
234
+ await store.put(
235
+ file,
236
+ JSON.stringify(
237
+ {
238
+ formatVersion: 2,
239
+ scope: source.scope,
240
+ epoch: tree.epoch,
241
+ counts: { nodes: nodes.items.length, edges: edges.items.length },
242
+ chunks,
243
+ referencePolicy:
244
+ 'Resolve linked Memory content online with current access. Unavailable targets do not remove nodes.',
245
+ },
246
+ null,
247
+ 2,
248
+ ) + '\n',
249
+ );
250
+ state.graph = { file, nodesCursor: nodes.cursor, edgesCursor: edges.cursor };
251
+ }