@acsetra/runner 0.1.92 → 0.1.94

package/bin/runner.js

@@ -190,7 +190,7 @@ async function main() {
   const argv = process.argv.slice(2);
   if (!argv.length || ["-h", "--help"].includes(argv[0])) { console.log(renderTop()); return 0; }
   const [cmd, ...rest] = argv;
-  if (["version", "--version", "-V"].includes(cmd)) { console.log("runner (@acsetra/runner) 0.1.92"); return 0; }
+  if (["version", "--version", "-V"].includes(cmd)) { console.log("runner (@acsetra/runner) 0.1.94"); return 0; }
 
   // help — top-level, `help <topic>`, and per-verb `<cmd> … --help` (lexical, before toOp)
   if (cmd === "help") {

package/lib/grammar.json

@@ -52,7 +52,8 @@
     "muted",
     "probe",
     "replace",
-    "run"
+    "run",
+    "tools"
   ],
   "primary_json": {
     "set.put": "meta",
@@ -1161,8 +1162,8 @@
       "desc": "render-level check: dead wiring, behavior↔surface mismatch, ctx typos. --map = per-node design-as-data; --run executes mount(ctx) and catches throws"
     },
     "pipe": {
-      "usage": "pipe <code> -S <scope> [-w code:label | -w scope/code] [--rate N] [--timeout N] [--keep]\n       pipe show <code>  |  pipe list  |  pipe remove <code>",
-      "desc": "create/upsert a pipeline envelope (resets workers unless --keep)"
+      "usage": "pipe <code> -S <scope> [-w code:label | -w scope/code] [--rate N] [--timeout N] [--keep]\n       [--cost-class free|metered|paid] [--requires '{\"approval\":true,\"per_user_daily\":N,\"owner_of\":\"<set>\"}']\n       pipe show <code>  |  pipe list  |  pipe catalog [-S scope] [--tools]  |  pipe remove <code>",
+      "desc": "create/upsert a pipeline envelope (resets workers unless --keep). `pipe remove` detaches TERMINAL run history onto the launches (audit preserved) and refuses only ACTIVE launches. `pipe catalog` = the live machine-readable org catalog (accepts/reads/writes/calls/callers/schedules/cost per pipeline; --tools adds OpenAI function schemas) — feed agents THIS, never a hand-synced registry set. `--requires` gates are enforced at admission for EVERY producer (browser, CLI, schedules, pipeline tier); a per_user_daily cap makes /run answer `remaining`"
     },
     "pipes": {
       "usage": "pipes",
@@ -1185,7 +1186,24 @@
         "            (a real child launch; -s '{\"pick\":[…],\"input\":{…}}' shapes its input)",
         "  batch     -s '{\"over\":\"items\",\"each\":{\"tier\":…,\"spec\":{…}},\"concurrency\":8}'",
         "            ONE run fans a sub-worker over a list: bounded (default 8, max 32), one item's",
-        "            failure is its own {error,index}, the answer counts ok/failed — never loop ctx.run"
+        "            failure is its own {error,index}, the answer counts ok/failed — never loop ctx.run",
+        "Every tier: -s '{\"as\":\"key\"}' lands the worker's WHOLE payload under one bag key;",
+        "  '{\"when\":{\"<bag key>\": value|[values]}}' gates the step on the bag (skip, never force-run).",
+        "snippet also: '{\"reads\":[keys]}' hands the snippet ONLY those bag keys (+ __ stamps, item).",
+        "llm also: messages_from (full chat array from the bag), response_format, reasoning (effort),",
+        "  max_tokens (clamped to the model's registry ceiling) — no more raw-httpx model calls.",
+        "read also: key_from, fields:[…], where/where_from (mode all), default, transient.",
+        "Errors: RAISE is the one error channel — a raised worker fails the launch with a receipt;",
+        "  output={'error':…} is just data and settles nothing.",
+        "The full per-tier key map lives in the manifest's worker_spec (CI-checked against the kernel).",
+        "Cross-tier -s keys (census wave 2): pick/drop (payload projection at the merge),",
+        "  retry (per-worker attempts), until/every/max_polls (poll the SAME worker until a",
+        "  condition matches — no more time.sleep in snippets), writes '{\"set\":\"bag key\"}'",
+        "  (multi-set atomic writes from ONE worker), writes_to_from (data-driven target),",
+        "  emit (pipeline-tier output contract), imports (snippet_lib modules; `import",
+        "  runner_lib` — the framework stdlib — is always available).",
+        "Zero-worker pipelines are refused at admission; terminal output carries __verdict",
+        "  (steps/ran/skipped/rows_written/sets) so done ≠ silently-did-nothing."
       ]
     },
     "op": {
@@ -1254,5 +1272,106 @@
         "op"
       ]
     }
+  },
+  "worker_spec": {
+    "_comment": "Per-tier worker spec keys — THE discoverability source of truth for what a worker's -s '{json}' understands. tests/test_grammar_manifest.py scans the kernel for every spec key it reads and FAILS when one is missing here (the when/reads-invisible-for-weeks class). _common keys apply to every tier.",
+    "_common": {
+      "as": "land this worker's ENTIRE payload under this ONE bag key instead of merging top-level (the universal namespacing rule; read/llm resolve `as` in-tier as the rows/reply key)",
+      "when": "{\"<bag key>\": value | [values]} — run this step only while every named key's bag value matches; otherwise SKIP it (no attempt, cursor advances). Authored spec, never a client flag",
+      "pick": "[keys] — keep ONLY these keys of a dict payload before it merges/nests (read/llm resolve their own shape; on the pipeline tier `pick` narrows the CHILD's input — use `emit` for its output)",
+      "drop": "[keys] — remove these keys from the payload before it merges, so a provider's 41-key envelope never enters the bag (retires the terminal null-out ritual)",
+      "retry": "per-worker retries: an int, or {\"attempts\": N, \"backoff\": s} — overrides the pipeline policy for THIS step only (max 10)",
+      "until": "{\"<bag key>\": value | [values]} — POLL-UNTIL: re-run this worker until the condition matches its merged result (the `when` grammar); exhausting max_polls is a LOUD error, never a silent miss",
+      "every": "seconds between polls (with `until`; default 5, clamped 1–300)",
+      "max_polls": "poll ceiling (with `until`; default 12, max 60)",
+      "writes": "{\"<set> | <scope>/<set>\": \"<bag key>\", …} — MULTI-SET WRITES: each named set receives that key of this worker's result (a list writes rows, a dict one envelope, a missing key skips), atomically in the same step; own-scope targets are minted at authoring, cross-scope targets must exist. Kills the one-writer-per-set stub tail",
+      "writes_to_from": "bag key naming the target set at RUN time ('<code>' or '<scope>/<code>' of an EXISTING same-org set) — this worker's own result lands there; an empty value skips. The data-driven writes_to (no more N cloned router workers)"
+    },
+    "snippet": {
+      "body": "the Python source — reads `input`, sets `output` (one row) or output={\"rows\":[…]} (many); DB-isolated subprocess",
+      "reads": "[keys] — hand the snippet ONLY these bag keys (plus the __ stamps and a batch `item`); a pass-through stub stops serialising the whole multi-MB bag",
+      "imports": "[modules] — rows of the scope's `snippet_lib` set (row code = module name, meta.body = Python source), materialized beside the body so `import <name>` works; `import runner_lib` (the framework stdlib: sv, rows_of, meta_of, latest, cur, by_code, sha, slug, iso, clamp, chunk, …) is ALWAYS available with no spec change"
+    },
+    "read": {
+      "set": "value set CODE to resolve",
+      "scope": "read a set of ANOTHER scope of this org (default: nearest set at the launch scope)",
+      "mode": "latest (one row) | all (the list)",
+      "key": "literal row key — ONE indexed point read",
+      "key_from": "dotted bag key(s), first non-empty wins — one authored worker serves every row",
+      "shape": "\"row\" answers the full row with revision/etag (record heads)",
+      "fields": "[…] — carry ONLY these meta keys into the bag (minimal-data projection)",
+      "where": "{k: v} — meta equality filters applied IN THE QUERY (mode all)",
+      "where_from": "{k: \"<dotted bag key>\"} — where values read from the bag",
+      "limit": "max rows (mode all)",
+      "order": "\"-ordinal\" for newest-first",
+      "default": "value answered when a latest/keyed read finds nothing",
+      "include_deleted": "a keyed read may answer a tombstoned family's last write",
+      "transient": "keep this read's rows OUT of the persisted launch output",
+      "optional": "true — a mode:all read of a set that does not EXIST answers [] instead of failing; default is a loud failure (distinct denial vs empty — an existing-but-empty set always answers []). me/me_* sets are always tolerant (minted per-user on first write)"
+    },
+    "llm": {
+      "provider": "provider entry (default openai); with `url`, any OpenAI-compatible endpoint",
+      "url": "override the provider endpoint",
+      "model": "model id (default: the registry's DEFAULT_MODEL)",
+      "keys": "key specs — a connection service (user key PARKS the run until connected) or \"$secrets.NAME\" from the org vault",
+      "system": "literal system prompt",
+      "system_from": "bag key holding the system prompt",
+      "user_from": "bag key holding the user message (default `ask`)",
+      "messages_from": "bag key holding a FULL chat `messages` array — multi-turn conversations without a snippet",
+      "response_format": "passed through to the provider (json_schema / json_object)",
+      "reasoning": "effort for reasoning models (none|minimal|low|medium|high|xhigh → reasoning_effort)",
+      "max_tokens": "output cap, clamped to the model's registry ceiling (sent as max_completion_tokens to api.openai.com)",
+      "response_path": "dotted path to the reply text (default: the provider's)"
+    },
+    "agent": {
+      "model": "model id — routed by the registry (gpt* → OpenAI, else Anthropic; HOUSE keys)",
+      "system": "literal system prompt",
+      "system_from": "bag key holding the system prompt",
+      "user_from": "bag key holding the ask (default: bag `ask`/`text`)",
+      "reasoning": "thinking effort (low|medium|high; OpenAI also none|minimal|xhigh)",
+      "search": "web search is ON by default (the model decides whether to use it) — false disables"
+    },
+    "httpx": {
+      "url": "the AUTHORED base — scheme+host are never data-driven (the SSRF gate and the key-carrying host are fixed at authoring)",
+      "method": "GET|POST|PUT|PATCH|DELETE|HEAD (default POST)",
+      "method_from": "dotted bag key naming the method (allowlisted)",
+      "path_from": "dotted bag key holding an ABSOLUTE path(+query) appended to the base — ids in paths without one worker per id",
+      "body_from": "dotted bag key holding the JSON body (default: the whole bag on mutating methods; GET/HEAD send none)",
+      "keys": "key specs — each carries a user/house connection token or \"$secrets.NAME\" (org vault) in its OWN header; a missing USER key parks the run; {\"token_from\": \"<bag key>\", \"header\"?, \"scheme\"?} sends a token MINTED BY THIS RUN (a prior session-mint step) — no more `import httpx` inside a snippet to carry it",
+      "allow_hosts": "pin the SSRF gate tighter than the default private/internal block",
+      "max_bytes": "response size ceiling in bytes — over it the worker fails loudly instead of dragging megabytes into the bag",
+      "follow_redirects": "follow up to N redirect hops (max 5): each hop re-proves the SSRF gate, and auth keys are DROPPED the moment the host changes"
+    },
+    "batch": {
+      "over": "bag key holding the list (default `items`)",
+      "each": "{tier, spec} — the sub-worker each item runs (it sees the bag plus `item`); one item's failure is ITS result, never the batch's",
+      "concurrency": "parallel items (default 8, max 32)",
+      "input_map": "(inside `each`) {\"<child key>\": \"<dotted path>\"} — name item fields into the child's input ({\"source_id\": \"item.source_id\"}) instead of forcing every fan-out child to open with an unwrap worker for the fixed `item` key"
+    },
+    "pipeline": {
+      "pipeline": "'<code>' or '<scope>/<code>' — an EXISTING pipeline of this org, run as a REAL child launch driven in-process (own receipts/rows/feed events)",
+      "pick": "[keys] — narrow the bag handed to the child",
+      "input": "overlay object templated over the bag before the child launches",
+      "emit": "[keys] — the child call's OUTPUT contract: only these keys of the child's terminal bag join the parent (without it the whole child bag lands — nine production bridge workers existed only to null that back out)"
+    },
+    "storage": {
+      "op": "store_bytes | start_upload | finalize_upload | fetch_upload — the byte-asset choreography (tenant code never sees bucket credentials)",
+      "from": "store_bytes: bag key holding base64 bytes (default `bytes_b64`)",
+      "accept": "content-type allowlist (exact or family wildcard, e.g. [\"image/*\"])",
+      "max_bytes": "size ceiling (default 25 MB)",
+      "kind": "asset kind for the emitted row (file | image | …)",
+      "visibility": "public (default) | …",
+      "class": "storage class (default managed)",
+      "content_type": "explicit content type (else from data / sniffed)",
+      "ext": "explicit file extension (else derived from the content type)",
+      "ttl": "fetch_upload: source-fetch timeout seconds (default 60); start_upload: presign TTL (default 600)",
+      "asset_code": "explicit asset row code (else from data.asset_code/code)",
+      "app_key": "storage key namespace (default: the scope leaf)",
+      "rel_scope": "where under the app the object key is filed (default root)",
+      "timeout": "fetch_upload: HTTP timeout seconds for the source fetch (default 60)"
+    },
+    "internal": {
+      "handler": "a NAMED vetted function from the internal registry (`record` = declarative row envelope from the input)"
+    }
   }
 }

package/lib/verbs.js

@@ -102,7 +102,7 @@ export function toOp(verb, rest) {
   }
   if (verb === "ls") { const { flags } = walk(rest); return ["set.list", assemble("set.list", [], flags)]; }
   if (verb === "pipe") {
-    if (rest.length && ["show", "list", "remove"].includes(rest[0])) {
+    if (rest.length && ["show", "list", "remove", "catalog"].includes(rest[0])) {
       const op = "pipe." + rest[0];
       const { positionals, flags } = walk(rest.slice(1));
       return [op, assemble(op, positionals, flags)];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acsetra/runner",
-  "version": "0.1.92",
+  "version": "0.1.94",
   "description": "Runner CLI — author and run hosted Runner apps from your terminal (the `runner` command).",
   "keywords": ["runner", "acsetra", "cli", "agent", "low-code"],
   "license": "MIT",