owenloop 0.5.14 → 0.5.16

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/docs/cli.md CHANGED
@@ -106,7 +106,7 @@ is independent of the `SEARCH INCOMPLETE` bounds notice.
106
106
  | `work <subcommand> [options]` | run the execution-side CLI companion — see [`work`](#work--execution-side-cli-companion) |
107
107
  | `util modifier-init --default <value>` | choose a modifier from rejection feedback, the order hint, or a default; intended for command steps |
108
108
  | `trust init\|grant\|revoke` | create and sign local enrollment trust records offline — see [`trust`](#trust--local-enrollment-trust) |
109
- | `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
109
+ | `create <def> [--title t] [--provide name=json …] [--param k=v …]` | create a local SQLite instance in the selected `--db` store; prints `{workflow}` |
110
110
  | `provide <wf> <name> [--value json] [--hub <url>]` | supply a seeded input after the fact; `--hub` targets a hosted workflow |
111
111
  | `tick <wf> [--now=<ms>] [--shallow] [--capability <l>]…` | claim and emit eligible **orders** (the jobs to run); deep by default — also descends into live `calls:` children (`--shallow` = this instance only); repeatable `--capability` claims steps without capabilities plus matching-capability steps — see below |
112
112
  | `reap <wf> [--now]` | run the reaper; `--now` forces every claim stale (TTL 0) — see below |
@@ -114,6 +114,7 @@ is independent of the `SEARCH INCOMPLETE` bounds notice.
114
114
  | `status <wf>` | derived view: `done`, `debts`, `eligible`, `blocked`, `inFlight` |
115
115
  | `wait <wf> --until eligible\|done [--timeout <dur>]` | block until engine state matches, then print `status` |
116
116
  | `show <wf>` | dump raw artifacts (debugging) |
117
+ | `trace <wf> [--format text\|json]` | read the local causal timeline and artifact biographies from the selected store; JSON is the default and both formats are local-store reads |
117
118
  | `list` | list instances |
118
119
  | `green <wf> <run> <path> [--value json] [--terminal]` | accept an owed output |
119
120
  | `emit <wf> <run> --items '[{…},{…}]'` | add collection elements |
@@ -126,6 +127,20 @@ is independent of the `SEARCH INCOMPLETE` bounds notice.
126
127
  | `delete <wf>` | delete an instance and all its rows |
127
128
  | `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
128
129
 
130
+ ### Local versus hosted instances
131
+
132
+ `create`, `tick`, `list`, `runs`, `status`, `show`, and `trace` are the local
133
+ engine path. `create` creates a local SQLite workflow instance; it does not
134
+ copy or expose the history of an existing hub run. `start` is the authenticated
135
+ hub path for creating a published workflow.
136
+
137
+ Every local invocation must resolve the same runtime database and definitions.
138
+ Repeat `--db` and `--defs` on each command, or set stable `OWENLOOP_DB` and
139
+ `OWENLOOP_DEFS` values. `list` returning `[]` means only that the selected
140
+ database has no instances. Changing the database selector can legitimately
141
+ produce `[]` or “workflow not found”; changing the definitions selector can
142
+ leave a stored workflow's definition unresolvable.
143
+
129
144
  Without `--hub`, `provide` and `reject` use the local SQLite engine exactly as
130
145
  before. With `--hub`, they operate on the project-bound (or explicitly named)
131
146
  hosted workflow and use the logged-in human credential; the explicit hub must
@@ -323,6 +338,15 @@ Untargeted inbox polling and sibling workflows continue, but command work in a
323
338
  cooled workflow can wait until its cooldown expires. This shift-local damper
324
339
  is separate from `--local-queue-hold` and from server `Retry-After` backoff.
325
340
 
341
+ **Fleet inbox filtering.** In org-wide mode, after the untargeted inbox
342
+ response, the shift skips a workflow only when its `eligible` value is exactly
343
+ the number `0`; missing, malformed, or nonzero values still receive a targeted
344
+ `whats_next` call. An explicit `--workflow` always receives its targeted call.
345
+ An inbox-only skip is not counted as a successful targeted observation, so it
346
+ cannot by itself make the work-directory reaper scan or remove that workflow's
347
+ directories. Work that becomes eligible after the inbox snapshot is picked up
348
+ on a later poll.
349
+
326
350
  **On-disk logs.** A running shift appends its dispatch record to
327
351
  `<log-dir>/shift.log` as JSON Lines, and gives each dispatched worker's stdout
328
352
  and stderr their own `<log-dir>/<run>.log`. Both files outlive the shift
@@ -654,11 +678,24 @@ The execution settings file is `<config>/settings.json` (see
654
678
  | `prepare <workflow> [--origin <url>]` | fetch, cache, and normalize step specs |
655
679
  | `lint <workflow-name \| path>` | lint `x.harness` option bags in a workflow definition |
656
680
  | `sessions [--all] [--json]` | list recorded harness sessions and how to reopen them |
681
+ | `approvals [--origin <url>] [--json]` | list every tool call a worker is currently blocked on, waiting for a person |
682
+ | `approvals approve <wf>/<run> <tool-use-id> [--origin <url>] [--note <text>]` | approve one still-pending tool call; the answer returns to that blocked call |
683
+ | `approvals deny <wf>/<run> <tool-use-id> [--origin <url>] [--note <text>]` | deny one still-pending tool call; the answer returns to that blocked call |
657
684
  | `release --session <id> [options]` | drain a session's held claims |
658
685
  | `settings` | print the resolved execution settings file |
659
686
  | `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
660
687
  | `util modifier-init --default <value>` | print the requested modifier from `OWENLOOP_FEEDBACK`, else `OWENLOOP_MODIFIER`, else the required default |
661
688
 
689
+ `work approvals` distinguishes a worker that is still running and waiting on a
690
+ tool decision from a pending input gate or an `ask` that ends the current run.
691
+ Listing uses the agent credential selected by `OWENLOOP_ACCOUNT` (default
692
+ `default`). `approve` and `deny` always use the stored `human` credential,
693
+ ignore `OWENLOOP_ACCOUNT` and `OWENLOOP_TOKEN`, and require
694
+ `owenloop login --hub <origin> --as human` when that slot is absent. They never
695
+ mint or log credentials. If the stored human credential is an expiring OAuth
696
+ credential, the decision path may refresh it and persist a rotated token under
697
+ the shared credential lock before answering the hub.
698
+
662
699
  ### `util modifier-init`
663
700
 
664
701
  `owenloop util modifier-init --default <value>` is a deterministic helper for
@@ -2718,7 +2755,8 @@ The plugin step probes and, when needed, converges the bundled `owenloop` plugin
2718
2755
  for each available harness: Claude Code and Codex. Plugin convergence is
2719
2756
  non-fatal and setup continues when a harness is missing, the bundled marketplace
2720
2757
  root is unavailable, or a plugin command fails. A second run with the expected
2721
- plugin version already installed performs no plugin writes. The steps:
2758
+ plugin version already installed performs no plugin writes when its effective
2759
+ MCP launch is verified safe. The steps:
2722
2760
 
2723
2761
  1. **inspect** — read-only report of what's already present (human credential,
2724
2762
  execution settings, `claude` and `codex` on PATH, agent slots). No writes.
@@ -2745,16 +2783,23 @@ plugin version already installed performs no plugin writes. The steps:
2745
2783
  it reports that file as skipped and leaves its bytes untouched. If setup does
2746
2784
  not know any crews for the identity, it records a non-fatal noted result.
2747
2785
  7. **plugin** — probe and converge the bundled `owenloop` plugin separately
2748
- for Claude Code and Codex. When the installed plugin is missing or its
2749
- version differs from the CLI package, setup adds the bundled marketplace
2750
- when needed and installs or updates the plugin. Claude Code uses
2786
+ for Claude Code and Codex. Setup verifies the installed MCP declaration
2787
+ itself: it must run exactly `owenloop mcp` through `PATH`; Codex must also
2788
+ pass `PATH` through to that subprocess, and the current environment must
2789
+ resolve an executable `owenloop`. When the installed plugin is missing, its
2790
+ version differs from the CLI package, or its launch is known unsafe, setup
2791
+ adds the bundled marketplace when needed and installs or updates the plugin.
2792
+ Claude Code uses
2751
2793
  `claude plugin install` for a fresh install and `claude plugin update` for
2752
2794
  an existing plugin. Codex uses `codex plugin add owenloop@owenloop` for both
2753
2795
  fresh installs and upgrades; setup does not call
2754
2796
  `codex plugin marketplace upgrade`, which applies only to Git marketplaces.
2755
2797
  **Non-fatal:** a missing harness or failed convergence is reported as
2756
- `noted` and never fails setup. If the bundled marketplace root is
2757
- unavailable, setup prints manual commands instead.
2798
+ `noted` and never fails setup. Unverifiable launch metadata is reported by
2799
+ doctor but does not cause repeated setup writes. An absolute marketplace,
2800
+ cache, install, or source location is not unsafe by itself—the effective
2801
+ command and arguments determine the verdict. If the bundled marketplace root
2802
+ is unavailable, setup prints manual commands instead.
2758
2803
  8. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
2759
2804
  the same surfaces, whose result becomes setup's exit code.
2760
2805
 
@@ -2938,15 +2983,25 @@ The checks, in order:
2938
2983
  | 3 | agent slot | an `agent:<name>` credential is stored | yes |
2939
2984
  | 4 | agent plane | that agent credential verifies live against the hub | yes |
2940
2985
  | 5 | execution settings | the settings file's `hubOrigin` matches this hub | yes |
2941
- | 6 | plugin (claude-code) | the Claude Code `owenloop` plugin is installed at the package version | **no** (rendered only) |
2942
- | 7 | plugin (codex) | the Codex `owenloop` plugin is installed at the package version | **no** (rendered only) |
2986
+ | 6 | plugin (claude-code) | the Claude Code `owenloop` plugin is at the package version and its effective launch resolves as `owenloop mcp` through PATH | **no** (rendered only) |
2987
+ | 7 | plugin (codex) | the Codex `owenloop` plugin is at the package version, launches `owenloop mcp` through PATH, and passes PATH through | **no** (rendered only) |
2943
2988
 
2944
2989
  The plugin checks also report the detected harness CLI version. An installed
2945
2990
  plugin whose version cannot be parsed is reported as `version unknown` and is
2946
2991
  not treated as a failure. A parsed plugin version that differs from the
2947
2992
  package version is reported as version skew with the remedy `run owenloop
2948
- setup`. A missing harness reports that the harness is not on `PATH`; a missing
2949
- plugin reports the harness-specific marketplace and install command.
2993
+ setup`. Doctor also reads each installed plugin's effective MCP declaration:
2994
+ an absolute or worktree command, alternate arguments, missing Codex PATH
2995
+ pass-through, or a missing executable `owenloop` on PATH is launch drift even
2996
+ when versions currently match. Missing or malformed launch metadata is rendered
2997
+ as explicitly unverifiable rather than guessed safe. Absolute marketplace,
2998
+ cache, install, and source paths are harness storage locations and are not by
2999
+ themselves launch drift. A missing harness reports that the harness is not on
3000
+ `PATH`; a missing plugin reports the harness-specific marketplace and install
3001
+ command. Unsafe declarations are summarized by command shape and argument
3002
+ count; doctor does not echo manifest values, which may contain credentials.
3003
+ `owenloop setup` repairs a known unsafe declaration through its existing
3004
+ non-fatal convergence flow.
2950
3005
 
2951
3006
  Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
2952
3007
  <origin>`, re-run setup's Replace, and so on). doctor never short-circuits — a
@@ -2977,8 +3032,11 @@ error telling you to run `owenloop login --hub <origin>` in a terminal and retry
2977
3032
  ### Plugin/CLI version alignment
2978
3033
 
2979
3034
  The shipped Claude Code and Codex plugins launch `owenloop mcp` from `PATH` and
2980
- carry the plugin version in `.mcp.json` as `OWENLOOP_PLUGIN_VERSION`. The MCP
2981
- server compares that expected version with its own package version on every
3035
+ carry the plugin version in `.mcp.json` as `OWENLOOP_PLUGIN_VERSION`; Codex also
3036
+ explicitly passes `PATH` through to the subprocess. Doctor verifies that
3037
+ effective installed launch shape as well as version equality, so a same-version
3038
+ absolute or worktree launch declaration is reported as drift. The MCP server
3039
+ still compares that expected version with its own package version on every
2982
3040
  recognized `tools/call`. The comparison is strict equality: a mismatch returns
2983
3041
  a tool error that names both versions and says `Run: owenloop setup`. The
2984
3042
  server does not reject the MCP startup handshake, so the diagnostic reaches the
@@ -3242,15 +3300,20 @@ owenloop() { node bin/owenloop.mjs "$@"; } # or `npm link` to put it on PATH
3242
3300
 
3243
3301
  owenloop defs # what workflows are available
3244
3302
 
3245
- # start an instance; `proposal` is seeded as owed, so we provide it up front
3303
+ # create a local instance; `proposal` is seeded as owed, so we provide it up front
3246
3304
  wf=$(owenloop create delivery \
3247
3305
  --provide proposal='{"text":"add dark mode"}' | jq -r .workflow)
3248
3306
 
3307
+ owenloop list # includes $wf in this local database
3308
+
3249
3309
  # the Step Agent loop: tick → run → report
3250
3310
  run=$(owenloop tick $wf | jq -r '.orders[0].run') # claim the planner job
3251
3311
  owenloop green $wf $run plan --value '{"plan":"…"}' # report its output
3312
+ owenloop close "$wf" "$run" # complete the planner firing
3252
3313
 
3253
3314
  owenloop status $wf # done / debts / eligible / blocked / pending / inFlight
3315
+ owenloop trace "$wf" # local causal timeline as JSON
3316
+ owenloop trace "$wf" --format text # the same local trace as text
3254
3317
  ```
3255
3318
 
3256
3319
  **A knock-back.** When the reviewer's job comes up, instead of greening its
@@ -38,6 +38,19 @@ tail; for a failed command, the receipt is ask context rather than an artifact.
38
38
  Full streams are represented only by the receipt's output hash and stdout/stderr
39
39
  byte counts.
40
40
 
41
+ ## Capability-silent agent diagnostics
42
+
43
+ Capability-silent `agent-run` attempts write their claim-time
44
+ `CAPABILITY-SILENT` warning and any terminal no-submit diagnostic to worker
45
+ stdout/stderr, so Shift dispatch preserves them in `<run>.log`. The claim
46
+ warning states whether the harness will use its default or an authored step
47
+ model/effort; the terminal message may name the harness-reported runtime model
48
+ and bounded failure context when available. It is intentionally not a
49
+ `shift.log` event and does not add a
50
+ diagnosis to the reason-less targeted hub release. Local logging can still be
51
+ disabled as described below, in which case the worker remains runnable but
52
+ these local diagnostics are not retained.
53
+
41
54
  | Command outcome | Worker channel | Header |
42
55
  | --- | --- | --- |
43
56
  | exit 0 and no machinery error | stdout | `… the command for step 'X' succeeded; its output follows` |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.14",
3
+ "version": "0.5.16",
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.14",
3
+ "version": "0.5.16",
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.14"
10
+ "OWENLOOP_PLUGIN_VERSION": "0.5.16"
11
11
  }
12
12
  }
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.14",
3
+ "version": "0.5.16",
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.14"
9
+ "OWENLOOP_PLUGIN_VERSION": "0.5.16"
10
10
  },
11
11
  "env_vars": [
12
12
  "HOME",