@datarails-ai/dr-cli 1.6.152 → 1.6.153

package/dist/cli.js

@@ -8,7 +8,7 @@ import { fileURLToPath as fileURLToPath3 } from "url";
 // package.json
 var package_default = {
   name: "@datarails-ai/dr-cli",
-  version: "1.6.152",
+  version: "1.6.153",
   description: "Datarails CLI",
   type: "module",
   engines: {
@@ -69,7 +69,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-10-22T10:56:58.559Z";
+var BUILD_TIME = "2026-10-22T11:50:40.297Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -69877,18 +69877,18 @@ async function preflightFile(filePath) {
       `${filePath}: unsupported file type "${ext}". Supported: ${[...EXT_TO_MIME.keys()].join(", ")}`
     );
   }
-  let stat3;
+  let stat4;
   try {
-    stat3 = await fsPromises3.stat(filePath);
+    stat4 = await fsPromises3.stat(filePath);
   } catch (err) {
     const m = err instanceof Error ? err.message : String(err);
     throw new Error(`${filePath}: ${m}`);
   }
-  if (!stat3.isFile()) {
+  if (!stat4.isFile()) {
     throw new Error(`${filePath}: not a regular file`);
   }
-  if (stat3.size > MAX_FILE_BYTES) {
-    const mb = (stat3.size / (1024 * 1024)).toFixed(1);
+  if (stat4.size > MAX_FILE_BYTES) {
+    const mb = (stat4.size / (1024 * 1024)).toFixed(1);
     throw new Error(
       `${filePath}: file is ${mb}MB, exceeds ${MAX_FILE_BYTES / (1024 * 1024)}MB limit`
     );
@@ -72634,7 +72634,7 @@ async function resolveTicketTeam(client, team, signal) {
 function errText2(err) {
   return err instanceof Error ? err.message : String(err);
 }
-async function planAttachments(paths, stat3 = async (p) => {
+async function planAttachments(paths, stat4 = async (p) => {
   const st = await fs34.stat(p);
   return { size: st.size, isFile: st.isFile() };
 }) {
@@ -72657,7 +72657,7 @@ async function planAttachments(paths, stat3 = async (p) => {
     }
     let info;
     try {
-      info = await stat3(filePath);
+      info = await stat4(filePath);
     } catch (err) {
       throw new Error(`--attach ${filePath}: ${errText2(err)}`);
     }
@@ -73045,8 +73045,8 @@ async function readAppPassword(src, stdinReader) {
   let raw2;
   if (fromFile) {
     try {
-      const stat3 = await fs34.stat(src.file);
-      if (!stat3.isFile()) {
+      const stat4 = await fs34.stat(src.file);
+      if (!stat4.isFile()) {
         throw new Error(
           "--password-file must be a regular file: a device or pipe can yield without end, and its reported size means nothing"
         );
@@ -74132,7 +74132,7 @@ function registerAppSpaceCommand(root) {
 
 // src/commands/agents.ts
 import { mkdir as mkdir5, writeFile as writeFile8 } from "fs/promises";
-import { join as join17 } from "path";
+import { join as join18 } from "path";
 
 // src/api/aiService.ts
 import { z as z3 } from "zod";
@@ -74500,13 +74500,26 @@ function renderScopeRegistry(registry) {
   const lines = [
     `Actions: ${[...actions, "*"].join(" | ")} (* = every action). Resource * = every resource.`
   ];
+  const unenforced = [];
   for (const product of Array.isArray(registry?.products) ? registry.products : []) {
-    lines.push("", product.name ?? product.key ?? "?");
+    const productName = product.name ?? product.key ?? "?";
+    const accepted = [];
     for (const resource of product.resources ?? []) {
-      const note = resource.enforced === false ? " (not enforced yet)" : "";
       const description = resource.description ? ` \u2014 ${resource.description}` : "";
-      lines.push(`  ${resource.name ?? "?"}${note}${description}`);
+      if (resource.enforced === false) {
+        unenforced.push(`  ${resource.name ?? "?"} (${productName})${description}`);
+      } else {
+        accepted.push(`  ${resource.name ?? "?"}${description}`);
+      }
     }
+    if (accepted.length > 0) lines.push("", productName, ...accepted);
+  }
+  if (unenforced.length > 0) {
+    lines.push(
+      "",
+      "Not enforced yet \u2014 listed for reference; --cli-scopes does not accept these until their product checks them:",
+      ...unenforced
+    );
   }
   return lines.join("\n");
 }
@@ -74526,10 +74539,13 @@ function cliScopesWriteLine(requested, after) {
   if (requested === null && after !== null) {
     return `WARNING: CLI scopes reset was sent but a ceiling is still stored: ${after.join(", ")}.`;
   }
+  if (requested !== null && requested.length > 0 && after === null) {
+    return `WARNING: CLI scopes ${requested.join(", ")} were sent but nothing is stored: the requested ceiling did not land, and the read-only default (${DEFAULT_CLI_SCOPES.join(", ")}) applies.`;
+  }
   return `CLI scopes: ${cliScopesLabel(after)}. Applies from the agent's next session; running sessions keep the ceiling they started with.`;
 }
 var SCOPE_ERROR_HINTS = {
-  INVALID_CLI_SCOPES: "run `agents scope-registry` for the resources and actions this environment knows.",
+  INVALID_CLI_SCOPES: 'run `agents scope-registry` for the resources and actions this environment knows; resources it marks "not enforced yet" are not accepted.',
   CLI_SCOPES_WITHOUT_CLI: "CLI scopes only apply to a CLI-exposed agent. Add `--expose-cli true` (update) or `--expose-cli` (create), or use --reset-cli-scopes to clear them."
 };
 function describeCliScopesError(err) {
@@ -75080,10 +75096,11 @@ function renderToolsProposalText(proposal, resolved) {
 
 // src/commands/agents_skills.ts
 import { mkdir as mkdir4, writeFile as writeFile7 } from "fs/promises";
-import { dirname as dirname9, join as join16 } from "path";
+import { dirname as dirname9, join as join17 } from "path";
 
 // src/commands/_agentSkillBundle.ts
-import { extname as extname5 } from "path";
+import { readdir as readdir4, stat as stat3 } from "fs/promises";
+import { extname as extname5, join as join16 } from "path";
 function inferContentType(filename) {
   switch (extname5(filename).toLowerCase()) {
     case ".md":
@@ -75121,7 +75138,60 @@ function inferContentType(filename) {
       return void 0;
   }
 }
-async function dirToFiles(baseDir) {
+var SKILL_BUNDLE_LIMITS = {
+  maxFileBytes: 20 * 1024 * 1024,
+  maxTotalBytes: 14 * 1024 * 1024
+};
+var SKILL_ENTRY_OVERHEAD_BYTES = 128;
+async function statSkillFiles(skillRoot) {
+  const out = [];
+  async function walk(dir, prefix) {
+    for (const e of await readdir4(dir, { withFileTypes: true })) {
+      if (isIgnoredSkillEntry(e.name)) continue;
+      const childAbs = join16(dir, e.name);
+      const childRel = prefix === "" ? e.name : `${prefix}/${e.name}`;
+      if (e.isDirectory()) {
+        await walk(childAbs, childRel);
+      } else if (e.isFile()) {
+        out.push({ relPath: childRel, size: (await stat3(childAbs)).size });
+      }
+    }
+  }
+  await walk(skillRoot, "");
+  out.sort((a, b) => a.relPath.localeCompare(b.relPath));
+  return out;
+}
+function assertUploadableSizes(files, limits) {
+  const oversized = files.find((f) => f.size > limits.maxFileBytes);
+  if (oversized !== void 0) {
+    throw new Error(
+      `skill file "${oversized.relPath}" is ${oversized.size} bytes; ai-service accepts at most ${limits.maxFileBytes} bytes per file`
+    );
+  }
+  const empty = files.filter((f) => f.size === 0).map((f) => `"${f.relPath}"`);
+  if (empty.length === 1) {
+    throw new Error(
+      `skill file ${empty[0]} is empty; ai-service rejects empty files \u2014 add content or remove it`
+    );
+  }
+  if (empty.length > 1) {
+    throw new Error(
+      `skill files ${empty.join(", ")} are empty; ai-service rejects empty files \u2014 add content or remove them`
+    );
+  }
+  const total = files.reduce(
+    (sum, f) => sum + f.size + Buffer.byteLength(f.relPath) + SKILL_ENTRY_OVERHEAD_BYTES,
+    0
+  );
+  if (total > limits.maxTotalBytes) {
+    const largest = files.reduce((a, b) => b.size > a.size ? b : a);
+    throw new Error(
+      `skill bundle is ${total} bytes counting its paths (${SKILL_ENTRY_OVERHEAD_BYTES} bytes per file on top); ai-service accepts at most ${limits.maxTotalBytes} bytes in one upload (${files.length} files; largest: "${largest.relPath}", ${largest.size} bytes)`
+    );
+  }
+}
+async function dirToFiles(baseDir, limits = SKILL_BUNDLE_LIMITS) {
+  assertUploadableSizes(await statSkillFiles(baseDir), limits);
   return (await readSkillFiles(baseDir)).map(({ relPath, bytes }) => {
     const contentType = inferContentType(relPath);
     return {
@@ -75289,7 +75359,7 @@ async function runSkillsPull(cfg) {
   const folder = bundleFolder(files);
   const targets = files.map((file) => ({
     file,
-    outPath: join16(baseDir, ...folder, ...relSegments(file.path))
+    outPath: join17(baseDir, ...folder, ...relSegments(file.path))
   }));
   await assertNoOverwrite(
     targets.map((t) => t.outPath),
@@ -75537,6 +75607,11 @@ async function runAgentsSystemEntities(cfg) {
   const ids = (list28) => (list28 ?? []).length > 0 ? (list28 ?? []).join(", ") : "(none)";
   cfg.out.write(`agents:       ${ids(res.agentIds)}
 `);
+  const protectedIds = res.protectedAgentIds;
+  cfg.out.write(
+    Array.isArray(protectedIds) ? `protected:    ${ids(protectedIds)}  (no archive or reach change; content stays editable)
+` : "protected:    (not reported by this ai-service)\n"
+  );
   cfg.out.write(`environments: ${ids(res.environmentIds)}
 `);
   cfg.out.write(`skills:       ${ids(res.skillIds)}
@@ -75773,6 +75848,11 @@ async function runAgentsRefresh(cfg) {
   const apis = toCatalogEntries(catalog.apis ?? []);
   const name = agent.name ?? agentId;
   const v = versionLabel2(agent.version);
+  if (!Array.isArray(agent.tools)) {
+    throw new Error(
+      `getAgent returned no tools list for ${agentId} ${v}; refusing to plan or write a tools change`
+    );
+  }
   if (proposal === void 0) {
     const plan = computeRefreshPlan(agent.tools, apis, topN);
     if (cfg.asJson) {
@@ -75886,15 +75966,15 @@ async function runAgentsPull(cfg) {
     throw new Error(`${agentId}: the response carried no system prompt, tools or skills to pull`);
   }
   await assertNoOverwrite(
-    files.map((f) => join17(baseDir, f.name)),
+    files.map((f) => join18(baseDir, f.name)),
     cfg.force === true
   );
   await mkdir5(baseDir, { recursive: true });
-  for (const f of files) await writeFile8(join17(baseDir, f.name), f.content);
+  for (const f of files) await writeFile8(join18(baseDir, f.name), f.content);
   cfg.out.write(`Wrote ${files.map((f) => f.name).join(", ")} to ${baseDir}/
 `);
   const base = typeof agent.version === "number" ? ` --version-number ${agent.version}` : "";
-  const fileFlags = files.map((f) => `${f.flag} ${shellArg(join17(baseDir, f.name))}`).join(" ");
+  const fileFlags = files.map((f) => `${f.flag} ${shellArg(join18(baseDir, f.name))}`).join(" ");
   cfg.out.write(
     `Edit, then: dr agents update --id ${shellArg(agentId)}${base} ${fileFlags} ${serverFlagText(cfg.client)}
 `
@@ -76486,7 +76566,7 @@ function registerAgentsCommand(root) {
   });
   withTarget(cliScopes);
   const scopeRegistry = agents.command("scope-registry").description(
-    "List the resources and actions a CLI scope may name in this environment \u2014 what --cli-scopes accepts."
+    'List the resources and actions a CLI scope may name in this environment. Resources listed under "Not enforced yet" are not accepted by --cli-scopes.'
   ).option("--json", JSON_HELP).action(async (opts) => {
     const setup = await setupCall(opts.server, opts.account);
     try {
@@ -76891,7 +76971,7 @@ function commandPath(actionCommand) {
 
 // src/telemetry/config.ts
 import { homedir as homedir7 } from "os";
-import { join as join19 } from "path";
+import { join as join20 } from "path";
 import { readFile as readFile9 } from "fs/promises";
 var TELEMETRY_ENV = "DR_CLI_TELEMETRY";
 var DISABLED_VALUES = /* @__PURE__ */ new Set(["0", "false", "off", "no"]);
@@ -76925,7 +77005,7 @@ function parseCollectorConfig(raw2) {
   return { endpoint, headerName, headerValue };
 }
 function remoteSettingsPath() {
-  return join19(homedir7(), ".claude", "remote-settings.json");
+  return join20(homedir7(), ".claude", "remote-settings.json");
 }
 async function readCollectorConfig(path13 = remoteSettingsPath()) {
   let raw2;

package/dist/scopes-map.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "cliVersion": "1.6.152",
+  "cliVersion": "1.6.153",
   "_contract": "Resolve a command path through `aliases` (canonical prefix + alias segment -> canonical path) before any lookup. A path listed in `pendingCommands`, or whose first segment is a key of `pending`, is UNDECIDED, not unrestricted: fail closed or skip it, and never read a path's absence from `commands` as 'no requirement'. An entry carrying `denied` is UNAVAILABLE to any AGENT-SCOPED credential — one whose `scopes` claim carries at least one `resource:action` entry; a claim that is absent, empty, capability-only or wholly unparseable is UNRESTRICTED, and this mark does not apply to it — whatever else that entry says: it is not a ceiling and it is not always-available, its `denied.reason` says why and `denied.until` names the ticket that lifts it, and the absence of `requires` on it must NEVER be read as 'no requirement'. Only an entry in `commands` with an empty `requires` means always-available.",
   "commands": {
     "login": {

package/dist/skills/schedule-drip-task/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: schedule-drip-task
-description: Use when a customer needs files or data pushed OUT of Datarails on a schedule through DRIP (the connectors platform) - an SFTP export, "send this CSV to the customer's SFTP every hour", "push the file to their server", "schedule an export", "scheduled task", "dr connectors tasks", "sftp_export", "lib/sftp_export", or when operating an existing schedule - "is the export running", "why did the export fail", "the task is paused", "run the export now", "pause the export", "task runs", "consecutive failures", "paused (failures)", "paused (schedule)", "no active version", "newest source file is older than max_age_seconds", "the target must not be a customer org-*-sftp container", a 403 "scheduled tasks need a support user or an org admin". Not for pulling data INTO Datarails (drip-implement-connector) or for polled SFTP ingestion (dr connectors poll).
+description: Use when a customer needs files or data pushed OUT of Datarails on a schedule through DRIP (the connectors platform) - an SFTP export, "send this CSV to the customer's SFTP every hour", "push the file to their server", "schedule an export", "scheduled task", "dr connectors tasks", "sftp_export", "lib/sftp_export", or when operating an existing schedule - "is the export running", "why did the export fail", "the task is paused", "run the export now", "pause the export", "task runs", "consecutive failures", "paused (failures)", "paused (schedule)", "no active version", "newest source file is older than max_age_seconds", "the target must not be a customer org-*-sftp container", a 403 "scheduled tasks need a support user or an org admin", or when writing a new task type - "write a scheduled task", "new DRIP task", "process() TaskResult", "run hook", "task state". Not for pulling data INTO Datarails (drip-implement-connector) or for polled SFTP ingestion (dr connectors poll).
 ---
 
 # Schedule a DRIP task
@@ -10,6 +10,9 @@ datasources, and keeps a run history. The control plane only schedules; the runn
 artifact's `process()`. The first task type is **SFTP Export** (`lib/sftp_export`): copy files from
 our hosted SFTP to a customer's SFTP under a name the customer wants.
 
+To write a task type other than SFTP Export (the `process()` hook, `TaskResult`, state, retries),
+see [reference/writing-a-task.md](reference/writing-a-task.md).
+
 Commands: `dr connectors tasks create | list | get | update | delete | run | pause | resume | runs`.
 Every one takes `--server`, `--account` and `--json`; a `<task>` is its id or its name.
 

package/dist/skills/schedule-drip-task/reference/sftp-export.md

@@ -16,10 +16,11 @@ datasources (the control plane refuses secret-looking keys with a 422).
 | `settle_seconds` | no | 120 | Skip files modified more recently (the producer may still be writing). 0 to 7 days |
 | `max_age_seconds` | no | none | `newest` only: fail the run if the newest file is older than this before the scheduled time, or if no file matches (producer late or stopped) |
 | `max_files_per_run` | no | 50 | `all_new`: at most this many files per run (1 to 1000); the rest go next run |
+| `upload` | no | `atomic` | `atomic`: write a `.part`, then rename it, so no reader sees a half-written file. `direct`: write the final name itself, for a target folder that takes files away as they arrive (the `.part` would be gone before the rename). `newest` only |
 
 Behaviour worth knowing:
 
-- Upload is atomic: a random `.<name>.<hex>.part` is written, then renamed. The customer's login must
+- Upload is atomic by default: a random `.<name>.<hex>.part` is written, then renamed. A run that fails with "a file vanished while publishing the upload" means the target takes files as they arrive: set `"upload": "direct"`. The customer's login must
   be allowed to create and rename files in `target_dir`. Stale parts of ours older than 2 h are swept.
 - The source is never written, moved or deleted. Cleaning it is the producer's job; with `all_new`,
   a folder that keeps every sent file eventually fails the run with "archive or delete them".

package/dist/skills/schedule-drip-task/reference/writing-a-task.md

@@ -0,0 +1,92 @@
+# Writing a new task type
+
+A scheduled task is an ordinary DRIP artifact in dr-connectors (a connection plus a dataquery,
+published and made active like any connector, see `drip-implement-connector`), whose dataquery
+implements `process()`. The control plane only schedules it. On each run it sends the flavor's
+runner a job with `hook: "run"`, and the runner calls `connect()`, then `process()`, in one job.
+The full contract is in dr-connectors-runner `docs/connector-kit.md`, "Scheduled tasks: the `run`
+hook". `lib/sftp_export` in dr-connectors is the reference implementation.
+
+## The code
+
+```python
+# lib/<task>/dataqueries/<name>.py
+from dr_integrations_sdk import DataQuery, PermanentError, SyncRequest, TaskResult, kit
+
+OBJECT_TYPES = ("<objectType>",)
+
+
+class MyTask(DataQuery):
+    async def process(self, session, req: SyncRequest) -> TaskResult:
+        config = req.config                                   # the task's --config, validated here
+        state = (req.metadata or {}).get("state") or {}       # what the last ok run returned
+        scheduled_for = req.metadata["scheduled_for"]         # ISO UTC time of the slot this run is for
+        other = await kit.auth.get_credentials_for(req, "source")  # a non-primary datasource, by role
+        sent = await do_the_work(session, other, config, state)
+        return TaskResult(state={"sent": sent}, summary={"sent": len(sent)})
+
+
+def get_query_class(object_type: str):
+    if object_type == "<objectType>":
+        return MyTask
+    raise PermanentError(f"unknown objectType {object_type!r}")
+```
+
+| Piece | Rule |
+|---|---|
+| `connect()` | Gets the **primary** datasource's credentials as for any connector. Log in here, so a wrong password or host key fails before any work |
+| `req.config` | The task's `--config` JSON. Must carry `objectType` (it picks the dataquery class). Validate it before any login. Never put credentials in it: the control plane refuses secret-looking keys with a 422 |
+| Other datasources | `kit.auth.get_credentials_for(req, "<role>")`, one per `--datasource <role>=<id>`. An unbound role is a `PermanentError` naming it |
+| `req.metadata` | `state`, `scheduled_for`, `run_id`, `attempt` (1, or 2 on the retry), `trigger` (`schedule` or `manual`) |
+| Imports | stdlib, `dr_integrations_sdk`, `lib` and the flavor's allowlist only (dr-connector-images). Set `RUNTIME_FLAVOR` in the connection |
+| Logs | `kit.logging.get_logger("<task>")`. They reach Groundcover under the runner flavor's workload |
+
+## The result
+
+`TaskResult(state=…, summary=…, verdict=…)`. Every field is optional.
+
+- **`state`**: the task's own bookkeeping (ids, cursors, names already sent), never the data
+  processed. It must be a JSON object or `None`, at most 64 KiB. The control plane keeps it only
+  from an `ok` run; after a failure the next run gets the last good state.
+- **`summary`**: what the run did, shown by `dr connectors tasks runs`.
+- **`verdict`**: `ok` (default), `retry` (the run is sent once more after 60 s) or `block` (the run
+  fails).
+- The whole result must be JSON (no `datetime`, `set`, `Decimal`, NaN) and at most 128 KiB.
+  Anything else fails the run as a connector error.
+
+## Errors
+
+| Raised | Run |
+|---|---|
+| `PermanentError`, `AuthError` | Fails, no retry. Use for bad config, refused credentials, missing folders |
+| `TransientError`, `httpx` 429/5xx, `httpx.TransportError` | Retried once after 60 s, then fails |
+| Anything else | Fails as a connector error |
+
+- After 5 failed runs in a row the task pauses itself (`paused (failures)`).
+- The control plane stores only the first few hundred characters of a run's error. Keep the message
+  short. Log anything longer, such as a key or a listing, and read it in Groundcover.
+- Never put a secret in an error or a log line.
+
+## Make it safe to run twice
+
+A retry runs `process()` again, a manual run can land next to a scheduled one, and a run that dies
+leaves no state. So:
+
+- Record what was done in `state`, and skip it next time.
+- Write the output so that a half-finished run leaves nothing a reader would take as done. For
+  example, upload to a temporary name and rename it.
+- Use `scheduled_for`, not the clock, for anything named after the run's time: a retry then makes
+  the same name.
+
+## Ship it
+
+1. **Shared code goes in `lib/<task>/`**, with tests. A thin per-org artifact re-exports it. The
+   dataquery must set its own `CONNECTION` (the thin connection file's name), as in
+   [SKILL.md](../SKILL.md) step 3.
+2. **Merge to dr-connectors.** CI publishes the artifact to JFrog.
+3. **Register and activate it on the region:** `dr connectors publish <dataquery file>`, then
+   `dr connectors promote <artifact> --artifact-version v<N>`, as the customer's support user.
+4. **Schedule it:** `dr connectors tasks create` (see [SKILL.md](../SKILL.md)), then `tasks run` once
+   and check `tasks runs`.
+5. **Test on dev-1 first.** The heartbeat artifact in dr-connectors
+   (`dev-1/69_(test-connectors.com)/heartbeat/`) is a minimal task that carries a counter in `state`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datarails-ai/dr-cli",
-  "version": "1.6.152",
+  "version": "1.6.153",
   "description": "Datarails CLI",
   "type": "module",
   "engines": {