@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 +112 -167
- package/dist/cli-update-worker.js +4 -2
- package/dist/os.js +490 -542
- package/package.json +2 -2
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
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
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()
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
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 --
|
|
528
|
-
os digest create --
|
|
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
|
|
547
|
-
as a member supplies `routinePublicationClient({ workspace,
|
|
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.
|
|
535
|
+
await changes.apply();
|
|
562
536
|
```
|
|
563
537
|
|
|
564
|
-
Local Runs read
|
|
565
|
-
|
|
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.
|
|
593
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
`execution.json` retains
|
|
628
|
-
|
|
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.
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
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 `
|
|
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
|
-
|
|
668
|
-
|
|
669
|
-
credential-redacted
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
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
|
-
|
|
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,
|
|
727
|
-
name and working-root flags
|
|
728
|
-
remains the separate ad hoc command
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
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
|
|
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
|
-
```
|
|
768
|
-
|
|
769
|
-
|
|
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
|
-
|
|
776
|
-
|
|
777
|
-
|
|
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
|
-
|
|
780
|
-
|
|
781
|
-
|
|
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
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
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
|