@pulsarinteractive/geniustasker 0.1.0-beta.12 → 0.1.0-beta.13
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 +6 -0
- package/README.md +8 -1
- package/docs/CHATGPT.md +6 -0
- package/docs/CLI.md +45 -5
- package/docs/INTEGRATIONS.md +25 -2
- package/examples/codex.toml +1 -1
- package/examples/mcp.json +1 -1
- package/mcp.json +1 -1
- package/package.json +1 -1
- package/plugin.json +1 -1
- package/remote/tool-catalog.json +185 -1
- package/remote/workflows.json +20 -0
- package/skills/geniustasker/SKILL.md +10 -1
- package/skills/geniustasker/references/metric-goals.md +143 -0
- package/skills/geniustasker/references/metrics-observations.md +184 -0
- package/skills/geniustasker/references/metrics.md +136 -0
- package/skills/geniustasker-memory/SKILL.md +4 -1
- package/src/changes.mjs +3 -5
- package/src/cli.mjs +39 -10
- package/src/command-catalog.mjs +96 -0
- package/src/command-input-schemas.mjs +551 -0
- package/src/commands.mjs +20 -3
- package/src/mcp.mjs +18 -18
- package/src/resources.mjs +98 -0
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# Link a goal to measured evidence
|
|
2
|
+
|
|
3
|
+
Use this workflow only for a requested goal and when live capabilities advertise
|
|
4
|
+
`metric.goal.create`, `metric.goal.update` and `metric.goal.delete`. A definition
|
|
5
|
+
or observation command never creates a goal implicitly. Read the
|
|
6
|
+
[definition](metrics.md) and [observation](metrics-observations.md) workflows first.
|
|
7
|
+
Existing recurring task goals and YouTube/Spotify goals remain separate.
|
|
8
|
+
|
|
9
|
+
## Read and explain the source
|
|
10
|
+
|
|
11
|
+
Use `metrics:read` / `metrics:write`; task and ordinary goal grants do not include
|
|
12
|
+
these permissions. Configuration also requires current project owner/admin
|
|
13
|
+
rights or the connected personal owner. Use `actor.ownerId` from identity for
|
|
14
|
+
`personal:<owner>`, never another account or a profile ID. The source definition
|
|
15
|
+
must exist in the **same scope** and express the intended unit and aggregation.
|
|
16
|
+
Creation and reactivation require an unarchived source; existing goals can still
|
|
17
|
+
be paused or archived while their source is archived, as explained below.
|
|
18
|
+
`metricId` cannot change on an existing goal.
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
geniustasker metrics list --scope project:PROJECT --id METRIC_UUID --json
|
|
22
|
+
geniustasker metrics list --scope project:PROJECT --collection metricGoals --json
|
|
23
|
+
geniustasker metrics list --scope personal:OWNER --collection personalMetricGoals --id GOAL_UUID --json
|
|
24
|
+
geniustasker commands describe --kind metric.goal.create --json
|
|
25
|
+
geniustasker workflow show --topic metrics --json
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
In MCP use `tasker_read_metrics` and `tasker_edit_metrics`. Read one bounded page
|
|
29
|
+
at a time; preserve the returned epoch, checkpoint and continuation. Goal
|
|
30
|
+
collections accept an exact goal `id`; `metricId` filtering is reserved for
|
|
31
|
+
observation/correction history. Do not scan all history to recompute progress.
|
|
32
|
+
|
|
33
|
+
## Choose the target and period
|
|
34
|
+
|
|
35
|
+
`target` is a decimal **string** in the source metric's unit, with a dot and at
|
|
36
|
+
most its configured precision. No exponent, thousands separator, percentage
|
|
37
|
+
symbol or JSON number. For a Ratio with `ratioScale:100`, target `"75"` means
|
|
38
|
+
75 percent; for scale 1 use `"0.75"` if the precision supports it. Preserve exact
|
|
39
|
+
decimal arithmetic instead of converting the threshold through floating point.
|
|
40
|
+
`AtLeast` means greater than or equal; `AtMost` means less than or equal.
|
|
41
|
+
|
|
42
|
+
`window:null` uses the recorded lifetime. A fixed window has explicit
|
|
43
|
+
timezone-qualified `start` and `end`, with start **included** and end **excluded**.
|
|
44
|
+
Choose boundaries in the user's intended timezone, then retain those instants.
|
|
45
|
+
It is not a recurring or rolling period. A goal called “This week” does not
|
|
46
|
+
advance itself next week. Date membership uses the observation's `observedAt`,
|
|
47
|
+
including late arrivals, corrections and voids, not its ingestion time.
|
|
48
|
+
|
|
49
|
+
Choose `OnReach` for completion as soon as a complete eligible result satisfies
|
|
50
|
+
the target. Choose `AtEnd` to wait for the fixed window's end; it requires a
|
|
51
|
+
non-null window. An upper-bound budget often needs `AtEnd`, since being below
|
|
52
|
+
the limit early does not establish the final result. Later evidence can still
|
|
53
|
+
correct a window's result after its end.
|
|
54
|
+
|
|
55
|
+
## Persist explicit configuration
|
|
56
|
+
|
|
57
|
+
This `data` example assumes a EUR Counter/Sum source with precision 2. The UUID
|
|
58
|
+
is illustrative: use the actual definition ID and the agreed dates and target.
|
|
59
|
+
Notification and coach options are off because the example does not request
|
|
60
|
+
either. Titles and explanations may use the user's language; API names and enum
|
|
61
|
+
values stay unchanged.
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"configuration": {
|
|
66
|
+
"metricId": "00000000-0000-4000-8000-000000000001",
|
|
67
|
+
"title": "Budget de novembre",
|
|
68
|
+
"description": "Dépenses vérifiées en euros sur novembre, clôture au terme de la période.",
|
|
69
|
+
"target": "500.00",
|
|
70
|
+
"comparison": "AtMost",
|
|
71
|
+
"window": {
|
|
72
|
+
"start": "2026-11-01T00:00:00+01:00",
|
|
73
|
+
"end": "2026-12-01T00:00:00+01:00"
|
|
74
|
+
},
|
|
75
|
+
"completion": "AtEnd",
|
|
76
|
+
"notifyCompleted": false,
|
|
77
|
+
"coachSignal": false,
|
|
78
|
+
"paused": false,
|
|
79
|
+
"archived": false
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Create with a new stable goal UUID, the scope's current epoch and
|
|
85
|
+
`expectedRevision:null`. For update, reread the goal and use its current revision
|
|
86
|
+
with the complete configuration, preserving unchanged choices. `metric.goal.delete`
|
|
87
|
+
takes empty `data` and a current revision; it does not delete the source metric
|
|
88
|
+
or its evidence. Never send the internal action, progress, scan cursor,
|
|
89
|
+
generation, attribution or completion fields.
|
|
90
|
+
|
|
91
|
+
Keep configuration concise: the current service limits it to 2,048 UTF-8 bytes
|
|
92
|
+
and admits at most 12 goals per metric, 128 per scope. These bounds apply in
|
|
93
|
+
addition to individual field limits. A refusal is not a reason to clone the
|
|
94
|
+
metric, split the same goal or rotate an agent profile.
|
|
95
|
+
|
|
96
|
+
Use the normal immutable command journal: prepare, then execute/retry the exact
|
|
97
|
+
operation. A lost acknowledgment is not a reason to create a second goal.
|
|
98
|
+
Revision conflicts require rereading before a new intentional edit. Hosted MCP
|
|
99
|
+
does not retain a local journal, so preserve the prepared request yourself.
|
|
100
|
+
Each read/write uses normal permissions and budgets; no bulk loop is implied.
|
|
101
|
+
|
|
102
|
+
## Report trustworthy progress
|
|
103
|
+
|
|
104
|
+
- `phase:"Pending"` means historical evaluation is incomplete. A bounded server
|
|
105
|
+
scan may already expose partial summary data; do not present it as the final
|
|
106
|
+
total, failure or success. Do not busy-poll or try to advance `scanAfter` yourself.
|
|
107
|
+
- `phase:"Ready"` means the summary is complete for the recorded evidence.
|
|
108
|
+
Use the server's `reached` result; comparison uses exact unrounded arithmetic.
|
|
109
|
+
`summary.value` is a nullable, rounded display string and can appear equal to
|
|
110
|
+
a threshold that the exact result has not reached. Summary integer fields
|
|
111
|
+
follow the [same scaling rules](metrics-observations.md#read-the-consolidated-result)
|
|
112
|
+
as the source; a goal's summary is restricted to its configured window.
|
|
113
|
+
- No active evidence yields `summary.value:null`, not a measured zero, even for
|
|
114
|
+
an `AtMost` target. Ready does not itself prove recent or complete external
|
|
115
|
+
data: inspect `latest.observedAt` and the definition's freshness configuration.
|
|
116
|
+
- `completedAt` records the first verified eligible completion. It is retained
|
|
117
|
+
through corrections, edits and retries. The current `reached` value can later
|
|
118
|
+
become false without erasing that historical fact. Do not recreate a goal to
|
|
119
|
+
repeat a reward, or confuse a completion record with confirmed push delivery.
|
|
120
|
+
|
|
121
|
+
`paused:true` retains progress tracking while suppressing automatic completion
|
|
122
|
+
reactions. `archived:true` stops tracking; restoration rebuilds progress before
|
|
123
|
+
reacting. Neither option discards evidence or clears prior completion.
|
|
124
|
+
|
|
125
|
+
Archiving the **source metric** also parks its goals’ pending scans and scheduled
|
|
126
|
+
checks without discarding progress. You can pause or archive an existing goal,
|
|
127
|
+
and clarify its title or description while keeping it paused/archived. You
|
|
128
|
+
cannot create a new goal, reactivate an archived goal, or change its target,
|
|
129
|
+
comparison, completion rule or window until the source is restored. A
|
|
130
|
+
`metric_paused` refusal is not a reason to reactivate the source without the
|
|
131
|
+
user’s request.
|
|
132
|
+
|
|
133
|
+
Restoring the source resumes a retained scan cursor or an outstanding `AtEnd`
|
|
134
|
+
boundary. A partial scan cannot complete early, and an `AtEnd` goal waits until
|
|
135
|
+
its boundary. Explicit goal pauses and archives remain in effect; restoration
|
|
136
|
+
does not clear them or reset `completedAt`.
|
|
137
|
+
|
|
138
|
+
`notifyCompleted` and `coachSignal` are explicit opt-ins; leave them false unless
|
|
139
|
+
requested, and preserve existing choices on update. They describe eligibility,
|
|
140
|
+
not evidence that a message was delivered or XP awarded. Recipient preferences
|
|
141
|
+
and the live service still apply. `coachSignal` does not issue an LLM request,
|
|
142
|
+
invoke an external agent, execute code or install a collector. Report saved
|
|
143
|
+
configuration, calculated progress and observed delivery as separate facts.
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
# Record, correct or void a metric observation
|
|
2
|
+
|
|
3
|
+
First read the [definition workflow](metrics.md), current identity, capabilities
|
|
4
|
+
and the exact definition. Use `metrics:read` to inspect it and `metrics:write`
|
|
5
|
+
for the requested mutation. The server also checks current native rights:
|
|
6
|
+
personal data belongs to the connected owner, while project observations use
|
|
7
|
+
the definition's writer policy. A grant never bypasses project opt-in or
|
|
8
|
+
membership. Do not add yourself to `writers` to work around a refusal.
|
|
9
|
+
|
|
10
|
+
## Read the consolidated result
|
|
11
|
+
|
|
12
|
+
Read the metric definition (`metrics` / `personalMetrics`) and inspect
|
|
13
|
+
`data.summary` before requesting observation history. This server-maintained
|
|
14
|
+
summary updates atomically with the source observation; it excludes voided
|
|
15
|
+
observations and all historical correction snapshots. It is lifetime-only.
|
|
16
|
+
A title such as “Weekly revenue” does not turn its summary into a current-week
|
|
17
|
+
aggregate. Requested [metric goals](metric-goals.md) have their own lifetime or
|
|
18
|
+
fixed-window evaluation. Discover that separate capability before using it; an
|
|
19
|
+
observation command never creates a goal or installs an arbitrary trigger.
|
|
20
|
+
|
|
21
|
+
- `activeCount` counts current, non-voided observations. It is distinct from
|
|
22
|
+
`observationCount`, which retains the count of recorded source observations.
|
|
23
|
+
- `sumUnits`, `numeratorUnits` and `denominatorUnits` are exact integer **strings**
|
|
24
|
+
in units of `10^-configuration.precision`. For precision 2, `"425"` means
|
|
25
|
+
4.25 units. Do not parse large totals as JavaScript `Number` or send these
|
|
26
|
+
strings back as new observations; keep exact integer/decimal arithmetic when
|
|
27
|
+
calculation is necessary.
|
|
28
|
+
- `value` is a nullable decimal **string**, already formatted at the configured
|
|
29
|
+
precision. Mean and Ratio round half away from zero for display. It is not a
|
|
30
|
+
JSON number or an unrounded threshold result. Use it for presentation without
|
|
31
|
+
another floating-point conversion; do not infer exact threshold satisfaction
|
|
32
|
+
from its rounded digits.
|
|
33
|
+
- `latest` identifies the latest active evidence with `observationId`,
|
|
34
|
+
`observedAt` and `measurement`. Gauge/Latest uses observation time, not arrival
|
|
35
|
+
time. A late older sample can change a Sum, Mean or Ratio without becoming the
|
|
36
|
+
latest observation. A correction or void can change which evidence is latest.
|
|
37
|
+
|
|
38
|
+
For an empty active set, `value` and `latest` are null. This is “no active
|
|
39
|
+
measurement,” not zero. A measured zero can instead have `activeCount > 0` and
|
|
40
|
+
`value:"0.00"`. A completely missing `summary` on a legacy definition means
|
|
41
|
+
unknown, not an empty set: never fabricate zero fields or reconstruct and write
|
|
42
|
+
the summary through client commands. If a write returns
|
|
43
|
+
`metric_summary_rebuild_required` (503), retain its immutable operation and
|
|
44
|
+
report that server repair is required; do not keep retrying or create another
|
|
45
|
+
metric to bypass it.
|
|
46
|
+
|
|
47
|
+
Freshness compares `summary.latest.observedAt` with the current time and
|
|
48
|
+
`configuration.freshnessSeconds`. Do not use definition `updated`, correction
|
|
49
|
+
arrival time or the time you fetched the page to claim fresh evidence. A null
|
|
50
|
+
freshness setting means no expected cadence was configured, not that all data
|
|
51
|
+
is always fresh. If latest is null, there is no active evidence to assess.
|
|
52
|
+
Late arrivals retain their source date; never replace it with now to make a
|
|
53
|
+
summary appear current.
|
|
54
|
+
|
|
55
|
+
## Choose the actual evidence
|
|
56
|
+
|
|
57
|
+
| Definition kind | `measurement` meaning |
|
|
58
|
+
| --------------- | ----------------------------------------------------------------------------------- |
|
|
59
|
+
| `Gauge` | `value` is the absolute level; `numerator` and `denominator` are null. |
|
|
60
|
+
| `Counter` | `value` is a signed contribution, not a running total; other fields are null. |
|
|
61
|
+
| `Ratio` | `value` is null; `numerator` is nonnegative and `denominator` is strictly positive. |
|
|
62
|
+
|
|
63
|
+
For example, a cumulative provider counter increasing from 100 to 103 is a
|
|
64
|
+
Gauge value of 103 **or**, for an explicitly defined increment metric with a
|
|
65
|
+
verified previous baseline, a Counter contribution of 3. It is never a Counter
|
|
66
|
+
contribution of 103. A negative Counter contribution can represent a real
|
|
67
|
+
reversal; correcting a wrong entry instead uses `metric.correct` so its cause
|
|
68
|
+
and previous value remain visible. Missing data is not a measured zero.
|
|
69
|
+
|
|
70
|
+
A Ratio's result uses the configured scale and sums of numerator and denominator.
|
|
71
|
+
Do not submit a percentage as `value`, or average rates with unequal denominators.
|
|
72
|
+
Do not calculate a global result from a partial history page. Corrections are
|
|
73
|
+
previous snapshots and must never be added to the observations; voided
|
|
74
|
+
observations must not be treated as active evidence.
|
|
75
|
+
|
|
76
|
+
Keep numbers in the definition's unit and precision. Magnitudes are bounded by
|
|
77
|
+
the current schema (currently 1,000,000,000); nonfinite numbers and invalid
|
|
78
|
+
denominators are not observations. Do not silently round or convert ambiguous
|
|
79
|
+
source units. Ask or clarify the definition when the source does not fit it.
|
|
80
|
+
|
|
81
|
+
## Record once
|
|
82
|
+
|
|
83
|
+
`metric.record` creates a new observation UUID with `expectedRevision:null`.
|
|
84
|
+
Its `data` contains `metricId`, the definition's current `measurementVersion`,
|
|
85
|
+
`sourceKey`, `sourceLabel`, `observedAt` and all three `measurement` fields.
|
|
86
|
+
The envelope ID is the **observation ID**, not the definition ID.
|
|
87
|
+
|
|
88
|
+
`sourceKey` is the stable event identity within that metric, for example a
|
|
89
|
+
provider record ID or a specific period's identifier. Preserve the observation
|
|
90
|
+
UUID and key in the producer's own mapping. Do not derive either from retry time
|
|
91
|
+
or translated text. Labels may be localized; identifiers must stay unchanged.
|
|
92
|
+
Neither field should contain credentials, signed download URLs or raw private
|
|
93
|
+
logs. A later independent observation gets its own event identity.
|
|
94
|
+
|
|
95
|
+
`observedAt` is the source observation time with an explicit timezone, not
|
|
96
|
+
arrival time. A late observation retains its real date. Do not substitute now
|
|
97
|
+
to evade freshness checks; the server bounds future skew. Never guess a missing
|
|
98
|
+
measurement, timestamp or source period.
|
|
99
|
+
|
|
100
|
+
Example `data` for a Gauge observation:
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"metricId": "00000000-0000-4000-8000-000000000001",
|
|
105
|
+
"measurementVersion": 1,
|
|
106
|
+
"sourceKey": "finance:week-2026-46",
|
|
107
|
+
"sourceLabel": "Weekly sales export",
|
|
108
|
+
"observedAt": "2026-11-15T23:00:00Z",
|
|
109
|
+
"measurement": { "value": 1250.5, "numerator": null, "denominator": null }
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Example `data` for a different definition configured as Ratio:
|
|
114
|
+
|
|
115
|
+
```json
|
|
116
|
+
{
|
|
117
|
+
"metricId": "00000000-0000-4000-8000-000000000002",
|
|
118
|
+
"measurementVersion": 1,
|
|
119
|
+
"sourceKey": "support:week-2026-46",
|
|
120
|
+
"sourceLabel": "Reviewed support outcomes",
|
|
121
|
+
"observedAt": "2026-11-15T23:00:00Z",
|
|
122
|
+
"measurement": { "value": null, "numerator": 18, "denominator": 20 }
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Do not send a batch hidden in one field. Each observation is one normal command,
|
|
127
|
+
using the shared account request and storage quotas. Preparing a local command
|
|
128
|
+
persists its immutable journal before sending; hosted preparation returns the
|
|
129
|
+
exact command to retain. On an uncertain response, retry that same operation ID,
|
|
130
|
+
`issuedAt` and body under the same identity. This is separate from source-event
|
|
131
|
+
deduplication: creating a new operation or UUID does not make an already used
|
|
132
|
+
`sourceKey` a new observation. On duplicate-source refusal, reconcile the saved
|
|
133
|
+
mapping and current record; do not alter the key to get around it.
|
|
134
|
+
|
|
135
|
+
## Correct or void with a reason
|
|
136
|
+
|
|
137
|
+
Read the current observation by ID, along with its definition. `metric.correct`
|
|
138
|
+
targets that observation UUID and its current revision, never the definition's
|
|
139
|
+
revision. Supply a complete replacement measurement and observedAt, plus a
|
|
140
|
+
concrete reason. It cannot change metricId, sourceKey or sourceLabel. The server
|
|
141
|
+
retains the previous snapshot and attributes the change to the real caller.
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
{
|
|
145
|
+
"observedAt": "2026-11-15T23:00:00Z",
|
|
146
|
+
"measurement": { "value": 1200.5, "numerator": null, "denominator": null },
|
|
147
|
+
"reason": "The verified export excluded a refunded sale that the initial amount included."
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Use `metric.void` when the evidence must be invalidated, with the current
|
|
152
|
+
observation revision and a reason:
|
|
153
|
+
|
|
154
|
+
```json
|
|
155
|
+
{ "reason": "This source export was generated from the wrong reporting period." }
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Void does not delete the observation or its audit trail. Do not clear source
|
|
159
|
+
keys, forge `voided` or write directly to correction collections. A conflict
|
|
160
|
+
means reread and decide again; do not overwrite a concurrent correction. If a
|
|
161
|
+
paused/archived definition or current writer policy refuses an operation, report
|
|
162
|
+
the refusal rather than changing settings implicitly.
|
|
163
|
+
|
|
164
|
+
## Bounded reads and truthful completion
|
|
165
|
+
|
|
166
|
+
```sh
|
|
167
|
+
geniustasker commands describe --kind metric.record --json
|
|
168
|
+
geniustasker commands describe --kind metric.correct --json
|
|
169
|
+
geniustasker metrics list --scope project:PROJECT --collection metricObservations --id OBSERVATION_UUID --json
|
|
170
|
+
geniustasker metrics list --scope project:PROJECT --collection metricObservations --metric-id METRIC_UUID --json
|
|
171
|
+
geniustasker metrics list --scope project:PROJECT --collection metricCorrections --metric-id METRIC_UUID --json
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Use the personal-prefixed collections for the connected personal scope. Every
|
|
175
|
+
page uses normal read admission; carry epoch/checkpoint/after and the exact
|
|
176
|
+
`metricId` filter unchanged. The equality filter applies only to observations
|
|
177
|
+
and corrections. Filtered reads return `changeCursor:null`; do not start a
|
|
178
|
+
filtered change stream. Only an unfiltered completed inventory supplies a
|
|
179
|
+
collection change cursor. There is no implicit full export or complex search.
|
|
180
|
+
A correction row includes `observationId`,
|
|
181
|
+
`previousRevision` and replacement attribution; it describes previous evidence,
|
|
182
|
+
not another event to count. Report the saved observation/correction and its
|
|
183
|
+
receipt. Do not claim goal progress, a trigger or a running collector unless
|
|
184
|
+
that separate capability is available and its result has actually been verified.
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Custom metric definitions
|
|
2
|
+
|
|
3
|
+
Use this workflow to define a measurement for the connected person or one
|
|
4
|
+
GeniusTasker project. Discover live capabilities first: `metrics:read` and
|
|
5
|
+
`metrics:write` are independent permissions. Existing task/goal grants do not
|
|
6
|
+
include them. Project configuration also requires the owner or administrator
|
|
7
|
+
and agent contributions enabled. A refusal is not permission to use private APIs.
|
|
8
|
+
|
|
9
|
+
Definition creation does not itself record a value. When capabilities advertise
|
|
10
|
+
`metric.record`, `metric.correct` and `metric.void`, use the
|
|
11
|
+
[observation workflow](metrics-observations.md) to record real evidence and retain
|
|
12
|
+
its corrections. These operations do not start a collector or link a goal.
|
|
13
|
+
When requested and advertised, use the separate [metric goal workflow](metric-goals.md)
|
|
14
|
+
to evaluate a target against the same scope’s metric. Existing YouTube/Spotify metrics are separate. Feature
|
|
15
|
+
activation and package installation are separate: use only what the current
|
|
16
|
+
server advertises.
|
|
17
|
+
|
|
18
|
+
## Read the right scope
|
|
19
|
+
|
|
20
|
+
Get `actor.ownerId` from current identity, never from a profile ID, name or old
|
|
21
|
+
session. For a personal definition use `personal:<actor.ownerId>`; for a project
|
|
22
|
+
definition use its discovered `project:<id>` scope. Consent to personal metrics
|
|
23
|
+
is a separate resource choice; it does not expose other personal account data.
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
geniustasker metrics list --scope personal:OWNER --json
|
|
27
|
+
geniustasker metrics list --scope project:PROJECT --json
|
|
28
|
+
geniustasker metrics list --scope project:PROJECT --id METRIC_UUID --json
|
|
29
|
+
geniustasker metrics list --scope project:PROJECT --collection metricObservations --json
|
|
30
|
+
geniustasker metrics list --scope personal:OWNER --collection personalMetricCorrections --json
|
|
31
|
+
geniustasker commands describe --kind metric.create --json
|
|
32
|
+
geniustasker workflow show --topic metrics --json
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Use the chosen environment/context consistently, including
|
|
36
|
+
`--environment production` for production data. `resources list` also supports
|
|
37
|
+
`metrics` in project scopes and `personalMetrics` in the connected personal
|
|
38
|
+
scope. In MCP prefer `tasker_read_metrics` with that same collection and scope.
|
|
39
|
+
Select `metricObservations` / `personalMetricObservations` for the current
|
|
40
|
+
observations, or `metricCorrections` / `personalMetricCorrections` for previous
|
|
41
|
+
snapshots. Linked goals use `metricGoals` / `personalMetricGoals`; these accept
|
|
42
|
+
an exact goal `id`, not the history-only `metricId` filter. The default CLI collection remains definitions for compatibility.
|
|
43
|
+
Read one page at a time; carry `after`, `epoch` and `checkpoint` unchanged for
|
|
44
|
+
continuation. Take the epoch from the returned page, including an empty one.
|
|
45
|
+
Use an exact ID read before editing and preserve unmodified configuration.
|
|
46
|
+
For observation/correction collections, `--metric-id METRIC_UUID` (MCP
|
|
47
|
+
`metricId`) selects one exact definition. Preserve that filter on every page;
|
|
48
|
+
filtered results have `changeCursor:null` and cannot start a filtered change
|
|
49
|
+
stream. Date-window and compound query filters are not exposed. Do not invent
|
|
50
|
+
query parameters or load every page implicitly; request further bounded pages
|
|
51
|
+
only when needed and state when a result is partial.
|
|
52
|
+
|
|
53
|
+
## Choose a useful meaning
|
|
54
|
+
|
|
55
|
+
For an existing metric's consolidated result, first read the definition's
|
|
56
|
+
`summary` with `metrics` or `personalMetrics`. This avoids scanning observations
|
|
57
|
+
just to obtain a total. The server updates it atomically with each accepted
|
|
58
|
+
record, correction or void. It covers the metric's **entire recorded lifetime**,
|
|
59
|
+
not a week, month or rolling window, even if the title mentions a period.
|
|
60
|
+
For exact numeric fields, missing values and freshness, read
|
|
61
|
+
[the summary rules](metrics-observations.md#read-the-consolidated-result).
|
|
62
|
+
|
|
63
|
+
| Meaning | Configuration | Avoid |
|
|
64
|
+
| ----------------------------------------------- | ------------------ | ------------------------------------------------ |
|
|
65
|
+
| Current level, such as audience size | `Gauge` + `Latest` | Summing repeated cumulative totals |
|
|
66
|
+
| Average of comparable samples | `Gauge` + `Mean` | Averaging unlike units or unequal weighted rates |
|
|
67
|
+
| Additive contributions, such as completed units | `Counter` + `Sum` | Overlapping periods and repeated contributions |
|
|
68
|
+
| Numerator/denominator measure | `Ratio` + `Ratio` | Unweighted averages of percentages |
|
|
69
|
+
|
|
70
|
+
Explain the unit, data source, interval and interpretation in the description.
|
|
71
|
+
Ask only for an ambiguity that changes the meaning. Never invent values or
|
|
72
|
+
claim an approximation is an observed result. The machine key stays stable;
|
|
73
|
+
write title and description naturally in the user's language. Do not translate
|
|
74
|
+
keys, IDs, API property names or enum values.
|
|
75
|
+
|
|
76
|
+
`precision` is 0–6. `ratioScale` is 1 or 100 for a Ratio, and 1 otherwise.
|
|
77
|
+
`freshnessSeconds` is null or 60–31536000; it describes expected freshness and
|
|
78
|
+
does not schedule collection. `writers` is empty for a personal definition.
|
|
79
|
+
Project writers are current approved member user IDs, not agent profile IDs;
|
|
80
|
+
they do not grant project administration or additional API permissions.
|
|
81
|
+
|
|
82
|
+
## Prepare and persist
|
|
83
|
+
|
|
84
|
+
`metric.create` and `metric.update` take this complete `data` shape (example in
|
|
85
|
+
French). Inspect command help for the current limits; do not send the internal
|
|
86
|
+
`action` field or server-owned creator, count, version or attribution fields.
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{
|
|
90
|
+
"configuration": {
|
|
91
|
+
"key": "weekly_revenue",
|
|
92
|
+
"title": "Chiffre d’affaires hebdomadaire",
|
|
93
|
+
"description": "Montant total pour une semaine complète, en euros. La source et la période seront précisées lors de la collecte.",
|
|
94
|
+
"kind": "Gauge",
|
|
95
|
+
"aggregation": "Latest",
|
|
96
|
+
"unit": "EUR",
|
|
97
|
+
"precision": 2,
|
|
98
|
+
"ratioScale": 1,
|
|
99
|
+
"freshnessSeconds": 604800,
|
|
100
|
+
"writers": [],
|
|
101
|
+
"paused": false,
|
|
102
|
+
"archived": false
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
For creation choose and retain one lowercase UUID as `id`, the scope's current
|
|
108
|
+
`epoch`, `expectedRevision:null`, and `kind:"metric.create"`. For update read the
|
|
109
|
+
existing UUID/revision and send `kind:"metric.update"` with the complete updated
|
|
110
|
+
configuration. The key cannot change. A duplicate key is a reason to reread and
|
|
111
|
+
reuse the intended definition, not to create several nearly identical entries.
|
|
112
|
+
|
|
113
|
+
Local CLI: `commands prepare --file draft.json --json`, then
|
|
114
|
+
`commands retry --operation OPERATION_UUID --json`. Local MCP: prepare with
|
|
115
|
+
`tasker_prepare_command`, then retry the returned operation or execute the
|
|
116
|
+
immutable request with `tasker_edit_metrics`. The dedicated tool uses the same
|
|
117
|
+
journal and normal server admission. Hosted MCP has no local journal: retain the
|
|
118
|
+
exact command returned by preparation and pass it to `tasker_edit_metrics`.
|
|
119
|
+
|
|
120
|
+
After uncertainty retain the exact operation ID, time and body. Respect retry
|
|
121
|
+
delays. After a revision conflict, reread and decide whether a new edit is still
|
|
122
|
+
appropriate. Do not automatically replace the user's configuration or broaden
|
|
123
|
+
access. A definition receipt proves configuration persistence, not collection or
|
|
124
|
+
progress toward a goal.
|
|
125
|
+
|
|
126
|
+
## Preserve existing meaning
|
|
127
|
+
|
|
128
|
+
Changing kind, aggregation, unit, precision or ratio scale changes the meaning
|
|
129
|
+
of samples. The server refuses it when observations exist. Do not silently
|
|
130
|
+
convert a definition to another unit or manufacture a zero observation count.
|
|
131
|
+
Descriptive changes do not increment measurement semantics.
|
|
132
|
+
|
|
133
|
+
Archive through `configuration.archived:true` with a current revision when the
|
|
134
|
+
definition should be retained. `metric.delete` takes empty `data` and a current
|
|
135
|
+
revision; it is refused when observations exist. No bulk ingestion, history
|
|
136
|
+
deletion or custom-goal operation is implied by these definition commands.
|
|
@@ -6,7 +6,10 @@ description: Read and maintain GeniusTasker Memory documents and Graph relations
|
|
|
6
6
|
Memory belongs to the account and is independent of projects. Use the user's
|
|
7
7
|
selected context and environment; discover identity and capabilities first.
|
|
8
8
|
If no session exists, ask the user to run `geniustasker auth login --context work`
|
|
9
|
-
in their terminal
|
|
9
|
+
in their terminal with the intended environment. The beta defaults to development;
|
|
10
|
+
TestFlight data requires `--environment production` at login and on subsequent
|
|
11
|
+
CLI/MCP invocations. Use a distinct context; its name alone does not select an
|
|
12
|
+
environment. The browser lets them select resources and permissions.
|
|
10
13
|
Do not collect passwords or tokens, approve your own consent, or edit credentials.
|
|
11
14
|
|
|
12
15
|
## Navigate without loading the entire corpus
|
package/src/changes.mjs
CHANGED
|
@@ -4,14 +4,11 @@ import { AgentClient } from './client.mjs';
|
|
|
4
4
|
import { Transport } from './transport.mjs';
|
|
5
5
|
import catalog from './command-catalog.mjs';
|
|
6
6
|
import { fail } from './errors.mjs';
|
|
7
|
+
import { resourceScopeSchema, validateResourceScope } from './resources.mjs';
|
|
7
8
|
|
|
8
9
|
export const changesSchema = z
|
|
9
10
|
.object({
|
|
10
|
-
scope:
|
|
11
|
-
.string()
|
|
12
|
-
.max(256)
|
|
13
|
-
// eslint-disable-next-line no-control-regex -- Reject control characters in untrusted input.
|
|
14
|
-
.regex(/^(project|memory):[^\u0000-\u001f]+$/u),
|
|
11
|
+
scope: resourceScopeSchema,
|
|
15
12
|
collection: z.string().min(1).max(32),
|
|
16
13
|
cursor: z.string().min(1).max(4096),
|
|
17
14
|
})
|
|
@@ -59,6 +56,7 @@ function query(input, schema) {
|
|
|
59
56
|
'Use a project or memory scope, collection and unchanged change cursor; waitSeconds must be within the supported bound.',
|
|
60
57
|
);
|
|
61
58
|
}
|
|
59
|
+
validateResourceScope(parsed.data);
|
|
62
60
|
return parsed.data;
|
|
63
61
|
}
|
|
64
62
|
/** Validate the entire bounded page before a caller can adopt its next cursor. */
|
package/src/cli.mjs
CHANGED
|
@@ -18,6 +18,7 @@ import { readMemoryTree, readMemoryMarkdown } from './documentation.mjs';
|
|
|
18
18
|
import { searchMemory, exploreGraph, resolveMemory } from './knowledge.mjs';
|
|
19
19
|
import { previewProtocol } from './protocols.mjs';
|
|
20
20
|
import { reportRunEvent } from './run-events.mjs';
|
|
21
|
+
import { readResources, readMetrics } from './resources.mjs';
|
|
21
22
|
import { MediaJournal, mediaAction, downloadMedia, compareMedia } from './media.mjs';
|
|
22
23
|
import { fail, safeError, exitCode } from './errors.mjs';
|
|
23
24
|
import { checkUpdate, installUpdate, maybeNotifyUpdate } from './update.mjs';
|
|
@@ -70,6 +71,11 @@ export const commands = {
|
|
|
70
71
|
summary: 'List independent account memories; follow nextAfter even for an empty page.',
|
|
71
72
|
options: ['after'],
|
|
72
73
|
},
|
|
74
|
+
'metrics list': {
|
|
75
|
+
summary:
|
|
76
|
+
'Read one bounded page of custom metric definitions (default), observations, corrections or linked goals. Select --collection; requires metrics:read.',
|
|
77
|
+
options: ['scope', 'collection', 'id', 'metric-id', 'after', 'epoch', 'checkpoint', 'archive'],
|
|
78
|
+
},
|
|
73
79
|
'media compare': {
|
|
74
80
|
summary: 'Compare a local file with an existing resource before uploading a replacement.',
|
|
75
81
|
options: ['scope', 'id', 'file'],
|
|
@@ -138,7 +144,17 @@ export const commands = {
|
|
|
138
144
|
},
|
|
139
145
|
'resources list': {
|
|
140
146
|
summary: 'Read a project or memory collection; carry epoch/checkpoint when continuing.',
|
|
141
|
-
options: [
|
|
147
|
+
options: [
|
|
148
|
+
'scope',
|
|
149
|
+
'collection',
|
|
150
|
+
'after',
|
|
151
|
+
'epoch',
|
|
152
|
+
'checkpoint',
|
|
153
|
+
'archive',
|
|
154
|
+
'id',
|
|
155
|
+
'path',
|
|
156
|
+
'metric-id',
|
|
157
|
+
],
|
|
142
158
|
},
|
|
143
159
|
'changes list': {
|
|
144
160
|
summary:
|
|
@@ -515,28 +531,41 @@ export async function main(
|
|
|
515
531
|
...(input.block === undefined ? {} : { blockId: input.block }),
|
|
516
532
|
});
|
|
517
533
|
}
|
|
534
|
+
} else if (command === 'metrics list') {
|
|
535
|
+
const input = Object.fromEntries(
|
|
536
|
+
commands[command].options
|
|
537
|
+
.filter((key) => options[key] !== undefined)
|
|
538
|
+
.map((key) => [key === 'metric-id' ? 'metricId' : key, options[key]]),
|
|
539
|
+
);
|
|
540
|
+
data = await readMetrics(client, {
|
|
541
|
+
...input,
|
|
542
|
+
collection:
|
|
543
|
+
options.collection ??
|
|
544
|
+
(options.scope?.startsWith('personal:') ? 'personalMetrics' : 'metrics'),
|
|
545
|
+
});
|
|
518
546
|
} else if (command === 'resources list' || command === 'questions answers') {
|
|
519
547
|
if (
|
|
520
548
|
!(command === 'questions answers'
|
|
521
549
|
? options.scope?.startsWith('project:')
|
|
522
550
|
: // eslint-disable-next-line no-control-regex -- Reject control characters in untrusted input.
|
|
523
|
-
/^(project|memory):[^\u0000-\u001f]+$/.test(options.scope ?? '')) ||
|
|
551
|
+
/^(project|memory|personal):[^\u0000-\u001f]+$/.test(options.scope ?? '')) ||
|
|
524
552
|
!(command === 'resources list' ? options.collection : options.question) ||
|
|
525
553
|
(options.after && (!options.epoch || !options.checkpoint))
|
|
526
554
|
) {
|
|
527
555
|
fail(
|
|
528
556
|
'invalid_arguments',
|
|
529
|
-
'Use --scope project:ID or memory:ID and --collection for resources or --question for answers;
|
|
557
|
+
'Use --scope project:ID or memory:ID and --collection for resources or --question for answers; personal:<connected-owner> is limited to metric definitions, observations and corrections. Continuation needs --epoch and --checkpoint.',
|
|
530
558
|
);
|
|
531
559
|
}
|
|
532
|
-
|
|
533
|
-
command
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
.filter((key) => options[key] !== undefined)
|
|
537
|
-
.map((key) => [key, options[key]]),
|
|
538
|
-
),
|
|
560
|
+
const input = Object.fromEntries(
|
|
561
|
+
commands[command].options
|
|
562
|
+
.filter((key) => options[key] !== undefined)
|
|
563
|
+
.map((key) => [key === 'metric-id' ? 'metricId' : key, options[key]]),
|
|
539
564
|
);
|
|
565
|
+
data =
|
|
566
|
+
command === 'resources list'
|
|
567
|
+
? await readResources(client, input)
|
|
568
|
+
: await client.get('answers', input);
|
|
540
569
|
} else if (command === 'mcp') {
|
|
541
570
|
const { runMcp } = await import('./mcp.mjs');
|
|
542
571
|
const server = await runMcp(client);
|