@oddington/cli 0.1.67 → 0.1.69

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/README.md CHANGED
@@ -72,10 +72,11 @@ operation on the API host. The verified member or retained Run supplies authorit
72
72
  the request names the Connection and exact Run ID. Hosted ad hoc execution needs
73
73
  both `OS_CONNECTION_RUN_TOKEN` and `OS_CONNECTION_RUN_ID`.
74
74
  Inbox publication goes directly to the selected workspace's `/api/inbox/check`,
75
- `/api/inbox/publish`, `/api/inbox/resolve` and `/api/inbox/files` operations.
76
- Data and shared Files go directly to their OS owners. Local publication validates
77
- the whole captured set before applying Records, retaining Files and publishing
78
- Asks/Digests; retry resumes the same retained identities and receipts.
75
+ `/api/inbox/publish` and `/api/inbox/resolve` operations. File intake and reads
76
+ use shared Files through `/api/files`.
77
+ Local routine Data reads and writes current schema-governed checkout files.
78
+ Files and Inbox operations complete during the call. A later failure retains
79
+ completed local paths and hosted effects in local Run history.
79
80
 
80
81
  ## Add a Data repository
81
82
 
@@ -194,39 +195,12 @@ and read-only connection availability; starts recheck current source and complet
194
195
  authority. Defaulted `run()` and authorized OS File descriptors use the same
195
196
  local runner as CLI. There is no app-specific child lifecycle.
196
197
 
197
- Run handles expose `current()`, connected `watch()`, retained `step(id)` and
198
- explicit `publish()`. Successful local execution reports `not_needed`, `ready`,
199
- `published` or publication `failed`; it never publishes automatically. Publication
200
- uses the existing guarded publisher and preserves confirmed receipts. Routine
201
- `runs.list()` returns at most 20 recent summaries; `runs.get(id)` opens retained
202
- facts under newly checked authority. Older Runs are not pruned. History and step
203
- detail survive refresh; interrupted execution has no restart recovery.
204
-
205
- The host owns live work across refresh and tab closure. Credential renewal
206
- preserves the logical session; replaced contexts invalidate old handles. Host
207
- stop, sign-out, expiry or authority loss ends active work. At most four starts
208
- occupy authorization/execution/cleanup slots. No browser command, path, workspace,
209
- connection setting, replay cursor or cancellation API is exposed. Local Data
210
- continues to use its exact published index. Browser File creation remains a
211
- separate unsupported local adapter; existing authorized Files may be Run input.
212
-
213
- ## Connections
214
-
215
- A connection gives a workspace controlled access to GitHub, Gmail, Airtable,
216
- or another external service. During the alpha, any workspace member can manage
217
- its connections.
218
-
219
- ### Names and IDs
220
-
221
- Routines use a connection's provider and name:
222
-
223
- ```text
224
- gmail/invoices
225
- airtable/project-management
226
- github/example-organization
227
- ```
228
-
229
- Management commands use the connection ID returned by `list --all`:
198
+ Run handles expose `current()`, connected `watch()` and retained `step(id)`.
199
+ Local summaries retain exact Data paths, safe live effects and Git provenance on
200
+ success and failure. There is no subsequent Run publication. Routine `runs.list()`
201
+ returns at most 20 recent summaries; `runs.get(id)` opens retained facts under the
202
+ established local session. Older Runs are not pruned. Interrupted execution has
203
+ no restart recovery.
230
204
 
231
205
  ```sh
232
206
  os connection list --workspace <workspace> --all
@@ -524,8 +498,8 @@ Editors, unregistered views, prerequisites, legacy record-picker formats and dir
524
498
  and reject explicitly.
525
499
 
526
500
  ```sh
527
- os ask create --workspace <workspace> --file <json> --request-key <key> --json
528
- os digest create --workspace <workspace> --file <json> --request-key <key> --dry-run --json
501
+ os ask create --file <json> --request-key <key> --json
502
+ os digest create --file <json> --request-key <key> --dry-run --json
529
503
  ```
530
504
 
531
505
  The JSON definition supplies title, description, optional questions (ask), and
@@ -543,8 +517,8 @@ import { data, defineHandler, resolveAsk, routinePublicationClient } from '@oddi
543
517
  const inbox = routinePublicationClient();
544
518
  ```
545
519
 
546
- Trusted launches supply workspace, capability and working root. A host publishing
547
- as a member supplies `routinePublicationClient({ workspace, workingRoot, request })`
520
+ Trusted launches supply workspace and capability. A host publishing
521
+ as a member supplies `routinePublicationClient({ workspace, request })`
548
522
  with its authorized member transport. CLI publication commands supply the CLI's
549
523
  signed-in request themselves. Response modules export a `handlers` array and
550
524
  perform no publishing on import. Accepted answers durably queue managed handlers
@@ -558,11 +532,23 @@ const repository = data.repository('general');
558
532
  const records = await repository.records.read(selectedRefs);
559
533
  const changes = repository.changes();
560
534
  changes.update(records[0], { status: 'ready' });
561
- await changes.publish();
535
+ await changes.apply();
562
536
  ```
563
537
 
564
- Local Runs read their own successive proposals and leave ordinary uncommitted
565
- Record files for review. Explicit `os routine publish` sends the logical journal.
538
+ Local Runs read current checkout Records and leave completed Data writes as
539
+ ordinary uncommitted files for review. Hosted effects complete during the call.
540
+
541
+ The human completion summary groups paths under Created, Updated and Deleted,
542
+ counting each file once across the Run. Repeated updates to a new file leave it
543
+ Created. Exact-byte restorations appear under Unchanged, and temporary creations
544
+ that were deleted are listed separately. The comparison spans the Run, including
545
+ all steps; JSON activity still retains the completed operations.
546
+
547
+ Review new files in your editor; Git diffs show edits to tracked files. Completion
548
+ calls out saved files ignored by Git and suggests correcting the ignore rule if
549
+ they should be committed. It does not edit ignore rules, force-add files or alter
550
+ the index. Stage suggestions exclude ignored files and unchanged restorations;
551
+ partial-write recovery keeps its explicit saved/failed/unattempted guidance.
566
552
 
567
553
  OS intersects the routine's declared access with configured workspace
568
554
  capabilities. A new routine runs locally from a customer branch without
@@ -589,8 +575,8 @@ require an explicit authored fix rather than a guessed package file.
589
575
  OS resolves the worktree's stable source identity and the canonical `defineRoutine`
590
576
  export in `routine.ts`. JSON input is validated before business work; its file/stdin
591
577
  path is transport, not business input. Omitted input uses the definition's default,
592
- when supplied. Each JSON value is bounded to 256 KiB. Local publication never
593
- deploys the routine or its handlers.
578
+ when supplied. Each JSON value is bounded to 256 KiB. Running a routine does not
579
+ deploy it or its handlers.
594
580
 
595
581
  To execute the active deployed version on OS, use:
596
582
 
@@ -602,7 +588,7 @@ os routine run invoice-import --remote --input - --json
602
588
  Remote start reads only worktree identity and business input. It neither uploads
603
589
  local source nor creates a local captured change set. It reports the accepted
604
590
  Run's ID, ordered steps, safe summaries and terminal result or failure through the
605
- shared Run handle. Remote Runs omit local publication; their authorized OS changes
591
+ shared Run handle. Remote Runs omit local activity; their authorized OS changes
606
592
  apply during execution. Input/defaults and access come from the deployed definition,
607
593
  and later activation cannot change a started invocation's code. Retained step
608
594
  detail, results and newest-first recent history use the same SDK handle contracts.
@@ -612,41 +598,21 @@ or authority override.
612
598
  Before local execution, the command names declared connections and explains that
613
599
  local filesystem changes, model calls and provider effects happen immediately.
614
600
  Only Record, File, Ask and Digest changes stay local for review. The child
615
- receives temporary scoped authority, which is revoked when execution ends.
616
- Success reports concrete nonzero counts and the stable Run reference:
617
-
618
- ```sh
619
- os routine publish
620
- os routine publish <run>
621
- os routine publish <run> --json
622
- ```
601
+ receives temporary scoped authority for the accepted execution.
623
602
 
624
- Declared records appear in the matched checkout; exact files, captured receipts,
625
- source/input and authored items stay in the private Run directory
626
- `~/.os/<workspace>/runs/<run>`.
627
- `execution.json` retains steps, optional result, redacted child output and known
628
- effect evidence. `complete.json` seals successful intent. Inspect these files and
629
- the bounded Git diff, then publish from the original root. Bare publish lists
630
- ready references and refuses ambiguity. A failed Run cannot publish;
631
- earlier local/provider effects remain real. A successful Run with no OS changes
632
- retains its evidence and says “Nothing needs to be sent to OS.”
603
+ Completed Data writes stay in the checkout, while File uploads and Inbox calls
604
+ are live. The terminal report and retained summary show exact local paths and
605
+ safe hosted references on success and failure. There is no later Run publication.
606
+ `execution.json` retains private bounded diagnostics; `run.json` retains the safe
607
+ summary and separate files retain requested step data.
633
608
 
634
609
  `--json` emits one value on stdout; notices use stderr and child logs stay in
635
- Run evidence. Run output includes `runId`, `state`, `placement`, `changes`,
636
- `counts`, optional declared `result`, and `directory`. Publish output includes
637
- the same Run reference, change state, confirmed receipts, Files, items and links.
638
-
639
- The SDK's `data.repository(name)` collection, selection and search calls also work in
640
- this mode, using only declared workspace repository access and the exact committed
641
- checkout version captured for the run. Dirty and untracked files are ignored;
642
- an OS cache outside the checkout reuses derived data without remote access.
643
- Accepted record effects advance later selections and searches to their exact
644
- proposed version. Validation and another publisher leave the captured view
645
- unchanged; replaying an older publication cannot rewind it. For example,
646
- `general.records.search('acme overdue', { collections: ['invoices'], limit: 20 })`
647
- returns bounded full Records with guards usable in Changes, or empty matches
648
- with the searched version. Missing/incomplete search data fails retryably with
649
- `unavailable`, and a dead parent has no hosted fallback. Authentication and named
610
+ Run evidence. It includes `runId`, `state`, `placement`, optional declared `result`,
611
+ and the retained `run` summary including `local` activity.
612
+
613
+ Data collection, selection and search calls read the schema-governed Markdown
614
+ currently present in declared local repositories. Later calls see completed
615
+ writes and external edits. Authentication and named
650
616
  provider connections retain their normal network and authority requirements;
651
617
  local execution may contact OS or providers.
652
618
 
@@ -659,21 +625,40 @@ Those details are not returned through app summaries. Use SDK 0.1.36 and CLI
659
625
  into a customer routine or an earlier saved Run.
660
626
 
661
627
  AI structured output is validated against the routine's requested schema.
662
- `generateObject` returns a typed object or throws a catchable `RoutineAIError`
628
+ `generateObject` returns a typed object or throws a catchable `AIError`
663
629
  with a clear validation reason and optional original answer text. A routine can
664
630
  inspect the answer, apply its own recovery policy and continue without making
665
631
  the whole Run fail. An uncaught routine or step exception still fails execution.
666
632
 
667
- For a failed Run, local `execution.json` retains the last eight `aiOutputs`,
668
- each linked by `call` to its local AI event and containing at most 8 KiB of
669
- credential-redacted final answer text. Truncation is marked. Successful Runs
670
- retain only rejected-answer samples, including when the routine recovered from
671
- them. The human CLI prints the local evidence location;
672
- shared summaries and JSON command output exclude answer samples. This evidence
673
- excludes prompts, reasoning and provider logs. These changes require an updated
674
- SDK and CLI; earlier versions keep their existing validation behavior.
633
+ Local `execution.json` keeps the last 32 rejected answers, including caught
634
+ failures in successful Runs. Failed Runs additionally keep the last eight final
635
+ answers. Each private sample is credential-redacted, bounded to 8 KiB, and marked
636
+ when truncated; rejected/retained/omitted counts are explicit. Compact per-call
637
+ metadata remains available when a sample was omitted.
638
+
639
+ Inspect one local Run using the active workspace and the login that started it:
675
640
 
676
- Keep an exact stable `@oddington/sdk` 0.1.x patch through 0.1.37 in root
641
+ ```sh
642
+ os routine inspect <run-id> --ai
643
+ os routine inspect <run-id> --ai --json
644
+ os routine inspect <run-id> --ai --show-output 7
645
+ ```
646
+
647
+ Default output includes call, step, operation, outcome, safe validation reason,
648
+ answer size and sample availability. Answer text requires `--show-output <call>`
649
+ even with `--json`. The explicit display shows only that redacted local sample.
650
+ Older Runs may lack validation reasons or omission accounting (`omitted: null`
651
+ in JSON); missing samples
652
+ cannot be reconstructed. Inspection does not resume work or call a model.
653
+
654
+ `AIError` is the public SDK name; `RoutineAIError` remains the same constructor
655
+ as a compatibility alias. Customer catches should preserve safe code/detail/message
656
+ and item identity, keeping `text` private. CLI evidence correlates run/step/call;
657
+ there is no direct customer-item-to-call link in this slice. The [SDK example](https://www.npmjs.com/package/@oddington/sdk)
658
+ shows a typed catch. Shared summaries and ordinary command JSON exclude answer
659
+ samples, prompts, reasoning and provider logs.
660
+
661
+ Keep an exact stable `@oddington/sdk` 0.1.x patch through 0.1.39 in root
677
662
  `devDependencies`, with its declaration, lock and installed package agreeing.
678
663
  Use compatible Node, the selected private ESM manifest and the shared frozen
679
664
  lock. OS verifies only the selected installed graph, stages its confined bytes
@@ -723,36 +708,25 @@ No dependency installation or package script runs. Run state is bounded to
723
708
  renews every 20 seconds with a 90-second lease; execution retains the existing
724
709
  15-minute capability bound.
725
710
 
726
- `routine prepare`, `run --local`, executable/argv selection, routine workspace,
727
- name and working-root flags, and publish `--run` are retired. `os run --connection`
728
- remains the separate ad hoc command; app children still publish immediately.
729
-
730
- `changes.delete(record)` captures the selected `$ref` and `$version`. A mixed
731
- create/update/delete group prepares one guarded proposal; validation creates no
732
- proposal or materialization. Local publication removes only declared Records,
733
- returns their captured identities in `deleted`, and advances subsequent run
734
- reads to the exact prepared version. Files and durable Source uses remain
735
- retained. Deleted paths are sealed as absent: recreating one before
736
- `os routine publish <run>` invalidates publication before effects.
737
- Later publication sends the retained group once to the guarded writer, which
738
- validates its captured intent against the current authoritative head, applies
739
- one ordinary commit and waits for its exact hosted index. Interrupted Git or index
740
- acknowledgements resume that same proposal and preserve the inspected identities.
741
-
742
- Publication admits the member, workspace and Run once, uploads referenced or
743
- explicitly retained local Files with their original IDs, applies Record changes
744
- when present, then publishes Asks in authored order followed by Digests. Each owning operation
745
- validates its own work; a later failure preserves earlier confirmed effects.
746
- A Run without Record changes performs no Git freshness/checkout or Data gate.
747
- Publication preserves unrelated local work. Changed prepared bytes, authority
748
- or conflicting Record history require repair and a new Run; publication never
749
- rebases inspected work.
750
- After interruption, repeat the same publish command with unchanged content.
751
- `publication.json` journals attempted operations and confirmed receipts
752
- separately from sealed intent. Fresh launches resume only unconfirmed work using the original operation, File
753
- and item identities. Confirmed receipts need no second owning-capability call. A published run reports its stored results. A killed owner
754
- leaves `preparing.lock`; inspect its recorded PID and root before removing a
755
- stale lock, and never remove a live owner's lock.
711
+ `routine prepare`, `routine publish`, `run --local`, executable/argv selection,
712
+ and routine workspace, name and working-root flags are retired. `os run --connection`
713
+ remains the separate ad hoc command.
714
+
715
+ Each current local Data operation reads committed, staged, modified and untracked
716
+ schema-governed Markdown. `changes.validate()` writes nothing. `changes.apply()`
717
+ immediately writes the requested local changes; there is no later Run
718
+ publication or prepared repository state. It validates the touched Records,
719
+ paths, authored links and captured versions without auditing unrelated Record
720
+ contents, then applies complete files atomically, one at a time. It retains
721
+ completed paths if a later filesystem operation fails; no rollback or replay occurs.
722
+ Subsequent reads observe completed writes and external edits. Current local Data
723
+ needs no published base, repository-context request or hosted index.
724
+
725
+ Files default to local storage. Explicit remote creation/upload completes live;
726
+ Inbox uploads referenced local Files before returning real hosted item identities.
727
+ Run summaries and CLI output distinguish live effects from exact local Data paths,
728
+ including safe write failures, with path-scoped Git review and staging commands.
729
+ Steps, results/failures and activity remain under `~/.os/<workspace>/runs/<id>`.
756
730
 
757
731
  Installed write grants authorize Data `changes()` for routine Record creates,
758
732
  updates and deletions. The runtime owns retry identity. `routinePublicationClient()`
@@ -761,63 +735,34 @@ their separately injected repository capability and durable execution identity;
761
735
  handler writes use their installation independently of the responder's identity.
762
736
  Customer executable handlers still require an approved managed deployment.
763
737
 
764
- Add an exact file before putting it on an ask or digest. Signed-in members and
765
- routines use `inbox.files.add({ path })` within the configured working root:
738
+ Add a file through shared Files before putting it on an ask or digest:
766
739
 
767
- ```ts
768
- const report = await inbox.files.add({ path: 'output/september.csv' })
769
- await inbox.publishAsk({
770
- // title, description and explicit recipients ...
771
- body: [fileBlock({ label: 'Files', files: [report] })],
772
- }, { requestKey: 'september-review' })
740
+ ```sh
741
+ os files add --file ./output/september.csv --path Statements --json
742
+ os ask create --file ./ask.json --request-key september-review --json
773
743
  ```
774
744
 
775
- Adding preserves bytes and returns an OS-issued `InboxFile`; it does not publish,
776
- attach, or interpret anything. CSV preview is a consumer concern and does not
777
- become File metadata. Unsupported files remain preserved and downloadable.
745
+ The signed-in session selects the active workspace. `--file` names a regular
746
+ file on this computer (relative to the current directory or absolute); `--path`
747
+ is its managed parent and defaults to `Files`. `--storage local|remote` defaults
748
+ to local, and `--name` may override the saved filename. JSON output is one shared
749
+ File descriptor. There is no File delete command or working-root option.
778
750
 
779
- Member-authored files may use `workingRoot` in the SDK, `--working-root` on the
780
- file command, or `OS_INBOX_WORKING_ROOT`. Named routine Runs receive
781
- their resolved worktree root from OS. The file command defaults to the current directory:
751
+ Supply that exact descriptor in a Files block in the Ask or Digest JSON. The
752
+ command uploads a local File before publication, retaining its ID, managed path,
753
+ hash and enrichments; existing remote Files are reused. `--dry-run` checks without
754
+ uploading or publishing. Member publication commands accept no workspace selector
755
+ or attachment paths.
782
756
 
783
- ```sh
784
- os files add --workspace <workspace> --working-root <local-root> --path <relative-file-path> --json
785
- ```
786
-
787
- The returned value goes in `fileBlock({ label, files })`. Record and Records
788
- Blocks may explicitly target named panel Views; files use their native panel.
789
- Paths and resolved symlinks must remain within that working root. Uploads require
790
- current workspace authority; files are visible only through recipient access to
791
- an item containing them.
757
+ Routines use `files.create({ file, name, path })` and
758
+ `fileBlock({ label, files })` from `@oddington/sdk`; Inbox has no separate intake
759
+ API. Blocks retain safe immutable File metadata. Current workspace Files access
760
+ owns bytes, while recipient access governs the Inbox item. CSV preview remains a
761
+ consumer concern; unsupported files remain downloadable.
792
762
 
793
763
  Resolution is an explicit guarded business outcome from a handler or the
794
764
  original publishing routine.
795
765
 
796
- Delete an unused shared File as its signed-in creator:
797
-
798
- ```sh
799
- os files delete --workspace <workspace> --id <file-id> --yes --json
800
- ```
801
-
802
- `--yes` explicitly confirms removal of the original and every retained
803
- enrichment. Without confirmation the command refuses before authentication or
804
- deletion work. A Source or another independent use conflicts without changing
805
- the File; delete that use through its owning capability first. Read access does
806
- not allow deleting another member's or an installed routine's File.
807
-
808
- The command uses the published SDK and the CLI member session. Configured
809
- `OS_FILES_ROOT` selects the existing managed local owner, including
810
- uploaded-cache cleanup. Success means physical cleanup and durable completion;
811
- repeating a completed command succeeds. Temporary failures remain retryable,
812
- and a pending File stays inaccessible. R2 cleanup removes only the exact pinned
813
- registered object and confirms absence; a changed identity fails with integrity.
814
- Human output names the workspace and File ID. JSON success is one document:
815
- `{"workspace":"playground","id":"<file-id>","status":"deleted"}`.
816
- Failures exit nonzero with the bounded Files error category.
817
- After interruption or a lost reply, repeat the same confirmed command and ID;
818
- do not create a replacement File to recover deletion. A completed retry needs
819
- no provider connection, but still requires current creator authority.
820
-
821
766
  ## Package boundary
822
767
 
823
768
  `@oddington/cli` contains the `os` executable and depends on the compatible