@m6d/cortex-cli 0.25.1 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "0.25.1",
+    "version": "0.26.0",
     "description": "Scaffold Cortex projects and manage a Cortex deployment",
     "license": "MIT",
     "type": "module",

package/src/commands/management.ts

@@ -116,7 +116,7 @@ async function login(given: string | undefined, name: string) {
         report.fail({
             what: "Cortex rejected that key",
             blocks: [
-                "Mint one on your account page, or set BOOTSTRAP_MANAGEMENT_KEY on a headless deployment.",
+                "Mint one under Developer settings on your console Account page, or set BOOTSTRAP_MANAGEMENT_KEY on a headless deployment.",
             ],
         });
     }
@@ -129,14 +129,15 @@ async function login(given: string | undefined, name: string) {
 }
 
 /**
- * The key Cortex recognized the bearer as, or null when it does not
- * authenticate. A Cortex that cannot be reached, or answers with
+ * The key Cortex recognized the bearer as, with the environment it acts in,
+ * or null when it does not authenticate. A Cortex that cannot be reached, or answers with
  * anything but 200/401, is the run's outcome, not a CLI bug.
  */
 async function whoami(profile: { url: string; key: string }) {
     try {
         const me = await managementClient(profile).managementKeys.mine();
-        return `key "${me.name}" (${me.fingerprint})`;
+        const { org, project, environment } = me.environment;
+        return `key "${me.name}" (${me.fingerprint}) in ${org}/${project}/${environment}`;
     } catch (error) {
         if (error instanceof ManagementClientError && error.status === 401) return null;
         if (error instanceof ManagementClientError) {

package/src/contracts/management/procedures.generated.ts

@@ -478,7 +478,6 @@ export const managementProcedureKinds = {
   "documents.prepareUpload": "mutation",
   "documents.remove": "mutation",
   "documents.retry": "mutation",
-  "managementKeys.list": "query",
   "managementKeys.mine": "query",
   "manifests.preview": "mutation",
   "manifests.sync": "mutation",
@@ -518,11 +517,15 @@ export const managementProcedureKinds = {
   "observability.updateSchemaDrift": "mutation",
   "orgs.create": "mutation",
   "orgs.delete": "mutation",
+  "orgs.deleteEnvironment": "mutation",
+  "orgs.deleteProject": "mutation",
   "orgs.inviteOwner": "mutation",
   "orgs.list": "query",
   "orgs.options": "query",
+  "orgs.rename": "mutation",
   "orgs.restore": "mutation",
   "orgs.suspend": "mutation",
+  "orgs.updateProject": "mutation",
   "publishing.exclusive": "query",
   "publishing.history": "query",
   "publishing.latest": "query",
@@ -663,6 +666,9 @@ export type ManagementProcedures = {
       locationPicker: boolean;
       messages: boolean;
       whileBusy: "refuse" | "queue" | "steer";
+      a2a: boolean;
+      a2aPushHostnames: string | number | boolean | null | Record<string, unknown> | Array<unknown>;
+      description: string;
       media: Array<"mermaid" | "vega-lite" | "map" | "report">;
       suggestions: Record<"en" | "ar", Array<{
         title: string;
@@ -711,6 +717,9 @@ export type ManagementProcedures = {
       locationPicker: boolean;
       messages: boolean;
       whileBusy: "refuse" | "queue" | "steer";
+      a2a: boolean;
+      a2aPushHostnames: string | number | boolean | null | Record<string, unknown> | Array<unknown>;
+      description: string;
       media: Array<"mermaid" | "vega-lite" | "map" | "report">;
       suggestions: Record<"en" | "ar", Array<{
         title: string;
@@ -771,6 +780,9 @@ export type ManagementProcedures = {
       locationPicker: boolean;
       messages: boolean;
       whileBusy: "refuse" | "queue" | "steer";
+      a2a: boolean;
+      a2aPushHostnames: string | number | boolean | null | Record<string, unknown> | Array<unknown>;
+      description: string;
       media: Array<"mermaid" | "vega-lite" | "map" | "report">;
       suggestions: Record<"en" | "ar", Array<{
         title: string;
@@ -940,6 +952,9 @@ export type ManagementProcedures = {
       locationPicker: boolean;
       messages: boolean;
       whileBusy: "refuse" | "queue" | "steer";
+      a2a: boolean;
+      a2aPushHostnames: string | number | boolean | null | Record<string, unknown> | Array<unknown>;
+      description: string;
       media: Array<"mermaid" | "vega-lite" | "map" | "report">;
       suggestions: Record<"en" | "ar", Array<{
         title: string;
@@ -976,6 +991,9 @@ export type ManagementProcedures = {
       media?: Array<"mermaid" | "vega-lite" | "map" | "report">;
       messages?: boolean;
       whileBusy?: "refuse" | "queue" | "steer";
+      a2a?: boolean;
+      a2aPushHostnames?: Array<string>;
+      description?: string;
       defaultLocale?: "en" | "ar";
       context?: {
         maxContextTokens: number;
@@ -1056,6 +1074,9 @@ export type ManagementProcedures = {
       locationPicker: boolean;
       messages: boolean;
       whileBusy: "refuse" | "queue" | "steer";
+      a2a: boolean;
+      a2aPushHostnames: string | number | boolean | null | Record<string, unknown> | Array<unknown>;
+      description: string;
       media: Array<"mermaid" | "vega-lite" | "map" | "report">;
       suggestions: Record<"en" | "ar", Array<{
         title: string;
@@ -1104,6 +1125,9 @@ export type ManagementProcedures = {
       locationPicker: boolean;
       messages: boolean;
       whileBusy: "refuse" | "queue" | "steer";
+      a2a: boolean;
+      a2aPushHostnames: string | number | boolean | null | Record<string, unknown> | Array<unknown>;
+      description: string;
       media: Array<"mermaid" | "vega-lite" | "map" | "report">;
       suggestions: Record<"en" | "ar", Array<{
         title: string;
@@ -1981,31 +2005,7 @@ export type ManagementProcedures = {
       updatedAt: string;
     };
   };
-  /** The caller's live management keys in name order, with pagination and search: name, display name, fingerprint, scope, and dates. Never the key itself. */
-  "managementKeys.list": {
-    input: {
-      pageIndex?: number;
-      pageSize?: number;
-      q?: string;
-    };
-    output: {
-      items: Array<{
-        id: string;
-        name: string;
-        displayName: Partial<Record<"en" | "ar", string>>;
-        fingerprint: string;
-        permissions: Array<string> | null;
-        lastUsedAt: string | null;
-        revokedAt: string | null;
-        createdAt: string;
-      }>;
-      /** Every row the caller may see, ignoring the search and filters. */
-      count: number;
-      /** The rows matching the search and filters, over all pages: the total to report. */
-      filteredCount: number;
-    };
-  };
-  /** The management key this request authenticated with (name, display name, fingerprint, scope, dates). Refused for a session or an operator token, which are not keys. */
+  /** The management key this request authenticated with (name, display name, fingerprint, scope, dates) and the environment it acts in, by org slug, project and environment name. Refused for a session or an operator token, which are not keys. */
   "managementKeys.mine": {
     input: undefined;
     output: {
@@ -2017,6 +2017,11 @@ export type ManagementProcedures = {
       lastUsedAt: string | null;
       revokedAt: string | null;
       createdAt: string;
+      environment: {
+        org: string;
+        project: string;
+        environment: string;
+      };
     };
   };
   /** What manifests.sync would create, update and delete, kind by kind, after the same checks, dataset host reads, OpenAPI document reads and knowledge document reads, changing nothing: it mints no trigger secret, stores no document and enqueues no job. `conflicts` lists each field that both the manifest and a live write changed since the last apply and that neither `resolutions` nor `prefer` answers; each keeps the manifest's value in what the preview judges. A field holding named parts (an agent's settings, greeting and suggestions, a collection's documents) conflicts part by part, its `key` naming the part. */
@@ -2077,6 +2082,9 @@ export type ManagementProcedures = {
           media?: Array<"mermaid" | "vega-lite" | "map" | "report">;
           messages?: boolean;
           whileBusy?: "refuse" | "queue" | "steer";
+          a2a?: boolean;
+          a2aPushHostnames?: Array<string>;
+          description?: string;
           defaultLocale?: "en" | "ar";
           context?: {
             maxContextTokens?: number;
@@ -2739,6 +2747,9 @@ export type ManagementProcedures = {
           media?: Array<"mermaid" | "vega-lite" | "map" | "report">;
           messages?: boolean;
           whileBusy?: "refuse" | "queue" | "steer";
+          a2a?: boolean;
+          a2aPushHostnames?: Array<string>;
+          description?: string;
           defaultLocale?: "en" | "ar";
           context?: {
             maxContextTokens?: number;
@@ -4239,6 +4250,24 @@ export type ManagementProcedures = {
       updatedAt: string;
     };
   };
+  /** Delete an environment: it serves nothing at once and the daily purge removes it with all it holds. Refused as `last_environment` for a project's last one. */
+  "orgs.deleteEnvironment": {
+    input: {
+      id: string;
+    };
+    output: {
+      environments: number;
+    };
+  };
+  /** Delete a project and every environment in it: they serve nothing at once and the daily purge removes them with all they hold. Refused as `last_project` for an org's last project. */
+  "orgs.deleteProject": {
+    input: {
+      id: string;
+    };
+    output: {
+      environments: number;
+    };
+  };
   /** Invite an email into an org as its Administrator, so an org left without one gets it back; returns the invitation link's path, shown only once, which expires in 7 days. */
   "orgs.inviteOwner": {
     input: {
@@ -4284,6 +4313,21 @@ export type ManagementProcedures = {
       name: string;
     }>;
   };
+  /** Rename the caller's org; its slug, its address in URLs, never changes. Returns the org. */
+  "orgs.rename": {
+    input: {
+      name: string;
+    };
+    output: {
+      id: string;
+      slug: string;
+      name: string;
+      suspendedAt: string | null;
+      purgeAt: string | null;
+      createdAt: string;
+      updatedAt: string;
+    };
+  };
   /** Restore a suspended or deleted org before its purge, as it was, its assistant brought up to this release. */
   "orgs.restore": {
     input: {
@@ -4314,6 +4358,20 @@ export type ManagementProcedures = {
       updatedAt: string;
     };
   };
+  /** Set a project's display name; its name, its address in URLs, never changes. Returns the project. */
+  "orgs.updateProject": {
+    input: {
+      id: string;
+      displayName: Partial<Record<"en" | "ar", string>>;
+    };
+    output: {
+      id: string;
+      name: string;
+      displayName: Partial<Record<"en" | "ar", string>>;
+      createdAt: string;
+      updatedAt: string;
+    };
+  };
   /** Components of every kind shared with this agent alone: what deleting it leaves shared with nobody, unless `agents.delete` names them in `deleteComponentIds`. */
   "publishing.exclusive": {
     input: {
@@ -4368,13 +4426,13 @@ export type ManagementProcedures = {
     input: {
       name: string;
       description: string;
-      permissions: Array<"agents:read" | "agents:write" | "tools:read" | "tools:write" | "tools:execute" | "services:read" | "services:write" | "skills:read" | "skills:write" | "triggers:read" | "triggers:write" | "triggers:fire" | "datasets:read" | "datasets:write" | "datasets:test" | "webhooks:read" | "webhooks:write" | "mcp-servers:read" | "mcp-servers:write" | "knowledge:read" | "knowledge:write" | "secrets:read" | "secrets:write" | "credentials:read" | "credentials:write" | "model-providers:read" | "model-providers:write" | "management-keys:use" | "servers:read" | "servers:write" | "threads:read" | "playground:use" | "publishing:read" | "manifests:apply" | "audit:read" | "observability:read" | "settings:manage" | "users:manage" | "roles:manage" | "orgs:manage">;
+      permissions: Array<"agents:read" | "agents:write" | "tools:read" | "tools:write" | "tools:execute" | "services:read" | "services:write" | "skills:read" | "skills:write" | "triggers:read" | "triggers:write" | "triggers:fire" | "datasets:read" | "datasets:write" | "datasets:test" | "webhooks:read" | "webhooks:write" | "mcp-servers:read" | "mcp-servers:write" | "knowledge:read" | "knowledge:write" | "secrets:read" | "secrets:write" | "credentials:read" | "credentials:write" | "model-providers:read" | "model-providers:write" | "management-keys:use" | "servers:read" | "servers:write" | "threads:read" | "playground:use" | "publishing:read" | "manifests:apply" | "audit:read" | "observability:read" | "settings:manage" | "users:manage" | "roles:manage" | "projects:manage" | "orgs:manage">;
     };
     output: {
       id: string;
       name: string;
       description: string;
-      permissions: Array<"agents:read" | "agents:write" | "tools:read" | "tools:write" | "tools:execute" | "services:read" | "services:write" | "skills:read" | "skills:write" | "triggers:read" | "triggers:write" | "triggers:fire" | "datasets:read" | "datasets:write" | "datasets:test" | "webhooks:read" | "webhooks:write" | "mcp-servers:read" | "mcp-servers:write" | "knowledge:read" | "knowledge:write" | "secrets:read" | "secrets:write" | "credentials:read" | "credentials:write" | "model-providers:read" | "model-providers:write" | "management-keys:use" | "servers:read" | "servers:write" | "threads:read" | "playground:use" | "publishing:read" | "manifests:apply" | "audit:read" | "observability:read" | "settings:manage" | "users:manage" | "roles:manage" | "orgs:manage">;
+      permissions: Array<"agents:read" | "agents:write" | "tools:read" | "tools:write" | "tools:execute" | "services:read" | "services:write" | "skills:read" | "skills:write" | "triggers:read" | "triggers:write" | "triggers:fire" | "datasets:read" | "datasets:write" | "datasets:test" | "webhooks:read" | "webhooks:write" | "mcp-servers:read" | "mcp-servers:write" | "knowledge:read" | "knowledge:write" | "secrets:read" | "secrets:write" | "credentials:read" | "credentials:write" | "model-providers:read" | "model-providers:write" | "management-keys:use" | "servers:read" | "servers:write" | "threads:read" | "playground:use" | "publishing:read" | "manifests:apply" | "audit:read" | "observability:read" | "settings:manage" | "users:manage" | "roles:manage" | "projects:manage" | "orgs:manage">;
     };
   };
   /** Delete a role; the built-in Administrator role cannot be deleted. */
@@ -4396,7 +4454,7 @@ export type ManagementProcedures = {
         id: string;
         name: string;
         description: string;
-        permissions: Array<"agents:read" | "agents:write" | "tools:read" | "tools:write" | "tools:execute" | "services:read" | "services:write" | "skills:read" | "skills:write" | "triggers:read" | "triggers:write" | "triggers:fire" | "datasets:read" | "datasets:write" | "datasets:test" | "webhooks:read" | "webhooks:write" | "mcp-servers:read" | "mcp-servers:write" | "knowledge:read" | "knowledge:write" | "secrets:read" | "secrets:write" | "credentials:read" | "credentials:write" | "model-providers:read" | "model-providers:write" | "management-keys:use" | "servers:read" | "servers:write" | "threads:read" | "playground:use" | "publishing:read" | "manifests:apply" | "audit:read" | "observability:read" | "settings:manage" | "users:manage" | "roles:manage" | "orgs:manage">;
+        permissions: Array<"agents:read" | "agents:write" | "tools:read" | "tools:write" | "tools:execute" | "services:read" | "services:write" | "skills:read" | "skills:write" | "triggers:read" | "triggers:write" | "triggers:fire" | "datasets:read" | "datasets:write" | "datasets:test" | "webhooks:read" | "webhooks:write" | "mcp-servers:read" | "mcp-servers:write" | "knowledge:read" | "knowledge:write" | "secrets:read" | "secrets:write" | "credentials:read" | "credentials:write" | "model-providers:read" | "model-providers:write" | "management-keys:use" | "servers:read" | "servers:write" | "threads:read" | "playground:use" | "publishing:read" | "manifests:apply" | "audit:read" | "observability:read" | "settings:manage" | "users:manage" | "roles:manage" | "projects:manage" | "orgs:manage">;
         builtInId: string | null;
         createdAt: string;
         assignedUsers: number;
@@ -4412,14 +4470,14 @@ export type ManagementProcedures = {
     input: {
       name: string;
       description: string;
-      permissions: Array<"agents:read" | "agents:write" | "tools:read" | "tools:write" | "tools:execute" | "services:read" | "services:write" | "skills:read" | "skills:write" | "triggers:read" | "triggers:write" | "triggers:fire" | "datasets:read" | "datasets:write" | "datasets:test" | "webhooks:read" | "webhooks:write" | "mcp-servers:read" | "mcp-servers:write" | "knowledge:read" | "knowledge:write" | "secrets:read" | "secrets:write" | "credentials:read" | "credentials:write" | "model-providers:read" | "model-providers:write" | "management-keys:use" | "servers:read" | "servers:write" | "threads:read" | "playground:use" | "publishing:read" | "manifests:apply" | "audit:read" | "observability:read" | "settings:manage" | "users:manage" | "roles:manage" | "orgs:manage">;
+      permissions: Array<"agents:read" | "agents:write" | "tools:read" | "tools:write" | "tools:execute" | "services:read" | "services:write" | "skills:read" | "skills:write" | "triggers:read" | "triggers:write" | "triggers:fire" | "datasets:read" | "datasets:write" | "datasets:test" | "webhooks:read" | "webhooks:write" | "mcp-servers:read" | "mcp-servers:write" | "knowledge:read" | "knowledge:write" | "secrets:read" | "secrets:write" | "credentials:read" | "credentials:write" | "model-providers:read" | "model-providers:write" | "management-keys:use" | "servers:read" | "servers:write" | "threads:read" | "playground:use" | "publishing:read" | "manifests:apply" | "audit:read" | "observability:read" | "settings:manage" | "users:manage" | "roles:manage" | "projects:manage" | "orgs:manage">;
       id: string;
     };
     output: {
       id: string;
       name: string;
       description: string;
-      permissions: Array<"agents:read" | "agents:write" | "tools:read" | "tools:write" | "tools:execute" | "services:read" | "services:write" | "skills:read" | "skills:write" | "triggers:read" | "triggers:write" | "triggers:fire" | "datasets:read" | "datasets:write" | "datasets:test" | "webhooks:read" | "webhooks:write" | "mcp-servers:read" | "mcp-servers:write" | "knowledge:read" | "knowledge:write" | "secrets:read" | "secrets:write" | "credentials:read" | "credentials:write" | "model-providers:read" | "model-providers:write" | "management-keys:use" | "servers:read" | "servers:write" | "threads:read" | "playground:use" | "publishing:read" | "manifests:apply" | "audit:read" | "observability:read" | "settings:manage" | "users:manage" | "roles:manage" | "orgs:manage">;
+      permissions: Array<"agents:read" | "agents:write" | "tools:read" | "tools:write" | "tools:execute" | "services:read" | "services:write" | "skills:read" | "skills:write" | "triggers:read" | "triggers:write" | "triggers:fire" | "datasets:read" | "datasets:write" | "datasets:test" | "webhooks:read" | "webhooks:write" | "mcp-servers:read" | "mcp-servers:write" | "knowledge:read" | "knowledge:write" | "secrets:read" | "secrets:write" | "credentials:read" | "credentials:write" | "model-providers:read" | "model-providers:write" | "management-keys:use" | "servers:read" | "servers:write" | "threads:read" | "playground:use" | "publishing:read" | "manifests:apply" | "audit:read" | "observability:read" | "settings:manage" | "users:manage" | "roles:manage" | "projects:manage" | "orgs:manage">;
     };
   };
   /** Delete a secret; fails while a credential or an agent's auth (its signing secret or reCAPTCHA API key) still references it. */
@@ -4977,7 +5035,7 @@ export type ManagementProcedures = {
       name: string;
     };
   };
-  /** The org's settings: log and thread retention, and the browser origins its engine routes admit. */
+  /** The caller's environment's settings: log and thread retention, and the browser origins its engine routes admit. */
   "settings.get": {
     input: undefined;
     output: {
@@ -4986,12 +5044,12 @@ export type ManagementProcedures = {
       corsOrigins: Array<string>;
     };
   };
-  /** Change the org's settings: retention, and the browser origins its engine routes admit. */
+  /** Change the caller's environment's settings: retention, and the browser origins its engine routes admit. */
   "settings.update": {
     input: {
       logRetentionDays: number;
       threadRetentionDays?: number;
-      /** Browser origins, beside the console's own, that may call the org's engine routes, such as a site embedding its widget. */
+      /** Browser origins, beside the console's own, that may call the environment's engine routes, such as a site embedding its widget. */
       corsOrigins: Array<string>;
     };
     output: {

package/src/contracts/manifest/index.ts

@@ -198,6 +198,9 @@ export const HOSTNAME_PATTERN =
 /** At most this many hosts an agent's `fetchImage` tool pulls images from. */
 export const FETCH_IMAGE_HOSTS_LIMIT = 20;
 
+/** At most this many hosts an agent's A2A push notifications are posted to. */
+export const A2A_PUSH_HOSTS_LIMIT = 20;
+
 /**
  * The widget's landing-page prompt chips, per locale: a short title the chip
  * shows and the prompt it sends when clicked. The console stores this exact
@@ -1829,6 +1832,15 @@ export const agentSettingsSchema = z.strictObject({
     messages: z.boolean().default(true),
     /** A message sent while the agent works: refused, queued, or steering the running turn. */
     whileBusy: z.enum(WHILE_BUSY).default("refuse"),
+    /** Serves the agent over A2A: its agent card and its A2A endpoint. */
+    a2a: z.boolean().default(false),
+    /** Hosts an A2A caller's push notifications may be posted to; none, no push. */
+    a2aPushHostnames: z
+        .array(z.string().max(253).regex(HOSTNAME_PATTERN))
+        .max(A2A_PUSH_HOSTS_LIMIT)
+        .default([]),
+    /** What the agent does, in a sentence or two: its A2A card tells callers. */
+    description: z.string().trim().max(1000).default(""),
     defaultLocale: localeSchema.default(BASE_LOCALE),
     context: z
         .strictObject({

package/src/contracts/runs/index.ts

@@ -130,7 +130,7 @@ export type WaitState = (typeof WAIT_STATES)[number];
 
 /**
  * One call a waiting run waits on, and the arguments it was made with: an
- * approval, which `POST /orgs/:org/agents/:agentName/runs/:id/answer`
+ * approval, which `POST /orgs/:org/projects/:project/envs/:env/agents/:agentName/runs/:id/answer`
  * decides, or a client tool's call, which its widget answers.
  */
 export const runWaitSchema = z.object({
@@ -142,8 +142,8 @@ export const runWaitSchema = z.object({
 export type RunWait = z.infer<typeof runWaitSchema>;
 
 /**
- * A run as `GET /orgs/:org/agents/:agentName/runs/:id` reads it, and each
- * row of `GET /orgs/:org/agents/:agentName/triggers/:name/runs`: the input
+ * A run as `GET /orgs/:org/projects/:project/envs/:env/agents/:agentName/runs/:id` reads it, and each
+ * row of `GET /orgs/:org/projects/:project/envs/:env/agents/:agentName/triggers/:name/runs`: the input
  * it answers, and its thread, null once that thread is gone.
  */
 export const runRecordSchema = z.object({
@@ -169,16 +169,16 @@ export const runRecordSchema = z.object({
 });
 export type RunRecord = z.infer<typeof runRecordSchema>;
 
-/** `GET /orgs/:org/agents/:agentName/triggers/:name/runs`: a page of the trigger's runs, newest first. */
+/** `GET /orgs/:org/projects/:project/envs/:env/agents/:agentName/triggers/:name/runs`: a page of the trigger's runs, newest first. */
 export const runListSchema = z.object({ runs: z.array(runRecordSchema) });
 export type RunList = z.infer<typeof runListSchema>;
 
-/** `POST /orgs/:org/agents/:agentName/runs/:id/cancel`: whether it stopped or ended anything; a run already over is left as it is. */
+/** `POST /orgs/:org/projects/:project/envs/:env/agents/:agentName/runs/:id/cancel`: whether it stopped or ended anything; a run already over is left as it is. */
 export const runCancelSchema = z.object({ cancelled: z.boolean() });
 export type RunCancel = z.infer<typeof runCancelSchema>;
 
 /**
- * `POST /orgs/:org/agents/:agentName/runs/:id/answer`: the decision on one
+ * `POST /orgs/:org/projects/:project/envs/:env/agents/:agentName/runs/:id/answer`: the decision on one
  * call the run waits on. A call id is as long as the model provider made it
  * (some carry a signature), so only the request's body limit bounds it.
  */

package/src/contracts/server/index.ts

@@ -231,7 +231,7 @@ const runEventFields = {
  * A run parked on calls that wait for a decision, as every receiver hears
  * of it: a webhook's body and the agent's server's event are this one
  * object. `runId` names the run a receiver decides through
- * `POST /orgs/:org/agents/:agentName/runs/:id/answer`. Every call it waits on is
+ * `POST /orgs/:org/projects/:project/envs/:env/agents/:agentName/runs/:id/answer`. Every call it waits on is
  * named, a client tool's among them; one whose input would carry the event
  * past `SERVER_REQUEST_MAX_BYTES` comes without its input. A run waiting
  * only on its widget's calls is not announced.

package/src/contracts/triggers/index.ts

@@ -4,7 +4,7 @@ import { inputReceiptSchema, runRecordSchema } from "../runs/index";
 
 /*
  * Triggers: named entry points on an agent. A caller fires one over
- * `POST /orgs/:org/agents/:agentName/triggers/:name` with the trigger's secret as its
+ * `POST /orgs/:org/projects/:project/envs/:env/agents/:agentName/triggers/:name` with the trigger's secret as its
  * bearer; the fire is an input on the thread the trigger's policy names,
  * and the run that takes it is read and decided under `/runs/:id`. These
  * are the shapes Cortex answers that caller with.
@@ -13,24 +13,35 @@ import { inputReceiptSchema, runRecordSchema } from "../runs/index";
 /** The tool a trigger run with an output schema answers through; no other tool may take its name. */
 export const TRIGGER_ANSWER_TOOL_NAME = "submitAnswer";
 
-/** The engine route of org `orgSlug`, which its agents' routes and its sign-ins sit under. */
-export function orgRoute(orgSlug: string) {
-    return `/orgs/${encodeURIComponent(orgSlug)}`;
+/** An environment by the names its engine routes carry: its org's slug, its project's name and its own. */
+export const environmentAddressSchema = z.object({
+    /** The slug of the org. */
+    org: z.string(),
+    /** The name of the project in that org. */
+    project: z.string(),
+    /** The name of the environment of that project, such as `production`. */
+    environment: z.string(),
+});
+export type EnvironmentAddress = z.infer<typeof environmentAddressSchema>;
+
+/** The engine route of environment `address`, which its agents' routes and its sign-ins sit under. */
+export function environmentRoute({ org, project, environment }: EnvironmentAddress) {
+    return `/orgs/${encodeURIComponent(org)}/projects/${encodeURIComponent(project)}/envs/${encodeURIComponent(environment)}`;
 }
 
-/** The engine route of agent `agentName` in org `orgSlug`, which the widget chats with and its triggers and runs sit under. */
-export function agentRoute(orgSlug: string, agentName: string) {
-    return `${orgRoute(orgSlug)}/agents/${encodeURIComponent(agentName)}`;
+/** The engine route of agent `agentName` in environment `address`, which the widget chats with and its triggers and runs sit under. */
+export function agentRoute(address: EnvironmentAddress, agentName: string) {
+    return `${environmentRoute(address)}/agents/${encodeURIComponent(agentName)}`;
 }
 
-/** The engine route a trigger is fired at on agent `agentName` in org `orgSlug`; its runs are listed under it. */
-export function triggerRoute(orgSlug: string, agentName: string, name: string) {
-    return `${agentRoute(orgSlug, agentName)}/triggers/${encodeURIComponent(name)}`;
+/** The engine route a trigger is fired at on agent `agentName` in environment `address`; its runs are listed under it. */
+export function triggerRoute(address: EnvironmentAddress, agentName: string, name: string) {
+    return `${agentRoute(address, agentName)}/triggers/${encodeURIComponent(name)}`;
 }
 
-/** The engine route a run of agent `agentName` in org `orgSlug` is read at, and answered and cancelled under. */
-export function runRoute(orgSlug: string, agentName: string, runId: string) {
-    return `${agentRoute(orgSlug, agentName)}/runs/${encodeURIComponent(runId)}`;
+/** The engine route a run of agent `agentName` in environment `address` is read at, and answered and cancelled under. */
+export function runRoute(address: EnvironmentAddress, agentName: string, runId: string) {
+    return `${agentRoute(address, agentName)}/runs/${encodeURIComponent(runId)}`;
 }
 
 /** What a fire answers once its run started: its input, run and thread; `GET .../runs/:id` reads the run. */
@@ -48,7 +59,7 @@ export const fireRejectedSchema = z.object({
 });
 
 /**
- * What `POST /orgs/:org/agents/:agentName/triggers/:name` answers as JSON: the run it
+ * What `POST .../agents/:agentName/triggers/:name` answers as JSON: the run it
  * started (`started`, 202); with `?wait=`, that run once it ended (a
  * `RunRecord`, 200) or parked on a decision (202); the fire's input while it
  * waits on the thread, once refused, or once cancelled before any run took

package/src/contracts/wire/index.ts

@@ -216,7 +216,7 @@ export type AccountConnection = {
 };
 
 /**
- * The form `POST /orgs/:org/oauth/start` takes, posted into the window a sign-in runs
+ * The form `POST /orgs/:org/projects/:project/envs/:env/oauth/start` takes, posted into the window a sign-in runs
  * in with its bearer in the body, so no link can start one: the console's
  * operator token and the server's id for the shared connection.
  */
@@ -627,8 +627,8 @@ export type WaitingInput<TPart = unknown> = {
     inputId: string;
     delivery: "prompt" | "steer" | "followUp" | "answer" | "note";
     message: CortexMessage<TPart>;
-    /** Whether it is text alone, which a running turn may take in as a steer; one with files waits for a turn of its own. */
-    textOnly: boolean;
+    /** Whether the widget may move it to steer the running turn: text alone, sent from the widget. One with files, or one an A2A caller sent, which is its own task, waits for a turn of its own. */
+    steerable: boolean;
 };
 
 /**

package/src/scaffold/files.ts

@@ -28,7 +28,7 @@ import { applyPorts, type Ports } from "@/scaffold/ports";
  * `@m6d/cortex` range below are stamped by scripts/sync-package-versions.ts
  * before the CLI publishes, so a scaffold pins what was current then.
  */
-const CORTEX_VERSION = "0.24.1";
+const CORTEX_VERSION = "0.25.0";
 
 /** This machine as Cortex's containers name it: the one private host the stack's egress policy admits. */
 export const DOCKER_HOST = "host.docker.internal";
@@ -147,7 +147,7 @@ function packageJson({ name, datasets, setup }: Project) {
                 verify: "bun run format:check && bun run lint && bun run spellcheck && bun run check && bun run audit",
             },
             dependencies: {
-                "@m6d/cortex": "~0.12.1",
+                "@m6d/cortex": "~0.13.0",
                 // drizzle 1.0 is in beta; this is the build `@m6d/cortex/drizzle` is tested against.
                 ...(datasets ? { "drizzle-orm": "1.0.0-beta.15-859cf75" } : {}),
                 hono: "^4.12.3",