owenloop 0.5.6 → 0.5.8
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 +30 -0
- package/README.md +3 -6
- package/dist/packages/work/src/agent/approvals.d.ts +53 -0
- package/dist/packages/work/src/agent/approvals.js +132 -0
- package/dist/packages/work/src/agent/brief.d.ts +12 -0
- package/dist/packages/work/src/agent/brief.js +51 -0
- package/dist/packages/work/src/agent/capability-model.d.ts +64 -82
- package/dist/packages/work/src/agent/capability-model.js +94 -91
- package/dist/packages/work/src/agent/loop.d.ts +43 -25
- package/dist/packages/work/src/agent/loop.js +135 -50
- package/dist/packages/work/src/bundle/types.d.ts +3 -3
- package/dist/packages/work/src/exec/loop.js +37 -15
- package/dist/packages/work/src/harness/child-env.js +4 -5
- package/dist/packages/work/src/harness/claude.d.ts +4 -0
- package/dist/packages/work/src/harness/claude.js +72 -3
- package/dist/packages/work/src/harness/codex.d.ts +37 -1
- package/dist/packages/work/src/harness/codex.js +136 -18
- package/dist/packages/work/src/harness/contract.d.ts +54 -1
- package/dist/packages/work/src/harness/session-store.d.ts +127 -17
- package/dist/packages/work/src/harness/session-store.js +157 -60
- package/dist/packages/work/src/hub/client.d.ts +13 -1
- package/dist/packages/work/src/hub/client.js +3 -0
- package/dist/packages/work/src/hub/types.d.ts +104 -3
- package/dist/packages/work/src/main.js +1 -0
- package/dist/packages/work/src/roles/agent-run.js +52 -42
- package/dist/packages/work/src/roles/approvals.d.ts +76 -0
- package/dist/packages/work/src/roles/approvals.js +231 -0
- package/dist/packages/work/src/roles/sessions.d.ts +3 -2
- package/dist/packages/work/src/roles/sessions.js +9 -2
- package/dist/packages/work/src/roles/settings.js +1 -1
- package/dist/packages/work/src/settings/roster.d.ts +21 -0
- package/dist/packages/work/src/settings/roster.js +80 -0
- package/dist/packages/work/src/settings/settings.d.ts +12 -24
- package/dist/packages/work/src/settings/settings.js +17 -35
- package/dist/packages/work/src/shift/loop.d.ts +2 -0
- package/dist/packages/work/src/shift/loop.js +2 -0
- package/dist/packages/work/src/shift/runtime.js +17 -9
- package/dist/packages/work/src/shift/spawn.d.ts +10 -53
- package/dist/packages/work/src/shift/spawn.js +28 -60
- package/dist/packages/work/src/usage.d.ts +1 -1
- package/dist/packages/work/src/usage.js +8 -4
- package/dist/src/capabilities.d.ts +44 -0
- package/dist/src/capabilities.js +38 -0
- package/dist/src/cli.d.ts +1 -0
- package/dist/src/cli.js +460 -5
- package/dist/src/config-dir.d.ts +13 -18
- package/dist/src/config-dir.js +15 -23
- package/dist/src/credentials.d.ts +1 -1
- package/dist/src/credentials.js +1 -1
- package/dist/src/crypto/records.d.ts +3 -0
- package/dist/src/crypto/records.js +19 -0
- package/dist/src/crypto/trust-roots.d.ts +2 -2
- package/dist/src/crypto/trust-roots.js +2 -2
- package/dist/src/engine.d.ts +14 -0
- package/dist/src/engine.js +26 -14
- package/dist/src/global-config.d.ts +4 -7
- package/dist/src/global-config.js +4 -7
- package/dist/src/hub.d.ts +207 -5
- package/dist/src/hub.js +263 -3
- package/dist/src/index.d.ts +2 -2
- package/dist/src/index.js +1 -1
- package/dist/src/model.d.ts +37 -1
- package/dist/src/model.js +47 -1
- package/dist/src/schemas/index.d.ts +19 -0
- package/dist/src/schemas/order.v1.schema.json +15 -1
- package/dist/src/store/pre-commit-verifier.js +1 -1
- package/dist/src/types.d.ts +58 -4
- package/dist/src/work-settings.d.ts +2 -4
- package/dist/src/work-settings.js +2 -4
- package/docs/agent-runner.md +2 -2
- package/docs/bundles.md +3 -1
- package/docs/cli.md +295 -101
- package/docs/crypto.md +14 -14
- package/docs/routing.md +607 -0
- package/docs/shift-logs.md +22 -6
- package/package.json +1 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/claude-code/plugin/skills/author/SKILL.md +1 -2
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +1 -2
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,36 @@ All notable changes to this project are documented here. The format is based on
|
|
|
4
4
|
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
|
|
5
5
|
adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
6
|
|
|
7
|
+
## [0.5.8](https://github.com/typicalday/owenloop/compare/v0.5.7...v0.5.8) (2026-08-17)
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
### Features
|
|
11
|
+
|
|
12
|
+
* add layered crew roster routing ([#186](https://github.com/typicalday/owenloop/issues/186)) ([9fc1a55](https://github.com/typicalday/owenloop/commit/9fc1a55447bc48806d5b8775a9bdd5340f9258b8))
|
|
13
|
+
* add owenloop routing command group for alerts and reroute rules ([#182](https://github.com/typicalday/owenloop/issues/182)) ([012a16a](https://github.com/typicalday/owenloop/commit/012a16a97f01b2c98691403a2a8a9eba201ef889))
|
|
14
|
+
* let the offer caller reroute a composed capability ([#181](https://github.com/typicalday/owenloop/issues/181)) ([7240e61](https://github.com/typicalday/owenloop/commit/7240e61ee4263290d9eb1adfea96c3659a657ca9))
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
### Bug Fixes
|
|
18
|
+
|
|
19
|
+
* key session resume on the engine task, not on the per-firing run id ([#177](https://github.com/typicalday/owenloop/issues/177)) ([f1d4fbb](https://github.com/typicalday/owenloop/commit/f1d4fbbccab3048558a5319293e87bb3bcff22e8))
|
|
20
|
+
* relay a command step's output to the worker log on success too ([#185](https://github.com/typicalday/owenloop/issues/185)) ([618a3e0](https://github.com/typicalday/owenloop/commit/618a3e0309d79bb680f521c19fc183934f6f7bf8))
|
|
21
|
+
* surface a hub instance's terminal status in `instance show` ([#187](https://github.com/typicalday/owenloop/issues/187)) ([42e53bd](https://github.com/typicalday/owenloop/commit/42e53bd809bfe8e93a27ffa2941b8a89b0161bcc))
|
|
22
|
+
|
|
23
|
+
## [0.5.7](https://github.com/typicalday/owenloop/compare/v0.5.6...v0.5.7) (2026-08-16)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
### Features
|
|
27
|
+
|
|
28
|
+
* bridge an escalated tool call to a human approval and back ([#174](https://github.com/typicalday/owenloop/issues/174)) ([aa60594](https://github.com/typicalday/owenloop/commit/aa6059445dc95fcd3f0a810ecfbdada2f687aa9c))
|
|
29
|
+
* let a codex step's escalated call reach the same human approval gate ([#175](https://github.com/typicalday/owenloop/issues/175)) ([e43ca74](https://github.com/typicalday/owenloop/commit/e43ca74bf51485a499cf6f254c6a7a34fd4a1a5d))
|
|
30
|
+
* tell a step agent the shape it owes, before it produces one ([#172](https://github.com/typicalday/owenloop/issues/172)) ([54461b4](https://github.com/typicalday/owenloop/commit/54461b490f5617931cd1751db08885873ec9cbe7))
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
### Bug Fixes
|
|
34
|
+
|
|
35
|
+
* stop one shift from killing another shift's live agent sessions ([#176](https://github.com/typicalday/owenloop/issues/176)) ([82d9d82](https://github.com/typicalday/owenloop/commit/82d9d82f84121749c32e7a67b36b9506a51020b2))
|
|
36
|
+
|
|
7
37
|
## [0.5.6](https://github.com/typicalday/owenloop/compare/v0.5.5...v0.5.6) (2026-08-15)
|
|
8
38
|
|
|
9
39
|
|
package/README.md
CHANGED
|
@@ -487,12 +487,9 @@ hub's own def hashes. `owenloop agent new
|
|
|
487
487
|
Setting up a machine from scratch? `owenloop setup` may sign you in as a human
|
|
488
488
|
and, when needed, mint or rekey and store a Scoped Identity. Setup writes only
|
|
489
489
|
`hubOrigin` into the execution settings file, preserving the other keys. The
|
|
490
|
-
file is `$
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
`$HOME/.config/owenloop/settings.json`. Prefer `OWENLOOP_CONFIG_DIR` when
|
|
494
|
-
running several shifts on one machine — `XDG_CONFIG_HOME` also relocates `gh`,
|
|
495
|
-
`git`, and `gcloud` for every command step the shift dispatches. For
|
|
490
|
+
file is `$HOME/.owenloop/settings.json` by default (`OWENLOOP_CONFIG_DIR` can
|
|
491
|
+
provide an absolute isolated directory; `XDG_CONFIG_HOME` is not consulted).
|
|
492
|
+
For
|
|
496
493
|
a non-default account,
|
|
497
494
|
setup only prints the `OWENLOOP_ACCOUNT=<name>` instruction. Setup probes and,
|
|
498
495
|
when needed, converges the bundled `owenloop` plugins for Claude Code and Codex.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The worker half of the deterministic tool-approval gate: raise one escalated
|
|
3
|
+
* tool call to the hub, wait for a person, and hand the answer back to the
|
|
4
|
+
* BLOCKED CALL — not to a future attempt.
|
|
5
|
+
*
|
|
6
|
+
* WHY WAITING HERE IS SAFE, WHICH IS THE WHOLE PREMISE. Two independent facts
|
|
7
|
+
* have to hold at once, and both were verified before this was written:
|
|
8
|
+
*
|
|
9
|
+
* 1. The harness has no park deadline on a permission prompt. The host
|
|
10
|
+
* callback may take as long as it takes; what it must never do is fail to
|
|
11
|
+
* answer at all, because an unanswered prompt blocks that tool call
|
|
12
|
+
* forever with nothing recorded.
|
|
13
|
+
* 2. The lease keeps heartbeating while the agent is blocked. The worker's
|
|
14
|
+
* lease loop runs on its own timer, started but never awaited by the agent
|
|
15
|
+
* loop, so it is not suspended by a blocked callback. Without this, waiting
|
|
16
|
+
* would let the hub reap the very claim the approval is stamped to.
|
|
17
|
+
*
|
|
18
|
+
* WHAT THIS DELIBERATELY DOES NOT DO. It does not model the deadline hub-side.
|
|
19
|
+
* The hub has no view of how long a given worker is willing to wait, and a
|
|
20
|
+
* hub-side expiry racing this one would produce the single outcome that must not
|
|
21
|
+
* exist: an approval marked answered that no worker ever received. The deadline
|
|
22
|
+
* lives here, with the process that is actually waiting.
|
|
23
|
+
*
|
|
24
|
+
* EVERY NON-ANSWER IS A DENIAL. Deadline reached, hub unreachable, lease gone,
|
|
25
|
+
* caller aborted — all of them return `denied` with a reason. The adapter then
|
|
26
|
+
* does exactly what it did before this existed: refuse the call and route the
|
|
27
|
+
* agent to `ask`. That is the degradation path, and it is the pre-existing
|
|
28
|
+
* behavior rather than a new one, which is why adding this cannot make a
|
|
29
|
+
* deployment worse than it was.
|
|
30
|
+
*/
|
|
31
|
+
import type { ApprovalRequester } from '../harness/contract.ts';
|
|
32
|
+
import type { HubClient } from '../hub/client.ts';
|
|
33
|
+
/** Emitted so a blocked worker is visible in the shift log rather than looking
|
|
34
|
+
* hung. The worker supplies its own event sink. */
|
|
35
|
+
export interface ApprovalEvent {
|
|
36
|
+
kind: 'raised' | 'waiting' | 'decided' | 'failed';
|
|
37
|
+
text: string;
|
|
38
|
+
}
|
|
39
|
+
export interface ApprovalRequesterOptions {
|
|
40
|
+
client: HubClient;
|
|
41
|
+
workflow: string;
|
|
42
|
+
run: string;
|
|
43
|
+
/** How long to wait for a person before denying. */
|
|
44
|
+
deadlineMs?: number;
|
|
45
|
+
/** How often to re-send the (idempotent) request while waiting. */
|
|
46
|
+
pollIntervalMs?: number;
|
|
47
|
+
onEvent?: (e: ApprovalEvent) => void;
|
|
48
|
+
/** Injected in tests. Defaults to an unref'd `setTimeout`. */
|
|
49
|
+
sleep?: (ms: number) => Promise<void>;
|
|
50
|
+
/** Injected in tests. Defaults to `Date.now`. */
|
|
51
|
+
now?: () => number;
|
|
52
|
+
}
|
|
53
|
+
export declare function createApprovalRequester(opts: ApprovalRequesterOptions): ApprovalRequester;
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
import { HubError } from "../hub/types.js";
|
|
2
|
+
/**
|
|
3
|
+
* Twenty minutes. Long enough that a person who is at their desk but not
|
|
4
|
+
* watching this specific run can still answer, short enough that a run left
|
|
5
|
+
* blocked overnight does not hold a worker slot until the shift is restarted.
|
|
6
|
+
* A denial at the deadline costs the run one honest `ask`, not a failure.
|
|
7
|
+
*/
|
|
8
|
+
const DEFAULT_DEADLINE_MS = 20 * 60 * 1_000;
|
|
9
|
+
/**
|
|
10
|
+
* Five seconds. The poll is the same idempotent request as the raise, so its
|
|
11
|
+
* only cost is one small round trip; the reason not to go faster is that a
|
|
12
|
+
* person cannot answer faster than this anyway.
|
|
13
|
+
*/
|
|
14
|
+
const DEFAULT_POLL_MS = 5_000;
|
|
15
|
+
/** A timer that cannot by itself keep the event loop alive — a blocked approval
|
|
16
|
+
* must never be the reason a worker process refuses to exit. */
|
|
17
|
+
function sleepUnref(ms) {
|
|
18
|
+
return new Promise((resolve) => {
|
|
19
|
+
const t = setTimeout(resolve, ms);
|
|
20
|
+
t.unref();
|
|
21
|
+
});
|
|
22
|
+
}
|
|
23
|
+
function errText(err) {
|
|
24
|
+
if (err instanceof HubError)
|
|
25
|
+
return `${err.status} ${err.message}`;
|
|
26
|
+
return err instanceof Error ? err.message : String(err);
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* A hub error while WAITING is not necessarily fatal — a hub restart, a network
|
|
30
|
+
* blip, or a 5xx are all things the next poll may well ride through, and denying
|
|
31
|
+
* on the first one would make the gate useless on any imperfect link. A 4xx is
|
|
32
|
+
* different: the request itself is wrong or refused (bad scope, unknown run),
|
|
33
|
+
* and repeating it cannot change that.
|
|
34
|
+
*/
|
|
35
|
+
function isRetryable(err) {
|
|
36
|
+
if (!(err instanceof HubError))
|
|
37
|
+
return true;
|
|
38
|
+
return err.status >= 500 || err.status === 429;
|
|
39
|
+
}
|
|
40
|
+
export function createApprovalRequester(opts) {
|
|
41
|
+
const deadlineMs = opts.deadlineMs ?? DEFAULT_DEADLINE_MS;
|
|
42
|
+
const pollMs = opts.pollIntervalMs ?? DEFAULT_POLL_MS;
|
|
43
|
+
const sleep = opts.sleep ?? sleepUnref;
|
|
44
|
+
const now = opts.now ?? Date.now;
|
|
45
|
+
const emit = (e) => opts.onEvent?.(e);
|
|
46
|
+
return async function request(req) {
|
|
47
|
+
const started = now();
|
|
48
|
+
let raised = false;
|
|
49
|
+
let consecutiveErrors = 0;
|
|
50
|
+
for (;;) {
|
|
51
|
+
if (req.signal?.aborted === true) {
|
|
52
|
+
return { decision: 'denied', reason: 'the session ended before anyone answered' };
|
|
53
|
+
}
|
|
54
|
+
let res;
|
|
55
|
+
try {
|
|
56
|
+
// The SAME call every time. Raise and poll are one verb, keyed on
|
|
57
|
+
// `toolUseId`, so a retry after a network failure cannot open a second
|
|
58
|
+
// question and a poll cannot ask about one nobody raised.
|
|
59
|
+
res = await opts.client.requestApproval({
|
|
60
|
+
workflow: opts.workflow,
|
|
61
|
+
run: opts.run,
|
|
62
|
+
tool_use_id: req.toolUseId,
|
|
63
|
+
tool_name: req.toolName,
|
|
64
|
+
tool_input: req.toolInput,
|
|
65
|
+
reason: req.reason,
|
|
66
|
+
...(req.title !== undefined ? { title: req.title } : {}),
|
|
67
|
+
});
|
|
68
|
+
consecutiveErrors = 0;
|
|
69
|
+
}
|
|
70
|
+
catch (err) {
|
|
71
|
+
if (!isRetryable(err)) {
|
|
72
|
+
emit({ kind: 'failed', text: `approval refused by the hub: ${errText(err)}` });
|
|
73
|
+
return { decision: 'denied', reason: `the hub refused the approval request (${errText(err)})` };
|
|
74
|
+
}
|
|
75
|
+
consecutiveErrors += 1;
|
|
76
|
+
if (now() - started >= deadlineMs) {
|
|
77
|
+
return {
|
|
78
|
+
decision: 'denied',
|
|
79
|
+
reason: `the hub was unreachable for the whole wait (${consecutiveErrors} attempts, last: ${errText(err)})`,
|
|
80
|
+
};
|
|
81
|
+
}
|
|
82
|
+
await sleep(pollMs);
|
|
83
|
+
continue;
|
|
84
|
+
}
|
|
85
|
+
// The claim ended underneath us. Nothing was written and there is nobody
|
|
86
|
+
// left for an answer to reach, so waiting longer cannot help.
|
|
87
|
+
if (res.ok === false || res.approval === undefined) {
|
|
88
|
+
const why = res.reason ?? 'the hub did not record the request';
|
|
89
|
+
emit({ kind: 'failed', text: `approval not open: ${why}` });
|
|
90
|
+
return { decision: 'denied', reason: `this run no longer holds its claim (${why})` };
|
|
91
|
+
}
|
|
92
|
+
const state = res.approval.state;
|
|
93
|
+
if (state === 'approved') {
|
|
94
|
+
emit({
|
|
95
|
+
kind: 'decided',
|
|
96
|
+
text: `approved by ${res.approval.decidedBy ?? 'a person'}: ${req.toolName}`,
|
|
97
|
+
});
|
|
98
|
+
return {
|
|
99
|
+
decision: 'approved',
|
|
100
|
+
...(res.approval.note !== null ? { note: res.approval.note } : {}),
|
|
101
|
+
};
|
|
102
|
+
}
|
|
103
|
+
if (state === 'denied' || state === 'expired') {
|
|
104
|
+
emit({
|
|
105
|
+
kind: 'decided',
|
|
106
|
+
text: `${state} by ${res.approval.decidedBy ?? 'the hub'}: ${req.toolName}`,
|
|
107
|
+
});
|
|
108
|
+
return {
|
|
109
|
+
decision: 'denied',
|
|
110
|
+
reason: state === 'denied' ? 'a person denied this call' : 'the approval is no longer live',
|
|
111
|
+
...(res.approval.note !== null ? { note: res.approval.note } : {}),
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
// Still pending.
|
|
115
|
+
if (!raised) {
|
|
116
|
+
raised = true;
|
|
117
|
+
emit({
|
|
118
|
+
kind: 'raised',
|
|
119
|
+
text: `waiting on a human decision: ${req.toolName} — ${req.reason}`,
|
|
120
|
+
});
|
|
121
|
+
}
|
|
122
|
+
if (now() - started >= deadlineMs) {
|
|
123
|
+
emit({ kind: 'waiting', text: `nobody answered within the wait window: ${req.toolName}` });
|
|
124
|
+
return {
|
|
125
|
+
decision: 'denied',
|
|
126
|
+
reason: `nobody answered within ${Math.round(deadlineMs / 60_000)} minutes`,
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
await sleep(pollMs);
|
|
130
|
+
}
|
|
131
|
+
};
|
|
132
|
+
}
|
|
@@ -99,6 +99,18 @@ export interface OwedBrief {
|
|
|
99
99
|
/** Engine refusals of a malformed value against the path's declared JSON
|
|
100
100
|
* Schema (`packet.owes[].schemaRejects`). */
|
|
101
101
|
schemaRejects?: number;
|
|
102
|
+
/**
|
|
103
|
+
* The JSON Schema the engine will enforce on this path at commit time
|
|
104
|
+
* (`packet.owes[].schema`). Optional for the same reason the counters are: a
|
|
105
|
+
* hub that does not project it is not a hub reporting "no constraint", so the
|
|
106
|
+
* shape contract stays silent rather than telling an agent its output is
|
|
107
|
+
* unconstrained when it may not be.
|
|
108
|
+
*/
|
|
109
|
+
schema?: unknown;
|
|
110
|
+
/** What `schema` governs (`packet.owes[].schemaAppliesTo`) — `'value'` for the
|
|
111
|
+
* submitted value itself, `'member'` for each member emitted into a
|
|
112
|
+
* collection. Read only when `schema` is present. */
|
|
113
|
+
schemaAppliesTo?: 'value' | 'member';
|
|
102
114
|
}
|
|
103
115
|
/**
|
|
104
116
|
* Substitute the four dispatch tokens into a step template.
|
|
@@ -38,6 +38,7 @@ export function renderBrief(templateContent, spec) {
|
|
|
38
38
|
renderRoutingLine(spec),
|
|
39
39
|
renderInputContract(spec),
|
|
40
40
|
renderSubmitContract(spec),
|
|
41
|
+
renderShapeContract(spec),
|
|
41
42
|
renderAttemptHistory(spec),
|
|
42
43
|
renderEscalationContract(spec),
|
|
43
44
|
substituted,
|
|
@@ -192,6 +193,56 @@ function renderSubmitContract(spec) {
|
|
|
192
193
|
'Printing that value as text, or inside a code fence, does NOT submit it — the turn ends, the hub records nothing, and this order is re-offered from scratch. Wherever this brief says "green <path> with <value>", it means exactly this tool call.',
|
|
193
194
|
].join('\n');
|
|
194
195
|
}
|
|
196
|
+
/**
|
|
197
|
+
* The SHAPE each owed value must have, stated before the agent produces one.
|
|
198
|
+
*
|
|
199
|
+
* WHY THIS EXISTS. The attempt history already tells a re-offered agent that its
|
|
200
|
+
* last submission failed its schema, and how many refusals remain before the
|
|
201
|
+
* step freezes. It never tells it the schema. So the agent on attempt two knows
|
|
202
|
+
* only that something about the shape was wrong, holds exactly the information
|
|
203
|
+
* it held on attempt one, and the most available move is to resubmit a near
|
|
204
|
+
* variant — which is how a step burns its whole `maxSchemaFailures` budget on
|
|
205
|
+
* one misunderstanding. The counter and the reasons are the symptom channel;
|
|
206
|
+
* this is the requirement channel, and only one of them was wired.
|
|
207
|
+
*
|
|
208
|
+
* A schema refusal is also the CHEAPEST failure to prevent and the most
|
|
209
|
+
* pointless to suffer: the engine rejects the value structurally, so no
|
|
210
|
+
* consumer and no judge ever sees it, no reviewer time is spent, and the agent
|
|
211
|
+
* learns nothing it could not have been told for free at dispatch.
|
|
212
|
+
*
|
|
213
|
+
* WHEN IT RENDERS. Only for owed paths whose produce actually declares a
|
|
214
|
+
* schema. Most do not, and for those the engine accepts any JSON — so silence
|
|
215
|
+
* here is correct, and a blanket "no schema declared" line would be worse than
|
|
216
|
+
* nothing: a hub too old to project the field looks identical to a produce with
|
|
217
|
+
* no schema, and only one of those two justifies telling an agent its output is
|
|
218
|
+
* unconstrained. Neither gets that claim.
|
|
219
|
+
*
|
|
220
|
+
* WHY IT PRINTS THE SCHEMA WHOLE. A truncated JSON Schema is not a smaller
|
|
221
|
+
* requirement, it is a different and wrong one — an agent that reads a clipped
|
|
222
|
+
* `required` array will confidently omit a field. If a schema is large, large
|
|
223
|
+
* is what the contract is.
|
|
224
|
+
*
|
|
225
|
+
* WHY `member` IS SPELLED OUT. A collection's owed path is its seal, but the
|
|
226
|
+
* declared schema is checked against each member emitted into it, never against
|
|
227
|
+
* the seal value. Printing the schema under the seal path without that sentence
|
|
228
|
+
* would tell the agent to shape the wrong thing.
|
|
229
|
+
*/
|
|
230
|
+
function renderShapeContract(spec) {
|
|
231
|
+
const constrained = (spec.owes ?? []).filter((o) => o.path !== '' && o.schema !== undefined);
|
|
232
|
+
if (constrained.length === 0)
|
|
233
|
+
return '';
|
|
234
|
+
const blocks = constrained.map((o) => {
|
|
235
|
+
const governs = o.schemaAppliesTo === 'member'
|
|
236
|
+
? `Each member you emit into \`${o.path}\` must satisfy this JSON Schema — it is checked per member, NOT against the sealed collection itself.`
|
|
237
|
+
: `The value you submit to \`${o.path}\` must satisfy this JSON Schema.`;
|
|
238
|
+
return `${governs}\n\`\`\`json\n${JSON.stringify(o.schema, null, 2)}\n\`\`\``;
|
|
239
|
+
});
|
|
240
|
+
return [
|
|
241
|
+
'The shape of what you owe:',
|
|
242
|
+
...blocks,
|
|
243
|
+
'The engine checks these at submit time, before any consumer or judge sees the value. A value that does not match is refused structurally — it is not reviewed, not partially accepted, and the refusal spends one of this order\'s limited schema attempts. Match the schema exactly rather than submitting something close and waiting to be told.',
|
|
244
|
+
].join('\n');
|
|
245
|
+
}
|
|
195
246
|
/**
|
|
196
247
|
* What an agent does when it CANNOT complete the order, stated to every agent on
|
|
197
248
|
* every run, right after the submit contract.
|
|
@@ -1,58 +1,34 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Resolve an order's COMPOSED CAPABILITY to the
|
|
3
|
-
*
|
|
2
|
+
* Resolve an order's COMPOSED CAPABILITY to the local crew roster that serves
|
|
3
|
+
* it. The hub decides what grade of work an order is; the machine decides
|
|
4
|
+
* which locally available harness, model, and effort serve that grade.
|
|
4
5
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
* definition has no business asserting.
|
|
10
|
-
*
|
|
11
|
-
* So the settings file carries a flat map from capability to `{model, effort}`:
|
|
6
|
+
* A crew roster is a capability-to-candidate-list table. It is deliberately
|
|
7
|
+
* local: accounts, quotas, and operator preference do not belong in a shared
|
|
8
|
+
* workflow definition. The candidates are ordered so an operator can express
|
|
9
|
+
* a preferred harness with a deterministic fallback:
|
|
12
10
|
*
|
|
13
11
|
* ```json
|
|
14
12
|
* {
|
|
15
|
-
* "
|
|
16
|
-
* "wise:deep":
|
|
17
|
-
*
|
|
18
|
-
*
|
|
13
|
+
* "roster": {
|
|
14
|
+
* "wise:deep": [
|
|
15
|
+
* { "harness": "<harness-id>", "model": "<model-id>", "effort": "xhigh" }
|
|
16
|
+
* ]
|
|
19
17
|
* }
|
|
20
18
|
* }
|
|
21
19
|
* ```
|
|
22
20
|
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
* and `docs/` carry worked examples with real ids.
|
|
27
|
-
*
|
|
28
|
-
* THIS REPLACES `tierMap`/`tierProfiles` OUTRIGHT. A tier was an abstract rung
|
|
29
|
-
* (`fast`/`standard`/`strong`/`strongest`) that a machine then mapped to a
|
|
30
|
-
* model, and the tier ladder could not express the thing the operator actually
|
|
31
|
-
* wanted: "Luna at low effort" and "Fable at max effort" are different routes,
|
|
32
|
-
* but the ladder welded model choice and depth into one ordered axis, so one
|
|
33
|
-
* could not vary without the other. A capability is just a name. What serves it
|
|
34
|
-
* is a local lookup, and depth rides on the capability's modifier suffix rather
|
|
35
|
-
* than on a rung.
|
|
36
|
-
*
|
|
37
|
-
* The one behavior worth carrying out of the tier code is EFFORT VALIDITY
|
|
38
|
-
* CHECKING, which now happens at settings load rather than at resolution time.
|
|
39
|
-
* It checks the effort against `EFFORT_LADDER` — the neutral start contract's
|
|
40
|
-
* own five rungs — and nothing else.
|
|
21
|
+
* The one behavior worth carrying out of the retired tier code is EFFORT
|
|
22
|
+
* VALIDITY CHECKING. It happens at settings load and checks only the neutral
|
|
23
|
+
* start contract's five rungs.
|
|
41
24
|
*
|
|
42
|
-
* IT DELIBERATELY DOES NOT CHECK EFFORT AGAINST THE MODEL.
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
* table here would be either a restatement of `EFFORT_LADDER` under
|
|
50
|
-
* model-shaped keys, or an invention that blocks a valid operator config. The
|
|
51
|
-
* real per-harness check belongs on the adapter contract; see the follow-up
|
|
52
|
-
* noted in `validateCapabilityModels`.
|
|
53
|
-
*
|
|
54
|
-
* The old snap-up/ceiling-refusal logic in `resolveEffort` is gone with the
|
|
55
|
-
* ladder it resolved through: there is no abstract rung left to snap.
|
|
25
|
+
* IT DELIBERATELY DOES NOT CHECK EFFORT AGAINST THE MODEL. That would require a
|
|
26
|
+
* table of model identifiers which this repository has no ground truth for.
|
|
27
|
+
* Harnesses may validate effort as a harness-wide property or pass it through;
|
|
28
|
+
* neither case establishes a per-model constraint. A table here would either
|
|
29
|
+
* restate `EFFORT_LADDER` under model-shaped keys or invent a restriction that
|
|
30
|
+
* rejects a valid operator config. A future per-harness check belongs on the
|
|
31
|
+
* adapter contract, not in this neutral shape module.
|
|
56
32
|
*/
|
|
57
33
|
/** Reasoning rungs the neutral start contract accepts, weakest to strongest. */
|
|
58
34
|
export declare const EFFORT_LADDER: readonly ["low", "medium", "high", "xhigh", "max"];
|
|
@@ -66,58 +42,64 @@ export type Effort = (typeof EFFORT_LADDER)[number];
|
|
|
66
42
|
export declare const MODIFIER_SEPARATOR = ":";
|
|
67
43
|
/** The bare capability name inside a composed capability. `wise:deep` → `wise`. */
|
|
68
44
|
export declare function capabilityNamePart(capability: string): string;
|
|
69
|
-
/** One
|
|
70
|
-
export interface
|
|
45
|
+
/** One ordered candidate in a crew roster row. */
|
|
46
|
+
export interface RosterCandidate {
|
|
47
|
+
harness: string;
|
|
71
48
|
model: string;
|
|
72
49
|
effort: string;
|
|
73
50
|
}
|
|
74
|
-
/**
|
|
75
|
-
export type
|
|
76
|
-
/** Thrown when the
|
|
77
|
-
export declare class
|
|
51
|
+
/** A crew roster keyed by composed capability (`wise:deep`) or bare name (`wise`). */
|
|
52
|
+
export type Roster = Readonly<Record<string, readonly RosterCandidate[]>>;
|
|
53
|
+
/** Thrown when the crew roster is unusable. Never silently repaired. */
|
|
54
|
+
export declare class RosterError extends Error {
|
|
78
55
|
}
|
|
79
56
|
/**
|
|
80
|
-
* Validate
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
* a missing or empty `model`, and an `effort` that is not one of
|
|
85
|
-
* `EFFORT_LADDER`. Each is wrong under every harness and every model, and a
|
|
86
|
-
* shift that started anyway would refuse or misroute its first matching order
|
|
87
|
-
* hours later, far from the typo.
|
|
57
|
+
* Validate a crew roster, throwing on the first unusable row. Every fault this
|
|
58
|
+
* function catches is certainly wrong: an empty capability, an old object row,
|
|
59
|
+
* an empty candidate list, or a candidate missing any required part would make
|
|
60
|
+
* routing ambiguous hours after the configuration mistake.
|
|
88
61
|
*
|
|
89
|
-
*
|
|
90
|
-
*
|
|
91
|
-
* header). FOLLOW-UP: `HarnessAdapter` is the right owner for the first one —
|
|
92
|
-
* an adapter that validates effort against a closed union could declare that
|
|
93
|
-
* union, and a composition root could check every row against every registered
|
|
94
|
-
* adapter at shift start. Until then those faults surface at the vendor API on
|
|
95
|
-
* the first order that lands on the bad row.
|
|
62
|
+
* It intentionally does not judge whether a model id exists or whether a
|
|
63
|
+
* particular model accepts an effort; see this module's header.
|
|
96
64
|
*/
|
|
97
|
-
export declare function
|
|
98
|
-
/** Which row served the order: its exact compound, or the bare name fallback. */
|
|
65
|
+
export declare function validateRoster(roster: Readonly<Record<string, unknown>>, ctx?: string): void;
|
|
66
|
+
/** Which roster row served the order: its exact compound, or the bare name fallback. */
|
|
99
67
|
export type CapabilityMatch = 'exact' | 'bare';
|
|
100
|
-
export interface
|
|
68
|
+
export interface CapabilityCandidates {
|
|
101
69
|
/** The capability the winning row was keyed by (`wise:deep` or `wise`). */
|
|
102
70
|
capability: string;
|
|
103
71
|
match: CapabilityMatch;
|
|
104
|
-
|
|
105
|
-
effort: string;
|
|
72
|
+
candidates: readonly RosterCandidate[];
|
|
106
73
|
}
|
|
107
74
|
/**
|
|
108
|
-
* Resolve an order's capabilities against the
|
|
109
|
-
* then the bare name-part row, else `undefined` (the caller
|
|
110
|
-
* never a default model).
|
|
75
|
+
* Resolve an order's capabilities against the merged roster: exact compound
|
|
76
|
+
* row first, then the bare name-part row, else `undefined` (the caller
|
|
77
|
+
* refuses the order — never a default model).
|
|
111
78
|
*
|
|
112
79
|
* TWO PASSES ACROSS ALL CAPABILITIES, NOT ONE PASS PER CAPABILITY. A step may
|
|
113
80
|
* author several capabilities, and the hub's claim gate is itself exact-first
|
|
114
|
-
* across the set
|
|
115
|
-
*
|
|
116
|
-
*
|
|
117
|
-
* bare `builder` grade purely because of authoring order.
|
|
81
|
+
* across the set. Resolving capability by capability instead would let a bare
|
|
82
|
+
* row on the first capability beat an exact row on the second — the shift
|
|
83
|
+
* would run a deep order at the bare grade purely because of authoring order.
|
|
118
84
|
*
|
|
119
|
-
* The bare row is what makes a
|
|
120
|
-
* hub
|
|
121
|
-
* then claims, and that shift has no `wise:deep` row by
|
|
85
|
+
* The bare row is what makes a name-match fallback order resolvable at all:
|
|
86
|
+
* the hub can stamp `wise:deep` on an order that a crew bound only to
|
|
87
|
+
* `wise:standard` then claims, and that shift has no `wise:deep` row by
|
|
88
|
+
* construction.
|
|
89
|
+
*/
|
|
90
|
+
export declare function resolveCapabilityCandidates(roster: Roster, capabilities: readonly string[]): CapabilityCandidates | undefined;
|
|
91
|
+
export type SelectionOutcome = {
|
|
92
|
+
kind: 'selected';
|
|
93
|
+
candidate: RosterCandidate;
|
|
94
|
+
} | {
|
|
95
|
+
kind: 'harness-policy';
|
|
96
|
+
offered: readonly string[];
|
|
97
|
+
} | {
|
|
98
|
+
kind: 'none-available';
|
|
99
|
+
offered: readonly string[];
|
|
100
|
+
};
|
|
101
|
+
/**
|
|
102
|
+
* Select the first usable candidate in roster order. A non-empty step harness
|
|
103
|
+
* is a policy constraint; it narrows candidates before availability is tested.
|
|
122
104
|
*/
|
|
123
|
-
export declare function
|
|
105
|
+
export declare function selectCandidate(candidates: readonly RosterCandidate[], stepHarness: string | undefined, isAvailable: (harnessId: string) => boolean): SelectionOutcome;
|