foldrun 21.3.0 → 22.0.0
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/bin/foldrun.mjs +21 -5
- package/docs/agents.md +1 -0
- package/docs/api.md +24 -0
- package/docs/cli.md +2 -0
- package/docs/extract.md +165 -0
- package/docs/providers.md +5 -4
- package/docs/runs.md +18 -3
- package/docs/security.md +11 -8
- package/package.json +3 -3
- package/src/commands.mjs +174 -2
package/bin/foldrun.mjs
CHANGED
|
@@ -32,7 +32,8 @@
|
|
|
32
32
|
// foldrun onboarding the account's getting-started steps, the next one first
|
|
33
33
|
// foldrun billing the balance, and what the money went on
|
|
34
34
|
// foldrun gallery the tools the platform ships to every account — list, pull, upgrade <tool>
|
|
35
|
-
// foldrun storage <verb> ls / cat / get / put / rm / share / shares / unshare — what the agents produced, and public links to it
|
|
35
|
+
// foldrun storage <verb> ls / cat / text / get / put / rm / share / shares / unshare — what the agents produced, and public links to it
|
|
36
|
+
// foldrun text <file> a PDF, scan, document, sheet or recording on this machine, as text — read by the platform
|
|
36
37
|
// foldrun runtimes the environments a workspace's agents need, and whether each is built
|
|
37
38
|
// foldrun secrets <verb> set / ls / rm — the vault, from the terminal
|
|
38
39
|
// foldrun new <name> another workspace in this account
|
|
@@ -212,6 +213,7 @@ const HELP = `foldrun — agents are just folders
|
|
|
212
213
|
foldrun docs [page] foldrun's docs, from the copy this CLI ships — what a coding agent should read (--path)
|
|
213
214
|
foldrun triggers why nothing ran: per flow, fired vs started and every reason, then the newest decisions and the deliveries at the hook and inbox URLs (--since <days>, --limit <n> of each, default 10, --to <workspace>, --json)
|
|
214
215
|
foldrun storage <verb> what a workspace produced: ls [prefix], cat <path> (--preview: a PDF, sheet, deck or zip as text), get <path>, put <file|folder>... (--into <folder/>, --as <path> for one file), rm <path> — and share <path> (--ttl <days>, --forever), shares (--all), unshare <token|id>
|
|
216
|
+
foldrun storage text <path> a file in a workspace's storage as text, read by the platform (PDF, scan, document, sheet, recording) — printed, and written beside it as <path>.txt unless --no-write (--lang, --ocr, --engine, --wait, --json; --to or --workspace <ws>)
|
|
215
217
|
foldrun storage ls --all every workspace's storage, as the account's Storage page: a block per workspace, busiest first ([prefix], --json)
|
|
216
218
|
foldrun runtimes the environments a deployed workspace's agents need (python, pip and npm packages) and whether each is built — failed ones with the installer's error (--wait holds on while any is building)
|
|
217
219
|
foldrun billing the account's balance and its recent ledger entries (--limit <n>)
|
|
@@ -310,6 +312,7 @@ Signing in
|
|
|
310
312
|
foldrun keys create <label> --gateway --cap <usd> [--daily <usd>] a key for a CODING agent (Claude Code: ANTHROPIC_BASE_URL + this key) — it spends the account's credits on foldrun's models through the gateway, up to its own limits, and opens no /api route; an admin of every workspace; shown once
|
|
311
313
|
foldrun keys create laptop --gateway --cap 20 --claude-code the same, and Claude Code is set up on this machine: the URL and key go into its settings, and its status line shows the key's spend
|
|
312
314
|
foldrun gateway status-line one line for Claude Code's status line: what the gateway key in ANTHROPIC_AUTH_TOKEN has spent, of its limits (asks the gateway; kept 10 s, --cache <s>)
|
|
315
|
+
foldrun text <file> a local file as text: uploads it to the platform, which reads it — a PDF or scan (OCR in Persian or English), a Word, sheet or slide file, a recording — and prints the text (--lang fa|en|auto, --ocr auto|always|never, --engine docling, --out <path> or -o <path>, --json, --wait <s>); a long job is polled until it ends
|
|
313
316
|
foldrun talk speak a prompt: records the microphone until you stop talking, foldrun's own Whisper turns it into text (Persian with the Persian model), prints the words — Claude Code's /talk runs it (--lang auto|fa|en…, --max <s> up to 120, --silence <s>, --file <audio or video> instead of the mic, --mic <name>, --plain, --json; the gateway key from ANTHROPIC_AUTH_TOKEN or --url/--key)
|
|
314
317
|
foldrun a2a ls --to <ws> what a workspace serves over A2A: each flow's a2a:, card and endpoint URLs, its A2A keys (admins), recent tasks and the key that asked (--json)
|
|
315
318
|
foldrun a2a publish <flow> set a2a: publish: true in the flow (--to <ws>: the deployed copy, an admin's) — --name, --description, --example "…" (repeatable), --public-card | --private-card; diff, checked, --dry-run
|
|
@@ -396,6 +399,11 @@ Options
|
|
|
396
399
|
--tag <t> invoke, flow run: a label on the run — repeatable, sent as tags
|
|
397
400
|
--inputs <set> invoke, flow run: the task is a saved input set (evals/<flow>-inputs.md, or an eval case for the flow)
|
|
398
401
|
--preview storage cat: the platform reads the file and prints what is in it
|
|
402
|
+
--lang <fa|en|auto> text, storage text: the language to read it in (OCR and speech; default auto)
|
|
403
|
+
--ocr <auto|always|never> text, storage text: read the page images too — auto does it where a page has no text layer
|
|
404
|
+
--wait <s> text, storage text: seconds the platform may hold the request before answering with a job, which the CLI then polls (30, 30s, 2m)
|
|
405
|
+
--no-write storage text: print the text only; the platform writes no <path>.txt beside the file
|
|
406
|
+
--json text, storage text: the whole result — text, kind, format, pages, OCR pages, engine, warnings, cached
|
|
399
407
|
--ttl <days> storage share: how long the link works (default 7); --forever: it never expires (keys create: the key never expires)
|
|
400
408
|
--into <folder/> storage put: upload under that folder of storage/
|
|
401
409
|
--as <path> storage put: the path one uploaded file lands at; agent import: the name the copy gets
|
|
@@ -408,6 +416,7 @@ Options
|
|
|
408
416
|
--accept-risk <agent,…> / --clear-accept-risk a2a publish: the agents accepted holding a secret while they can run code (a2a: accept_risk)
|
|
409
417
|
--days <n> usage: the window the charges cover (default 56); status --platform --history: 1-90 (default 90); observe: the same as --since
|
|
410
418
|
--id <revision> history: one revision in full, as diffs
|
|
419
|
+
--engine <e> text, storage text: the parser that reads the file (docling)
|
|
411
420
|
--engine <e> login: (with a site) the browser to sign in with — chrome (default: real Google Chrome, Chromium when it is not installed), chromium, firefox or safari
|
|
412
421
|
--new-client connect: enter a new OAuth client even when one is saved for the secret
|
|
413
422
|
--step <n> approve, reject: decide only that step; default is every step that is waiting
|
|
@@ -436,7 +445,7 @@ Options
|
|
|
436
445
|
--workspaces <a,b> secrets set: store an account secret limited to those workspaces, in the same write (with --account); team invite, team access: the workspaces they may open
|
|
437
446
|
--add <site> agent network: add a site to its network: list (repeatable)
|
|
438
447
|
--remove <site> agent network: take a site off its network: list (repeatable)
|
|
439
|
-
--out <file> api spec: where to write the OpenAPI document (default: stdout); check: where to write the JSON or SARIF report
|
|
448
|
+
--out <file> api spec: where to write the OpenAPI document (default: stdout); check: where to write the JSON or SARIF report; text: where to write the text (-o <file> too; refused when it exists, --force overwrites)
|
|
440
449
|
--file <path> source put, library put, flow paste: the local file to send (default: stdin); secrets set --kind file|service-account: the file it holds; storage get, report get, report live, account export, export, billing statement: where to write it (- for stdout)
|
|
441
450
|
--message "<why>" source put: recorded on the file's revision
|
|
442
451
|
--check source put: refuse the save when the file would not check out (422: the issues printed, nothing written)
|
|
@@ -490,7 +499,7 @@ Platform options (deploy, invoke, secrets, logs, keys)
|
|
|
490
499
|
--dry-run source share: list what would move, move nothing
|
|
491
500
|
--dry-run deploy: check and report, change nothing; flow add, flow set, flow trigger, flow compute, flow move-step, flow paste, flow draft, assistant, history restore, agent link, agent unlink: show the diff, write nothing; restore <ws>: the diff only, restore nothing; import: the preview only, write nothing; stop, rerun (bulk): list what matches, touch nothing
|
|
492
501
|
--no-runtimes deploy: do not wait for the workspace's environments to be built
|
|
493
|
-
--force deploy: deploy even while runs are in flight; pull, storage get: overwrite local files
|
|
502
|
+
--force deploy: deploy even while runs are in flight; pull, storage get, text: overwrite local files
|
|
494
503
|
--yes deploy: allow deleting files this folder no longer has (asked otherwise; required with no terminal)
|
|
495
504
|
--platform --yes workspaces rm: delete it on the platform, deliberately
|
|
496
505
|
--format <text|json|sarif> check: how to print the findings (--json is --format json; sarif is for GitHub code scanning); --out <file> writes it there
|
|
@@ -514,7 +523,7 @@ if (!command || command === "--help" || command === "-h") {
|
|
|
514
523
|
// `--value` as the account's argument and stored an empty secret; `--force
|
|
515
524
|
// ./dir` swallowed the directory. A flag followed by another flag is also
|
|
516
525
|
// boolean, so an unlisted switch at least does not eat its neighbour.
|
|
517
|
-
const BOOLEAN_FLAGS = new Set(["read-only", "account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "generate-key", "device", "write", "dpop", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "gateway", "claude-code", "login", "unreachable", "public-card", "private-card", "return-immediately", "online", "overwrite", "no-send", "event-wait", "with-client", "use", "clear-name", "clear-description", "clear-examples", "clear-accept-risk", "clear-address", "clear-email", "clear-abn", "no-task", "empty", "plain", "no-beep", "require-customer"]);
|
|
526
|
+
const BOOLEAN_FLAGS = new Set(["read-only", "account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "generate-key", "device", "write", "dpop", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "gateway", "claude-code", "login", "unreachable", "public-card", "private-card", "return-immediately", "online", "overwrite", "no-send", "event-wait", "with-client", "use", "clear-name", "clear-description", "clear-examples", "clear-accept-risk", "clear-address", "clear-email", "clear-abn", "no-task", "empty", "plain", "no-beep", "require-customer", "no-write"]);
|
|
518
527
|
// Flags said more than once collect into a list: `--tag a --tag b`.
|
|
519
528
|
const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example", "accept-risk"]);
|
|
520
529
|
/** Flags that become a list only when given more than once (FOL-163 `--file`). */
|
|
@@ -523,9 +532,16 @@ const LIST_WHEN_REPEATED = new Set(["file"]);
|
|
|
523
532
|
// a span: `--wait 30m`, `--wait event`. Only a value that reads as one is
|
|
524
533
|
// taken, so `invoke x --wait` and friends are as they were.
|
|
525
534
|
const WAIT_VALUE = /^(\d+(\.\d+)?\s*[smhd]|event)$/i;
|
|
535
|
+
// `text` and `storage text` take --wait as plain seconds (`--wait 30`), and
|
|
536
|
+
// `-o <file>` as --out.
|
|
537
|
+
const textVerb = () => command === "text" || (command === "storage" && positional[0] === "text");
|
|
526
538
|
const flags = {};
|
|
527
539
|
const positional = [];
|
|
528
540
|
for (let i = 0; i < rest.length; i++) {
|
|
541
|
+
if (rest[i] === "-o" && rest[i + 1] !== undefined && textVerb()) {
|
|
542
|
+
flags.out = rest[++i];
|
|
543
|
+
continue;
|
|
544
|
+
}
|
|
529
545
|
if (!rest[i].startsWith("--")) {
|
|
530
546
|
positional.push(rest[i]);
|
|
531
547
|
continue;
|
|
@@ -533,7 +549,7 @@ for (let i = 0; i < rest.length; i++) {
|
|
|
533
549
|
const name = rest[i].slice(2);
|
|
534
550
|
const next = rest[i + 1];
|
|
535
551
|
let value;
|
|
536
|
-
if (name === "wait" && next !== undefined && WAIT_VALUE.test(next)) value = rest[++i];
|
|
552
|
+
if (name === "wait" && next !== undefined && (WAIT_VALUE.test(next) || (textVerb() && /^\d+(\.\d+)?$/.test(next)))) value = rest[++i];
|
|
537
553
|
else if (BOOLEAN_FLAGS.has(name) || next === undefined || next.startsWith("--")) value = true;
|
|
538
554
|
else value = rest[++i];
|
|
539
555
|
if (REPEATABLE.has(name) && typeof value === "string") flags[name] = [...(Array.isArray(flags[name]) ? flags[name] : []), value];
|
package/docs/agents.md
CHANGED
|
@@ -112,6 +112,7 @@ only Web takes a provider:
|
|
|
112
112
|
| **Web** | `web` | eight actions — search, fetch, browse, crawl, map, extract, answer, monitor | one per action under `web:` — unset is ours |
|
|
113
113
|
| **Files** | `read` | Read, Glob, Grep — inspect but never modify | — |
|
|
114
114
|
| | `write` | Read, Write, Edit, Glob, Grep | — |
|
|
115
|
+
| | `text` | `extract_text(path, lang?, ocr?, save?)` — a file it can reach as text: images and scanned PDFs (Persian and English OCR), text PDFs, DOCX, PPTX, XLSX, EPUB, HTML, and the speech in audio and video, read by foldrun's own extraction service ([Files to text](extract)). `lang` is `fa`, `en` or `auto` (default); `save: true` also writes `<path>.txt` beside the file (or under `outputs/` where it cannot write, or where that file already exists — it never overwrites). Text over 200 KB returns its start; `save: true` keeps all of it in the file (a second call is answered from the cache); files over 200 MB are refused; a long recording may take minutes. Platform runs only — on `foldrun run` it says so and sends nothing. Named `text`, not `extract`, because `extract` is one of `web`'s actions. Platform limits: files up to the install's extraction limit (100 MB by default), 30 files a minute per step, 3 extractions at once per account (shared with the dashboard and API) — past one the tool says when to try again; the same file with the same options is answered from the account's earlier result. `limits: {text: 20}` caps it per step | — |
|
|
115
116
|
| **Code** | `code` | Bash — runs anything in the sandbox: Python and Node (packages via `runtime:`), Debian programs (`runtime: system:`), or a binary you ship | — |
|
|
116
117
|
| **Memory** | `search` | `search_files(query)` over knowledge, memory, state and storage at every scope | — |
|
|
117
118
|
| | `history` | `recall_runs()` and `read_run(id)` — the workspace's last thirty finished runs | — |
|
package/docs/api.md
CHANGED
|
@@ -315,6 +315,30 @@ one; a body that does not match the length it declared is a `400`.
|
|
|
315
315
|
Blobs go to object storage; the index of what exists stays local. Presigned
|
|
316
316
|
URLs mean nothing in a run pod ever holds the bucket credential.
|
|
317
317
|
|
|
318
|
+
## Files to text
|
|
319
|
+
|
|
320
|
+
An image, a PDF, a Word, PowerPoint or Excel file, HTML, a recording or a
|
|
321
|
+
video, turned into text on foldrun's own servers — OCR (Persian and English),
|
|
322
|
+
text layers, and speech by Whisper ([Files to text](extract.md)). The text is
|
|
323
|
+
kept as the account's own artifact: the same file with the same options comes
|
|
324
|
+
back at once with `cached: true`, and is never shared with another account.
|
|
325
|
+
|
|
326
|
+
A call waits up to `wait` seconds (0–60, default 50). Done in time, it answers
|
|
327
|
+
`200` with the text; still working, `202 { id, status: "running", poll }` —
|
|
328
|
+
GET the `poll` URL until `status` is `done` or `failed`. Refusals: `413` over
|
|
329
|
+
the size limit (`FOLDRUN_EXTRACT_MAX_MB`, default 100 MB) or the parser's own
|
|
330
|
+
limits (pages, length), `415` a type it does not read, `422` a file it cannot
|
|
331
|
+
read, `429` with `Retry-After` past 20 extractions a minute per key or person
|
|
332
|
+
or 3 running at once per account, `503` when the server has no extraction set
|
|
333
|
+
up. Each refusal carries a `code` (`unsupported`, `too_large`, `unreadable`,
|
|
334
|
+
`rate_limited`, `too_many_running`, `not_configured`, …).
|
|
335
|
+
|
|
336
|
+
| Route | Methods | |
|
|
337
|
+
|---|---|---|
|
|
338
|
+
| `/api/extract?name&lang&ocr&engine&wait` | POST | a file to text, sent whole as the raw request body with a `Content-Length` (at most 10 MB, the API's per-request limit — a larger file goes to storage first and through `storage/extract`). `name` the file's name (a hint; the bytes decide), `lang` `fa`, `en` or `auto` (OCR `fas+eng` or `eng`; speech in that language or the one heard), `ocr` `auto` (only pages with no text layer), `always` or `never`, `engine` `docling` for a PDF read by Docling. Answers `{ sha256, kind, format, text, pages?, ocrPages?, seconds?, confidence?, language?, engine: { parser, speech? }, truncated, warnings, cached, ms }`; speech comes under `[audio · m:ss · transcript, fa]`, a video's as `[video · m:ss · speech]` then its on-screen text. The file is not stored. What starting a run needs (`run:start`). Idempotent |
|
|
339
|
+
| `/api/extract/<id>` | GET | one extraction that answered `202`: `{ id, status, result?, error?, wrote?, createdAt, finishedAt }` — `status` `running`, `done` (with `result`) or `failed` (with `error: { status, code, message }`; `worker_stopped` when the server working on it stopped). The account's own; a member or key scoped to some workspaces reads the jobs of those and the account-level ones it started. Kept a day |
|
|
340
|
+
| `/api/workspaces/<ws>/storage/extract` | POST | a stored file to text: `{ path, lang?, ocr?, engine?, write?, wait? }`. With `write` (the default, `workspace:write`) the text is written to `<path>.txt` beside the file once it is done — also when the caller stopped waiting — and the answer says `wrote: "<path>.txt"`; a `.txt` is refused. `write: false` only reads (`workspace:read`). Same answers as `/api/extract`, plus `wrote`. Idempotent |
|
|
341
|
+
|
|
318
342
|
## Shares — a public link to one file
|
|
319
343
|
|
|
320
344
|
| Route | Methods | |
|
package/docs/cli.md
CHANGED
|
@@ -171,6 +171,8 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
171
171
|
| `foldrun version` | this CLI's version, its `@foldrun/core`'s, and — when a platform is known (`--url`, `--profile`, `FOLDRUN_URL` or where you signed in) — that platform's: version, release time, API version, each component's commit and the browsers its runner image has (with versions where known: `chrome 154.0.8037.58`), from `GET /api/version` (no key needed). Warns when the platform was released with a newer CLI than this one. An unreachable platform is a dim line, not a failure. `--json` prints `{ cli, core, platform }`. `foldrun --version` (or `-v`) prints only the CLI's version, offline. See [Versions and releases](versions) |
|
|
172
172
|
| `foldrun doctor` | check the road to the platform, one line each: Node (22 or newer), the CLI and core versions, which of `FOLDRUN_URL`, `FOLDRUN_TOKEN`, `FOLDRUN_TIMEOUT`, `HTTPS_PROXY` are set (never their values), which model credential a local run would use (by its variable, never its value), the account it would act as, DNS for the platform's host, and a timed `GET /api/healthz`. The first thing to run when a command cannot reach the platform |
|
|
173
173
|
| `foldrun storage <verb>` | what a workspace PRODUCED, as opposed to what you wrote — `source` is the other half. `ls [prefix]` lists every file with its size, when it was written, how long ago and which run wrote it (`run:<id>`, `user:<email>` for an upload, `api-key` for a key), newest first, plus what the store holds against its quota. `cat <path>` prints a text file and refuses one that is not text; `cat <path> --preview` asks the platform to read it instead and prints what is in it — a PDF or Word document as paragraphs, a spreadsheet or CSV as a table, a deck as slides, an archive as its listing. `get <path>` downloads it beside you — `--file <path>` names somewhere else, `--force` overwrites. `put <file|folder>...` uploads any files, of any type, into storage under their own names, walking folders whole (`.git`, `node_modules` and `.DS_Store` are skipped); `--into <folder/>` puts them under a folder, `--as <path>` renames a single file, and large files go straight to the bucket by a presigned URL, so size is not capped by the platform's request limit; `rm <path>` removes one. `share <path>` mints a public link to one produced file (7 days; `--ttl <days>`, `--forever`) and prints the URL; `shares` lists the live links (`--all` includes expired and revoked); `unshare <token|id>` revokes one — the link answers 404 from then on and the token is never reused. Only an admin, or the person who made a link, sees its token; anyone else sees the link with its token masked and an id (`sh_…`) to unshare it by. `--to <workspace>` from anywhere; inside a workspace folder it is already known. `ls --all` lists every workspace's storage, as the account's Storage page: a block per workspace with its files, size and quota, the busiest first, then the empty ones by name (`[prefix]` narrows each; `--json` is `{ workspaces: [...] }`, one storage document per workspace; a workspace that could not be read is a non-zero exit) |
|
|
174
|
+
| `foldrun storage text <path>` | a file already in a workspace's storage, as text: `POST /api/workspaces/<ws>/storage/extract` with `{ path, lang, ocr, engine, wait, write }`. Prints the text, and the platform writes it beside the file as `<path>.txt` (`wrote <path>.txt` on stderr) unless `--no-write`. The same `--lang`, `--ocr`, `--engine`, `--wait` and `--json` as `foldrun text`, and the same polling when it answers 202. `--to <workspace>` or `--workspace <name>` from anywhere; inside a workspace folder it is already known |
|
|
175
|
+
| `foldrun text <file>` | a file on this machine as text, read by the platform ([Files to text](extract)): it uploads the bytes to `POST /api/extract` and prints what the platform read — a photo, scan or PDF (OCR in Persian and English), a Word, sheet or slide file, or a recording (speech to text). `--lang fa\|en\|auto` (default auto), `--ocr auto\|always\|never` (auto reads page images only where a page has no text layer), `--engine docling` picks the parser, `--wait <s>` is how long the platform may hold the request before answering with a job (`30`, `30s`, `2m`). A long job answers 202 and is polled at `GET /api/extract/<id>` every 2 s (or as Retry-After says) with one progress line on stderr until it is done or failed. The text goes to stdout; `--out <path>` (or `-o <path>`) writes it to a file instead (refused when the file exists; `--force` overwrites); `--json` prints the whole result — `sha256`, `kind`, `format`, `text`, `pages`, `ocrPages`, `seconds`, `language`, `engine`, `truncated`, `warnings`, `cached`, `ms`. Files over 10 MB go into storage first (`foldrun storage put`, then `foldrun storage text`). Warnings go to stderr; a refused or failed job prints the platform's reason and exits 1 |
|
|
174
176
|
| `foldrun runtimes` | the environments a deployed workspace's agents need — each distinct `runtime:` (an agent's own merged with its tools'), the packages in it, which agents use it, and whether the platform has built it: ready, building, or failed with the installer's own error. `foldrun deploy` prints the same thing after a deploy and waits up to two minutes for builds in progress (`--no-runtimes` skips the wait); this asks again later, and `--wait` holds on while any is building. Exits 1 when one has failed. `--to <workspace>` from anywhere |
|
|
175
177
|
| `foldrun schedule` | every flow in the account whose `trigger:` is a clock: workspace, flow, the cron line, its timezone, how many steps, whether the scheduler can parse it, and the next three times it fires. The times are the point — `0 5 1-7 * 5` reads as "the first Friday" and fires eight times in twenty-eight days, because day-of-month and day-of-week are OR'd. Exits 1 if any line is unparseable, since an invalid schedule errors nowhere and simply never runs. `--to <workspace>` narrows it |
|
|
176
178
|
| `foldrun schedule tick` | Settings' **Run scheduler now**: fire whatever is due this minute and print which flows went (`POST /api/schedule`). They were due anyway; this only makes them go now |
|
package/docs/extract.md
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# Files to text
|
|
2
|
+
|
|
3
|
+
foldrun turns a file into text on its own servers: a photo of a letter, a
|
|
4
|
+
scanned PDF, a Word document, a spreadsheet, a voice note, a video. The text
|
|
5
|
+
is what an agent reads and what a model is sent — never the picture, the
|
|
6
|
+
sound or the video itself. Persian is read as well as English, in print and
|
|
7
|
+
in speech.
|
|
8
|
+
|
|
9
|
+
Nothing leaves foldrun to do it: OCR, document parsing and speech recognition
|
|
10
|
+
run on foldrun's own machines, which hold no keys and reach nothing outside.
|
|
11
|
+
|
|
12
|
+
## What it reads
|
|
13
|
+
|
|
14
|
+
| The file | How | What comes back |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| Images — PNG, JPEG, TIFF, BMP, GIF, WebP, HEIC, AVIF | OCR (Tesseract, Persian + English) | the text in it, and a confidence 0–100 |
|
|
17
|
+
| PDF | its text layer; OCR for pages that have none (scanned pages) | the text, page by page, `[page 4 · OCR]` on a page that was OCR'd |
|
|
18
|
+
| Word, PowerPoint, Excel (`.docx`, `.pptx`, `.xlsx`), EPUB | Docling | the text, tables kept as markdown |
|
|
19
|
+
| HTML, plain text | read as they are | the text |
|
|
20
|
+
| Audio — WAV, MP3, M4A, OGG/Opus, FLAC, AMR, WebM | Whisper, in segments of 5 minutes | `[audio · 2:41 · transcript, fa]` and what was said |
|
|
21
|
+
| Video — MP4, MOV, MKV, WebM, AVI, MPEG | Whisper for the sound; OCR on frames (one every 5 s or more) | `[video · 4:10 · speech]`, what was said, then `[0:35 · on-screen text]` blocks |
|
|
22
|
+
|
|
23
|
+
A legacy Office file (`.doc`, `.xls`, `.ppt`) or a zip archive is refused
|
|
24
|
+
with `415` and says why: save it as `.docx`/`.xlsx`/`.pptx` first.
|
|
25
|
+
|
|
26
|
+
## Persian
|
|
27
|
+
|
|
28
|
+
`lang` says which language to expect:
|
|
29
|
+
|
|
30
|
+
| `lang` | OCR reads | Speech is heard as |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| `auto` (default) | Persian and English (`fas+eng`) | the language Whisper detects in the first part; Persian goes to the Persian model |
|
|
33
|
+
| `fa` | Persian and English (`fas+eng`) | Persian, on the Persian model |
|
|
34
|
+
| `en` | English (`eng`) | English |
|
|
35
|
+
|
|
36
|
+
OCR uses Tesseract's most accurate trained models (`tessdata_best`) for
|
|
37
|
+
Persian and English. Persian text is normalised — Arabic ي and ك to Persian
|
|
38
|
+
ی and ک — so it searches and compares as typed. Speech in Persian goes to a
|
|
39
|
+
Whisper model fine-tuned on Persian; every other language to the general
|
|
40
|
+
Whisper large-v3-turbo model.
|
|
41
|
+
|
|
42
|
+
Measure on your own files before you rely on it: OCR on a phone photo of a
|
|
43
|
+
crumpled page, or speech over loud music, is less accurate than on a clean
|
|
44
|
+
scan or a quiet recording. `confidence` (OCR) says how sure it was.
|
|
45
|
+
|
|
46
|
+
## Limits
|
|
47
|
+
|
|
48
|
+
| | |
|
|
49
|
+
|---|---|
|
|
50
|
+
| One file | at most 100 MB (`FOLDRUN_EXTRACT_MAX_MB`). Sent straight to the API, at most 10 MB — the API's per-request limit; a larger file goes to storage first |
|
|
51
|
+
| A document | its first 500 pages; at most 200 of them read by OCR |
|
|
52
|
+
| A recording or video | at most 4 hours |
|
|
53
|
+
| The text | at most 8 MB; past it the text is cut and `truncated: true` says so |
|
|
54
|
+
| How fast | 20 extractions a minute per key or person, 3 running at once per account — past either, `429` with `Retry-After` |
|
|
55
|
+
|
|
56
|
+
A short file comes back in a few seconds. A long recording takes minutes:
|
|
57
|
+
every call waits up to `wait` seconds (default 50, at most 60) and otherwise
|
|
58
|
+
answers `202` with a job to poll.
|
|
59
|
+
|
|
60
|
+
## The same file twice
|
|
61
|
+
|
|
62
|
+
The text of a file is kept as the account's own, by the file's content hash
|
|
63
|
+
and the options it was read with. The same file again — from another path,
|
|
64
|
+
another person, another run — comes back at once with `cached: true`, and no
|
|
65
|
+
work is done. Different options (`lang`, `ocr`, `engine`) are a separate
|
|
66
|
+
reading. One account's texts are never shared with, or visible to, another.
|
|
67
|
+
|
|
68
|
+
## In the dashboard
|
|
69
|
+
|
|
70
|
+
**Storage → a file → Extract text** reads the file and writes its text to
|
|
71
|
+
`<file>.txt` beside it, where an agent reads it like any other file. A long
|
|
72
|
+
recording takes a while; the `.txt` appears when it is done, even if you
|
|
73
|
+
close the preview. A `.txt` has no button: it is already text.
|
|
74
|
+
|
|
75
|
+
## From the CLI
|
|
76
|
+
|
|
77
|
+
```sh
|
|
78
|
+
foldrun text scan.jpg # a file on this machine: its text, printed
|
|
79
|
+
foldrun text voice-note.ogg --lang fa # Persian speech
|
|
80
|
+
foldrun storage text inbox/letter.pdf --to sales # a stored file: writes inbox/letter.pdf.txt
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`--lang fa|en|auto`, `--ocr auto|always|never` and `--engine docling` work on
|
|
84
|
+
both; `storage text --no-write` prints the text without writing the `.txt`.
|
|
85
|
+
Either waits for a long recording until it is done ([cli](cli.md)).
|
|
86
|
+
|
|
87
|
+
## For an agent
|
|
88
|
+
|
|
89
|
+
`tools: [text]` gives an agent `extract_text(path, lang?, ocr?)`: the text of
|
|
90
|
+
any file it can read — in its sandbox, in `workspace/storage/`, or a file it
|
|
91
|
+
was handed as an input — read the same way and kept the same way.
|
|
92
|
+
|
|
93
|
+
```markdown
|
|
94
|
+
---
|
|
95
|
+
name: intake
|
|
96
|
+
tools: [read, text]
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
Read each scanned letter in workspace/storage/inbox/ with extract_text
|
|
100
|
+
(lang: fa) and file a one-line summary of each.
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Audio and video therefore reach a model as text, not as sound or pictures:
|
|
104
|
+
the model is sent what was said and what was shown on screen
|
|
105
|
+
([runs](runs.md), [providers](providers.md)).
|
|
106
|
+
|
|
107
|
+
## The API
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
# a file sent whole
|
|
111
|
+
curl -sS -X POST "$FOLDRUN_URL/api/extract?name=letter.jpg&lang=fa" \
|
|
112
|
+
-H "authorization: Bearer $FOLDRUN_TOKEN" \
|
|
113
|
+
--data-binary @letter.jpg
|
|
114
|
+
|
|
115
|
+
# a stored file, its text written to inbox/letter.pdf.txt
|
|
116
|
+
curl -sS -X POST "$FOLDRUN_URL/api/workspaces/sales/storage/extract" \
|
|
117
|
+
-H "authorization: Bearer $FOLDRUN_TOKEN" -H "content-type: application/json" \
|
|
118
|
+
-d '{"path": "inbox/letter.pdf", "lang": "fa"}'
|
|
119
|
+
|
|
120
|
+
# a 202's job, polled
|
|
121
|
+
curl -sS "$FOLDRUN_URL/api/extract/xj-…" -H "authorization: Bearer $FOLDRUN_TOKEN"
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
The answer:
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"sha256": "3f2a…", "kind": "audio", "format": "ogg",
|
|
129
|
+
"text": "[audio · 0:42 · transcript, fa]\nسلام، جلسه فردا ساعت ده است.",
|
|
130
|
+
"seconds": 42, "language": "fa",
|
|
131
|
+
"engine": { "parser": "ffmpeg", "speech": "whisper-large-fa-v1" },
|
|
132
|
+
"truncated": false, "warnings": [], "cached": false, "ms": 6120
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Every route, field and refusal is in [api](api.md#files-to-text). Starting
|
|
137
|
+
an extraction of a file you send takes what starting a run takes; reading a
|
|
138
|
+
stored file takes read access to its workspace, writing its `.txt` beside it
|
|
139
|
+
takes write access.
|
|
140
|
+
|
|
141
|
+
## Engines and their licences
|
|
142
|
+
|
|
143
|
+
All open source, all running on foldrun's own servers.
|
|
144
|
+
|
|
145
|
+
| Engine | Used for | Licence |
|
|
146
|
+
|---|---|---|
|
|
147
|
+
| [Tesseract](https://github.com/tesseract-ocr/tesseract) 5.5, with `tessdata_best` `fas` + `eng` | OCR: images, scanned pages, video frames | Apache-2.0 |
|
|
148
|
+
| [Poppler](https://poppler.freedesktop.org/) | PDF text layers, rendering scanned pages for OCR | GPL-2.0-or-later (run as a separate program) |
|
|
149
|
+
| [Docling](https://github.com/docling-project/docling) | Word, PowerPoint, Excel, and PDFs with `engine: docling` | MIT |
|
|
150
|
+
| [FFmpeg](https://ffmpeg.org/) | audio tracks, video frames | LGPL-2.1-or-later |
|
|
151
|
+
| [whisper.cpp](https://github.com/ggml-org/whisper.cpp) | speech recognition | MIT |
|
|
152
|
+
| [givia/whisper-large-v3-turbo-persian](https://huggingface.co/givia/whisper-large-v3-turbo-persian) | Persian speech | CC-BY-4.0 |
|
|
153
|
+
| [openai/whisper-large-v3-turbo](https://huggingface.co/openai/whisper-large-v3-turbo) | speech in every other language | MIT |
|
|
154
|
+
|
|
155
|
+
The Persian speech model is "whisper-large-v3-turbo-persian" by givia,
|
|
156
|
+
licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/);
|
|
157
|
+
foldrun runs it converted to whisper.cpp's format.
|
|
158
|
+
|
|
159
|
+
## Running it yourself
|
|
160
|
+
|
|
161
|
+
A self-hosted install extracts text when it runs the extraction service and
|
|
162
|
+
points `FOLDRUN_EXTRACT_URL` at it (and `FOLDRUN_TRANSCRIBE_URL`, plus
|
|
163
|
+
`FOLDRUN_TRANSCRIBE_FA_URL` for Persian speech, at the Whisper servers).
|
|
164
|
+
Without them every route answers `503` — "text extraction is not configured
|
|
165
|
+
on this server" — and nothing else changes.
|
package/docs/providers.md
CHANGED
|
@@ -215,10 +215,11 @@ model on Chat Completions a PDF's text, read it with a script. Whether a given
|
|
|
215
215
|
model can see images at all is the provider's; one that cannot refuses or
|
|
216
216
|
ignores the image.
|
|
217
217
|
|
|
218
|
-
Audio and video are never
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
218
|
+
Audio and video are never sent as sound or video: no endpoint above is sent
|
|
219
|
+
one, whatever its provider supports. They reach a model as text instead —
|
|
220
|
+
foldrun transcribes the speech and reads a video's on-screen text on its own
|
|
221
|
+
servers, with the `text` tool (`tools: [text]`) or as a `<file>.txt` beside
|
|
222
|
+
the file ([Files to text](extract.md)), and the model is sent that text.
|
|
222
223
|
|
|
223
224
|
### Persian prompts, by tier (checked 11 Nov 2026)
|
|
224
225
|
|
package/docs/runs.md
CHANGED
|
@@ -595,9 +595,13 @@ every file.
|
|
|
595
595
|
Which model is shown an image or a PDF is the one the step runs on — Claude
|
|
596
596
|
only when the step's provider is Anthropic (your key, or foldrun's models
|
|
597
597
|
set to Anthropic); OpenAI, Gemini or another provider otherwise. Audio and
|
|
598
|
-
video (a voice note, an `.mp3`, an `.mp4`) are never sent to a model
|
|
599
|
-
|
|
600
|
-
|
|
598
|
+
video (a voice note, an `.mp3`, an `.mp4`) are never sent to a model as sound
|
|
599
|
+
or pictures; they reach it as text. An agent with `tools: [text]` turns any
|
|
600
|
+
file into text on foldrun's own servers — speech by Whisper, a video's
|
|
601
|
+
on-screen text by OCR, Persian included — and a file's text written to
|
|
602
|
+
`<file>.txt` beside it (Storage → Extract text, `foldrun storage text`) is a
|
|
603
|
+
file the agent reads like any other ([Files to text](extract.md)). Nothing of
|
|
604
|
+
it goes to an outside service.
|
|
601
605
|
|
|
602
606
|
```sh
|
|
603
607
|
foldrun storage put brief.pdf --to sales --into briefs/
|
|
@@ -626,6 +630,17 @@ takes `inputs: ["briefs/brief.pdf"]` on `POST …/agents/<agent>/run` and
|
|
|
626
630
|
snapshot.
|
|
627
631
|
- **Released with the run.** Deleting a run, or the retention window
|
|
628
632
|
pruning it, lets its held copies go.
|
|
633
|
+
- **Text beside media.** On an install with text extraction, each input
|
|
634
|
+
that is an image, PDF, office document (DOCX, PPTX, XLSX, ODT, RTF,
|
|
635
|
+
EPUB…), recording or video gets a `<file>.txt` beside it in `inputs/`
|
|
636
|
+
before the step starts — OCR (Persian and English), the document's text,
|
|
637
|
+
or a transcript — and the step's prompt says which files have one and to
|
|
638
|
+
read the text first. Limits: 120 seconds for all of a run's inputs
|
|
639
|
+
together, files of at most 50 MB, recordings of at most 10 minutes. Best
|
|
640
|
+
effort: a file that yields no text gets no `.txt` and one line in the
|
|
641
|
+
run's trail (`inputs: photo.jpg → no text (reason)`), and the run goes on.
|
|
642
|
+
A `.txt` never replaces an input of the same name; text, data and code
|
|
643
|
+
files are left as they are.
|
|
629
644
|
|
|
630
645
|
## End customers
|
|
631
646
|
|
package/docs/security.md
CHANGED
|
@@ -193,16 +193,18 @@ its record.
|
|
|
193
193
|
Your run's record — its prompts, replies, files, tool arguments and errors —
|
|
194
194
|
is yours, in your workspace, and goes where you send it (`telemetry:` to your
|
|
195
195
|
own OpenTelemetry collector, `notify:` to your webhook). The platform's own
|
|
196
|
-
logs and metrics are a different thing: they
|
|
197
|
-
|
|
196
|
+
logs and metrics are a different thing: they go to our own operations store
|
|
197
|
+
(in a bucket only it can read; the platform team reads it to see what happened
|
|
198
|
+
to an account — a refused sign-in, a refused key or call, a failure), and they
|
|
199
|
+
never carry your content.
|
|
198
200
|
|
|
199
201
|
| Carries | Never carries |
|
|
200
202
|
|---|---|
|
|
201
|
-
| ids: account, run, job, task, lease, pod | prompts, replies, a step's output |
|
|
203
|
+
| ids: account, member, API key (its id, never the key), request, run, job, task, lease, pod | prompts, replies, a step's output |
|
|
202
204
|
| the names of your workspaces, flows, agents and evals | file names or contents, knowledge, memory |
|
|
203
205
|
| counts, durations, bytes, dollars, HTTP status | tool or script arguments and results |
|
|
204
206
|
| an error's class (`timeout`, `oom`, `disk_full`, `model_error`, `network_error`, `policy_denied`, `user_code_error`, `not_found`, `cancelled`, `platform_error`), its type, its errno or SQLSTATE, and where in **our** code it happened | an error's message or stack text, a model process's stderr, a query or its values |
|
|
205
|
-
| a reason word from a fixed set (`paused`, `
|
|
207
|
+
| a reason word from a fixed set (`paused`, `key_revoked`, `bad_credentials`) | URLs, email addresses, anything with a space in it |
|
|
206
208
|
|
|
207
209
|
It holds by construction, not by care:
|
|
208
210
|
|
|
@@ -214,9 +216,10 @@ It holds by construction, not by care:
|
|
|
214
216
|
replaces its console and its stdout/stderr at start. Anything else that
|
|
215
217
|
prints — our older code, a dependency, Next.js — becomes "a line was
|
|
216
218
|
printed here", never what it said.
|
|
217
|
-
- **A second line at the collector.** The log shipper
|
|
218
|
-
|
|
219
|
-
|
|
219
|
+
- **A second line at the collector.** The log shipper keeps a line only if
|
|
220
|
+
it is such a line, and of it only those fields, each in its shape — a value
|
|
221
|
+
that does not fit is deleted, not stored. It never reads the namespace where
|
|
222
|
+
steps run.
|
|
220
223
|
- **Tests.** A process inside the boundary tries every way to print a
|
|
221
224
|
marker (an error's message, stack, name and code; a forged envelope; a
|
|
222
225
|
raw write; an uncaught rejection) and the test reads the raw bytes; the
|
|
@@ -260,7 +263,7 @@ an install that sets neither keeps everything, as before 5 Nov 2026.
|
|
|
260
263
|
| **Audit log** — security evidence | sign-ins and refusals, keys, roles, invites, secrets set or deleted (by name, never a value), deploys, exports, support access, the operator's own actions | **365 days** on the hosted platform (`audit.retention_days`; unset: kept) | the daily pass |
|
|
261
264
|
| The ledger | what each run and pod session was charged | for good — a financial record | never |
|
|
262
265
|
| A run's wide event | its funnel's timestamps, image, size, model, figures, cost and error class — metadata, never content | with run records (`runs.retention_days`) | the daily pass; closing the account |
|
|
263
|
-
| The platform's own logs and metrics | ids, counts, classes — never your content ([above](#what-our-telemetry-carries)) |
|
|
266
|
+
| The platform's own logs and metrics | ids, counts, classes — never your content ([above](#what-our-telemetry-carries)) | 30 days | the operations store |
|
|
264
267
|
|
|
265
268
|
Every period counts from when the record was written (a run: when it
|
|
266
269
|
finished), and the daily pass deletes on its first round after the day. A
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "22.0.0",
|
|
4
4
|
"description": "Agents are just folders. Write them, check them, run them — on your machine.",
|
|
5
5
|
"license": "FSL-1.1-ALv2",
|
|
6
6
|
"type": "module",
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"node": ">=22"
|
|
12
12
|
},
|
|
13
13
|
"dependencies": {
|
|
14
|
-
"@foldrun/core": "^
|
|
14
|
+
"@foldrun/core": "^20.0.0"
|
|
15
15
|
},
|
|
16
16
|
"files": [
|
|
17
17
|
"bin",
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
],
|
|
23
23
|
"scripts": {
|
|
24
24
|
"e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
|
|
25
|
-
"test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-team-me.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts tests/cli-flow-filter.test.ts tests/cli-eval-grades.test.ts tests/cli-eval-compare.test.ts tests/cli-proposals.test.ts tests/cli-inbox.test.ts tests/cli-usage-compute.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts tests/cli-mcp.test.ts tests/cli-a2a.test.ts tests/cli-gateway.test.ts tests/cli-switches.test.ts tests/cli-parity-runs.test.ts tests/cli-parity-b.test.ts tests/cli-parity-clears.test.ts tests/cli-parity-c.test.ts tests/cli-runs-paging.test.ts tests/cli-budget-invoices.test.ts tests/cli-observe-analysis.test.ts tests/cli-failure-retention.test.ts tests/cli-snapshot.test.ts tests/cli-run-money.test.ts tests/cli-talk.test.ts",
|
|
25
|
+
"test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-team-me.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts tests/cli-flow-filter.test.ts tests/cli-eval-grades.test.ts tests/cli-eval-compare.test.ts tests/cli-proposals.test.ts tests/cli-inbox.test.ts tests/cli-usage-compute.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts tests/cli-mcp.test.ts tests/cli-a2a.test.ts tests/cli-gateway.test.ts tests/cli-switches.test.ts tests/cli-parity-runs.test.ts tests/cli-parity-b.test.ts tests/cli-parity-clears.test.ts tests/cli-parity-c.test.ts tests/cli-runs-paging.test.ts tests/cli-budget-invoices.test.ts tests/cli-observe-analysis.test.ts tests/cli-failure-retention.test.ts tests/cli-snapshot.test.ts tests/cli-run-money.test.ts tests/cli-talk.test.ts tests/cli-text.test.ts",
|
|
26
26
|
"release": "node scripts/release.mjs",
|
|
27
27
|
"typecheck": "tsc -p tsconfig.json",
|
|
28
28
|
"docs:sync": "node scripts/sync-docs.mjs",
|
package/src/commands.mjs
CHANGED
|
@@ -6557,6 +6557,172 @@ function humanBytes(n) {
|
|
|
6557
6557
|
* the ones this key may open (GET /api/workspaces), each listed by its own
|
|
6558
6558
|
* storage route.
|
|
6559
6559
|
*/
|
|
6560
|
+
// ----------------------------------------------------------- files to text
|
|
6561
|
+
|
|
6562
|
+
/** How long `text` and `storage text` keep polling a job before giving up. */
|
|
6563
|
+
const EXTRACT_POLL_LIMIT_MS = 60 * 60 * 1000;
|
|
6564
|
+
|
|
6565
|
+
/**
|
|
6566
|
+
* The options `foldrun text` and `foldrun storage text` share, checked:
|
|
6567
|
+
* --lang, --ocr, --engine and --wait (seconds the platform may hold the
|
|
6568
|
+
* request before it answers 202 with a job to poll).
|
|
6569
|
+
* @param {Record<string, any>} flags
|
|
6570
|
+
*/
|
|
6571
|
+
function extractOptions(flags) {
|
|
6572
|
+
const out = {};
|
|
6573
|
+
if (flags.lang !== undefined) {
|
|
6574
|
+
const lang = String(flags.lang).toLowerCase();
|
|
6575
|
+
if (!["auto", "fa", "en"].includes(lang)) throw new Error("--lang is fa, en or auto");
|
|
6576
|
+
out.lang = lang;
|
|
6577
|
+
}
|
|
6578
|
+
if (flags.ocr !== undefined) {
|
|
6579
|
+
const ocr = String(flags.ocr).toLowerCase();
|
|
6580
|
+
if (!["auto", "always", "never"].includes(ocr)) throw new Error("--ocr is auto, always or never");
|
|
6581
|
+
out.ocr = ocr;
|
|
6582
|
+
}
|
|
6583
|
+
if (flags.engine !== undefined) {
|
|
6584
|
+
if (typeof flags.engine !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(flags.engine)) throw new Error("--engine names a parser, such as docling");
|
|
6585
|
+
out.engine = flags.engine;
|
|
6586
|
+
}
|
|
6587
|
+
// A bare --wait means nothing more here: the CLI polls until the job ends.
|
|
6588
|
+
if (flags.wait !== undefined && flags.wait !== true) {
|
|
6589
|
+
const m = /^(\d+(?:\.\d+)?)\s*(s|m)?$/i.exec(String(flags.wait).trim());
|
|
6590
|
+
if (!m) throw new Error("--wait is the seconds the platform may hold the request before answering with a job to poll (30, 30s, 2m)");
|
|
6591
|
+
out.wait = Number(m[1]) * (m[2]?.toLowerCase() === "m" ? 60 : 1);
|
|
6592
|
+
}
|
|
6593
|
+
return out;
|
|
6594
|
+
}
|
|
6595
|
+
|
|
6596
|
+
/**
|
|
6597
|
+
* A /api/extract answer as { status, body, retryAfterMs }, or the API's own
|
|
6598
|
+
* message thrown. Read by hand rather than through remoteCall: the 202's
|
|
6599
|
+
* Retry-After sets the next poll, and remoteCall keeps only the body.
|
|
6600
|
+
* @param {Response} res @param {string} url @param {Record<string, any>} flags @param {string} apiPath
|
|
6601
|
+
*/
|
|
6602
|
+
async function extractAnswer(res, url, flags, apiPath) {
|
|
6603
|
+
const text = await res.text();
|
|
6604
|
+
/** @type {any} */
|
|
6605
|
+
let body = {};
|
|
6606
|
+
try {
|
|
6607
|
+
body = text.trim() ? JSON.parse(text) : {};
|
|
6608
|
+
} catch {
|
|
6609
|
+
const type = (res.headers.get("content-type") ?? "unknown type").split(";")[0].trim();
|
|
6610
|
+
throw new HttpError(`${apiPath} → HTTP ${res.status} (${type}) — not the platform's answer; is ${new URL(url).host} the right address, and is it up?`, res.status, {});
|
|
6611
|
+
}
|
|
6612
|
+
if (!res.ok) {
|
|
6613
|
+
const said = typeof body.error === "string" ? body.error : typeof body.error?.message === "string" ? body.error.message : typeof body.message === "string" ? body.message : `${apiPath.split("?")[0]} → HTTP ${res.status}`;
|
|
6614
|
+
const hint = res.status === 401 || res.status === 403 ? refusedHint(url, flags) : res.status === 429 ? rateLimitHint(res, body) : "";
|
|
6615
|
+
throw new HttpError(`${said}${hint}`, res.status, body);
|
|
6616
|
+
}
|
|
6617
|
+
const h = res.headers.get("retry-after");
|
|
6618
|
+
const retryAfterMs = h && /^\d+(\.\d+)?$/.test(h.trim()) ? Number(h) * 1000 : h && !Number.isNaN(Date.parse(h)) ? Math.max(0, Date.parse(h) - Date.now()) : null;
|
|
6619
|
+
return { status: res.status, body, retryAfterMs };
|
|
6620
|
+
}
|
|
6621
|
+
|
|
6622
|
+
/**
|
|
6623
|
+
* Follow a 202 to its end: GET the job every 2 s (or what Retry-After says)
|
|
6624
|
+
* until it is done or failed. One line on stderr says it is waiting. A done
|
|
6625
|
+
* job's result is its `result` when it carries one, else the body itself.
|
|
6626
|
+
* @param {string} url @param {Record<string, any>} flags @param {{ body: any, retryAfterMs: number | null }} first @param {string} what
|
|
6627
|
+
*/
|
|
6628
|
+
async function followExtract(url, flags, first, what) {
|
|
6629
|
+
let { body, retryAfterMs } = first;
|
|
6630
|
+
if (body?.status !== "running" || !body.id) return body;
|
|
6631
|
+
const pollPath = typeof body.poll === "string" && body.poll.startsWith("/api/") ? body.poll : `/api/extract/${enc(String(body.id))}`;
|
|
6632
|
+
const started = Date.now();
|
|
6633
|
+
if (flags.quiet !== true) console.error(` ${c.dim(`reading ${what} on the platform (job ${body.id}) — this can take a while for a long scan or recording`)}`);
|
|
6634
|
+
while (body?.status === "running") {
|
|
6635
|
+
if (Date.now() - started > EXTRACT_POLL_LIMIT_MS) throw new Error(`job ${body.id} is still running after an hour — GET ${pollPath} reads it later`);
|
|
6636
|
+
await sleep(Math.min(Math.max(retryAfterMs ?? 2000, 500), 60_000));
|
|
6637
|
+
const token = await renewedToken(url, flags);
|
|
6638
|
+
const res = await remoteFetch(url, pollPath, {}, { token, seconds: timeoutSeconds(flags) });
|
|
6639
|
+
({ body, retryAfterMs } = await extractAnswer(res, url, flags, pollPath));
|
|
6640
|
+
}
|
|
6641
|
+
if (body?.status === "failed") {
|
|
6642
|
+
const why = typeof body.error === "string" ? body.error : typeof body.error?.message === "string" ? body.error.message : "the platform gave no reason";
|
|
6643
|
+
throw new Error(`${what}: the extraction failed — ${why}`);
|
|
6644
|
+
}
|
|
6645
|
+
if (body?.status && body.status !== "done") throw new Error(`${what}: the job answered status ${body.status}, not done or failed`);
|
|
6646
|
+
// A polled job carries `wrote` beside `result`, not inside it: keep it.
|
|
6647
|
+
return body?.result && typeof body.result === "object" ? { ...body.result, ...(body.wrote ? { wrote: body.wrote } : {}) } : body;
|
|
6648
|
+
}
|
|
6649
|
+
|
|
6650
|
+
/**
|
|
6651
|
+
* What `text` and `storage text` print once there is a result: the text on
|
|
6652
|
+
* stdout (or --out), --json the whole object, warnings on stderr.
|
|
6653
|
+
* @param {any} result @param {Record<string, any>} flags
|
|
6654
|
+
*/
|
|
6655
|
+
function printExtracted(result, flags) {
|
|
6656
|
+
const warnings = Array.isArray(result?.warnings) ? result.warnings.map(String) : [];
|
|
6657
|
+
const text = typeof result?.text === "string" ? result.text : "";
|
|
6658
|
+
const out = typeof flags.out === "string" && flags.out && flags.out !== "-" ? flags.out : null;
|
|
6659
|
+
if (flags.json === true && !out) console.log(JSON.stringify(result, null, 2));
|
|
6660
|
+
else if (out) {
|
|
6661
|
+
if (fs.existsSync(out) && flags.force !== true) throw new Error(`${out} already exists — --force overwrites, --out <path> puts it somewhere else`);
|
|
6662
|
+
fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
|
|
6663
|
+
fs.writeFileSync(out, flags.json === true ? `${JSON.stringify(result, null, 2)}\n` : text.endsWith("\n") || !text ? text : `${text}\n`);
|
|
6664
|
+
const pages = result?.pages ? ` · ${result.pages} page${result.pages === 1 ? "" : "s"}${result.ocrPages ? ` (${result.ocrPages} by OCR)` : ""}` : "";
|
|
6665
|
+
const secs = result?.seconds ? ` · ${result.seconds} s of audio` : "";
|
|
6666
|
+
console.error(` ${c.green("✓")} wrote ${out} ${c.dim(`${humanBytes(Buffer.byteLength(text))}${result?.kind ? ` · ${result.kind}` : ""}${result?.format ? ` ${result.format}` : ""}${pages}${secs}${result?.cached ? " · cached" : ""}`)}`);
|
|
6667
|
+
} else writeExact(text.endsWith("\n") || !text ? text : `${text}\n`);
|
|
6668
|
+
if (result?.truncated) console.error(` ${c.yellow("!")} the text was cut at the platform's limit — the file holds more than this`);
|
|
6669
|
+
for (const w of warnings) console.error(` ${c.yellow("!")} ${w}`);
|
|
6670
|
+
}
|
|
6671
|
+
|
|
6672
|
+
/**
|
|
6673
|
+
* `foldrun text <file>` — a local file (a PDF, a scan, a document, a sheet,
|
|
6674
|
+
* a recording) turned into text by the platform: POST /api/extract with the
|
|
6675
|
+
* bytes, then the job polled when the platform answers 202.
|
|
6676
|
+
* @param {string[]} positional @param {Record<string, any>} flags
|
|
6677
|
+
*/
|
|
6678
|
+
async function textCmd(positional, flags) {
|
|
6679
|
+
const file = positional[0];
|
|
6680
|
+
if (!file) throw new Error("which file? `foldrun text <file>` — a PDF, scan, document, sheet or recording on this machine (`foldrun storage text <path>` for one already in a workspace)");
|
|
6681
|
+
if (positional.length > 1) throw new Error(`one file at a time — \`foldrun text ${file}\` (got ${positional.length})${flags.wait === true ? "; --wait takes seconds: --wait 30" : ""}`);
|
|
6682
|
+
const opts = extractOptions(flags);
|
|
6683
|
+
const url = platformFor(flags, "text");
|
|
6684
|
+
if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`${file} is not a file here`);
|
|
6685
|
+
const bytes = fs.readFileSync(file);
|
|
6686
|
+
if (!bytes.length) throw new Error(`${file} is empty`);
|
|
6687
|
+
const q = new URLSearchParams({ name: path.basename(file) });
|
|
6688
|
+
for (const k of ["lang", "ocr", "engine", "wait"]) if (opts[k] !== undefined) q.set(k, String(opts[k]));
|
|
6689
|
+
// The request holds for --wait at most, plus the upload itself.
|
|
6690
|
+
const seconds = explicitTimeout(flags) ?? Math.max(timeoutSeconds(flags), (opts.wait ?? 50) + 30, Math.ceil(bytes.length / 200_000));
|
|
6691
|
+
const token = await renewedToken(url, flags);
|
|
6692
|
+
const apiPath = `/api/extract?${q}`;
|
|
6693
|
+
const res = await remoteFetch(url, apiPath, { method: "POST", body: bytes, headers: { "content-type": "application/octet-stream" } }, { token, seconds });
|
|
6694
|
+
const result = await followExtract(url, flags, await extractAnswer(res, url, flags, apiPath), path.basename(file));
|
|
6695
|
+
printExtracted(result, flags);
|
|
6696
|
+
return 0;
|
|
6697
|
+
}
|
|
6698
|
+
|
|
6699
|
+
/**
|
|
6700
|
+
* `foldrun storage text <path>` — a file already in a workspace's storage,
|
|
6701
|
+
* as text: POST …/storage/extract. The platform also writes <path>.txt
|
|
6702
|
+
* beside it unless --no-write.
|
|
6703
|
+
* @param {string} url @param {string} ws @param {string[]} positional @param {Record<string, any>} flags
|
|
6704
|
+
*/
|
|
6705
|
+
async function storageTextCmd(url, ws, positional, flags) {
|
|
6706
|
+
const given = positional[1];
|
|
6707
|
+
if (!given) throw new Error("`foldrun storage text <path>` — a path under storage/, as `foldrun storage ls` names it");
|
|
6708
|
+
if (typeof flags.out === "string" && flags.out) throw new Error("--out is for `foldrun text <file>`; `storage text` writes <path>.txt in the workspace (--no-write: it does not)");
|
|
6709
|
+
const rel = given.replace(/^storage\//, "");
|
|
6710
|
+
const opts = extractOptions(flags);
|
|
6711
|
+
const seconds = explicitTimeout(flags) ?? Math.max(timeoutSeconds(flags), (opts.wait ?? 50) + 30);
|
|
6712
|
+
const token = await renewedToken(url, flags);
|
|
6713
|
+
const apiPath = `/api/workspaces/${enc(ws)}/storage/extract`;
|
|
6714
|
+
const res = await remoteFetch(
|
|
6715
|
+
url,
|
|
6716
|
+
apiPath,
|
|
6717
|
+
{ method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ path: rel, ...opts, write: flags["no-write"] !== true }) },
|
|
6718
|
+
{ token, seconds },
|
|
6719
|
+
);
|
|
6720
|
+
const result = await followExtract(url, flags, await extractAnswer(res, url, flags, apiPath), rel);
|
|
6721
|
+
printExtracted(result, flags);
|
|
6722
|
+
if (result?.wrote) console.error(` ${c.green("✓")} wrote ${typeof result.wrote === "string" ? result.wrote : `${rel}.txt`}`);
|
|
6723
|
+
return 0;
|
|
6724
|
+
}
|
|
6725
|
+
|
|
6560
6726
|
async function storageLsAll(url, prefix, flags) {
|
|
6561
6727
|
const { workspaces = [] } = await remoteCall(url, flags, "/api/workspaces");
|
|
6562
6728
|
const inPrefix = (f) => (prefix ? f.path === prefix || f.path.startsWith(prefix.replace(/\/*$/, "/")) : true);
|
|
@@ -6613,10 +6779,14 @@ async function storageCmd(positional, flags, layout) {
|
|
|
6613
6779
|
// fall back to the directory's NAME, which from ~/Downloads asks the
|
|
6614
6780
|
// platform for a workspace called "Downloads" and reports a 404 as though
|
|
6615
6781
|
// the file were missing. --to is the answer from anywhere else.
|
|
6616
|
-
|
|
6782
|
+
// `storage text` also takes --workspace <name> — a name, not a folder.
|
|
6783
|
+
const named = positional[0] === "text" && typeof flags.workspace === "string" && /^[^/\\.][^/\\]*$/.test(flags.workspace) ? flags.workspace : null;
|
|
6784
|
+
const ws = typeof flags.to === "string" ? flags.to : named ?? (layout?.kind === "empty" ? null : takeWorkspace([], layout));
|
|
6617
6785
|
if (!ws) throw new Error("which workspace? `foldrun storage ls --to <workspace>` — or run it inside one");
|
|
6618
6786
|
const verb = positional[0] ?? "ls";
|
|
6619
6787
|
|
|
6788
|
+
if (verb === "text") return storageTextCmd(url, ws, positional, flags);
|
|
6789
|
+
|
|
6620
6790
|
if (verb === "ls") {
|
|
6621
6791
|
const body = await remoteCall(url, flags, `/api/workspaces/${ws}/storage`);
|
|
6622
6792
|
const prefix = positional[1];
|
|
@@ -6760,7 +6930,7 @@ async function storageCmd(positional, flags, layout) {
|
|
|
6760
6930
|
}
|
|
6761
6931
|
|
|
6762
6932
|
if (verb !== "cat" && verb !== "get") {
|
|
6763
|
-
throw new Error(`unknown storage verb "${verb}" — ls, cat, get, put, rm, share, shares or unshare`);
|
|
6933
|
+
throw new Error(`unknown storage verb "${verb}" — ls, cat, text, get, put, rm, share, shares or unshare`);
|
|
6764
6934
|
}
|
|
6765
6935
|
|
|
6766
6936
|
const rel = positional[1];
|
|
@@ -15639,6 +15809,8 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
15639
15809
|
return extract(workspace, flags);
|
|
15640
15810
|
case "talk":
|
|
15641
15811
|
return talkCmd(flags);
|
|
15812
|
+
case "text":
|
|
15813
|
+
return textCmd(positional, flags);
|
|
15642
15814
|
case "deploy":
|
|
15643
15815
|
return deploy(positional[0] ?? ".", flags, layout);
|
|
15644
15816
|
case "run":
|