owenloop 0.5.21 → 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) {
package/dist/src/cli.js CHANGED
@@ -63,7 +63,7 @@ import { BundleError, digestBundle, inspectBundle, packBundle, unpackBundle } fr
63
63
  import { acquireInstallLock, ADD_JOURNAL_FILENAME, archivePathViolation, commitInstall, finalizeInstallCommit, githubShaUrl, githubTarballUrl, installFolder, parkOldNameDir, parseRepoSpec, readLockfile, recoverInterruptedInstall, releaseInstallLock, removeAddJournal, rmRecursiveForce, rollbackInstallCommit, RollbackFailedError, stageFiles, STAGING_DIRNAME, writeAddJournal, writeLockfile, } from "./add.js";
64
64
  import { BundleIngestorUnavailableError, collectWorkflowStoreGarbage, compareStoreText, globalStoreRoot, installWorkflowBundle, inspectCasDefs, loadCasDefs, PreCommitVerifierUnavailableError, parseWorkflowCoordinate, projectStoreRoot, createBundleIngestor, createPreCommitVerifier, recoverWorkflowStore, storeIndexPath, workflowStoreReplacementRecovery, workflowStoreStatePaths, } from "./store/index.js";
65
65
  import { recoverInterruptedWorkflowStoreGc } from "./store/gc-recovery.js";
66
- import { asAgentIdentities, asCreateWorkflowOk, capabilityPublishReportText, asCapabilityRerouteAdded, asCapabilityRerouteRemoved, asCapabilityReroutes, asCapabilityRouteAdded, asCapabilityRouteRemoved, asCapabilityRoutes, asInterfaceCatalogList, asInterfaceCatalogVersion, asCrewCreated, asCrewDeleted, asCrewMemberAdded, asCrewMemberRemoved, asCrews, asRoutingAlerts, asRunRouting, asWhoami, computeServerDiff, credentialBackend, createWorkflowError, credentialFilePath, credentialSlot, DEFAULT_HUB, externalCredentialCommand, hashDefForHub, hubBindingPath, keychainServiceFor, listStoredHubOrigins, normalizeOrigin, parseWorkflowList, pkcePair, randomState, readCredentialFile, readHubBinding, readStoredCredential, resolveEndpoint, resolveKeychain, writeCredentialFile, writeHubBinding, } from "./hub.js";
66
+ import { asAgentIdentities, asCreateWorkflowOk, capabilityPublishReportText, asCapabilityRerouteAdded, asCapabilityRerouteRemoved, asCapabilityReroutes, asCapabilityRouteAdded, asCapabilityRouteRemoved, asCapabilityRoutes, asInterfaceCatalogList, asInterfaceCatalogVersion, asWorkflowCatalogVisibility, asCrewCreated, asCrewDeleted, asCrewMemberAdded, asCrewMemberRemoved, asCrews, asRoutingAlerts, asRunRouting, asWhoami, computeServerDiff, credentialBackend, createWorkflowError, credentialFilePath, credentialSlot, DEFAULT_HUB, externalCredentialCommand, hashDefForHub, hubBindingPath, keychainServiceFor, listStoredHubOrigins, normalizeOrigin, parseWorkflowList, pkcePair, randomState, readCredentialFile, readHubBinding, readStoredCredential, resolveEndpoint, resolveKeychain, writeCredentialFile, writeHubBinding, } from "./hub.js";
67
67
  import { fetchCapabilityMappings, recordCapabilityMappings } from "./capability-mapping-client.js";
68
68
  import { MODIFIER_SEPARATOR } from "./capabilities.js";
69
69
  import { loadSettings, settingsPath as executionSettingsPath } from "../packages/work/src/settings/settings.js";
@@ -1245,6 +1245,7 @@ ${' '.repeat(41)}the instance has reached a terminal status.
1245
1245
  capability bind <capability> <crew> [--hub <url>] add a crew to a workflow capability on the hub org — a capability may bind many crews (admin; human credential)
1246
1246
  capability unbind <capability> <crew> [--hub <url>] remove one (capability, crew) route
1247
1247
  capability list [--hub <url>] list the hub org's capability routes
1248
+ catalog visibility <name> visible|hidden [--hub <url>]
1248
1249
  interface register <name> <version> --signature <file> [--hub <url>]
1249
1250
  interface get <name> <version> [--hub <url>]
1250
1251
  interface list [--hub <url>]
@@ -1364,6 +1365,7 @@ export const COMMAND_OPTIONS = new Map([
1364
1365
  ['instance', cmdOpts('hub')],
1365
1366
  ['agent', cmdOpts('crews', 'hub', 'scopes', 'shift')],
1366
1367
  ['capability', cmdOpts('hub')],
1368
+ ['catalog', cmdOpts('hub')],
1367
1369
  ['interface', cmdOpts('hub', 'signature')],
1368
1370
  // Per-TOP-LEVEL-command allowlist, not per-subcommand: `--position` on
1369
1371
  // `routing alerts` is meaningless but accepted and ignored, exactly as
@@ -6255,6 +6257,76 @@ async function dispatchInterface(io, args) {
6255
6257
  throw e;
6256
6258
  }
6257
6259
  }
6260
+ /**
6261
+ * Set whether one published workflow definition appears in catalog discovery.
6262
+ * The hub remains the source of truth for opaque definition-name semantics and
6263
+ * returned state; this command only validates its small argv shape.
6264
+ */
6265
+ async function dispatchCatalog(io, args) {
6266
+ const USAGE_FORM = 'usage: owenloop catalog visibility <name> visible|hidden [--hub <url>]';
6267
+ if (args.positionals[1] !== 'visibility') {
6268
+ throw new CliError('unknown catalog subcommand ' + JSON.stringify(args.positionals[1] ?? '') + ' — ' + USAGE_FORM);
6269
+ }
6270
+ const name = args.positionals[2];
6271
+ if (name === undefined || name === '') {
6272
+ throw new CliError('missing required argument: <name> (' + USAGE_FORM + ')');
6273
+ }
6274
+ const state = args.positionals[3];
6275
+ if (state === undefined || state === '') {
6276
+ throw new CliError('missing required argument: visible|hidden (' + USAGE_FORM + ')');
6277
+ }
6278
+ if (args.positionals[4] !== undefined) {
6279
+ throw new CliError('too many positional arguments — ' + USAGE_FORM);
6280
+ }
6281
+ if (state !== 'visible' && state !== 'hidden') {
6282
+ throw new CliError('visibility state must be visible or hidden — ' + USAGE_FORM);
6283
+ }
6284
+ const visible = state === 'visible';
6285
+ const origin = resolveAgentHub(io, args, 'set workflow catalog visibility on');
6286
+ const slot = { principal: 'human' };
6287
+ const credential = readCredential(io, origin, slot);
6288
+ if (credential === null) {
6289
+ throw new CliError('no human credential for ' + origin + ' — run: owenloop login --hub ' + origin, { exitCode: 3 });
6290
+ }
6291
+ try {
6292
+ const { res } = await authedPost(io, origin, slot, credential, '/api/set_workflow_catalog_visibility', { name, visible });
6293
+ if (res.status === 401) {
6294
+ throw new CliError('credential rejected by the hub — run `owenloop login`');
6295
+ }
6296
+ if (!res.ok) {
6297
+ throw new CliError((await hubRequestMessage(res)) ?? ('hub ' + origin + ' rejected the request (HTTP ' + res.status + ')'));
6298
+ }
6299
+ let body;
6300
+ try {
6301
+ body = (await res.json());
6302
+ }
6303
+ catch {
6304
+ throw new CliError('set_workflow_catalog_visibility: malformed success response — body is not valid JSON');
6305
+ }
6306
+ let result;
6307
+ try {
6308
+ result = asWorkflowCatalogVisibility(body);
6309
+ }
6310
+ catch (e) {
6311
+ throw new CliError(e.message);
6312
+ }
6313
+ print(io, {
6314
+ ok: true,
6315
+ hub: origin,
6316
+ name: result.name,
6317
+ catalogVisible: result.catalogVisible,
6318
+ previousCatalogVisible: result.previousCatalogVisible,
6319
+ unchanged: result.unchanged,
6320
+ });
6321
+ return 0;
6322
+ }
6323
+ catch (e) {
6324
+ if (e instanceof CliError && /run `owenloop login`/.test(e.message)) {
6325
+ throw new CliError(e.message + ' — run: owenloop login --hub ' + origin, { exitCode: 3 });
6326
+ }
6327
+ throw e;
6328
+ }
6329
+ }
6258
6330
  /**
6259
6331
  * `owenloop capability bind|unbind|list` — manage the hub org's **capability routes**, the
6260
6332
  * admin-owned table mapping a workflow-def `capabilities:` entry to a crew.
@@ -8476,7 +8548,7 @@ async function runDoctor(io, origin) {
8476
8548
  * the async path, so every existing command and test keeps working exactly as
8477
8549
  * before.
8478
8550
  */
8479
- export const ASYNC_COMMANDS = new Set(['add', 'login', 'logout', 'connect', 'publish', 'trust', 'push', 'install', 'start', 'pending-gates', 'cancel', 'provide', 'reject', 'retry', 'instance', 'agent', 'capability', 'interface', 'routing', 'crew', 'roster', 'setup', 'doctor', 'enrollments', 'mcp', 'shift']);
8551
+ export const ASYNC_COMMANDS = new Set(['add', 'login', 'logout', 'connect', 'publish', 'trust', 'push', 'install', 'start', 'pending-gates', 'cancel', 'provide', 'reject', 'retry', 'instance', 'agent', 'capability', 'catalog', 'interface', 'routing', 'crew', 'roster', 'setup', 'doctor', 'enrollments', 'mcp', 'shift']);
8480
8552
  export async function mainAsync(argv, io = defaultIO()) {
8481
8553
  // Delegate execution-side and shift argv tails before root parsing. Their
8482
8554
  // roles own their option grammars, including repeated/value forms that the
@@ -8550,6 +8622,8 @@ export async function mainAsync(argv, io = defaultIO()) {
8550
8622
  return await dispatchAgent(io, args);
8551
8623
  case 'capability':
8552
8624
  return await dispatchCapability(io, args);
8625
+ case 'catalog':
8626
+ return await dispatchCatalog(io, args);
8553
8627
  case 'interface':
8554
8628
  return await dispatchInterface(io, args);
8555
8629
  case 'routing':
package/dist/src/hub.d.ts CHANGED
@@ -878,6 +878,15 @@ export interface InterfaceCatalogVersionWire extends InterfaceCatalogRowWire {
878
878
  export declare function asInterfaceCatalogVersion(body: unknown, endpoint: 'register_interface' | 'interfaces'): InterfaceCatalogVersionWire;
879
879
  /** Narrow `GET /api/interfaces`, preserving the hub's opaque row order. */
880
880
  export declare function asInterfaceCatalogList(body: unknown): InterfaceCatalogRowWire[];
881
+ /** The whitelisted success fields from set_workflow_catalog_visibility. */
882
+ export interface WorkflowCatalogVisibilityWire {
883
+ name: string;
884
+ catalogVisible: boolean;
885
+ previousCatalogVisible: boolean;
886
+ unchanged: boolean;
887
+ }
888
+ /** Narrow the visibility setter response without preserving its text or unknown fields. */
889
+ export declare function asWorkflowCatalogVisibility(body: unknown): WorkflowCatalogVisibilityWire;
881
890
  /**
882
891
  * One **routing alert** as the hub reports it — an org-scoped record that the
883
892
  * hub made a routing decision an operator needs to know about.
package/dist/src/hub.js CHANGED
@@ -1329,6 +1329,32 @@ export function asInterfaceCatalogList(body) {
1329
1329
  }
1330
1330
  return body.interfaces.map((entry, index) => asInterfaceCatalogRow(entry, prefix, `interfaces[${index}]`));
1331
1331
  }
1332
+ /** Narrow the visibility setter response without preserving its text or unknown fields. */
1333
+ export function asWorkflowCatalogVisibility(body) {
1334
+ const prefix = 'set_workflow_catalog_visibility: malformed success response';
1335
+ if (typeof body !== 'object' || body === null) {
1336
+ throw new Error(prefix + ' — response is not an object');
1337
+ }
1338
+ const value = body;
1339
+ if (typeof value.name !== 'string' || value.name === '') {
1340
+ throw new Error(prefix + ' — response missing non-empty string name');
1341
+ }
1342
+ if (typeof value.catalogVisible !== 'boolean') {
1343
+ throw new Error(prefix + ' — response missing boolean catalogVisible');
1344
+ }
1345
+ if (typeof value.previousCatalogVisible !== 'boolean') {
1346
+ throw new Error(prefix + ' — response missing boolean previousCatalogVisible');
1347
+ }
1348
+ if (value.unchanged !== undefined && typeof value.unchanged !== 'boolean') {
1349
+ throw new Error(prefix + ' — response unchanged must be boolean when present');
1350
+ }
1351
+ return {
1352
+ name: value.name,
1353
+ catalogVisible: value.catalogVisible,
1354
+ previousCatalogVisible: value.previousCatalogVisible,
1355
+ unchanged: value.unchanged ?? false,
1356
+ };
1357
+ }
1332
1358
  /**
1333
1359
  * Validate the eight `RoutingAlertWire` fields on one row. `prefix` is the
1334
1360
  * endpoint-qualified lead-in the caller wants (e.g.
@@ -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
@@ -81,6 +81,7 @@ is independent of the `SEARCH INCOMPLETE` bounds notice.
81
81
  | `capability bind <capability> <crew> [--hub <url>]` | add a crew to a workflow capability on the hub org — a capability may route to many crews (admin; human credential) — see [Capability routes](#capability-routes) |
82
82
  | `capability unbind <capability> <crew> [--hub <url>]` | remove one `(capability, crew)` route — see [Capability routes](#capability-routes) |
83
83
  | `capability list [--hub <url>]` | list the hub org's capability routes — see [Capability routes](#capability-routes) |
84
+ | `catalog visibility <name> visible\|hidden [--hub <url>]` | set whether one published workflow definition appears in catalog discovery (admin; human credential) — see [Workflow catalog visibility](#workflow-catalog-visibility) |
84
85
  | `interface register <name> <version> --signature <file> [--hub <url>]` | register one immutable hub interface signature (admin; human credential) — see [Interface catalog](#interface-catalog) |
85
86
  | `interface get <name> <version> [--hub <url>]` | get one exact interface signature from the hub — see [Interface catalog](#interface-catalog) |
86
87
  | `interface list [--hub <url>]` | list every registered interface coordinate — see [Interface catalog](#interface-catalog) |
@@ -2396,6 +2397,48 @@ needs a translation step.
2396
2397
  | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
2397
2398
  | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
2398
2399
 
2400
+ ## Workflow catalog visibility
2401
+
2402
+ Use `owenloop catalog visibility <name> visible|hidden [--hub <url>]` to set
2403
+ whether one published workflow definition is shown in catalog discovery. The
2404
+ `catalog` namespace names the discovery surface directly; `defs` is local
2405
+ definition discovery and `workflow` would be ambiguous with workflow-instance
2406
+ coordinates.
2407
+
2408
+ The CLI sends `POST /api/set_workflow_catalog_visibility` with
2409
+ `{ "name": "<name>", "visible": true }` for `visible` and the same body with
2410
+ `false` for `hidden`. It accepts only those two state words and only requires
2411
+ that `<name>` is non-empty; definition-name syntax and existence remain hub
2412
+ decisions.
2413
+
2414
+ This changes catalog discovery only. It does not change exact-name reads,
2415
+ starts, call resolution, authorization, or existing instances. Each invocation
2416
+ sets one definition: it does not read state, list/filter definitions, or accept
2417
+ bulk or glob inputs.
2418
+
2419
+ The command resolves `--hub` first; without it, exactly one enumerable stored
2420
+ hub is required. It uses only the human/admin credential, and supports
2421
+ `OWENLOOP_CREDENTIAL_COMMAND` because it writes no local credential. Successful
2422
+ stdout is exactly one JSON document:
2423
+
2424
+ `{ "ok": true, "hub": "<origin>", "name": "<server name>", "catalogVisible": false, "previousCatalogVisible": true, "unchanged": false }`
2425
+
2426
+ The server-echoed fields are authoritative. `unchanged: false` means this call
2427
+ changed visibility; `unchanged: true` means it was already in the requested
2428
+ state. Both are successful exit-0 results. The hub's `text` field and unknown
2429
+ response fields are never printed.
2430
+
2431
+ An unknown definition surfaces the hub's non-empty message unchanged (for
2432
+ example, its `DefNotFoundError` message), with no raw error code or replacement
2433
+ body. Malformed successful responses leave stdout empty.
2434
+
2435
+ | code | meaning |
2436
+ |---|---|
2437
+ | `0` | visibility was set, including an idempotent repeat |
2438
+ | `1` | usage, runtime, hub, or malformed-response error |
2439
+ | `2` | the hub could not be resolved |
2440
+ | `3` | the human credential is missing or irrecoverable; stderr names `owenloop login --hub <origin>` |
2441
+
2399
2442
  ## Interface catalog
2400
2443
 
2401
2444
  The hub's interface catalog is an append-only registry of exact opaque
@@ -3580,6 +3623,10 @@ child's `eligible` orders or wait on child completion. To block on a tree, wait
3580
3623
  on the instance that actually owes the work (often a child), or poll deep
3581
3624
  `tick`/`status` yourself.
3582
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
+
3583
3630
  ## Instance pinning — editing a workflow definition mid-flight
3584
3631
 
3585
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.21",
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.21",
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.21"
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.21",
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.21"
9
+ "OWENLOOP_PLUGIN_VERSION": "0.5.23"
10
10
  },
11
11
  "env_vars": [
12
12
  "HOME",