@unoverse-platform/studio 0.1.115 → 0.1.117

package/vendor/base/src/manifests/runtime/usage.ts

@@ -15,8 +15,8 @@
  * Sniffing those three is a wire-format rule, not a per-node rule — no manifest changes.
  *
  * A run may hold SEVERAL model calls (the tool loop's turns), each with its own usage
- * block; the collector SUMS numeric fields across them, which is what "this execution
- * cost N tokens" means. Fire-and-forget on save, same contract as the MCP trace:
+ * block; the collector SUMS numeric fields across what it saw since its last save, and the
+ * rows for one execution add up to what it cost. Fire-and-forget on save, same contract as the MCP trace:
  * observability must never slow a run or fail it.
  */
 import type { ComposedNode } from "../compose.js";
@@ -38,7 +38,12 @@ export interface UsageCollector {
    * the length. A vendor that reports running totals (GPT-Live) would otherwise be summed.
    */
   set(field: string, value: number): void;
-  /** Post the summed usage to the engine. No usage seen, or no execution scope → no-op. */
+  /**
+   * Post what was seen SINCE THE LAST SAVE to the engine, then start again from nothing. Called
+   * after each turn of a tool loop, so spend is on record while the run is still going: a budget
+   * read mid-run (an Agent's, AGENTS.md § 9) saw nothing until the loop settled. Nothing new, or no
+   * execution scope → no-op.
+   */
   save(): void;
 }
 
@@ -61,7 +66,7 @@ function addInto(totals: Record<string, any>, block: Record<string, unknown>): v
 }
 
 export function makeUsageCollector(node: ComposedNode, ctx: RunContext): UsageCollector {
-  const totals: Record<string, number | Record<string, number>> = {};
+  let totals: Record<string, number | Record<string, number>> = {};
   let seen = false;
   let model: string | undefined;
 
@@ -80,6 +85,9 @@ export function makeUsageCollector(node: ComposedNode, ctx: RunContext): UsageCo
     },
     save() {
       if (!seen) return;
+      const spent = totals;
+      totals = {};
+      seen = false;
       const { workflowId, executionId, nodeId } = ctx.scope ?? {};
       // Node-test / headless: no execution to attach to (same rule as the MCP trace).
       if (!workflowId || !executionId || !nodeId) return;
@@ -89,7 +97,7 @@ export function makeUsageCollector(node: ComposedNode, ctx: RunContext): UsageCo
         nodeId,
         nodeType: node.type,
         model: model ?? (ctx.config as any)?.model ?? "unknown",
-        usage: totals,
+        usage: spent,
         timestamp: new Date().toISOString(),
       });
     },

package/vendor/base/src/platform/agentBudget.ts

@@ -0,0 +1,65 @@
+/**
+ * AN AGENT'S BUDGET (docs/architecture/signal/AGENTS.md § 9, § 9a; UNO-222).
+ *
+ * Counted, not trusted: what an Agent spent is the platform's own usage rows (`token_usage`) for
+ * everything run as the Agent (its own thinking and every task it called), priced by the one table
+ * (`tokenCost.ts`). Checked BEFORE every model call and every task, never after:
+ *
+ *   under 80% of a limit   go on
+ *   80% or more            go on, its owner is told once
+ *   100%                   start nothing new
+ *
+ * Pure: the rows and the limits come in.
+ */
+import { parseTokenUsage, calculateTokenCost } from "./tokenCost.js";
+
+/** "20 USD", "20", "$20" → 20. Null when it is not an amount in US dollars. */
+export function dollars(amount: string | undefined): number | null {
+  if (!amount) return null;
+  const m = /^\s*\$?\s*(\d+(?:\.\d+)?)\s*(USD)?\s*$/i.exec(amount);
+  return m ? Number(m[1]) : null;
+}
+
+/** One usage row as the platform keeps it. */
+export interface UsageRow {
+  model: string | null;
+  usage: unknown;
+}
+
+/** What these rows cost, in US dollars. */
+export function spent(rows: UsageRow[]): number {
+  let total = 0;
+  for (const row of rows) {
+    if (!row.model) continue;
+    total += Number(calculateTokenCost(row.model, parseTokenUsage(row.model, row.usage)));
+  }
+  return Math.round(total * 10000) / 10000;
+}
+
+export interface BudgetLimits {
+  perDay?: string;
+  perRun?: string;
+}
+
+export type BudgetCheck =
+  | { go: true; near?: "day" | "run"; message?: string }
+  | { go: false; limit: "day" | "run" | "none"; message: string };
+
+/** May the Agent start one more model call or task? */
+export function checkBudget(limits: BudgetLimits, used: { today: number; run: number }): BudgetCheck {
+  const day = dollars(limits.perDay);
+  if (day === null) return { go: false, limit: "none", message: "No daily budget: an Agent with no budget.perDay never runs" };
+  const run = dollars(limits.perRun);
+  if (used.today >= day) return { go: false, limit: "day", message: `Today's budget is spent: $${used.today.toFixed(2)} of $${day.toFixed(2)}. Carries on tomorrow.` };
+  if (run !== null && used.run >= run) return { go: false, limit: "run", message: `This run's budget is spent: $${used.run.toFixed(2)} of $${run.toFixed(2)}.` };
+  if (used.today >= day * 0.8) return { go: true, near: "day", message: `$${used.today.toFixed(2)} of today's $${day.toFixed(2)} spent` };
+  if (run !== null && used.run >= run * 0.8) return { go: true, near: "run", message: `$${used.run.toFixed(2)} of this run's $${run.toFixed(2)} spent` };
+  return { go: true };
+}
+
+/** Midnight today in the environment's own time zone, where an Agent's day starts. */
+export function startOfToday(now: Date = new Date()): Date {
+  const d = new Date(now);
+  d.setHours(0, 0, 0, 0);
+  return d;
+}

package/vendor/base/src/platform/agentCalendar.ts

@@ -0,0 +1,87 @@
+/**
+ * AN AGENT'S DAY IS ITS CALENDAR (docs/architecture/signal/AGENTS.md § 5; UNO-207).
+ *
+ * A person drops slots into the Agent's calendar: the title names the slot, the description is
+ * what to do. Every `checkIn` the calendar is read; a slot that started since the last look, or is
+ * under way now, wakes the Agent, once, with the slot as its instruction: its work is a task from the
+ * moment it is on the calendar, never something to wait for. These are the rules; the engine's check-in
+ * (`engine/src/agentKeys/checkIn.ts`) reads the calendar and wakes it.
+ *
+ * Only people in its org give it work (§ 7b): a slot made by the mailbox itself, or by someone at
+ * the same company domain. A public mail domain (gmail.com and the like) is nobody's company, so
+ * there only the mailbox's own slots count. An outside invitation is never an instruction.
+ *
+ * A slot names the Agent (owner, 2026-10-10: "start with Bob:"): its title begins with the Agent's
+ * name and a colon, "Bob: Morning sweep". Every other event in the calendar is a person's own
+ * meeting and never wakes it, which matters while it reads a person's calendar rather than its own.
+ */
+
+/** The fields of an event these rules read. */
+export interface SlotEvent {
+  id: string;
+  title: string;
+  description: string;
+  start: string;
+  /** When it ends; empty for none. A slot under way still wakes an Agent that has not worked it. */
+  end?: string | null;
+  organizer: { address: string } | null;
+  creator: { address: string } | null;
+}
+
+/** How often its calendar is read when its file says nothing. */
+export const DEFAULT_CHECK_IN_MS = 15 * 60_000;
+
+/** "15m", "1h", "30s" → milliseconds; anything else, the default. Never under a minute. */
+export function checkInEvery(checkIn: string | undefined): number {
+  const m = /^\s*(\d+)\s*(s|m|h)\s*$/i.exec(checkIn ?? "");
+  if (!m) return DEFAULT_CHECK_IN_MS;
+  const ms = Number(m[1]) * { s: 1000, m: 60_000, h: 3_600_000 }[m[2].toLowerCase() as "s" | "m" | "h"];
+  return Math.max(ms, 60_000);
+}
+
+const PUBLIC_DOMAINS = new Set(["gmail.com", "googlemail.com", "outlook.com", "hotmail.com", "live.com", "msn.com", "yahoo.com", "icloud.com", "me.com", "proton.me", "protonmail.com", "aol.com"]);
+const domainOf = (address: string) => address.slice(address.lastIndexOf("@") + 1).toLowerCase();
+
+/** Was this slot made by someone in the Agent's org? */
+export function fromOrg(event: SlotEvent, mailbox: string): boolean {
+  const maker = (event.creator ?? event.organizer)?.address?.toLowerCase();
+  const own = mailbox.trim().toLowerCase();
+  if (!maker) return false;
+  if (maker === own) return true;
+  const domain = domainOf(own);
+  return !PUBLIC_DOMAINS.has(domain) && domainOf(maker) === domain;
+}
+
+/** "Bob: Morning sweep" for Bob → "Morning sweep"; null when the slot is not addressed to it. */
+export function addressedTo(title: string, agentName: string): string | null {
+  const name = agentName.trim().toLowerCase();
+  const t = title.trim();
+  if (!name || t.slice(0, name.length + 1).toLowerCase() !== `${name}:`) return null;
+  return t.slice(name.length + 1).trim();
+}
+
+/** The slots to work now, earliest first: started after `since` and by `now`, or started earlier
+ *  and still under way. Whether one was already worked is the run record's (`slotKey`). */
+export function slotsDue<T extends SlotEvent>(events: T[], since: Date, now: Date): T[] {
+  return events
+    .filter((e) => {
+      const at = Date.parse(e.start);
+      if (at > now.getTime()) return false;
+      if (at > since.getTime()) return true;
+      const end = e.end ? Date.parse(e.end) : NaN;
+      return end > now.getTime();
+    })
+    .sort((a, b) => Date.parse(a.start) - Date.parse(b.start));
+}
+
+/** One slot, once: a recurring slot's occurrences differ by start. What its run is recorded as. */
+export function slotKey(event: SlotEvent): string {
+  return `calendar:${event.id}@${event.start}`;
+}
+
+/** What the Agent is told when a slot starts. */
+export function slotInstruction(event: SlotEvent, agentName: string): string {
+  const what = event.description.trim();
+  const title = addressedTo(event.title, agentName) || event.title.trim() || "(untitled)";
+  return `Your calendar: "${title}" has started.${what ? `\n\n${what}` : "\n\nIt has no description: do your job, as your skills say."}`;
+}

package/vendor/base/src/platform/inbound.ts

@@ -0,0 +1,67 @@
+/**
+ * IS THIS MESSAGE GENUINE? (docs/auth-security/INBOUND.md § 2 step 3; UNO-239)
+ *
+ * The verifiers, written here and nowhere else. A node only NAMES its scheme and the field of its
+ * credential holding the secret (`inbound:` in node.yaml); it can never describe its own check, so
+ * no node can switch checking off. Each one fails closed: no secret, no timestamp, a wrong or old
+ * signature, all refused. Compared in constant time over the raw bytes, before anything is parsed.
+ *
+ * A service's one-time address check (Slack's `url_verification`) is answered here too, but only
+ * once the request has passed the same check: an unsigned challenge is refused like anything else.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/** What a verifier decides. `challenge`: the service is checking the address; echo this, do nothing else. */
+export type Verdict = { ok: false; reason: string } | { ok: true; challenge?: string };
+
+/** The schemes a node may name. */
+export const SCHEMES = ["slack"] as const;
+export type Scheme = (typeof SCHEMES)[number];
+
+/** Older than this, or this far in the future, and a message is a replay (Slack's own window). */
+export const MAX_SKEW_SECONDS = 300;
+
+function same(a: string, b: string): boolean {
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+/**
+ * SLACK (docs.slack.dev, "Verifying requests from Slack"): `X-Slack-Signature` is `v0=` and the hex
+ * HMAC-SHA256, keyed by the app's signing secret, of `v0:<X-Slack-Request-Timestamp>:<raw body>`.
+ */
+function slack(headers: Headers, raw: string, secret: string, nowSeconds: number): Verdict {
+  const ts = headers.get("x-slack-request-timestamp") ?? "";
+  const signature = headers.get("x-slack-signature") ?? "";
+  if (!/^\d+$/.test(ts) || !signature) return { ok: false, reason: "unsigned" };
+  if (Math.abs(nowSeconds - Number(ts)) > MAX_SKEW_SECONDS) return { ok: false, reason: "too old" };
+  const expected = `v0=${createHmac("sha256", secret).update(`v0:${ts}:${raw}`).digest("hex")}`;
+  if (!same(signature, expected)) return { ok: false, reason: "wrong signature" };
+  try {
+    const body = JSON.parse(raw);
+    if (body?.type === "url_verification" && typeof body.challenge === "string") return { ok: true, challenge: body.challenge };
+  } catch {
+    /* a signed body that is not JSON is still genuine; what it says is the next step's to read */
+  }
+  return { ok: true };
+}
+
+const VERIFIERS: Record<Scheme, (headers: Headers, raw: string, secret: string, nowSeconds: number) => Verdict> = { slack };
+
+/**
+ * Check one message with the scheme its node names. `secrets` holds the current secret and, while
+ * one is being replaced, the next: either passing is genuine. No secret at all is a refusal.
+ */
+export function verifyInbound(scheme: string, headers: Headers, raw: string, secrets: Array<string | undefined | null>, nowSeconds = Math.floor(Date.now() / 1000)): Verdict {
+  const verify = VERIFIERS[scheme as Scheme];
+  if (!verify) return { ok: false, reason: `no verifier for "${scheme}"` };
+  const usable = secrets.filter((s): s is string => typeof s === "string" && s.length > 0);
+  if (!usable.length) return { ok: false, reason: "no secret" };
+  let last: Verdict = { ok: false, reason: "no secret" };
+  for (const secret of usable) {
+    last = verify(headers, raw, secret, nowSeconds);
+    if (last.ok) return last;
+  }
+  return last;
+}

package/vendor/base/src/platform/taskChanged.ts

@@ -0,0 +1,25 @@
+/**
+ * "A TASK CHANGED" (docs/mcp/MCP_TASKS.md § 5a, S3; step 6). Whatever writes a task's row says
+ * so here, once, after the write: the engine when a run starts and ends, the server when a step
+ * is saved or a node starts or stops asking. It lives in base because both write rows, in one
+ * process; a client following that task (`notifications/tasks`, server/taskListen.ts) is sent the
+ * whole task again. Nothing else lives here.
+ */
+const listeners = new Set<(taskId: string) => void>();
+
+/** Listen for changed tasks. Returns the way to stop listening. */
+export function onTaskChanged(listener: (taskId: string) => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** Say a task's row changed. A listener that fails never stops the others. */
+export function taskChanged(taskId: string): void {
+  for (const listener of listeners) {
+    try {
+      listener(taskId);
+    } catch {
+      /* one entry's failure is its own */
+    }
+  }
+}