@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 +24 -0
- package/README.md +7 -1
- package/docs/ARCHITECTURE.md +15 -13
- package/docs/CLI.md +109 -1
- package/docs/INTEGRATIONS.md +2 -2
- package/docs/MEMORY.md +9 -0
- package/docs/WORKFLOWS.md +14 -0
- package/examples/codex.toml +1 -1
- package/examples/mcp.json +1 -1
- package/mcp.json +1 -1
- package/package.json +2 -2
- package/plugin.json +1 -1
- package/remote/tool-catalog.json +112 -1
- package/remote/workflows.json +33 -2
- package/skills/geniustasker/SKILL.md +5 -0
- package/skills/geniustasker/references/agent-runs.md +144 -0
- package/skills/geniustasker/references/host-events.md +116 -0
- package/skills/geniustasker/references/importance.md +90 -0
- package/skills/geniustasker/references/protocols.md +156 -0
- package/skills/geniustasker/references/updates.md +31 -0
- package/skills/geniustasker-graph/SKILL.md +10 -0
- package/skills/geniustasker-memory/SKILL.md +15 -5
- package/skills/geniustasker-memory/references/knowledge-workflows.md +42 -0
- package/skills/geniustasker-planning/SKILL.md +6 -1
- package/src/cli.mjs +70 -5
- package/src/client.mjs +7 -0
- package/src/command-catalog.mjs +753 -562
- package/src/command-input-schemas.d.mts +8 -0
- package/src/command-input-schemas.mjs +470 -0
- package/src/commands.mjs +70 -25
- package/src/mcp.mjs +31 -3
- package/src/protocols.mjs +122 -0
- package/src/recovery.mjs +80 -0
- package/src/run-events.mjs +145 -0
- package/src/transport.mjs +20 -4
- package/src/update-runtime.mjs +169 -0
- package/src/update.mjs +306 -0
|
@@ -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
|
|
48
|
-
it with `tasker_retry_command` and the returned operation ID
|
|
49
|
-
`commands prepare --file draft.json` and
|
|
50
|
-
|
|
51
|
-
|
|
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.
|