@m6d/cortex-cli 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "0.5.1",
+    "version": "0.7.0",
     "description": "Scaffold and operate Cortex servers",
     "license": "MIT",
     "type": "module",

package/src/commands/cc.ts

@@ -167,7 +167,7 @@ function withProfileFile<T>(operation: () => T) {
 
 /** The key rides on every call, so the URL it goes to must be https (or loopback). */
 function requireTls(url: string) {
-    if (canCarrySecret(url, false)) return url;
+    if (canCarrySecret(url, [])) return url;
     return report.fail({
         what: `${url} is not https`,
         blocks: [

package/src/contracts/credentials/index.ts

@@ -21,12 +21,12 @@ export const credentialDefinitionSchema = z.discriminatedUnion("kind", [
     }),
     z.object({
         kind: z.literal("oauth2-client-credentials"),
-        /** The token endpoint; a client secret travels over TLS, to loopback, or to a private host while the egress policy is relaxed. */
+        /** The token endpoint; a client secret travels over TLS, to loopback, or to a host the egress policy admits. */
         tokenUrl: z
             .url()
             .refine(
                 (url) => canCarrySecret(url),
-                "token URL must be https, or http to loopback (or a private host while the egress policy is relaxed)",
+                "token URL must be https, or http to loopback or to a host the egress policy admits",
             ),
         clientId: z.string().min(1),
         clientSecret: z.string().min(1),

package/src/contracts/egress/index.ts

@@ -1,7 +1,7 @@
 import { lookup } from "node:dns/promises";
 import type { LookupFunction } from "node:net";
 import { Agent } from "undici";
-import { isEgressRelaxed, isPrivateAddress } from "./url";
+import { isEgressAllowedHost, isPrivateAddress, normalizeHost } from "./url";
 
 /*
  * The outbound network policy for URLs a tenant controls (tool endpoints,
@@ -14,17 +14,14 @@ import { isEgressRelaxed, isPrivateAddress } from "./url";
 export { credentialForms, scrubCredentialStrings } from "./scrub";
 
 /**
- * Whether an IP address must not be dialed. `EGRESS_ALLOW_PRIVATE_NETWORK=true` is
- * the development opt-out for localhost and private demo backends; it disables
- * every range check, lets a secret travel over plain http to a private host
- * (`canCarrySecret`), and must never be set in production.
+ * Whether a host may be dialed at these addresses: any address when the
+ * policy admits the host (`EGRESS_ALLOWED_HOSTS`), else only public ones.
  */
-function isBlockedAddress(address: string) {
-    if (isEgressRelaxed()) return false;
-    return isPrivateAddress(address);
+function isDialable(hostname: string, addresses: string[]) {
+    return isEgressAllowedHost(hostname) || !addresses.some(isPrivateAddress);
 }
 
-export { canCarrySecret, isEgressRelaxed } from "./url";
+export { canCarrySecret, egressAllowedHosts } from "./url";
 
 export function egressError() {
     const error: NodeJS.ErrnoException = new Error("egress blocked");
@@ -51,7 +48,13 @@ const pinnedLookup: LookupFunction = (hostname, options, callback) => {
     lookup(hostname, { all: true, verbatim: true }).then(
         (addresses) => {
             const first = addresses[0];
-            if (!first || addresses.some((address) => isBlockedAddress(address.address))) {
+            if (
+                !first ||
+                !isDialable(
+                    hostname,
+                    addresses.map((address) => address.address),
+                )
+            ) {
                 callback(egressError(), "", 0);
                 return;
             }
@@ -74,23 +77,33 @@ const pinnedLookup: LookupFunction = (hostname, options, callback) => {
 
 /**
  * Checks a URL before any socket opens: http(s) only, no embedded credentials,
- * an optional exact-host allowlist, and every resolved address public. Returns
+ * an optional per-call restriction to `allowedHostnames`, and the host dialable
+ * (every resolved address public, or the host admitted by the policy). Returns
  * the bare hostname on success. `pinnedLookup` re-checks at connect time; this
  * is the cheap, clean refusal for a statically bad target.
  */
 export async function checkEgressTarget(target: URL, allowedHostnames?: string[]) {
+    // Resolved as written, root dot included, so an absolute name is never search-suffixed; normalized only to compare.
     const hostname = target.hostname.replace(/^\[(.*)]$/, "$1");
-    const normalize = (host: string) => host.toLowerCase().replace(/\.$/, "");
 
     if (!["http:", "https:"].includes(target.protocol) || target.username || target.password) {
         return false;
     }
-    if (allowedHostnames && !allowedHostnames.map(normalize).includes(normalize(hostname))) {
+    if (
+        allowedHostnames &&
+        !allowedHostnames.map(normalizeHost).includes(normalizeHost(hostname))
+    ) {
         return false;
     }
 
     const preflight = await lookup(hostname, { all: true, verbatim: true });
-    return preflight.length > 0 && !preflight.some((address) => isBlockedAddress(address.address));
+    return (
+        preflight.length > 0 &&
+        isDialable(
+            hostname,
+            preflight.map((address) => address.address),
+        )
+    );
 }
 
 /**

package/src/contracts/egress/url.ts

@@ -1,6 +1,8 @@
 /*
- * Where a secret may be sent, judged from the URL alone. Pure and free of
- * node modules, so a browser bundle judges a URL the same way the server does.
+ * The egress policy as far as a URL alone can tell: which addresses are
+ * private, which hosts the deployment admits, and where a secret may be
+ * sent. Pure and free of node modules, so a browser bundle judges a URL the
+ * same way the server does.
  */
 
 type Range = { first: number; last: number };
@@ -63,46 +65,64 @@ export function isPrivateAddress(address: string) {
     return address.includes(":") ? isBlockedV6(address) : isBlockedV4(address);
 }
 
+/** Loopback by its normalized spelling: `[::1]` arrives from a URL without its brackets. */
 function isLoopback(hostname: string) {
-    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
 }
 
 /**
- * A host on the developer's own network: a private IP literal, a bare compose
- * service name such as `app`, or a `.internal` / `.local` / `.localhost` name
- * such as `host.docker.internal`. Public names and addresses are not.
+ * One spelling for a host: lower case, no DNS root dot, no IPv6 brackets, and
+ * an IPv6 literal compressed the way `URL` spells it, so `fd00:0::1` in the
+ * policy matches the `fd00::1` a parsed URL reports.
  */
-function isPrivateHost(hostname: string) {
-    const bare = hostname.replace(/^\[|\]$/g, "");
-    if (bare.includes(":") || V4_LITERAL.test(bare)) return isPrivateAddress(bare);
-    return !hostname.includes(".") || /\.(internal|local|localhost)$/.test(hostname);
+export function normalizeHost(hostname: string) {
+    const bare = hostname
+        .toLowerCase()
+        .replace(/\.$/, "")
+        .replace(/^\[(.*)]$/, "$1");
+    if (!bare.includes(":")) return bare;
+    try {
+        return new URL(`http://[${bare}]`).hostname.replace(/^\[(.*)]$/, "$1");
+    } catch {
+        return bare;
+    }
 }
 
 /**
- * The development opt-out of the egress policy: `EGRESS_ALLOW_PRIVATE_NETWORK=true`
- * lifts every range check and lets a secret travel over plain http within the
- * private network. Read lazily and through `globalThis`, so a browser bundle,
- * which has no `process`, sees it off.
+ * The hosts the egress policy admits beyond its strict rules, from
+ * `EGRESS_ALLOWED_HOSTS`: hostnames separated by commas, or `*` for every
+ * host. A listed host may be dialed even when it resolves to a private
+ * address, and a secret may travel to it over plain http; everything else
+ * keeps the strict rules. Empty, the default, admits nothing. Read lazily and
+ * through `globalThis`, so a browser bundle, which has no `process`, sees
+ * nothing admitted.
  */
-export function isEgressRelaxed() {
-    return globalThis.process?.env?.EGRESS_ALLOW_PRIVATE_NETWORK === "true";
+export function egressAllowedHosts() {
+    return (globalThis.process?.env?.EGRESS_ALLOWED_HOSTS ?? "")
+        .split(",")
+        .map((host) => host.trim())
+        .filter(Boolean);
+}
+
+/** Whether the policy admits this host: it is listed, or the list is `*`. */
+export function isEgressAllowedHost(hostname: string, allowed = egressAllowedHosts()) {
+    const wanted = normalizeHost(hostname);
+    return allowed.some((host) => host === "*" || normalizeHost(host) === wanted);
 }
 
 /**
- * Whether a secret may be sent to this URL: over TLS anywhere, or over plain
- * http to loopback, and while the egress policy is relaxed to any private host.
- * Pass `relaxed` explicitly where the policy is known from elsewhere (the
- * browser form reads it from the session) or must stay strict regardless of it
- * (a URL the browser or the CLI dials, not the server).
+ * Whether a secret may be sent to this URL: over TLS anywhere, over plain
+ * http to loopback, or over plain http to a host the policy admits. Pass
+ * `allowed` explicitly where the policy is known from elsewhere (the browser
+ * form reads it from the session) or must stay strict regardless of it (a
+ * URL the browser or the CLI dials, not the server): `[]` admits nothing.
  */
-export function canCarrySecret(url: string, relaxed = isEgressRelaxed()) {
+export function canCarrySecret(url: string, allowed = egressAllowedHosts()) {
     try {
-        const { protocol, hostname: raw } = new URL(url);
+        const { protocol, hostname } = new URL(url);
         if (protocol === "https:") return true;
         if (protocol !== "http:") return false;
-        // A trailing dot is the DNS root, the same name: `host.docker.internal.` is `host.docker.internal`.
-        const hostname = raw.replace(/\.$/, "");
-        return isLoopback(hostname) || (relaxed && isPrivateHost(hostname));
+        return isLoopback(normalizeHost(hostname)) || isEgressAllowedHost(hostname, allowed);
     } catch {
         return false;
     }

package/src/contracts/runtime/sync.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { MESSAGE_ROLES, type TokenUsage } from "../wire/index";
 import { agentRefSchema, agentSlugSchema, variableDeclarationSchema } from "./grammar";
-import { TRIGGER_OUTCOMES, TRIGGER_SOURCES } from "./triggers";
+import { approvalRequestedEventSchema, TRIGGER_OUTCOMES, TRIGGER_SOURCES } from "./triggers";
 import { DATASET_ERROR_KINDS } from "./datasets";
 
 /*
@@ -141,6 +141,19 @@ export const syncEventSchema = z.discriminatedUnion("type", [
         createdAt: z.iso.datetime(),
         finishedAt: z.iso.datetime().nullable(),
     }),
+    /**
+     * A run on a cc-backed agent parked on approval. cc delivers it to the
+     * published webhooks in the agent's audience; a code agent reacts in
+     * code and sends none.
+     */
+    z.object({
+        type: z.literal("approval.requested"),
+        id: z.uuid(),
+        agentSlug: agentSlugSchema,
+        agentRef: agentRefSchema,
+        payload: approvalRequestedEventSchema,
+        createdAt: z.iso.datetime(),
+    }),
     /** What the server offers console-created agents, sent whole at boot and replacing the previous declaration. */
     z.object({
         type: z.literal("server.declare"),

package/src/contracts/runtime/triggers.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { datasetIdentifierSchema } from "./datasets";
 import {
+    agentRefSchema,
     agentSlugSchema,
     localizedTextSchema,
     mentionedToolSchema,
@@ -152,6 +153,38 @@ export type TriggerAuthResponse = z.infer<typeof triggerAuthResponseSchema>;
 
 /* The server answers a caller firing `POST /agents/:agentSlug/triggers/:name`. */
 
+/** One server tool call a parked run waits on; `POST .../firings/:id/answer` decides it. */
+const triggerApprovalSchema = z.object({
+    toolCallId: z.string(),
+    toolName: z.string(),
+    input: z.unknown(),
+});
+
+/** The host-reaction events a run reports. One so far; the shape is generic. */
+export const HOST_EVENTS = ["approval_requested"] as const;
+
+/**
+ * A run parked on server tools that need the user's approval, as every host
+ * hears of it: the code hook's argument and a webhook's body are this one
+ * object. `agentId` is the slug; `agentRef` is cc's id when cc backs the
+ * agent. `firingId` and `triggerName` are set when a trigger started the run,
+ * which is what a host answering through the firing route needs.
+ */
+export const approvalRequestedEventSchema = z.object({
+    event: z.literal("approval_requested"),
+    agentId: z.string(),
+    agentRef: agentRefSchema.optional(),
+    threadId: z.string(),
+    runId: z.string(),
+    userId: z.string(),
+    firingId: z.uuid().optional(),
+    triggerName: z.string().optional(),
+    /** The hook always gets each call's `input`; a webhook body leaves it out when the whole would be too large for the wire. */
+    approvals: z.array(triggerApprovalSchema.extend({ input: z.unknown().optional() })),
+    occurredAt: z.iso.datetime(),
+});
+export type ApprovalRequestedEvent = z.infer<typeof approvalRequestedEventSchema>;
+
 export const triggerFiringResponseSchema = z.discriminatedUnion("outcome", [
     z.object({
         firingId: z.uuid(),
@@ -165,9 +198,7 @@ export const triggerFiringResponseSchema = z.discriminatedUnion("outcome", [
         outcome: z.literal("awaiting_approval"),
         threadId: z.uuid(),
         runId: z.string(),
-        approvals: z.array(
-            z.object({ toolCallId: z.string(), toolName: z.string(), input: z.unknown() }),
-        ),
+        approvals: z.array(triggerApprovalSchema),
     }),
     z.object({
         firingId: z.uuid(),
@@ -216,6 +247,8 @@ export const triggerFiringRecordSchema = z.object({
     reason: z.string().nullable(),
     /** Set once a run with an output schema completed; null otherwise. */
     output: z.unknown(),
+    /** The calls an `awaiting_approval` firing waits on; filled by the single-firing read, empty in the list and for every other outcome. */
+    approvals: z.array(triggerApprovalSchema),
     createdAt: z.iso.datetime(),
     finishedAt: z.iso.datetime().nullable(),
 });

package/src/scaffold/files.ts

@@ -27,7 +27,7 @@ export type Database = "postgres" | "mssql";
 // sync (scripts/sync-package-versions.ts) restamps it and files.test.ts holds
 // them to that.
 export const DEPENDENCIES = {
-    "@m6d/cortex-server": "~0.5.1",
+    "@m6d/cortex-server": "~0.7.0",
     "@tanstack/ai": "^0.55.0",
     "@tanstack/ai-openai": "^0.22.8",
     hono: "^4.12.3",