@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.
@@ -0,0 +1,144 @@
1
+ # Coordinate an agent run
2
+
3
+ Use a run for an actual agent working on a tracked task, especially when another
4
+ agent or person may work on it too. A run is a temporary collaboration claim and
5
+ an attributed record of real checkpoints. It neither starts an agent nor proves
6
+ that an external process is alive. Tasker does not monitor an uninstrumented
7
+ agent; silence is unknown activity.
8
+
9
+ ## Read before claiming
10
+
11
+ 1. Read identity, capabilities, the relevant Details project and its current task.
12
+ Discover `agentRuns` and `run.claim`, `run.checkpoint`, `run.patch`, `run.finish`.
13
+ They require the usual project access and task permissions; delegated writes
14
+ require `tasks:write` and project agent contributions to be enabled.
15
+ 2. Inspect a relevant existing run with a bounded `resources` read. Preserve its
16
+ epoch/revision. An active claim is not permission to take over another agent.
17
+ Current grant/profile restrictions apply even when the task belongs to you.
18
+ 3. Read `tasker_command_help` for the chosen command, or
19
+ `geniustasker commands describe --kind run.claim --json`. The local help is
20
+ offline schema guidance, not evidence that the account has access.
21
+ 4. Claim only work the user authorized. Keep one new UUID as the run's command
22
+ target, the current task ID and task revision, and the current project epoch.
23
+ A create command uses `expectedRevision: null`.
24
+
25
+ Example **data** for `run.claim` (replace task identity and revision from reads):
26
+
27
+ ```json
28
+ {
29
+ "task": "TASK_ID_FROM_CURRENT_READ",
30
+ "taskRevision": "7",
31
+ "summary": "Check the requested behavior and its acceptance criteria.",
32
+ "leaseSeconds": 300
33
+ }
34
+ ```
35
+
36
+ Use the normal immutable command prepare/execute workflow. A confirmed claim
37
+ returns the run's revision; read `agentRuns` to obtain its current lease and
38
+ attribution. Another actor may win the claim between your read and write. On a
39
+ claim conflict, inspect the current run and choose independent authorized work;
40
+ never change profiles, overwrite the claim or infer human approval.
41
+
42
+ ## Report actual work and keep the fence
43
+
44
+ `run.checkpoint` targets the run UUID and its current revision. Use `Working`,
45
+ `Waiting` or `NeedsReview`, a factual summary and the useful next steps. Waiting
46
+ and review checkpoints need an actionable `nextSteps`. Evidence links must be
47
+ labeled HTTPS URLs without credentials or private signed links. Do not upload
48
+ full conversations, terminal output or secret-bearing diagnostics.
49
+
50
+ ```json
51
+ {
52
+ "state": "Working",
53
+ "summary": "The regression is reproduced; the targeted correction is under test.",
54
+ "nextSteps": "Verify the correction and the unchanged neighboring behavior.",
55
+ "evidence": [],
56
+ "leaseSeconds": 300
57
+ }
58
+ ```
59
+
60
+ Adapt this text to observations; do not copy it as invented progress. A checkpoint
61
+ may renew a live lease. Schedule bounded updates around real work and respect
62
+ retry times, not a polling loop that invents movement. The saved lease is the
63
+ server authority; a local timer alone never authorizes another write.
64
+
65
+ Only the creating user/profile may report on the run. A new profile is a new
66
+ identity, not a way to resume an uncertain write. Original immutable operations
67
+ retain their original connection/session identity for retries.
68
+
69
+ For task changes while holding a claim, use `run.patch` with the current **run**
70
+ revision in the envelope and current **task** revision in `data.taskRevision`:
71
+
72
+ ```json
73
+ {
74
+ "taskRevision": "8",
75
+ "patch": { "description": "Updated with the verified acceptance criteria." }
76
+ }
77
+ ```
78
+
79
+ The patch accepts only fields supported by `task.update`. It preserves ordinary
80
+ permissions, human-owned importance, dependencies and task lifecycle rules.
81
+ Do not send internal fields, arbitrary mutations or a stale task snapshot.
82
+ A human edit changes the revision; reread and reconcile instead of overwriting.
83
+
84
+ ## Distinguish silence, waiting and completion
85
+
86
+ - `Waiting` is an explicit agent report requiring information or another action.
87
+ - `NeedsReview` is an explicit request to inspect a real result.
88
+ - An expired `leaseUntil` means the signal is stale. It does not prove failure,
89
+ blockage, cancellation or task completion. Do not generate a failure report
90
+ just because a heartbeat was absent.
91
+ - `cancelRequestedAt` asks the agent to stop. Stop new task changes and safely
92
+ finish as `Cancelled` when still authorized. Human cancellation/takeover is an
93
+ app control, not a command agents may impersonate or bypass.
94
+ - `TakenOver` or `Superseded` means the prior run cannot continue writing. Reread
95
+ the task and current authority; do not silently recreate a claim to defeat a
96
+ person's decision.
97
+
98
+ After lease expiry, do not forge the clock or renew an expired command under a
99
+ fresh ID. Read the task/run again. A fresh claim is a new explicit operation for
100
+ still-authorized open work, not a replay of the old run. Preserve any uncertain
101
+ operation and establish its outcome before issuing a conflicting new command.
102
+
103
+ `run.finish` records `Completed`, `Failed` or `Cancelled`, with an honest summary,
104
+ next steps when needed and actual evidence. Finishing the run does **not** mark
105
+ the task Done. If the requested work is verified and task completion is intended,
106
+ apply that task transition through the live run first, then finish the run.
107
+ Do not award yourself progress, XP or successful delivery from an exit code alone.
108
+
109
+ If the lease expired while you were disconnected, a final result may still close
110
+ the unchanged claim under its original user/profile. This does not renew the
111
+ lease or permit another task patch. A superseding claim or human takeover blocks
112
+ that late result. If the task was deleted, only `Failed` or `Cancelled` can close
113
+ the run, under current project permissions; never restore it to report success.
114
+
115
+ Finishing a run or human takeover changes the task's server revision without
116
+ changing its content. Reread both task and run before any later task edit;
117
+ an earlier task revision is deliberately stale, regardless of your local clock.
118
+
119
+ `Expired` is a server-ended abandoned run; it does not certify that the external
120
+ work failed. Run checkpoint history is bounded. `checkpointCount` can exceed the number of
121
+ retained checkpoints; absence of an older detail is not evidence it never
122
+ occurred. Read the confirmed task and run before reporting a final outcome.
123
+ Use `changes` or a bounded `watch` for a known cursor if needed. A successful API
124
+ response does not certify that another device has already displayed it.
125
+
126
+ ## CLI and hosted recovery
127
+
128
+ ```sh
129
+ geniustasker workflow show --topic runs --json
130
+ geniustasker commands describe --kind run.claim --json
131
+ geniustasker commands prepare --file claim-draft.json --context work --json
132
+ geniustasker commands execute --file prepared-command.json --context work --json
133
+ geniustasker resources list --scope project:PROJECT_ID --collection agentRuns --id RUN_ID --context work --json
134
+ ```
135
+
136
+ These are individually requested calls. For a host that can explicitly report
137
+ real lifecycle events, use the [opt-in host event adapter](host-events.md). It
138
+ does not observe an uninstrumented process or run a background daemon.
139
+ Local preparation saves a private operation journal; retry
140
+ an uncertain operation unchanged with `commands retry --operation ID`.
141
+ Hosted ChatGPT preparation returns an immutable object instead; retain it for
142
+ the exact same retry using the authorized edit tool. Both use the same server
143
+ permissions, quota and concurrency rules. Never clear the journal to suppress
144
+ an uncertain result or create an untracked replacement operation.
@@ -0,0 +1,116 @@
1
+ # Connect explicit host lifecycle events
2
+
3
+ Use this adapter only when the user has enabled reporting for an actual task and
4
+ your host can explicitly invoke the CLI or local MCP at known work events. It
5
+ does not install a hook into Codex, Claude or another agent host, observe an
6
+ unmodified process, launch commands, capture logs or run a background timer.
7
+
8
+ Before enabling it, discover the four `run.*` commands and read the project/task.
9
+ Ordinary account permissions, project agent contributions, quotas, leases and
10
+ run/task revisions still apply. The host must retain the current run identity and
11
+ confirmed revision; each event is one normal command, not a batch or bypass.
12
+
13
+ ## Map facts to the right event
14
+
15
+ | Actual host event | Event `type` | Command and state |
16
+ | ------------------------------------------------------- | ---------------- | ------------------------------ |
17
+ | Authorized work starts on a current open task | `started` | `run.claim` → Working |
18
+ | A factual progress checkpoint is available | `checkpoint` | `run.checkpoint` → Working |
19
+ | The agent explicitly needs an input or dependency | `waiting` | `run.checkpoint` → Waiting |
20
+ | A concrete result awaits review | `review` | `run.checkpoint` → NeedsReview |
21
+ | Only the process exit is known | `process_exited` | `run.checkpoint` → NeedsReview |
22
+ | The agent explicitly reports its verified work finished | `finished` | `run.finish` → Completed |
23
+ | The agent explicitly reports failure | `failed` | `run.finish` → Failed |
24
+ | The agent actually stopped the work after cancellation | `cancelled` | `run.finish` → Cancelled |
25
+
26
+ `waiting`, `review` and `process_exited` require actionable `nextSteps`. An exit
27
+ code, silence or elapsed time cannot prove acceptance, failure or task completion.
28
+ No hook edits the task or awards XP. A `finished` run still does not mark its task
29
+ Done. A cancelled/replaced/expired lease may refuse a checkpoint; keep the real
30
+ event and report that refusal rather than starting an unauthorized replacement.
31
+
32
+ ## Save the event before sending
33
+
34
+ For each actual event, the host persists one UUID `eventId` and its original
35
+ millisecond `occurredAt`. They become the command's `operationId` and `issuedAt`.
36
+ Save the complete event before invoking the adapter and reuse it unchanged on
37
+ retry. Do not create a new UUID/timestamp each time a shell hook is restarted.
38
+
39
+ The following fixtures show the file shape. Replace their IDs, timestamp and
40
+ revision with actual observations before saving your event; do not send the
41
+ example as claimed progress. `runId` is one UUID for the run, distinct from each
42
+ event's UUID. Starting uses a null run revision and the current task revision.
43
+
44
+ ```json
45
+ {
46
+ "eventId": "11111111-1111-4111-8111-111111111111",
47
+ "occurredAt": 1794823200000,
48
+ "type": "started",
49
+ "scope": "project:PROJECT_ID_FROM_CURRENT_READ",
50
+ "epoch": "EPOCH_FROM_CURRENT_READ",
51
+ "runId": "22222222-2222-4222-8222-222222222222",
52
+ "expectedRevision": null,
53
+ "task": "TASK_ID_FROM_CURRENT_READ",
54
+ "taskRevision": "7",
55
+ "summary": "Starting the authorized recovery check.",
56
+ "leaseSeconds": 300
57
+ }
58
+ ```
59
+
60
+ ```sh
61
+ geniustasker runs event --file started.json --prepare --context work --json
62
+ geniustasker runs event --file started.json --context work --json
63
+ geniustasker commands inspect --operation EVENT_UUID --context work --json
64
+ geniustasker commands retry --operation EVENT_UUID --context work --json
65
+ ```
66
+
67
+ `--prepare` persists the exact command locally and sends no API request. Repeating
68
+ preparation preserves any existing uncertainty, cooldown or receipt. Sending the
69
+ same event uses the normal immutable journal; it cannot replace a different
70
+ request under that ID. A local receipt replay is explicitly labeled
71
+ `local_receipt`, not a fresh server observation.
72
+
73
+ A later event uses the same run ID but its latest revision from a confirmed
74
+ receipt/read and a distinct event ID. For example, if the host only knows its
75
+ process stopped:
76
+
77
+ ```json
78
+ {
79
+ "eventId": "33333333-3333-4333-8333-333333333333",
80
+ "occurredAt": 1794823220000,
81
+ "type": "process_exited",
82
+ "scope": "project:PROJECT_ID_FROM_CURRENT_READ",
83
+ "epoch": "EPOCH_FROM_CURRENT_READ",
84
+ "runId": "22222222-2222-4222-8222-222222222222",
85
+ "expectedRevision": "8",
86
+ "summary": "The host process exited; acceptance has not been checked.",
87
+ "nextSteps": "Inspect the produced changes and run the agreed checks."
88
+ }
89
+ ```
90
+
91
+ ## Host integration and recovery
92
+
93
+ For a Codex or Claude host integration you control, configure an **opt-in**
94
+ callback to invoke `geniustasker runs event --file` on the host's saved, sanitized
95
+ event. If no supported callback exists, have the agent explicitly call the local
96
+ MCP tool at meaningful checkpoints. Do not claim that installing this skill or
97
+ adding an MCP connection automatically instruments that host.
98
+
99
+ Local MCP exposes `tasker_run_event` with `{ "event": EVENT_OBJECT,
100
+ "prepareOnly": true }` to prepare, or `{ "event": EVENT_OBJECT }` to send. It
101
+ uses the same journal as `tasker_retry_command`. Hosted ChatGPT uses the existing
102
+ prepared `run.*` command and task edit tool; it has no local event adapter or
103
+ filesystem access.
104
+
105
+ Only send the allowed structured fields. `summary` is bounded to 2,000 characters,
106
+ `nextSteps` to 4,000 and evidence to eight labeled HTTPS links. Do not send raw
107
+ stdout/stderr, environment, arguments, prompts, transcripts, credentials or
108
+ signed private links. Unknown fields are refused rather than forwarded.
109
+
110
+ Serialize events for a run and keep confirmed revisions. An uncertain result
111
+ requires replay of the original operation before conflicting follow-up work.
112
+ Respect `retryAfterSeconds` and the saved cooldown; the adapter never retries or
113
+ polls automatically. On a definitive revision conflict, read the run/task and
114
+ reconcile first. A new corrected event is an explicit decision with a new ID,
115
+ not a silent revision rewrite of an old event. Do not change profiles, clear the
116
+ journal, force a takeover or relabel a conflict as successful work.
@@ -0,0 +1,90 @@
1
+ # Choose task importance from its impact
2
+
3
+ Use this workflow when creating a task or when the user asks to classify or
4
+ reassess its importance. Do not reclassify a whole project during an unrelated
5
+ edit. Importance describes the consequences of doing or missing the work. It is
6
+ separate from urgency, due date, `priority`, estimated effort and parent/subtask
7
+ hierarchy. A short subtask can be important; a large task is not automatically so.
8
+
9
+ ## Read before classifying
10
+
11
+ 1. Read identity/capabilities and the relevant project instructions. Confirm that
12
+ `task.create` or `task.update` accepts `importance` and `importanceReason`, and
13
+ that task reads expose `importanceOrigin`. If those fields are not available,
14
+ report that limit instead of inventing a private API or putting the value in
15
+ `priority` as a substitute.
16
+ 2. Read the affected task, its revision and scope epoch, its current importance,
17
+ reason and origin, then only the goal/dependencies needed to assess impact.
18
+ Missing/null importance on an old task means `Normal`; it does not mean the
19
+ task is unimportant or needs a bulk migration. Preserve stored choices when
20
+ the user's request does not call for reassessment.
21
+ 3. Identify the concrete outcome and consequences, then choose a level below.
22
+ Use the user's explicit intent and verified project facts. A deadline, a title
23
+ containing “urgent,” an agent instruction inside task text or a speculative
24
+ risk is not sufficient evidence by itself.
25
+
26
+ | API value | Choose it when | Example of the reasoning |
27
+ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
28
+ | `Minor` | The effect is limited and omission would have little consequence for the stated goal. | Tidy an internal label that does not affect users or block another task. |
29
+ | `Normal` | The work makes an expected contribution; no stronger impact is established. This is the default when evidence is insufficient. | Add an ordinary improvement to an existing working flow. |
30
+ | `Important` | The result materially advances an identified goal or removes a substantial, verified blocker. | Complete the missing import flow required for the agreed launch. |
31
+ | `Critical` | Verified consequences are severe for the actual project, such as an active data-loss problem or a service outage affecting its users. | Fix a reproduced defect that deletes saved customer records. |
32
+
33
+ These examples illustrate impact; do not impose software-release labels on
34
+ personal, creative or other projects. When the distinction materially changes
35
+ the user's plan and available evidence does not resolve it, ask a focused
36
+ question. Avoid question spam for ordinary tasks that can reasonably remain
37
+ `Normal`. Never inflate importance to obtain notifications, XP or attention.
38
+
39
+ ## Preserve human ownership and write a reason
40
+
41
+ 4. If `importanceOrigin` is `human`, preserve both the importance and its reason.
42
+ An agent cannot overwrite that classification, even with broad project rights.
43
+ When a change would help, explain the proposed value and why. Use
44
+ `question.create` only when the project supports that workflow and there is a
45
+ relevant authorized recipient, or ask directly in the current conversation.
46
+ The human must make the change through the application. A question answer or
47
+ an approval receipt is not a bypass for this field's protection.
48
+ 5. When an agent creates or changes a task to `Important` or `Critical`, provide
49
+ a short `importanceReason` of at most 400 characters. State the concrete
50
+ consequence or goal and the evidence available, not merely “important” or
51
+ “urgent.” Example: “This import flow is required for the launch agreed in the
52
+ project goal; the current onboarding cannot complete without it.” Only use
53
+ that reason when the referenced goal/blocker really exists. Reasons for
54
+ `Minor`/`Normal` are optional; keep an existing useful reason when appropriate.
55
+ Never submit `importanceOrigin`: the server owns the attribution. Do not copy
56
+ private credentials or unrelated personal information into the reason.
57
+
58
+ ## Apply and verify
59
+
60
+ 6. Use the ordinary immutable command workflow. For a task already read, create
61
+ a `task.update` draft with its real scope, epoch, ID and current revision. The
62
+ relevant `data` can be:
63
+
64
+ ```json
65
+ {
66
+ "importance": "Important",
67
+ "importanceReason": "The approved launch depends on this import flow working."
68
+ }
69
+ ```
70
+
71
+ This is only the data fragment, not a complete executable command. Populate
72
+ the envelope from the live read and confirm that the reason fits the task.
73
+ Local CLI: `geniustasker commands prepare --file importance-draft.json --json`,
74
+ then `geniustasker commands retry --operation OPERATION_ID --json` using the
75
+ returned operation ID. Hosted MCP: prepare the command, then pass that exact
76
+ command object to the permitted edit tool. Retry an uncertain outcome with
77
+ the same operation; do not generate a replacement request blindly.
78
+
79
+ 7. Read back the task. `task_importance_human_review_required` is a final conflict
80
+ requiring human action, not a transient error. Do not clear the origin,
81
+ recreate the task, switch transport/profile or repeatedly retry to get around
82
+ it. For an ordinary revision conflict, reread and reconcile the intent before
83
+ preparing a new operation. For `task_importance_reason_required`, add a real
84
+ justification to a newly prepared command only after confirming the request
85
+ was rejected and the task's current state.
86
+
87
+ The change can appear in the task audit. It does not by itself establish that a
88
+ push was sent, XP was awarded or an overlay was displayed. Notification thresholds
89
+ and Flutter presentation are separate capabilities; discover them rather than
90
+ promising a future interface from these fields alone.
@@ -0,0 +1,156 @@
1
+ # Reuse a task protocol
2
+
3
+ Use this workflow when the user wants a reusable procedure with several tasks,
4
+ dependencies, acceptance criteria and deliberately selected importance. A
5
+ protocol creates tracked work; it does not execute the work or run an agent.
6
+ For a few unrelated tasks, ordinary task commands remain sufficient.
7
+
8
+ ## Find the right version
9
+
10
+ Read identity, capabilities, the selected project and its relevant configuration.
11
+ Discover `taskTemplates`, `protocolInstances` and `protocol.*` commands before
12
+ using them. Protocols target Details projects. A legacy template containing only
13
+ a name and description is not a published protocol. Existing project agent
14
+ contributions, current membership and the appropriate grants must permit writes.
15
+
16
+ Read the selected `taskTemplates` version, its `protocolDefinition`, family,
17
+ version and digest. Preserve its step keys; they determine task identities.
18
+ Check project features, dependencies, members and the user's intended outcome.
19
+ Do not infer that an administrative role or a task assignment authorizes an
20
+ unrelated external action.
21
+
22
+ Publishing requires project administration and `tasks:write`. Use
23
+ `protocol.publish` with a new UUID, null revision and
24
+ `data: {definition, previousVersionId}`. Null starts a family; otherwise use the
25
+ latest immutable version ID. Never patch a published version in place or
26
+ silently convert an older template. Read command help for the current schema.
27
+
28
+ ## Inspect the exact data schema
29
+
30
+ Use `geniustasker commands describe --kind protocol.publish --json` or local /
31
+ hosted `tasker_command_help` with `{"kind":"protocol.publish"}` before preparing
32
+ it. The four protocol commands expose nested field schemas and required fields.
33
+ Local help is offline; it does not claim the account has access. The server still
34
+ checks semantic rules such as valid members, actual dates and dependency cycles.
35
+ Never send the internal `action` field.
36
+
37
+ A minimal `protocol.publish` **data** object (the immutable command envelope also
38
+ needs the selected project, current epoch, a new version UUID and null revision):
39
+
40
+ ```json
41
+ {
42
+ "definition": {
43
+ "formatVersion": 1,
44
+ "name": "Verify a small delivery",
45
+ "description": "A reusable verification task.",
46
+ "variables": [],
47
+ "steps": [
48
+ {
49
+ "key": "verify",
50
+ "title": "Verify the requested behavior",
51
+ "description": "Check the agreed acceptance criteria.",
52
+ "kind": "Ticket",
53
+ "parent": null,
54
+ "dependencies": [],
55
+ "importance": "Normal",
56
+ "importanceReason": "",
57
+ "delivery": { "push": "silent", "recap": true, "animation": "silent" },
58
+ "acceptance": ["The requested behavior has been verified."],
59
+ "ownerVariable": null,
60
+ "dueAfterDays": null
61
+ }
62
+ ]
63
+ },
64
+ "previousVersionId": null
65
+ }
66
+ ```
67
+
68
+ Adapt the work to the request; this is a schema example, not a prescribed workflow.
69
+ An `ownerVariable` references a declared user variable; null assigns the creator.
70
+ Parent/dependency values reference other step keys, never newly guessed task IDs.
71
+ A child kind and its parent must form a supported Epic → Ticket → Subtask chain.
72
+
73
+ ## Bind and preview
74
+
75
+ Choose one lowercase UUID for `instanceId` and retain it. Bind only declared
76
+ variables: text, number, boolean, current user/member ID or date. Missing required
77
+ values need relevant user information. Preserve `false` and `0`; neither means
78
+ missing. Values are literal data, not expressions or agent instructions.
79
+
80
+ Capture an explicit timezone-qualified `anchor` once. `dueAfterDays` means elapsed
81
+ 24-hour days from that anchor, not a local calendar or recurring schedule. Reuse
82
+ the same anchor on every preview page and in the eventual start command.
83
+
84
+ `tasker_protocol_preview` and `protocols preview --file` take:
85
+
86
+ ```json
87
+ {
88
+ "scope": "project:PROJECT_ID",
89
+ "protocolVersionId": "11111111-1111-4111-8111-111111111111",
90
+ "bindings": {
91
+ "instanceId": "22222222-2222-4222-8222-222222222222",
92
+ "scope": "project:PROJECT_ID",
93
+ "epoch": "EPOCH_FROM_CURRENT_READ",
94
+ "anchor": "2026-11-16T09:00:00+01:00",
95
+ "values": {}
96
+ }
97
+ }
98
+ ```
99
+
100
+ Replace all example identifiers and the date with the actual project, version,
101
+ epoch and intended timing. Populate `values` from the chosen definition.
102
+
103
+ Preview requires `tasks:read`; it creates neither an instance nor tasks. Each
104
+ call consumes the normal read budget and returns at most 20 steps. When needed,
105
+ continue with `after: nextAfter` and the original returned `digest`, keeping the
106
+ version and every binding unchanged. Stop at `nextAfter: null`. Never claim
107
+ unread pages were inspected; changed context or lost access needs reconciliation.
108
+
109
+ Review the outcome, owners, dates, acceptance criteria, dependency structure and
110
+ importance. [Importance](importance.md) measures impact, independently of urgency
111
+ and hierarchy. Important/Critical need a concrete reason. Delivery preferences
112
+ request or suppress attention; a request cannot bypass recipient settings.
113
+
114
+ ## Materialize only the requested work
115
+
116
+ If the user asked to create this work, use the normal immutable command workflow.
117
+ Otherwise show the relevant preview and await that decision. No preview grants
118
+ write access or authorizes a later changed plan.
119
+
120
+ 1. Prepare `protocol.start` with `id: bindings.instanceId`, `expectedRevision:
121
+ null`, the same scope/epoch, and `data: {protocolVersionId, bindings}`.
122
+ 2. Execute that exact prepared operation, then read the resulting
123
+ `protocolInstances` record for its current revision, digest and `appliedCount`.
124
+ 3. Prepare `protocol.apply` against that instance and revision with
125
+ `data: {digest, from: appliedCount, count: 20}` or a smaller intended batch.
126
+ One call creates at most 20 steps through ordinary authority and quota checks.
127
+ 4. Read the confirmed result before preparing another batch. Continue only
128
+ within the requested work; there is no automatic apply loop in the client.
129
+
130
+ An uncertain reply requires replaying the same operation, not incrementing the
131
+ cursor or creating a fresh ID. After a definitive conflict, reread and reconcile.
132
+ Do not bypass expired/revoked access, identity binding, an ID collision or a
133
+ human-owned importance decision by using another transport or recreating tasks.
134
+ The creating user or a current project administrator may continue or cancel an
135
+ instance. The same user may continue under another profile only within that
136
+ profile's current grants; each new command rechecks access. An uncertain operation
137
+ remains bound to its original command identity and cannot be moved to another
138
+ profile or session. Resolve its outcome before preparing a new batch.
139
+
140
+ `Applied` means the tasks were materialized. It says nothing about completed
141
+ work, earned XP or delivered notifications. `protocol.cancel` with the current
142
+ revision stops remaining materialization; it preserves already created tasks.
143
+ Do not delete them as an implicit rollback. Instance counters, state and
144
+ provenance are server-owned.
145
+
146
+ CLI example for inspection, without creation:
147
+
148
+ ```sh
149
+ geniustasker workflow show --topic protocols --json
150
+ geniustasker protocols preview --file protocol-preview.json --context work --json
151
+ geniustasker commands describe --json
152
+ ```
153
+
154
+ CLI/local MCP preparation saves a private journal. Hosted ChatGPT preparation
155
+ returns the immutable command object; retain it and pass it to `tasker_edit_tasks`.
156
+ Both share the same account budget, membership and project permissions.
@@ -0,0 +1,31 @@
1
+ # CLI updates
2
+
3
+ Use `geniustasker update check --json` when checking package freshness. It reads
4
+ the official npm registry anonymously and does not read an account or consume its
5
+ API quota. The installed release selects beta or stable automatically; use
6
+ `--channel beta` or `--channel stable` only when that channel change is intended.
7
+ An older registry version is not a downgrade instruction.
8
+
9
+ When the user has requested an update, stop the local MCP server and let active
10
+ CLI commands finish, then run `geniustasker update install --json` in a terminal.
11
+ It updates only the current global npm installation. If the host uses an npx
12
+ version pin, a project dependency, a source checkout or another package manager,
13
+ update that installation through its own workflow instead; do not replace an
14
+ unrelated global package or change the host configuration without authorization.
15
+ Restart the MCP host after installation. This is not a hosted connector update.
16
+
17
+ The updater preserves credentials and immutable journals. An uncertain operation
18
+ stays uncertain: inspect it and retry the same operation only when the underlying
19
+ task calls for it. Do not reset authentication, remove journals or automatically
20
+ retry domain commands because a package was updated.
21
+
22
+ `update_runtime_busy` means another CLI/MCP process or an installer still owns
23
+ the installation. Wait or close it; never kill another task to install an update.
24
+ A crashed installer may leave an `install.lock` directory. Recover it only after
25
+ confirming that the installer and all clients have stopped, using the procedure
26
+ in [CLI updates](../../../docs/CLI.md#updates). `update_install_unconfirmed` needs
27
+ inspection of the installed version before retrying; it is not a success receipt.
28
+
29
+ Automatic discovery never runs from MCP or JSON calls. For terminal sessions,
30
+ `GENIUSTASKER_NO_UPDATE_CHECK=1` disables it. A registry outage must not interrupt
31
+ the user's actual work or trigger repeated checks.
@@ -10,6 +10,16 @@ do not load every graph at startup. Search nodes, inspect `nodeIndex`, then use
10
10
  `tasker_graph` around a selected node. Respect `truncated`: an incomplete
11
11
  neighborhood cannot prove a relation is absent. Read full records before edits.
12
12
 
13
+ Graph creation, node/edge changes and delegated Graph reads/search/exploration
14
+ require the acting user's Starter or Pro plan as well as the existing resource
15
+ grant. A paid space owner does not upgrade another reader. Document pages,
16
+ attachments and document references remain independent capabilities.
17
+ On `memory_graph_premium_required`, stop Graph calls; another tool, profile or
18
+ connection is not a workaround. After downgrade, the user can still inspect
19
+ existing content through ordinary application sync and personal-data export.
20
+ Offer document-only work when it satisfies the request; do not copy Graph data
21
+ into pages to evade the restriction.
22
+
13
23
  Each node owns its title, type, notes and optional resource thumbnail. Each edge
14
24
  has a source, target, typed relation and certainty. Prefer precise relation names
15
25
  and mark proposed connections as proposals. Preserve existing identities instead
@@ -44,11 +44,16 @@ A new memory uses one UUID v4 for root ID, scope suffix and initial epoch. Updat
44
44
  and deletes use a freshly read revision. Destructive changes require the user's
45
45
  actual authorization; read access never implies write access.
46
46
 
47
- Prepare a complete immutable operation using `tasker_prepare_command`, then send
48
- it with `tasker_retry_command` and the returned operation ID. CLI equivalents are
49
- `commands prepare --file draft.json` and `commands retry --operation ID`.
50
- After a timeout retry the exact retained operation. After a revision conflict,
51
- reread and prepare a new edit. Never change the body under an existing ID.
47
+ Prepare a complete immutable operation using `tasker_prepare_command`. In local
48
+ MCP, execute it with `tasker_retry_command` and the returned operation ID; the CLI
49
+ equivalents are `commands prepare --file draft.json` and
50
+ `commands retry --operation ID`. Hosted ChatGPT has no local operation journal:
51
+ retain the returned command object and send it through the discovered Memory edit
52
+ tool (`tasker_edit_memory`), unchanged after an uncertain result. Do not call a
53
+ local-only retry tool in the connector. After a revision conflict, reread and
54
+ reconcile the other contribution before preparing a new operation; never replace
55
+ the complete current page with an older snapshot. See the multi-agent procedure
56
+ in [focused knowledge workflows](references/knowledge-workflows.md).
52
57
 
53
58
  For authorized imports, keep a resumable local journal and source hashes; split
54
59
  pages to the advertised bounds, avoid duplicates, preserve editorial authority,
@@ -64,6 +69,11 @@ deployments may not expose them. Nodes and edges live in a memory scope. Read
64
69
  (`graph explore`) around a selected node rather than reading the entire graph.
65
70
  `truncated` means the result is incomplete. Never infer absent relations from it.
66
71
 
72
+ Graph creation, edits and delegated Graph reads/search/exploration require
73
+ Starter or Pro for the acting user, plus the resource grant. Documents and their
74
+ attachments remain independent. On `memory_graph_premium_required`, stop Graph
75
+ calls; do not switch tools, profiles or copy it into documents to bypass the tier.
76
+
67
77
  Each node owns its editable text; references contain only scope, pageId and an
68
78
  optional blockId. Use `tasker_reference` (`memory resolve`) for linked content.
69
79
  Access to Graph does not grant access to its references, including shared memories.
@@ -12,6 +12,12 @@ with the original epoch and checkpoint, including empty pages with a cursor.
12
12
  An unavailable source is not an empty source. Report the gap without changing
13
13
  accounts, permissions or the user's sharing settings.
14
14
 
15
+ Search is lexical, not a semantic ranking or a corpus-wide reasoning engine.
16
+ It matches up to twelve word prefixes together in one Memory and returns one
17
+ bounded page. If the result is insufficient, refine the words or make another
18
+ targeted call. Each call has normal authorization and usage accounting; do not
19
+ simulate an unlimited search with parallel calls over every Memory.
20
+
15
21
  ## Explore Graph progressively
16
22
 
17
23
  Use node search or `nodeIndex` to find a starting node. Call `tasker_graph` with
@@ -55,3 +61,39 @@ and source provenance. Prepare one immutable command and retain its operation ID
55
61
  retry that exact operation after a timeout. A revision conflict requires a new
56
62
  read and a new operation. Report what changed, what was verified, and what
57
63
  remains inaccessible or incomplete.
64
+
65
+ ## Cooperate without overwriting another agent
66
+
67
+ Two agents can read the same revision. A successful edit by one makes the
68
+ other's older update stale, even when their intended changes affect different
69
+ blocks. There is no automatic document merge and no exclusive Memory run lease.
70
+ Use separate profiles for attribution, not to avoid limits or gain access.
71
+
72
+ 1. Read the full page or node and retain its epoch, revision and stable block IDs.
73
+ Identify the requested change separately from the rest of the document.
74
+ 2. Prepare one immutable operation. After a timeout, establish that operation's
75
+ outcome before sending any replacement; a fresh read alone cannot settle an
76
+ uncertain command.
77
+ 3. If the service definitively reports `revision_conflict`, read the current
78
+ record again. Keep the other agent's contribution and all unrelated IDs,
79
+ references, source provenance and access fields.
80
+ 4. If the changes are compatible, apply only the intended edit to the new full
81
+ content and prepare a **new operation ID** using the newly read revision.
82
+ For conflicting claims or incompatible edits, leave the current record intact
83
+ and present the conflict or an explicitly labeled proposal to the user. Do not
84
+ decide that your version is authoritative because it came from an agent.
85
+ 5. Read back the saved result. Report the source ID/revision and the verified
86
+ change. Refresh relevant documentation mirrors after the source is confirmed.
87
+
88
+ `sourceId`, `authority`, `provenance` and `metadataJson` describe the content;
89
+ they are not verified identity, permission or proof of factual correctness.
90
+ Preserve original attribution and distinguish evidence from a new proposal.
91
+ The read-only `lastAgentActor`, when available on a page, node or edge, identifies
92
+ the server-verified latest agent editor (`ownerId`, `profileId`, `profileName`).
93
+ Never send or forge it in an edit. A human edit clears it; an older record without
94
+ the field has unknown agent attribution, not proof of human authorship. This
95
+ latest-editor snapshot is not a complete audit history or a claim that its
96
+ content has been fact-checked.
97
+ For local CLI/MCP retain the journal operation ID. For hosted ChatGPT retain the
98
+ complete prepared command and retry it with the discovered Memory edit tool;
99
+ the host cannot read a local journal or repository filesystem.