@w6w/cli 0.9.15 → 0.9.23

package/dist/src/client.js

@@ -9,9 +9,16 @@
  * has a flag which outranks the environment variable.
  *
  * ```
- * CLI flag (--base-url / --token)  >  environment variable  >  nothing (an error)
+ * base URL  CLI flag (--base-url)  >  W6W_BASE_URL  >  stored `baseUrl`  >  DEFAULT_BASE_URL
+ * token     CLI flag (--token)     >  W6W_TOKEN     >  the stored token for the resolved base URL
  * ```
  *
+ * The stored tier is the per-user config `w6w auth login` writes (see
+ * `src/config-store.ts`). A stored token is **bound to the base URL it was saved
+ * for**: it is looked up by the canonical resolved base URL, exact match only, so
+ * pointing `--base-url` or `W6W_BASE_URL` at another host can never send it
+ * there. That is the trust boundary of this module.
+ *
  * The resolved values are passed to the SDK **explicitly**, and the SDK is never
  * left to read the environment on the CLI's behalf. That is a mechanism choice,
  * not a stylistic one: the CLI has to be able to say *which* source it was
@@ -23,7 +30,10 @@
  *
  * @module
  */
-import { ConfigError, W6WClient } from "@w6w/sdk";
+import { ConfigError, joinBaseUrl, W6WClient } from "@w6w/sdk";
+import { NO_CONFIG } from "./config-store.js";
+/** The API every command targets unless told otherwise. Equals endpoints.json `defaultBaseUrl`. */
+export const DEFAULT_BASE_URL = "https://api.w6w.io";
 /** Environment variable holding the server **origin**. Falls behind `--base-url`. */
 export const ENV_BASE_URL = "W6W_BASE_URL";
 /** Environment variable holding the bearer token. Falls behind `--token`. */
@@ -34,8 +44,8 @@ export const NO_ENV = () => undefined;
  * Read an environment variable, treating a blank value as **absent**.
  *
  * `W6W_BASE_URL=`, `W6W_BASE_URL="   "` and an unset `W6W_BASE_URL` are the same
- * thing: all three fall through the precedence chain to the next source, and
- * ultimately to a usage error naming both sources.
+ * thing: all three fall through the precedence chain to the next source (the
+ * stored base URL, then the default).
  *
  * The check is a trim-and-emptiness test and deliberately **not** a nullish
  * coalesce. `??` does not convert `""`, so a set-but-empty variable would
@@ -60,21 +70,6 @@ export function envValue(env, name) {
         return undefined;
     return value;
 }
-/**
- * Apply the precedence rule to one setting.
- *
- * A flag that was **given** wins outright, even when what it was given is empty:
- * that is a value the user typed, and quietly consulting the environment behind
- * an explicit `--token=` would be the CLI second-guessing them. (It still does
- * not produce a usable value — an empty flag reaches the same error — but it
- * gets there without a detour through the environment.) Only an **absent** flag
- * falls through.
- */
-function resolve(flag, env, name) {
-    if (flag !== undefined)
-        return flag;
-    return envValue(env, name);
-}
 /**
  * A value the CLI cannot work with, phrased as a usage error.
  *
@@ -123,7 +118,7 @@ function requireAbsolute(baseUrl) {
  * the header builder and comes back as a bare `TypeError` from outside anyone's
  * error model: a stack trace, for a typo.
  */
-function isUnsendable(token) {
+export function isUnsendable(token) {
     for (const character of token) {
         const code = character.codePointAt(0) ?? 0;
         if (code < 0x20 || code === 0x7f || code > 0xff)
@@ -138,6 +133,67 @@ function requireSendableToken(token) {
     throw configError("The w6w API token contains a character that cannot be sent in an HTTP header " +
         "(a control character, such as a newline).", "--token", ENV_TOKEN, "A token read out of a file usually carries a trailing newline — strip it.");
 }
+/**
+ * The one resolver. `createClient` and every `auth` command use it, so what
+ * `auth status` reports is what a command will do.
+ *
+ * Base URL: flag (given, even empty) > env (blank = absent) > stored `baseUrl` >
+ * {@linkcode DEFAULT_BASE_URL}, validated, then canonicalised once. Token: flag >
+ * env > `stored.hosts[<canonical base URL>]` — exact key only.
+ *
+ * @throws {ConfigError} When the base URL is blank-by-flag, relative, or not http(s),
+ *   or a resolved token cannot be sent in a header. A *missing* token is not an
+ *   error here; `createClient` raises that.
+ */
+export function resolveSettings(globals, env = NO_ENV, stored = NO_CONFIG) {
+    let raw;
+    let baseUrlSource;
+    if (globals.baseUrl !== undefined) {
+        raw = globals.baseUrl;
+        baseUrlSource = "flag";
+    }
+    else {
+        const fromEnv = envValue(env, ENV_BASE_URL);
+        if (fromEnv !== undefined) {
+            raw = fromEnv;
+            baseUrlSource = "env";
+        }
+        else if (stored.baseUrl.trim().length > 0) {
+            raw = stored.baseUrl;
+            baseUrlSource = "config";
+        }
+        else {
+            raw = DEFAULT_BASE_URL;
+            baseUrlSource = "default";
+        }
+    }
+    if (raw.trim().length === 0) {
+        throw configError("No w6w base URL is configured.", "--base-url", ENV_BASE_URL, "It holds the server's origin, like `https://api.example.com`; the API is served at its root, so no path is appended.");
+    }
+    // Validate for the CLI's own message, then canonicalise with the SDK's join —
+    // the single key used both to look a token up and to build the client.
+    const baseUrl = joinBaseUrl(requireAbsolute(raw.trim()));
+    let token;
+    let tokenSource;
+    if (globals.token !== undefined) {
+        token = globals.token;
+        tokenSource = "flag";
+    }
+    else {
+        const fromEnv = envValue(env, ENV_TOKEN);
+        if (fromEnv !== undefined) {
+            token = fromEnv;
+            tokenSource = "env";
+        }
+        else if (Object.hasOwn(stored.hosts, baseUrl)) {
+            token = stored.hosts[baseUrl].token;
+            tokenSource = "config";
+        }
+    }
+    if (token === undefined || token.trim().length === 0)
+        return { baseUrl, baseUrlSource };
+    return { baseUrl, baseUrlSource, token: requireSendableToken(token), tokenSource };
+}
 /**
  * Build the API client for one invocation.
  *
@@ -147,25 +203,22 @@ function requireSendableToken(token) {
  *
  * @param globals - The parsed global flags.
  * @param env - The environment seam. Defaults to an empty environment.
- * @param options - Transport and default project.
+ * @param options - Transport, default project and the stored config.
  * @returns A configured client.
  * @throws {ConfigError} When the base URL or token is missing or unusable — a usage error.
  */
 export function createClient(globals, env = NO_ENV, options = {}) {
-    const baseUrl = resolve(globals.baseUrl, env, ENV_BASE_URL);
-    if (baseUrl === undefined || baseUrl.trim().length === 0) {
-        throw configError("No w6w base URL is configured.", "--base-url", ENV_BASE_URL, "It holds the server's origin, like `https://api.example.com`; the API is served at its root, so no path is appended.");
-    }
-    const token = resolve(globals.token, env, ENV_TOKEN);
-    if (token === undefined || token.trim().length === 0) {
-        throw configError("No w6w API token is configured.", "--token", ENV_TOKEN, "Every w6w API command is authenticated.");
+    const settings = resolveSettings(globals, env, options.stored);
+    if (settings.token === undefined) {
+        throw configError(`No w6w API token is configured for ${settings.baseUrl}.`, "--token", ENV_TOKEN, "Or save one with `w6w auth login` (a saved token only applies to the base URL it was saved for). " +
+            "Every w6w API command is authenticated.");
     }
     // The join rule (origin in, base path appended, never doubled) belongs to the
     // SDK and is applied by the constructor. Nothing here re-derives it — read it
     // back off `client.config.baseUrl` if you need to know where a request went.
     return new W6WClient({
-        baseUrl: requireAbsolute(baseUrl.trim()),
-        token: requireSendableToken(token),
+        baseUrl: settings.baseUrl,
+        token: settings.token,
         project: options.project,
         fetch: options.fetch,
     });

package/dist/src/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/agents-studio.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `w6w skills|context|agents …` — the agent-authoring surface at the command line.
+ *
+ * Seventeen commands, **one SDK call each**. Skill upload is deliberately not
+ * here: it is `w6w assets upload --purpose skill`.
+ *
+ * Two write paths carry optimistic concurrency — `agents update` and
+ * `context entries-update`. Both send the body `revision` and, when given, the
+ * `--if-unmodified-since` precondition. A `409` is re-thrown as an `ApiError`
+ * with a message naming the **current revision** and what to do next; a `428`
+ * says the precondition is required. Both keep their status, so the exit code is
+ * the API-error code and a script can tell the write was refused. A uniform
+ * `404` needs no handling at all: `main()` prints the server's one-line message
+ * and exits, never a stack trace.
+ *
+ * Only flags the user typed reach the wire, so an omitted `--description` leaves
+ * the field alone and `--description ""` clears it.
+ *
+ * @module
+ */
+import type { CommandRegistry } from "../../mod.ts";
+/** Keys are the help tree's command paths (`naming.cli`). */
+export declare const AGENT_STUDIO_COMMANDS: CommandRegistry;
+//# sourceMappingURL=agents-studio.d.ts.map

package/dist/src/commands/agents-studio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-studio.d.ts","sourceRoot":"","sources":["../../../src/commands/agents-studio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAkC,eAAe,EAAE,MAAM,cAAc,CAAC;AA+hBpF,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB,EAAE,eAyBnC,CAAC"}

package/dist/src/commands/agents-studio.js

@@ -0,0 +1,431 @@
+/**
+ * `w6w skills|context|agents …` — the agent-authoring surface at the command line.
+ *
+ * Seventeen commands, **one SDK call each**. Skill upload is deliberately not
+ * here: it is `w6w assets upload --purpose skill`.
+ *
+ * Two write paths carry optimistic concurrency — `agents update` and
+ * `context entries-update`. Both send the body `revision` and, when given, the
+ * `--if-unmodified-since` precondition. A `409` is re-thrown as an `ApiError`
+ * with a message naming the **current revision** and what to do next; a `428`
+ * says the precondition is required. Both keep their status, so the exit code is
+ * the API-error code and a script can tell the write was refused. A uniform
+ * `404` needs no handling at all: `main()` prints the server's one-line message
+ * and exits, never a stack trace.
+ *
+ * Only flags the user typed reach the wire, so an omitted `--description` leaves
+ * the field alone and `--description ""` clears it.
+ *
+ * @module
+ */
+import { ApiError } from "@w6w/sdk";
+import { argument, noExtraArguments, requiredFlag, table, textFlag, usageError } from "./shared.js";
+/** A positive-integer flag, or `undefined` when absent. */
+function count(context, name) {
+    const value = textFlag(context, name);
+    if (value === undefined)
+        return undefined;
+    if (!/^[0-9]+$/.test(value) || Number(value) < 1) {
+        throw usageError(context, `\`--${name}\` must be a positive integer.`);
+    }
+    return Number(value);
+}
+/** A non-negative integer flag that must be present (a revision may be `0`). */
+function revision(context) {
+    const value = requiredFlag(context, "revision", "--revision <n>");
+    if (!/^[0-9]+$/.test(value)) {
+        throw usageError(context, "`--revision` must be a non-negative integer.");
+    }
+    return Number(value);
+}
+function includeArchived(context) {
+    return context.invocation.options.includeArchived === true ? { includeArchived: true } : {};
+}
+function tags(context) {
+    const value = textFlag(context, "tags");
+    if (value === undefined)
+        return undefined;
+    return value.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+}
+/** A flag whose value is a JSON array of pins. */
+function jsonList(context, name) {
+    const value = textFlag(context, name);
+    if (value === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw usageError(context, `\`--${name}\` must be valid JSON (an array).`);
+    }
+    if (!Array.isArray(parsed))
+        throw usageError(context, `\`--${name}\` must be a JSON array.`);
+    return parsed;
+}
+function visibility(context) {
+    const value = textFlag(context, "visibility");
+    if (value === undefined)
+        return undefined;
+    if (value !== "private" && value !== "project" && value !== "account") {
+        throw usageError(context, "`--visibility` must be private, project or account.");
+    }
+    return value;
+}
+const cell = (value) => value === null || value === undefined || value === "" ? "-" : String(value);
+/**
+ * Run a precondition write, turning a 409 / 428 into an actionable message.
+ *
+ * The thrown error is still an `ApiError` with the original status, code and
+ * body, so the exit code and `--json` consumers are unchanged; only the sentence
+ * a human reads is replaced.
+ */
+async function guarded(what, refetch, run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 409) {
+            const current = err.raw?.error
+                ?.currentRevision;
+            const at = current === undefined ? "" : ` (current revision: ${current})`;
+            throw new ApiError(409, err.code, `Conflict: ${what} changed since you read it${at}. ` +
+                `Re-read it with \`${refetch}\` and retry with the new revision.`, err.raw);
+        }
+        if (err instanceof ApiError && err.status === 428) {
+            throw new ApiError(428, err.code, `Precondition required: ${what} can only be updated with a precondition. ` +
+                `Pass \`--if-unmodified-since <ts>\` (the updatedAt you read).`, err.raw);
+        }
+        throw err;
+    }
+}
+const precondition = (context) => ({
+    ifUnmodifiedSince: textFlag(context, "ifUnmodifiedSince"),
+});
+// ---------------------------------------------------------------- skills
+const skillRow = (s) => [s.id, s.name, cell(s.activeVersionId), cell(s.archivedAt)];
+const skillsList = async (context) => {
+    noExtraArguments(context, 0);
+    const rows = await context.client().skills.list({
+        ...includeArchived(context),
+        limit: count(context, "limit"),
+    });
+    context.out.emit(rows, (styles) => rows.length === 0
+        ? styles.dim("No skills.")
+        : table(["ID", "NAME", "ACTIVE VERSION", "ARCHIVED"], rows.map(skillRow), styles));
+};
+const skillsGet = async (context) => {
+    const id = argument(context, 0, "a skill id (see: `w6w skills list`)");
+    noExtraArguments(context, 1);
+    const skill = await context.client().skills.get(id);
+    context.out.emit(skill, (styles) => table(["ID", "NAME", "ACTIVE VERSION", "ARCHIVED"], [skillRow(skill)], styles));
+};
+const skillsVersions = async (context) => {
+    const id = argument(context, 0, "a skill id (see: `w6w skills list`)");
+    noExtraArguments(context, 1);
+    const rows = await context.client().skills.versions(id);
+    const row = (v) => {
+        const r = v;
+        return [cell(r.id), cell(r.version), cell(r.createdAt)];
+    };
+    context.out.emit(rows, (styles) => rows.length === 0
+        ? styles.dim("No versions.")
+        : table(["ID", "VERSION", "CREATED"], rows.map(row), styles));
+};
+const skillsArchive = async (context) => {
+    const id = argument(context, 0, "a skill id (see: `w6w skills list`)");
+    noExtraArguments(context, 1);
+    const skill = await context.client().skills.archive(id);
+    context.out.emit(skill, (styles) => `Archived ${styles.bold(skill.name)} ${styles.dim(`(${id})`)}`);
+};
+// --------------------------------------------------------------- context
+const collectionRow = (c) => [
+    c.id,
+    c.name,
+    c.tags.join(",") || "-",
+    c.visibility,
+    cell(c.archivedAt),
+];
+const COLLECTION_HEAD = ["ID", "NAME", "TAGS", "VISIBILITY", "ARCHIVED"];
+const contextList = async (context) => {
+    noExtraArguments(context, 0);
+    const rows = await context.client().context.list({
+        ...includeArchived(context),
+        limit: count(context, "limit"),
+    });
+    context.out.emit(rows, (styles) => rows.length === 0
+        ? styles.dim("No context collections.")
+        : table(COLLECTION_HEAD, rows.map(collectionRow), styles));
+};
+const contextCreate = async (context) => {
+    const name = argument(context, 0, "a collection name");
+    noExtraArguments(context, 1);
+    const created = await context.client().context.create({
+        name,
+        description: textFlag(context, "description"),
+        tags: tags(context),
+        visibility: visibility(context),
+    });
+    context.out.emit(created, (styles) => `Created ${styles.bold(created.name)} ${styles.dim(`(${created.id})`)}`);
+};
+const contextGet = async (context) => {
+    const id = argument(context, 0, "a collection id (see: `w6w context list`)");
+    noExtraArguments(context, 1);
+    const found = await context.client().context.get(id);
+    context.out.emit(found, (styles) => table(COLLECTION_HEAD, [collectionRow(found)], styles));
+};
+/** A patch: only the typed flags are sent (collection edits are last-write-wins). */
+const contextUpdate = async (context) => {
+    const id = argument(context, 0, "a collection id (see: `w6w context list`)");
+    noExtraArguments(context, 1);
+    const patch = {};
+    const name = textFlag(context, "name");
+    if (name !== undefined)
+        patch.name = name;
+    const description = textFlag(context, "description");
+    if (description !== undefined)
+        patch.description = description;
+    const tagList = tags(context);
+    if (tagList !== undefined)
+        patch.tags = tagList;
+    const updated = await context.client().context.update(id, patch);
+    context.out.emit(updated, (styles) => `Updated ${styles.bold(updated.name)} ${styles.dim(`(${id})`)}`);
+};
+const contextArchive = async (context) => {
+    const id = argument(context, 0, "a collection id (see: `w6w context list`)");
+    noExtraArguments(context, 1);
+    const archived = await context.client().context.archive(id);
+    context.out.emit(archived, (styles) => `Archived ${styles.bold(archived.name)} ${styles.dim(`(${id})`)}`);
+};
+const entryRow = (e) => [
+    e.id,
+    e.name,
+    e.mediaType,
+    cell(e.revision),
+    cell(e.archivedAt),
+];
+const ENTRY_HEAD = ["ID", "NAME", "TYPE", "REVISION", "ARCHIVED"];
+const entriesList = async (context) => {
+    const id = argument(context, 0, "a collection id (see: `w6w context list`)");
+    noExtraArguments(context, 1);
+    const rows = await context.client().context.entries.list(id, includeArchived(context));
+    context.out.emit(rows, (styles) => rows.length === 0 ? styles.dim("No entries.") : table(ENTRY_HEAD, rows.map(entryRow), styles));
+};
+const entriesCreate = async (context) => {
+    const id = argument(context, 0, "a collection id (see: `w6w context list`)");
+    const name = argument(context, 1, "an entry name");
+    noExtraArguments(context, 2);
+    const entry = await context.client().context.entries.create(id, {
+        name,
+        text: requiredFlag(context, "text", "--text <text>"),
+    });
+    context.out.emit(entry, (styles) => `Created ${styles.bold(entry.name)} ${styles.dim(`(${entry.id}, revision ${entry.revision})`)}`);
+};
+const entriesUpdate = async (context) => {
+    const id = argument(context, 0, "a collection id (see: `w6w context list`)");
+    const entryId = argument(context, 1, "an entry id (see: `w6w context entries-list`)");
+    noExtraArguments(context, 2);
+    const text = requiredFlag(context, "text", "--text <text>");
+    const rev = revision(context);
+    const entry = await guarded("the entry", `w6w context entries-list ${id}`, () => context.client().context.entries.update(id, entryId, { text, revision: rev }, precondition(context)));
+    context.out.emit(entry, (styles) => `Updated ${styles.bold(entry.name)} ${styles.dim(`(${entry.id}, revision ${entry.revision})`)}`);
+};
+// ------------------------------------------------------- context-entries
+const topEntryRow = (e) => [
+    e.id,
+    e.name,
+    cell(e.mediaType),
+    cell(e.revision),
+];
+const TOP_ENTRY_HEAD = ["ID", "NAME", "TYPE", "REVISION"];
+const ceList = async (context) => {
+    noExtraArguments(context, 0);
+    const rows = await context.client().contextEntries.list({
+        ...includeArchived(context),
+        collectionId: textFlag(context, "collectionId"),
+        project: textFlag(context, "project"),
+    });
+    context.out.emit(rows, (styles) => rows.length === 0
+        ? styles.dim("No context entries.")
+        : table(TOP_ENTRY_HEAD, rows.map(topEntryRow), styles));
+};
+const ceCreate = async (context) => {
+    const name = argument(context, 0, "an entry name");
+    noExtraArguments(context, 1);
+    const ids = textFlag(context, "collectionId");
+    const collectionIds = ids === undefined
+        ? undefined
+        : ids.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    const entry = await context.client().contextEntries.create({
+        name,
+        text: requiredFlag(context, "text", "--text <text>"),
+        visibility: visibility(context),
+        ...(collectionIds ? { collectionIds } : {}),
+    });
+    context.out.emit(entry, (styles) => `Created ${styles.bold(entry.name)} ${styles.dim(`(${entry.id}, revision ${entry.revision})`)}`);
+};
+const ceGet = async (context) => {
+    const id = argument(context, 0, "an entry id (see: `w6w context-entries list`)");
+    noExtraArguments(context, 1);
+    const entry = await context.client().contextEntries.get(id);
+    context.out.emit(entry, (styles) => table(TOP_ENTRY_HEAD, [topEntryRow(entry)], styles));
+};
+const ceUpdate = async (context) => {
+    const id = argument(context, 0, "an entry id (see: `w6w context-entries list`)");
+    noExtraArguments(context, 1);
+    const text = requiredFlag(context, "text", "--text <text>");
+    const rev = revision(context);
+    const entry = await guarded("the entry", `w6w context-entries get ${id}`, () => context.client().contextEntries.update(id, { text, revision: rev }, precondition(context)));
+    context.out.emit(entry, (styles) => `Updated ${styles.bold(entry.name)} ${styles.dim(`(${entry.id}, revision ${entry.revision})`)}`);
+};
+const ceArchive = async (context) => {
+    const id = argument(context, 0, "an entry id (see: `w6w context-entries list`)");
+    noExtraArguments(context, 1);
+    const entry = await context.client().contextEntries.archive(id);
+    context.out.emit(entry, (styles) => `Archived ${styles.bold(entry.name)} ${styles.dim(`(${id})`)}`);
+};
+const ceAdd = async (context) => {
+    const id = argument(context, 0, "an entry id (see: `w6w context-entries list`)");
+    const collection = argument(context, 1, "a collection id (see: `w6w context list`)");
+    noExtraArguments(context, 2);
+    const entry = await context.client().contextEntries.addToCollection(id, collection);
+    context.out.emit(entry, (styles) => `Added ${styles.bold(entry.name)} to ${styles.dim(collection)}`);
+};
+const ceRemove = async (context) => {
+    const id = argument(context, 0, "an entry id (see: `w6w context-entries list`)");
+    const collection = argument(context, 1, "a collection id (see: `w6w context list`)");
+    noExtraArguments(context, 2);
+    const entry = await context.client().contextEntries.removeFromCollection(id, collection);
+    context.out.emit(entry, (styles) => `Removed ${styles.bold(entry.name)} from ${styles.dim(collection)}`);
+};
+// ---------------------------------------------------------------- agents
+const agentRow = (a) => [
+    a.id,
+    cell(a.name),
+    cell(a.modelRouteId),
+    String(a.revision),
+    a.archived ? "yes" : "no",
+    "no",
+];
+const AGENT_HEAD = ["ID", "NAME", "MODEL ROUTE", "REVISION", "ARCHIVED", "RUNNABLE"];
+const agentsList = async (context) => {
+    noExtraArguments(context, 0);
+    const rows = await context.client().agents.list(includeArchived(context));
+    context.out.emit(rows, (styles) => rows.length === 0 ? styles.dim("No agents.") : table(AGENT_HEAD, rows.map(agentRow), styles));
+};
+/** The fields `agents create|update` share, only those typed. */
+function agentFields(context) {
+    const fields = {};
+    const name = textFlag(context, "name");
+    if (name !== undefined)
+        fields.name = name;
+    const instructions = textFlag(context, "instructions");
+    if (instructions !== undefined)
+        fields.instructions = instructions;
+    const route = textFlag(context, "modelRouteId");
+    if (route !== undefined)
+        fields.modelRouteId = route;
+    const skills = jsonList(context, "skills");
+    if (skills !== undefined)
+        fields.skills = skills;
+    const pins = jsonList(context, "context");
+    if (pins !== undefined)
+        fields.context = pins;
+    const vis = visibility(context);
+    if (vis !== undefined)
+        fields.visibility = vis;
+    const project = textFlag(context, "project");
+    if (project !== undefined)
+        fields.project = project;
+    const modelOptions = modelOptionFlags(context);
+    if (modelOptions !== undefined)
+        fields.modelOptions = modelOptions;
+    return fields;
+}
+/** `--temperature`, `--top-p`, `--max-output-tokens` and the repeatable `--stop`. */
+function modelOptionFlags(context) {
+    const options = {};
+    const number = (name, min, max, integer) => {
+        const raw = textFlag(context, name);
+        if (raw === undefined)
+            return undefined;
+        const value = Number(raw);
+        if (raw.trim() === "" || !Number.isFinite(value) || value < min || value > max ||
+            (integer && !Number.isInteger(value))) {
+            throw usageError(context, `\`--${name}\` must be ${integer ? "an integer" : "a number"} from ${min} to ${max}.`);
+        }
+        return value;
+    };
+    const temperature = number("temperature", 0, 2, false);
+    if (temperature !== undefined)
+        options.temperature = temperature;
+    const topP = number("topP", 0, 1, false);
+    if (topP !== undefined)
+        options.topP = topP;
+    const max = number("maxOutputTokens", 1, 1_000_000, true);
+    if (max !== undefined)
+        options.maxOutputTokens = max;
+    const stop = context.invocation.lists?.stop;
+    if (stop !== undefined)
+        options.stop = stop;
+    return Object.keys(options).length > 0 ? options : undefined;
+}
+const agentsCreate = async (context) => {
+    noExtraArguments(context, 0);
+    const agent = await context.client().agents.create(agentFields(context));
+    context.out.emit(agent, (styles) => `Created ${styles.bold(cell(agent.name))} ${styles.dim(`(${agent.id}, revision ${agent.revision})`)}`);
+};
+const agentsGet = async (context) => {
+    const id = argument(context, 0, "an agent id (see: `w6w agents list`)");
+    noExtraArguments(context, 1);
+    const agent = await context.client().agents.get(id);
+    context.out.emit(agent, (styles) => {
+        const issues = agent.validation.map((v) => `  ! ${JSON.stringify(v)}`);
+        return [
+            table(AGENT_HEAD, [agentRow(agent)], styles),
+            ...(agent.instructions.length > 0 ? ["", agent.instructions] : []),
+            ...(issues.length > 0 ? ["", "Validation:", ...issues] : []),
+        ].join("\n");
+    });
+};
+const agentsUpdate = async (context) => {
+    const id = argument(context, 0, "an agent id (see: `w6w agents list`)");
+    noExtraArguments(context, 1);
+    const patch = { ...agentFields(context), revision: revision(context) };
+    const agent = await guarded("the agent", `w6w agents get ${id}`, () => context.client().agents.update(id, patch, precondition(context)));
+    context.out.emit(agent, (styles) => `Updated ${styles.bold(cell(agent.name))} ${styles.dim(`(${id}, revision ${agent.revision})`)}`);
+};
+const agentsArchive = async (context) => {
+    const id = argument(context, 0, "an agent id (see: `w6w agents list`)");
+    noExtraArguments(context, 1);
+    const agent = await context.client().agents.archive(id);
+    context.out.emit(agent, (styles) => `Archived ${styles.bold(cell(agent.name))} ${styles.dim(`(${id})`)}`);
+};
+/** Keys are the help tree's command paths (`naming.cli`). */
+export const AGENT_STUDIO_COMMANDS = {
+    "skills list": skillsList,
+    "skills get": skillsGet,
+    "skills versions": skillsVersions,
+    "skills archive": skillsArchive,
+    "context list": contextList,
+    "context create": contextCreate,
+    "context get": contextGet,
+    "context update": contextUpdate,
+    "context archive": contextArchive,
+    "context entries-list": entriesList,
+    "context entries-create": entriesCreate,
+    "context entries-update": entriesUpdate,
+    "context-entries list": ceList,
+    "context-entries create": ceCreate,
+    "context-entries get": ceGet,
+    "context-entries update": ceUpdate,
+    "context-entries archive": ceArchive,
+    "context-entries add-to-collection": ceAdd,
+    "context-entries remove-from-collection": ceRemove,
+    "agents list": agentsList,
+    "agents create": agentsCreate,
+    "agents get": agentsGet,
+    "agents update": agentsUpdate,
+    "agents archive": agentsArchive,
+};
+//# sourceMappingURL=agents-studio.js.map