@anchrd/intel-contract 0.8.0 → 0.9.0

package/dist/contract/contract.d.ts

@@ -470,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";
@@ -673,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>;

package/dist/contract/contract.js

@@ -281,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).
@@ -442,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.8.0",
+  "version": "0.9.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {