owenloop 0.5.22 → 0.5.24
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 +14 -0
- package/dist/packages/work/src/agent/brief.d.ts +16 -0
- package/dist/packages/work/src/agent/brief.js +23 -0
- package/dist/packages/work/src/agent/loop.d.ts +11 -1
- package/dist/packages/work/src/agent/loop.js +520 -8
- package/dist/packages/work/src/harness/claude.d.ts +43 -3
- package/dist/packages/work/src/harness/claude.js +520 -115
- package/dist/packages/work/src/harness/contract.d.ts +36 -1
- package/dist/packages/work/src/harness/contract.js +34 -0
- package/dist/packages/work/src/harness/gatekeeper.d.ts +21 -0
- package/dist/packages/work/src/harness/gatekeeper.js +55 -8
- package/dist/packages/work/src/harness/session-store.d.ts +18 -0
- package/dist/packages/work/src/harness/session-store.js +30 -1
- package/dist/packages/work/src/roles/agent-run.js +5 -1
- package/dist/packages/work/src/roles/sessions.d.ts +7 -0
- package/dist/packages/work/src/roles/sessions.js +56 -5
- package/docs/agent-runner.md +42 -3
- package/docs/cli.md +4 -0
- 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/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
|
@@ -85,6 +85,15 @@ export type AgentEvent = {
|
|
|
85
85
|
kind: 'needs_input';
|
|
86
86
|
question: string;
|
|
87
87
|
}
|
|
88
|
+
/**
|
|
89
|
+
* Sanitized liveness telemetry. It intentionally carries no provider event
|
|
90
|
+
* or response bytes: callers may persist it as recovery control state.
|
|
91
|
+
*/
|
|
92
|
+
| {
|
|
93
|
+
kind: 'activity';
|
|
94
|
+
at: number;
|
|
95
|
+
deadlineAt: number;
|
|
96
|
+
}
|
|
88
97
|
/** The model turn completed (the SDK result message on an in-process SDK
|
|
89
98
|
* path; `turn/completed` on an app-server path). */
|
|
90
99
|
| {
|
|
@@ -314,6 +323,8 @@ export interface StartArgs {
|
|
|
314
323
|
* behavior stands — that is a supported deployment, not a degraded one.
|
|
315
324
|
*/
|
|
316
325
|
approvals?: ApprovalRequester;
|
|
326
|
+
/** Optional, adapter-resolved provider-silence recovery policy for this firing. */
|
|
327
|
+
recoveryPolicy?: HarnessRecoveryPolicy;
|
|
317
328
|
}
|
|
318
329
|
/**
|
|
319
330
|
* Everything an adapter needs to RESUME an existing session with one message.
|
|
@@ -341,7 +352,25 @@ export interface StartArgs {
|
|
|
341
352
|
* happened to hold, and it must NOT fall back to a minimal option set on a map
|
|
342
353
|
* miss.
|
|
343
354
|
*/
|
|
344
|
-
export type DeliverArgs = Pick<StartArgs, 'cwd' | 'owenloopMcp' | 'permissions'> & Pick<StartArgs, 'model' | 'effort' | 'approvals'>;
|
|
355
|
+
export type DeliverArgs = Pick<StartArgs, 'cwd' | 'owenloopMcp' | 'permissions'> & Pick<StartArgs, 'model' | 'effort' | 'approvals' | 'recoveryPolicy'>;
|
|
356
|
+
/** The neutral part of an adapter's opt-in silence recovery configuration. */
|
|
357
|
+
export interface HarnessRecoveryPolicy {
|
|
358
|
+
/** Maximum interval with no raw provider message before a turn is interrupted. */
|
|
359
|
+
idleTimeoutMs: number;
|
|
360
|
+
}
|
|
361
|
+
export declare const HARNESS_FAILURE_CATEGORIES: readonly ["idle-timeout", "authentication", "permission-policy", "model-unavailable", "configuration", "provider"];
|
|
362
|
+
export type HarnessFailureCategory = (typeof HARNESS_FAILURE_CATEGORIES)[number];
|
|
363
|
+
/** A structured adapter failure whose category is safe to persist and render. */
|
|
364
|
+
export declare class HarnessTurnError extends Error {
|
|
365
|
+
readonly category: HarnessFailureCategory;
|
|
366
|
+
readonly terminal: boolean;
|
|
367
|
+
constructor(category: HarnessFailureCategory, terminal: boolean, message: string);
|
|
368
|
+
}
|
|
369
|
+
/** Provider silence while a recovery-enabled turn was awaiting a raw message. */
|
|
370
|
+
export declare class HarnessIdleTimeoutError extends HarnessTurnError {
|
|
371
|
+
constructor(idleTimeoutMs: number);
|
|
372
|
+
}
|
|
373
|
+
export declare function isHarnessTurnError(err: unknown): err is HarnessTurnError;
|
|
345
374
|
/**
|
|
346
375
|
* One harness implementation.
|
|
347
376
|
*
|
|
@@ -369,6 +398,12 @@ export interface HarnessAdapter {
|
|
|
369
398
|
/** Registry key — the adapter's own harness id. Stable across versions. */
|
|
370
399
|
id: string;
|
|
371
400
|
resumeTier: ResumeTier;
|
|
401
|
+
/**
|
|
402
|
+
* Reads and validates adapter-owned recovery configuration. The worker calls
|
|
403
|
+
* it exactly once per firing and passes the resulting neutral policy back to
|
|
404
|
+
* every provider dispatch.
|
|
405
|
+
*/
|
|
406
|
+
recoveryPolicy?(): HarnessRecoveryPolicy | undefined;
|
|
372
407
|
/**
|
|
373
408
|
* Mandatory permission preflight. Returns every restriction this adapter cannot
|
|
374
409
|
* enforce exactly. The worker calls this before start or resume; a non-empty
|
|
@@ -78,6 +78,40 @@ export const NEUTRAL_PERMISSION_MODES = Object.freeze([
|
|
|
78
78
|
export function isNeutralPermissionMode(value) {
|
|
79
79
|
return NEUTRAL_PERMISSION_MODES.includes(value);
|
|
80
80
|
}
|
|
81
|
+
export const HARNESS_FAILURE_CATEGORIES = [
|
|
82
|
+
'idle-timeout',
|
|
83
|
+
'authentication',
|
|
84
|
+
'permission-policy',
|
|
85
|
+
'model-unavailable',
|
|
86
|
+
'configuration',
|
|
87
|
+
'provider',
|
|
88
|
+
];
|
|
89
|
+
/** A structured adapter failure whose category is safe to persist and render. */
|
|
90
|
+
export class HarnessTurnError extends Error {
|
|
91
|
+
category;
|
|
92
|
+
terminal;
|
|
93
|
+
constructor(category, terminal, message) {
|
|
94
|
+
super(message);
|
|
95
|
+
this.name = 'HarnessTurnError';
|
|
96
|
+
this.category = category;
|
|
97
|
+
this.terminal = terminal;
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
/** Provider silence while a recovery-enabled turn was awaiting a raw message. */
|
|
101
|
+
export class HarnessIdleTimeoutError extends HarnessTurnError {
|
|
102
|
+
constructor(idleTimeoutMs) {
|
|
103
|
+
super('idle-timeout', false, `provider emitted no SDK message for ${idleTimeoutMs}ms`);
|
|
104
|
+
this.name = 'HarnessIdleTimeoutError';
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
export function isHarnessTurnError(err) {
|
|
108
|
+
if (typeof err !== 'object' || err === null)
|
|
109
|
+
return false;
|
|
110
|
+
const candidate = err;
|
|
111
|
+
return (typeof candidate.category === 'string' &&
|
|
112
|
+
HARNESS_FAILURE_CATEGORIES.includes(candidate.category) &&
|
|
113
|
+
typeof candidate.terminal === 'boolean');
|
|
114
|
+
}
|
|
81
115
|
/** The `code` every `ResumeUnavailableError` carries. Match on THIS, not on the class. */
|
|
82
116
|
export const RESUME_UNAVAILABLE = 'RESUME_UNAVAILABLE';
|
|
83
117
|
/**
|
|
@@ -94,6 +94,13 @@ export interface GateCall {
|
|
|
94
94
|
* `unrestricted` declaration may widen audited filesystem reads only.
|
|
95
95
|
*/
|
|
96
96
|
filesystem?: FilesystemPermission;
|
|
97
|
+
/**
|
|
98
|
+
* The host-owned exact-work-root boundary. This is deliberately separate from
|
|
99
|
+
* an authored filesystem permission: the latter may describe an unrestricted
|
|
100
|
+
* legacy workflow, while this flag is the narrow audit profile that must never
|
|
101
|
+
* be widened by an approval or an SDK shortcut.
|
|
102
|
+
*/
|
|
103
|
+
exactWorkdir?: boolean;
|
|
97
104
|
}
|
|
98
105
|
/** The gatekeeper's answer. `reason` is written to be shown to a person and to
|
|
99
106
|
* the agent, so it names the specific thing that triggered it. */
|
|
@@ -102,12 +109,26 @@ export type GateVerdict = {
|
|
|
102
109
|
} | {
|
|
103
110
|
decision: 'escalate';
|
|
104
111
|
reason: string;
|
|
112
|
+
} | {
|
|
113
|
+
decision: 'deny';
|
|
114
|
+
reason: string;
|
|
105
115
|
};
|
|
106
116
|
/** Audited built-ins that cannot mutate the filesystem. WebFetch/WebSearch
|
|
107
117
|
* can read the unrestricted network without weakening a read-only filesystem.
|
|
108
118
|
* This is the canonical audited read-tool set used by both the adapter's tool
|
|
109
119
|
* surface and the explicit unrestricted-filesystem containment exception. */
|
|
110
120
|
export declare const READ_ONLY_TOOLS: ReadonlySet<string>;
|
|
121
|
+
/** The path-bearing built-ins, derived from the same metadata as extraction. */
|
|
122
|
+
export declare const PATH_BEARING_TOOL_NAMES: ReadonlySet<string>;
|
|
123
|
+
/** Fixed, payload-free guidance for the exact audit boundary. */
|
|
124
|
+
export declare const EXACT_WORKDIR_DENIAL_MESSAGE = "The exact work-root policy denied this path-bearing tool call. Work inside the assigned directory, or call the born-bound `ask` tool on the mounted `owenloop` MCP server if the order cannot be completed there.";
|
|
125
|
+
/**
|
|
126
|
+
* Classify a path-bearing call for the host-controlled exact-work-root policy.
|
|
127
|
+
* It deliberately catches model-authored getters/Proxies and path-normalization
|
|
128
|
+
* errors so an unexpected input cannot make a hook throw and leave the SDK
|
|
129
|
+
* waiting for a response.
|
|
130
|
+
*/
|
|
131
|
+
export declare function classifyExactWorkdirPath(call: GateCall): GateVerdict;
|
|
111
132
|
/**
|
|
112
133
|
* Whether `candidate` resolves inside `root`.
|
|
113
134
|
*
|
|
@@ -63,14 +63,20 @@ export const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebFetch', 'Web
|
|
|
63
63
|
* guessed at.
|
|
64
64
|
*/
|
|
65
65
|
const PATH_ARGS = Object.freeze({
|
|
66
|
-
Read: { args: ['file_path'], humanGateSafeRead: true },
|
|
67
|
-
Write: { args: ['file_path'] },
|
|
68
|
-
Edit: { args: ['file_path'] },
|
|
69
|
-
NotebookRead: { args: ['notebook_path'], humanGateSafeRead: true },
|
|
70
|
-
NotebookEdit: { args: ['notebook_path'] },
|
|
71
|
-
Glob
|
|
72
|
-
|
|
66
|
+
Read: { args: [{ key: 'file_path' }], humanGateSafeRead: true },
|
|
67
|
+
Write: { args: [{ key: 'file_path' }] },
|
|
68
|
+
Edit: { args: [{ key: 'file_path' }] },
|
|
69
|
+
NotebookRead: { args: [{ key: 'notebook_path' }], humanGateSafeRead: true },
|
|
70
|
+
NotebookEdit: { args: [{ key: 'notebook_path' }] },
|
|
71
|
+
// Glob/Grep schemas deliberately default an omitted path to cwd.
|
|
72
|
+
// Empty, non-string, or inaccessible values are NOT that omission.
|
|
73
|
+
Glob: { args: [{ key: 'path', optional: true }], humanGateSafeRead: true },
|
|
74
|
+
Grep: { args: [{ key: 'path', optional: true }], humanGateSafeRead: true },
|
|
73
75
|
});
|
|
76
|
+
/** The path-bearing built-ins, derived from the same metadata as extraction. */
|
|
77
|
+
export const PATH_BEARING_TOOL_NAMES = new Set(Object.keys(PATH_ARGS));
|
|
78
|
+
/** Fixed, payload-free guidance for the exact audit boundary. */
|
|
79
|
+
export const EXACT_WORKDIR_DENIAL_MESSAGE = 'The exact work-root policy denied this path-bearing tool call. Work inside the assigned directory, or call the born-bound `ask` tool on the mounted `owenloop` MCP server if the order cannot be completed there.';
|
|
74
80
|
/**
|
|
75
81
|
* The owenloop MCP mount, which is ALWAYS allowed under every policy.
|
|
76
82
|
*
|
|
@@ -121,6 +127,40 @@ function stringArg(input, key) {
|
|
|
121
127
|
const v = input[key];
|
|
122
128
|
return typeof v === 'string' && v !== '' ? v : undefined;
|
|
123
129
|
}
|
|
130
|
+
/**
|
|
131
|
+
* Classify a path-bearing call for the host-controlled exact-work-root policy.
|
|
132
|
+
* It deliberately catches model-authored getters/Proxies and path-normalization
|
|
133
|
+
* errors so an unexpected input cannot make a hook throw and leave the SDK
|
|
134
|
+
* waiting for a response.
|
|
135
|
+
*/
|
|
136
|
+
export function classifyExactWorkdirPath(call) {
|
|
137
|
+
const spec = PATH_ARGS[call.toolName];
|
|
138
|
+
if (spec === undefined)
|
|
139
|
+
return ALLOW;
|
|
140
|
+
try {
|
|
141
|
+
if (call.blockedPath !== undefined && call.blockedPath !== '') {
|
|
142
|
+
return { decision: 'deny', reason: EXACT_WORKDIR_DENIAL_MESSAGE };
|
|
143
|
+
}
|
|
144
|
+
for (const arg of spec.args) {
|
|
145
|
+
const present = Object.prototype.hasOwnProperty.call(call.input, arg.key);
|
|
146
|
+
if (!present && arg.optional === true)
|
|
147
|
+
continue;
|
|
148
|
+
if (!present)
|
|
149
|
+
return { decision: 'deny', reason: EXACT_WORKDIR_DENIAL_MESSAGE };
|
|
150
|
+
const value = call.input[arg.key];
|
|
151
|
+
if (typeof value !== 'string' || value === '') {
|
|
152
|
+
return { decision: 'deny', reason: EXACT_WORKDIR_DENIAL_MESSAGE };
|
|
153
|
+
}
|
|
154
|
+
if (!isInside(call.workdir, value)) {
|
|
155
|
+
return { decision: 'deny', reason: EXACT_WORKDIR_DENIAL_MESSAGE };
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
return ALLOW;
|
|
159
|
+
}
|
|
160
|
+
catch {
|
|
161
|
+
return { decision: 'deny', reason: EXACT_WORKDIR_DENIAL_MESSAGE };
|
|
162
|
+
}
|
|
163
|
+
}
|
|
124
164
|
/**
|
|
125
165
|
* Whether `candidate` resolves inside `root`.
|
|
126
166
|
*
|
|
@@ -166,6 +206,13 @@ export function dangerousCommand(command) {
|
|
|
166
206
|
export function classifyToolCall(call, policy) {
|
|
167
207
|
if (call.toolName.startsWith(OWENLOOP_MCP_PREFIX))
|
|
168
208
|
return ALLOW;
|
|
209
|
+
// This host profile runs before legacy policy semantics. It is intentionally
|
|
210
|
+
// not an escalation: no human approval can widen the exact snapshot boundary.
|
|
211
|
+
if (call.exactWorkdir === true) {
|
|
212
|
+
const exact = classifyExactWorkdirPath(call);
|
|
213
|
+
if (exact.decision === 'deny')
|
|
214
|
+
return exact;
|
|
215
|
+
}
|
|
169
216
|
if (policy === 'deny-unapproved') {
|
|
170
217
|
return { decision: 'escalate', reason: `permissionMode denies unapproved tool calls` };
|
|
171
218
|
}
|
|
@@ -178,7 +225,7 @@ export function classifyToolCall(call, policy) {
|
|
|
178
225
|
}
|
|
179
226
|
const pathArgs = PATH_ARGS[call.toolName];
|
|
180
227
|
const paths = (pathArgs?.args ?? [])
|
|
181
|
-
.map((key) => stringArg(call.input, key))
|
|
228
|
+
.map(({ key }) => stringArg(call.input, key))
|
|
182
229
|
.filter((p) => p !== undefined);
|
|
183
230
|
// An explicit unrestricted filesystem declaration widens only the declared
|
|
184
231
|
// boundary of the shared audited read set. It does not change which operation
|
|
@@ -1,6 +1,22 @@
|
|
|
1
|
+
import type { HarnessFailureCategory } from './contract.ts';
|
|
1
2
|
import { type Liveness } from '../shift/state.ts';
|
|
2
3
|
/** Where a step attempt is in its life. */
|
|
3
4
|
export type SessionStatus = 'active' | 'turn-ended' | 'submitted' | 'dead';
|
|
5
|
+
export type RecoveryPhase = 'primary' | 'wake' | 'cold-restart' | 'held';
|
|
6
|
+
/** Fsynced, sanitized control state for a recovery-enabled turn. */
|
|
7
|
+
export interface RecoveryCheckpoint {
|
|
8
|
+
generation: string;
|
|
9
|
+
phase: RecoveryPhase;
|
|
10
|
+
wakeUsed: boolean;
|
|
11
|
+
coldRestartUsed: boolean;
|
|
12
|
+
phaseStartedAt?: number;
|
|
13
|
+
lastActivityAt?: number;
|
|
14
|
+
deadlineAt?: number;
|
|
15
|
+
lastFailure?: {
|
|
16
|
+
category: HarnessFailureCategory;
|
|
17
|
+
at: number;
|
|
18
|
+
};
|
|
19
|
+
}
|
|
4
20
|
/** One line of `sessions.jsonl`. */
|
|
5
21
|
export interface SessionRecord {
|
|
6
22
|
workflow: string;
|
|
@@ -62,6 +78,8 @@ export interface SessionRecord {
|
|
|
62
78
|
* `attempt` stays outside it, per Phase 1.
|
|
63
79
|
*/
|
|
64
80
|
deliveredReasonAt?: number;
|
|
81
|
+
/** Present only for opt-in recovery; never contains a prompt, token, or SDK payload. */
|
|
82
|
+
recovery?: RecoveryCheckpoint;
|
|
65
83
|
updatedAt: number;
|
|
66
84
|
}
|
|
67
85
|
export interface SessionStoreOptions {
|
|
@@ -154,6 +154,35 @@ function firstInvalidSessionRecordField(v) {
|
|
|
154
154
|
return 'key';
|
|
155
155
|
if (typeof r['status'] !== 'string' || !STATUSES.has(r['status']))
|
|
156
156
|
return 'status';
|
|
157
|
+
if (r['recovery'] !== undefined) {
|
|
158
|
+
if (typeof r['recovery'] !== 'object' || r['recovery'] === null || Array.isArray(r['recovery']))
|
|
159
|
+
return 'recovery';
|
|
160
|
+
const recovery = r['recovery'];
|
|
161
|
+
if (!isNonEmptyString(recovery['generation']))
|
|
162
|
+
return 'recovery.generation';
|
|
163
|
+
if (!['primary', 'wake', 'cold-restart', 'held'].includes(recovery['phase']))
|
|
164
|
+
return 'recovery.phase';
|
|
165
|
+
if (typeof recovery['wakeUsed'] !== 'boolean')
|
|
166
|
+
return 'recovery.wakeUsed';
|
|
167
|
+
if (typeof recovery['coldRestartUsed'] !== 'boolean')
|
|
168
|
+
return 'recovery.coldRestartUsed';
|
|
169
|
+
for (const field of ['phaseStartedAt', 'lastActivityAt', 'deadlineAt']) {
|
|
170
|
+
if (recovery[field] !== undefined && (!Number.isFinite(recovery[field]) || recovery[field] < 0)) {
|
|
171
|
+
return `recovery.${field}`;
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
if (recovery['lastFailure'] !== undefined) {
|
|
175
|
+
if (typeof recovery['lastFailure'] !== 'object' || recovery['lastFailure'] === null || Array.isArray(recovery['lastFailure'])) {
|
|
176
|
+
return 'recovery.lastFailure';
|
|
177
|
+
}
|
|
178
|
+
const failure = recovery['lastFailure'];
|
|
179
|
+
if (!['idle-timeout', 'authentication', 'permission-policy', 'model-unavailable', 'configuration', 'provider'].includes(failure['category'])) {
|
|
180
|
+
return 'recovery.lastFailure.category';
|
|
181
|
+
}
|
|
182
|
+
if (!Number.isFinite(failure['at']) || failure['at'] < 0)
|
|
183
|
+
return 'recovery.lastFailure.at';
|
|
184
|
+
}
|
|
185
|
+
}
|
|
157
186
|
return null;
|
|
158
187
|
}
|
|
159
188
|
/**
|
|
@@ -459,7 +488,7 @@ function appendSessionUnlocked(file, rec, opts) {
|
|
|
459
488
|
let failure;
|
|
460
489
|
try {
|
|
461
490
|
writeFileSync(fd, `${separator}${JSON.stringify(rec)}\n`);
|
|
462
|
-
if (rec.status === 'active') {
|
|
491
|
+
if (rec.status === 'active' || rec.recovery !== undefined) {
|
|
463
492
|
const sync = opts.sync ?? fsyncSync;
|
|
464
493
|
sync(fd);
|
|
465
494
|
if (!existed)
|
|
@@ -98,7 +98,7 @@ import { effectiveRosterLayers, mergeRosterLayers } from "../settings/roster.js"
|
|
|
98
98
|
import { adapterFor, defaultHarnessId, registeredHarnessIds } from "../harness/registry.js";
|
|
99
99
|
import { parseHarnessCarrier } from "../bundle/fetch.js";
|
|
100
100
|
import { normalizeStepPermissions, validateHarnessOptions } from "../harness/permissions.js";
|
|
101
|
-
import { appendSession, latestForTask, sessionsPath, } from "../harness/session-store.js";
|
|
101
|
+
import { appendSession, latestFor, latestForTask, sessionsPath, } from "../harness/session-store.js";
|
|
102
102
|
import { ensureWorkDir, resolveAllowedWorkdirRoots, resolveWorkRepo, resolveWorkRoot, } from "../agent/workdir.js";
|
|
103
103
|
import { resolveShiftId, resolveTarget } from "./hold.js";
|
|
104
104
|
import { installSignalHandlers } from "./signals.js";
|
|
@@ -194,6 +194,7 @@ export function exitCodeFor(outcome) {
|
|
|
194
194
|
switch (outcome) {
|
|
195
195
|
case 'submitted':
|
|
196
196
|
case 'completed':
|
|
197
|
+
case 'held':
|
|
197
198
|
return 0;
|
|
198
199
|
case 'misroute':
|
|
199
200
|
case 'workdir-denied':
|
|
@@ -550,6 +551,9 @@ export async function run(args, deps = {}) {
|
|
|
550
551
|
// PHASE 4: the same reader `nextAttempt` uses, handed to the loop whole so
|
|
551
552
|
// it can decide resume vs cold replay. Reads only; the loop is what writes.
|
|
552
553
|
latestSession: (task) => latestForTask(sessionsFile, task),
|
|
554
|
+
// Recovery consumption belongs to this concrete hub run. A human retry
|
|
555
|
+
// gets a fresh run id and therefore a fresh bounded recovery budget.
|
|
556
|
+
latestRunSession: (workflow, run, step) => latestFor(sessionsFile, workflow, run, step),
|
|
553
557
|
sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
|
|
554
558
|
now: () => Date.now(),
|
|
555
559
|
out,
|
|
@@ -56,6 +56,13 @@ export declare function formatAge(ms: number): string;
|
|
|
56
56
|
* LISTING — one bad row must not take down the other rows with it.
|
|
57
57
|
*/
|
|
58
58
|
export declare function resumeCommandFor(rec: SessionRecord): string | undefined;
|
|
59
|
+
/**
|
|
60
|
+
* Recovery records use an explicit allowlist, unlike legacy local-resume rows.
|
|
61
|
+
* The JSONL reader intentionally preserves forward fields, so exclusion-based
|
|
62
|
+
* redaction would disclose any future/stray prompt, credential, config, token,
|
|
63
|
+
* or failure-prose field that reached the machine-local store.
|
|
64
|
+
*/
|
|
65
|
+
export declare function projectSession(rec: SessionRecord): SessionRecord | Record<string, unknown>;
|
|
59
66
|
/** Render the table. Exported for the unit test; `run` does the I/O. */
|
|
60
67
|
export declare function renderTable(records: readonly SessionRecord[], now: number): string;
|
|
61
68
|
export declare function run(args: string[]): Promise<number>;
|
|
@@ -107,6 +107,10 @@ function shellQuote(s) {
|
|
|
107
107
|
* LISTING — one bad row must not take down the other rows with it.
|
|
108
108
|
*/
|
|
109
109
|
export function resumeCommandFor(rec) {
|
|
110
|
+
// Recovery control rows are intentionally safe to show to an operator or a
|
|
111
|
+
// script. A provider token would make that guarantee false.
|
|
112
|
+
if (rec.recovery !== undefined)
|
|
113
|
+
return undefined;
|
|
110
114
|
// An empty token is a real, readable record: the worker writes one before the
|
|
111
115
|
// harness emits `started`, so a launch that died still leaves proof it existed.
|
|
112
116
|
// Handing that empty string to `resumeCommand` would print a command that
|
|
@@ -124,6 +128,53 @@ export function resumeCommandFor(rec) {
|
|
|
124
128
|
return undefined;
|
|
125
129
|
}
|
|
126
130
|
}
|
|
131
|
+
function recoverySummary(rec) {
|
|
132
|
+
const state = rec.recovery;
|
|
133
|
+
if (state === undefined)
|
|
134
|
+
return '—';
|
|
135
|
+
const activity = state.lastActivityAt ?? state.deadlineAt;
|
|
136
|
+
return [
|
|
137
|
+
state.phase === 'held' ? 'held: action required' : state.phase,
|
|
138
|
+
`wake=${state.wakeUsed ? 'yes' : 'no'}`,
|
|
139
|
+
`cold=${state.coldRestartUsed ? 'yes' : 'no'}`,
|
|
140
|
+
...(activity !== undefined ? [`at=${activity}`] : []),
|
|
141
|
+
...(state.lastFailure !== undefined ? [`failure=${state.lastFailure.category}`] : []),
|
|
142
|
+
].join(', ');
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* Recovery records use an explicit allowlist, unlike legacy local-resume rows.
|
|
146
|
+
* The JSONL reader intentionally preserves forward fields, so exclusion-based
|
|
147
|
+
* redaction would disclose any future/stray prompt, credential, config, token,
|
|
148
|
+
* or failure-prose field that reached the machine-local store.
|
|
149
|
+
*/
|
|
150
|
+
export function projectSession(rec) {
|
|
151
|
+
if (rec.recovery === undefined)
|
|
152
|
+
return rec;
|
|
153
|
+
const state = rec.recovery;
|
|
154
|
+
return {
|
|
155
|
+
workflow: rec.workflow,
|
|
156
|
+
run: rec.run,
|
|
157
|
+
step: rec.step,
|
|
158
|
+
order: rec.order,
|
|
159
|
+
...(rec.key !== undefined ? { key: rec.key } : {}),
|
|
160
|
+
attempt: rec.attempt,
|
|
161
|
+
harness: rec.harness,
|
|
162
|
+
status: rec.status,
|
|
163
|
+
createdAt: rec.createdAt,
|
|
164
|
+
...(rec.deliveredReasonAt !== undefined ? { deliveredReasonAt: rec.deliveredReasonAt } : {}),
|
|
165
|
+
updatedAt: rec.updatedAt,
|
|
166
|
+
recovery: {
|
|
167
|
+
generation: state.generation,
|
|
168
|
+
phase: state.phase,
|
|
169
|
+
wakeUsed: state.wakeUsed,
|
|
170
|
+
coldRestartUsed: state.coldRestartUsed,
|
|
171
|
+
...(state.phaseStartedAt !== undefined ? { phaseStartedAt: state.phaseStartedAt } : {}),
|
|
172
|
+
...(state.lastActivityAt !== undefined ? { lastActivityAt: state.lastActivityAt } : {}),
|
|
173
|
+
...(state.deadlineAt !== undefined ? { deadlineAt: state.deadlineAt } : {}),
|
|
174
|
+
...(state.lastFailure !== undefined ? { lastFailure: { category: state.lastFailure.category, at: state.lastFailure.at } } : {}),
|
|
175
|
+
},
|
|
176
|
+
};
|
|
177
|
+
}
|
|
127
178
|
/** Render the table. Exported for the unit test; `run` does the I/O. */
|
|
128
179
|
export function renderTable(records, now) {
|
|
129
180
|
const rows = records.map((rec) => [
|
|
@@ -133,9 +184,10 @@ export function renderTable(records, now) {
|
|
|
133
184
|
rec.status,
|
|
134
185
|
String(rec.attempt),
|
|
135
186
|
formatAge(now - rec.updatedAt),
|
|
187
|
+
recoverySummary(rec),
|
|
136
188
|
resumeCommandFor(rec) ?? '—',
|
|
137
189
|
]);
|
|
138
|
-
const header = ['ORDER', 'STEP', 'HARNESS', 'STATUS', 'ATTEMPT', 'AGE', 'RESUME'];
|
|
190
|
+
const header = ['ORDER', 'STEP', 'HARNESS', 'STATUS', 'ATTEMPT', 'AGE', 'RECOVERY', 'RESUME'];
|
|
139
191
|
const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)));
|
|
140
192
|
// The last column is not padded: trailing spaces on a command an operator is
|
|
141
193
|
// about to copy are noise, and a resume command can be long.
|
|
@@ -170,10 +222,9 @@ export async function run(args) {
|
|
|
170
222
|
// one that just failed.
|
|
171
223
|
visible.sort((a, b) => b.updatedAt - a.updatedAt);
|
|
172
224
|
if (parsed.json) {
|
|
173
|
-
//
|
|
174
|
-
//
|
|
175
|
-
|
|
176
|
-
process.stdout.write(`${JSON.stringify(visible, null, 2)}\n`);
|
|
225
|
+
// Legacy records remain raw for established local-resume scripts. Opt-in
|
|
226
|
+
// recovery rows are a deliberately redacted projection.
|
|
227
|
+
process.stdout.write(`${JSON.stringify(visible.map(projectSession), null, 2)}\n`);
|
|
177
228
|
return 0;
|
|
178
229
|
}
|
|
179
230
|
if (visible.length === 0) {
|
package/docs/agent-runner.md
CHANGED
|
@@ -123,16 +123,55 @@ The Claude Code adapter refuses a `read-only` allow-list containing anything out
|
|
|
123
123
|
|
|
124
124
|
## Owenloop control-plane exception
|
|
125
125
|
|
|
126
|
-
`network: owenloop-only` means that the Step Agent may reach only the born-bound Owenloop MCP control plane for the held order. The exception exists so the Step Agent can call `get_order` and `
|
|
126
|
+
`network: owenloop-only` means that the Step Agent may reach only the born-bound Owenloop MCP control plane for the held order. The exception exists so the Step Agent can call `get_order`, `submit`, and `ask`; without those calls the Step Agent cannot inspect, complete, or honestly hold an impossible order.
|
|
127
127
|
|
|
128
|
-
For Claude Code isolation, the adapter sets `settingSources: []`, `strictMcpConfig: true`, disables skills, excludes hooks and external MCP servers, and mounts only the worker-created `owenloop` MCP server. The restricted MCP child positively registers exactly `get_order` and `
|
|
128
|
+
For Claude Code isolation, the adapter sets `settingSources: []`, `strictMcpConfig: true`, disables skills, excludes hooks and external MCP servers, and mounts only the worker-created `owenloop` MCP server. The restricted MCP child positively registers exactly `get_order`, `submit`, and `ask`; the restricted MCP child does not register `reject`. A future work-holder tool therefore does not enter restricted sessions unless the adapter explicitly adds the tool to the positive registration list. The adapter also restricts built-in tools to an audited no-network set. The same option construction runs for cold start and resume.
|
|
129
129
|
|
|
130
|
-
The born-bound Owenloop MCP server is created by the worker from the live workflow, run, origin, account, Shift, and held claim. Workflow extension data cannot replace that mount. During isolation, the adapter adds `mcp__owenloop__get_order` and `
|
|
130
|
+
The born-bound Owenloop MCP server is created by the worker from the live workflow, run, origin, account, Shift, and held claim. Workflow extension data cannot replace that mount. During isolation, the adapter adds `mcp__owenloop__get_order`, `mcp__owenloop__submit`, and `mcp__owenloop__ask` to `allowedTools` so those control calls execute without an unattended permission prompt. `allowedTools` controls permission automation; `allowedTools` does not filter the MCP server's `tools/list` response. The positive registration list on the MCP child is the visibility boundary. The adapter also adds `mcp__owenloop__reject` to `disallowedTools` as defense in depth. A direct deny or an MCP wildcard deny that blocks Owenloop `get_order`, `submit`, or `ask` is refused.
|
|
131
131
|
|
|
132
132
|
Outside Claude Code isolation, the default work-holder MCP child continues to register `get_order`, `submit`, and `reject`.
|
|
133
133
|
|
|
134
134
|
## Security boundary
|
|
135
135
|
|
|
136
|
+
### Claude exact work root
|
|
137
|
+
|
|
138
|
+
A dedicated audit Shift may enable `OWENLOOP_CLAUDE_EXACT_WORKDIR=1` in the
|
|
139
|
+
host environment. It is a host-only setting: it is removed before the Claude
|
|
140
|
+
child is launched and is not carried in prompts, events, provider options, or
|
|
141
|
+
durable session records. Absence leaves existing workflows unchanged; any other
|
|
142
|
+
present value fails configuration before a provider query starts.
|
|
143
|
+
|
|
144
|
+
This profile requires an explicit or derived built-in surface containing only
|
|
145
|
+
`Read`, `Glob`, and `Grep` (an explicit `tools: []` remains valid). It forces
|
|
146
|
+
the same isolated settings/MCP/skills profile described above, rejects an
|
|
147
|
+
incompatible authored surface rather than silently filtering it, and keeps the
|
|
148
|
+
born-bound `get_order`, `submit`, and `ask` controls headless.
|
|
149
|
+
|
|
150
|
+
Every path-bearing built-in is intercepted by a host-owned `PreToolUse` guard
|
|
151
|
+
before the SDK's bare `allowedTools` approval can run. A well-formed lexical
|
|
152
|
+
path inside the exact step directory proceeds headlessly. Outside, malformed,
|
|
153
|
+
or SDK-blocked paths are final fixed-message denials: they never create a human
|
|
154
|
+
tool approval, and the agent must work inside the directory or use `ask` when
|
|
155
|
+
the order is impossible there. The callback retains the same final-deny check
|
|
156
|
+
as defense in depth.
|
|
157
|
+
|
|
158
|
+
For a configured model, both cold and resumed strict turns require the provider
|
|
159
|
+
to confirm the identical literal model name. Missing identity, a different
|
|
160
|
+
model, an unavailable model, or a structured fallback event fails the turn
|
|
161
|
+
instead of accepting a substitute. No fallback model is configured.
|
|
162
|
+
|
|
163
|
+
The boundary is lexical containment only; it does not claim to defeat symlinks
|
|
164
|
+
or special files. Snapshot construction remains responsible for those separate
|
|
165
|
+
checks.
|
|
166
|
+
|
|
136
167
|
`x.harness` permission fields are enforced policy. Adapter preflight must prove that the selected adapter can implement each authored restriction exactly; unsupported policy fails closed.
|
|
137
168
|
|
|
138
169
|
`advisory.tools` is model guidance only. `advisory.tools` does not configure an adapter, does not remove a provider tool, and is not a security boundary.
|
|
170
|
+
|
|
171
|
+
## Claude SDK idle recovery
|
|
172
|
+
|
|
173
|
+
`OWENLOOP_CLAUDE_IDLE_TIMEOUT_MS` is an opt-in, host-only Claude Code setting. It accepts a canonical decimal duration from `1000` through `3600000` milliseconds; a present invalid value is a typed configuration failure before the model is started. The pilot value is `600000` (ten minutes). The setting is deliberately not passed to the SDK child environment.
|
|
174
|
+
|
|
175
|
+
When enabled, the timer measures silence between raw SDK messages, including partial stream events, rather than total turn time. Recovery logs contain only local lifecycle lines, typed failure categories, and sanitized timestamps: provider session ids, cwd, stderr, result/init prose, assistant/user payloads, and partial events are suppressed. Recovery applies only when the order has exactly one non-empty owed output: it permits a primary turn, one same-session wake, and one cold replay. A submit or other hub outcome wins every race. Authentication, permission-policy, model-unavailable, and configuration failures go straight to a producer-side `ask`; exhausted recovery also holds through `ask` rather than releasing the debt.
|
|
176
|
+
|
|
177
|
+
Phase and consumed wake/cold flags are fsynced before dispatch. A crash may therefore skip a phase but cannot duplicate it; re-dispatch of the same run reads the same checkpoint. A human retry has a new run id and a fresh budget. Once the hub confirms submission or claim loss, the worker stops its lease before provider cleanup; recovery cleanup is best-effort and bounded to five seconds, so a stuck adapter cannot keep heartbeats or ownership semantics alive. `work sessions` shows phase, flags, activity/deadline and typed category for recovery rows, identifies `held` as requiring human action, and redacts the provider token/resume command in both table and JSON output. Start and resume retain the dedicated `CLAUDE_CONFIG_DIR` and `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` isolation environment.
|
package/docs/cli.md
CHANGED
|
@@ -3623,6 +3623,10 @@ child's `eligible` orders or wait on child completion. To block on a tree, wait
|
|
|
3623
3623
|
on the instance that actually owes the work (often a child), or poll deep
|
|
3624
3624
|
`tick`/`status` yourself.
|
|
3625
3625
|
|
|
3626
|
+
## Claude idle-recovery status
|
|
3627
|
+
|
|
3628
|
+
For a Shift intentionally using `OWENLOOP_CLAUDE_IDLE_TIMEOUT_MS=600000`, `owenloop work sessions` reports recovery phase (`primary`, `wake`, `cold-restart`, or `held`), wake/cold usage, durable activity/deadline, and typed failure category. `held: action required` means the worker has called the normal producer-side `ask` after an exhausted recovery budget or a terminal/configuration failure; answer/retry the held artifact in the usual way. Recovery applies only to an order with exactly one non-empty owed output. Recovery-enabled rows omit provider tokens and do not print a `RESUME` command; recovery worker logs likewise suppress provider session ids, cwd, stderr, result/init prose, and SDK payloads. The setting is host-only, must be a canonical decimal duration between 1000 and 3600000 ms, and is never copied into the agent child environment.
|
|
3629
|
+
|
|
3626
3630
|
## Instance pinning — editing a workflow definition mid-flight
|
|
3627
3631
|
|
|
3628
3632
|
`create` snapshots the fully-expanded definition (post `include:`/`calls:`) onto the
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "owenloop",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.24",
|
|
4
4
|
"description": "Deterministic rails for agentic workflows. Declare steps and dependencies; the engine guarantees order, redoes what changes invalidate, and stops what keeps failing — instead of hoping the agent follows through.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "typicalday",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "owenloop",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.24",
|
|
4
4
|
"description": "Claude Code driver for owenloop — cross-harness shift and conduct skills driven by the owenloop CLI, plus one hub control-plane MCP server backing an author skill and a fallback worker, for conducting and authoring workflows against your hosted owenloop server.",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Typical Day"
|