owenloop 0.5.18 → 0.5.20

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 CHANGED
@@ -4,6 +4,20 @@ All notable changes to this project are documented here. The format is based on
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
5
5
  adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [0.5.20](https://github.com/typicalday/owenloop/compare/v0.5.19...v0.5.20) (2026-08-22)
8
+
9
+
10
+ ### Features
11
+
12
+ * **cli:** manage the hub interface catalog ([#285](https://github.com/typicalday/owenloop/issues/285)) ([ca83565](https://github.com/typicalday/owenloop/commit/ca83565aa0d1a1f41c96c954b2f4add4b5b3ec65))
13
+
14
+ ## [0.5.19](https://github.com/typicalday/owenloop/compare/v0.5.18...v0.5.19) (2026-08-22)
15
+
16
+
17
+ ### Features
18
+
19
+ * **work:** submit an artifact by file reference ([#283](https://github.com/typicalday/owenloop/issues/283)) ([8f0f988](https://github.com/typicalday/owenloop/commit/8f0f988f5a05952340014e40a8aefd4353efa46c))
20
+
7
21
  ## [0.5.18](https://github.com/typicalday/owenloop/compare/v0.5.17...v0.5.18) (2026-08-22)
8
22
 
9
23
 
@@ -48,6 +48,8 @@ export interface HoldMcpDeps {
48
48
  hub: HubClient;
49
49
  workflow: string;
50
50
  run: string;
51
+ /** Sole containment root for submit value files. */
52
+ workdir: string;
51
53
  /** Positive registration list. Absent exposes the full three-tool server. */
52
54
  tools?: readonly HoldMcpToolName[];
53
55
  /** Hub origin used to resolve the local machine signing key. */
@@ -37,6 +37,7 @@
37
37
  */
38
38
  import { textResult } from "../mcp/server.js";
39
39
  import { buildSubmitProof } from "../submit-proof.js";
40
+ import { readSubmitValueFile } from "../submit-file.js";
40
41
  import { normalizeSubmitValue } from "../submit-value.js";
41
42
  import { createHoldLoop } from "./loop.js";
42
43
  export const HOLD_MCP_TOOL_NAMES = ['get_order', 'submit', 'reject', 'ask'];
@@ -160,15 +161,20 @@ export function createHoldMcp(deps) {
160
161
  };
161
162
  const submitTool = {
162
163
  name: 'submit',
163
- description: 'Submit a receipt for one owed output path of this order. Set done=true when this is the final value for the path. When the hub reports the run has closed, the holder releases and exits.',
164
+ description: 'Submit a receipt for one owed output path of this order. Provide exactly one of value or valueFile. valueFile names a UTF-8 JSON document inside the run working directory. Set done=true when this is the final value for the path. When the hub reports the run has closed, the holder releases and exits.',
164
165
  inputSchema: {
165
166
  type: 'object',
166
- required: ['path', 'value'],
167
+ required: ['path'],
167
168
  properties: {
168
169
  path: { type: 'string', description: 'The owed output path to submit a receipt for.' },
169
170
  value: { description: 'The receipt value (any JSON).' },
171
+ valueFile: { type: 'string', description: 'A UTF-8 JSON file inside the run working directory.' },
170
172
  done: { type: 'boolean', description: 'Mark this the final submit for the path.' },
171
173
  },
174
+ oneOf: [
175
+ { required: ['value'] },
176
+ { required: ['valueFile'] },
177
+ ],
172
178
  additionalProperties: false,
173
179
  },
174
180
  handler: async (args) => {
@@ -179,8 +185,14 @@ export function createHoldMcp(deps) {
179
185
  if (typeof path !== 'string' || path === '') {
180
186
  return textResult({ error: 'submit requires a non-empty string "path"' }, true);
181
187
  }
182
- if (!('value' in args)) {
183
- return textResult({ error: 'submit requires a "value"' }, true);
188
+ const hasValue = Object.prototype.hasOwnProperty.call(args, 'value');
189
+ const hasValueFile = Object.prototype.hasOwnProperty.call(args, 'valueFile');
190
+ if (hasValue === hasValueFile) {
191
+ return textResult({ error: 'submit-value-source-invalid: provide exactly one of value or valueFile' }, true);
192
+ }
193
+ const valueFile = args['valueFile'];
194
+ if (hasValueFile && (typeof valueFile !== 'string' || valueFile.trim() === '')) {
195
+ return textResult({ error: 'submit-value-file-invalid: valueFile must be a non-empty string' }, true);
184
196
  }
185
197
  const done = args['done'];
186
198
  // Normalize a JSON-encoded string value to the object the hub would
@@ -188,8 +200,11 @@ export function createHoldMcp(deps) {
188
200
  // the proof (it stores normalized bytes the signature does not cover),
189
201
  // silently, on both sides — see `../submit-value.ts`. One value is used
190
202
  // for both the proof and the wire so the two can never diverge.
191
- const value = normalizeSubmitValue(args['value']);
192
203
  try {
204
+ const rawValue = hasValue
205
+ ? args['value']
206
+ : await readSubmitValueFile(deps.workdir, valueFile);
207
+ const value = normalizeSubmitValue(rawValue);
193
208
  // Submit is also a dynamic-data boundary. Fetch and gate the bound
194
209
  // packet even when no origin was supplied for submit-proof signing;
195
210
  // otherwise a direct submit call could bypass MCP consume-side
@@ -320,6 +320,7 @@ export async function run(args, deps = {}) {
320
320
  hub,
321
321
  workflow: target.workflow,
322
322
  run: target.run,
323
+ workdir: process.cwd(),
323
324
  ...(parsed.mcpTools !== undefined ? { tools: parsed.mcpTools } : {}),
324
325
  origin,
325
326
  env,
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Read a submit value from a JSON document contained in a run worktree.
3
+ *
4
+ * The lexical check rejects traversal before probing the filesystem. The
5
+ * canonical check rejects symlinks whose target leaves the worktree.
6
+ */
7
+ export declare function readSubmitValueFile(workdir: string, valueFile: unknown): Promise<unknown>;
@@ -0,0 +1,47 @@
1
+ import { readFile, realpath } from 'node:fs/promises';
2
+ import { resolve } from 'node:path';
3
+ import { isInside } from "./harness/gatekeeper.js";
4
+ function errorMessage(error) {
5
+ return error instanceof Error ? error.message : String(error);
6
+ }
7
+ /**
8
+ * Read a submit value from a JSON document contained in a run worktree.
9
+ *
10
+ * The lexical check rejects traversal before probing the filesystem. The
11
+ * canonical check rejects symlinks whose target leaves the worktree.
12
+ */
13
+ export async function readSubmitValueFile(workdir, valueFile) {
14
+ if (typeof valueFile !== 'string' || valueFile.trim() === '') {
15
+ throw new Error(`submit-value-file-invalid: valueFile must be a non-empty string: ${String(valueFile)}`);
16
+ }
17
+ const candidate = resolve(workdir, valueFile);
18
+ if (!isInside(workdir, candidate)) {
19
+ throw new Error(`submit-value-file-outside-workdir: ${valueFile} is outside the run workdir`);
20
+ }
21
+ let canonicalCandidate;
22
+ try {
23
+ const canonicalWorkdir = await realpath(workdir);
24
+ canonicalCandidate = await realpath(candidate);
25
+ if (!isInside(canonicalWorkdir, canonicalCandidate)) {
26
+ throw new Error(`submit-value-file-outside-workdir: ${valueFile} is outside the run workdir`);
27
+ }
28
+ }
29
+ catch (error) {
30
+ if (error instanceof Error && error.message.startsWith('submit-value-file-outside-workdir:'))
31
+ throw error;
32
+ throw new Error(`submit-value-file-read-failed: could not read ${valueFile}: ${errorMessage(error)}`);
33
+ }
34
+ let text;
35
+ try {
36
+ text = await readFile(canonicalCandidate, 'utf8');
37
+ }
38
+ catch (error) {
39
+ throw new Error(`submit-value-file-read-failed: could not read ${valueFile}: ${errorMessage(error)}`);
40
+ }
41
+ try {
42
+ return JSON.parse(text);
43
+ }
44
+ catch (error) {
45
+ throw new Error(`submit-value-file-invalid-json: could not parse ${valueFile}: ${errorMessage(error)}`);
46
+ }
47
+ }
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, 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, 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,9 @@ ${' '.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
+ interface register <name> <version> --signature <file> [--hub <url>]
1249
+ interface get <name> <version> [--hub <url>]
1250
+ interface list [--hub <url>]
1248
1251
  routing alerts [--workflow <wf>] [--limit <n>] [--hub <url>]
1249
1252
  ${' '.repeat(41)}list the hub org's routing alerts — newest first org-wide; --workflow scopes to
1250
1253
  ${' '.repeat(41)}one run and flips to oldest first. A \`binding-gap\` alert means the hub HELD an
@@ -1361,6 +1364,7 @@ export const COMMAND_OPTIONS = new Map([
1361
1364
  ['instance', cmdOpts('hub')],
1362
1365
  ['agent', cmdOpts('crews', 'hub', 'scopes', 'shift')],
1363
1366
  ['capability', cmdOpts('hub')],
1367
+ ['interface', cmdOpts('hub', 'signature')],
1364
1368
  // Per-TOP-LEVEL-command allowlist, not per-subcommand: `--position` on
1365
1369
  // `routing alerts` is meaningless but accepted and ignored, exactly as
1366
1370
  // `--kind` is on `crew list`. Policing flags per subcommand is deliberately
@@ -6105,6 +6109,152 @@ async function dispatchAgent(io, args) {
6105
6109
  });
6106
6110
  return 0;
6107
6111
  }
6112
+ /**
6113
+ * `owenloop interface register|get|list` — administer the hub's immutable
6114
+ * interface catalog without inspecting the signature's schema semantics.
6115
+ *
6116
+ * | subcommand | endpoint | auth principal |
6117
+ * |---|---|---|
6118
+ * | `interface register <name> <version> --signature <file>` | `POST /api/register_interface` | human (admin role on the hub) |
6119
+ * | `interface get <name> <version>` | `GET /api/interfaces/:name/:version` | human (`get_status`) |
6120
+ * | `interface list` | `GET /api/interfaces` | human (`get_status`) |
6121
+ *
6122
+ * This namespace stores no credential locally, so it deliberately permits an
6123
+ * `OWENLOOP_CREDENTIAL_COMMAND` backend just like `capability`. It accepts
6124
+ * opaque coordinates and an opaque, JSON-parsed signature without client-side
6125
+ * semantic validation; the hub owns all catalog validation. stdout is always
6126
+ * one whitelisted JSON document. Exit codes: 0 success; 1 runtime, hub, or
6127
+ * malformed-response error; 2 unresolvable hub; 3 absent or irrecoverable
6128
+ * human credential (with a runnable login remedy).
6129
+ */
6130
+ async function dispatchInterface(io, args) {
6131
+ const USAGE_FORMS = 'usage: owenloop interface register <name> <version> --signature <file> [--hub <url>] | ' +
6132
+ 'owenloop interface get <name> <version> [--hub <url>] | owenloop interface list [--hub <url>]';
6133
+ const sub = args.positionals[1];
6134
+ if (sub !== 'register' && sub !== 'get' && sub !== 'list') {
6135
+ throw new CliError(`unknown interface subcommand '${sub ?? ''}' — ${USAGE_FORMS}`);
6136
+ }
6137
+ const signatureFlags = all(args, 'signature');
6138
+ let name = '';
6139
+ let version = '';
6140
+ if (sub === 'list') {
6141
+ if (args.positionals[2] !== undefined) {
6142
+ throw new CliError(`interface list takes no positional arguments — ${USAGE_FORMS}`);
6143
+ }
6144
+ if (signatureFlags.length > 0) {
6145
+ throw new CliError(`--signature is only valid for interface register — ${USAGE_FORMS}`);
6146
+ }
6147
+ }
6148
+ else {
6149
+ const rawName = args.positionals[2];
6150
+ const rawVersion = args.positionals[3];
6151
+ if (rawName === undefined || rawName === '') {
6152
+ throw new CliError(`missing required argument: <name> (${USAGE_FORMS})`);
6153
+ }
6154
+ if (rawVersion === undefined || rawVersion === '') {
6155
+ throw new CliError(`missing required argument: <version> (${USAGE_FORMS})`);
6156
+ }
6157
+ if (args.positionals[4] !== undefined) {
6158
+ throw new CliError(`too many positional arguments — ${USAGE_FORMS}`);
6159
+ }
6160
+ name = rawName;
6161
+ version = rawVersion;
6162
+ if (sub === 'get' && signatureFlags.length > 0) {
6163
+ throw new CliError(`--signature is only valid for interface register — ${USAGE_FORMS}`);
6164
+ }
6165
+ }
6166
+ let signature;
6167
+ if (sub === 'register') {
6168
+ if (signatureFlags.length !== 1 || args.missingOptionValues.has('signature') || signatureFlags[0] === '') {
6169
+ throw new CliError(`interface register requires exactly one non-empty --signature <file> — ${USAGE_FORMS}`);
6170
+ }
6171
+ const signaturePath = resolve(io.cwd, signatureFlags[0]);
6172
+ let source;
6173
+ try {
6174
+ source = readFileSync(signaturePath, 'utf8');
6175
+ }
6176
+ catch (e) {
6177
+ throw new CliError(`cannot read interface signature file ${signaturePath}: ${e.message}`);
6178
+ }
6179
+ try {
6180
+ signature = JSON.parse(source);
6181
+ }
6182
+ catch {
6183
+ throw new CliError('interface signature file is not valid JSON');
6184
+ }
6185
+ }
6186
+ // All input validation and the only local file read happened above: hub,
6187
+ // credential, and network work cannot obscure a usage failure.
6188
+ const origin = resolveAgentHub(io, args, 'manage interfaces on');
6189
+ const slot = { principal: 'human' };
6190
+ const credential = readCredential(io, origin, slot);
6191
+ if (credential === null) {
6192
+ throw new CliError(`no human credential for ${origin} — run: owenloop login --hub ${origin}`, { exitCode: 3 });
6193
+ }
6194
+ try {
6195
+ let res;
6196
+ let endpoint;
6197
+ if (sub === 'register') {
6198
+ ({ res } = await authedPost(io, origin, slot, credential, '/api/register_interface', { name, version, signature }));
6199
+ endpoint = 'register_interface';
6200
+ }
6201
+ else if (sub === 'get') {
6202
+ ({ res } = await authedGet(io, origin, slot, credential, `/api/interfaces/${encodeURIComponent(name)}/${encodeURIComponent(version)}`));
6203
+ endpoint = 'interfaces';
6204
+ }
6205
+ else {
6206
+ ({ res } = await authedGet(io, origin, slot, credential, '/api/interfaces'));
6207
+ endpoint = 'interfaces';
6208
+ }
6209
+ if (res.status === 401) {
6210
+ throw new CliError('credential rejected by the hub — run `owenloop login`');
6211
+ }
6212
+ if (!res.ok) {
6213
+ throw new CliError((await hubRequestMessage(res)) ?? `hub ${origin} rejected the request (HTTP ${res.status})`);
6214
+ }
6215
+ let body;
6216
+ try {
6217
+ body = (await res.json());
6218
+ }
6219
+ catch {
6220
+ throw new CliError(`${endpoint}: malformed success response — body is not valid JSON`);
6221
+ }
6222
+ if (sub === 'list') {
6223
+ let interfaces;
6224
+ try {
6225
+ interfaces = asInterfaceCatalogList(body);
6226
+ }
6227
+ catch (e) {
6228
+ throw new CliError(e.message);
6229
+ }
6230
+ print(io, { ok: true, hub: origin, interfaces });
6231
+ return 0;
6232
+ }
6233
+ let result;
6234
+ try {
6235
+ result = asInterfaceCatalogVersion(body, endpoint);
6236
+ }
6237
+ catch (e) {
6238
+ throw new CliError(e.message);
6239
+ }
6240
+ print(io, {
6241
+ ok: true,
6242
+ hub: origin,
6243
+ name: result.name,
6244
+ version: result.version,
6245
+ signature: result.signature,
6246
+ createdBy: result.createdBy,
6247
+ createdAt: result.createdAt,
6248
+ });
6249
+ return 0;
6250
+ }
6251
+ catch (e) {
6252
+ if (e instanceof CliError && /run `owenloop login`/.test(e.message)) {
6253
+ throw new CliError(`${e.message} — run: owenloop login --hub ${origin}`, { exitCode: 3 });
6254
+ }
6255
+ throw e;
6256
+ }
6257
+ }
6108
6258
  /**
6109
6259
  * `owenloop capability bind|unbind|list` — manage the hub org's **capability routes**, the
6110
6260
  * admin-owned table mapping a workflow-def `capabilities:` entry to a crew.
@@ -8326,7 +8476,7 @@ async function runDoctor(io, origin) {
8326
8476
  * the async path, so every existing command and test keeps working exactly as
8327
8477
  * before.
8328
8478
  */
8329
- export const ASYNC_COMMANDS = new Set(['add', 'login', 'logout', 'connect', 'publish', 'trust', 'push', 'install', 'start', 'pending-gates', 'cancel', 'provide', 'reject', 'retry', 'instance', 'agent', 'capability', 'routing', 'crew', 'roster', 'setup', 'doctor', 'enrollments', 'mcp', 'shift']);
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']);
8330
8480
  export async function mainAsync(argv, io = defaultIO()) {
8331
8481
  // Delegate execution-side and shift argv tails before root parsing. Their
8332
8482
  // roles own their option grammars, including repeated/value forms that the
@@ -8400,6 +8550,8 @@ export async function mainAsync(argv, io = defaultIO()) {
8400
8550
  return await dispatchAgent(io, args);
8401
8551
  case 'capability':
8402
8552
  return await dispatchCapability(io, args);
8553
+ case 'interface':
8554
+ return await dispatchInterface(io, args);
8403
8555
  case 'routing':
8404
8556
  return await dispatchRouting(io, args);
8405
8557
  case 'crew':
package/dist/src/hub.d.ts CHANGED
@@ -862,6 +862,22 @@ export declare function asCapabilityRouteRemoved(body: unknown): {
862
862
  * whose `crewName` is `null` is a dangling route and is kept, not dropped.
863
863
  */
864
864
  export declare function asCapabilityRoutes(body: unknown): CapabilityRouteWire[];
865
+ /** One signature-free row returned by `GET /api/interfaces`. */
866
+ export interface InterfaceCatalogRowWire {
867
+ name: string;
868
+ version: string;
869
+ createdBy: string;
870
+ createdAt: number;
871
+ }
872
+ /** The exact-coordinate form returned by register and exact get. */
873
+ export interface InterfaceCatalogVersionWire extends InterfaceCatalogRowWire {
874
+ /** Opaque hub-owned signature. The CLI deliberately does not validate its semantics. */
875
+ signature: unknown;
876
+ }
877
+ /** Narrow a register or exact-get response while retaining its opaque signature. */
878
+ export declare function asInterfaceCatalogVersion(body: unknown, endpoint: 'register_interface' | 'interfaces'): InterfaceCatalogVersionWire;
879
+ /** Narrow `GET /api/interfaces`, preserving the hub's opaque row order. */
880
+ export declare function asInterfaceCatalogList(body: unknown): InterfaceCatalogRowWire[];
865
881
  /**
866
882
  * One **routing alert** as the hub reports it — an org-scoped record that the
867
883
  * hub made a routing decision an operator needs to know about.
package/dist/src/hub.js CHANGED
@@ -1286,6 +1286,49 @@ export function asCapabilityRoutes(body) {
1286
1286
  const list = body.bindings;
1287
1287
  return list.map((entry, i) => asCapabilityRouteRow(entry, 'capability_routes: malformed response', `bindings[${i}]`));
1288
1288
  }
1289
+ /**
1290
+ * Narrow one interface-catalog row without interpreting the signature or any
1291
+ * schemas it may contain. The hub is the only semantic validator; this guard
1292
+ * only protects CLI output from malformed transport data.
1293
+ */
1294
+ function asInterfaceCatalogRow(entry, prefix, where) {
1295
+ if (typeof entry !== 'object' || entry === null) {
1296
+ throw new Error(`${prefix} — ${where} is not an object`);
1297
+ }
1298
+ const value = entry;
1299
+ for (const field of ['name', 'version', 'createdBy']) {
1300
+ if (typeof value[field] !== 'string' || value[field] === '') {
1301
+ throw new Error(`${prefix} — ${where} missing non-empty string ${field}`);
1302
+ }
1303
+ }
1304
+ if (typeof value.createdAt !== 'number') {
1305
+ throw new Error(`${prefix} — ${where} missing number createdAt`);
1306
+ }
1307
+ return {
1308
+ name: value.name,
1309
+ version: value.version,
1310
+ createdBy: value.createdBy,
1311
+ createdAt: value.createdAt,
1312
+ };
1313
+ }
1314
+ /** Narrow a register or exact-get response while retaining its opaque signature. */
1315
+ export function asInterfaceCatalogVersion(body, endpoint) {
1316
+ const prefix = `${endpoint}: malformed response`;
1317
+ const row = asInterfaceCatalogRow(body, prefix, 'response');
1318
+ const value = body;
1319
+ if (!Object.prototype.hasOwnProperty.call(value, 'signature')) {
1320
+ throw new Error(`${prefix} — response missing signature`);
1321
+ }
1322
+ return { ...row, signature: value.signature };
1323
+ }
1324
+ /** Narrow `GET /api/interfaces`, preserving the hub's opaque row order. */
1325
+ export function asInterfaceCatalogList(body) {
1326
+ const prefix = 'interfaces: malformed response';
1327
+ if (typeof body !== 'object' || body === null || !Array.isArray(body.interfaces)) {
1328
+ throw new Error(`${prefix} — missing interfaces array`);
1329
+ }
1330
+ return body.interfaces.map((entry, index) => asInterfaceCatalogRow(entry, prefix, `interfaces[${index}]`));
1331
+ }
1289
1332
  /**
1290
1333
  * Validate the eight `RoutingAlertWire` fields on one row. `prefix` is the
1291
1334
  * endpoint-qualified lead-in the caller wants (e.g.
package/docs/cli.md CHANGED
@@ -81,6 +81,9 @@ 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
+ | `interface register <name> <version> --signature <file> [--hub <url>]` | register one immutable hub interface signature (admin; human credential) — see [Interface catalog](#interface-catalog) |
85
+ | `interface get <name> <version> [--hub <url>]` | get one exact interface signature from the hub — see [Interface catalog](#interface-catalog) |
86
+ | `interface list [--hub <url>]` | list every registered interface coordinate — see [Interface catalog](#interface-catalog) |
84
87
  | `routing alerts [--workflow <wf>] [--limit <n>] [--hub <url>]` | list the hub org's routing alerts — every hold, reroute, wait and fallback the hub recorded — see [Routing](#routing) |
85
88
  | `routing show <workflow> [--hub <url>]` | print one **hub run's** routing: modifier, wait policy, alerts, resolution reports and escalations — see [Routing](#routing) |
86
89
  | `routing rule list [--hub <url>]` | list the org's capability **reroute rules**, in the order the hub tries them — see [Routing](#routing) |
@@ -703,6 +706,20 @@ mint or log credentials. If the stored human credential is an expiring OAuth
703
706
  credential, the decision path may refresh it and persist a rotated token under
704
707
  the shared credential lock before answering the hub.
705
708
 
709
+ ### `work hold --mcp` — machine-attached MCP holder
710
+
711
+ `owenloop work hold --order <workflow>/<run> --mcp` keeps the order lease warm
712
+ and exposes the holder's MCP tools over stdio. Its `submit` tool requires
713
+ exactly one of `value` or `valueFile`, along with the owed `path`; `done: true`
714
+ marks the final receipt for that path.
715
+
716
+ `valueFile` is a UTF-8 JSON document resolved inside the holder's run working
717
+ directory. Traversal, outside absolute paths, and symlinks that escape that
718
+ directory are refused. The file is parsed as JSON before the normal submit
719
+ value normalization, so the parsed value is the one sent to the hub and used
720
+ for any submit proof. There is no client-side artifact-size limit; the hub's
721
+ existing size policy still applies.
722
+
706
723
  ### `util modifier-init`
707
724
 
708
725
  `owenloop util modifier-init --default <value>` is a deterministic helper for
@@ -2379,6 +2396,83 @@ needs a translation step.
2379
2396
  | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
2380
2397
  | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
2381
2398
 
2399
+ ## Interface catalog
2400
+
2401
+ The hub's interface catalog is an append-only registry of exact opaque
2402
+ `name@version` signatures. It is the operator surface for registering a
2403
+ breaking interface version before a workflow definition claims it. There is no
2404
+ update, delete, latest lookup, implementation index, or `x.implements` tooling:
2405
+ duplicate coordinates are refused and are never overwritten.
2406
+
2407
+ | command | method and endpoint | principal |
2408
+ |---|---|---|
2409
+ | `interface register <name> <version> --signature <file> [--hub <url>]` | `POST /api/register_interface` with `{name,version,signature}` | human; admin role required |
2410
+ | `interface get <name> <version> [--hub <url>]` | `GET /api/interfaces/:name/:version` | human; hub applies `get_status` |
2411
+ | `interface list [--hub <url>]` | `GET /api/interfaces` | human; hub applies `get_status` |
2412
+
2413
+ `get` encodes `<name>` and `<version>` separately as URL path segments, so a
2414
+ slash or space in either coordinate does not alter the route. The CLI does not
2415
+ validate coordinate syntax; the hub is the enforcement of record. At deployed
2416
+ hub SHA `d1dc2a1b02645ea6cf4eb4bf0319c3b917e137f4` (owenloop-service #263), the
2417
+ hub refuses a whole `.` or `..` name or version during registration with
2418
+ `interface_catalog_input_invalid`: those path segments normalize before the
2419
+ path-based exact-read route can address them. This is the only coordinate
2420
+ exception; ordinary dotted versions such as `evidence-report@2.0.0` round-trip
2421
+ through register, get, and list. The CLI sends all coordinates unchanged and
2422
+ does not add a local dot-segment guard or encoding workaround.
2423
+
2424
+ ### Registering a signature
2425
+
2426
+ Pass a UTF-8 JSON file with `--signature`; a relative path is resolved from the
2427
+ current directory. For example, after reviewing a local file, use
2428
+ `owenloop interface register evidence-report 2.0.0 --signature interfaces/evidence-report-2.json --hub https://hub.example`.
2429
+ This is intentionally a file rather than the small inline JSON accepted by
2430
+ `start --provide name=json` and `provide --value json`: interface signatures
2431
+ can approach the hub's 64 KiB serialized limit and should be reviewable and
2432
+ reusable without shell quoting or argument-size concerns. It is also unlike
2433
+ `login --with-token`, which reads a secret from stdin; an interface signature is
2434
+ non-secret structured data.
2435
+
2436
+ The CLI reads the file and runs `JSON.parse` only. It sends the resulting value
2437
+ unchanged and delegates coordinate validity, signature shape, typed artifacts,
2438
+ JSON Schemas, duplicate artifact names, and size validation entirely to the
2439
+ hub. A syntactically valid but semantically invalid signature—or a whole `.` or
2440
+ `..` coordinate—therefore reaches the hub and surfaces its non-empty error
2441
+ message; an unreadable or invalid-JSON file fails before a network call.
2442
+
2443
+ ### Reading and output
2444
+
2445
+ `get` and successful `register` return the full opaque signature for one exact
2446
+ coordinate. `list` preserves hub order and deliberately returns signature-free
2447
+ rows, so listing a catalog does not transfer every signature body. stdout is
2448
+ exactly one whitelisted JSON document per successful invocation; the hub's
2449
+ `text` field and unknown response fields are never printed.
2450
+
2451
+ | command | stdout |
2452
+ |---|---|
2453
+ | `interface register` / `interface get` | `{ "ok": true, "hub": "<origin>", "name": "evidence-report", "version": "2.0.0", "signature": { … }, "createdBy": "<id>", "createdAt": 1738000000000 }` |
2454
+ | `interface list` | `{ "ok": true, "hub": "<origin>", "interfaces": [{ "name": "evidence-report", "version": "2.0.0", "createdBy": "<id>", "createdAt": 1738000000000 }] }` |
2455
+
2456
+ Malformed 2xx bodies are rejected before printing. Typed hub refusals such as
2457
+ a duplicate/invalid registration (`400 interface_catalog_input_invalid`),
2458
+ non-admin register (`403 forbidden`), and an unknown exact coordinate (`404
2459
+ interface_catalog_not_found`) surface only the hub's non-empty `message` on
2460
+ stderr and leave stdout empty; the CLI does not prefix it with an `error` code.
2461
+
2462
+ **Hub and credential selection.** All three commands resolve `--hub <url>`
2463
+ first; without it they require exactly one enumerable stored human hub. They do
2464
+ not default from `OWENLOOP_HUB` or a production origin. The human credential slot
2465
+ is used for every command. `OWENLOOP_CREDENTIAL_COMMAND` is supported because
2466
+ this namespace stores no credential locally; an external backend that cannot
2467
+ enumerate hubs must receive `--hub` explicitly.
2468
+
2469
+ | code | meaning |
2470
+ |---|---|
2471
+ | `0` | registered, read, or listed successfully |
2472
+ | `1` | runtime, hub, or malformed-response error, including a hub-side registration refusal |
2473
+ | `2` | the hub could not be resolved |
2474
+ | `3` | the human credential is missing or irrecoverable; stderr names `owenloop login --hub <origin>` |
2475
+
2382
2476
  ## Routing
2383
2477
 
2384
2478
  `owenloop routing` reads and edits the hub's **live routing** state — what the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.18",
3
+ "version": "0.5.20",
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.18",
3
+ "version": "0.5.20",
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.18"
10
+ "OWENLOOP_PLUGIN_VERSION": "0.5.20"
11
11
  }
12
12
  }
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.18",
3
+ "version": "0.5.20",
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.18"
9
+ "OWENLOOP_PLUGIN_VERSION": "0.5.20"
10
10
  },
11
11
  "env_vars": [
12
12
  "HOME",