@metagptx/deepflow-suite-cli 0.3.0 → 0.3.1

package/bundle/skills/df-task/SKILL.md

@@ -15,106 +15,19 @@ CLI 由 `@metagptx/deepflow-suite-cli` 统一安装，本 Skill 不携带 CLI
 
 ## 任务描述
 
-每轮工作先用 `df-task get "$DF_TASK_ID" --json` 读取 `description` 与 `description_version`。标题是简短名称，描述是当前需求，首条消息仅是历史事实；不能用首条消息替代描述。汇报前再次核对版本，若描述变化需重新核对范围与验收条件。
+每轮工作先读取当前 `description` 与 `description_version`。支持字段选择的 CLI 可用 `df-task get "$DF_TASK_ID" --fields id,description,description_version --json`，只在需要时追加明确的 metadata 路径；旧版用 `get --json` 保存到本轮文件再提取，不把完整 metadata 打进上下文。标题是简短名称，描述是当前需求，首条消息仅是历史事实；不能用首条消息替代描述。汇报前再次核对版本，若描述变化需重新核对范围与验收条件。
 
-## 目标环境门禁与地址
-
-每次调用服务前，必须先确认用户要操作的目标环境。在推进器拉起的 Run 里按下文「Run 内的目标环境」确定，不询问。其他情况下，用户没有明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
-
-```text
-请指定目标环境：local（本地）、dev（开发环境）还是 prod（生产环境）？
-```
-
-环境一旦选定，本轮所有服务调用都必须保持在同一环境；不能因为连接失败就切换到另一环境，也不能把当前机器所在位置当成目标环境。
-
-| 目标环境 | 本地执行时的地址 | 在 dev-k8s 内执行时的地址 |
-| --- | --- | --- |
-| `local` | `http://127.0.0.1:8090` | 不适用 |
-| `dev` | `https://deepflowtask.dev.deepwisdomai.com` | `http://deepflowtask.deepflow.svc.cluster.local:8090` |
-| `prod` | 尚未配置 | 尚未配置 |
-
-地址列描述的是同一目标环境的两种访问方式：本地 CLI 使用 dev Ingress，集群内 Agent 使用 dev Service DNS。确认环境后，可以用用户明确提供的 `--base-url` 覆盖该环境的默认地址，但该地址必须属于已选环境；如果地址与环境冲突，先停止并澄清，不能用它绕过环境门禁。`prod` 目前没有地址，任何 prod 操作都必须停止并说明尚未接入。
-
-本地操作 dev 时示例：
-
-```bash
-df-task --base-url https://deepflowtask.dev.deepwisdomai.com facts "$DF_TASK_ID" --json
-```
+## 环境与身份
 
 ### Run 内的目标环境
 
-`DF_TASK_ID`、`DF_RUN_ID`、`DF_TASK_ACTOR_KIND` 都非空时，你运行在推进器拉起的 Run 里，没有用户可以询问。此时目标环境由部署决定：用注入的 `DF_TASK_BASE_URL` 对照上表反查所属环境，例如 `http://deepflowtask.deepflow.svc.cluster.local:8090` 即 `dev`。每一轮、每个 Run 都按同一规则确定，不需要也不应该等待任何人确认。
-
-反查不到任何环境、地址属于 `prod`，或指令要求操作的环境与反查结果不一致时，停止，不调用服务、不改用其他地址，在最终回复里说明注入地址和冲突原因。推进器会照常记录本次执行结束，交给下一轮调度或人处理。
-
-不在 Run 里时，只有在用户明确选择 `dev` 且 `DF_TASK_BASE_URL` 确认属于 dev 时，才可以复用它；用户选择 `local` 时必须忽略该值并使用 `http://127.0.0.1:8090`。用户没有先选环境都不能执行请求。
-
-先用 `GET /healthz` 验证选定地址，再执行读写操作。健康检查失败时报告该环境不可达，不得静默改用 localhost 或其他环境。
+托管 Run 中 `DF_TASK_ID/DF_RUN_ID/DF_TASK_ACTOR_KIND` 非空，`DF_TASK_BASE_URL` 由部署注入，绑定本 Run 的事实服务；不询问、不根据同名 Service DNS 猜成 dev，不覆盖写入身份，不因业务目标出现“生产”而切换流程服务。身份或地址缺失/冲突先报告，不能伪造或回退 localhost。只核对必要值，不输出完整环境。在 Run 内一律使用 `--json`。
 
-下面的示例还用到两个变量，同样由 runtime 注入，同样不要自己编：`DF_TASK_ID` 是你这次执行所属的 Task，`DF_RUN_ID` 是你自己这个 Run 的标识（写事实时 payload 里的 `run_id` 填它）。如果它们是空的，说明这次执行不是由推进器兑现唤起起来的 —— 别猜一个填进去，写一条 `summary` 说明情况。
-
-**在 Run 里一律加 `--json`。** 不加 `--json` 的输出是给人看的排版，字段随时会调整。
-
-```bash
-# 按本轮需要选择事实类型（选择标准见「读日志」）
-df-task facts "$DF_TASK_ID" --types user_message,artifact_published --json
-df-task facts "$DF_TASK_ID" --types user_message,artifact_published --after 128 --limit 100 --json
-
-# 追加一条事实：payload 写成 JSON 文件再传
-# 注意 heredoc 的标记不加引号，加了引号 $DF_RUN_ID 就不会展开
-cat > /tmp/artifact.json <<JSON
-{"run_id":"$DF_RUN_ID","kind":"diff","ref":"abc1234def5678","title":"登录按钮溢出修复"}
-JSON
-df-task append "$DF_TASK_ID" --type artifact_published --file /tmp/artifact.json --json
-```
+外部调用须先确认 local/dev/prod，再按[环境与地址](references/environment.md)显式选址；用户未明确时先询问，连接失败不切换，跨服务保持同一环境。先验证所选地址 `/healthz`，不能用内部同名 DNS 猜环境。生产写操作仅限已有授权。
 
-## 业务 metadata 与软范围查询
+## metadata 与工具可用性
 
-Task 可以携带业务方自定义的 JSON metadata。基础服务只约定顶层的
-`source`、`query_keys` 和 `data`：前两个用于可选的软范围查询，`data` 完全由业务方组织。
-例如：
-
-```bash
-df-task create \
-  --title '订单分析' \
-  --metadata '{"source":"workbench","query_keys":["account:u123"],"data":{"project":"orders"}}' \
-  --json
-```
-
-`--metadata` 必须是 JSON 对象；没有 metadata 时服务保存 `{}`，不会改变原有流程。创建、
-列表和单Task读取会返回 metadata。事实读取也支持同一范围过滤：
-
-```bash
-SCOPE_SOURCE=workbench
-SCOPE_KEY=account:u123
-
-df-task ls \
-  --metadata-source "$SCOPE_SOURCE" \
-  --metadata-query-key "$SCOPE_KEY" \
-  --json
-df-task get "$DF_TASK_ID" \
-  --metadata-source "$SCOPE_SOURCE" \
-  --metadata-query-key "$SCOPE_KEY" \
-  --json
-df-task facts "$DF_TASK_ID" \
-  --metadata-source "$SCOPE_SOURCE" \
-  --metadata-query-key "$SCOPE_KEY" \
-  --json
-df-task stream \
-  --metadata-source "$SCOPE_SOURCE" \
-  --metadata-query-key "$SCOPE_KEY" \
-  --json
-```
-
-查询规则：
-
-- 同时提供 `source` 和 `query_key` 时，Task 必须匹配来源和查询标识；只提供其中一个时只按该条件过滤。`query_keys` 包含 `"*"` 的显式共享Task例外于这两个条件。
-- `query_keys` 可以包含多个标识；`"*"` 表示显式共享，匹配任意查询范围。
-- 不提供过滤参数仍然是历史上的全量查询。业务上下文存在时才携带过滤参数，不要把它当成权限边界。
-- 先从Task响应的 metadata 读取 `source` 和 `query_keys`，再把当前业务上下文中的具体 key 传给后续查询；不要从 `data` 中猜测过滤字段。
-
-metadata 只影响读请求的范围。`append`、`dispatch`、`wait`、`handoff` 和 `title` 仍按明确的
-Task ID 操作，不支持 metadata 过滤参数；事实服务不会根据 metadata 做鉴权。
+metadata 的 `source`、`query_keys` 用于可选软范围过滤，`data` 由业务方定义；它们不是权限边界。有业务上下文时沿用已确认的来源和具体 key，不能从 data 猜测。需要创建、查询或核对共享范围时读[范围查询说明](references/query-scope.md)。
 
 托管 Run 中 `df-task` 由 Runtime 镜像提供。命令缺失或 `--help` 无法执行时，报告执行环境异常并结束；不要在 Run 中安装、编译 CLI 或猜测绝对路径来继续。非托管的本地开发可按项目 README 安装 CLI。**注意不要把 runtime 的地址填成 Task 服务的地址** —— `df-agentrt` 和 `df-task` 是两个服务、两个端口、两套授权。
 
@@ -147,6 +60,25 @@ df-task facts "$DF_TASK_ID" \
 - API 不支持按 `run_id` 过滤、精确查单个 `seq` 或倒序取尾页。返回中按关联字段核对 Run/引用；不要尝试不存在的参数。
 - `artifact_published` 只有引用坐标。需要 diff、spec、MR 正文时，用 `ref` 到对应系统读取。
 
+### 字段选择与有界分页
+
+以下是新 CLI 的可选读取能力；以实际 `df-task help get/facts` 为准，旧版继续使用上面的单页 JSON 及游标，不在 Run 中安装或反复试错。
+
+```bash
+# get 的已知顶层字段；metadata 可选对象路径
+df-task get "$DF_TASK_ID" --fields id,description,description_version --json
+# --fields 作用于每条事实，分页信封保留；payload 可整体保留
+df-task facts "$DF_TASK_ID" --types summary,run_outcome --fields seq,type,actor_id,payload --json
+# 原文写本轮新文件，stdout 仅返回查询/数量/类型/完整性/文件摘要
+df-task facts "$DF_TASK_ID" --types dispatch_intent,invocation_started,invocation_accepted,invocation_ended \
+  --all --output-file /tmp/dispatch-facts.json --json
+```
+
+- `--fields` 必须显式指定且配合 `--json`。支持的顶层字段和对象路径、缺字段与 null 的区别见[读取契约](references/reading.md)。选择过的输出不证明其他字段没有信息；关键结论需要读原事实。
+- `--all` 必须配合 `--output-file`、`--json`，不能同时使用 `--fields`。文件保留完整事实；清单不是事实正文，按当前判断从文件提取必要的关联和 payload。
+- 默认最多 10 页、8 MiB，只有观察到空页才 `complete=true`。预算耗尽或请求失败会保留已接纳的完整页，返回 `complete=false`、`stop_reason` 和准确 `next_after_seq`，**退出 1**。不要把文件存在或读到部分事实当成读完；按缺口显式续读或报告未完成。
+- 文件是本轮私有缓存，拒绝覆盖；不是跨 Session 产物引用，不替代 Task 事实。`complete` 仅限清单所列类型/过滤/起始游标与本次查询，仍遵守上面的晚提交、换类型和水位规则。
+
 ## 任务 Run 可以写什么
 
 | 命令 | 落成哪条事实 | 什么时候写 |
@@ -195,7 +127,7 @@ df-task facts "$DF_TASK_ID" \
 
 ## 输出与错误
 
-`--json` 下 stdout 是服务端原样返回的 JSON。退出码只有三个：`0` 成功、`1` 网络或服务端失败、`2` 本地参数无效。**参数错误不会发出任何请求**，所以拿到 `2` 时日志里一定没有任何痕迹。
+默认 `--json` 下 stdout 是服务端原样 JSON；显式 `--fields` 输出所选字段，`--all` 输出读取清单。退出码 `0` 表示读取/写入成功，`1` 表示请求、解码、文件写入失败或有界分页未完成，`2` 表示本地参数/路径预检失败（未发请求）。`complete=false` 必须作为未完成读取处理。
 
 追加成功返回那条事实，含它的 `seq`。`--idempotency-key` 重复提交同一个键时返回**已存在的那条事实**，HTTP 状态是 `200` 而不是 `201` —— 这不是错误，重试是安全的。
 

package/bundle/skills/df-task/references/environment.md

@@ -0,0 +1,50 @@
+# 环境与地址
+
+
+每次调用服务前，必须先确认用户要操作的目标环境。在推进器拉起的 Run 里按下文「Run 内的目标环境」确定，不询问。其他情况下，用户没有明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
+
+```text
+请指定目标环境：local（本地）、dev（开发环境）还是 prod（生产环境）？
+```
+
+环境一旦选定，本轮所有服务调用都必须保持在同一环境；不能因为连接失败就切换到另一环境，也不能把当前机器所在位置当成目标环境。
+
+| 目标环境 | 集群外访问地址 | 对应环境集群内地址 |
+| --- | --- | --- |
+| `local` | `http://127.0.0.1:8090` | 不适用 |
+| `dev` | `https://deepflowtask.dev.deepwisdomai.com` | `http://deepflowtask.deepflow.svc.cluster.local:8090` |
+| `prod` | `https://deepflowtask.deepwisdomai.com` | `http://deepflowtask.deepflow.svc.cluster.local:8090` |
+
+`prod` 指国内生产 `prod-cn`。集群内地址只在对应环境集群中访问；dev 与 prod 的 Service DNS 字符串相同，不能仅凭该字符串反查环境，也不能从本机直接访问它来代替生产入口。CLI 不会按环境名自动选址：本地调用须显式设置已选环境的地址；可以使用用户提供且已确认归属的 `--base-url`，地址与已选环境冲突时先澄清，连接失败不得改用其他环境。生产写操作仍只执行当前任务已授权的范围。
+
+本地操作 dev 时示例：
+
+```bash
+df-task --base-url https://deepflowtask.dev.deepwisdomai.com facts "$DF_TASK_ID" --json
+```
+
+### Run 内的目标环境
+
+`DF_TASK_ID`、`DF_RUN_ID`、`DF_TASK_ACTOR_KIND` 都非空时，你运行在推进器拉起的 Run 里。`DF_TASK_BASE_URL` 由部署注入，绑定当前 Run 所属的事实服务；沿用它访问本 Task，不重新询问环境、不根据同名 Service DNS 猜成 dev，也不因业务需求中出现“生产/开发”就重定向流程服务。业务项目的目标环境与 DeepFlow 流程服务的部署环境分别核对。
+
+注入地址缺失或与当前流程已确认的部署环境冲突时，停止相关调用并说明缺口；不回退 localhost、不自行改地址或伪造身份。不在 Run 里时，先由用户选择环境，再按上表显式选址；内部 DNS 需要已确认的集群访问上下文。
+
+先用 `GET /healthz` 验证选定地址，再执行读写操作。健康检查失败时报告该环境不可达，不得静默改用 localhost 或其他环境。
+
+下面的示例还用到两个变量，同样由 runtime 注入，同样不要自己编：`DF_TASK_ID` 是你这次执行所属的 Task，`DF_RUN_ID` 是你自己这个 Run 的标识（写事实时 payload 里的 `run_id` 填它）。如果它们是空的，说明这次执行不是由推进器兑现唤起起来的 —— 别猜一个填进去，写一条 `summary` 说明情况。
+
+**在 Run 里一律加 `--json`。** 不加 `--json` 的输出是给人看的排版，字段随时会调整。
+
+```bash
+# 按本轮需要选择事实类型（选择标准见「读日志」）
+df-task facts "$DF_TASK_ID" --types user_message,artifact_published --json
+df-task facts "$DF_TASK_ID" --types user_message,artifact_published --after 128 --limit 100 --json
+
+# 追加一条事实：payload 写成 JSON 文件再传
+# 注意 heredoc 的标记不加引号，加了引号 $DF_RUN_ID 就不会展开
+cat > /tmp/artifact.json <<JSON
+{"run_id":"$DF_RUN_ID","kind":"diff","ref":"abc1234def5678","title":"登录按钮溢出修复"}
+JSON
+df-task append "$DF_TASK_ID" --type artifact_published --file /tmp/artifact.json --json
+```
+

package/bundle/skills/df-task/references/query-scope.md

@@ -0,0 +1,49 @@
+# metadata 与软范围查询
+
+
+Task 可以携带业务方自定义的 JSON metadata。基础服务只约定顶层的
+`source`、`query_keys` 和 `data`：前两个用于可选的软范围查询，`data` 完全由业务方组织。
+例如：
+
+```bash
+df-task create \
+  --title '订单分析' \
+  --metadata '{"source":"workbench","query_keys":["account:u123"],"data":{"project":"orders"}}' \
+  --json
+```
+
+`--metadata` 必须是 JSON 对象；没有 metadata 时服务保存 `{}`，不会改变原有流程。创建、
+列表和单Task读取会返回 metadata。事实读取也支持同一范围过滤：
+
+```bash
+SCOPE_SOURCE=workbench
+SCOPE_KEY=account:u123
+
+df-task ls \
+  --metadata-source "$SCOPE_SOURCE" \
+  --metadata-query-key "$SCOPE_KEY" \
+  --json
+df-task get "$DF_TASK_ID" \
+  --metadata-source "$SCOPE_SOURCE" \
+  --metadata-query-key "$SCOPE_KEY" \
+  --json
+df-task facts "$DF_TASK_ID" \
+  --metadata-source "$SCOPE_SOURCE" \
+  --metadata-query-key "$SCOPE_KEY" \
+  --json
+df-task stream \
+  --metadata-source "$SCOPE_SOURCE" \
+  --metadata-query-key "$SCOPE_KEY" \
+  --json
+```
+
+查询规则：
+
+- 同时提供 `source` 和 `query_key` 时，Task 必须匹配来源和查询标识；只提供其中一个时只按该条件过滤。`query_keys` 包含 `"*"` 的显式共享Task例外于这两个条件。
+- `query_keys` 可以包含多个标识；`"*"` 表示显式共享，匹配任意查询范围。
+- 不提供过滤参数仍然是历史上的全量查询。业务上下文存在时才携带过滤参数，不要把它当成权限边界。
+- 先从Task响应的 metadata 读取 `source` 和 `query_keys`，再把当前业务上下文中的具体 key 传给后续查询；不要从 `data` 中猜测过滤字段。
+
+metadata 只影响读请求的范围。`append`、`dispatch`、`wait`、`handoff` 和 `title` 仍按明确的
+Task ID 操作，不支持 metadata 过滤参数；事实服务不会根据 metadata 做鉴权。
+

package/bundle/skills/df-task/references/reading.md

@@ -0,0 +1,9 @@
+# CLI 读取契约
+
+`--fields` 只在 `get/facts --json` 可用，默认 `--json` 不变。get 顶层可选 `id,title,description,description_version,metadata,created_at,updated_at`；facts 每条可选 `seq,type,actor_kind,actor_id,payload,idempotency_key,created_at`。metadata/payload 允许点分对象路径；无数组下标、表达式、通配符或父子路径重叠。不存在的路径省略，直接选中的 null 保留；数值不经过浮点转换。facts 的 task_id、next_after_seq 及其他信封字段保留。没有业务摘要、排序或正文裁剪。
+
+`facts --all --output-file PATH --json` 可沿用 `--after/--types/--limit/--metadata-source/--metadata-query-key`。默认 page limit=200，max-pages=10，max-bytes=8388608；显式预算范围分别 1..100、1..67108864。字节预算按接纳前的 HTTP 响应计，超过预算的页整体不接纳，游标不跳过该页。页必须匹配 Task、严格递增，next_after_seq 必须等于该页末 seq；空页保留输入游标。
+
+清单字段：query（Task、地址、类型、过滤、起始游标、page limit）、complete、stop_reason、pages（接纳页数，含终止空页）、count、first_seq/last_seq（有事实时）、next_after_seq、type_counts、response_bytes、output_file、file_bytes、file_sha256。正文不会进入清单。文件包含 query、facts、complete、stop_reason、next_after_seq，权限 0600，原子发布且不覆盖。SHA 对应实际文件字节。
+
+stop_reason：empty_page 表示本次见到空页；page_limit/byte_limit 表示预算耗尽；request_error/invalid_page 表示失败。除 empty_page 外 complete=false 且退出 1；本地参数/路径预检错误退出 2（未发请求）。本地写入失败不返回伪造的成功清单。显式续读须保持过滤条件，使用已返回的 next_after_seq 和新的文件名；先前文件不会被补写。complete 不承诺事务快照或不存在晚提交。

package/bundle/skills/df-taskdriver/SKILL.md

@@ -21,13 +21,13 @@ CLI 由 `@metagptx/deepflow-suite-cli` 统一安装，本 Skill 不携带 CLI
 
 环境一旦选定，本轮所有服务调用都必须保持在同一环境；不能因为连接失败就切换到另一环境，也不能把当前机器所在位置当成目标环境。
 
-| 目标环境 | 本地执行时的地址 | 在 dev-k8s 内执行时的地址 |
+| 目标环境 | 集群外访问地址 | 对应环境集群内地址 |
 | --- | --- | --- |
 | `local` | `http://127.0.0.1:8081` | 不适用 |
 | `dev` | `https://deepflowtaskdriver.dev.deepwisdomai.com` | `http://deepflowtaskdriver.deepflow.svc.cluster.local:8081` |
-| `prod` | 尚未配置 | 尚未配置 |
+| `prod` | `https://deepflowtaskdriver.deepwisdomai.com` | `http://deepflowtaskdriver.deepflow.svc.cluster.local:8081` |
 
-地址列描述的是同一目标环境的两种访问方式：本地 CLI 使用 dev Ingress，集群内 Agent 使用 dev Service DNS。确认环境后，可以用用户明确提供的 `--base-url` 覆盖该环境的默认地址，但该地址必须属于已选环境；如果地址与环境冲突，先停止并澄清，不能用它绕过环境门禁。`prod` 目前没有地址，任何 prod 操作都必须停止并说明尚未接入。
+`prod` 指国内生产 `prod-cn`。集群内地址只在对应环境集群中访问；dev 与 prod 的 Service DNS 字符串相同，不能仅凭该字符串反查环境，也不能从本机直接访问它来代替生产入口。CLI 不会按环境名自动选址：本地调用须显式设置已选环境的地址；可以使用用户提供且已确认归属的 `--base-url`，地址与已选环境冲突时先澄清，连接失败不得改用其他环境。生产写操作仍只执行当前任务已授权的范围。
 
 本地操作 dev 时示例：
 

package/bundle/skills/df-workbench/SKILL.md

@@ -15,6 +15,14 @@ CLI 由 `@metagptx/deepflow-suite-cli` 统一安装，本 Skill 不携带 CLI
 
 用户必须先明确目标环境：`local`、`dev` 或 `prod`。本轮不要因为连接失败自动切换环境。
 
+| 环境 | Workbench 根地址 |
+| --- | --- |
+| `local` | `http://127.0.0.1:8793` |
+| `dev` | `https://deepflowworkbench.dev.deepwisdomai.com` |
+| `prod`（国内生产 `prod-cn`） | `https://deepflowworkbench.deepwisdomai.com` |
+
+CLI 不会根据环境名自动切换地址。确认环境后显式设置 `DF_WORKBENCH_BASE_URL`；Token 与工作区也须属于该入口，不能复用 dev 身份去操作 prod。生产写操作只执行当前任务已授权的范围。
+
 CLI 配置：
 
 ```text
@@ -32,7 +40,11 @@ df-workbench config --json
 
 `me` 返回当前用户和可访问工作区；`config` 返回认证模式、当前工作区、Task 写入能力和 Workbench UI 能力。不要打印 Token、Cookie 或其他凭据。
 
-local 环境只允许从本机回环地址访问；OIDC 环境使用 Workbench personal token。Token 应通过公司内部配置或 Skill 平台提供，不在命令参数中传递。
+local 环境只允许从本机回环地址访问，无需 Token；OIDC 环境使用 Workbench personal token。
+
+Token 获取入口：使用公司账号登录目标环境 Workbench，打开「头像 → 个人设置 → 个人 Token → 创建 Token」，填写用途名称和到期时间。完整 Token 只在创建时显示一次，将其配置为 `DF_WORKBENCH_TOKEN`；`DF_WORKBENCH_BASE_URL` 使用同一环境的 Workbench 根地址。也可通过公司内部配置或 Skill 平台的个人凭据配置提供，不在命令参数中传递，不打印凭据。
+
+列表仅显示前缀和使用状态，无法找回完整 Token；遗失、到期或不再使用时，在同一入口撤销并按需新建。独立管理员账号不支持创建个人 Token，需使用公司账号登录。网页退出不会撤销 Token。
 
 ## 用户任务流程
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metagptx/deepflow-suite-cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Agent-friendly installer and distribution CLI for the DeepFlow suite.",
   "license": "UNLICENSED",
   "type": "module",

package/runtime/df-agentctrl/release.json

@@ -1 +1 @@
-{"version":"0.3.0","project":"deepflow-agent-ctrl","sourceCommit":"e3aa5dee2eb31a7267e69f48127175deab664fe0","sourceDirty":false}
+{"version":"0.3.1","project":"deepflow-agent-ctrl","sourceCommit":"10e745773559f4712b04ab61915a018995e30630","sourceDirty":false}

package/runtime/df-agentrt/release.json

@@ -1 +1 @@
-{"version":"0.3.0","project":"deepflow-agent-runtime","sourceCommit":"12624d320d032b65d8f4ed3fdd0193d33d95be7d","sourceDirty":false}
+{"version":"0.3.1","project":"deepflow-agent-runtime","sourceCommit":"420ebb91ed4cf92ca81eb8c295cc111f94b9da2c","sourceDirty":false}

package/runtime/df-agentrt/result.mjs

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import { mkdtemp, open, link, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+const terminal = (status) => ['succeeded', 'failed', 'cancelled'].includes(status);
+const statuses = ['pending', 'waiting_for_runtime', 'claimed', 'running', 'succeeded', 'failed', 'cancelled'];
+export function resultView(inv, maxBytes) {
+  const view = { invocation_id: inv.id, session_id: inv.session_id, status: inv.status, terminal: terminal(inv.status), result_state: terminal(inv.status) ? 'missing' : 'pending', output_present: false, output: '', output_bytes: 0, output_returned_bytes: 0, output_truncated: false };
+  if (inv.finished_at) view.finished_at = inv.finished_at;
+  if (inv.error) view.error = inv.error;
+  const invalid = (message) => { view.result_state = 'invalid'; view.format_error = message; return { view, output: '' }; };
+  if (!statuses.includes(inv.status)) { view.result_state = 'invalid'; view.format_error = 'unknown invocation status'; }
+  if (!inv.result) return { view, output: '' };
+  let result;
+  try { result = JSON.parse(inv.result); } catch { return invalid('result is not a JSON object'); }
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return invalid('result is not a JSON object');
+  for (const [field, target] of [['error', 'result_error'], ['failure_reason', 'failure_reason']]) {
+    if (!Object.hasOwn(result, field) || result[field] === null) continue;
+    if (typeof result[field] !== 'string') return invalid(`${field} is not a string`);
+    if (result[field]) view[target] = result[field];
+  }
+  if (!Object.hasOwn(result, 'output') || result.output === null) return { view, output: '' };
+  if (typeof result.output !== 'string') return invalid('output is not a string');
+  const bytes = Buffer.from(result.output);
+  view.output_present = true; view.output_bytes = bytes.length;
+  if (view.terminal) view.result_state = 'available';
+  view.output_sha256 = createHash('sha256').update(bytes).digest('hex');
+  let end = Math.min(maxBytes, bytes.length);
+  if (end < bytes.length) while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--;
+  view.output = bytes.subarray(0, end).toString('utf8');
+  view.output_truncated = bytes.length > maxBytes;
+  view.output_returned_bytes = end;
+  return { view, output: result.output };
+}
+
+// Publish a private file atomically without replacing a concurrent destination.
+export async function writeResultFile(destination, data) {
+  const directory = await mkdtemp(path.join(path.dirname(destination), '.invocation-result-'));
+  try {
+    const staging = path.join(directory, 'output'), file = await open(staging, 'wx', 0o600);
+    try { await file.writeFile(data); } finally { await file.close(); }
+    await link(staging, destination);
+  } finally { await rm(directory, { recursive: true, force: true }); }
+}

package/runtime/df-agentrt/runtime.mjs

@@ -1,9 +1,10 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, lstat } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
 import { usage } from './usage.mjs';
+import { resultView, writeResultFile } from './result.mjs';
 
 const terminal = (status) => ['succeeded', 'failed', 'cancelled'].includes(status);
 const decode = (raw) => JSON.parse(raw, (_key, value, context) => typeof value === 'number' && !Number.isSafeInteger(value) && /^-?\d+$/.test(context.source) ? BigInt(context.source) : value);
@@ -49,11 +50,11 @@ export class RuntimeCLI {
     if (!addr) this.environment('MULTICA_SERVER_URL is not set, so there is no runtime API to talk to; this command only works inside a running task');
     return addr.replace(/\/+$/, '');
   }
-  async request(method, route, body, { headers = {}, raw = false, stream = false, signal } = {}) {
+  async request(method, route, body, { headers = {}, raw = false, stream = false, signal, responseLimit = 0, timeout = false } = {}) {
     const addr = this.address();
     let response;
     try {
-      response = await fetch(addr + route, { method, headers: { ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}), ...(stream ? { Accept: 'text/event-stream' } : {}), ...headers }, body: body === undefined ? undefined : typeof body === 'string' ? body : JSON.stringify(body), signal: signal || (!stream && this.self ? AbortSignal.timeout(30000) : undefined) });
+      response = await fetch(addr + route, { method, headers: { ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}), ...(stream ? { Accept: 'text/event-stream' } : {}), ...headers }, body: body === undefined ? undefined : typeof body === 'string' ? body : JSON.stringify(body), signal: signal || (!stream && (this.self || timeout) ? AbortSignal.timeout(30000) : undefined) });
     } catch (error) { throw new Failure(`cannot reach the runtime API at ${addr}: ${error.message}`); }
     if (!response.ok) {
       const text = (await response.text()).slice(0, 65536); let error;
@@ -62,7 +63,16 @@ export class RuntimeCLI {
     }
     if (stream) return response.body;
     if (method === 'DELETE') { await response.body?.cancel(); return; }
-    const text = await response.text();
+    let text;
+    if (responseLimit) {
+      const chunks = []; let bytes = 0;
+      for await (const chunk of response.body) {
+        bytes += chunk.length;
+        if (bytes > responseLimit) throw new Failure(`response exceeds ${responseLimit} bytes`);
+        chunks.push(chunk);
+      }
+      text = Buffer.concat(chunks).toString('utf8');
+    } else text = await response.text();
     try { const value = decode(text); return raw ? text.trim() : value; } catch (error) { throw new Failure(`decode response: ${error.message}`); }
   }
   async ownSession() {
@@ -86,6 +96,27 @@ export class RuntimeCLI {
     return encodeURIComponent(rest[0]);
   }
   async getJSON(route) { this.stdout.write(await this.request('GET', route, undefined, { raw: true }) + '\n'); }
+  async invocationCmd(command, args) {
+    const form = `usage: ${this.name} invocation result <invocation-id> [--json] [--max-bytes N] [--output-file PATH]`;
+    if (command !== 'result') this.fail(form);
+    if (args.includes('--help') || args.includes('-h')) { this.stdout.write(form + '\n'); return; }
+    const { v, rest } = flags(args, ['max-bytes', 'output-file'], ['json']);
+    numeric(v['max-bytes'], 'max-bytes', 1n << 20n);
+    const maxBytes = Number(v['max-bytes'] ?? 4096);
+    if (rest.length !== 1 || !rest[0].trim() || maxBytes < 1) this.fail(form);
+    let destination;
+    if ('output-file' in v) {
+      if (!v['output-file'].trim()) this.fail('--output-file must not be empty');
+      destination = path.resolve(v['output-file']);
+      try { await lstat(destination); this.fail(`output file already exists: ${destination}`); }
+      catch (error) { if (error.code !== 'ENOENT') this.fail(error.message); }
+    }
+    const inv = await this.request('GET', `/v1/invocations/${encodeURIComponent(rest[0])}`, undefined, { responseLimit: 64 << 20, timeout: true });
+    if (!inv || inv.id !== rest[0] || typeof inv.session_id !== 'string' || !inv.session_id || typeof inv.status !== 'string' || !inv.status) throw new Failure('invalid invocation identity or status in response');
+    const { view, output } = resultView(inv, maxBytes);
+    if (destination && view.output_present) { await writeResultFile(destination, output); view.output_file = destination; }
+    this.stdout.write(JSON.stringify(view, null, v.json ? undefined : 2) + '\n');
+  }
   printSession(s) {
     const rows = [['id', s.id], ['provider', s.provider], ['status', s.status]];
     if (s.client_ref) rows.push(['client_ref', s.client_ref]);
@@ -301,6 +332,7 @@ export class RuntimeCLI {
       }
       const [group, command, ...rest] = args;
       if (group === 'events') await this.events(args.slice(1));
+      else if (group === 'invocation') await this.invocationCmd(command, rest);
       else if (['session', 'repo', 'msg', 'ops'].includes(group)) {
         if (!command) this.groupUsage(group);
         else if (group === 'session') await this.sessionCmd(command, rest);

package/runtime/df-agentrt/usage.mjs

@@ -1,13 +1,13 @@
 export const usage = {
   "df-agentrt": {
-    "": "df-agentrt -- DeepFlow Agent Runtime, from inside a task\n\nTHIS SESSION\n  df-agentrt session info                           Which session this is:\n                                                    provider, model, working\n                                                    directory, repositories,\n                                                    and whether the\n                                                    conversation history\n                                                    survived into this turn.\n  df-agentrt session turns [--session ID] [--json]  Every turn; defaults to\n                                                    this session.\n  df-agentrt events [--session ID] [--after N]      The message stream. Also\n                                                    --limit N, --raw and\n                                                    --follow.\n  df-agentrt repo list                              The repositories this\n                                                    session may check out.\n  df-agentrt repo search <name>                     Find an application and\n                                                    the repository its code\n                                                    lives in.\n  df-agentrt repo add <url|code> ...                Make another repository\n                                                    available and check it out\n                                                    now. Prints the absolute\n                                                    path of each checkout.\n  df-agentrt msg cancel [invocation-id]             Ask a turn to stop;\n                                                    defaults to the current\n                                                    turn.\n\nOTHER SESSIONS\n  df-agentrt session ls                             Sessions on this runtime.\n  df-agentrt session get <id> [--json]              One session in full.\n  df-agentrt session create ...                     Start a new session. It\n                                                    runs an agent and costs\n                                                    money, and it does not end\n                                                    by itself.\n  df-agentrt msg send <id> <text>                   Queue a turn on another\n                                                    session. Same caveat.\n\nRUNTIME\n  df-agentrt ops runtimes [--json]                  Which execution engines\n                                                    are registered and alive.\n  df-agentrt ops orphans                            Where the records and the\n                                                    world have drifted apart.\n\nRun `df-agentrt <group>` for the flags of one group.\n",
+    "": "df-agentrt -- DeepFlow Agent Runtime, from inside a task\n\nTHIS SESSION\n  df-agentrt session info                           Which session this is:\n                                                    provider, model, working\n                                                    directory, repositories,\n                                                    and whether the\n                                                    conversation history\n                                                    survived into this turn.\n  df-agentrt session turns [--session ID] [--json]  Every turn; defaults to\n                                                    this session.\n  df-agentrt events [--session ID] [--after N]      The message stream. Also\n                                                    --limit N, --raw and\n                                                    --follow.\n  df-agentrt repo list                              The repositories this\n                                                    session may check out.\n  df-agentrt repo search <name>                     Find an application and\n                                                    the repository its code\n                                                    lives in.\n  df-agentrt repo add <url|code> ...                Make another repository\n                                                    available and check it out\n                                                    now. Prints the absolute\n                                                    path of each checkout.\n  df-agentrt msg cancel [invocation-id]             Ask a turn to stop;\n                                                    defaults to the current\n                                                    turn.\n\nOTHER SESSIONS\n  df-agentrt invocation result <id> [--json]         Read a bounded final result.\n                                                    --output-file saves full text.\n  df-agentrt session ls                             Sessions on this runtime.\n  df-agentrt session get <id> [--json]              One session in full.\n  df-agentrt session create ...                     Start a new session. It\n                                                    runs an agent and costs\n                                                    money, and it does not end\n                                                    by itself.\n  df-agentrt msg send <id> <text>                   Queue a turn on another\n                                                    session. Same caveat.\n\nRUNTIME\n  df-agentrt ops runtimes [--json]                  Which execution engines\n                                                    are registered and alive.\n  df-agentrt ops orphans                            Where the records and the\n                                                    world have drifted apart.\n\nRun `df-agentrt <group>` for the flags of one group.\n",
     "session": "df-agentrt session <command>\n\n  info                This session. Includes whether the conversation history\n                      carried over into this turn -- if it did not, you have the\n                      same files but none of what was said before.\n  turns [--session ID] [--json]\n                      Every turn; defaults to this session, oldest first.\n  ls                  Sessions on this runtime.\n  get      <id> [--json] [--metadata-source S] [--metadata-query-key K]\n                      Another session in full.\n  create   --provider P [--model M] [--thinking-level L] [--instructions S]\n           [--skill S ...] [--repo R ...] [--client-ref REF] [--mcp-config FILE]\n           [--metadata JSON]\n           [--idempotency-key KEY]\n                      Start a new session. It runs an agent and costs money, and\n                      nothing ends it for you.\n  release  <id>       Stop a session accepting turns and ask for its working\n                      directory back.\n  rm       <id>       Delete a session's record, message stream included.\n\nEverything about a session except its repository set is fixed at creation.\nFor repositories see `df-agentrt repo` -- those can be appended afterwards.\n",
     "repo": "df-agentrt repo <command>\n\n  list                        The repositories this session may check out.\n  search  <name>              Find an application and the repository its code\n                              lives in. Use this when you know what a thing is\n                              called but not where its code is.\n  add     <url|app-code> ...  Make another repository available to this session\n          [--ref REF]         and check it out now. Prints the absolute path of\n                              each checkout on stdout; nothing else to run\n                              afterwards. --ref takes one repository only.\n\nAn argument containing \"://\" or \"@\" is treated as a clone url and stored\nverbatim; anything else is treated as an application code and looked up for\nyou. A code can never contain either, so the two cannot be confused.\n\nAppend-only: there is no remove. Removing a repository you are working inside\nwould break this turn.\n",
     "msg": "df-agentrt msg <command>\n\n  send    <session-id> <text> [--follow] [--idempotency-key KEY] [--raw]\n          Queue a turn on another session. That session runs an agent and\n          costs money; it is not this one. --follow waits for the turn to\n          finish, which blocks you for as long as it runs.\n  cancel  [<turn-id>]\n          Ask a turn to stop. With no argument, the turn you are executing\n          right now -- you will be asked to wind down, not killed outright.\n",
     "ops": "df-agentrt ops <command>\n\n  runtimes [--json]  Which daemons have registered, and which are still alive.\n  orphans [--fix]    Where the records and the world have drifted apart.\n                     Reports only unless --fix is given; --fix fails stranded\n                     turns on other sessions and cannot be undone.\n"
   },
   "agentrt": {
-    "": "agentrt -- DeepFlow Agent Runtime CLI\n\nUSAGE\n  agentrt <group> <command> [flags]\n\nGROUPS\n  session   info | create | get | ls | turns | release | rm\n  repo      ls | add | search\n  msg       send | cancel\n  events    events <session> [--after N]\n  ops       runtimes | orphans\n\nENVIRONMENT\n  AGENTRT_ADDR      Base URL of the runtime API (default http://127.0.0.1:8141)\n\nRun `agentrt <group>` for that group's commands.\n",
+    "": "agentrt -- DeepFlow Agent Runtime CLI\n\nUSAGE\n  agentrt <group> <command> [flags]\n\nGROUPS\n  session   info | create | get | ls | turns | release | rm\n  invocation result <id> [--json] [--max-bytes N] [--output-file PATH]\n  repo      ls | add | search\n  msg       send | cancel\n  events    events <session> [--after N]\n  ops       runtimes | orphans\n\nENVIRONMENT\n  AGENTRT_ADDR      Base URL of the runtime API (default http://127.0.0.1:8141)\n\nRun `agentrt <group>` for that group's commands.\n",
     "session": "agentrt session <command>\n\n  info     <session-id>    The same view as get. Named for the agent-side CLI,\n                           where it is the command for \"which session am I in\".\n  create   --provider P [--model M] [--thinking-level L] [--instructions S]\n           [--skill S ...] [--repo R ...] [--client-ref REF] [--mcp-config FILE]\n           [--idempotency-key KEY]\n  get      <session-id> [--json] [--metadata-source S] [--metadata-query-key K]\n\t  ls       [--status active|released] [--limit N] [--metadata-source S] [--metadata-query-key K]\n  turns    <session-id> [--json] (or --session <session-id>)\n                           Every turn of one session, oldest first -- the same\n                           timeline the web UI draws, from the same endpoint.\n  release  <session-id>    Stop accepting turns; Phase 1 keeps the Worker workspace.\n                           Events and active workspace reads stay available afterwards.\n\t rm       <session-id>    Delete the record. Workspace archive is not a Phase 1 operation.\n\nEverything here except the repository set is fixed when the session is created.\nFor repositories, see `agentrt repo` -- they can be appended to afterwards.\n",
     "repo": "agentrt repo <command>\n\n  ls      <session-id>                     Repositories this session may check out.\n  add     <session-id> <url|app-code> ...  Append repositories. Takes effect on the\n                                           next checkout, including mid-turn.\n          [--ref REF]                      Branch, tag or commit. One repository only.\n  search  <name>                           Find an application and its repository in\n                                           the registry.\n\nAn argument containing \"://\" or \"@\" is taken as a clone URL and stored\nverbatim; anything else is taken as an application code and resolved against\nthe registry. A code can never contain either, so the two cannot be confused.\n\nAppend-only: there is no remove. Removing a repository the agent is working\ninside would break the turn in flight.\n",
     "msg": "agentrt msg <command>\n\n  send    <session-id> <text> [--follow] [--idempotency-key KEY] [--raw]\n          Queue one turn. --follow attaches to the event stream and waits for\n          the turn to finish, exiting non-zero if it failed.\n  cancel  <invocation-id>\n          Ask for a running turn to stop. Returns as soon as the request is\n          recorded, which is before the agent has actually wound down.\n",

package/runtime/df-task/commands.mjs

@@ -2,9 +2,10 @@ export const help = `df-task — DeepFlow Task fact log CLI
 
 Usage:
   df-task ls [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]
-  df-task get <task-id> [--metadata-source <source>] [--metadata-query-key <key>]
+  df-task get <task-id> [--fields <paths> --json] [--metadata-source <source>] [--metadata-query-key <key>]
   df-task create --title <text> [--description <text>] [--message <text>] [--metadata <json>]
   df-task facts <task-id> [--after <seq>] [--types <a,b>] [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]
+  df-task facts <task-id> --all --output-file <path> --json [--max-pages <n>] [--max-bytes <n>]
   df-task append <task-id> --type <type> --file payload.json [--idempotency-key <k>]
   df-task stream [--after <seq>] [--types <a,b>] [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]
   df-task title <task-id> --title <text>
@@ -41,9 +42,10 @@ export const commands = {
     "writes": false
   },
   "get": {
-    "usage": "get <task-id> [--metadata-source <source>] [--metadata-query-key <key>]",
-    "description": "Read one task's identity.",
+    "usage": "get <task-id> [--fields <paths> --json] [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "Read one task's identity. --fields selects known fields and object paths; absent paths are omitted.",
     "flags": [
+      "--fields",
       "--metadata-source",
       "--metadata-query-key"
     ],
@@ -67,9 +69,14 @@ export const commands = {
     "writes": true
   },
   "facts": {
-    "usage": "facts <task-id> [--after <seq>] [--types <a,b>] [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]",
-    "description": "Read one task's facts in seq order.",
+    "usage": "facts <task-id> [--after <seq>] [--types <a,b>] [--limit <n>] [--fields <paths> --json | --all --output-file <path> --json [--max-pages <n>] [--max-bytes <n>]] [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "Read facts in seq order. --fields selects fields per fact, retaining pagination. --all writes complete raw pages to a private file and prints a manifest; limits default to 10 pages / 8 MiB. Only an observed empty page marks complete. Partial reads exit 1.",
     "flags": [
+      "--fields",
+      "--all",
+      "--output-file",
+      "--max-pages",
+      "--max-bytes",
       "--after",
       "--types",
       "--limit",

package/runtime/df-task/df-task.mjs

@@ -4,9 +4,10 @@ import { fileURLToPath } from 'node:url';
 import { realpathSync } from 'node:fs';
 import { help, commands } from './commands.mjs';
 import { factTypes, actorKinds } from './protocol.mjs';
+import { validateReadOptions, projectResponse, readAllFacts, readResponse } from './read.mjs';
 
 const uuid = /^(?:urn:uuid:)?(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\})$/i;
-const valueFlags = new Set(['--base-url', ...Object.values(commands).flatMap((spec) => spec.flags)]);
+const valueFlags = new Set(['--base-url', ...Object.values(commands).flatMap((spec) => spec.flags).filter((flag) => flag !== '--all')]);
 export function parse(args) {
   const o = { command: '', args: [], values: {}, json: false, help: false };
   const seen = new Set();
@@ -20,6 +21,9 @@ export function parse(args) {
     if (['--help', '-h', '--json'].includes(key)) {
       if (equals >= 0) throw Error(`${key} does not take a value`);
       o[key === '--json' ? 'json' : 'help'] = true;
+    } else if (key === '--all') {
+      if (equals >= 0) throw Error(`${key} does not take a value`);
+      o.values[key] = 'true';
     } else if (valueFlags.has(key)) {
       if (equals < 0 && (i + 1 === args.length || args[i + 1].startsWith('--'))) throw Error(`${key} requires a value`);
       o.values[key] = equals < 0 ? args[++i] : arg.slice(equals + 1);
@@ -57,6 +61,7 @@ export function validate(o, env) {
     if (!actorKinds.includes(env.DF_TASK_ACTOR_KIND)) throw Error(`unknown DF_TASK_ACTOR_KIND ${env.DF_TASK_ACTOR_KIND}`);
     if (o.command === 'metadata' && env.DF_TASK_ACTOR_KIND !== 'human') throw Error('metadata requires DF_TASK_ACTOR_KIND=human');
   }
+  validateReadOptions(o);
 }
 function object(raw, message) {
   let value;
@@ -127,7 +132,7 @@ export async function run(args, { env = process.env, stdout = process.stdout, st
     stdout.write((args.includes('--json') ? JSON.stringify(report) : `df-task ${version}`) + '\n');
     return 0;
   }
-  let o, base, req;
+  let o, base, initialRequest;
   try {
     o = parse(args);
     if (o.command === 'help' && !o.args.length) { stdout.write(help); return 0; }
@@ -139,15 +144,22 @@ export async function run(args, { env = process.env, stdout = process.stdout, st
     base = o.values['--base-url'] || env.DF_TASK_BASE_URL || 'http://127.0.0.1:8090';
     const url = new URL(base);
     if (!['http:', 'https:'].includes(url.protocol) || url.search || url.hash || url.username || url.password) throw Error('invalid base URL');
-    req = await requestFor(o);
+    initialRequest = await requestFor(o);
   } catch (error) { stderr.write(error.message + '\n'); return 2; }
-  try {
+  const request = async (options, limit = 0) => {
+    const req = options === o ? initialRequest : await requestFor(options);
     const headers = req.body ? { 'Content-Type': 'application/json' } : {};
     if (req.method !== 'GET') { headers['X-DF-Actor-Kind'] = env.DF_TASK_ACTOR_KIND; headers['X-DF-Actor-Id'] = env.DF_TASK_ACTOR_ID; }
     const response = await fetch(base.replace(/\/+$/, '') + req.path, { method: req.method, body: req.body, headers, signal: AbortSignal.timeout(30000) });
-    const data = await response.text();
+    const data = await readResponse(response, limit);
     if (response.status >= 400) throw Error(`HTTP ${response.status}: ${data.trim()}`);
     try { JSON.parse(data); } catch { throw Error('server returned invalid JSON'); }
+    return data;
+  };
+  if (o.values['--all']) return readAllFacts(o, base, request, stdout, stderr);
+  try {
+    let data = await request(o, '--fields' in o.values ? 64 << 20 : 0);
+    if ('--fields' in o.values) data = projectResponse(o.command, data, o.values['--fields'].split(','));
     if (o.json) stdout.write(data + '\n'); else human(o.command, data, stdout);
     return 0;
   } catch (error) { stderr.write(error.message + '\n'); return 1; }