owenloop 0.3.1 → 0.4.1
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 +32 -0
- package/README.md +53 -1
- package/dist/add.d.ts +12 -40
- package/dist/add.js +11 -176
- package/dist/cli.d.ts +52 -7
- package/dist/cli.js +1072 -382
- package/dist/credentials.d.ts +274 -0
- package/dist/credentials.js +695 -0
- package/dist/defs.js +23 -0
- package/dist/engine.js +15 -6
- package/dist/hub.d.ts +363 -6
- package/dist/hub.js +551 -4
- package/dist/index.d.ts +4 -1
- package/dist/index.js +2 -1
- package/dist/lock.d.ts +80 -0
- package/dist/lock.js +217 -0
- package/dist/mcp/serve.d.ts +84 -0
- package/dist/mcp/serve.js +565 -0
- package/dist/mcp/server.d.ts +135 -0
- package/dist/mcp/server.js +330 -0
- package/dist/model.d.ts +59 -4
- package/dist/model.js +148 -21
- package/dist/owenwork.d.ts +57 -0
- package/dist/owenwork.js +84 -0
- package/dist/types.d.ts +48 -6
- package/dist/util.d.ts +24 -0
- package/dist/util.js +25 -0
- package/docs/authoring.md +9 -0
- package/docs/cli.md +411 -15
- package/docs/design.md +86 -12
- package/docs/embedding.md +58 -0
- package/package.json +1 -1
package/docs/cli.md
CHANGED
|
@@ -21,10 +21,22 @@ every command, as above. `--help` on any command (or bare `-h`/`help`)
|
|
|
21
21
|
prints this usage and exits 0 without doing any work.
|
|
22
22
|
|
|
23
23
|
Boolean flags (`--force`, `--dry-run`, `--all`, `--open`, `--terminal`,
|
|
24
|
-
`--recursive`, `--with-token`, `--shallow`, `--assume-provided`,
|
|
25
|
-
`--now` on `reap`) never take a following
|
|
26
|
-
positional or the next `--flag`, never
|
|
27
|
-
`--flag=value` (e.g. `--now=<ms>` on
|
|
24
|
+
`--recursive`, `--with-token`, `--shallow`, `--assume-provided`,
|
|
25
|
+
`--strict-inputs`, and the bare `--now` on `reap`) never take a following
|
|
26
|
+
value — the next token is always a positional or the next `--flag`, never
|
|
27
|
+
consumed as this flag's argument. Use `--flag=value` (e.g. `--now=<ms>` on
|
|
28
|
+
`tick`) for flags that do take a value.
|
|
29
|
+
|
|
30
|
+
`owenloop check <def>` defaults to treating `seedOwed` inputs as provided
|
|
31
|
+
(`assumeProvided: true`), so a def whose only initial gate is an unprovided
|
|
32
|
+
seeded input no longer reports a false depth-0 `True deadlocks` and doesn't
|
|
33
|
+
exit nonzero for it. `--strict-inputs` opts back out to the previous
|
|
34
|
+
seedOwed-starts-owed behavior, and when that's the def's only blocker also
|
|
35
|
+
prints a one-line hint naming the responsible input(s). `--assume-provided`
|
|
36
|
+
is still accepted (never errors) but is now redundant with the default; if
|
|
37
|
+
both flags are passed, `--strict-inputs` wins. See
|
|
38
|
+
[`docs/design.md` §25](design.md#25-the-model-checker-owenloop-check--scope)
|
|
39
|
+
for the full breakdown.
|
|
28
40
|
|
|
29
41
|
## Commands
|
|
30
42
|
|
|
@@ -33,10 +45,14 @@ positional or the next `--flag`, never consumed as this flag's argument. Use
|
|
|
33
45
|
| `defs` | list available workflow definitions |
|
|
34
46
|
| `add <owner>/<repo>[@ref]` | fetch, validate, and install a repo's workflow defs from GitHub (public repos only) — see below |
|
|
35
47
|
| `add --recover` | finish or undo a crash-interrupted install, offline — no network call — see below |
|
|
36
|
-
| `login [--hub <url>] [--with-token]` | authenticate the CLI against a hub — loopback OAuth, or `--with-token` from stdin — see [Hub](#hub-login--connect--push--logout) |
|
|
37
|
-
| `connect [--hub <url>]` | bind this project to a hub (writes `.owenloop/hub.json`) and verify the credential |
|
|
38
|
-
| `push [<defName>...] [--force] [--dry-run]` | publish local workflow defs to the bound hub (idempotent against the hub's own def hashes) |
|
|
39
|
-
| `logout [--hub <url>]` | delete the stored credential for a hub |
|
|
48
|
+
| `login [--hub <url>] [--with-token] [--as <slot>]` | authenticate the CLI against a hub — loopback OAuth, or `--with-token` from stdin — see [Hub](#hub-login--connect--push--logout) |
|
|
49
|
+
| `connect [--hub <url>] [--as <slot>]` | bind this project to a hub (writes `.owenloop/hub.json`) and verify the credential |
|
|
50
|
+
| `push [<defName>...] [--force] [--dry-run] [--as <slot>]` | publish local workflow defs to the bound hub (idempotent against the hub's own def hashes) |
|
|
51
|
+
| `logout [--hub <url>] [--as <slot>]` | delete the stored credential for a hub |
|
|
52
|
+
| `agent new <name> [--pools <a,b>] [--hub <url>]` | mint a new agent identity on the hub and store its token in slot `agent:<name>` — the token is never printed — see [Hub](#hub-login--connect--push--logout) |
|
|
53
|
+
| `setup [--hub <url>] [--new-agent <name> \| --replace-agent <name>] [--pools <a,b>]` | converge this machine's install (human login, agent credential, owenwork settings, plugin) in one idempotent pass — see [`setup`](#setup--converge-a-machines-install) |
|
|
54
|
+
| `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
|
|
55
|
+
| `mcp [--hub <url>]` | serve the hub control plane to a local MCP host over stdio — spawned by MCP hosts, not run by humans — see [`mcp`](#mcp--stdio-control-plane-server-for-mcp-hosts) |
|
|
40
56
|
| `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
|
|
41
57
|
| `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
|
|
42
58
|
| `tick <wf> [--now=<ms>] [--shallow] [--label <l>]…` | claim and emit eligible **orders** (the jobs to run); deep by default — also descends into live `calls:` children (`--shallow` = this instance only); repeatable `--label` claims unlabeled steps plus matching-label steps — see below |
|
|
@@ -337,20 +353,106 @@ that can't call the hub is never written to disk):
|
|
|
337
353
|
table). An `olp_`-prefixed **agent** token or an `mcpat_`-prefixed **access**
|
|
338
354
|
token is accepted; anything else is rejected before any network call.
|
|
339
355
|
|
|
356
|
+
**Credential slots (`--as`).** A hub origin holds more than one credential, each
|
|
357
|
+
in a named **slot**, so a human sign-in and any number of agent tokens coexist
|
|
358
|
+
on the same machine without overwriting each other:
|
|
359
|
+
|
|
360
|
+
| `--as` value | slot | who it is |
|
|
361
|
+
|---|---|---|
|
|
362
|
+
| *(omitted)* | depends on the credential — see below | |
|
|
363
|
+
| `human` | `human` | you, via loopback OAuth or a pasted `mcpat_` token |
|
|
364
|
+
| `agent` | `agent:default` | an agent token with no account name |
|
|
365
|
+
| `agent:<account>` | `agent:<account>` | a named agent, e.g. `agent:ci` |
|
|
366
|
+
|
|
367
|
+
An account name is 1–64 characters matching `[A-Za-z0-9][A-Za-z0-9._-]*`;
|
|
368
|
+
anything else is a usage error. With `--as` omitted, a credential lands in the
|
|
369
|
+
slot it belongs to: loopback OAuth and pasted `mcpat_` tokens go to `human`,
|
|
370
|
+
`olp_` agent tokens go to `agent:default`. The two contradictions are refused as
|
|
371
|
+
usage errors **before any network call**, so nothing unverified is stored:
|
|
372
|
+
`--as human` with an `olp_` token, and `--as agent[:…]` with an OAuth or pasted
|
|
373
|
+
human credential. `login`'s JSON reports the `slot` it wrote.
|
|
374
|
+
|
|
375
|
+
`connect`, `push`, and `logout` take the same `--as` and act on exactly that
|
|
376
|
+
slot — there is no fallback to another slot, so `push --as agent:ci` with an
|
|
377
|
+
empty `agent:ci` fails rather than quietly pushing as you. `logout` without
|
|
378
|
+
`--as` removes only `human`.
|
|
379
|
+
|
|
340
380
|
**Where the credential lands.** On macOS it goes into the login **Keychain**
|
|
341
|
-
(`security`, service `owenloop
|
|
342
|
-
fed over stdin, never on the command line.
|
|
343
|
-
`OWENLOOP_NO_KEYCHAIN=1` — it falls back to a `0600` file at
|
|
381
|
+
(`security`, service `owenloop:<hub origin>`, one item per slot, with the slot
|
|
382
|
+
name as the account) with the secret fed over stdin, never on the command line.
|
|
383
|
+
Elsewhere — or with `OWENLOOP_NO_KEYCHAIN=1` — it falls back to a `0600` file at
|
|
344
384
|
`$XDG_CONFIG_HOME/owenloop/credentials.json` (or `~/.config/owenloop/…`) inside
|
|
345
|
-
a `0700` directory
|
|
346
|
-
`.env`. `login`'s JSON reports `storage: "keychain" |
|
|
347
|
-
prints **no token value** to stdout/stderr.
|
|
385
|
+
a `0700` directory, keyed `hubs[origin][slot]`. Either way the token is never
|
|
386
|
+
written into the repo or a `.env`. `login`'s JSON reports `storage: "keychain" |
|
|
387
|
+
"file"` and `kind`, and prints **no token value** to stdout/stderr. A credential
|
|
388
|
+
stored by an earlier release used a different keying and is **not** read; there
|
|
389
|
+
is deliberately no migration, so re-run `owenloop login`.
|
|
348
390
|
|
|
349
391
|
The backend is chosen once from your platform and env and then used for every
|
|
350
392
|
read and write — a keychain-backed CLI never silently drops to the file store.
|
|
351
393
|
If the keychain write fails (locked or unavailable), `login` errors out instead
|
|
352
394
|
of writing the secret elsewhere: unlock the keychain, or set
|
|
353
|
-
`OWENLOOP_NO_KEYCHAIN=1` to select the file store up front.
|
|
395
|
+
`OWENLOOP_NO_KEYCHAIN=1` to select the file store up front. Programmatic hosts
|
|
396
|
+
can read (only read) a stored credential through the same backend logic via the
|
|
397
|
+
package's exported `readStoredCredential` — see
|
|
398
|
+
[Embedding](embedding.md#whats-exported).
|
|
399
|
+
|
|
400
|
+
**Serializing writes (`credentials.lock`).** A store write — a refreshed OAuth
|
|
401
|
+
token, or a `login`/`logout` that stores or deletes a slot — is serialized by a
|
|
402
|
+
lockfile at `credentials.lock`, a sibling of `credentials.json` in the config
|
|
403
|
+
dir (created for the keychain backend too, since the race it closes is
|
|
404
|
+
backend-independent). The concern is a token-refresh race: two owenloop
|
|
405
|
+
processes hitting an expiring OAuth token at once would each POST a refresh and
|
|
406
|
+
each persist, and because refresh tokens rotate, the second write clobbers the
|
|
407
|
+
first with a token whose refresh link is already spent — silently killing the
|
|
408
|
+
credential. Under the lock a process re-reads the slot after acquiring it and,
|
|
409
|
+
if another process already refreshed, **adopts** that fresh token instead of
|
|
410
|
+
refreshing again — one network refresh, one write, no lost token. The lock
|
|
411
|
+
matters only for OAuth refresh and store/delete; read paths and the external-
|
|
412
|
+
command mode (which never writes the local store) do not take it. Staleness is
|
|
413
|
+
liveness-based: a lock held by a dead same-host process is reclaimed at once, an
|
|
414
|
+
unparseable or pid-less lockfile is reclaimed once older than the ~30s TTL, and
|
|
415
|
+
a lock held by a live process is never age-reclaimed. If the lock can't be
|
|
416
|
+
acquired within the wait budget the CLI fails loudly (`another owenloop process
|
|
417
|
+
is using the credential store … — timed out waiting after Ns`) rather than
|
|
418
|
+
refreshing unlocked. Three test knobs override the timings:
|
|
419
|
+
`OWENLOOP_CRED_LOCK_WAIT_MS` (default 45000), `OWENLOOP_CRED_LOCK_STALE_MS`
|
|
420
|
+
(default 30000), and `OWENLOOP_CRED_LOCK_POLL_MS` (default 100). No token value
|
|
421
|
+
ever appears in the lockfile or the timeout message.
|
|
422
|
+
|
|
423
|
+
**Supplying the credential from your own tooling.** If your secrets live in a
|
|
424
|
+
secret manager, or you run on a host with no keychain, set
|
|
425
|
+
`OWENLOOP_CREDENTIAL_COMMAND` to a shell command line that prints a credential.
|
|
426
|
+
It takes precedence over both stores, so the full order is **external command →
|
|
427
|
+
keychain → file**, still chosen once. Nothing is auto-detected: the variable is
|
|
428
|
+
the only way to turn this on, and an unset or blank value leaves everything
|
|
429
|
+
exactly as described above.
|
|
430
|
+
|
|
431
|
+
The contract:
|
|
432
|
+
|
|
433
|
+
- The command runs as `/bin/sh -c "<your command>"`, so a pipeline or arguments
|
|
434
|
+
work (`my-helper --hub prod`).
|
|
435
|
+
- Context arrives in the **environment**, not on the command line:
|
|
436
|
+
`OWENLOOP_CREDENTIAL_ORIGIN` (the normalized hub origin) and
|
|
437
|
+
`OWENLOOP_CREDENTIAL_SLOT` (`human` or `agent:<account>`). Your command should
|
|
438
|
+
return the credential for exactly that pair.
|
|
439
|
+
- `OWENLOOP_CREDENTIAL_COMMAND` is **removed** from the command's own
|
|
440
|
+
environment, so a helper that shells back into `owenloop` cannot recurse.
|
|
441
|
+
- It must print a credential as a JSON object on **stdout** — the same shape
|
|
442
|
+
stored in `credentials.json`, e.g. `{"kind":"agent","accessToken":"olp_…"}` or
|
|
443
|
+
a full `{"kind":"oauth", …}` object. A bare token is not accepted. stdout is
|
|
444
|
+
captured and never logged; the command's **stderr passes straight through** to
|
|
445
|
+
your terminal, so put diagnostics there — never the secret.
|
|
446
|
+
- It must finish within 10s, overridable with
|
|
447
|
+
`OWENLOOP_CREDENTIAL_COMMAND_TIMEOUT_MS`.
|
|
448
|
+
|
|
449
|
+
A configured command is **authoritative**: a nonzero exit, a timeout, empty
|
|
450
|
+
output, or output that is not a well-formed credential is a hard error naming
|
|
451
|
+
the hub and the slot — never a quiet fall back to a keychain or file entry,
|
|
452
|
+
which would risk handing back a stale key. For the same reason `login` refuses
|
|
453
|
+
to run while the variable is set (unset it if you want to use the local store
|
|
454
|
+
again), and a refreshed OAuth token is not written to the local store — your
|
|
455
|
+
command owns the credential's lifecycle. `logout` still clears local entries.
|
|
354
456
|
|
|
355
457
|
Both branches verify the credential against `GET /api/whoami` before storing
|
|
356
458
|
it — a `401` there means the credential is never written to disk. On success
|
|
@@ -430,6 +532,300 @@ Exact-match redirect URIs (no RFC 8252 variable-port allowance) and no
|
|
|
430
532
|
device-code grant remain recorded follow-ups on the service, not gaps in the
|
|
431
533
|
CLI.
|
|
432
534
|
|
|
535
|
+
### `agent new` — mint an agent token into a slot
|
|
536
|
+
|
|
537
|
+
`owenloop agent new <name>` mints a new agent identity on the hub (`POST
|
|
538
|
+
/api/mint_agent_token`, authenticated as your **human** credential) and stores
|
|
539
|
+
the returned `olp_` token in the local credential slot `agent:<name>` — the same
|
|
540
|
+
slot `login --as agent:<name>` writes and `push --as agent:<name>` reads. Use it
|
|
541
|
+
to provision an agent token without pasting one by hand: the mint and the store
|
|
542
|
+
happen in one step, and you never handle the secret.
|
|
543
|
+
|
|
544
|
+
**The token is never printed.** The minted `olp_` token goes process → store
|
|
545
|
+
only — it never appears on stdout, stderr, in an error, or in a log (identity
|
|
546
|
+
model §6, "rule of gates"). The confirmation JSON is built from a whitelist of
|
|
547
|
+
**non-secret** fields only: `hub`, `name`, `slot`, `pools` (the resolved pool
|
|
548
|
+
names), `scopes` (`["work"]`), `storage` (`keychain` | `file`), `agentId` (the
|
|
549
|
+
agent's id), and `tokenId` (a revocation handle). To use the agent afterwards,
|
|
550
|
+
pass `--as agent:<name>` to `connect`/`push`; to revoke it, use its `tokenId`
|
|
551
|
+
on the hub.
|
|
552
|
+
|
|
553
|
+
**Which hub gets minted on (`--hub`).** Resolution is deliberately narrow —
|
|
554
|
+
minting on the wrong org is not undone by a retry:
|
|
555
|
+
|
|
556
|
+
1. `--hub <origin>` if given (normalized the same way as everywhere else).
|
|
557
|
+
2. Otherwise the **one** hub your credential *file* stores — if exactly one is
|
|
558
|
+
present, it's used.
|
|
559
|
+
3. Otherwise the command **exits 2** naming both remedies (pass `--hub`, or log
|
|
560
|
+
in to exactly one hub); when more than one hub is stored their origins are
|
|
561
|
+
listed back so you can pick.
|
|
562
|
+
|
|
563
|
+
Unlike other commands this does **not** fall back to `OWENLOOP_HUB` or the
|
|
564
|
+
built-in default hub — silently defaulting a mint would risk minting on the
|
|
565
|
+
production hub while you're logged into a dev one. Note that hub enumeration is
|
|
566
|
+
**file-store only** (shared with `owenloop mcp`): the keychain and the
|
|
567
|
+
external-command backend cannot list their entries, so on such a machine step 2
|
|
568
|
+
cannot enumerate the store and you must pass `--hub`.
|
|
569
|
+
|
|
570
|
+
**`--pools <a,b>`.** A comma-separated list of pool names the token is granted
|
|
571
|
+
on (trimmed, empties dropped). Omit the flag to let the hub default the token to
|
|
572
|
+
the minter's personal pool; `--pools ""` (or `--pools ,`) is a usage error. Pool
|
|
573
|
+
names are validated by the hub, not the client.
|
|
574
|
+
|
|
575
|
+
**A configured external credential command blocks the mint.** If
|
|
576
|
+
`OWENLOOP_CREDENTIAL_COMMAND` is set, that command — not the local store —
|
|
577
|
+
supplies credentials for the hub, so `agent new` refuses up front (it has
|
|
578
|
+
nowhere to write the minted token); unset the variable to use the local store.
|
|
579
|
+
This check, the name validation, and the empty-`--pools` check all run **before**
|
|
580
|
+
any network call, so a refusal never mints a server-side token first — a mint
|
|
581
|
+
that then failed to store would burn the agent name permanently.
|
|
582
|
+
|
|
583
|
+
**Exit codes.**
|
|
584
|
+
|
|
585
|
+
| code | meaning |
|
|
586
|
+
|---|---|
|
|
587
|
+
| `0` | minted and stored |
|
|
588
|
+
| `1` | generic failure — invalid or already-taken name, pool/shape rejection, network timeout, or a token that minted but couldn't be stored |
|
|
589
|
+
| `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
|
|
590
|
+
| `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
|
|
591
|
+
|
|
592
|
+
## `setup` — converge a machine's install
|
|
593
|
+
|
|
594
|
+
`owenloop setup` is the one-shot onboarding command. It brings a machine to a
|
|
595
|
+
working install by converging six surfaces in order, each a **probe → (skip |
|
|
596
|
+
act)** step — a step acts only when its probe fails, so a second run on an
|
|
597
|
+
already-set-up machine performs **zero writes** (no store mutation, no settings
|
|
598
|
+
write, no browser, no mint/rekey/register POST). The steps:
|
|
599
|
+
|
|
600
|
+
1. **inspect** — read-only report of what's already present (human credential,
|
|
601
|
+
owenwork settings, `claude` on PATH, agent slots). No writes.
|
|
602
|
+
2. **human login** — verify the stored **human** credential, or run the same
|
|
603
|
+
loopback-OAuth browser flow as `owenloop login` when none is present or it no
|
|
604
|
+
longer verifies. This is the gate that makes step 3's mint/rekey legal.
|
|
605
|
+
3. **agent** — find a local `agent:<name>` slot that verifies live against the
|
|
606
|
+
hub and reuse it; otherwise **mint** a new agent identity or **rekey**
|
|
607
|
+
(replace the credential of) an existing one. How the target is chosen is
|
|
608
|
+
[below](#choosing-the-agent-flow-a-vs-flow-b).
|
|
609
|
+
4. **owenwork settings** — write `hubOrigin` into the owenwork settings file so
|
|
610
|
+
the local worker talks to this hub (skipped when it already matches).
|
|
611
|
+
5. **plugin** — check whether the Claude Code `owenloop` plugin is installed.
|
|
612
|
+
**Non-fatal:** while the marketplace is unpublished this step only *prints*
|
|
613
|
+
the manual install commands (`claude plugin marketplace add owenloop` then
|
|
614
|
+
`claude plugin install owenloop@owenloop`); it never fails setup.
|
|
615
|
+
6. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
|
|
616
|
+
the same surfaces, whose result becomes setup's exit code.
|
|
617
|
+
|
|
618
|
+
Progress lines (the `[n/6]` headers and `✓`/`✗` marks) go to **stderr**; the
|
|
619
|
+
final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
|
|
620
|
+
**stdout**.
|
|
621
|
+
|
|
622
|
+
### Choosing the agent (Flow A vs Flow B)
|
|
623
|
+
|
|
624
|
+
When step 3 has to act (no reusable local agent slot), it decides *which* agent
|
|
625
|
+
to connect this machine to:
|
|
626
|
+
|
|
627
|
+
- **Flow A — fresh org (no agent identities on the hub):** setup asks you to
|
|
628
|
+
**name** the agent, prefilled with a sanitized form of the machine hostname.
|
|
629
|
+
The name is a suggestion — any label matching `[A-Za-z0-9][A-Za-z0-9._-]*`
|
|
630
|
+
(1–64 chars) is accepted. It then **mints** that agent.
|
|
631
|
+
- **Flow B — org already has agents (succession):** setup shows the existing
|
|
632
|
+
agents (each with its name, when it was **last active**, and its **pools**)
|
|
633
|
+
and asks whether this is a *new* installation or one that *replaces* an
|
|
634
|
+
existing agent. Choosing **new** mints a fresh agent; choosing **replace**
|
|
635
|
+
**rekeys** the chosen agent — which **revokes that agent's current
|
|
636
|
+
credential**, so if it is still running elsewhere it will be disconnected
|
|
637
|
+
there.
|
|
638
|
+
|
|
639
|
+
**Non-interactive runs must pass a bypass flag.** When stdin is not a TTY (a
|
|
640
|
+
scripted or piped run) and step 3 needs to act, setup will not block on a
|
|
641
|
+
prompt — it errors unless you pre-decide with one of:
|
|
642
|
+
|
|
643
|
+
- `--new-agent <name>` — mint a new agent named `<name>` (skips Flow A's name
|
|
644
|
+
prompt and Flow B's succession prompt).
|
|
645
|
+
- `--replace-agent <name>` — rekey the existing agent named `<name>` (skips the
|
|
646
|
+
succession prompt); errors if no such agent exists on the hub.
|
|
647
|
+
|
|
648
|
+
The two flags are mutually exclusive. `--pools <a,b>` applies **only** to a mint
|
|
649
|
+
(`--new-agent` or a fresh org); combining it with `--replace-agent` is a usage
|
|
650
|
+
error, because rekeying preserves the agent's existing pools (manage those in
|
|
651
|
+
the console).
|
|
652
|
+
|
|
653
|
+
### Hub resolution differs from `agent new`
|
|
654
|
+
|
|
655
|
+
`setup` (and `doctor`) resolve the target hub like `agent new` with **one**
|
|
656
|
+
deliberate difference: a brand-new machine with **no** stored hub falls back to
|
|
657
|
+
the built-in **default hub** (printing a `targeting <hub>` notice to stderr)
|
|
658
|
+
instead of exiting 2. That is safe here because the mint happens only *after*
|
|
659
|
+
you sign in through that hub's own browser consent, and the target is printed
|
|
660
|
+
first. Resolution order:
|
|
661
|
+
|
|
662
|
+
1. `--hub <origin>` if given.
|
|
663
|
+
2. Otherwise the **one** hub your credential *file* stores, if exactly one is
|
|
664
|
+
present.
|
|
665
|
+
3. More than one stored hub → **exit 2**, listing them so you can pass `--hub`.
|
|
666
|
+
4. Zero stored hubs (or a keychain/external backend that can't enumerate) →
|
|
667
|
+
the **default hub**, with a printed notice.
|
|
668
|
+
|
|
669
|
+
### A configured external credential command blocks setup
|
|
670
|
+
|
|
671
|
+
If `OWENLOOP_CREDENTIAL_COMMAND` is set, that command — not the local store —
|
|
672
|
+
supplies this hub's credentials, so setup **refuses up front**, *before any
|
|
673
|
+
browser opens*. Its human-login and agent-mint steps would write keys nobody
|
|
674
|
+
reads; unset the variable to use `owenloop login` and the local store. (This is
|
|
675
|
+
the same guard `agent new` applies, just moved ahead of the OAuth round-trip so
|
|
676
|
+
the flagship command never opens a browser only to fail at the store.)
|
|
677
|
+
|
|
678
|
+
### After setup
|
|
679
|
+
|
|
680
|
+
If the connected agent account is anything other than `default`, setup prints a
|
|
681
|
+
reminder to run owenwork with `OWENWORK_ACCOUNT=<name>` so the worker reads the
|
|
682
|
+
right slot.
|
|
683
|
+
|
|
684
|
+
**Exit codes.**
|
|
685
|
+
|
|
686
|
+
| code | meaning |
|
|
687
|
+
|---|---|
|
|
688
|
+
| `0` | every step ended skipped/done/noted **and** doctor's core checks (1–5) passed |
|
|
689
|
+
| `1` | setup ran but doctor's core checks did not all pass |
|
|
690
|
+
| non-zero (thrown) | a hard failure — bad flags, unresolvable hub (2), 403 from the hub (setup needs an admin credential to manage agents), a named `--replace-agent` that doesn't exist, or a configured external credential command |
|
|
691
|
+
|
|
692
|
+
## `doctor` — check a machine's install
|
|
693
|
+
|
|
694
|
+
`owenloop doctor` is the **read-only** diagnostic behind setup's final step. It
|
|
695
|
+
probes the same install surfaces and prints one `✓`/`✗` line per check to
|
|
696
|
+
stderr, plus a `{ ok, hub, checks }` summary to stdout. It performs **no
|
|
697
|
+
configuration writes** — no mint, rekey, slot create/delete, settings write, or
|
|
698
|
+
browser. (The one unavoidable carve-out: verifying the human credential may
|
|
699
|
+
rotate-and-persist an *expiring* human OAuth token, exactly as every authed
|
|
700
|
+
command does — refreshing without persisting would strand the rotated refresh
|
|
701
|
+
token and corrupt the install.)
|
|
702
|
+
|
|
703
|
+
The checks, in order:
|
|
704
|
+
|
|
705
|
+
| # | check | ✓ means | core |
|
|
706
|
+
|---|---|---|---|
|
|
707
|
+
| 1 | human credential | a human credential is stored for this hub | yes |
|
|
708
|
+
| 2 | human plane | that credential verifies live against the hub (`whoami`) | yes |
|
|
709
|
+
| 3 | agent slot | an `agent:<name>` credential is stored | yes |
|
|
710
|
+
| 4 | agent plane | that agent credential verifies live against the hub | yes |
|
|
711
|
+
| 5 | owenwork settings | the settings file's `hubOrigin` matches this hub | yes |
|
|
712
|
+
| 6 | plugin | the Claude Code `owenloop` plugin is installed | **no** (rendered only) |
|
|
713
|
+
|
|
714
|
+
Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
|
|
715
|
+
<origin>`, re-run setup's Replace, and so on). doctor never short-circuits — a
|
|
716
|
+
machine with no working human credential still renders lines 3–6, degrading
|
|
717
|
+
honestly rather than dropping them.
|
|
718
|
+
|
|
719
|
+
**Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise. The
|
|
720
|
+
plugin check (6) is *rendered* but does not affect the exit code while the
|
|
721
|
+
marketplace is unpublished.
|
|
722
|
+
|
|
723
|
+
## `mcp` — stdio control-plane server for MCP hosts
|
|
724
|
+
|
|
725
|
+
`owenloop mcp` is a long-running server that exposes the hub's **human control
|
|
726
|
+
plane** to a local MCP host (Claude Code, or any client that speaks MCP over
|
|
727
|
+
stdio). This is the `owenloop-cli-mcp` surface: an MCP host spawns it as a
|
|
728
|
+
subprocess — **you do not run it yourself at a prompt**. It reads
|
|
729
|
+
newline-delimited JSON-RPC 2.0 on stdin, translates each `tools/call` into one
|
|
730
|
+
authenticated HTTPS request to the hub's `/api/*` REST mirror, and writes the
|
|
731
|
+
JSON-RPC reply on stdout. It runs until stdin closes (EOF), then exits `0`.
|
|
732
|
+
|
|
733
|
+
It authenticates as the logged-in **human**, using the same stored credential
|
|
734
|
+
`login` writes and the same locked OAuth-refresh path the other hub commands
|
|
735
|
+
use. It is never interactive: it never opens a browser and never starts a
|
|
736
|
+
loopback listener. If no human credential is stored, a tool call returns an
|
|
737
|
+
error telling you to run `owenloop login --hub <origin>` in a terminal and retry
|
|
738
|
+
(see [Authentication and secrets](#authentication-and-secrets) below).
|
|
739
|
+
|
|
740
|
+
### Choosing the hub origin
|
|
741
|
+
|
|
742
|
+
`owenloop mcp` binds to exactly one hub origin, resolved in this order:
|
|
743
|
+
|
|
744
|
+
1. `--hub <url>` flag.
|
|
745
|
+
2. `OWENLOOP_HUB` env var.
|
|
746
|
+
3. If the **file** credential backend holds exactly ONE hub with a valid `human`
|
|
747
|
+
credential, that hub is used.
|
|
748
|
+
4. Otherwise it exits `2` and prints why to stderr (nothing is written to
|
|
749
|
+
stdout — stdout is the protocol channel).
|
|
750
|
+
|
|
751
|
+
There is **no** silent default-hub fallback: a control-plane server must never
|
|
752
|
+
bind to a hub you did not name. The exit-`2` messages name both remedies:
|
|
753
|
+
|
|
754
|
+
- No hub credentials stored → `run \`owenloop login --hub <origin>\` first, or pass --hub <origin>`.
|
|
755
|
+
- More than one hub stored → the message lists every stored origin and says `pass --hub <origin>`.
|
|
756
|
+
- The credential store cannot be enumerated (macOS Keychain or an external
|
|
757
|
+
credential command) → `pass --hub <origin> (or set OWENLOOP_HUB)`. Only the
|
|
758
|
+
file backend can list stored origins, so on a Keychain-backed machine `mcp`
|
|
759
|
+
effectively requires `--hub` or `OWENLOOP_HUB`.
|
|
760
|
+
|
|
761
|
+
A malformed `--hub`/`OWENLOOP_HUB` value is a normal exit-`1` error, like every
|
|
762
|
+
other command.
|
|
763
|
+
|
|
764
|
+
### Tools
|
|
765
|
+
|
|
766
|
+
The server exposes 17 baseline tools mirroring the hub's own MCP toolset, plus
|
|
767
|
+
`create_agent`. Each baseline tool's result is the hub REST response as one text
|
|
768
|
+
block; a non-2xx response comes back as an error result.
|
|
769
|
+
|
|
770
|
+
| tool | what it does |
|
|
771
|
+
|---|---|
|
|
772
|
+
| `whats_next` | tick a workflow and get the next work order(s), or the inbox of started instances |
|
|
773
|
+
| `submit` | submit a work order output |
|
|
774
|
+
| `reject_artifact` | send an upstream artifact back to its producer with a reason |
|
|
775
|
+
| `provide_input` | answer a human gate — provide a value for a seeded/owed input |
|
|
776
|
+
| `start_run` | create a new instance from a definition name |
|
|
777
|
+
| `create_workflow` | parse + load a workflow def YAML (the authoring hard gate) |
|
|
778
|
+
| `get_workflow` | fetch one loaded definition |
|
|
779
|
+
| `list_workflows` | names, titles, step counts, and def hash/version of every loaded def |
|
|
780
|
+
| `get_status` | `engine.status` verbatim plus a plain-English rendering |
|
|
781
|
+
| `heartbeat` | touch the liveness timestamp on an open run so it is not reaped mid-step |
|
|
782
|
+
| `get_order` | re-fetch the persisted order packet and lease state for a run you hold |
|
|
783
|
+
| `release` | give back a claim so its order is re-offered without waiting out the reap TTL |
|
|
784
|
+
| `publish_event` | publish an event against a contract, starting one run per matched subscription |
|
|
785
|
+
| `list_subscriptions` | the org's contract subscriptions |
|
|
786
|
+
| `presence_ping` | register/refresh this conductor in the presence registry |
|
|
787
|
+
| `list_conductors` | your principal's registered conductors and their online/offline state |
|
|
788
|
+
| `wake` | cheap "has anything changed since cursor X" pre-check for a polling loop |
|
|
789
|
+
| `create_agent` | create a NEW agent identity and store its credential locally — **never returns the token** |
|
|
790
|
+
|
|
791
|
+
`create_agent {name, pools?}` mints a fresh agent identity on the hub with
|
|
792
|
+
`work` scope, then writes the minted `olp_` token straight to this machine's
|
|
793
|
+
credential store (slot `agent:<name>`). The token is **never** returned in the
|
|
794
|
+
tool result, printed, or logged — the result is `{name, pools, stored: true}`,
|
|
795
|
+
built from scratch. It refuses a name that is already taken (the hub's error
|
|
796
|
+
message is surfaced verbatim; error bodies never carry tokens). If the store
|
|
797
|
+
write fails, the result says so and tells you to revoke/re-key the agent from
|
|
798
|
+
the console.
|
|
799
|
+
|
|
800
|
+
One further tool, `stage_enrollment`, is **conditionally** registered — it
|
|
801
|
+
appears only when the hub advertises the staging endpoint (or when
|
|
802
|
+
`OWENLOOP_MCP_ENROLLMENT=1` forces it on). It returns a join code the new agent
|
|
803
|
+
redeems; a join code is transferred authority, not a credential, so it is safe
|
|
804
|
+
to surface in a tool result. When the endpoint is absent, the tool is hidden
|
|
805
|
+
(fail-closed).
|
|
806
|
+
|
|
807
|
+
### Authentication and secrets
|
|
808
|
+
|
|
809
|
+
Every tool call re-reads the stored `human` credential, refreshes it through the
|
|
810
|
+
shared locked OAuth path if it is near expiry, and attaches it only as the
|
|
811
|
+
`Authorization` header — the bearer never rides a tool result. Minted agent
|
|
812
|
+
tokens (`create_agent`) are written to the local credential store and **never
|
|
813
|
+
appear in any tool result, stderr line, or log**. If authentication fails
|
|
814
|
+
(missing credential, refresh failure, or a final 401), the tool returns an error
|
|
815
|
+
result whose text names the fix — run `owenloop login --hub <origin>` in a
|
|
816
|
+
terminal — rather than prompting; the server itself never authenticates
|
|
817
|
+
interactively.
|
|
818
|
+
|
|
819
|
+
### Environment knobs
|
|
820
|
+
|
|
821
|
+
| variable | effect |
|
|
822
|
+
|---|---|
|
|
823
|
+
| `OWENLOOP_HUB` | hub origin when `--hub` is absent (rung 2 of origin resolution) |
|
|
824
|
+
| `OWENLOOP_MCP_ENROLLMENT` | `1` forces `stage_enrollment` on, `0` off; unset = probe the hub |
|
|
825
|
+
| `OWENLOOP_MCP_PROBE_TIMEOUT_MS` | deadline for the `stage_enrollment` capability probe (default `3000`) |
|
|
826
|
+
| `OWENLOOP_HUB_TIMEOUT_MS` | per-request hub timeout (shared with the other hub commands) |
|
|
827
|
+
| `OWENLOOP_CRED_LOCK_WAIT_MS` / `OWENLOOP_CRED_LOCK_POLL_MS` | credential-lock wait/poll knobs (shared) |
|
|
828
|
+
|
|
433
829
|
## Hand-driven walkthrough
|
|
434
830
|
|
|
435
831
|
The [`examples/workflows`](../examples/workflows) folder has a workflow per
|
package/docs/design.md
CHANGED
|
@@ -933,10 +933,71 @@ agents:**
|
|
|
933
933
|
## §25 The model checker (`owenloop check`) — scope
|
|
934
934
|
|
|
935
935
|
`owenloop check <def>` (see `cli.ts` usage) runs a bounded reachability
|
|
936
|
-
search over `applyOutcome` transitions in `model.ts`, looking for
|
|
937
|
-
deadlocks, stuck artifacts, dead steps, and violations of any
|
|
938
|
-
invariants. It is a static analysis of a workflow definition's
|
|
939
|
-
simulation of a running instance.
|
|
936
|
+
search over `applyOutcome` transitions in `model.ts`, looking for stall
|
|
937
|
+
states, true deadlocks, stuck artifacts, dead steps, and violations of any
|
|
938
|
+
declared invariants. It is a static analysis of a workflow definition's
|
|
939
|
+
shape, not a simulation of a running instance.
|
|
940
|
+
|
|
941
|
+
**Stall states vs true deadlocks.** A reachable, non-done state with zero
|
|
942
|
+
eligible firings is classified into exactly ONE of two mutually exclusive
|
|
943
|
+
buckets, by recomputing eligibility as if every freeze were lifted
|
|
944
|
+
(`eligibleFirings(def, arts, undefined, { ignoreFreeze: true })` — "unlimited
|
|
945
|
+
attempts," i.e. what a human `retry` grants):
|
|
946
|
+
- **stall state** (`report.stallStates`) — the recompute yields >= 1 firing:
|
|
947
|
+
the state's ONLY blocker is a frozen/stalled debt — `maxAttempts` reached
|
|
948
|
+
(`isStalled`, §6), `maxSchemaFailures` reached (`isSchemaStalled`, §6/§18),
|
|
949
|
+
or held (`isHeld`, §20). Lifting the freeze re-arms a producer, so the
|
|
950
|
+
line COULD move. This is a by-design human-escalation brake — EXPECTED,
|
|
951
|
+
never a defect, and it never affects the exit code.
|
|
952
|
+
- **true deadlock** (`report.deadlocks`) — the recompute STILL yields zero
|
|
953
|
+
firings: no producer would re-arm even at unlimited attempts. A genuine
|
|
954
|
+
structural dead-end (e.g. a `group:`-blocked or ungreen-input state, or an
|
|
955
|
+
owed input with no producer). This is folded into `hasDefiniteDefect` and
|
|
956
|
+
makes `check` exit nonzero — but only when the search was exhaustive
|
|
957
|
+
(`!report.bounded`), since a tight `--max-collection`/`--max-states` cap
|
|
958
|
+
can otherwise manufacture a spurious no-moves state.
|
|
959
|
+
|
|
960
|
+
The freeze-lift recompute ONLY lifts the `frozen()` guard — it does not
|
|
961
|
+
bypass group-exclusivity (`groupBlockingWinner`), input-green gates, or
|
|
962
|
+
`isDebt`. A state blocked by a group winner or an ungreen input classifies as
|
|
963
|
+
a true deadlock, not a stall state, even if some artifact elsewhere also
|
|
964
|
+
happens to be frozen.
|
|
965
|
+
|
|
966
|
+
Separately, `report.stuck` records reachable states that have a stalled
|
|
967
|
+
debt (`maxAttempts`/`maxSchemaFailures`/held) BUT still have >= 1 eligible
|
|
968
|
+
firing — a brake tripped on one branch while the line can still move on
|
|
969
|
+
another. This is informational only, never a defect on its own, and a
|
|
970
|
+
no-moves state is never listed here (it lands in `stallStates` or
|
|
971
|
+
`deadlocks` instead) — so no single state is ever double-listed across
|
|
972
|
+
`stuck`, `stallStates`, and `deadlocks`.
|
|
973
|
+
|
|
974
|
+
Dead steps — a step name that never appears as a firing in any explored
|
|
975
|
+
transition — are split into two categories with different severity, via a
|
|
976
|
+
static `canEverFire(step, def)` check (`model.ts`) that needs no search
|
|
977
|
+
bounds at all:
|
|
978
|
+
- **structurally dead** (`report.structurallyDeadSteps`) — `canEverFire` is
|
|
979
|
+
false: the step can NEVER fire, regardless of `--max-depth`/
|
|
980
|
+
`--max-states`. This is a genuine wiring defect (e.g. a reduce-mode step
|
|
981
|
+
with no singleton produce to discharge). It is always a *definite*
|
|
982
|
+
finding — bounds-independent by construction — so it is folded into
|
|
983
|
+
`hasDefiniteDefect` and makes `check` exit nonzero, the same way an
|
|
984
|
+
invariant violation does.
|
|
985
|
+
- **unreached within bounds** (`report.unreachedSteps`) — `canEverFire` is
|
|
986
|
+
true: the step CAN fire in principle, but the bounded search didn't reach
|
|
987
|
+
it before exhausting `--max-states`/`--max-depth`. This is informational
|
|
988
|
+
only, a bounds artifact — it does NOT affect the exit code. Raising the
|
|
989
|
+
search bounds may surface the step firing.
|
|
990
|
+
|
|
991
|
+
`canEverFire` is a sound detector of deadness: it only reports a step as
|
|
992
|
+
structurally dead when certain no firing can ever be pushed for it (mirrors
|
|
993
|
+
`eligibleFirings`'s discharge-set logic per step mode); when uncertain it
|
|
994
|
+
defaults to "can fire," so a step is never wrongly flagged as a wiring
|
|
995
|
+
defect. Most structurally-dead shapes are already caught earlier as hard
|
|
996
|
+
errors by `validateDef` (which `check` runs first and throws on) — the
|
|
997
|
+
residual case `canEverFire` exists to catch is a reduce-mode step whose
|
|
998
|
+
`produces:` has zero singleton entries (and no collection produce either,
|
|
999
|
+
so `validateDef`'s reduce check doesn't trip), which reaches `modelCheck`
|
|
1000
|
+
silently dead.
|
|
940
1001
|
|
|
941
1002
|
Two things it deliberately does not model, and why: **born-rejected
|
|
942
1003
|
commits** — a stale-CAS refusal (§12.2, §24.4) is a refusal, not a state
|
|
@@ -950,14 +1011,27 @@ either of these — it answers "is this graph structurally sound," not "can a
|
|
|
950
1011
|
human or a stale commit route around a stall." See README's Testing section
|
|
951
1012
|
for how `owenloop check` fits alongside the test suite.
|
|
952
1013
|
|
|
953
|
-
The checker also has no runtime `provide` values, so
|
|
954
|
-
|
|
955
|
-
|
|
956
|
-
always supplies via `provide`
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
|
|
1014
|
+
The checker also has no runtime `provide` values, so a `seedOwed: true`
|
|
1015
|
+
input has no transition that can green it on its own — without seeding it
|
|
1016
|
+
green some other way, it starts owed and can manufacture a false depth-0
|
|
1017
|
+
deadlock for a def whose inputs the operator always supplies via `provide`
|
|
1018
|
+
at `create` time. `CheckOptions.assumeProvided` (library level, when calling
|
|
1019
|
+
`modelCheck` directly) controls this and **defaults to `false`** — that
|
|
1020
|
+
library default is unchanged by the CLI change below, and is what the
|
|
1021
|
+
`modelCheck` unit tests calling it directly still rely on.
|
|
1022
|
+
|
|
1023
|
+
`owenloop check` (the CLI command), however, now defaults to
|
|
1024
|
+
`assumeProvided: true` — seedOwed inputs are seeded green by default,
|
|
1025
|
+
modeling "the operator already ran `provide` at `create`." This dissolves
|
|
1026
|
+
the false depth-0 deadlock for the common case without the flag. Pass
|
|
1027
|
+
`--strict-inputs` to opt back out to the seedOwed-starts-owed behavior; when
|
|
1028
|
+
that's the *sole* reason for an initial-state deadlock, `owenloop check`
|
|
1029
|
+
also prints a one-line hint naming the responsible seedOwed input(s) and
|
|
1030
|
+
pointing at re-running without `--strict-inputs`. `--assume-provided` is
|
|
1031
|
+
still accepted (never errors) but is now redundant with the default; if both
|
|
1032
|
+
`--strict-inputs` and `--assume-provided` are passed, `--strict-inputs` wins.
|
|
1033
|
+
In all cases, seeding only affects the initial seed — a genuine deadlock
|
|
1034
|
+
reachable past the inputs is still reported.
|
|
961
1035
|
|
|
962
1036
|
## §26 Declarative exclusive produce-groups (`group:`)
|
|
963
1037
|
|
package/docs/embedding.md
CHANGED
|
@@ -262,6 +262,64 @@ all the shared types (`Order`, `CommitResult`, `WorkflowStatus`, `WorkflowDef`,
|
|
|
262
262
|
`EngineEvent`, `EngineListener`, …). For most hosts, `createEngine` + the engine methods + the `Order` /
|
|
263
263
|
`CommitResult` / `WorkflowStatus` types are the whole surface you need.
|
|
264
264
|
|
|
265
|
+
The index also exports a **credential surface** for hosts that need to read,
|
|
266
|
+
write, or refresh a stored hub credential through owenloop's own store logic
|
|
267
|
+
instead of duplicating it. The read entry is `readStoredCredential(origin, opts)`,
|
|
268
|
+
which returns the `Credential`
|
|
269
|
+
for a hub origin **and slot** (or `null` if none is stored), using the same
|
|
270
|
+
backend selection as the CLI — macOS Keychain, or the `0600` credentials file
|
|
271
|
+
elsewhere / with `OWENLOOP_NO_KEYCHAIN=1` (see
|
|
272
|
+
[where the credential lands](cli.md#hub-login--connect--push--logout)). The
|
|
273
|
+
backend is chosen once and a keychain-backed read never falls through to the
|
|
274
|
+
file; a corrupt keychain entry reads as absent. The origin is normalized with
|
|
275
|
+
the exported `normalizeOrigin` (invalid or plaintext-remote origins throw,
|
|
276
|
+
exactly as in the CLI), and `ReadStoredCredentialOpts` lets tests and hosts
|
|
277
|
+
inject `env` and a `Keychain` backend — whose `get`/`set`/`delete` now take
|
|
278
|
+
`(service, account)`, the account being the slot.
|
|
279
|
+
|
|
280
|
+
`opts` is required, and carries the slot selector: `{ principal: 'human' }` or
|
|
281
|
+
`{ principal: 'agent', account?: string }` (`account` defaults to `'default'`,
|
|
282
|
+
and is only meaningful for `'agent'`). The companion exports `credentialSlot`
|
|
283
|
+
(selector → the canonical slot string `human` / `agent:<account>`, throwing on
|
|
284
|
+
an invalid account name) and `keychainServiceFor` (normalized origin → the
|
|
285
|
+
keychain service name) let a host address the same slots the CLI does without
|
|
286
|
+
re-deriving the keying. Slots never fall back to one another: an empty
|
|
287
|
+
`agent:ci` reads as `null` even when `human` is populated. The function never
|
|
288
|
+
logs or echoes the secret.
|
|
289
|
+
|
|
290
|
+
The write entries let a host store or refresh a credential the same way the CLI
|
|
291
|
+
does, addressing the same slots. All three are **async** and take a `CredentialIO`
|
|
292
|
+
(`{ env, keychain?, fetch? }` — a strict subset of the CLI's own io, so the CLI
|
|
293
|
+
passes its `io` unchanged):
|
|
294
|
+
|
|
295
|
+
- `storeCredential(io, origin, slot, credential)` — writes a credential into a
|
|
296
|
+
slot, merging with the other slots on the same origin (the file backend keeps
|
|
297
|
+
`human` when you write `agent:ci`).
|
|
298
|
+
- `deleteCredential(io, origin, slot)` — removes one slot.
|
|
299
|
+
- `ensureFreshOAuth(io, origin, slot, credential)` — returns the credential if
|
|
300
|
+
it is still fresh (more than 60s from expiry), otherwise refreshes the OAuth
|
|
301
|
+
token over the network and persists the rotated result, returning it.
|
|
302
|
+
|
|
303
|
+
`storeCredential`, `deleteCredential`, and the persist inside `ensureFreshOAuth`
|
|
304
|
+
serialize through the `credentials.lock` file described in
|
|
305
|
+
[where the credential lands](cli.md#hub-login--connect--push--logout): a
|
|
306
|
+
concurrent refresh adopts a token another process already rotated rather than
|
|
307
|
+
double-refreshing and clobbering it. When `OWENLOOP_CREDENTIAL_COMMAND` is set,
|
|
308
|
+
that command owns the credential lifecycle — `storeCredential`/`deleteCredential`
|
|
309
|
+
refuse to write, and `ensureFreshOAuth` refreshes over the network without
|
|
310
|
+
persisting. `login`/`logout` are still the CLI's way to store or remove a
|
|
311
|
+
credential; these exports are the programmatic equivalent for a host embedding
|
|
312
|
+
the engine.
|
|
313
|
+
|
|
314
|
+
One behaviour to handle: when the user has set `OWENLOOP_CREDENTIAL_COMMAND` (an
|
|
315
|
+
external command that supplies the credential, ahead of both stores — see
|
|
316
|
+
[where the credential lands](cli.md#hub-login--connect--push--logout)),
|
|
317
|
+
`readStoredCredential` consults that command instead of any store, and a failing
|
|
318
|
+
command **throws** rather than returning `null`. So in that mode `null` still
|
|
319
|
+
means "no credential", but an exception means "the configured command could not
|
|
320
|
+
produce one" — surface its message rather than treating it as an empty slot,
|
|
321
|
+
because falling back to a local store is exactly what the setting forbids.
|
|
322
|
+
|
|
265
323
|
`SUPPORTED_ENGINE_VERSION` is the programmatic form of the design.md §27
|
|
266
324
|
engine-version contract — the highest `engine:` a def may declare and still load.
|
|
267
325
|
Tooling can preflight-check a def's `engine:` field against it before handing the
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "owenloop",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.1",
|
|
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",
|