@terminus-ai/cli 0.0.1

package/bin/agent-discovery.mjs

@@ -0,0 +1,71 @@
+/**
+ * The `discovery` section of an agent's terminus.json: whether, beyond what
+ * its `tools` name, the agent may go looking in the Store during a
+ * conversation.
+ *
+ *   "discovery": {
+ *     "skills":   "store" | "pinned",
+ *     "services": "store" | "pinned",
+ *     "agents":   "store" | "pinned"
+ *   }
+ *
+ * "store"  — it may search the Store and ask the person before using
+ *            something it was not given.
+ * "pinned" — only what `tools` names, which it uses without asking.
+ *
+ * An absent kind means the platform's behaviour today, which is what the
+ * defaults below describe: pinning any skill already lets an agent search the
+ * marketplace and load any open skill; services are an exact allowlist; a
+ * published agent cannot call other agents at all (only Norbert can).
+ *
+ * The section is authored intent the platform does not read yet, so like
+ * `models` it is validated here and dropped from the wire manifest.
+ */
+
+import { CliError } from "./client.mjs";
+
+export const DISCOVERY_KINDS = ["skills", "services", "agents"];
+export const DISCOVERY_MODES = ["store", "pinned"];
+export const DISCOVERY_DEFAULTS = { skills: "store", services: "pinned", agents: "pinned" };
+
+export function readDiscovery(manifest = {}) {
+  const section = manifest.discovery && typeof manifest.discovery === "object" && !Array.isArray(manifest.discovery)
+    ? manifest.discovery
+    : {};
+  return Object.fromEntries(DISCOVERY_KINDS.map((kind) => [
+    kind,
+    DISCOVERY_MODES.includes(section[kind]) ? section[kind] : DISCOVERY_DEFAULTS[kind],
+  ]));
+}
+
+export function validateDiscovery(manifest = {}) {
+  if (!Object.hasOwn(manifest, "discovery")) return;
+  const section = manifest.discovery;
+  if (!section || typeof section !== "object" || Array.isArray(section)) {
+    throw new CliError("terminus.json discovery must be an object of skills|services|agents modes");
+  }
+  for (const [kind, mode] of Object.entries(section)) {
+    if (!DISCOVERY_KINDS.includes(kind)) {
+      throw new CliError(`terminus.json discovery has no '${kind}' (use ${DISCOVERY_KINDS.join(", ")})`);
+    }
+    if (!DISCOVERY_MODES.includes(mode)) {
+      throw new CliError(`terminus.json discovery.${kind} is "store" or "pinned"`);
+    }
+  }
+}
+
+/** Set one kind's mode, writing only what differs from the default. */
+export function writeDiscovery(manifest, kind, mode) {
+  if (!DISCOVERY_KINDS.includes(kind)) throw new CliError(`discovery has no '${kind}'`);
+  if (!DISCOVERY_MODES.includes(mode)) throw new CliError(`discovery.${kind} is "store" or "pinned"`);
+  const current = readDiscovery(manifest);
+  current[kind] = mode;
+  const section = Object.fromEntries(
+    DISCOVERY_KINDS
+      .filter((entry) => current[entry] !== DISCOVERY_DEFAULTS[entry])
+      .map((entry) => [entry, current[entry]]),
+  );
+  if (Object.keys(section).length) manifest.discovery = section;
+  else delete manifest.discovery;
+  return manifest;
+}

package/bin/agent-icon.mjs

@@ -0,0 +1,77 @@
+/**
+ * An agent's mark.
+ *
+ * The platform already owns this: `apps.icon_key` is artifact-level and never
+ * release-pinned, so a publisher refreshing their mark does not republish, and
+ * production falls back to the house robot for any agent that has none (see
+ * ArtifactIcon's `kind` branch). The CLI's job is only to show the same thing
+ * `terminus dev` will show in production, and to give an unpublished package a
+ * way to carry a mark until it has a remote to hold one.
+ *
+ * Hence two — and only two — places an icon can live:
+ *
+ *   remote  the linked artifact's own icon, read through the maintainer door.
+ *           Authoritative once a package is linked: Studio and the dev are
+ *           looking at one object, so an icon changed in either shows in both.
+ *   staged  `icon.png` (or .webp/.jpg) beside terminus.json. This exists ONLY
+ *           to seed the mark of a package that has never been pushed, and
+ *           `pushDraft` uploads it on the first push that finds the remote
+ *           still bare. It never overwrites a mark set in Studio.
+ *
+ * With neither, the dev draws the robot — the same default production draws.
+ */
+
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+
+/** The backend's own ceiling (routes/apps/media.rs MAX_ICON_BYTES). */
+export const MAX_ICON_BYTES = 512 * 1024;
+
+/** Sniffed, not trusted from the extension — the backend sniffs too, and a
+ * mislabelled file should fail here with a clear message rather than there. */
+export function sniffImage(bytes) {
+  if (!bytes || bytes.length < 12) return null;
+  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
+    return { extension: "png", mediaType: "image/png" };
+  }
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+    return { extension: "jpg", mediaType: "image/jpeg" };
+  }
+  if (
+    bytes.toString("ascii", 0, 4) === "RIFF"
+    && bytes.toString("ascii", 8, 12) === "WEBP"
+  ) {
+    return { extension: "webp", mediaType: "image/webp" };
+  }
+  return null;
+}
+
+/** Candidate basenames, in the order a package would prefer them. */
+export const STAGED_ICON_NAMES = ["icon.webp", "icon.png", "icon.jpg", "icon.jpeg"];
+
+/** The staged mark beside terminus.json, or null. Reads the bytes because
+ * every caller needs them — to serve, to measure, or to upload. */
+export async function readStagedIcon(dir) {
+  let entries;
+  try {
+    entries = new Set(await readdir(dir));
+  } catch {
+    return null;
+  }
+  for (const name of STAGED_ICON_NAMES) {
+    if (!entries.has(name)) continue;
+    const absolute = path.join(dir, name);
+    let bytes;
+    try {
+      bytes = await readFile(absolute);
+    } catch {
+      continue;
+    }
+    const sniffed = sniffImage(bytes);
+    // A file called icon.png that is not an image is a mistake worth ignoring
+    // rather than failing the whole dev over.
+    if (!sniffed) continue;
+    return { name, absolute, bytes, mediaType: sniffed.mediaType };
+  }
+  return null;
+}

package/bin/agent-models.mjs

@@ -0,0 +1,77 @@
+/**
+ * The `models` section of an agent's terminus.json.
+ *
+ * All model configuration lives under ONE key, because it is one decision:
+ *
+ *   "models": {
+ *     "default":   "openai:gpt-5.6-luna",
+ *     "mode":      "all" | "selective" | "default",  // absent means all
+ *     "available": ["anthropic:claude-haiku-4-5"]    // only under selective
+ *   }
+ *
+ * An agent that says nothing gets the house configuration: every model on
+ * Terminus, starting on GPT-5.6 Luna. `terminus init agent` writes it out so
+ * it can be read and changed. `mode: "default"` narrows the agent to its
+ * default model alone.
+ *
+ * This is the only shape read: nothing reads any other key, so a key the
+ * section does not have changes nothing.
+ *
+ * The wire manifest still carries a top-level `model`, because that is a
+ * required, release-pinned field the backend validates — `models.default` is
+ * lifted onto it during the same normalization that turns tool sugar into
+ * capabilities. The section itself never reaches the backend; `agent_models`
+ * is a live setting on its own door, not part of a release.
+ */
+
+export const MODEL_MODES = ["default", "all", "selective"];
+
+/** The model an agent starts on when terminus.json names none. */
+export const DEFAULT_AGENT_MODEL = "openai:gpt-5.6-luna";
+
+/** Which models an agent offers when terminus.json does not say. */
+export const DEFAULT_MODEL_MODE = "all";
+
+/** Read the section, filling in the house configuration where it is silent.
+ * Shape errors are the caller's to report. */
+export function readModelSection(manifest = {}) {
+  const section = manifest.models && !Array.isArray(manifest.models) && typeof manifest.models === "object"
+    ? manifest.models
+    : {};
+  const available = (Array.isArray(section.available) ? section.available : [])
+    .filter((entry) => typeof entry === "string")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  const declared = String(section.mode ?? "").trim();
+  return {
+    default: String(section.default ?? "").trim() || DEFAULT_AGENT_MODEL,
+    mode: MODE_OF(declared, available),
+    available,
+  };
+}
+
+function MODE_OF(declared, available) {
+  if (MODEL_MODES.includes(declared)) return declared;
+  return available.length ? "selective" : DEFAULT_MODEL_MODE;
+}
+
+/** The section as terminus.json spells it: always a default and a mode, and
+ * a list only where `selective` gives it meaning. */
+export function modelSectionDocument({ default: fallback, mode, available = [] }) {
+  const section = {
+    default: String(fallback ?? "").trim() || DEFAULT_AGENT_MODEL,
+    mode: MODEL_MODES.includes(mode) ? mode : DEFAULT_MODEL_MODE,
+  };
+  if (section.mode === "selective") {
+    if (available.length) section.available = [...available];
+    // A selection of nothing is the default model alone.
+    else section.mode = "default";
+  }
+  return section;
+}
+
+/** Write the section back into a manifest. */
+export function writeModelSection(manifest, section) {
+  manifest.models = modelSectionDocument(section);
+  return manifest;
+}

package/bin/agent-type.mjs

@@ -0,0 +1,51 @@
+/**
+ * An agent's `type` in terminus.json: who can read its conversations.
+ *
+ *   "type": "observed"
+ *
+ * "default"  — each conversation stays private to the person having it.
+ * "observed" — every conversation is shared with the agent's maintainers
+ *              from the moment the visitor accepts the disclosure. It
+ *              compiles to the collect plane's conversations channel, and
+ *              that channel IS the collection: nothing else is declared.
+ *
+ * Omitting the key means "default", so the file never states it.
+ */
+
+import { CliError } from "./client.mjs";
+
+export const AGENT_TYPES = ["default", "observed"];
+export const DEFAULT_AGENT_TYPE = "default";
+
+/** The type terminus.json declares; anything it does not recognise reads as
+ * the default here, and the compile is what refuses it. */
+export function readAgentType(manifest = {}) {
+  const type = String(manifest.type ?? "").trim();
+  return AGENT_TYPES.includes(type) ? type : DEFAULT_AGENT_TYPE;
+}
+
+/** Set the type, writing the key only when it is not the default. A key that
+ * arrives sits beside `kind` — the other word for what this package is —
+ * rather than trailing after everything else. */
+export function writeAgentType(manifest, type) {
+  if (!AGENT_TYPES.includes(type)) {
+    throw new CliError(`type is one of ${AGENT_TYPES.map((name) => `'${name}'`).join(", ")}`);
+  }
+  if (type === DEFAULT_AGENT_TYPE) {
+    delete manifest.type;
+    return manifest;
+  }
+  if (Object.hasOwn(manifest, "type") || !Object.hasOwn(manifest, "kind")) {
+    manifest.type = type;
+    return manifest;
+  }
+  // JSON keeps insertion order, so every key is re-seated with `type` after
+  // `kind`; the caller holds this object, which is why it is not replaced.
+  const entries = Object.entries(manifest);
+  for (const [key] of entries) delete manifest[key];
+  for (const [key, value] of entries) {
+    manifest[key] = value;
+    if (key === "kind") manifest.type = type;
+  }
+  return manifest;
+}