@m6d/cortex-cli 0.1.0 → 0.3.0

package/package.json

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

package/src/contracts/credentials/index.ts

@@ -0,0 +1,166 @@
+import { z } from "zod";
+import { isTlsOrLoopback } from "../egress/url";
+
+export { isTlsOrLoopback };
+
+/*
+ * A credential is a value Cortex presents to an upstream: one it holds
+ * (`static`) or one it acquires (`oauth2-client-credentials`, RFC 6749 §4.4).
+ * The definition is the same on both sides; the Control Center stores it,
+ * a code config declares it, and each side resolves it to a bearer through
+ * the helper and cache below with its own egress-guarded fetch.
+ */
+
+export const CREDENTIAL_KINDS = ["static", "oauth2-client-credentials"] as const;
+export type CredentialKind = (typeof CREDENTIAL_KINDS)[number];
+
+export const credentialDefinitionSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("static"),
+        value: z.string().min(1),
+    }),
+    z.object({
+        kind: z.literal("oauth2-client-credentials"),
+        /** The token endpoint; a client secret travels only over TLS, or to loopback. */
+        tokenUrl: z.url().refine(isTlsOrLoopback, "token URL must be https, or http to loopback"),
+        clientId: z.string().min(1),
+        clientSecret: z.string().min(1),
+        scope: z.string().min(1).optional(),
+    }),
+]);
+export type CredentialDefinition = z.infer<typeof credentialDefinitionSchema>;
+export type OAuth2ClientCredentials = Extract<
+    CredentialDefinition,
+    { kind: "oauth2-client-credentials" }
+>;
+
+/** One POST to the token endpoint through the caller's guarded fetch; `null` when the transport failed. */
+export type TokenPost = (
+    url: string,
+    init: { headers: Record<string, string>; body: string },
+) => Promise<{ status: number; body: string } | null>;
+
+/** A bearer and when it stops being one; `null` when the issuer did not say. */
+export type AcquiredToken = { token: string; expiresAt: number | null };
+
+export type AcquireResult =
+    | { ok: true; value: AcquiredToken }
+    | { ok: false; error: "token_request_failed" | "token_rejected" | "token_response_invalid" };
+
+const tokenResponseSchema = z.object({
+    access_token: z.string().min(1),
+    token_type: z.string().optional(),
+    // Some issuers (Azure AD v1 among them) send the lifetime as a string.
+    expires_in: z
+        .union([z.number(), z.string().regex(/^\d+$/).transform(Number)])
+        .pipe(z.number().nonnegative())
+        .optional(),
+});
+
+/**
+ * The client credentials grant: a form-encoded POST with the client
+ * authenticated by `client_secret_basic` (RFC 6749 §2.3.1, each half
+ * form-encoded before base64). The endpoint's body never leaves this
+ * function: a failure is one of three literals, since the body may echo
+ * the client secret or carry the issuer's own error detail.
+ */
+export async function acquireOAuth2ClientCredentials(
+    definition: OAuth2ClientCredentials,
+    post: TokenPost,
+) {
+    const basic = Buffer.from(
+        `${encodeURIComponent(definition.clientId)}:${encodeURIComponent(definition.clientSecret)}`,
+    ).toString("base64");
+    const answer = await post(definition.tokenUrl, {
+        headers: {
+            Authorization: `Basic ${basic}`,
+            "Content-Type": "application/x-www-form-urlencoded",
+            Accept: "application/json",
+        },
+        body: new URLSearchParams({
+            grant_type: "client_credentials",
+            ...(definition.scope ? { scope: definition.scope } : {}),
+        }).toString(),
+    });
+    if (!answer) return { ok: false, error: "token_request_failed" } satisfies AcquireResult;
+    if (answer.status < 200 || answer.status >= 300) {
+        return { ok: false, error: "token_rejected" } satisfies AcquireResult;
+    }
+    let parsed: z.ZodSafeParseResult<z.infer<typeof tokenResponseSchema>>;
+    try {
+        parsed = tokenResponseSchema.safeParse(JSON.parse(answer.body));
+    } catch {
+        return { ok: false, error: "token_response_invalid" } satisfies AcquireResult;
+    }
+    if (!parsed.success || (parsed.data.token_type ?? "bearer").toLowerCase() !== "bearer") {
+        return { ok: false, error: "token_response_invalid" } satisfies AcquireResult;
+    }
+    const issuedAt = Date.now();
+    return {
+        ok: true as const,
+        value: {
+            token: parsed.data.access_token,
+            expiresAt:
+                parsed.data.expires_in === undefined
+                    ? null
+                    : issuedAt + parsed.data.expires_in * 1000,
+        },
+    } satisfies AcquireResult;
+}
+
+/** A token is not reused inside this margin of its expiry: the call it is presented on still has to complete. */
+const EXPIRY_MARGIN_MS = 30_000;
+
+/** Equal definitions share one key; a rotated secret is another definition and another token. Kept in memory only, like the definitions themselves. */
+function keyOf(definition: CredentialDefinition) {
+    return JSON.stringify(definition);
+}
+
+/**
+ * Acquired tokens by definition, reused until their expiry margin. Concurrent
+ * acquisitions of one definition share a single request; a token the issuer
+ * gave no expiry for is answered but not kept, since nothing says when it
+ * stops working. `invalidate` is for the caller that saw a 401: the next
+ * resolve acquires again. Pure, so the console's client bundle may import
+ * the schemas beside it.
+ */
+export function createCredentialCache(now: () => number = Date.now) {
+    const tokens = new Map<string, AcquiredToken>();
+    const inFlight = new Map<string, Promise<AcquireResult>>();
+
+    return {
+        async get(definition: CredentialDefinition, acquire: () => Promise<AcquireResult>) {
+            const key = keyOf(definition);
+            const cached = tokens.get(key);
+            if (
+                cached &&
+                cached.expiresAt !== null &&
+                cached.expiresAt - EXPIRY_MARGIN_MS > now()
+            ) {
+                return { ok: true, value: cached } satisfies AcquireResult;
+            }
+            tokens.delete(key);
+            const pending = inFlight.get(key);
+            if (pending) return pending;
+            const acquiring = acquire()
+                .then((result) => {
+                    if (
+                        result.ok &&
+                        result.value.expiresAt !== null &&
+                        result.value.expiresAt - EXPIRY_MARGIN_MS > now()
+                    ) {
+                        tokens.set(key, result.value);
+                    }
+                    return result;
+                })
+                .finally(() => inFlight.delete(key));
+            inFlight.set(key, acquiring);
+            return acquiring;
+        },
+        invalidate(definition: CredentialDefinition) {
+            tokens.delete(keyOf(definition));
+        },
+    };
+}
+
+export type CredentialCache = ReturnType<typeof createCredentialCache>;

package/src/contracts/egress/index.ts

@@ -63,22 +63,7 @@ export function isBlockedAddress(address: string) {
     return isIP(address) === 6 ? isBlockedV6(address) : isBlockedV4(address);
 }
 
-/**
- * Whether a credential may travel to this URL: over TLS anywhere, or over
- * plain http to loopback alone, for a service on the developer's machine.
- */
-export function isTlsOrLoopback(url: string) {
-    try {
-        const { protocol, hostname } = new URL(url);
-        if (protocol === "https:") return true;
-        return (
-            protocol === "http:" &&
-            (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]")
-        );
-    } catch {
-        return false;
-    }
-}
+export { isTlsOrLoopback } from "./url";
 
 export function egressError() {
     const error: NodeJS.ErrnoException = new Error("egress blocked");

package/src/contracts/egress/url.ts

@@ -0,0 +1,17 @@
+/**
+ * Whether a credential may travel to this URL: over TLS anywhere, or over
+ * plain http to loopback alone, for a service on the developer's machine.
+ * Pure, so a browser bundle can judge a URL the same way the server does.
+ */
+export function isTlsOrLoopback(url: string) {
+    try {
+        const { protocol, hostname } = new URL(url);
+        if (protocol === "https:") return true;
+        return (
+            protocol === "http:" &&
+            (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]")
+        );
+    } catch {
+        return false;
+    }
+}

package/src/contracts/runtime/signature.ts

@@ -90,7 +90,7 @@ type Resolve = ReturnType<typeof resolver>;
 
 function literalUnion(values: unknown[]) {
     return values
-        .filter((value) => SCALAR_TYPES.has(typeof value))
+        .filter((value) => value === null || SCALAR_TYPES.has(typeof value))
         .map((value) => JSON.stringify(value))
         .join(" | ");
 }
@@ -125,15 +125,32 @@ function inputType(schema: unknown, resolve: Resolve, depth = 0, indent = 0): st
         const rendered = variants.map((variant) => inputType(variant, resolve, depth, indent));
         return [...new Set(rendered)].join(" | ");
     }
-    if (schema.type === "null") return "null";
-    if (schema.type === "array") {
-        return `${inputType(schema.items, resolve, depth + 1, indent)}[]`;
+    const type = primaryType(schema.type);
+    const nullable = allowsNull(schema.type) ? " | null" : "";
+    if (type === "null") return "null";
+    if (type === "array") {
+        const item = inputType(schema.items, resolve, depth + 1, indent);
+        // A union item type binds looser than `[]`, so it is parenthesized.
+        return `${item.includes(" | ") ? `(${item})` : item}[]${nullable}`;
     }
-    if (schema.type === "object" || isRecord(schema.properties)) {
-        return inputObject(schema, resolve, depth, indent);
+    if (type === "object" || isRecord(schema.properties)) {
+        return inputObject(schema, resolve, depth, indent) + nullable;
     }
-    if (schema.type === "integer") return "number";
-    return SCALAR_TYPES.has(String(schema.type)) ? String(schema.type) : "unknown";
+    if (type === "integer") return `number${nullable}`;
+    return SCALAR_TYPES.has(String(type)) ? `${String(type)}${nullable}` : "unknown";
+}
+
+/** The non-null member of a JSON Schema `type`, so `["string", "null"]` reads as `string`. */
+function primaryType(type: unknown) {
+    if (!Array.isArray(type)) return type;
+    const members: unknown[] = type;
+    return members.find((member) => member !== "null");
+}
+
+function allowsNull(type: unknown) {
+    if (!Array.isArray(type)) return false;
+    const members: unknown[] = type;
+    return members.includes("null");
 }
 
 /** The branches of a union schema, under whichever keyword carries them. */
@@ -143,7 +160,9 @@ function variantsOf(schema: Record<string, unknown>) {
 }
 
 function isObjectSchema(schema: unknown): schema is Record<string, unknown> {
-    return isRecord(schema) && (schema.type === "object" || isRecord(schema.properties));
+    return (
+        isRecord(schema) && (primaryType(schema.type) === "object" || isRecord(schema.properties))
+    );
 }
 
 /**
@@ -176,7 +195,7 @@ function responseObject(schema: Record<string, unknown>, resolve: Resolve, depth
     const fields = orderedPropertyNames(schema).map((name) => {
         const child = responseUnion(properties[name], resolve);
         if (!isRecord(child) || depth >= MAX_DEPTH) return propertyName(name);
-        if (child.type === "array") {
+        if (primaryType(child.type) === "array") {
             const items = responseUnion(child.items, resolve);
             return isObjectSchema(items)
                 ? `${propertyName(name)}[].${responseObject(items, resolve, depth + 1)}`
@@ -200,7 +219,7 @@ export function responseShape(schema: unknown) {
     const resolve = resolver(schema);
     const root = responseUnion(schema, resolve);
     if (!isRecord(root)) return "{}";
-    if (root.type === "array") {
+    if (primaryType(root.type) === "array") {
         const items = responseUnion(root.items, resolve);
         return isObjectSchema(items) ? `[]${responseObject(items, resolve)}` : "[]";
     }

package/src/contracts/runtime/sync.ts

@@ -27,14 +27,25 @@ export const tokenUsageSchema = z.object({
     total: tokenCountSchema,
 }) satisfies z.ZodType<TokenUsage>;
 
+const componentNamesSchema = z.array(z.string().min(1).max(128)).max(1_000);
+
 /**
  * What a server offers every agent the Control Center creates for it, sent
  * whole at boot in `server.declare`: the `{{variables}}` its session loader
- * and request context fill, SDK ones included. Agents in the server's own
- * code never appear here; the Control Center is blind to them.
+ * and request context fill, SDK ones included, and the names of the
+ * components its code declares at server level, which reach those agents
+ * too and which the Control Center therefore refuses on its own components.
+ * Agents in the server's own code never appear here; the Control Center is
+ * blind to them.
  */
 export const serverDeclarationSchema = z.object({
     variables: z.array(variableDeclarationSchema),
+    components: z.object({
+        tool: componentNamesSchema,
+        skill: componentNamesSchema,
+        trigger: componentNamesSchema,
+        dataset_host: componentNamesSchema,
+    }),
 });
 export type ServerDeclaration = z.infer<typeof serverDeclarationSchema>;
 

package/src/contracts/runtime/triggers.ts

@@ -129,7 +129,8 @@ export type TriggerDeclaration = z.infer<typeof triggerDeclarationSchema>;
 /**
  * `POST /api/runtime/agents/:agentSlug/triggers/:name/auth`: a server holding a
  * bearer for a cc trigger asks cc whether it is the trigger's secret. Only the
- * hash travels; a positive answer carries the trigger's credential, if any.
+ * hash travels; a positive answer carries the bearer the run acts with, if
+ * the trigger has a credential, resolved by cc (acquired, for an OAuth2 one).
  */
 export const triggerAuthRequestSchema = z.object({
     secretHash: sha256HexSchema,
@@ -140,6 +141,8 @@ export const triggerAuthResponseSchema = z.discriminatedUnion("ok", [
     z.object({
         ok: z.literal(true),
         credential: z.string().nullable(),
+        /** When the bearer stops working, ISO 8601; null for one that does not expire or has no credential. */
+        expiresAt: z.iso.datetime().nullable(),
         /** The bearer was a single-use test secret, now spent: the server must not cache this verdict. */
         oneShot: z.boolean(),
     }),

package/src/contracts/wire/index.ts

@@ -160,9 +160,10 @@ export type TriggerFiringSummary = {
 };
 
 /**
- * A stored message as it is persisted and served. TanStack AI's `UIMessage`
- * has no metadata field, so cortex owns the envelope: the SDK's parts plus the
- * server-derived metadata the UI renders on settled messages.
+ * A stored message as it is persisted and served: the SDK's parts plus the
+ * server-derived envelope the UIs render, carried in the SDK message's own
+ * `metadata` bag so it travels with the message over the stream and the
+ * transcript alike.
  *
  * `TPart` stays generic so this file keeps its zero dependencies — both
  * sides substitute the SDK's `MessagePart`.
@@ -175,6 +176,15 @@ export type CortexMessage<TPart = unknown> = {
     metadata?: MessageMetadata;
 };
 
+/**
+ * A stored message as the SDK's chat client takes it. The SDK has no `trigger`
+ * role, so a firing's message travels as a user turn; its true role stays on
+ * the envelope (`metadata.trigger`), which is what the UIs render the event from.
+ */
+export function toUiMessage<TPart>(message: CortexMessage<TPart>) {
+    return { ...message, role: message.role === "trigger" ? ("user" as const) : message.role };
+}
+
 /**
  * Key under the AG-UI request's `forwardedProps` carrying the answers to
  * parked client tool calls on a continuation request. The server owns the

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.1.0",
+    "@m6d/cortex-server": "~0.3.0",
     "@tanstack/ai": "^0.55.0",
     "@tanstack/ai-openai": "^0.22.8",
     hono: "^4.12.3",
@@ -167,9 +167,10 @@ ${on === "" ? "" : `${on}\n`}    agents: {
         assistant: defineAgent({
             systemPrompt: "You are a helpful assistant.",
             // Applications that serve datasets for grouped questions (see the
-            // README's "Dataset hosts"): the host applies its own access rules,
-            // the agent only picks which datasets to expose and pin.
-            // datasetHosts: [{ name: "store", url: "https://store.example/api/datasets", pinned: ["orders"] }],
+            // README's "Dataset hosts"): the host applies its own access rules
+            // under the run's token the list below forwards, the agent only
+            // picks which datasets to expose and pin.
+            // datasetHosts: [{ name: "store", url: "https://store.example/api/datasets", credentials: [{ header: "X-End-User-Token", credential: { kind: "run-token" } }], pinned: ["orders"] }],
         }),
     },