@m6d/cortex-cli 0.13.0 → 0.14.0

package/src/contracts/manifest/index.ts

@@ -7,6 +7,7 @@ import {
     IDENTIFIER_PATTERN,
     localeSchema,
     SERVER_EVENTS,
+    refuseBlockedApprovalTitle,
     serverToolSchema,
 } from "../server/index";
 import { MESSAGE_TRIGGER_NAME } from "../triggers/index";
@@ -573,7 +574,7 @@ const toolBaseSchema = z.strictObject({
     audience: audienceSchema,
 });
 
-/** A tool that calls an endpoint; `approval` set, every call waits for the end user to approve it. */
+/** A tool that calls an endpoint; with `requiresApproval`, every call waits for the end user to approve it. */
 const calledToolSchema = toolBaseSchema.extend({
     inputSchema: objectSchemaOf(true).default(EMPTY_OBJECT),
     url: upstreamUrlSchema.refine(
@@ -581,33 +582,66 @@ const calledToolSchema = toolBaseSchema.extend({
         "a {parameter} outside the path or query",
     ),
     credentials: credentialsSchema,
-    approval: serverToolSchema.shape.approval,
+    requiresApproval: z.boolean().default(false),
 });
 
-const manifestToolSchema = z.discriminatedUnion("type", [
-    calledToolSchema.extend({
-        type: z.literal("http"),
-        method: z.enum(TOOL_METHODS),
-        readOnly: z.boolean(),
-        ...toolConfigByType.http.shape,
-    }),
-    /** The endpoint is the initiate call that opens the page; never read-only, so a reload rejoins it. */
-    calledToolSchema.extend({
-        type: z.literal("embedded"),
-        method: z.enum(TOOL_METHODS),
-        ...toolConfigByType.embedded.shape,
-    }),
-    /** Always POSTed. */
-    calledToolSchema.extend({
-        type: z.literal("soap"),
-        readOnly: z.boolean(),
-        ...toolConfigByType.soap.shape,
-    }),
-    /** Answered by your app: the model calls it and the widget hands the call over. */
-    toolBaseSchema.extend({ type: z.literal("client") }),
-]);
+const manifestToolSchema = z
+    .discriminatedUnion("type", [
+        calledToolSchema.extend({
+            type: z.literal("http"),
+            method: z.enum(TOOL_METHODS),
+            readOnly: z.boolean(),
+            ...toolConfigByType.http.shape,
+        }),
+        /** The endpoint is the initiate call that opens the page; never read-only, so a reload rejoins it. */
+        calledToolSchema.extend({
+            type: z.literal("embedded"),
+            method: z.enum(TOOL_METHODS),
+            ...toolConfigByType.embedded.shape,
+        }),
+        /** Always POSTed. */
+        calledToolSchema.extend({
+            type: z.literal("soap"),
+            readOnly: z.boolean(),
+            ...toolConfigByType.soap.shape,
+        }),
+        /** Answered by your app: the model calls it and the widget hands the call over. */
+        toolBaseSchema.extend({ type: z.literal("client") }),
+    ])
+    .superRefine((tool, context) => {
+        if (tool.type !== "client") refuseBlockedApprovalTitle(tool, context, []);
+    });
 export type ManifestTool = z.input<typeof manifestToolSchema>;
 
+const toolNamesSchema = z.array(serverToolSchema.shape.name).max(500).default([]);
+
+/**
+ * An OpenAPI document whose operations become HTTP tools this manifest owns.
+ * Each apply reads it, imports every operation Cortex supports, keeps those
+ * tools in step with the document and deletes the ones it no longer has.
+ * Every tool presents `credentials`. A GET call runs at once; any other
+ * method waits for the end user's approval, unless `approval` names the
+ * tool the other way.
+ */
+const manifestOpenApiSchema = z.strictObject({
+    /** Names the source in what an apply reports. */
+    name: nameSchema,
+    /** Where the document is read, with no credentials: OpenAPI 3 or Swagger 2, JSON or YAML. */
+    url: upstreamUrlSchema,
+    credentials: credentialsSchema,
+    /** Tools listed in every turn of every agent they reach, whatever the question. */
+    pinned: toolNamesSchema,
+    approval: z
+        .strictObject({ never: toolNamesSchema, always: toolNamesSchema })
+        .prefault({})
+        .refine(
+            ({ never, always }) => !never.some((name) => always.includes(name)),
+            "a tool both never and always needs approval",
+        ),
+    audience: audienceSchema,
+});
+export type ManifestOpenApi = z.input<typeof manifestOpenApiSchema>;
+
 /** Identified by its `key`, which skills and collections scope themselves by; `name` is its label. */
 const manifestServiceSchema = z.strictObject({
     /** What consumers parameterize their tools with; fixed once published. */
@@ -896,6 +930,7 @@ export const manifestSchema = z.strictObject({
     id: slugSchema,
     agents: listOf(manifestAgentSchema, (agent) => agent.slug),
     tools: listOf(manifestToolSchema, byName),
+    openapi: listOf(manifestOpenApiSchema, byName),
     services: listOf(manifestServiceSchema, (service) => service.key),
     skills: listOf(manifestSkillSchema, byName),
     triggers: listOf(manifestTriggerSchema, byName),
@@ -907,8 +942,14 @@ export const manifestSchema = z.strictObject({
 /** A manifest as written: every field with a default may be left out. */
 export type Manifest = z.input<typeof manifestSchema>;
 
-/** Entry names per kind: agents by slug, services by key, everything else by name. */
-const namesByKindSchema = z.record(manifestSchema.keyof().exclude(["id"]), z.array(z.string()));
+/**
+ * Entry names per kind: agents by slug, services by key, everything else by
+ * name. An OpenAPI source's operations are counted among `tools`.
+ */
+const namesByKindSchema = z.record(
+    manifestSchema.keyof().exclude(["id", "openapi"]),
+    z.array(z.string()),
+);
 
 /** What an apply creates, updates and deletes, kind by kind; a preview answers the same without doing it. */
 export const manifestChangesSchema = z.object({

package/src/contracts/server/index.ts

@@ -2,7 +2,8 @@ import { z } from "zod";
 import { REQUEST_LOCATION_TOOL } from "../client-tools/index";
 import { backendErrorSchema } from "../errors/index";
 import { pendingApprovalSchema, TRIGGER_ANSWER_TOOL_NAME } from "../triggers/index";
-import { LOCALES } from "../wire/index";
+import { isRecord, unescapePointerToken } from "../json/index";
+import { APPROVAL_TITLE_FIELD, LOCALES } from "../wire/index";
 
 /*
  * The server protocol: what Cortex calls on a customer's backend. `GET /`
@@ -108,11 +109,14 @@ export function isBuiltInToolName(name: string) {
     return BUILT_IN_TOOL_NAMES.some((builtIn) => builtIn === name);
 }
 
+/** The longest name a tool takes, a server's or one defined in Cortex. */
+export const TOOL_NAME_MAX_LENGTH = 64;
+
 /** A tool name, a server's or one defined in Cortex: an identifier no built-in tool holds. */
 const declaredToolNameSchema = z
     .string()
     .regex(IDENTIFIER_PATTERN)
-    .max(64)
+    .max(TOOL_NAME_MAX_LENGTH)
     .refine((name) => !isBuiltInToolName(name), "the name of a built-in tool");
 
 const jsonSchemaSchema = z.record(z.string(), z.unknown());
@@ -135,8 +139,9 @@ export type ServerVariable = z.infer<typeof serverVariableSchema>;
 
 /**
  * A tool the server runs. Its input is an object, the `input` its calls
- * carry. An `approval` sentence per locale parks every call for the end
- * user's approval.
+ * carry. `requiresApproval` parks every call for the end user's approval;
+ * such a tool's input cannot declare `APPROVAL_TITLE_FIELD`, which the
+ * model fills for the approval card.
  */
 export const serverToolSchema = z.object({
     name: declaredToolNameSchema,
@@ -147,7 +152,7 @@ export const serverToolSchema = z.object({
     ),
     outputSchema: jsonSchemaSchema.optional(),
     readOnly: z.boolean(),
-    approval: z.record(localeSchema, z.string().trim().min(1).max(500)).optional(),
+    requiresApproval: z.boolean().optional(),
 });
 export type ServerTool = z.infer<typeof serverToolSchema>;
 
@@ -179,6 +184,97 @@ export const approvalRequestedEventSchema = z.object({
 });
 export type ApprovalRequestedEvent = z.infer<typeof approvalRequestedEventSchema>;
 
+/** A JSON Pointer token as a key: percent-decoded, then unescaped; undefined when its encoding is broken. */
+function pointerKey(token: string) {
+    try {
+        return unescapePointerToken(decodeURIComponent(token));
+    } catch {
+        return undefined;
+    }
+}
+
+/** What a local `$ref` (`#/$defs/order`) points at in `root`, read as the input compiler reads it; undefined for any other. */
+function pointedAt(root: unknown, ref: string) {
+    if (!ref.startsWith("#")) return undefined;
+    let node = root;
+    for (const token of ref.slice(1).split("/").slice(1)) {
+        const key = pointerKey(token);
+        node =
+            key !== undefined && (isRecord(node) || Array.isArray(node))
+                ? new Map<string, unknown>(Object.entries(node)).get(key)
+                : undefined;
+    }
+    return node;
+}
+
+/** Whether one schema node names `APPROVAL_TITLE_FIELD` as a property or a required field. */
+function namesApprovalTitle(node: Record<string, unknown>) {
+    const required: unknown = node.required;
+    return (
+        (isRecord(node.properties) && Object.hasOwn(node.properties, APPROVAL_TITLE_FIELD)) ||
+        (Array.isArray(required) && required.includes(APPROVAL_TITLE_FIELD))
+    );
+}
+
+/** What describes the same object as `node`: its `allOf`, `anyOf` and `oneOf` members, and what its local `$ref` points at in `root`. */
+function sameObjectSchemas(node: Record<string, unknown>, root: unknown) {
+    const schemas: unknown[] = typeof node.$ref === "string" ? [pointedAt(root, node.$ref)] : [];
+    for (const keyword of ["allOf", "anyOf", "oneOf"]) {
+        const members: unknown = node[keyword];
+        if (!Array.isArray(members)) continue;
+        const listed: unknown[] = members;
+        schemas.push(...listed);
+    }
+    return schemas;
+}
+
+/**
+ * Every node that describes the same object as an input schema's root: the
+ * root, and what `sameObjectSchemas` reaches from it at any depth, each once.
+ */
+function sameObjectNodes(inputSchema: unknown) {
+    const nodes = new Array<Record<string, unknown>>();
+    const pending = [inputSchema];
+    while (pending.length > 0) {
+        const node = pending.pop();
+        if (!isRecord(node) || nodes.includes(node)) continue;
+        nodes.push(node);
+        pending.push(...sameObjectSchemas(node, inputSchema));
+    }
+    return nodes;
+}
+
+/** Whether one schema node is closed to properties it does not declare. */
+function closed(node: Record<string, unknown>) {
+    return node.additionalProperties === false || node.unevaluatedProperties === false;
+}
+
+/**
+ * Whether an input schema leaves no room for `APPROVAL_TITLE_FIELD`, which
+ * Cortex adds to the root of a tool that needs approval: a node describing
+ * the input names it, or one besides the root is closed to it, so a strict
+ * reading of the schema could not take the title.
+ */
+export function blocksApprovalTitle(inputSchema: unknown) {
+    return sameObjectNodes(inputSchema).some(
+        (node) => namesApprovalTitle(node) || (node !== inputSchema && closed(node)),
+    );
+}
+
+/** Refuses, under `path`, a tool that needs approval whose input `blocksApprovalTitle`. */
+export function refuseBlockedApprovalTitle(
+    tool: { requiresApproval?: boolean; inputSchema: unknown },
+    context: z.RefinementCtx,
+    path: Array<string | number>,
+) {
+    if (!tool.requiresApproval || !blocksApprovalTitle(tool.inputSchema)) return;
+    context.addIssue({
+        code: "custom",
+        path: [...path, "inputSchema"],
+        message: `a tool that needs approval cannot take an input named ${APPROVAL_TITLE_FIELD}, nor one a closed sub-schema describes: Cortex adds the approval card's title to it`,
+    });
+}
+
 function uniqueNames(entries: ReadonlyArray<{ name: string }>) {
     return new Set(entries.map((entry) => entry.name)).size === entries.length;
 }
@@ -187,7 +283,13 @@ function uniqueNames(entries: ReadonlyArray<{ name: string }>) {
 export const serverManifestSchema = z.object({
     version: z.string().min(1).max(128),
     variables: z.array(serverVariableSchema).max(100).refine(uniqueNames, "variable names repeat"),
-    tools: z.array(serverToolSchema).max(500).refine(uniqueNames, "tool names repeat"),
+    tools: z
+        .array(serverToolSchema)
+        .max(500)
+        .refine(uniqueNames, "tool names repeat")
+        .superRefine((tools, context) => {
+            tools.forEach((tool, index) => refuseBlockedApprovalTitle(tool, context, [index]));
+        }),
     verify: z.boolean(),
     events: z.array(z.enum(SERVER_EVENTS)),
 });

package/src/contracts/wire/index.ts

@@ -171,13 +171,18 @@ export type LocalizedText = Record<Locale, string>;
  */
 export const STATEMENT_TOOLS = ["executeCode", "queryDataset", "describeDataset"] as const;
 
+/**
+ * The input Cortex adds to every tool that waits for the end user's approval:
+ * the model writes what that one call will do, and the approval card shows it
+ * as its title. Cortex removes it before the call runs.
+ */
+export const APPROVAL_TITLE_FIELD = "approvalTitle";
+
 /**
  * What Cortex stamps on a tool call's `metadata.cortex` from its first chunk,
  * so the live part and the stored one agree.
  */
 export type ToolCallMetadata = {
-    /** The action the approval card names, in the author's words rather than the function's name. */
-    approval?: LocalizedText;
     /**
      * Set on every call the client answers: a client tool's, the consumer's own, or a built-in
      * input's. Cortex runs every other call, so only these take an output from a request.

package/src/management/client.ts

@@ -225,6 +225,8 @@ export async function callManagement(
             ...(method === "post" ? { "Content-Type": "application/json" } : {}),
         },
         body: method === "post" && input !== undefined ? JSON.stringify(input) : undefined,
+    }).catch((error: unknown) => {
+        throw new UnreachableError(error);
     });
     const body: unknown = await response.json().catch(() => null);
     if (!response.ok) {
@@ -261,6 +263,18 @@ function queryString(input: Record<string, unknown>) {
     return encoded === "" ? "" : `?${encoded}`;
 }
 
+/**
+ * Cortex did not answer at all: refused, reset, unresolvable. `fetch` rejects
+ * only for these, with whatever its runtime throws (Bun's is a plain `Error`
+ * with a `code`), so `callManagement` names them once here.
+ */
+export class UnreachableError extends Error {
+    public constructor(cause: unknown) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.name = "UnreachableError";
+    }
+}
+
 /** A refusal; `detail` is what the refusal names, when it names something (an entry, the row holding a name). */
 export class ManagementError extends Error {
     public constructor(

package/src/management/profiles.ts

@@ -87,14 +87,16 @@ export function removeProfile(name: string) {
 }
 
 /**
- * The profile a management command runs against: `CORTEX_URL` + `CORTEX_KEY`
- * when both are set (CI, containers), else the named or current entry from
- * the file. `undefined` means nobody has logged in.
+ * The profile a management command runs against: the entry `name` picks from
+ * the file, else `CORTEX_URL` + `CORTEX_KEY` when both are set (CI, containers,
+ * a project's .env), else the current entry. A name always wins, so `-p prod`
+ * inside a project whose .env points at its own Cortex still reaches prod.
+ * `undefined` means nobody has logged in.
  */
 export function resolveProfile(name?: string) {
     const url = process.env["CORTEX_URL"];
     const key = process.env["CORTEX_KEY"];
-    if (url && key) return { name: "env", url: url.replace(/\/+$/, ""), key };
+    if (name === undefined && url && key) return { name: "env", url: url.replace(/\/+$/, ""), key };
     const store = readStore();
     const chosen = name ?? store.current;
     const profile = lookup(store, chosen);