@pulsarinteractive/geniustasker 0.1.0-beta.10 → 0.1.0-beta.12

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,29 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.0-beta.12 — 2026-11-16
4
+
5
+ - Add an opt-in host event adapter to CLI/local MCP with stable IDs/times, prepare-only support and the normal immutable journal. Process exit requests review, never task completion; no process/log capture or automatic polling.
6
+ - Clarify Memory cooperation, hosted versus local retries and server-owned latest-agent attribution; preserve concurrent contributions after explicit revision conflicts.
7
+
8
+ - Agent run workflows document explicit claims, real checkpoints, fenced task patches and truthful completion across CLI and MCP.
9
+
10
+ - Protocol command help now includes filtered, generated nested schemas, nullability and limits in the CLI and local MCP, with an explicit publish example.
11
+
12
+ - Add task protocol preview to CLI/local MCP and the hosted tool catalogue, with a read-only POST, digest-bound pagination, explicit 20-step apply commands and a shared protocol workflow.
13
+
14
+ - Explain impact-based task importance, short reasons for agent-classified Important/Critical work, preservation of human choices and the same workflow across CLI/local MCP/hosted guides. Field availability is discovered from the service; this is not a claim of Flutter notification-threshold delivery.
15
+ - Discover updates at most once per UTC day and installed version in interactive terminals, with bounded anonymous npm checks and an opt-out. JSON, MCP, CI and local-only commands do not check automatically.
16
+ - Add `update check` and explicit `update install` with beta/stable channel selection. Global npm installation is verified before and after the update; local/npx/managed copies receive manual guidance.
17
+ - Keep simultaneous CLI commands and long-lived MCP servers protected from installation through per-process activity leases. Credentials and immutable operation journals are unchanged.
18
+
19
+ ## 0.1.0-beta.11 — 2026-10-26
20
+
21
+ - Update the transitive URI parser to its patched 3.1.9 release.
22
+
23
+ - Preserve sessions and immutable command journals on temporary edge refusals. Respect numeric and HTTP-date Retry-After deadlines across CLI restarts, with positive jitter and no automatic replay. Recognized API permission refusals keep their existing behavior.
24
+
25
+ - Correct CLI help to describe the official login's requested-permission defaults.
26
+
3
27
  ## 0.1.0-beta.10
4
28
 
5
29
  - Add project creation/settings/deletion with the distinct `projects:write` permission. Existing grants do not expand automatically.
package/README.md CHANGED
@@ -33,6 +33,12 @@ Installing the package does not grant application access.
33
33
  Availability follows your account, the permissions you approve and the service's
34
34
  current capabilities. [Memory & Graph guide](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/MEMORY.md).
35
35
 
36
+ In a terminal, the CLI checks for a newer release at most once per UTC day and
37
+ installed version. It never installs automatically. Use `geniustasker update check
38
+ --json` to check explicitly, and `geniustasker update install` to update a global
39
+ npm installation after closing other CLI commands and local MCP servers.
40
+ See [updates and managed installations](docs/CLI.md#updates).
41
+
36
42
  ## Connect your AI assistant
37
43
 
38
44
  For a stdio MCP host, use this after signing in:
@@ -42,7 +48,7 @@ For a stdio MCP host, use this after signing in:
42
48
  "mcpServers": {
43
49
  "geniustasker": {
44
50
  "command": "npx",
45
- "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.10", "mcp", "--context", "work"]
51
+ "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.12", "mcp", "--context", "work"]
46
52
  }
47
53
  }
48
54
  }
@@ -19,19 +19,21 @@ flowchart LR
19
19
 
20
20
  ## Module responsibilities
21
21
 
22
- | Module | Responsibility |
23
- | --------------------- | --------------------------------------------------------------------------- |
24
- | `cli.mjs` | Argument validation, context/environment selection, output and exit status |
25
- | `login.mjs` | Browser PKCE consent, loopback callback validation and optional device flow |
26
- | `store.mjs` | Private local files, atomic replacement and inter-process locking |
27
- | `client.mjs` | Origin-bound sessions, serialized renewal, profile selection and reads |
28
- | `transport.mjs` | Allowed origins/routes, timeouts, size limits and sanitized API failures |
29
- | `commands.mjs` | Validated command envelopes and durable immutable operation journals |
30
- | `profiles.mjs` | Bounded profile discovery, creation, restriction and selection |
31
- | `changes.mjs` | Validated incremental reads and bounded, cancellable waits |
32
- | `mcp.mjs` | Strict tool schemas and protocol-safe responses over stdio |
33
- | `errors.mjs` | Stable errors, safe serialization and CLI exit codes |
34
- | `command-catalog.mjs` | Generated public interface definitions and limits |
22
+ | Module | Responsibility |
23
+ | --------------------- | ------------------------------------------------------------------------------------ |
24
+ | `cli.mjs` | Argument validation, context/environment selection, output and exit status |
25
+ | `login.mjs` | Browser PKCE consent, loopback callback validation and optional device flow |
26
+ | `store.mjs` | Private local files, atomic replacement and inter-process locking |
27
+ | `client.mjs` | Origin-bound sessions, serialized renewal, profile selection and reads |
28
+ | `transport.mjs` | Allowed origins/routes, timeouts, size limits and sanitized API failures |
29
+ | `commands.mjs` | Validated command envelopes and durable immutable operation journals |
30
+ | `profiles.mjs` | Bounded profile discovery, creation, restriction and selection |
31
+ | `changes.mjs` | Validated incremental reads and bounded, cancellable waits |
32
+ | `mcp.mjs` | Strict tool schemas and protocol-safe responses over stdio |
33
+ | `errors.mjs` | Stable errors, safe serialization and CLI exit codes |
34
+ | `update.mjs` | Anonymous bounded npm discovery, daily attempt cache and explicit global npm updates |
35
+ | `update-runtime.mjs` | Concurrent CLI/MCP activity leases and an exclusive installation barrier |
36
+ | `command-catalog.mjs` | Generated public interface definitions and limits |
35
37
 
36
38
  ## Authentication and renewal
37
39
 
package/docs/CLI.md CHANGED
@@ -5,6 +5,31 @@ comment, ask questions and keep a useful handoff. Your account and project
5
5
  permissions remain the limit. GeniusTasker does not run your agent or bill its
6
6
  external model tokens.
7
7
 
8
+ ## Task protocols
9
+
10
+ Discover `taskTemplates`, `protocolInstances` and the `protocol.*` commands in
11
+ capabilities before using this workflow. Protocols are versioned procedures for
12
+ Details projects, with stable task keys, dependencies and acceptance criteria.
13
+
14
+ ```sh
15
+ geniustasker workflow show --topic protocols --json
16
+ geniustasker protocols preview --file protocol-preview.json --context work --json
17
+ ```
18
+
19
+ The file contains `scope`, `protocolVersionId` and `bindings` with `instanceId`,
20
+ matching `scope`, current `epoch`, a timezone-qualified `anchor` and primitive
21
+ `values`. Preview performs one read-only POST with `tasks:read`, returns at most
22
+ 20 steps and never creates tasks. For another page, preserve these fields and
23
+ add `after: nextAfter` plus the returned `digest`. Each call consumes the normal
24
+ read budget. There is no automatic pagination or apply loop.
25
+
26
+ Use `protocol.publish/start/apply/cancel` through the existing `commands prepare`
27
+ and `commands retry` workflow only for requested changes. `protocol.apply` takes
28
+ `digest`, `from` and `count` (1–20) with the current instance revision. `Applied`
29
+ means the tasks exist, not that their work is done. Cancellation preserves tasks
30
+ already created. Follow the [protocol guide](../skills/geniustasker/references/protocols.md)
31
+ for binding, importance, permissions, recovery and hosted MCP equivalents.
32
+
8
33
  ## Install and connect
9
34
 
10
35
  Requires Node.js 22.13 or newer. Install the beta:
@@ -55,7 +80,7 @@ launching stdio servers with this entry (adjust environment/context as needed):
55
80
  "mcpServers": {
56
81
  "geniustasker": {
57
82
  "command": "npx",
58
- "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.10", "mcp", "--context", "work"]
83
+ "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.12", "mcp", "--context", "work"]
59
84
  }
60
85
  }
61
86
  }
@@ -442,3 +467,86 @@ it visible to that Graph's readers and requires the user's authorization.
442
467
  Read the full current record before editing and preserve its revision.
443
468
 
444
469
  For project-owned reusable task selections, see [Shared project filters](PROJECT_FILTERS.md).
470
+
471
+ ## Updates
472
+
473
+ ```sh
474
+ geniustasker update check --json
475
+ geniustasker update check --channel stable --json
476
+ # Close local MCP servers and let other CLI commands finish before installing.
477
+ geniustasker update install --json
478
+ ```
479
+
480
+ The default channel follows the installed version: a `-beta.N` release checks
481
+ `beta`; a stable release checks `latest` and rejects prereleases on that tag.
482
+ `--channel beta|stable` selects a channel for that invocation. The updater pins the
483
+ checked version and never downgrades. Switching from beta to stable therefore
484
+ waits for a stable version newer than the installed beta. The returned
485
+ `installedVersion`, `availableVersion`, `channel` and `updateAvailable` explain
486
+ that comparison.
487
+
488
+ After a successful interactive command, automatic discovery makes at most one
489
+ anonymous registry attempt per UTC day and installed version, even across
490
+ concurrent terminals or a failed check. Its deadline is 900 ms. The notice goes
491
+ to stderr; the command result is unchanged. MCP, `--json`, redirected output,
492
+ CI, help and local-only inspection/preparation commands never check automatically.
493
+ Set `GENIUSTASKER_NO_UPDATE_CHECK=1` to disable terminal discovery. Explicit checks
494
+ remain available and have a 1.5-second deadline. No account credentials are sent
495
+ to npm, and no GeniusTasker API quota is used.
496
+
497
+ `update install` supports only the active global npm installation. It checks
498
+ `npm root --global` against the actual package path; source checkouts, npm links,
499
+ project dependencies, npx copies and other managed installations require their
500
+ own update workflow. An npx pin in an MCP configuration does not change when a
501
+ global installation is updated. The installer fixes both npm registry settings to
502
+ `https://registry.npmjs.org`, disables lifecycle scripts, enforces Node engines,
503
+ and verifies the installed package name/version. It never elevates privileges.
504
+ The npm log is not copied into CLI output.
505
+
506
+ An installation barrier prevents replacement while another command or local MCP
507
+ process from this installation is active. Ordinary commands still run in
508
+ parallel. A running MCP process must be closed, even if currently idle; restart
509
+ it after the update. Stop older clients that predate this activity guard as well.
510
+ Credentials and pending immutable command journals are neither read nor modified
511
+ by the updater. An update does not replay any saved operation.
512
+
513
+ The small disposable discovery markers live in
514
+ `~/.cache/geniustasker/cli-updates`; normal checks retain only the current and
515
+ previous UTC day, inspecting at most 64 entries per pass. Runtime activity lives
516
+ separately under `~/.cache/geniustasker/cli-runtime/<installation-hash>/active`.
517
+ Only records belonging to positively dead processes are reclaimed during an
518
+ installation. Unknown files and possibly reused PIDs conservatively block it.
519
+ Do not clear runtime activity while clients are running.
520
+
521
+ If an installer is interrupted, its empty `install.lock` directory in that same
522
+ installation-specific runtime directory remains. First confirm that every local
523
+ GeniusTasker client and npm installer has stopped, then remove only that empty
524
+ lock directory with `rmdir`. Do not delete credentials, journals, or active-process
525
+ records. After `update_install_unconfirmed`, inspect the global installed version
526
+ and package integrity before retrying; an interrupted npm operation may already
527
+ have changed files. A successful result uses `state: installed`; an already
528
+ current or newer installation uses `state: up_to_date`.
529
+
530
+ Protocol command schemas are available offline with
531
+ `geniustasker commands describe --kind protocol.publish --json` (also
532
+ `protocol.start`, `protocol.apply`, `protocol.cancel`). `tasker_command_help`
533
+ provides the same local MCP guidance. Use the required fields and nested limits;
534
+ current authorization and semantic validation remain server-side.
535
+
536
+ ## Agent runs
537
+
538
+ Discover the `agentRuns` collection and `run.claim`, `run.checkpoint`, `run.patch`,
539
+ `run.finish` commands before using them. Inspect each schema with
540
+ `geniustasker commands describe --kind run.claim --json`, then use the normal
541
+ immutable command journal. [The run workflow](../skills/geniustasker/references/agent-runs.md)
542
+ explains separate run/task revisions, real checkpoints, stale leases, human
543
+ takeover and recovery. Finishing a run does not mark its task Done; no background
544
+ agent execution or monitoring is implied.
545
+
546
+ For an explicitly instrumented host, `geniustasker runs event --file event.json
547
+ --context work --json` maps one saved real event to those same run commands.
548
+ Add `--prepare` to journal it without sending. Keep its stable `eventId` and
549
+ `occurredAt`; retries use the normal command journal. Local MCP exposes
550
+ `tasker_run_event`. A `process_exited` event only requests review, with explicit
551
+ next steps. See [host event fields, examples and recovery](../skills/geniustasker/references/host-events.md)
552
+ before connecting a host callback; no host hook is installed automatically.
@@ -7,8 +7,8 @@ are selected in the browser and enforced by the service on every request.
7
7
  ## Codex: direct MCP
8
8
 
9
9
  ```sh
10
- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.10 auth login --context work
11
- codex mcp add geniustasker -- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.10 mcp --context work
10
+ npx -y @pulsarinteractive/geniustasker@0.1.0-beta.12 auth login --context work
11
+ codex mcp add geniustasker -- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.12 mcp --context work
12
12
  ```
13
13
 
14
14
  Restart the host as needed, then inspect its MCP list. Ask the agent to read its
package/docs/MEMORY.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # Memory and Graph
2
2
 
3
+ Graph creation, node/edge changes and Graph reads through CLI/MCP/connectors
4
+ require Starter or Pro for the acting user, plus the normal resource permissions.
5
+ The space owner's plan does not grant a collaborator this capability. Document
6
+ pages, attachments and document references retain their independent access.
7
+ `memory_graph_premium_required` is a subscription refusal, not a reason to switch
8
+ tools or profiles. After downgrade, ordinary application sync and account export
9
+ remain available for existing data. Discover the current server capabilities;
10
+ package installation alone does not activate a server release.
11
+
3
12
  Memory stores structured documents independently of projects. Graph connects
4
13
  nodes and links them to a page or a stable document block. These commands require
5
14
  the matching deployed service capabilities; check `geniustasker capabilities --json` before using them.
package/docs/WORKFLOWS.md CHANGED
@@ -2,6 +2,7 @@
2
2
 
3
3
  | What you want | Guide topic | Operations |
4
4
  | --------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
5
+ | Reuse a task procedure | `protocols` | Inspect immutable versions, bind variables, preview and explicitly materialize bounded batches |
5
6
  | Work on a project | `projects` | Read project/member configuration; create/edit/archive/restore tasks; create and plan tickets in existing backlogs/sprints |
6
7
  | Prepare a shared workflow | `projects` | Project tags and saved filters; sprint, recurring schedule and workflow lifecycle |
7
8
  | Collaborate | `projects` | Comments, work reports, questions, exact action approvals and member goals |
@@ -15,6 +16,13 @@ Discover commands before editing. A readable collection does not imply a matchin
15
16
  write command. See [projects and planning](PLANNING.md) for lifecycle commands.
16
17
  Membership and consent changes remain in the application.
17
18
 
19
+ For importance, use the `projects` guide and
20
+ [the classification workflow](../skills/geniustasker/references/importance.md).
21
+ The four values are `Minor`, `Normal`, `Important` and `Critical`. Importance is
22
+ impact, independently of urgency or hierarchy. Agents justify the two higher
23
+ levels and preserve human classifications. Check live field availability before
24
+ using them; these fields do not establish a particular notification or Flutter UI.
25
+
18
26
  ## Example requests
19
27
 
20
28
  - “Find my tasks in the current sprint and summarize what blocks them.”
@@ -35,3 +43,9 @@ Existing project agent contributions must be enabled by an authorized member.
35
43
  New projects created with projects:write start with contributions enabled. No tool
36
44
  can grant itself membership, approve an action as a human, or bypass account
37
45
  [limits](LIMITS.md).
46
+
47
+ Read [Task protocols](../skills/geniustasker/references/protocols.md) for exact preview, binding and immutable recovery examples.
48
+
49
+ For real agent claims, checkpoints, scoped task patches and completion, read
50
+ [Agent runs](../skills/geniustasker/references/agent-runs.md). A recorded run does
51
+ not start or monitor an external agent automatically.
@@ -1,3 +1,3 @@
1
1
  [mcp_servers.geniustasker]
2
2
  command = "npx"
3
- args = ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.10", "mcp", "--context", "work"]
3
+ args = ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.12", "mcp", "--context", "work"]
package/examples/mcp.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "mcpServers": {
3
3
  "geniustasker": {
4
4
  "command": "npx",
5
- "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.10", "mcp", "--context", "work"]
5
+ "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.12", "mcp", "--context", "work"]
6
6
  }
7
7
  }
8
8
  }
package/mcp.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "geniustasker": {
5
5
  "type": "stdio",
6
6
  "command": "npx",
7
- "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.10", "mcp", "--context", "work"]
7
+ "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.12", "mcp", "--context", "work"]
8
8
  }
9
9
  }
10
10
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pulsarinteractive/geniustasker",
3
- "version": "0.1.0-beta.10",
3
+ "version": "0.1.0-beta.12",
4
4
  "private": false,
5
5
  "description": "GeniusTasker delegated CLI and local agent tools",
6
6
  "type": "module",
@@ -46,7 +46,7 @@
46
46
  "@eslint/js": "10.0.1",
47
47
  "@modelcontextprotocol/client": "2.3.1",
48
48
  "ajv": "8.20.0",
49
- "eslint": "10.11.0",
49
+ "eslint": "10.15.0",
50
50
  "globals": "17.12.0",
51
51
  "prettier": "3.9.9"
52
52
  },
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "geniustasker",
4
- "version": "0.1.0-beta.10",
4
+ "version": "0.1.0-beta.12",
5
5
  "description": "Track project work and independent product memories with your own agents.",
6
6
  "author": {
7
7
  "name": "Pulsar Interactive"
@@ -78,6 +78,7 @@
78
78
  "collection": {
79
79
  "type": "string",
80
80
  "enum": [
81
+ "agentRuns",
81
82
  "assets",
82
83
  "comments",
83
84
  "documentFolders",
@@ -97,6 +98,7 @@
97
98
  "project",
98
99
  "projectDocumentIndex",
99
100
  "projectDocuments",
101
+ "protocolInstances",
100
102
  "questions",
101
103
  "schedules",
102
104
  "sprintHistory",
@@ -317,8 +319,16 @@
317
319
  "project.delete",
318
320
  "project.features",
319
321
  "project.update",
322
+ "protocol.apply",
323
+ "protocol.cancel",
324
+ "protocol.publish",
325
+ "protocol.start",
320
326
  "question.close",
321
327
  "question.create",
328
+ "run.checkpoint",
329
+ "run.claim",
330
+ "run.finish",
331
+ "run.patch",
322
332
  "schedule.create",
323
333
  "schedule.delete",
324
334
  "schedule.update",
@@ -392,8 +402,16 @@
392
402
  "project.delete",
393
403
  "project.features",
394
404
  "project.update",
405
+ "protocol.apply",
406
+ "protocol.cancel",
407
+ "protocol.publish",
408
+ "protocol.start",
395
409
  "question.close",
396
410
  "question.create",
411
+ "run.checkpoint",
412
+ "run.claim",
413
+ "run.finish",
414
+ "run.patch",
397
415
  "schedule.create",
398
416
  "schedule.delete",
399
417
  "schedule.update",
@@ -507,8 +525,16 @@
507
525
  "project.delete",
508
526
  "project.features",
509
527
  "project.update",
528
+ "protocol.apply",
529
+ "protocol.cancel",
530
+ "protocol.publish",
531
+ "protocol.start",
510
532
  "question.close",
511
533
  "question.create",
534
+ "run.checkpoint",
535
+ "run.claim",
536
+ "run.finish",
537
+ "run.patch",
512
538
  "schedule.create",
513
539
  "schedule.delete",
514
540
  "schedule.update",
@@ -961,6 +987,14 @@
961
987
  "folder.create",
962
988
  "folder.delete",
963
989
  "folder.update",
990
+ "protocol.apply",
991
+ "protocol.cancel",
992
+ "protocol.publish",
993
+ "protocol.start",
994
+ "run.checkpoint",
995
+ "run.claim",
996
+ "run.finish",
997
+ "run.patch",
964
998
  "schedule.create",
965
999
  "schedule.delete",
966
1000
  "schedule.update",
@@ -1236,6 +1270,7 @@
1236
1270
  "collection": {
1237
1271
  "type": "string",
1238
1272
  "enum": [
1273
+ "agentRuns",
1239
1274
  "comments",
1240
1275
  "documentFolders",
1241
1276
  "documents",
@@ -1245,6 +1280,7 @@
1245
1280
  "preparedLists",
1246
1281
  "projectDocumentIndex",
1247
1282
  "projectDocuments",
1283
+ "protocolInstances",
1248
1284
  "questions",
1249
1285
  "schedules",
1250
1286
  "sprintHistory",
@@ -1363,12 +1399,87 @@
1363
1399
  "properties": {
1364
1400
  "topic": {
1365
1401
  "type": "string",
1366
- "enum": ["connection", "mutations", "projects", "memory", "graph", "planning"]
1402
+ "enum": [
1403
+ "connection",
1404
+ "mutations",
1405
+ "projects",
1406
+ "memory",
1407
+ "graph",
1408
+ "planning",
1409
+ "protocols",
1410
+ "runs"
1411
+ ]
1367
1412
  }
1368
1413
  },
1369
1414
  "required": ["topic"],
1370
1415
  "additionalProperties": false
1371
1416
  },
1372
1417
  "scopes": []
1418
+ },
1419
+ {
1420
+ "name": "tasker_protocol_preview",
1421
+ "title": "Preview a task protocol",
1422
+ "description": "Preview one page of a published task protocol without creating an instance or tasks. Requires tasks:read and spends the normal read budget. Keep the same version and bindings; after greater than zero requires the original digest. At most 20 steps per call. Read workflow topic protocols before applying explicit commands.",
1423
+ "inputSchema": {
1424
+ "type": "object",
1425
+ "required": ["bindings", "protocolVersionId", "scope"],
1426
+ "properties": {
1427
+ "after": {
1428
+ "type": "integer",
1429
+ "minimum": 0,
1430
+ "maximum": 199
1431
+ },
1432
+ "bindings": {
1433
+ "type": "object",
1434
+ "required": ["anchor", "epoch", "instanceId", "scope", "values"],
1435
+ "properties": {
1436
+ "anchor": {
1437
+ "type": "string"
1438
+ },
1439
+ "epoch": {
1440
+ "type": "string",
1441
+ "minLength": 1,
1442
+ "maxLength": 128
1443
+ },
1444
+ "instanceId": {
1445
+ "type": "string",
1446
+ "maxLength": 36,
1447
+ "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
1448
+ },
1449
+ "scope": {
1450
+ "type": "string",
1451
+ "maxLength": 128,
1452
+ "pattern": "^project:[A-Za-z0-9_-]+$"
1453
+ },
1454
+ "values": {
1455
+ "type": "object",
1456
+ "maxProperties": 24,
1457
+ "additionalProperties": {}
1458
+ }
1459
+ },
1460
+ "additionalProperties": false
1461
+ },
1462
+ "digest": {
1463
+ "type": "string",
1464
+ "maxLength": 64,
1465
+ "pattern": "^[a-f0-9]{64}$"
1466
+ },
1467
+ "protocolVersionId": {
1468
+ "type": "string",
1469
+ "maxLength": 36
1470
+ },
1471
+ "scope": {
1472
+ "type": "string",
1473
+ "maxLength": 128,
1474
+ "pattern": "^project:[A-Za-z0-9_-]+$"
1475
+ }
1476
+ },
1477
+ "additionalProperties": false
1478
+ },
1479
+ "scopes": ["tasks:read"],
1480
+ "route": "protocols/preview",
1481
+ "method": "POST",
1482
+ "write": false,
1483
+ "destructive": false
1373
1484
  }
1374
1485
  ]
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "formatVersion": 1,
3
- "version": "2026-10-23",
3
+ "version": "2026-11-16",
4
4
  "topics": {
5
5
  "connection": {
6
6
  "title": "Connection, permissions and language",
@@ -28,6 +28,9 @@
28
28
  "List projects and choose only those relevant to the request. Existing projects must have agent contributions enabled by a human administrator. project.create requires projects:write and all-resources consent including future projects; use a new UUID v4 for id and epoch and project:<id> for scope. It creates an owned project with agent contributions enabled; type defaults to Details and icon to layers. It does not change consent or access to other projects.",
29
29
  "Read the project configuration, members, tasks and relevant sprints/workflows. Follow nextAfter with epoch and checkpoint even when a filtered page is empty. Use exact record IDs when known; archive accepts active, archived or all.",
30
30
  "Use task.create/update for ordinary task fields. Use ticket.create and ticket.plan for backlog, sprint placement and planning. Inspect command_help and the current project revision before planning; read the affected task revisions. Do not invent sprint IDs, workflow IDs or member IDs.",
31
+ "When creating or reassessing task importance, first discover importance/importanceReason in task.create or task.update and importanceOrigin in task reads. Read the current task and only relevant goals/dependencies. Missing legacy importance means Normal. Do not reclassify during unrelated edits or substitute priority when the importance fields are unavailable.",
32
+ "Importance measures verified impact, independently of urgency, due dates, effort and parent/subtask hierarchy: Minor is limited consequence; Normal is expected useful work or insufficient evidence for more; Important materially advances an identified goal or removes a substantial verified blocker; Critical has severe concrete consequences for this project. Do not inflate importance to obtain XP, pushes or attention. Agent-created or changed Important/Critical classifications require a short importanceReason (at most 400 characters) describing the actual consequence or evidence, not just an urgency label.",
33
+ "importanceOrigin is server-owned: never supply it. Preserve a human-origin importance and its reason. If reassessment would help, propose the new value and reason through a supported question or the current conversation; a human must apply it through the application. task_importance_human_review_required is a final conflict, not permission to retry through another profile/transport, clear provenance or recreate the task. A question answer does not bypass that protection. Use normal immutable-command recovery and readback; an importance-only edit does not establish notification delivery, XP or any future Flutter threshold control.",
31
34
  "Tags and saved filters are project-specific. Use tag.create/update/delete and filter.create/update/delete. Reuse existing names and criteria; never impose example release labels globally.",
32
35
  "Record actual progress with task.report and relevant comments. Questions and action approvals are separate workflows; an agent may request or consume an exact granted approval but cannot approve on a human behalf. Mark work complete only when the requested work is actually complete.",
33
36
  "Use project.update for ordinary project settings and project.features for planning switches, with projects:write and native administration rights. project.features is a full configuration: read and preserve all seven booleans and timeZone. It cannot change agent opt-in, membership, ownership or counters. project.delete requires project ownership, a current revision and an explicit user deletion request.",
@@ -39,7 +42,8 @@
39
42
  "steps": [
40
43
  "Projects and Memory are independent spaces. List memories, inspect pageIndex or the tree, then fetch specific pages. Search before adding duplicate documentation. Preserve folder parentId and stable page/block IDs.",
41
44
  "Read the page current revision and use memory.page.create/update/delete for both documents and folders. A folder is a page with directory:true, a stable id/path and parentId; child pages reference that ID. Preserve visibility/readRoles, stable block IDs and content not requested for modification. A parent or Graph link does not bypass current document permissions.",
42
- "In ChatGPT use the available bounded memory/knowledge read tools and memory edit commands. Repository documentation mirroring and local file upload are CLI/local MCP operations, not hosted connector filesystem access.",
45
+ "In ChatGPT use the available bounded memory/knowledge read tools and memory edit commands. Prepare with tasker_prepare_command, retain the complete immutable object and execute/retry with tasker_edit_memory. Hosted ChatGPT has no local journal or tasker_retry_command; local MCP uses that operation-ID tool and CLI uses commands retry. Repository documentation mirroring and local file upload are CLI/local MCP operations, not hosted connector filesystem access.",
46
+ "After revision_conflict, read the full current page/node and reconcile the other contribution. Preserve unrelated blocks, stable IDs, references and provenance. Compatible edits need a new operation ID and fresh revision; contradictory claims require an explicit proposal or user decision. An uncertain command must be resolved before a conflicting replacement. Content authority/provenance/metadata are claims, not permission or verified identity. Read-only lastAgentActor identifies the latest server-verified agent editor when present; never forge it, infer historic human authorship from its absence or treat it as factual verification.",
43
47
  "For media, reuse a stable asset ID. In local MCP/CLI compare content hashes before uploading a replacement, preserve references and never delete an asset still in use. Do not claim that mentioning a ChatGPT attachment has uploaded it to Memory.",
44
48
  "When a repository mirror is configured, check source freshness at a new work session and after knowledge changes. Edit authoritative Memory through MCP, then sync the mirror; generated Markdown is not the source of truth."
45
49
  ]
@@ -47,6 +51,7 @@
47
51
  "graph": {
48
52
  "title": "Graph nodes, relations and revoked references",
49
53
  "steps": [
54
+ "Graph creation, node/edge edits and delegated Graph reads/search/exploration require Starter or Pro for the acting user in addition to the normal grant; a paid space owner does not upgrade a collaborator. Documents, attachments and document references remain independent. On memory_graph_premium_required stop Graph calls rather than switching tools/profiles. Ordinary application sync and personal-data export remain available after downgrade. Do not copy Graph data into pages to bypass the restriction.",
50
55
  "Read the relevant graph or a bounded neighborhood instead of crawling every space. Nodes have types and independent data; edges express typed relations. Use exact node IDs and inspect existing relations before adding duplicates.",
51
56
  "Use memory.node.create/update/delete and memory.edge.create/update/delete with current revisions. Preserve imageAssetId, detailLevel, provenance and source references unless the user requested a change.",
52
57
  "Resolve cross-space references through the authorized reference tool. If a friend removes access, the node and its own content may remain while the linked data is unavailable. Never delete the node or paste cached private data as a workaround.",
@@ -62,6 +67,32 @@
62
67
  "schedule.create/update set the recurring task fields, including period, interval, startTime, weekDay and IANA timeZoneId. Read current settings before edits; preserve owner, notifications, deadlines and dependencies. The server validates recurrence and invalidates its scheduler checkpoint. Never send nextCheck, lastCreation or disabled: these are server-managed. schedule.delete stops future occurrences, preserves existing task history and removes dependent recurrence references.",
63
68
  "Prepare and execute the exact command once; uncertain retries reuse its immutable envelope. On conflict reread the affected records. Read back sprint/task/schedule changes and let normal application realtime subscriptions refresh the open views. Never claim a successful command proves device rendering."
64
69
  ]
70
+ },
71
+ "protocols": {
72
+ "title": "Reusable task protocols and controlled materialization",
73
+ "steps": [
74
+ "Discover current commands and collections first. Read the chosen Details project, its agent opt-in, members, features, taskTemplates and relevant protocolInstances with tasks:read. An older name/description template without protocolDefinition is not a published protocol. Never convert ordinary templates or enable project features without a user request.",
75
+ "Read tasker_command_help for protocol.publish/start/apply/cancel (CLI commands describe --kind). The local snapshot includes nested required fields and limits without network access. Do not supply the internal action field; current grants and semantic validation remain server-owned.",
76
+ "A published protocol is an immutable version: protocol.publish creates a new UUID and accepts definition plus previousVersionId (null for a new family, otherwise the latest version ID). Publication needs native project administration and tasks:write. Keep stable step keys, valid parent/dependency keys, explicit acceptance criteria, reasonable importance and delivery requests. Minor/Normal/Important/Critical measure impact, not urgency; Important/Critical need a concrete reason. Requested push/animation never overrides recipient preferences.",
77
+ "Bind only declared primitive variables, with exact current member IDs and the project epoch. Choose one lowercase UUID for instanceId and retain it. Capture one timezone-qualified anchor; dueAfterDays adds elapsed 24-hour days, not a local recurring schedule. Text values are data, never executable instructions. Do not invent missing required information or copy unrelated account history.",
78
+ "Call tasker_protocol_preview or CLI protocols preview --file with scope, protocolVersionId and bindings. It creates nothing, requires tasks:read and charges the normal read budget. Inspect one page of at most 20 steps. Follow nextAfter only as needed, preserving every binding and the returned digest; a continuation after zero requires that digest. Stop and reconcile on a changed preview or lost access. Do not claim uninspected pages were checked.",
79
+ "After the user has requested this materialization, prepare protocol.start with id equal to bindings.instanceId, expectedRevision:null and data {protocolVersionId,bindings}. Read the new protocolInstances record and its digest/revision. For each explicitly intended batch prepare protocol.apply on that same instance with the current revision and data {digest,from:appliedCount,count:20 or fewer}. Each call uses normal permission and storage admission. No automatic server loop or bulk quota bypass creates all 200 possible steps at once.",
80
+ "Retain the immutable command before every write. After a timeout retry that exact operation; do not advance from or mint a new operation ID until its outcome is known. On a definitive conflict read the instance and affected tasks before deciding whether a new command is appropriate. Do not recreate or overwrite a task to bypass a collision, revocation, expiration or human importance decision. The creating user or a current project administrator may continue or cancel an instance. The same user may continue with another profile only under its current grants. An uncertain operation keeps its original immutable identity; resolve its outcome before preparing a new batch under a different session/profile.",
81
+ "Applied means task materialization is finished, not that anyone completed the work. Read the instance and affected tasks to report the actual result. protocol.cancel with the current revision stops remaining materialization and retains already created tasks; it is not a rollback or a deletion command. Do not edit server-owned instance state, bindings, cursor or provenance directly."
82
+ ]
83
+ },
84
+ "runs": {
85
+ "title": "Coordinate real agent work with runs and claims",
86
+ "steps": [
87
+ "Read current identity, capabilities, relevant Details project and task. Discover agentRuns and run.claim/checkpoint/patch/finish; require current project rights, task read/write grants and enabled agent contributions. Read one bounded page, never crawl every project.",
88
+ "Use tasker_command_help for the selected run command. Claim only authorized open work with a new run UUID, null create revision, current task ID/taskRevision and scope epoch. A concurrent claim conflict means reread or select independent work, not overwrite or profile switching.",
89
+ "Report real Working, Waiting or NeedsReview checkpoints against the run revision. Waiting/review need useful nextSteps. Include only labeled HTTPS evidence without credentials or signed private URLs. No fabricated progress or full terminal/chat logs. A valid checkpoint may renew the live lease; respect service retry times.",
90
+ "Use run.patch while holding the claim. The envelope uses the run revision; data.taskRevision uses the task revision; patch accepts only task.update fields. Ordinary ACL, dependencies, task transitions and human importance choices still apply. Human edits require a fresh read and reconciliation.",
91
+ "An expired lease means stale reporting, not known failure or blockage. Tasker neither starts an agent nor observes an uninstrumented process. Never promise always-on operation. Respect cancellation_requested, TakenOver and Superseded; human control remains in the app and cannot be impersonated through MCP.",
92
+ "Use run.finish with Completed, Failed or Cancelled and truthful summary/evidence. It ends the run, not the task. Complete the task through run.patch only after verified intended work. After lease expiry, only a final result on the unchanged claim under its original user/profile may close it; task patches stay refused. A deleted task permits only Failed or Cancelled under current project permissions. Do not infer XP, task completion or device display from a run receipt.",
93
+ "Keep immutable operations and original identity after an uncertain result. Local CLI/stdio retain a journal; hosted ChatGPT must retain the exact command object. Reread after a definitive conflict and after finish or human takeover: the task revision changes as a server concurrency barrier without changing its content. New work after expiry requires current authority and an explicit fresh claim; never bypass human takeover. History is bounded: checkpointCount may exceed retained checkpoints.",
94
+ "For an explicitly instrumented local host, use CLI runs event --file or local MCP tasker_run_event with one saved eventId/occurredAt, current scope/run identity and revision, and a sanitized real summary. --prepare/prepareOnly only journals. process_exited maps to NeedsReview and requires nextSteps, never Task Done. No daemon, polling, log/environment/argument capture or host-hook installation is implied. Hosted ChatGPT uses prepared run commands through the task edit tool instead."
95
+ ]
65
96
  }
66
97
  }
67
98
  }
@@ -104,6 +104,11 @@ project/ticket and distinguish completed work, validation and remaining work.
104
104
 
105
105
  ## Specialized workflows
106
106
 
107
+ - For coordinated agent work on a task, read [Agent runs](references/agent-runs.md). Claim explicitly, report real observations, distinguish stale signals from blockers, and honor human takeover. For explicit host callbacks, use [host events](references/host-events.md); installation alone does not monitor your process.
108
+
109
+ - To reuse or publish a multi-task procedure, read [Task protocols](references/protocols.md). Preview the chosen version and bindings before explicitly materializing bounded batches.
110
+ - For task importance, read [Impact and human-owned classification](references/importance.md). Read the existing value first; urgency, hierarchy and rewards do not determine importance.
111
+ - For CLI version checks or an explicitly requested package update, read [CLI updates](references/updates.md). An update is not a repair for missing account permissions or a reason to replay pending operations.
107
112
  - To create, switch or restrict an agent identity, read [Profiles](references/profiles.md).
108
113
  - For ticket questions, progress reports or precise human approvals, read [Collaboration](references/collaboration.md).
109
114
  - Memory is a separate account resource. This project skill never assumes that a project grants Memory access. Discover capabilities and independent memory grants before using it.