@terminus-ai/cli 0.0.1

package/bin/toolchain.mjs

@@ -0,0 +1,125 @@
+/**
+ * Toolchain resolution for local agent dev: find the `terminus-agentd`
+ * binary `terminus dev` runs on.
+ *
+ * Resolution order: `--agentd <path>` / `$TERMINUS_AGENTD` → a
+ * `terminus-agentd` already on PATH → the `@terminus-ai/agentd-<platform>`
+ * package npm installed alongside this CLI.
+ *
+ * The npm package is the lane that works for everyone: `os`/`cpu` fields
+ * mean npm installs exactly the one matching build, so the binary is simply
+ * on disk before the dev ever starts.
+ */
+
+import { constants as fsConstants } from "node:fs";
+import { access, chmod, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { CliError } from "./client.mjs";
+
+/**
+ * Per-platform binary packages, declared as optionalDependencies so npm
+ * installs the single one this machine can run. Built and published from
+ * terminus-agent's `release-binaries` workflow; the table there
+ * (`npm/stage.mjs`) is the other half of this one and must agree with it.
+ */
+export const AGENTD_PACKAGES = {
+  "darwin-arm64": "@terminus-ai/agentd-darwin-arm64",
+  "darwin-x64": "@terminus-ai/agentd-darwin-x64",
+  "linux-x64": "@terminus-ai/agentd-linux-x64",
+  "linux-arm64": "@terminus-ai/agentd-linux-arm64",
+};
+
+export function agentdPackage(platform = process.platform, arch = process.arch) {
+  return AGENTD_PACKAGES[`${platform}-${arch}`] ?? null;
+}
+
+/** The Rust target each package's binary is built for — terminus-agent's
+ * release matrix, which the package table above follows. */
+export function agentdTriple(platform = process.platform, arch = process.arch) {
+  const triples = {
+    "darwin-arm64": "aarch64-apple-darwin",
+    "darwin-x64": "x86_64-apple-darwin",
+    "linux-x64": "x86_64-unknown-linux-musl",
+    "linux-arm64": "aarch64-unknown-linux-musl",
+  };
+  return triples[`${platform}-${arch}`] ?? null;
+}
+
+async function executable(candidate) {
+  try {
+    await access(candidate, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function onPath(name) {
+  const separator = process.platform === "win32" ? ";" : ":";
+  for (const dir of (process.env.PATH ?? "").split(separator)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, name);
+    if (await executable(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * The binary inside the installed per-platform package, if npm put one
+ * there. Resolves `package.json` rather than the binary itself so that a
+ * package that is present but unstaged — the `npm link` case during local
+ * development — is distinguishable from one that was never installed;
+ * `resolveAgentd` turns that into an error that says what to run.
+ */
+async function packagedAgentd() {
+  const name = agentdPackage();
+  if (!name) return { name: null, dir: null, binary: null };
+  let dir = null;
+  try {
+    dir = path.dirname(createRequire(import.meta.url).resolve(`${name}/package.json`));
+  } catch {
+    return { name, dir: null, binary: null };
+  }
+  const binary = path.join(dir, "bin", "terminus-agentd");
+  if (await executable(binary)) return { name, dir, binary };
+  // Present but not executable: a packaging step that dropped the mode bit,
+  // or a staged copy written without one. Cheap to repair, confusing to hit.
+  const exists = await stat(binary).then(() => true, () => false);
+  if (exists && (await chmod(binary, 0o755).then(() => true, () => false))) {
+    if (await executable(binary)) return { name, dir, binary };
+  }
+  return { name, dir, binary: null };
+}
+
+/** Resolve the terminus-agentd binary the dev should spawn. */
+export async function resolveAgentd(flags = {}) {
+  const explicit = flags.agentd ?? process.env.TERMINUS_AGENTD;
+  if (explicit) {
+    if (await executable(explicit)) return explicit;
+    throw new CliError(`--agentd/${"$"}TERMINUS_AGENTD points at ${explicit}, which is not executable`);
+  }
+  // PATH stays ahead of the package: it is how someone building agentd
+  // itself runs their own build.
+  const found = await onPath("terminus-agentd");
+  if (found) return found;
+  const packaged = await packagedAgentd();
+  if (packaged.binary) return packaged.binary;
+  if (packaged.dir) {
+    // Linked or vendored, but carrying no binary — only reachable during
+    // local development, where the fix is one command.
+    throw new CliError(
+      `${packaged.name} is installed at ${packaged.dir} but holds no binary — `
+      + "stage one with `node npm/stage.mjs --from target/release/terminus-agentd` "
+      + "in the terminus-agent repo, or point $TERMINUS_AGENTD at a build",
+    );
+  }
+  throw new CliError(
+    "the local dev needs the terminus-agentd binary, and "
+    + `${packaged.name ? `${packaged.name} is not installed` : `there is no build for ${process.platform}/${process.arch}`} — `
+    + "install terminus-agentd on your PATH (cargo build --release -p "
+    + "terminus-agentd in the terminus-agent repo), or point $TERMINUS_AGENTD "
+    + "/ --agentd at one",
+  );
+}

package/bin/vendor/app-runtime-v1/app-host.json

@@ -0,0 +1,124 @@
+{
+  "schema_version": 1,
+  "contract": "terminus.app-runtime.app-host",
+  "runtime_api_version": 1,
+  "prefix": "/_terminus",
+  "routing": [
+    "worker_handled paths are answered by the app host itself.",
+    "bootstrap answers only GET and HEAD (405 method_not_allowed otherwise) and is rewritten to its upstream.",
+    "Without a session cookie, an app open to guests answers guest.bootstrap itself, forwards guest.doors (a capability asset only for a capability its current release declares) and refuses every other door with guest.refusal. A top-level page navigation from a browser without guest.marker_cookie goes once to the platform's authorization page first: a person signed in there comes back with a session, anyone else comes back through /_terminus/guest, which sets the marker. Any other app answers 401 unauthorized to a fetch and redirects a navigation to the platform's authorization page.",
+    "The suffix after the prefix is at most 1024 characters; each percent-decoded segment is non-empty, not . or .., and free of / \\ and control characters; the first segment must be in allowed_segments. Anything else is 404 not_found.",
+    "A request other than GET, HEAD or OPTIONS must carry an Origin (or else a Referer) equal to the app's own origin, or it is 403 forbidden.",
+    "rewrites apply by path prefix (their request_headers are set on the upstream call); every other door maps to default_upstream_prefix plus the suffix. The query string is preserved, the method and body pass through, the session rides as Authorization: Bearer, and redirects are passed through rather than followed."
+  ],
+  "worker_handled": ["icon", "logout", "callback", "open", "signin", "guest"],
+  "bootstrap": {
+    "path": "/bootstrap",
+    "methods": ["GET", "HEAD"],
+    "upstream": "/v1/app-runtime/session/current"
+  },
+  "allowed_segments": [
+    "capabilities",
+    "collaboration",
+    "collect",
+    "collections",
+    "connectors",
+    "data",
+    "egress",
+    "events",
+    "jobs",
+    "lifecycle",
+    "logs",
+    "net",
+    "notifications",
+    "schedules",
+    "server",
+    "service-jobs",
+    "services",
+    "spaces",
+    "storage",
+    "transactions",
+    "users"
+  ],
+  "rewrites": [
+    {
+      "prefix": "/capabilities",
+      "upstream_prefix": "/v1/capabilities",
+      "request_headers": { "x-terminus-artifact-context": "app" }
+    }
+  ],
+  "default_upstream_prefix": "/v1/app-runtime",
+  "request_headers": ["accept", "content-type", "idempotency-key", "if-none-match"],
+  "response_headers": [
+    "cache-control",
+    "content-disposition",
+    "content-language",
+    "content-type",
+    "etag",
+    "last-modified",
+    "location",
+    "vary",
+    "retry-after",
+    "x-terminus-data-version",
+    "x-terminus-schema-id",
+    "x-terminus-schema-version",
+    "x-terminus-observation-id",
+    "x-terminus-provenance",
+    "x-terminus-url"
+  ],
+  "added_response_headers": { "x-content-type-options": "nosniff" },
+  "response_header_overrides": [
+    { "prefix": "/service-jobs/", "headers": { "cache-control": "private, no-store" } }
+  ],
+  "asset_identity": "/v1/app-runtime/session/identity",
+  "session_cookie": "__Host-terminus_app",
+  "guest": {
+    "bootstrap": {
+      "platform_api_version": 1,
+      "guest": true,
+      "app": {
+        "id": "{resolve.app_id}",
+        "slug": "{resolve.slug}",
+        "name": "{resolve.name}",
+        "icon_url": "/_terminus/icon"
+      },
+      "installation": null,
+      "user": null,
+      "data": { "grants": [], "resource_grants": [] }
+    },
+    "doors": ["capabilities.asset"],
+    "marker_cookie": "__Host-terminus_guest",
+    "marker_max_age_seconds": 43200,
+    "refusal": { "status": 401, "code": "unauthorized" }
+  },
+  "errors": [
+    {
+      "when": "an unknown or unsafe /_terminus path, or a first segment outside allowed_segments",
+      "status": 404,
+      "code": "not_found"
+    },
+    {
+      "when": "bootstrap with a method other than GET or HEAD, or a worker-handled door with a method other than its own",
+      "status": 405,
+      "code": "method_not_allowed"
+    },
+    { "when": "a cross-origin mutation", "status": 403, "code": "forbidden" },
+    {
+      "when": "a door without a session (a signed-out fetch, or a guest calling a door outside guest.doors)",
+      "status": 401,
+      "code": "unauthorized"
+    },
+    { "when": "the backend cannot be reached", "status": 503, "code": "service_unavailable" }
+  ],
+  "html_pages": "Top-level navigations (an unknown app host, an unpublished app, a failed sign-in callback) render an HTML error page; every /_terminus answer that is not a navigation is the JSON error envelope.",
+  "worker_upstream": [
+    "GET /v1/app-runtime/resolve",
+    "GET /v1/app-runtime/icon",
+    "POST /v1/app-runtime/session",
+    "GET /v1/app-runtime/session/identity",
+    "DELETE /v1/app-runtime/session/current",
+    "GET /v1/app-runtime/assets/{*path}",
+    "GET /v1/app-runtime/guest-assets/{release_id}/{*path}",
+    "GET /v1/capabilities/{id}/{major}/assets/{*path}"
+  ]
+}

package/bin/vendor/app-runtime-v1/capability-calls.json

@@ -0,0 +1,412 @@
+{
+  "schema_version": 1,
+  "contract": "terminus.sdk.capability-calls",
+  "sources": {
+    "extensions": [".cjs", ".cts", ".html", ".js", ".jsx", ".mjs", ".mts", ".svelte", ".ts", ".tsx", ".vue"],
+    "skip_directories": ["__tests__", "fixtures", "test", "tests"],
+    "skip_files": "\\.(?:spec|test)\\.[^.]+$",
+    "comments": "Comments are masked before matching; string literals and offsets are preserved.",
+    "binding": "A call is <binding>.<method>( with an optional TypeScript type argument, where <binding> is the call's surface or a local alias from import { <surface> as <alias> } from \"@terminus-ai/app-sdk\"; a longer member path ending in the binding matches too (TerminusSDK.net.fetch(...)).",
+    "literals": "A literal argument is a single- or double-quoted string (never a template literal) or an integer literal at its listed index. A call to a compiled method whose literal arguments are not literal fails the build.",
+    "placeholders": "{name} in a grant is replaced by the literal argument of that name; integer arguments substitute as numbers."
+  },
+  "calls": [
+    {
+      "call": "horizontal.require",
+      "literal_args": [
+        { "index": 0, "name": "id", "kind": "string", "pattern": "^[a-z](?:[a-z0-9-]{0,62}[a-z0-9])?$" },
+        { "index": 1, "name": "version", "kind": "integer", "pattern": "^[1-9][0-9]*$" }
+      ],
+      "grant": {
+        "capability": "horizontal",
+        "merge_by": "id",
+        "entry": { "id": "{id}", "version": "{version}", "operations": [] }
+      },
+      "checks": [
+        "{id} v{version} names a capability in the horizontal registry",
+        "a package uses one version of {id}"
+      ]
+    },
+    {
+      "call": "horizontal.loadModule",
+      "literal_args": [
+        { "index": 0, "name": "id", "kind": "string", "pattern": "^[a-z](?:[a-z0-9-]{0,62}[a-z0-9])?$" },
+        { "index": 1, "name": "version", "kind": "integer", "pattern": "^[1-9][0-9]*$" }
+      ],
+      "grant": {
+        "capability": "horizontal",
+        "merge_by": "id",
+        "entry": { "id": "{id}", "version": "{version}", "operations": [] }
+      },
+      "checks": [
+        "{id} v{version} names a capability in the horizontal registry",
+        "a package uses one version of {id}"
+      ]
+    },
+    {
+      "call": "horizontal.loadStyle",
+      "literal_args": [
+        { "index": 0, "name": "id", "kind": "string", "pattern": "^[a-z](?:[a-z0-9-]{0,62}[a-z0-9])?$" },
+        { "index": 1, "name": "version", "kind": "integer", "pattern": "^[1-9][0-9]*$" }
+      ],
+      "grant": {
+        "capability": "horizontal",
+        "merge_by": "id",
+        "entry": { "id": "{id}", "version": "{version}", "operations": [] }
+      },
+      "checks": [
+        "{id} v{version} names a capability in the horizontal registry",
+        "a package uses one version of {id}"
+      ]
+    },
+    {
+      "call": "horizontal.describe",
+      "literal_args": [
+        { "index": 0, "name": "id", "kind": "string", "pattern": "^[a-z](?:[a-z0-9-]{0,62}[a-z0-9])?$" },
+        { "index": 1, "name": "version", "kind": "integer", "pattern": "^[1-9][0-9]*$" }
+      ],
+      "grant": {
+        "capability": "horizontal",
+        "merge_by": "id",
+        "entry": { "id": "{id}", "version": "{version}", "operations": [] }
+      },
+      "checks": [
+        "{id} v{version} names a capability in the horizontal registry",
+        "a package uses one version of {id}"
+      ]
+    },
+    {
+      "call": "horizontal.assetUrl",
+      "literal_args": [
+        { "index": 0, "name": "id", "kind": "string", "pattern": "^[a-z](?:[a-z0-9-]{0,62}[a-z0-9])?$" },
+        { "index": 1, "name": "version", "kind": "integer", "pattern": "^[1-9][0-9]*$" }
+      ],
+      "grant": {
+        "capability": "horizontal",
+        "merge_by": "id",
+        "entry": { "id": "{id}", "version": "{version}", "operations": [] }
+      },
+      "checks": [
+        "{id} v{version} names a capability in the horizontal registry",
+        "a package uses one version of {id}"
+      ]
+    },
+    {
+      "call": "horizontal.moduleUrl",
+      "literal_args": [
+        { "index": 0, "name": "id", "kind": "string", "pattern": "^[a-z](?:[a-z0-9-]{0,62}[a-z0-9])?$" },
+        { "index": 1, "name": "version", "kind": "integer", "pattern": "^[1-9][0-9]*$" }
+      ],
+      "grant": {
+        "capability": "horizontal",
+        "merge_by": "id",
+        "entry": { "id": "{id}", "version": "{version}", "operations": [] }
+      },
+      "checks": [
+        "{id} v{version} names a capability in the horizontal registry",
+        "a package uses one version of {id}"
+      ]
+    },
+    {
+      "call": "horizontal.invoke",
+      "literal_args": [
+        { "index": 0, "name": "id", "kind": "string", "pattern": "^[a-z](?:[a-z0-9-]{0,62}[a-z0-9])?$" },
+        { "index": 1, "name": "version", "kind": "integer", "pattern": "^[1-9][0-9]*$" },
+        { "index": 2, "name": "operation", "kind": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$" }
+      ],
+      "grant": {
+        "capability": "horizontal",
+        "merge_by": "id",
+        "entry": { "id": "{id}", "version": "{version}", "operations": ["{operation}"] }
+      },
+      "checks": [
+        "{id} v{version} names a capability in the horizontal registry",
+        "a package uses one version of {id}"
+      ]
+    },
+    {
+      "call": "connectors.request",
+      "literal_args": [{ "index": 0, "name": "slug", "kind": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }],
+      "grant": { "capability": "connectors", "add": "{slug}" }
+    },
+    {
+      "call": "connectors.json",
+      "literal_args": [{ "index": 0, "name": "slug", "kind": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }],
+      "grant": { "capability": "connectors", "add": "{slug}" }
+    },
+    {
+      "call": "services.invoke",
+      "literal_args": [
+        { "index": 0, "name": "address", "kind": "string", "pattern": "^@[^\\s/@]+/[a-z0-9][a-z0-9-]*$" },
+        { "index": 1, "name": "operation", "kind": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$" }
+      ],
+      "grant": {
+        "capability": "services",
+        "merge_by": "address",
+        "entry": { "address": "{address}", "operations": ["{operation}"] },
+        "also": {
+          "capability": "artifacts",
+          "entry": {
+            "address": "{address}",
+            "kind": "service",
+            "relationship": "uses",
+            "operations": ["{operation}"]
+          }
+        }
+      }
+    },
+    {
+      "call": "services.json",
+      "literal_args": [
+        { "index": 0, "name": "address", "kind": "string", "pattern": "^@[^\\s/@]+/[a-z0-9][a-z0-9-]*$" },
+        { "index": 1, "name": "operation", "kind": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$" }
+      ],
+      "grant": {
+        "capability": "services",
+        "merge_by": "address",
+        "entry": { "address": "{address}", "operations": ["{operation}"] },
+        "also": {
+          "capability": "artifacts",
+          "entry": {
+            "address": "{address}",
+            "kind": "service",
+            "relationship": "uses",
+            "operations": ["{operation}"]
+          }
+        }
+      }
+    },
+    {
+      "call": "services.search",
+      "literal_args": [
+        { "index": 0, "name": "address", "kind": "string", "pattern": "^@[^\\s/@]+/[a-z0-9][a-z0-9-]*$" }
+      ],
+      "grant": {
+        "capability": "services",
+        "merge_by": "address",
+        "entry": { "address": "{address}", "operations": ["search"] },
+        "also": {
+          "capability": "artifacts",
+          "entry": {
+            "address": "{address}",
+            "kind": "service",
+            "relationship": "uses",
+            "operations": ["search"]
+          }
+        }
+      }
+    },
+    {
+      "call": "services.fetch",
+      "literal_args": [
+        { "index": 0, "name": "address", "kind": "string", "pattern": "^@[^\\s/@]+/[a-z0-9][a-z0-9-]*$" }
+      ],
+      "grant": {
+        "capability": "services",
+        "merge_by": "address",
+        "entry": { "address": "{address}", "operations": ["fetch"] },
+        "also": {
+          "capability": "artifacts",
+          "entry": {
+            "address": "{address}",
+            "kind": "service",
+            "relationship": "uses",
+            "operations": ["fetch"]
+          }
+        }
+      }
+    },
+    {
+      "call": "services.generateImage",
+      "literal_args": [
+        { "index": 0, "name": "address", "kind": "string", "pattern": "^@[^\\s/@]+/[a-z0-9][a-z0-9-]*$" }
+      ],
+      "grant": {
+        "capability": "services",
+        "merge_by": "address",
+        "entry": { "address": "{address}", "operations": ["generate", "edit"] },
+        "also": {
+          "capability": "artifacts",
+          "entry": {
+            "address": "{address}",
+            "kind": "service",
+            "relationship": "uses",
+            "operations": ["generate", "edit"]
+          }
+        }
+      }
+    },
+    {
+      "call": "services.convertDocument",
+      "literal_args": [
+        { "index": 0, "name": "address", "kind": "string", "pattern": "^@[^\\s/@]+/[a-z0-9][a-z0-9-]*$" }
+      ],
+      "grant": {
+        "capability": "services",
+        "merge_by": "address",
+        "entry": { "address": "{address}", "operations": ["convert"] },
+        "also": {
+          "capability": "artifacts",
+          "entry": {
+            "address": "{address}",
+            "kind": "service",
+            "relationship": "uses",
+            "operations": ["convert"]
+          }
+        }
+      }
+    },
+    {
+      "call": "services.executeCode",
+      "literal_args": [
+        { "index": 0, "name": "address", "kind": "string", "pattern": "^@[^\\s/@]+/[a-z0-9][a-z0-9-]*$" }
+      ],
+      "grant": {
+        "capability": "services",
+        "merge_by": "address",
+        "entry": { "address": "{address}", "operations": ["execute"] },
+        "also": {
+          "capability": "artifacts",
+          "entry": {
+            "address": "{address}",
+            "kind": "service",
+            "relationship": "uses",
+            "operations": ["execute"]
+          }
+        }
+      }
+    },
+    {
+      "call": "services.sendEmail",
+      "literal_args": [
+        { "index": 0, "name": "address", "kind": "string", "pattern": "^@[^\\s/@]+/[a-z0-9][a-z0-9-]*$" }
+      ],
+      "grant": {
+        "capability": "services",
+        "merge_by": "address",
+        "entry": { "address": "{address}", "operations": ["send"] },
+        "also": {
+          "capability": "artifacts",
+          "entry": {
+            "address": "{address}",
+            "kind": "service",
+            "relationship": "uses",
+            "operations": ["send"]
+          }
+        }
+      }
+    },
+    {
+      "call": "egress.request",
+      "literal_args": [
+        { "index": 0, "name": "template", "kind": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }
+      ],
+      "grant": {
+        "capability": "egress",
+        "requires_declared": "terminus.json egress.templates[].name == {template}"
+      },
+      "checks": [
+        "the template is declared in terminus.json egress (its URL, headers and secrets cannot be read off a call site); capabilities.egress is the declared templates"
+      ]
+    },
+    {
+      "call": "collect.submit",
+      "literal_args": [
+        { "index": 0, "name": "channel", "kind": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$" }
+      ],
+      "grant": { "capability": "collect.channels", "key": "{channel}", "entry": { "kind": "documents" } }
+    },
+    {
+      "call": "collect.retract",
+      "literal_args": [
+        { "index": 0, "name": "channel", "kind": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$" }
+      ],
+      "grant": { "capability": "collect.channels", "key": "{channel}", "entry": { "kind": "documents" } }
+    },
+    {
+      "call": "server.call",
+      "literal_args": [{ "index": 0, "name": "op", "kind": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$" }],
+      "grant": { "capability": "server.ops", "key": "{op}", "entry": {} },
+      "checks": [
+        "only calls outside server/ count",
+        "the package has server/main.js or server/main.py, and a Node entry exports ops.{op}",
+        "at most 16 ops"
+      ]
+    },
+    {
+      "call": "net.fetch",
+      "literal_args": [],
+      "grant": { "capability": "network_proxy", "add": "public-text" }
+    },
+    {
+      "call": "net.image",
+      "literal_args": [],
+      "grant": { "capability": "network_proxy", "add": "public-image" }
+    },
+    {
+      "call": "notifications.create",
+      "literal_args": [],
+      "grant": { "capability": "shell.notifications", "set": true }
+    }
+  ],
+  "workload_steps": [
+    {
+      "action": "connector.request",
+      "params": { "connector": "string" },
+      "grant": { "capability": "connectors", "add": "{connector}" }
+    },
+    {
+      "action": "service.invoke",
+      "params": { "address": "string", "operation": "string" },
+      "grant": {
+        "capability": "services",
+        "merge_by": "address",
+        "entry": { "address": "{address}", "operations": ["{operation}"] },
+        "also": {
+          "capability": "artifacts",
+          "entry": { "address": "{address}", "kind": "service", "relationship": "uses", "operations": ["{operation}"] }
+        }
+      }
+    },
+    {
+      "action": "notification.create",
+      "params": {},
+      "grant": { "capability": "shell.notifications", "set": true }
+    },
+    {
+      "action": "server.run",
+      "params": { "op": "string" },
+      "grant": {
+        "capability": "server.ops",
+        "key": "{op}",
+        "entry": { "background_only": true, "timeout_ms": 120000 },
+        "unless": "the app also calls server.call(\"{op}\"), which keeps the interactive entry {}"
+      }
+    }
+  ],
+  "server_calls": [
+    {
+      "call": "terminus.records.get|put|delete|query|update",
+      "in": "server/ JavaScript",
+      "literal_args": [
+        { "index": 0, "name": "scope", "kind": "string", "pattern": "^(?:global|installation)$" },
+        { "index": 1, "name": "collection", "kind": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$" }
+      ],
+      "grant": {
+        "capability": "server.records",
+        "add": { "collections": "{collection}", "scopes": "{scope}" }
+      },
+      "checks": ["at most 16 record collections"]
+    }
+  ],
+  "notes": [
+    "net is a top-level SDK namespace (net.fetch, net.image); the client.net.* spelling is gone.",
+    "net.fetch and net.image take runtime URLs: the grant is the fixed SSRF-guarded broker lane, not a destination.",
+    "connectors.json is connectors.request with the answer parsed, so it compiles the same connector grant.",
+    "services.jobs.*, horizontal.list and every other SDK call compile no grant.",
+    "notifications.create compiles shell.notifications = true into the release; terminus.json never declares it.",
+    "A notification.create automation step compiles the same shell.notifications = true, so an app that notifies only from an automation declares nothing either.",
+    "shell.* names a top-level release section, not a capabilities group.",
+    "Compiled grants belong to the release, never to the author's files: clone and pull never write them back into terminus.json."
+  ]
+}