@pulsarinteractive/geniustasker 0.1.0-beta.4 → 0.1.0-beta.6

package/skills/geniustasker-media/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: geniustasker-media
+description: Compare, reuse, upload and link GeniusTasker Memory resources with stable asset IDs. Use when maintaining document images, attachments or Graph thumbnails, especially when replacing an existing visual.
+---
+
+# Memory resources
+
+Discover `mediaUploadAvailable`, the current scope and the necessary media
+permissions. Work only with explicitly selected files and destinations.
+
+Before replacing an existing resource, call `tasker_media_compare` with the
+local file, scope and asset ID. Equal bytes should reuse that ID without an upload
+or new document revision. When bytes differ, inspect the old and new image or
+media: a different checksum does not establish a visual improvement. Explain the
+actual change before describing it as improved.
+
+Prepare authorized uploads with `tasker_media_prepare`; retain the operation ID
+and use `tasker_media_upload`. Retry uncertain transfers with that same ID.
+Link the returned asset ID from document blocks or node thumbnails; never embed
+base64 or public bucket URLs. One asset can have many uses without duplicate
+storage. Asset bytes belong to the owning Memory’s quota.
+
+Changing an image means publishing a new immutable resource and updating the
+intended references with their current revisions. Reuse the old resource for any
+pages that should keep it. When `protectedMemoryAssets` is advertised, removal
+of an in-use resource returns `memory_asset_in_use`, including hidden uses.
+Do not probe private page names or remove other users’ links to bypass the guard.
+After the last authorized use is removed, normal resource removal can proceed.
+
+After relevant edits, sync any configured repository documentation. Its optional
+local media are derived snapshots; do not hand-edit them and claim the source was
+updated. Report actual IDs, changed references and verification, without exposing
+unrelated private source content.

package/skills/geniustasker-media/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'GeniusTasker Resources'
+  short_description: 'Compare and reuse private document media'
+  default_prompt: 'Use $geniustasker-media for the selected GeniusTasker knowledge workflow.'

package/skills/geniustasker-memory/SKILL.md

@@ -13,7 +13,7 @@ Do not collect passwords or tokens, approve your own consent, or edit credential
 
 1. Call `tasker_identity` and `tasker_capabilities` (CLI `whoami`, `capabilities`).
 2. Use `tasker_memories` / `memories list`. Follow `nextAfter`, including empty pages.
-3. Read `tasker_resources` with a discovered `memory:ID` scope and `collection: pageIndex`.
+3. When `documentationSync` is advertised, use `tasker_memory_tree` to navigate folders and compare branch versions. Otherwise read `tasker_resources` with `collection: pageIndex`.
 4. Fetch the needed `pages` by `id` or `path`. Targeted reads do not return a change cursor.
 5. Use `tasker_search` (`memory search`) to find page or node excerpts. Read the
    full record before editing; an excerpt does not establish the full context.
@@ -83,7 +83,10 @@ type; retain the operation ID and pass it to `tasker_media_upload`. After a time
 retry that same ID. Link its returned assetId from an image or attachment block.
 Do not embed base64 files in documents. Use an explicit new destination for
 `tasker_media_download`; never upload a directory or private administrative files.
-The Memory owner pays for the bytes. Removed files leave repairable block links.
+The Memory owner pays for the bytes. Compare proposed replacements with
+`tasker_media_compare` and reuse an identical asset ID. When
+`protectedMemoryAssets` is advertised, in-use resource deletion is blocked,
+including private-page and Graph uses; unlink only the authorized references.
 Image/PDF/text support and byte limits come from capabilities, not guesswork.
 Report what was actually stored, verified, skipped and still pending without
 exposing private source content.
@@ -111,3 +114,7 @@ shows every type and supports type/status filters. Prefer `auto`; an explicit
 Upload only approved imagery. Attaching a private image to a shared Graph makes
 it visible to that Graph's readers and requires the user's authorization.
 Read the full current record before editing and preserve its revision.
+
+For a repository documentation mirror, use the documentation skill and packaged
+`docs/DOCUMENTATION_SYNC.md`: check at least once per working day before relying
+on the local copy, and sync again after relevant completed changes.

package/src/cli.mjs

@@ -1,3 +1,9 @@
+import { readFile } from 'node:fs/promises';
+import {
+  syncDocumentation,
+  documentationStatus,
+  unlockDocumentation,
+} from './documentation-sync.mjs';
 import open, { apps } from 'open';
 import catalog from './command-catalog.mjs';
 import { CredentialStore } from './store.mjs';
@@ -7,8 +13,9 @@ import { deviceLogin, browserLogin } from './login.mjs';
 import { CommandJournal, describeCommands, readCommandFile } from './commands.mjs';
 import { AgentProfiles } from './profiles.mjs';
 import { readChanges, watchChanges } from './changes.mjs';
+import { readMemoryTree, readMemoryMarkdown } from './documentation.mjs';
 import { searchMemory, exploreGraph, resolveMemory } from './knowledge.mjs';
-import { MediaJournal, mediaAction, downloadMedia } from './media.mjs';
+import { MediaJournal, mediaAction, downloadMedia, compareMedia } from './media.mjs';
 import { fail, safeError, exitCode } from './errors.mjs';
 
 export const commands = {
@@ -49,6 +56,10 @@ export const commands = {
     summary: 'List independent account memories; follow nextAfter even for an empty page.',
     options: ['after'],
   },
+  'media compare': {
+    summary: 'Compare a local file with an existing resource before uploading a replacement.',
+    options: ['scope', 'id', 'file'],
+  },
   'media prepare': {
     summary: 'Prepare a local private attachment; retain its operation ID.',
     options: ['scope', 'file', 'content-type', 'epoch'],
@@ -65,6 +76,26 @@ export const commands = {
     summary: 'Download an authorized attachment to a new local file.',
     options: ['scope', 'owner', 'id', 'file'],
   },
+  'docs sync': {
+    summary: 'Refresh selected Memory/Graph sources in a managed local documentation directory.',
+    options: ['directory', 'file', 'max-files', 'max-bytes'],
+  },
+  'docs status': {
+    summary: 'Inspect the local snapshot date and selections without a network request.',
+    options: ['directory'],
+  },
+  'docs unlock': {
+    summary: 'Remove a sync lock only when its process on this host has stopped.',
+    options: ['directory'],
+  },
+  'memory tree': {
+    summary: 'Read one folder and descendant versions; unchanged validators avoid page bodies.',
+    options: ['scope', 'parent', 'after', 'epoch', 'checkpoint', 'if-none-match'],
+  },
+  'memory markdown': {
+    summary: 'Fetch one portable Markdown document with stable media IDs and source metadata.',
+    options: ['scope', 'page', 'revision', 'epoch', 'checkpoint'],
+  },
   'memory search': {
     summary: 'Search document blocks or Graph nodes without loading the corpus.',
     options: ['scope', 'query', 'collection', 'after', 'epoch', 'checkpoint'],
@@ -343,6 +374,52 @@ export async function main(
                 ? {}
                 : { waitSeconds: Number(options['wait-seconds']) }),
             });
+    } else if (command === 'docs sync') {
+      let configuration;
+      if (options.file) {
+        const raw = await readFile(options.file, 'utf8');
+        if (Buffer.byteLength(raw) > 32768) {
+          fail('invalid_arguments', 'The source configuration is too large.');
+        }
+        try {
+          configuration = JSON.parse(raw);
+        } catch {
+          fail('invalid_arguments', 'The source configuration must be JSON.');
+        }
+      }
+      data = await syncDocumentation(client, {
+        directory: options.directory,
+        configuration,
+        maxFiles: options['max-files'] === undefined ? undefined : Number(options['max-files']),
+        maxBytes: options['max-bytes'] === undefined ? undefined : Number(options['max-bytes']),
+      });
+    } else if (command === 'docs status' || command === 'docs unlock') {
+      data = await (command === 'docs status' ? documentationStatus : unlockDocumentation)({
+        directory: options.directory,
+      });
+    } else if (command === 'memory tree') {
+      data = await readMemoryTree(client, {
+        scope: options.scope,
+        parentId: options.parent,
+        after: options.after,
+        epoch: options.epoch,
+        checkpoint: options.checkpoint,
+        ifNoneMatch: options['if-none-match'],
+      });
+    } else if (command === 'memory markdown') {
+      data = await readMemoryMarkdown(client, {
+        scope: options.scope,
+        pageId: options.page,
+        revision: options.revision,
+        epoch: options.epoch,
+        checkpoint: options.checkpoint,
+      });
+    } else if (command === 'media compare') {
+      data = await compareMedia(client, {
+        scope: options.scope,
+        id: options.id,
+        file: options.file,
+      });
     } else if (command === 'media prepare') {
       data = await new MediaJournal(client).prepare({
         scope: options.scope,

package/src/client.mjs

@@ -180,6 +180,8 @@ export class AgentClient {
         'changes',
         'knowledge',
         'reference',
+        'memory/tree',
+        'memory/markdown',
       ].includes(resource)
     ) {
       fail('invalid_arguments', 'Unknown delegated resource.');

package/src/command-catalog.mjs

@@ -55,6 +55,29 @@ export default {
       "module": "Project/ProjectTaskComment",
       "permission": "comments:write"
     },
+    "filter.create": {
+      "create": true,
+      "fields": [
+        "name",
+        "criteria"
+      ],
+      "module": "Project/ProjectTaskFilter",
+      "permission": "tasks:write"
+    },
+    "filter.delete": {
+      "delete": true,
+      "fields": [],
+      "module": "Project/ProjectTaskFilter",
+      "permission": "tasks:write"
+    },
+    "filter.update": {
+      "fields": [
+        "name",
+        "criteria"
+      ],
+      "module": "Project/ProjectTaskFilter",
+      "permission": "tasks:write"
+    },
     "goal.create": {
       "create": true,
       "fields": [
@@ -279,6 +302,31 @@ export default {
       "module": "$private/VoteDraft",
       "permission": "questions:write"
     },
+    "tag.create": {
+      "create": true,
+      "fields": [
+        "name",
+        "backgroundColor",
+        "textColor"
+      ],
+      "module": "Project/ProjectCustomTag",
+      "permission": "tasks:write"
+    },
+    "tag.delete": {
+      "delete": true,
+      "fields": [],
+      "module": "Project/ProjectCustomTag",
+      "permission": "tasks:write"
+    },
+    "tag.update": {
+      "fields": [
+        "name",
+        "backgroundColor",
+        "textColor"
+      ],
+      "module": "Project/ProjectCustomTag",
+      "permission": "tasks:write"
+    },
     "task.archive": {
       "fields": [],
       "module": "Project/ProjectTask",

package/src/documentation-graph.mjs

@@ -0,0 +1,251 @@
+import * as z from 'zod/v4';
+import { readChanges } from './changes.mjs';
+import { fail } from './errors.mjs';
+const id = z.string().regex(/^[a-zA-Z0-9_-]{1,128}$/);
+const recordSchema = z.object({
+  id,
+  revision: z.string().regex(/^[0-9]+$/),
+  data: z.record(z.string(), z.unknown()),
+});
+const parse = (schema, value) => {
+  const result = schema.safeParse(value);
+  if (!result.success) {
+    fail('invalid_response', 'The Graph source format is invalid.');
+  }
+  return result.data;
+};
+const contextOf = (tree) => ({ epoch: tree.epoch, checkpoint: tree.checkpoint });
+const equivalentAccess = (before, tree) =>
+  before?.epoch === tree.epoch && before.accessRevision === tree.accessRevision;
+const escape = (value) =>
+  String(value)
+    .replace(/[\r\n]/g, ' ')
+    .replace(/[\\`*_[\]<>|]/g, '\\$&');
+
+async function graphCollection(client, scope, collection, tree, previous, cursor, downloads) {
+  const records = new Map((previous ?? []).map((record) => [record.id, record]));
+  if (cursor) {
+    try {
+      for (let count = 0; count < 1000; count++) {
+        const page = await readChanges(client, { scope, collection, cursor });
+        if (page.epoch !== tree.epoch || page.omittedIds.length) {
+          fail('incomplete_documentation', 'The Graph change response is incomplete.');
+        }
+        for (const item of page.items) {
+          if (item.kind === 'remove') {
+            records.delete(item.id);
+          } else {
+            records.set(
+              item.id,
+              parse(recordSchema, { id: item.id, revision: item.revision, data: item.data }),
+            );
+          }
+        }
+        cursor = page.nextCursor;
+        if (!page.hasMore) {
+          return { items: [...records.values()], cursor };
+        }
+      }
+      fail('documentation_capacity', 'The Graph change window exceeds its request budget.');
+    } catch (error) {
+      if (!['reset_required', 'agent_change_history_expired'].includes(error.code)) {
+        throw error;
+      }
+      records.clear(); // Explicit server reset: replace from a fresh bounded inventory.
+    }
+  }
+  let after;
+  for (let count = 0; count < 1000; count++) {
+    const query = { scope, collection, after, ...contextOf(tree) };
+    const key = JSON.stringify(query),
+      bucket = downloads.graphBucket(tree);
+    const cached = await downloads.read(scope, bucket, key, 8388608);
+    const page = cached
+      ? JSON.parse(cached.toString('utf8'))
+      : await client.get('resources', query);
+    if (
+      page.scope !== scope ||
+      page.collection !== collection ||
+      page.epoch !== tree.epoch ||
+      page.checkpoint !== tree.checkpoint ||
+      !Array.isArray(page.items) ||
+      page.items.length > 50 ||
+      !Array.isArray(page.omittedIds) ||
+      page.omittedIds.length
+    ) {
+      fail('incomplete_documentation', 'The Graph inventory is incomplete.');
+    }
+    for (const item of page.items) {
+      const record = parse(recordSchema, item);
+      if (records.has(record.id)) {
+        fail('invalid_response', 'The Graph inventory repeated an item.');
+      }
+      records.set(record.id, record);
+    }
+    if (!cached) {
+      await downloads.put(scope, bucket, key, Buffer.from(JSON.stringify(page)));
+    }
+    if (!page.nextAfter) {
+      if (!page.changeCursor) {
+        fail('invalid_response', 'The Graph inventory has no incremental cursor.');
+      }
+      return { items: [...records.values()], cursor: page.changeCursor };
+    }
+    if (page.nextAfter === after || page.nextAfter !== page.items.at(-1)?.id) {
+      fail('invalid_response', 'The Graph inventory cursor did not advance.');
+    }
+    after = page.nextAfter;
+  }
+  fail('documentation_capacity', 'The Graph inventory exceeds its request budget.');
+}
+
+export async function exportGraph(client, store, source, tree, previous, state, assets, downloads) {
+  if (!source.graph) {
+    return;
+  }
+  const file = `${source.scope.replace(':', '-')}/graph.json`;
+  const oldBytes =
+    previous?.graph && equivalentAccess(previous, tree)
+      ? await store.readPrevious(previous.graph.file)
+      : null;
+  const oldIndex = oldBytes ? JSON.parse(oldBytes.toString('utf8')) : null;
+  let old = oldIndex;
+  if (oldIndex?.formatVersion === 2) {
+    old = { nodes: [], edges: [] };
+    for (const collection of ['nodes', 'edges']) {
+      const chunks = oldIndex.chunks?.[collection];
+      if (!Array.isArray(chunks) || chunks.length > 300) {
+        fail('invalid_documentation_manifest', 'The Graph chunk index is invalid.');
+      }
+      for (const path of chunks) {
+        const bytes = await store.readPrevious(path);
+        if (!bytes) {
+          fail('invalid_documentation_manifest', 'A tracked Graph chunk is missing.');
+        }
+        const chunk = JSON.parse(bytes.toString('utf8'));
+        if (!Array.isArray(chunk) || chunk.length > 100) {
+          fail('invalid_documentation_manifest', 'A Graph chunk exceeds its bound.');
+        }
+        old[collection].push(...chunk.map((record) => parse(recordSchema, record)));
+      }
+    }
+  }
+  const nodes = await graphCollection(
+    client,
+    source.scope,
+    'nodes',
+    tree,
+    old?.nodes,
+    old && previous.graph.nodesCursor,
+    downloads,
+  );
+  const edges = await graphCollection(
+    client,
+    source.scope,
+    'edges',
+    tree,
+    old?.edges,
+    old && previous.graph.edgesCursor,
+    downloads,
+  );
+  if (nodes.items.length > 10000 || edges.items.length > 30000) {
+    fail('documentation_capacity', 'The Graph exceeds its source capacity.');
+  }
+  const ids = new Set(nodes.items.map((node) => node.id));
+  if (edges.items.some((edge) => !ids.has(edge.data.source) || !ids.has(edge.data.target))) {
+    fail(
+      'read_context_changed',
+      'The Graph has missing endpoints; refresh its source before exporting.',
+    );
+  }
+  for (const node of nodes.items) {
+    if (node.data.imageAssetId) {
+      assets.add(parse(id, node.data.imageAssetId));
+    }
+  }
+  // Bounded portable chunks keep large Graphs out of one enormous JSON/Markdown
+  // file. Borrowed references remain identities, never cached source bodies.
+  const notice =
+    '> Automatically generated from GeniusTasker. Edit through the [MCP](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/DOCUMENTATION_SYNC.md), then sync again.';
+  const footer = `Source scope: \`${source.scope}\` · Epoch: \`${tree.epoch}\` · Checkpoint: \`${tree.checkpoint}\``;
+  const overview = [
+    notice,
+    '',
+    `# ${escape(tree.title)} — Graph`,
+    '',
+    'Linked Memory content is resolved online with current permissions. These files preserve this Graph’s own notes and qualified relations.',
+    '',
+  ];
+  const chunks = { nodes: [], edges: [] };
+  for (const [collection, records] of [
+    ['nodes', nodes.items],
+    ['edges', edges.items],
+  ]) {
+    records.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    for (let offset = 0; offset < records.length; offset += 100) {
+      const part = records.slice(offset, offset + 100),
+        name = `graph/${collection}-${String(offset / 100).padStart(4, '0')}`;
+      const path = `${source.scope.replace(':', '-')}/${name}`;
+      chunks[collection].push(path + '.json');
+      await store.put(path + '.json', JSON.stringify(part, null, 2) + '\n');
+      const text = [
+        notice,
+        '',
+        `# ${collection === 'nodes' ? 'Nodes' : 'Relations'} ${offset + 1}–${offset + part.length}`,
+        '',
+      ];
+      for (const record of part) {
+        if (collection === 'nodes') {
+          text.push(
+            `## ${escape(record.data.title ?? record.id)}`,
+            '',
+            String(record.data.text ?? record.data.summary ?? ''),
+            '',
+          );
+          for (const ref of record.data.references ?? []) {
+            text.push(
+              `- Memory reference: \`${escape(ref.scope)}\` / \`${escape(ref.pageId)}\`${ref.blockId ? ' / `' + escape(ref.blockId) + '`' : ''} (resolve current access)`,
+            );
+          }
+        } else {
+          text.push(
+            `## ${escape(record.data.label || record.data.relation)}`,
+            '',
+            `\`${escape(record.data.source)}\` → \`${escape(record.data.target)}\` · ${escape(record.data.certainty)}`,
+            '',
+            String(record.data.note ?? ''),
+            '',
+          );
+        }
+        text.push(
+          `Source ID: \`${record.id}\` · Revision: \`${record.revision}\` · Updated: ${escape(record.data.updated ?? 'unknown')} · Author: ${escape(record.data.lastEditor ?? record.data.creator ?? 'unknown')}`,
+          '',
+        );
+      }
+      text.push('', '---', '', footer, '');
+      await store.put(path + '.md', text.join('\n'));
+      overview.push(
+        `- [${collection === 'nodes' ? 'Nodes' : 'Relations'} ${offset + 1}–${offset + part.length}](${name}.md) · [JSON](${name}.json)`,
+      );
+    }
+  }
+  overview.push('', '---', '', footer, '');
+  await store.put(file.replace('.json', '.md'), overview.join('\n'));
+  await store.put(
+    file,
+    JSON.stringify(
+      {
+        formatVersion: 2,
+        scope: source.scope,
+        epoch: tree.epoch,
+        counts: { nodes: nodes.items.length, edges: edges.items.length },
+        chunks,
+        referencePolicy:
+          'Resolve linked Memory content online with current access. Unavailable targets do not remove nodes.',
+      },
+      null,
+      2,
+    ) + '\n',
+  );
+  state.graph = { file, nodesCursor: nodes.cursor, edgesCursor: edges.cursor };
+}