owenloop 0.5.22 → 0.5.23

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.
@@ -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
  /**
@@ -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
- // The RAW records, tokens included. This is machine-local data an operator
174
- // already owns, and withholding the token would make the output useless for
175
- // exactly the scripting this flag exists for.
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) {
@@ -136,3 +136,11 @@ Outside Claude Code isolation, the default work-holder MCP child continues to re
136
136
  `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
137
 
138
138
  `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.
139
+
140
+ ## Claude SDK idle recovery
141
+
142
+ `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.
143
+
144
+ 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.
145
+
146
+ 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.22",
3
+ "version": "0.5.23",
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.22",
3
+ "version": "0.5.23",
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"
@@ -7,7 +7,7 @@
7
7
  "mcp"
8
8
  ],
9
9
  "env": {
10
- "OWENLOOP_PLUGIN_VERSION": "0.5.22"
10
+ "OWENLOOP_PLUGIN_VERSION": "0.5.23"
11
11
  }
12
12
  }
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.22",
3
+ "version": "0.5.23",
4
4
  "description": "Codex plugin for the owenloop workflow engine.",
5
5
  "skills": "./skills/",
6
6
  "mcpServers": "./.mcp.json"
@@ -6,7 +6,7 @@
6
6
  "mcp"
7
7
  ],
8
8
  "env": {
9
- "OWENLOOP_PLUGIN_VERSION": "0.5.22"
9
+ "OWENLOOP_PLUGIN_VERSION": "0.5.23"
10
10
  },
11
11
  "env_vars": [
12
12
  "HOME",