@karmaniverous/jeeves-meta-openclaw 0.10.7 → 0.12.0
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/README.md +4 -3
- package/dist/index.js +111 -6
- package/dist/serviceClient.d.ts +9 -0
- package/dist/skills/jeeves-meta/SKILL.md +91 -32
- package/openclaw.plugin.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,9 +4,10 @@ OpenClaw plugin for [jeeves-meta](../service/). A thin HTTP client that register
|
|
|
4
4
|
|
|
5
5
|
## Features
|
|
6
6
|
|
|
7
|
-
- **
|
|
7
|
+
- **Twelve tools** — standard: `meta_status`, `meta_config`, `meta_config_apply`, `meta_service`; custom: `meta_list`, `meta_detail`, `meta_trigger`, `meta_preview`, `meta_seed`, `meta_unlock`, `meta_queue` (list/clear/abort), `meta_update`
|
|
8
8
|
- **MetaServiceClient** — typed HTTP client delegating all operations to the running service
|
|
9
|
-
- **TOOLS.md injection** — periodic refresh of entity stats via `ComponentWriter` from `@karmaniverous/jeeves` (73-second prime interval)
|
|
9
|
+
- **TOOLS.md injection** — periodic refresh of entity stats, phase-state summary, failed-phase alerts, and next-phase indicator via `ComponentWriter` from `@karmaniverous/jeeves` (73-second prime interval)
|
|
10
|
+
- **Phase-state awareness** — tools expose per-meta `_phaseState`, `owedPhase`, and phase-state summary from the service's phase-state machine
|
|
10
11
|
- **Cleanup escalation** — passes `gatewayUrl` into `ComponentWriter` so managed-content cleanup can request a gateway session when needed
|
|
11
12
|
- **Dependency health** — shows warnings when watcher/gateway are degraded
|
|
12
13
|
- **Consumer skill** — `SKILL.md` for agent integration
|
|
@@ -57,7 +58,7 @@ The `configRoot` setting tells `@karmaniverous/jeeves` core where to find the pl
|
|
|
57
58
|
## Documentation
|
|
58
59
|
|
|
59
60
|
- **[Plugin Setup](guides/plugin-setup.md)** — installation, config, lifecycle
|
|
60
|
-
- **[Tools Reference](guides/tools-reference.md)** —
|
|
61
|
+
- **[Tools Reference](guides/tools-reference.md)** — 12 tools: standard (meta_status, meta_config, meta_config_apply, meta_service) + custom (meta_list, meta_detail, meta_trigger, meta_preview, meta_seed, meta_unlock, meta_queue, meta_update)
|
|
61
62
|
- **[Virtual Rules](guides/virtual-rules.md)** — watcher inference rules
|
|
62
63
|
- **[TOOLS.md Injection](guides/tools-injection.md)** — dynamic prompt generation
|
|
63
64
|
|
package/dist/index.js
CHANGED
|
@@ -18842,6 +18842,63 @@ async function generateMetaMenu(client) {
|
|
|
18842
18842
|
if (dependencies.gateway.status !== 'ok') {
|
|
18843
18843
|
depLines.push('> ⚠️ **Gateway**: ' + dependencies.gateway.status);
|
|
18844
18844
|
}
|
|
18845
|
+
// Phase-state summary from /status health
|
|
18846
|
+
const phaseLines = [];
|
|
18847
|
+
const phaseSummary = status.health.phaseStateSummary;
|
|
18848
|
+
if (phaseSummary) {
|
|
18849
|
+
// Aggregate counts across all phases
|
|
18850
|
+
const totals = {};
|
|
18851
|
+
for (const phase of ['architect', 'builder', 'critic']) {
|
|
18852
|
+
const counts = phaseSummary[phase];
|
|
18853
|
+
for (const [state, count] of Object.entries(counts)) {
|
|
18854
|
+
if (count > 0) {
|
|
18855
|
+
totals[state] = (totals[state] ?? 0) + count;
|
|
18856
|
+
}
|
|
18857
|
+
}
|
|
18858
|
+
}
|
|
18859
|
+
const parts = [];
|
|
18860
|
+
for (const state of ['fresh', 'pending', 'running', 'failed']) {
|
|
18861
|
+
if (totals[state]) {
|
|
18862
|
+
parts.push(totals[state].toString() + ' ' + state);
|
|
18863
|
+
}
|
|
18864
|
+
}
|
|
18865
|
+
if (parts.length > 0) {
|
|
18866
|
+
phaseLines.push('Phases: ' + parts.join(', '));
|
|
18867
|
+
}
|
|
18868
|
+
// Failed-phase alert
|
|
18869
|
+
const failedParts = [];
|
|
18870
|
+
for (const item of metas.metas) {
|
|
18871
|
+
const ps = item.phaseState;
|
|
18872
|
+
if (!ps)
|
|
18873
|
+
continue;
|
|
18874
|
+
for (const phase of ['architect', 'builder', 'critic']) {
|
|
18875
|
+
if (ps[phase] === 'failed') {
|
|
18876
|
+
const p = item.path;
|
|
18877
|
+
failedParts.push(p + ' (' + phase + ')');
|
|
18878
|
+
}
|
|
18879
|
+
}
|
|
18880
|
+
}
|
|
18881
|
+
if (failedParts.length > 0) {
|
|
18882
|
+
phaseLines.push('> Failed: ' +
|
|
18883
|
+
failedParts.slice(0, 10).join(', ') +
|
|
18884
|
+
(failedParts.length > 10
|
|
18885
|
+
? ' (+' + (failedParts.length - 10).toString() + ' more)'
|
|
18886
|
+
: ''));
|
|
18887
|
+
}
|
|
18888
|
+
}
|
|
18889
|
+
// Next-phase indicator from /status health
|
|
18890
|
+
const nextPhase = status.health.nextPhase;
|
|
18891
|
+
if (nextPhase) {
|
|
18892
|
+
phaseLines.push('Next: ' +
|
|
18893
|
+
nextPhase.path +
|
|
18894
|
+
' → ' +
|
|
18895
|
+
nextPhase.phase +
|
|
18896
|
+
' (band ' +
|
|
18897
|
+
nextPhase.band.toString() +
|
|
18898
|
+
', staleness ' +
|
|
18899
|
+
formatAge(nextPhase.staleness) +
|
|
18900
|
+
')');
|
|
18901
|
+
}
|
|
18845
18902
|
return [
|
|
18846
18903
|
'The jeeves-meta synthesis engine manages ' +
|
|
18847
18904
|
summary.total.toString() +
|
|
@@ -18856,6 +18913,7 @@ async function generateMetaMenu(client) {
|
|
|
18856
18913
|
'| Never synthesized | ' + summary.neverSynthesized.toString() + ' |',
|
|
18857
18914
|
'| Stalest | ' + stalestDisplay + ' |',
|
|
18858
18915
|
'| Last synthesized | ' + lastSynthDisplay + ' |',
|
|
18916
|
+
...(phaseLines.length > 0 ? ['', '### Phase State', ...phaseLines] : []),
|
|
18859
18917
|
...(depLines.length > 0 ? ['', '### Dependencies', ...depLines] : []),
|
|
18860
18918
|
'',
|
|
18861
18919
|
'Read the `jeeves-meta` skill for usage guidance, configuration, and troubleshooting.',
|
|
@@ -18905,11 +18963,22 @@ class MetaServiceClient {
|
|
|
18905
18963
|
qs.set('neverSynthesized', String(params.neverSynthesized));
|
|
18906
18964
|
if (params?.locked !== undefined)
|
|
18907
18965
|
qs.set('locked', String(params.locked));
|
|
18966
|
+
if (params?.disabled !== undefined)
|
|
18967
|
+
qs.set('disabled', String(params.disabled));
|
|
18908
18968
|
if (params?.fields?.length)
|
|
18909
18969
|
qs.set('fields', params.fields.join(','));
|
|
18910
18970
|
const query = qs.toString();
|
|
18911
18971
|
return this.get('/metas' + (query ? '?' + query : ''));
|
|
18912
18972
|
}
|
|
18973
|
+
/** PATCH /metas/:path — update user-settable reserved properties. */
|
|
18974
|
+
async update(metaPath, updates) {
|
|
18975
|
+
const encoded = encodeURIComponent(metaPath);
|
|
18976
|
+
return fetchJson(`${this.baseUrl}/metas/${encoded}`, {
|
|
18977
|
+
method: 'PATCH',
|
|
18978
|
+
headers: { 'Content-Type': 'application/json' },
|
|
18979
|
+
body: JSON.stringify(updates),
|
|
18980
|
+
});
|
|
18981
|
+
}
|
|
18913
18982
|
/** GET /metas/:path — detail for a single meta. */
|
|
18914
18983
|
async detail(metaPath, options) {
|
|
18915
18984
|
const encoded = encodeURIComponent(metaPath);
|
|
@@ -18980,6 +19049,7 @@ function buildCustomTools(client, baseUrl) {
|
|
|
18980
19049
|
buildMetaSeedTool(client, baseUrl),
|
|
18981
19050
|
buildMetaUnlockTool(client, baseUrl),
|
|
18982
19051
|
buildMetaQueueTool(client, baseUrl),
|
|
19052
|
+
buildMetaUpdateTool(client, baseUrl),
|
|
18983
19053
|
];
|
|
18984
19054
|
}
|
|
18985
19055
|
/** Wrap tool execution with connection error handling. */
|
|
@@ -18991,7 +19061,7 @@ function wrap(baseUrl, fn) {
|
|
|
18991
19061
|
function buildMetaListTool(client, baseUrl) {
|
|
18992
19062
|
return {
|
|
18993
19063
|
name: 'meta_list',
|
|
18994
|
-
description: 'List metas with summary stats and per-meta projection.
|
|
19064
|
+
description: 'List metas with summary stats and per-meta projection. Response includes _phaseState and owedPhase per meta.',
|
|
18995
19065
|
parameters: {
|
|
18996
19066
|
type: 'object',
|
|
18997
19067
|
properties: {
|
|
@@ -19001,12 +19071,13 @@ function buildMetaListTool(client, baseUrl) {
|
|
|
19001
19071
|
},
|
|
19002
19072
|
filter: {
|
|
19003
19073
|
type: 'object',
|
|
19004
|
-
description: 'Structured filter. Supported keys: hasError (boolean), staleHours (number), neverSynthesized (boolean), locked (boolean).',
|
|
19074
|
+
description: 'Structured filter. Supported keys: hasError (boolean), staleHours (number), neverSynthesized (boolean), locked (boolean), disabled (boolean).',
|
|
19005
19075
|
properties: {
|
|
19006
19076
|
hasError: { type: 'boolean' },
|
|
19007
19077
|
staleHours: { type: 'number' },
|
|
19008
19078
|
neverSynthesized: { type: 'boolean' },
|
|
19009
19079
|
locked: { type: 'boolean' },
|
|
19080
|
+
disabled: { type: 'boolean' },
|
|
19010
19081
|
},
|
|
19011
19082
|
},
|
|
19012
19083
|
fields: {
|
|
@@ -19024,6 +19095,7 @@ function buildMetaListTool(client, baseUrl) {
|
|
|
19024
19095
|
staleHours: filter?.staleHours,
|
|
19025
19096
|
neverSynthesized: filter?.neverSynthesized,
|
|
19026
19097
|
locked: filter?.locked,
|
|
19098
|
+
disabled: filter?.disabled,
|
|
19027
19099
|
fields: params.fields,
|
|
19028
19100
|
}));
|
|
19029
19101
|
},
|
|
@@ -19032,7 +19104,7 @@ function buildMetaListTool(client, baseUrl) {
|
|
|
19032
19104
|
function buildMetaDetailTool(client, baseUrl) {
|
|
19033
19105
|
return {
|
|
19034
19106
|
name: 'meta_detail',
|
|
19035
|
-
description: 'Full detail for a single meta, with optional archive history.',
|
|
19107
|
+
description: 'Full detail for a single meta, with optional archive history. Response includes _phaseState and owedPhase.',
|
|
19036
19108
|
parameters: {
|
|
19037
19109
|
type: 'object',
|
|
19038
19110
|
properties: {
|
|
@@ -19061,7 +19133,7 @@ function buildMetaDetailTool(client, baseUrl) {
|
|
|
19061
19133
|
function buildMetaPreviewTool(client, baseUrl) {
|
|
19062
19134
|
return {
|
|
19063
19135
|
name: 'meta_preview',
|
|
19064
|
-
description: 'Dry-run
|
|
19136
|
+
description: 'Dry-run preview of next synthesis. Returns owedPhase, priorityBand, phaseState, stalenessInputs, and architectInvalidators.',
|
|
19065
19137
|
parameters: {
|
|
19066
19138
|
type: 'object',
|
|
19067
19139
|
properties: {
|
|
@@ -19077,7 +19149,7 @@ function buildMetaPreviewTool(client, baseUrl) {
|
|
|
19077
19149
|
function buildMetaTriggerTool(client, baseUrl) {
|
|
19078
19150
|
return {
|
|
19079
19151
|
name: 'meta_trigger',
|
|
19080
|
-
description: '
|
|
19152
|
+
description: 'Trigger synthesis. Path-targeted creates an override queue entry; returns owedPhase. Fully-fresh metas return status:skipped.',
|
|
19081
19153
|
parameters: {
|
|
19082
19154
|
type: 'object',
|
|
19083
19155
|
properties: {
|
|
@@ -19153,7 +19225,7 @@ function buildMetaUnlockTool(client, baseUrl) {
|
|
|
19153
19225
|
function buildMetaQueueTool(client, baseUrl) {
|
|
19154
19226
|
return {
|
|
19155
19227
|
name: 'meta_queue',
|
|
19156
|
-
description: 'Queue management
|
|
19228
|
+
description: 'Queue management. list: 3-layer model (current with phase, overrides, automatic, pending). clear: removes overrides only. abort: returns {status,path,phase} or {status:idle}.',
|
|
19157
19229
|
parameters: {
|
|
19158
19230
|
type: 'object',
|
|
19159
19231
|
properties: {
|
|
@@ -19180,6 +19252,39 @@ function buildMetaQueueTool(client, baseUrl) {
|
|
|
19180
19252
|
},
|
|
19181
19253
|
};
|
|
19182
19254
|
}
|
|
19255
|
+
function buildMetaUpdateTool(client, baseUrl) {
|
|
19256
|
+
return {
|
|
19257
|
+
name: 'meta_update',
|
|
19258
|
+
description: 'Update user-settable reserved properties on a meta entity.',
|
|
19259
|
+
parameters: {
|
|
19260
|
+
type: 'object',
|
|
19261
|
+
properties: {
|
|
19262
|
+
path: {
|
|
19263
|
+
type: 'string',
|
|
19264
|
+
description: 'Path to the .meta/ directory or owner directory.',
|
|
19265
|
+
},
|
|
19266
|
+
updates: {
|
|
19267
|
+
type: 'object',
|
|
19268
|
+
description: 'Properties to set. Supported: _steer, _emphasis, _depth, _crossRefs, _disabled. Set to null to remove.',
|
|
19269
|
+
properties: {
|
|
19270
|
+
_steer: { type: ['string', 'null'] },
|
|
19271
|
+
_emphasis: { type: ['number', 'null'] },
|
|
19272
|
+
_depth: { type: ['number', 'null'] },
|
|
19273
|
+
_crossRefs: {
|
|
19274
|
+
oneOf: [
|
|
19275
|
+
{ type: 'array', items: { type: 'string' } },
|
|
19276
|
+
{ type: 'null' },
|
|
19277
|
+
],
|
|
19278
|
+
},
|
|
19279
|
+
_disabled: { type: ['boolean', 'null'] },
|
|
19280
|
+
},
|
|
19281
|
+
},
|
|
19282
|
+
},
|
|
19283
|
+
required: ['path', 'updates'],
|
|
19284
|
+
},
|
|
19285
|
+
execute: async (_id, params) => wrap(baseUrl, () => client.update(params.path, params.updates)),
|
|
19286
|
+
};
|
|
19287
|
+
}
|
|
19183
19288
|
|
|
19184
19289
|
/**
|
|
19185
19290
|
* Meta tool registrations for OpenClaw.
|
package/dist/serviceClient.d.ts
CHANGED
|
@@ -91,8 +91,17 @@ export declare class MetaServiceClient {
|
|
|
91
91
|
staleHours?: number;
|
|
92
92
|
neverSynthesized?: boolean;
|
|
93
93
|
locked?: boolean;
|
|
94
|
+
disabled?: boolean;
|
|
94
95
|
fields?: string[];
|
|
95
96
|
}): Promise<MetasResponse>;
|
|
97
|
+
/** PATCH /metas/:path — update user-settable reserved properties. */
|
|
98
|
+
update(metaPath: string, updates: {
|
|
99
|
+
_steer?: string | null;
|
|
100
|
+
_emphasis?: number | null;
|
|
101
|
+
_depth?: number | null;
|
|
102
|
+
_crossRefs?: string[] | null;
|
|
103
|
+
_disabled?: boolean | null;
|
|
104
|
+
}): Promise<unknown>;
|
|
96
105
|
/** GET /metas/:path — detail for a single meta. */
|
|
97
106
|
detail(metaPath: string, options?: {
|
|
98
107
|
includeArchive?: boolean | number;
|
|
@@ -7,6 +7,12 @@ jeeves-meta is the Jeeves platform's knowledge synthesis engine. It discovers
|
|
|
7
7
|
gathers context from co-located source files, and uses a three-step LLM process
|
|
8
8
|
(architect, builder, critic) to produce structured synthesis artifacts.
|
|
9
9
|
|
|
10
|
+
Each meta entity carries a **phase-state machine** (`_phaseState`) tracking
|
|
11
|
+
the state of each phase independently: `fresh`, `stale`, `pending`, `running`,
|
|
12
|
+
or `failed`. The scheduler picks **one phase per tick** across the entire
|
|
13
|
+
corpus (critic > builder > architect priority), enabling surgical retries of
|
|
14
|
+
failed phases without re-running the full pipeline.
|
|
15
|
+
|
|
10
16
|
**Requires:** jeeves-watcher ≥ 0.10.0 (provides `POST /walk` and auto
|
|
11
17
|
rules-reindex on registration).
|
|
12
18
|
|
|
@@ -19,16 +25,19 @@ registration health.
|
|
|
19
25
|
|
|
20
26
|
### meta_list
|
|
21
27
|
List all `.meta/` directories with summary stats and per-meta projection.
|
|
22
|
-
Supports filtering by path prefix, error status, staleness,
|
|
23
|
-
Use for engine health checks and finding stale knowledge.
|
|
28
|
+
Supports filtering by path prefix, error status, staleness, lock state, and
|
|
29
|
+
disabled status. Use for engine health checks and finding stale knowledge.
|
|
30
|
+
Each meta entry includes `phaseState` (`{ architect, builder, critic }`)
|
|
31
|
+
showing the per-phase state.
|
|
24
32
|
|
|
25
33
|
**Parameters:**
|
|
26
34
|
- `pathPrefix` (optional): Filter by path prefix (e.g. "github/")
|
|
27
|
-
- `filter` (optional): Structured filter (`{ hasError: true }`, `{ staleHours: 24 }`)
|
|
35
|
+
- `filter` (optional): Structured filter (`{ hasError: true }`, `{ staleHours: 24 }`, `{ disabled: true }`)
|
|
28
36
|
- `fields` (optional): Property projection array
|
|
29
37
|
|
|
30
38
|
### meta_detail
|
|
31
|
-
Full detail for a single meta, with optional archive history.
|
|
39
|
+
Full detail for a single meta, with optional archive history. Includes
|
|
40
|
+
`_phaseState` showing the per-phase state machine status.
|
|
32
41
|
|
|
33
42
|
**Parameters:**
|
|
34
43
|
- `path` (required): `.meta/` or owner directory path
|
|
@@ -36,20 +45,22 @@ Full detail for a single meta, with optional archive history.
|
|
|
36
45
|
- `includeArchive` (optional): false, true, or number (N most recent)
|
|
37
46
|
|
|
38
47
|
### meta_preview
|
|
39
|
-
Dry-run for the next synthesis
|
|
40
|
-
architect trigger reasons, steer status,
|
|
41
|
-
running any LLM calls.
|
|
42
|
-
|
|
48
|
+
Dry-run for the next synthesis candidate. Shows scope files, delta files,
|
|
49
|
+
architect trigger reasons, steer status, structure changes, and the
|
|
50
|
+
phase that would execute next — without running any LLM calls. Includes
|
|
51
|
+
`phaseState` and `owedPhase` (the phase that would run). Use before
|
|
52
|
+
`meta_trigger` to understand what will happen.
|
|
43
53
|
|
|
44
54
|
**Parameters:**
|
|
45
55
|
- `path` (optional): Specific `.meta/` or owner directory path. If omitted,
|
|
46
56
|
previews the stalest candidate.
|
|
47
57
|
|
|
48
58
|
### meta_trigger
|
|
49
|
-
Enqueue a synthesis
|
|
59
|
+
Enqueue a synthesis for a specific meta or the next-stalest candidate.
|
|
50
60
|
The synthesis runs asynchronously in the service queue; the tool returns
|
|
51
|
-
immediately with the queue position.
|
|
52
|
-
|
|
61
|
+
immediately with the queue position. Only one phase runs per tick (the
|
|
62
|
+
owed phase). Includes `owedPhase` in the response showing which phase
|
|
63
|
+
will execute.
|
|
53
64
|
|
|
54
65
|
**Parameters:**
|
|
55
66
|
- `path` (optional): Specific `.meta/` or owner directory path. If omitted,
|
|
@@ -86,16 +97,30 @@ filtering to extract specific settings. Sensitive fields (e.g.
|
|
|
86
97
|
- `path` (optional): JSONPath expression (e.g. `$.schedule`). If omitted,
|
|
87
98
|
returns the full sanitized config.
|
|
88
99
|
|
|
100
|
+
### meta_update
|
|
101
|
+
Update user-settable reserved properties on a meta entity. Use this to
|
|
102
|
+
toggle `_disabled`, change `_steer`, adjust `_emphasis` or `_depth`, or
|
|
103
|
+
modify `_crossRefs` — without editing `meta.json` directly on the filesystem.
|
|
104
|
+
|
|
105
|
+
**Parameters:**
|
|
106
|
+
- `path` (required): `.meta/` or owner directory path.
|
|
107
|
+
- `updates` (required): Object with properties to set. Supported:
|
|
108
|
+
`_steer`, `_emphasis`, `_depth`, `_crossRefs`, `_disabled`.
|
|
109
|
+
Set a value to `null` to remove the property.
|
|
110
|
+
|
|
89
111
|
### meta_queue
|
|
90
112
|
Queue management: list pending items, clear the queue, or abort current
|
|
91
|
-
synthesis. The
|
|
92
|
-
|
|
113
|
+
synthesis. The queue has three layers: `current` (the running phase),
|
|
114
|
+
`overrides` (explicitly triggered entries), and `automatic` (scheduler-
|
|
115
|
+
computed candidates). The `pending` and `state` fields provide legacy
|
|
116
|
+
compatibility.
|
|
93
117
|
|
|
94
118
|
**Parameters:**
|
|
95
119
|
- `action` (required): One of `list`, `clear`, `abort`.
|
|
96
|
-
- `list`: Show current queue state (current
|
|
97
|
-
|
|
98
|
-
- `
|
|
120
|
+
- `list`: Show current queue state (current with phase, overrides,
|
|
121
|
+
automatic candidates, pending items).
|
|
122
|
+
- `clear`: Remove all override queue entries.
|
|
123
|
+
- `abort`: Stop the currently running phase and release its lock.
|
|
99
124
|
|
|
100
125
|
## When to Use
|
|
101
126
|
|
|
@@ -113,6 +138,9 @@ what's running, clear queued work, or abort a stuck synthesis.
|
|
|
113
138
|
- **Checking queue state:** `meta_queue` with action `list`
|
|
114
139
|
- **Clearing queued work:** `meta_queue` with action `clear`
|
|
115
140
|
- **Aborting stuck synthesis:** `meta_queue` with action `abort`
|
|
141
|
+
- **Disabling a meta:** `meta_update` with path and `updates: { _disabled: true }`
|
|
142
|
+
- **Re-enabling a meta:** `meta_update` with path and `updates: { _disabled: null }`
|
|
143
|
+
- **Changing steer via API:** `meta_update` with path and `updates: { _steer: "new focus" }`
|
|
116
144
|
- **Reading synthesis output:** Use `watcher_search` filtered by the properties
|
|
117
145
|
configured in `metaProperty` (e.g. `{ "domains": ["meta"] }` in production).
|
|
118
146
|
The default properties are `{ _meta: "current" }` for live metas and
|
|
@@ -131,6 +159,10 @@ what's running, clear queued work, or abort a stuck synthesis.
|
|
|
131
159
|
- **Staleness:** Time since last synthesis. Deeper metas (leaves) update more
|
|
132
160
|
often than rollup metas (parents). Cross-ref freshness does NOT affect
|
|
133
161
|
the referencing meta's staleness — each meta synthesizes independently.
|
|
162
|
+
- **Disabled (`_disabled`):** Set `_disabled: true` on a meta to exclude it
|
|
163
|
+
from automatic staleness scheduling. The scheduler and auto-select both
|
|
164
|
+
skip disabled metas. Manual triggers (`meta_trigger` with explicit path)
|
|
165
|
+
still work. Use `meta_update` to toggle the flag.
|
|
134
166
|
- **Three steps:** Architect crafts the task brief, Builder produces content,
|
|
135
167
|
Critic evaluates quality. The feedback loop self-improves over cycles.
|
|
136
168
|
- **Archives:** Each cycle creates a timestamped snapshot in `.meta/archive/`.
|
|
@@ -140,6 +172,17 @@ what's running, clear queued work, or abort a stuck synthesis.
|
|
|
140
172
|
(e.g. phased analysis, incremental refinement). On builder timeout, the
|
|
141
173
|
engine attempts to recover partial output — if `_state` advanced, it saves
|
|
142
174
|
the new state without overwriting existing content.
|
|
175
|
+
- **Phase-state machine (`_phaseState`):** Each meta tracks its three phases
|
|
176
|
+
independently: `{ architect: <state>, builder: <state>, critic: <state> }`.
|
|
177
|
+
States are `fresh`, `stale`, `pending`, `running`, or `failed`. The
|
|
178
|
+
scheduler picks the single highest-priority owed phase across all metas
|
|
179
|
+
each tick (critic > builder > architect, with staleness tiebreaking).
|
|
180
|
+
Failed phases are automatically retried on the next tick (promoted from
|
|
181
|
+
`failed` → `pending`). Only the failed phase reruns — upstream/downstream
|
|
182
|
+
phases are untouched (surgical retries). A full cycle completes only when
|
|
183
|
+
all three phases are `fresh`, at which point the archive snapshot is taken
|
|
184
|
+
and `_synthesisCount` increments. Legacy metas without `_phaseState` have
|
|
185
|
+
their state derived automatically from existing fields on first load.
|
|
143
186
|
|
|
144
187
|
## Configuration
|
|
145
188
|
|
|
@@ -498,9 +541,10 @@ The service exposes these endpoints (default port 1938):
|
|
|
498
541
|
|
|
499
542
|
| Method | Path | Description |
|
|
500
543
|
|--------|------|-------------|
|
|
501
|
-
| GET | `/status` | Service health, queue state, dependency checks |
|
|
544
|
+
| GET | `/status` | Service health, queue state, dependency checks, phase-state summary |
|
|
502
545
|
| GET | `/metas` | List metas with filtering and field projection |
|
|
503
546
|
| GET | `/metas/:path` | Single meta detail with optional archive |
|
|
547
|
+
| PATCH | `/metas/:path` | Update user-settable reserved properties |
|
|
504
548
|
| GET | `/preview` | Dry-run next synthesis candidate |
|
|
505
549
|
| POST | `/synthesize` | Enqueue synthesis (stalest or specific path) |
|
|
506
550
|
| POST | `/synthesize/abort` | Abort the currently running synthesis |
|
|
@@ -508,8 +552,8 @@ The service exposes these endpoints (default port 1938):
|
|
|
508
552
|
| POST | `/unlock` | Remove `.lock` file from a meta entity |
|
|
509
553
|
| GET | `/config` | Query sanitized config with optional JSONPath (`?path=$.schedule`) |
|
|
510
554
|
| POST | `/config/apply` | Apply a config patch (merge or replace) |
|
|
511
|
-
| GET | `/queue` |
|
|
512
|
-
| POST | `/queue/clear` | Remove all
|
|
555
|
+
| GET | `/queue` | Queue state: current (with phase), overrides, automatic, pending |
|
|
556
|
+
| POST | `/queue/clear` | Remove all override queue entries |
|
|
513
557
|
|
|
514
558
|
All endpoints return JSON. The OpenClaw plugin tools are thin wrappers
|
|
515
559
|
around these endpoints.
|
|
@@ -534,15 +578,22 @@ The `start` command uses `--config`/`-c` instead (port is read from the config f
|
|
|
534
578
|
Recommended periodic checks:
|
|
535
579
|
- **Errors:** `meta_list` with `filter: { hasError: true }` — investigate
|
|
536
580
|
and retry with `meta_trigger`
|
|
581
|
+
- **Failed phases:** The TOOLS.md injection shows a "Failed:" alert listing
|
|
582
|
+
metas with failed phases. Failed phases auto-retry on the next scheduler
|
|
583
|
+
tick. Use `meta_detail` to inspect the `_phaseState` and `_error` fields.
|
|
537
584
|
- **Stuck locks:** `meta_list` with `filter: { locked: true }` — locks
|
|
538
585
|
older than 30 minutes indicate a crashed synthesis; use `jeeves-meta unlock`
|
|
539
586
|
- **Stale knowledge:** `meta_list` with `filter: { staleHours: 48 }` — check
|
|
540
587
|
if the scheduler is running and the watcher is up
|
|
588
|
+
- **Phase health:** `/status` includes `phaseStateSummary` with aggregate
|
|
589
|
+
counts per phase (`fresh`, `stale`, `pending`, `running`, `failed`) and
|
|
590
|
+
`nextPhase` showing the next candidate.
|
|
541
591
|
- **Service health:** `/status` endpoint (via `meta_list` summary or direct
|
|
542
592
|
HTTP) includes dependency status for watcher and gateway
|
|
543
593
|
|
|
544
594
|
The TOOLS.md injection surfaces the most critical stats (entity count, errors,
|
|
545
|
-
stalest entity
|
|
595
|
+
stalest entity, phase summary, failed-phase alerts, next-phase indicator) in
|
|
596
|
+
the agent's system prompt automatically.
|
|
546
597
|
|
|
547
598
|
## Troubleshooting
|
|
548
599
|
|
|
@@ -603,18 +654,22 @@ progressive work is not lost on timeout — only the content update is skipped.
|
|
|
603
654
|
3. Check if the LLM provider is slow or rate-limited
|
|
604
655
|
4. Check scope size: large scopes with many files take longer
|
|
605
656
|
|
|
606
|
-
### LLM errors in synthesis
|
|
657
|
+
### LLM errors in synthesis phases
|
|
607
658
|
|
|
608
|
-
**Symptom:** `meta_detail` shows `_error` field with step/code/message
|
|
659
|
+
**Symptom:** `meta_detail` shows `_error` field with step/code/message, and
|
|
660
|
+
`_phaseState` shows `failed` for one or more phases.
|
|
609
661
|
**Cause:** Subprocess failed (API error, malformed output, rate limit)
|
|
610
662
|
**Fix:**
|
|
611
663
|
1. Check error details: `meta_detail <path>` — `_error.step` tells you
|
|
612
|
-
which
|
|
613
|
-
2.
|
|
664
|
+
which phase failed; `_phaseState` shows the exact state of each phase
|
|
665
|
+
2. Failed phases are **automatically retried** on the next scheduler tick
|
|
666
|
+
(promoted from `failed` → `pending`). Only the failed phase reruns —
|
|
667
|
+
other phases are untouched (surgical retry).
|
|
668
|
+
3. Architect failure with existing `_builder`: engine reuses cached brief
|
|
614
669
|
(self-healing)
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
670
|
+
4. Architect failure without `_builder` (first run): retry with `meta_trigger`
|
|
671
|
+
5. Builder failure: meta stays stale, retried next tick automatically
|
|
672
|
+
6. Critic failure: content saved without feedback, not critical
|
|
618
673
|
|
|
619
674
|
### Discovery returns wrong/stale results
|
|
620
675
|
|
|
@@ -630,8 +685,9 @@ not yet indexed new files
|
|
|
630
685
|
|
|
631
686
|
## Gotchas
|
|
632
687
|
|
|
633
|
-
- `meta_trigger`
|
|
634
|
-
|
|
688
|
+
- `meta_trigger` enqueues a single phase (not all three). A full cycle
|
|
689
|
+
requires three separate ticks (one per phase). Use `meta_detail` to
|
|
690
|
+
check `_phaseState` for progress.
|
|
635
691
|
- A locked meta (another synthesis in progress) will be skipped silently.
|
|
636
692
|
- First-run quality is lower — the feedback loop needs 2-3 cycles to calibrate.
|
|
637
693
|
- Changing `metaProperty` requires both a meta service restart AND a watcher reindex.
|
|
@@ -642,9 +698,12 @@ not yet indexed new files
|
|
|
642
698
|
- All prompts are compiled as Handlebars templates. Avoid using `{{` in prompt
|
|
643
699
|
overrides unless you intend template variable resolution. Escape with `\{{`
|
|
644
700
|
for literal double-braces.
|
|
645
|
-
- The synthesis queue is single-threaded
|
|
646
|
-
|
|
701
|
+
- The synthesis queue is single-threaded with three layers: `current` (the
|
|
702
|
+
running phase), `overrides` (explicitly triggered entries, highest priority),
|
|
703
|
+
and `automatic` (scheduler-computed candidates). Override entries are
|
|
704
|
+
processed before automatic candidates.
|
|
647
705
|
- The scheduler uses adaptive backoff: if no stale candidates are found, it
|
|
648
|
-
doubles the skip interval (max 4×). Backoff resets after
|
|
706
|
+
doubles the skip interval (max 4×). Backoff resets after any successful
|
|
707
|
+
phase execution (not just full-cycle completion).
|
|
649
708
|
- All CLI commands except `start` require the service to be running (they call
|
|
650
709
|
the HTTP API).
|
package/openclaw.plugin.json
CHANGED
package/package.json
CHANGED