@anchrd/intel-contract 0.7.0 → 0.9.0

package/dist/contract/contract.d.ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
 export declare const IntelId: z.ZodString;
 export declare const IsoDateTime: z.ZodISODateTime;
+export declare const UI_LANGUAGES: readonly ["en", "de", "es"];
+export type UiLanguage = (typeof UI_LANGUAGES)[number];
 export declare const ProblemDetails: z.ZodObject<{
     type: z.ZodString;
     status: z.ZodNumber;
@@ -468,6 +470,41 @@ export declare const AgentReference: z.ZodObject<{
     }>;
 }, z.core.$strict>;
 export type AgentReference = z.infer<typeof AgentReference>;
+/**
+ * Which kinds of node each role can actually be given (#255).
+ *
+ * ⚠️ Not every role takes every kind, and the reasons are about what the runtime DOES with a
+ * reference rather than about tidiness:
+ *
+ *   `memory` is a folder because the agent WRITES there — `agent_remember` creates a note inside
+ *   it. A single document as memory would mean the agent overwrites the document it was given.
+ *
+ *   `semantic-context` is a folder because it is a search SPACE, searched per folder by
+ *   `loop/scoped-search`. A single document is not a narrower search space; reading it whole is a
+ *   different behaviour, and one that gets named before it is introduced, not slipped in.
+ *
+ *   `system-message` reads single nodes already and takes a document or a table as well as a
+ *   folder. A document is the natural case — a skill somebody wrote as ordinary text — and a table
+ *   is the same read: the runtime asks intel for the node and prepends its content, which for a
+ *   table is its CSV.
+ *
+ * ⚠️ `folder` stays on `system-message` although a folder carries no content of its own. Every
+ * definition written before #255 could only name folders, and taking the combination away here
+ * would refuse the next save of an agent that has been working for months — "existing definitions
+ * stay valid" is not only about reading them.
+ *
+ * ⚠️ This is the ONE place the rule lives. The screen offers what it says and the write path
+ * refuses what it forbids; a surface that made its own list would eventually disagree with the
+ * other, and the one that matters is whichever runs last.
+ */
+export declare const AgentReferenceKinds: {
+    readonly "system-message": readonly ["folder", "document", "table"];
+    readonly "semantic-context": readonly ["folder"];
+    readonly memory: readonly ["folder"];
+};
+export declare function agentReferenceAccepts(role: AgentReferenceRole, kind: NodeKind): boolean;
+/** The roles a node of this kind may be given — the same rule, read from the other side. */
+export declare function agentReferenceRolesFor(kind: NodeKind): AgentReferenceRole[];
 export declare const AgentScheduleTarget: z.ZodObject<{
     kind: z.ZodEnum<{
         document: "document";
@@ -478,6 +515,7 @@ export declare const AgentScheduleTarget: z.ZodObject<{
 export type AgentScheduleTarget = z.infer<typeof AgentScheduleTarget>;
 export declare const AgentSchedule: z.ZodObject<{
     cron: z.ZodString;
+    timezone: z.ZodDefault<z.ZodString>;
     target: z.ZodObject<{
         kind: z.ZodEnum<{
             document: "document";
@@ -553,6 +591,7 @@ export declare const AgentDefinition: z.ZodObject<{
     }, z.core.$strict>>>;
     schedules: z.ZodDefault<z.ZodArray<z.ZodObject<{
         cron: z.ZodString;
+        timezone: z.ZodDefault<z.ZodString>;
         target: z.ZodObject<{
             kind: z.ZodEnum<{
                 document: "document";
@@ -595,6 +634,7 @@ export declare const AgentDefinitionInput: z.ZodObject<{
     }, z.core.$strict>>>;
     schedules: z.ZodDefault<z.ZodArray<z.ZodObject<{
         cron: z.ZodString;
+        timezone: z.ZodDefault<z.ZodString>;
         target: z.ZodObject<{
             kind: z.ZodEnum<{
                 document: "document";
@@ -629,6 +669,7 @@ export declare const SaveAgentDefinitionInput: z.ZodObject<{
         }, z.core.$strict>>>;
         schedules: z.ZodDefault<z.ZodArray<z.ZodObject<{
             cron: z.ZodString;
+            timezone: z.ZodDefault<z.ZodString>;
             target: z.ZodObject<{
                 kind: z.ZodEnum<{
                     document: "document";
@@ -667,6 +708,116 @@ export declare const RunAgentNowInput: z.ZodObject<{
     }, z.core.$strict>;
 }, z.core.$strict>;
 export type RunAgentNowInput = z.infer<typeof RunAgentNowInput>;
+/**
+ * What one agent has actually cost, read out of Cloudflare's AI Gateway log (#251).
+ *
+ * ⚠️ Intel computes none of this from tokens and a price table. The gateway publishes the billed
+ * figure per call, and that figure is the debit from the Cloudflare balance 1:1 — Cloudflare takes
+ * its 5 % when the balance is loaded and passes inference through unchanged (measured 2026-08-07).
+ * A second, self-maintained answer beside it would be wrong on the day the two disagreed, and the
+ * wrong one would be the one on screen.
+ *
+ * ⚠️ `status` travels with the numbers and may never be dropped. `runs: []` means "cost nothing"
+ * only when `status` is `read`; under `not_configured` or `unreadable` it means "not known", and a
+ * screen that renders the two alike reports an outage as a saving.
+ */
+export declare const AgentCostStatus: z.ZodEnum<{
+    read: "read";
+    not_configured: "not_configured";
+    unreadable: "unreadable";
+}>;
+export type AgentCostStatus = z.infer<typeof AgentCostStatus>;
+export declare const AgentRunCost: z.ZodObject<{
+    runId: z.ZodString;
+    cost: z.ZodNumber;
+    calls: z.ZodNumber;
+}, z.core.$strict>;
+export type AgentRunCost = z.infer<typeof AgentRunCost>;
+export declare const AgentCostWindow: z.ZodObject<{
+    days: z.ZodNumber;
+    cost: z.ZodNumber;
+    calls: z.ZodNumber;
+    models: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type AgentCostWindow = z.infer<typeof AgentCostWindow>;
+export declare const AgentCosts: z.ZodObject<{
+    status: z.ZodEnum<{
+        read: "read";
+        not_configured: "not_configured";
+        unreadable: "unreadable";
+    }>;
+    currency: z.ZodLiteral<"USD">;
+    runs: z.ZodArray<z.ZodObject<{
+        runId: z.ZodString;
+        cost: z.ZodNumber;
+        calls: z.ZodNumber;
+    }, z.core.$strict>>;
+    windows: z.ZodArray<z.ZodObject<{
+        days: z.ZodNumber;
+        cost: z.ZodNumber;
+        calls: z.ZodNumber;
+        models: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    partial: z.ZodBoolean;
+}, z.core.$strict>;
+export type AgentCosts = z.infer<typeof AgentCosts>;
+/**
+ * What the models on offer cost and how much they hold (#257).
+ *
+ * ⚠️ `source` is per ENTRY and not per response, and that is not over-engineering. Cloudflare
+ * publishes figures for the models it serves itself and none at all for the Anthropic models it
+ * resells through Unified Billing — so a perfectly healthy read still leaves half the list on a
+ * written-out table, and one flag for the whole answer would call either the read stale or the
+ * table live.
+ */
+export declare const ModelPrice: z.ZodObject<{
+    inputPerMillion: z.ZodNumber;
+    outputPerMillion: z.ZodNumber;
+}, z.core.$strict>;
+export type ModelPrice = z.infer<typeof ModelPrice>;
+export declare const ModelCatalogEntry: z.ZodObject<{
+    provider: z.ZodEnum<{
+        "workers-ai": "workers-ai";
+        anthropic: "anthropic";
+    }>;
+    model: z.ZodString;
+    name: z.ZodString;
+    contextTokens: z.ZodNullable<z.ZodNumber>;
+    price: z.ZodNullable<z.ZodObject<{
+        inputPerMillion: z.ZodNumber;
+        outputPerMillion: z.ZodNumber;
+    }, z.core.$strict>>;
+    source: z.ZodEnum<{
+        cloudflare: "cloudflare";
+        builtin: "builtin";
+    }>;
+}, z.core.$strict>;
+export type ModelCatalogEntry = z.infer<typeof ModelCatalogEntry>;
+export declare const ModelCatalog: z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        provider: z.ZodEnum<{
+            "workers-ai": "workers-ai";
+            anthropic: "anthropic";
+        }>;
+        model: z.ZodString;
+        name: z.ZodString;
+        contextTokens: z.ZodNullable<z.ZodNumber>;
+        price: z.ZodNullable<z.ZodObject<{
+            inputPerMillion: z.ZodNumber;
+            outputPerMillion: z.ZodNumber;
+        }, z.core.$strict>>;
+        source: z.ZodEnum<{
+            cloudflare: "cloudflare";
+            builtin: "builtin";
+        }>;
+    }, z.core.$strict>>;
+    liveStatus: z.ZodEnum<{
+        read: "read";
+        not_configured: "not_configured";
+        unreadable: "unreadable";
+    }>;
+}, z.core.$strict>;
+export type ModelCatalog = z.infer<typeof ModelCatalog>;
 export declare const ListAgentsInput: z.ZodObject<{
     parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     includeArchived: z.ZodDefault<z.ZodBoolean>;
@@ -690,6 +841,7 @@ export declare const CreateAgentInput: z.ZodObject<{
         }, z.core.$strict>>>;
         schedules: z.ZodDefault<z.ZodArray<z.ZodObject<{
             cron: z.ZodString;
+            timezone: z.ZodDefault<z.ZodString>;
             target: z.ZodObject<{
                 kind: z.ZodEnum<{
                     document: "document";
@@ -759,6 +911,7 @@ export declare const NodeAgent: z.ZodObject<{
         }, z.core.$strict>>>;
         schedules: z.ZodDefault<z.ZodArray<z.ZodObject<{
             cron: z.ZodString;
+            timezone: z.ZodDefault<z.ZodString>;
             target: z.ZodObject<{
                 kind: z.ZodEnum<{
                     document: "document";
@@ -842,6 +995,7 @@ export declare const CreatedAgent: z.ZodObject<{
         }, z.core.$strict>>>;
         schedules: z.ZodDefault<z.ZodArray<z.ZodObject<{
             cron: z.ZodString;
+            timezone: z.ZodDefault<z.ZodString>;
             target: z.ZodObject<{
                 kind: z.ZodEnum<{
                     document: "document";

package/dist/contract/contract.js

@@ -1,6 +1,14 @@
 import { z } from "zod";
 export const IntelId = z.string().min(1).max(128);
 export const IsoDateTime = z.iso.datetime({ offset: true });
+// The languages whose UI catalog ships inside intel-ui. They live here rather than only in the UI
+// because `intel build` has to know them: a built-in language may be chosen as `ui.defaultLanguage`
+// without the customer listing a copy under `ui.languages` that would rot at every UI update.
+//
+// ⚠️ The list is a claim about the contents of packages/ui/src/i18n and cannot be checked here.
+// `i18n.unit.ts` compares it against the catalogs actually built in; a language listed here without
+// a file gives a red run there instead of a UI that starts on a catalog which does not exist.
+export const UI_LANGUAGES = ["en", "de", "es"];
 export const ProblemDetails = z.strictObject({
     type: z.string(),
     status: z.number().int().min(400).max(599),
@@ -273,6 +281,45 @@ export const AgentMediaType = "application/vnd.anchrd.agent+json";
 //   memory            write target — ordinary Knowledge, versioned and readable like everything else
 export const AgentReferenceRole = z.enum(["system-message", "semantic-context", "memory"]);
 export const AgentReference = z.strictObject({ nodeId: IntelId, role: AgentReferenceRole });
+/**
+ * Which kinds of node each role can actually be given (#255).
+ *
+ * ⚠️ Not every role takes every kind, and the reasons are about what the runtime DOES with a
+ * reference rather than about tidiness:
+ *
+ *   `memory` is a folder because the agent WRITES there — `agent_remember` creates a note inside
+ *   it. A single document as memory would mean the agent overwrites the document it was given.
+ *
+ *   `semantic-context` is a folder because it is a search SPACE, searched per folder by
+ *   `loop/scoped-search`. A single document is not a narrower search space; reading it whole is a
+ *   different behaviour, and one that gets named before it is introduced, not slipped in.
+ *
+ *   `system-message` reads single nodes already and takes a document or a table as well as a
+ *   folder. A document is the natural case — a skill somebody wrote as ordinary text — and a table
+ *   is the same read: the runtime asks intel for the node and prepends its content, which for a
+ *   table is its CSV.
+ *
+ * ⚠️ `folder` stays on `system-message` although a folder carries no content of its own. Every
+ * definition written before #255 could only name folders, and taking the combination away here
+ * would refuse the next save of an agent that has been working for months — "existing definitions
+ * stay valid" is not only about reading them.
+ *
+ * ⚠️ This is the ONE place the rule lives. The screen offers what it says and the write path
+ * refuses what it forbids; a surface that made its own list would eventually disagree with the
+ * other, and the one that matters is whichever runs last.
+ */
+export const AgentReferenceKinds = {
+    "system-message": ["folder", "document", "table"],
+    "semantic-context": ["folder"],
+    memory: ["folder"],
+};
+export function agentReferenceAccepts(role, kind) {
+    return AgentReferenceKinds[role].includes(kind);
+}
+/** The roles a node of this kind may be given — the same rule, read from the other side. */
+export function agentReferenceRolesFor(kind) {
+    return AgentReferenceRole.options.filter((role) => agentReferenceAccepts(role, kind));
+}
 // A `document` target means the content of that document is the instruction — a "skill" somebody
 // wrote as ordinary text; a `flow` target means a run is started through Intel MCP and worked step
 // by step. Both are references, so nothing in here goes stale (ADR-0005 §4).
@@ -283,8 +330,42 @@ export const AgentScheduleTarget = z.strictObject({
     kind: z.enum(["document", "flow"]),
     id: IntelId,
 });
+/**
+ * ⚠️ `timezone` is what the cron expression is READ IN, and it belongs to the schedule rather than
+ * to whoever is looking at it (#228). "Every morning at eight" means eight o'clock where the person
+ * who wrote it sits — in Berlin that is 06:00 UTC in summer and 07:00 in winter, and a field that
+ * does not carry the zone cannot express that difference. A UTC cron is an hour wrong twice a year
+ * and nobody sees why.
+ *
+ * The UI suggests the reader's own zone when a schedule is created, but it is not a per-user
+ * setting: an agent's schedule would otherwise move whenever its owner travelled, and it would mean
+ * different times to two people reading the same definition. What is stored is the answer.
+ *
+ * ⚠️ The default is `"UTC"`, and it is load-bearing rather than tidy: every definition written
+ * before this field parses to it and therefore keeps firing exactly when it did. A default of
+ * "whatever the writer's browser says" would silently move every existing schedule at the next save.
+ *
+ * The name is validated against this runtime's own tz database rather than a pattern. A regular
+ * expression would accept `Mars/Olympus`, and the failure would surface inside a Durable Object
+ * alarm — the place where nobody is watching.
+ */
+const IanaTimezone = z
+    .string()
+    .trim()
+    .min(1)
+    .max(64)
+    .refine((zone) => {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: zone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, { message: "must be an IANA timezone name this runtime knows, for example Europe/Berlin" });
 export const AgentSchedule = z.strictObject({
     cron: z.string().trim().min(1).max(120),
+    timezone: IanaTimezone.default("UTC"),
     target: AgentScheduleTarget,
 });
 export const AgentModel = z.strictObject({
@@ -400,6 +481,68 @@ export const RunAgentNowInput = z.strictObject({
     nodeId: IntelId,
     target: AgentScheduleTarget,
 });
+/**
+ * What one agent has actually cost, read out of Cloudflare's AI Gateway log (#251).
+ *
+ * ⚠️ Intel computes none of this from tokens and a price table. The gateway publishes the billed
+ * figure per call, and that figure is the debit from the Cloudflare balance 1:1 — Cloudflare takes
+ * its 5 % when the balance is loaded and passes inference through unchanged (measured 2026-08-07).
+ * A second, self-maintained answer beside it would be wrong on the day the two disagreed, and the
+ * wrong one would be the one on screen.
+ *
+ * ⚠️ `status` travels with the numbers and may never be dropped. `runs: []` means "cost nothing"
+ * only when `status` is `read`; under `not_configured` or `unreadable` it means "not known", and a
+ * screen that renders the two alike reports an outage as a saving.
+ */
+export const AgentCostStatus = z.enum(["read", "not_configured", "unreadable"]);
+export const AgentRunCost = z.strictObject({
+    runId: z.string(),
+    cost: z.number(),
+    calls: z.number(),
+});
+export const AgentCostWindow = z.strictObject({
+    days: z.number(),
+    cost: z.number(),
+    calls: z.number(),
+    // Which models produced this figure. It is here so the model select can say the number is about
+    // the PAST (#257) — a reader who switched model would otherwise take it for a forecast.
+    models: z.array(z.string()),
+});
+export const AgentCosts = z.strictObject({
+    status: AgentCostStatus,
+    currency: z.literal("USD"),
+    runs: z.array(AgentRunCost),
+    windows: z.array(AgentCostWindow),
+    // The read hit its page limit, so every total above is a floor rather than a total.
+    partial: z.boolean(),
+});
+/**
+ * What the models on offer cost and how much they hold (#257).
+ *
+ * ⚠️ `source` is per ENTRY and not per response, and that is not over-engineering. Cloudflare
+ * publishes figures for the models it serves itself and none at all for the Anthropic models it
+ * resells through Unified Billing — so a perfectly healthy read still leaves half the list on a
+ * written-out table, and one flag for the whole answer would call either the read stale or the
+ * table live.
+ */
+export const ModelPrice = z.strictObject({
+    inputPerMillion: z.number(),
+    outputPerMillion: z.number(),
+});
+export const ModelCatalogEntry = z.strictObject({
+    provider: z.enum(["workers-ai", "anthropic"]),
+    model: z.string(),
+    name: z.string(),
+    contextTokens: z.number().nullable(),
+    // `null` where this installation has no figure. Never zero and never a guess — an invented number
+    // is a false statement about money.
+    price: ModelPrice.nullable(),
+    source: z.enum(["cloudflare", "builtin"]),
+});
+export const ModelCatalog = z.strictObject({
+    entries: z.array(ModelCatalogEntry),
+    liveStatus: z.enum(["read", "not_configured", "unreadable"]),
+});
 // ⚠️ Three states, not two, and the same three the flow list makes: omitted is the whole tree,
 // `null` is the root level, an ID is that folder. "Which agents may I use" is a question about the
 // tree rather than about one folder, so the useful answer has to be reachable without knowing where

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-contract",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {