@blazingagents/sdk 0.1.0

package/dist/contracts/entities/tasks.js

@@ -0,0 +1,252 @@
+import { Cron } from "croner";
+import { z } from "zod";
+import { paginatedResponseSchema } from "../api.js";
+import { agentIdSchema, sessionIdSchema, taskIdSchema, taskRunIdSchema, tenantIdSchema, turnIdSchema, } from "../ids.js";
+import { MAX_TASK_NAME_LENGTH, MAX_TASK_PROMPT_LENGTH, MIN_TASK_INTERVAL_MS, } from "../limitations.js";
+import { atLeastOneFieldMessage, hasObjectKeys } from "../utils.js";
+import { agentVersionNumberSchema } from "./agents.js";
+import { metadataSchema, userIdSchema } from "./attribution.js";
+import { sessionMessageSchema } from "./sessions.js";
+/**
+ * Schedule kinds — discriminated union, Cohand's kinds with croner-forked
+ * next-run math. `staggerMs` is an optional cron load-spreading offset.
+ */
+export const taskScheduleKindSchema = z.enum(["once", "interval", "cron"]);
+export const taskOnceConfigSchema = z
+    .object({
+    at: z.iso.datetime({ offset: true }),
+})
+    .strict();
+export const taskIntervalConfigSchema = z
+    .object({
+    everyMs: z.number().int().min(MIN_TASK_INTERVAL_MS),
+})
+    .strict();
+const CRON_FIELDS_SEPARATOR = /\s+/;
+const NUMERIC_CRON_EXPRESSION = /^[\d*,/\-\s]+$/;
+/** Croner owns cron grammar; the product limits schedules to five numeric fields. */
+const cronExpressionSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(120)
+    .refine((expression) => expression.split(CRON_FIELDS_SEPARATOR).length === 5 &&
+    NUMERIC_CRON_EXPRESSION.test(expression), { message: "Expected a five-field numeric cron expression." });
+/**
+ * Canonical IANA timezone: `UTC` or `Area/Location` (optionally
+ * `Area/Location/Sublocation`). Rejects legacy abbreviations (`PST`, `GMT`)
+ * that `Intl` quietly accepts but `croner` cannot resolve deterministically.
+ */
+const IANA_TIMEZONE_REGEX = /^(UTC|[A-Za-z_]+\/[A-Za-z0-9_+-]+(\/[A-Za-z0-9_+-]+)?)$/;
+const ianaTimezoneSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(64)
+    .regex(IANA_TIMEZONE_REGEX, "Expected an IANA timezone (e.g. America/New_York).")
+    .refine((tz) => {
+    try {
+        Intl.DateTimeFormat("en-US", { timeZone: tz });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, { message: "Unknown IANA timezone." });
+/**
+ * Croner validates the expression in the schedule's own timezone. The DBOS
+ * schedule plan uses that validated expression and timezone unchanged.
+ */
+export const taskCronConfigSchema = z
+    .object({
+    expression: cronExpressionSchema,
+    staggerMs: z.number().int().min(0).optional(),
+    timezone: ianaTimezoneSchema.default("UTC"),
+})
+    .strict()
+    .superRefine((config, ctx) => {
+    try {
+        const cron = new Cron(config.expression, {
+            paused: true,
+            timezone: config.timezone,
+        });
+        if (cron.nextRun() === null) {
+            throw new Error("no next run");
+        }
+    }
+    catch {
+        ctx.addIssue({
+            code: "custom",
+            message: "Invalid cron expression.",
+            path: ["expression"],
+        });
+    }
+});
+export const taskScheduleInputSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("once"),
+        config: taskOnceConfigSchema,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("interval"),
+        config: taskIntervalConfigSchema,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("cron"),
+        config: taskCronConfigSchema,
+    })
+        .strict(),
+]);
+const taskNameSchema = z.string().trim().min(1).max(MAX_TASK_NAME_LENGTH);
+const taskPromptSchema = z.string().trim().min(1).max(MAX_TASK_PROMPT_LENGTH);
+/**
+ * `POST /v1/tasks` — schedule present = scheduled task; absent = on-demand.
+ * `submit: true` enqueues a run immediately (on-demand's only trigger
+ * alongside creation) with a server-minted random run id. This path is
+ * NOT idempotent — each call creates a new task + new run. For run-level
+ * idempotency, use `POST /v1/tasks/{taskId}/runs` with an idempotency key
+ * (the task must already exist so the deterministic run id is stable
+ * across replays).
+ */
+export const createTaskBodySchema = z
+    .object({
+    agentId: agentIdSchema,
+    agentVersion: agentVersionNumberSchema.nullable().default(null),
+    name: taskNameSchema,
+    prompt: taskPromptSchema,
+    schedule: taskScheduleInputSchema.nullable().default(null),
+    enabled: z.boolean().default(true),
+    submit: z.boolean().default(false),
+    userId: userIdSchema.default(""),
+    metadata: metadataSchema.default({}),
+})
+    .strict();
+// `PATCH /v1/tasks/{taskId}` — name/prompt/schedule/enabled/metadata;
+// agentId + userId immutable.
+export const updateTaskBodySchema = z
+    .object({
+    agentVersion: agentVersionNumberSchema.nullable().optional(),
+    name: taskNameSchema.optional(),
+    prompt: taskPromptSchema.optional(),
+    schedule: taskScheduleInputSchema.nullable().optional(),
+    enabled: z.boolean().optional(),
+    metadata: metadataSchema.optional(),
+})
+    .strict()
+    .refine(hasObjectKeys, {
+    message: atLeastOneFieldMessage,
+});
+// `POST /v1/tasks/{taskId}/runs` — optional client idempotency key.
+export const createTaskRunBodySchema = z
+    .object({
+    idempotencyKey: z.string().trim().min(1).optional(),
+})
+    .strict();
+/**
+ * Task run status. `blocked` is the soft-block terminal state for an expected
+ * admission denial, such as quota exhaustion, missing subscription, or
+ * insufficient Usage credit. Like the other terminal statuses, it sets
+ * `finishedAt` and frees the task's active-run slot for the next scheduled fire.
+ */
+export const taskRunStatusSchema = z.enum([
+    "queued",
+    "running",
+    "blocked",
+    "succeeded",
+    "failed",
+    "canceled",
+]);
+// The task record — pure definition; state lives in its runs.
+export const taskSchema = z
+    .object({
+    id: taskIdSchema,
+    tenantId: tenantIdSchema,
+    agentId: agentIdSchema,
+    agentVersion: agentVersionNumberSchema.nullable(),
+    name: taskNameSchema,
+    prompt: taskPromptSchema,
+    schedule: taskScheduleInputSchema.nullable(),
+    enabled: z.boolean(),
+    activeRunId: taskRunIdSchema.nullable(),
+    latestRunId: taskRunIdSchema.nullable(),
+    userId: userIdSchema,
+    metadata: metadataSchema,
+    deletedAt: z.iso.datetime({ offset: true }).nullable(),
+    createdAt: z.iso.datetime({ offset: true }),
+    updatedAt: z.iso.datetime({ offset: true }),
+})
+    .strict();
+// Compact run embed for list items — kills N+1 status polling.
+export const taskLatestRunSchema = z
+    .object({
+    id: taskRunIdSchema,
+    status: taskRunStatusSchema,
+    finishedAt: z.iso.datetime({ offset: true }).nullable(),
+})
+    .strict();
+export const taskListItemSchema = taskSchema.extend({
+    latestRun: taskLatestRunSchema.nullable(),
+});
+export const tasksListResponseSchema = paginatedResponseSchema(taskListItemSchema);
+export const tasksListQuerySchema = z
+    .object({
+    agentId: agentIdSchema.optional(),
+    userId: z.string().optional(),
+    cursor: z.string().nullable().optional(),
+})
+    .strict();
+export const taskResponseSchema = taskSchema;
+// Task run record. `userId`/`metadata` are inherited from the task at
+// enqueue (immutable thereafter); the run's session and usage facts carry
+// the same attribution.
+export const taskRunSchema = z
+    .object({
+    id: taskRunIdSchema,
+    taskId: taskIdSchema,
+    tenantId: tenantIdSchema,
+    agentId: agentIdSchema,
+    agentVersion: agentVersionNumberSchema,
+    sessionId: sessionIdSchema.nullable(),
+    turnId: turnIdSchema.nullable(),
+    status: taskRunStatusSchema,
+    error: z.string().nullable(),
+    userId: userIdSchema,
+    metadata: metadataSchema,
+    startedAt: z.iso.datetime({ offset: true }).nullable(),
+    finishedAt: z.iso.datetime({ offset: true }).nullable(),
+    cancelRequestedAt: z.iso.datetime({ offset: true }).nullable(),
+    canceledAt: z.iso.datetime({ offset: true }).nullable(),
+    createdAt: z.iso.datetime({ offset: true }),
+    updatedAt: z.iso.datetime({ offset: true }),
+})
+    .strict();
+export const taskRunResponseSchema = taskRunSchema;
+export const taskRunsListResponseSchema = paginatedResponseSchema(taskRunSchema);
+// `POST /v1/tasks` response — the created task + optional queued run id.
+export const createTaskResponseSchema = z
+    .object({
+    task: taskSchema,
+    runId: taskRunIdSchema.nullable(),
+})
+    .strict();
+// `POST /v1/tasks/{taskId}/runs` response — the queued run id.
+export const createTaskRunResponseSchema = z
+    .object({
+    runId: taskRunIdSchema,
+})
+    .strict();
+// `GET .../runs/{runId}/messages` — task-run session transcript, paginated.
+// Mirrors `sessionMessagesResponseSchema`: `latestCursor` is the tail
+// position (newest seq) for the poll loop's `?after=` cursor.
+export const taskRunMessagesResponseSchema = z
+    .object({
+    data: z.array(sessionMessageSchema),
+    nextCursor: z.string().nullable(),
+    latestCursor: z.string().nullable(),
+})
+    .strict();

package/dist/contracts/entities/tenants.d.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+/**
+ * `GET /v1/me` (JWT-only) — the tenant record. `authUserId` is a uuid
+ * referencing `auth.users(id)` per the migration.
+ */
+export declare const tenantSchema: z.ZodObject<{
+    id: z.ZodString;
+    authUserId: z.ZodUUID;
+    email: z.ZodString;
+    name: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const subscriptionStatusSchema: z.ZodEnum<{
+    active: "active";
+    inactive: "inactive";
+}>;
+export declare const tenantResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    authUserId: z.ZodUUID;
+    email: z.ZodString;
+    name: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+    subscriptionStatus: z.ZodEnum<{
+        active: "active";
+        inactive: "inactive";
+    }>;
+}, z.core.$strict>;
+/**
+ * Quota — `GET/PATCH /v1/tenant` carries the tenant's self-set quota.
+ * `null` means unlimited (no quota row).
+ */
+export declare const quotaSchema: z.ZodObject<{
+    monthlyTokenLimit: z.ZodNullable<z.ZodNumber>;
+    monthlyRequestLimit: z.ZodNullable<z.ZodNumber>;
+    resetDay: z.ZodNumber;
+}, z.core.$strict>;
+export declare const tenantSettingsSchema: z.ZodObject<{
+    name: z.ZodString;
+    quota: z.ZodNullable<z.ZodObject<{
+        monthlyTokenLimit: z.ZodNullable<z.ZodNumber>;
+        monthlyRequestLimit: z.ZodNullable<z.ZodNumber>;
+        resetDay: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const tenantSettingsResponseSchema: z.ZodObject<{
+    name: z.ZodString;
+    quota: z.ZodNullable<z.ZodObject<{
+        monthlyTokenLimit: z.ZodNullable<z.ZodNumber>;
+        monthlyRequestLimit: z.ZodNullable<z.ZodNumber>;
+        resetDay: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const updateTenantSettingsBodySchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    quota: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        monthlyTokenLimit: z.ZodNullable<z.ZodNumber>;
+        monthlyRequestLimit: z.ZodNullable<z.ZodNumber>;
+        resetDay: z.ZodNumber;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type Tenant = z.infer<typeof tenantSchema>;
+export type SubscriptionStatus = z.infer<typeof subscriptionStatusSchema>;
+export type TenantResponse = z.infer<typeof tenantResponseSchema>;
+export type Quota = z.infer<typeof quotaSchema>;
+export type TenantSettings = z.infer<typeof tenantSettingsSchema>;
+export type TenantSettingsResponse = z.infer<typeof tenantSettingsResponseSchema>;
+export type UpdateTenantSettingsBody = z.infer<typeof updateTenantSettingsBodySchema>;

package/dist/contracts/entities/tenants.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { tenantIdSchema } from "../ids.js";
+import { MAX_QUOTA_RESET_DAY, MAX_TENANT_NAME_LENGTH, MIN_QUOTA_RESET_DAY, } from "../limitations.js";
+import { atLeastOneFieldMessage, hasObjectKeys } from "../utils.js";
+/**
+ * `GET /v1/me` (JWT-only) — the tenant record. `authUserId` is a uuid
+ * referencing `auth.users(id)` per the migration.
+ */
+export const tenantSchema = z
+    .object({
+    id: tenantIdSchema,
+    authUserId: z.uuid(),
+    email: z.string().min(1),
+    name: z.string().min(1),
+    createdAt: z.iso.datetime({ offset: true }),
+    updatedAt: z.iso.datetime({ offset: true }),
+})
+    .strict();
+export const subscriptionStatusSchema = z.enum(["active", "inactive"]);
+export const tenantResponseSchema = tenantSchema
+    .extend({ subscriptionStatus: subscriptionStatusSchema })
+    .strict();
+/**
+ * Quota — `GET/PATCH /v1/tenant` carries the tenant's self-set quota.
+ * `null` means unlimited (no quota row).
+ */
+export const quotaSchema = z
+    .object({
+    monthlyTokenLimit: z.number().int().positive().nullable(),
+    monthlyRequestLimit: z.number().int().positive().nullable(),
+    resetDay: z
+        .number()
+        .int()
+        .min(MIN_QUOTA_RESET_DAY)
+        .max(MAX_QUOTA_RESET_DAY),
+})
+    .strict()
+    .refine(({ monthlyRequestLimit, monthlyTokenLimit }) => monthlyRequestLimit !== null || monthlyTokenLimit !== null, { message: "At least one quota limit is required" });
+export const tenantSettingsSchema = z
+    .object({
+    name: z.string().trim().min(1).max(MAX_TENANT_NAME_LENGTH),
+    quota: quotaSchema.nullable(),
+})
+    .strict();
+export const tenantSettingsResponseSchema = tenantSettingsSchema;
+export const updateTenantSettingsBodySchema = z
+    .object({
+    name: z.string().trim().min(1).max(MAX_TENANT_NAME_LENGTH).optional(),
+    quota: quotaSchema.nullable().optional(),
+})
+    .strict()
+    .refine(hasObjectKeys, {
+    message: atLeastOneFieldMessage,
+});

package/dist/contracts/entities/usage.d.ts

@@ -0,0 +1,95 @@
+import { z } from "zod";
+/**
+ * `GET /v1/usage` groupBy — `day|agent|model|session|user`. `session` is
+ * top-N by tokens; the others are exhaustive and bounded. `user` is the
+ * end-user attribution dimension (ADR-0001) — one bucket per `userId`, with
+ * `''` emitted verbatim as the tenant-level bucket.
+ */
+export declare const usageGroupBySchema: z.ZodDefault<z.ZodEnum<{
+    agent: "agent";
+    day: "day";
+    model: "model";
+    session: "session";
+    user: "user";
+}>>;
+/**
+ * A `sessionId` filter value — either a real platform session id (`ss_…`)
+ * or the `''` sentinel for stateless `completion`/`object` turns. The daily
+ * table stores `''` for stateless turns; the bucket wire shape maps `''`
+ * back to `null` on read (see `usageBucketSchema.sessionId`).
+ */
+export declare const usageSessionFilterSchema: z.ZodString;
+/**
+ * `?from=&to=&agentId=&sessionId=&userId=&groupBy=&limit=` — `from`/`to` are
+ * date strings (`YYYY-MM-DD`) since the daily table is keyed by `day date`.
+ * Range capped at 31 days; default is the last 30 days ending today (UTC).
+ * The `sessionId` filter accepts `''` to drill into stateless turns only.
+ * The `userId` filter accepts any opaque string (including `''` for
+ * tenant-level usage only) — see ADR-0001 for the three filter modes.
+ */
+export declare const usageQuerySchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodISODate>;
+    to: z.ZodOptional<z.ZodISODate>;
+    agentId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+    groupBy: z.ZodDefault<z.ZodEnum<{
+        agent: "agent";
+        day: "day";
+        model: "model";
+        session: "session";
+        user: "user";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+/**
+ * Usage bucket — one row per group. `sessionId` is the platform session id
+ * (`ss_…`) or `null` for the `''` stateless sentinel (mapped at the read
+ * seam); `day` is `YYYY-MM-DD` for `groupBy=day`, else `null`. `userId` is
+ * the end-user attribution dimension for `groupBy=user` (else `null`); the
+ * `''` tenant-level sentinel is emitted verbatim, not mapped to `null`, so
+ * callers can distinguish tenant-level usage from a named user.
+ */
+export declare const usageBucketSchema: z.ZodObject<{
+    day: z.ZodNullable<z.ZodString>;
+    agentId: z.ZodNullable<z.ZodString>;
+    sessionId: z.ZodNullable<z.ZodString>;
+    userId: z.ZodNullable<z.ZodString>;
+    provider: z.ZodNullable<z.ZodString>;
+    model: z.ZodNullable<z.ZodString>;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    requestCount: z.ZodNumber;
+    durationMs: z.ZodNumber;
+}, z.core.$strict>;
+export declare const usageTotalsSchema: z.ZodObject<{
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    requestCount: z.ZodNumber;
+    durationMs: z.ZodNumber;
+}, z.core.$strict>;
+export declare const usageResponseSchema: z.ZodObject<{
+    buckets: z.ZodArray<z.ZodObject<{
+        day: z.ZodNullable<z.ZodString>;
+        agentId: z.ZodNullable<z.ZodString>;
+        sessionId: z.ZodNullable<z.ZodString>;
+        userId: z.ZodNullable<z.ZodString>;
+        provider: z.ZodNullable<z.ZodString>;
+        model: z.ZodNullable<z.ZodString>;
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        requestCount: z.ZodNumber;
+        durationMs: z.ZodNumber;
+    }, z.core.$strict>>;
+    totals: z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        requestCount: z.ZodNumber;
+        durationMs: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type UsageGroupBy = z.infer<typeof usageGroupBySchema>;
+export type UsageQuery = z.infer<typeof usageQuerySchema>;
+export type UsageBucket = z.infer<typeof usageBucketSchema>;
+export type UsageTotals = z.infer<typeof usageTotalsSchema>;
+export type UsageResponse = z.infer<typeof usageResponseSchema>;

package/dist/contracts/entities/usage.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { agentIdSchema, sessionIdSchema } from "../ids.js";
+import { DEFAULT_USAGE_SESSION_TOP_N, MAX_USAGE_RANGE_DAYS, MAX_USAGE_SESSION_TOP_N, } from "../limitations.js";
+import { userIdSchema } from "./attribution.js";
+/**
+ * `GET /v1/usage` groupBy — `day|agent|model|session|user`. `session` is
+ * top-N by tokens; the others are exhaustive and bounded. `user` is the
+ * end-user attribution dimension (ADR-0001) — one bucket per `userId`, with
+ * `''` emitted verbatim as the tenant-level bucket.
+ */
+export const usageGroupBySchema = z
+    .enum(["day", "agent", "model", "session", "user"])
+    .default("day");
+/**
+ * A `sessionId` filter value — either a real platform session id (`ss_…`)
+ * or the `''` sentinel for stateless `completion`/`object` turns. The daily
+ * table stores `''` for stateless turns; the bucket wire shape maps `''`
+ * back to `null` on read (see `usageBucketSchema.sessionId`).
+ */
+export const usageSessionFilterSchema = z
+    .string()
+    .refine((v) => v === "" || z.validate(sessionIdSchema, v), {
+    message: "Must be a session id or '' for stateless turns.",
+});
+/**
+ * `?from=&to=&agentId=&sessionId=&userId=&groupBy=&limit=` — `from`/`to` are
+ * date strings (`YYYY-MM-DD`) since the daily table is keyed by `day date`.
+ * Range capped at 31 days; default is the last 30 days ending today (UTC).
+ * The `sessionId` filter accepts `''` to drill into stateless turns only.
+ * The `userId` filter accepts any opaque string (including `''` for
+ * tenant-level usage only) — see ADR-0001 for the three filter modes.
+ */
+export const usageQuerySchema = z
+    .object({
+    from: z.iso.date().optional(),
+    to: z.iso.date().optional(),
+    agentId: agentIdSchema.optional(),
+    sessionId: usageSessionFilterSchema.optional(),
+    userId: userIdSchema.optional(),
+    groupBy: usageGroupBySchema,
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_USAGE_SESSION_TOP_N)
+        .default(DEFAULT_USAGE_SESSION_TOP_N),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    /**
+     * Require either both `from` and `to` or neither — a partial range
+     * (only one bound) is rejected so the caller doesn't silently get the
+     * default window when they meant to specify a custom range.
+     */
+    if ((value.from === undefined) !== (value.to === undefined)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "`from` and `to` must both be present or both be absent.",
+            path: value.from === undefined ? ["from"] : ["to"],
+        });
+    }
+    if (value.from && value.to) {
+        const fromMs = new Date(`${value.from}T00:00:00Z`).getTime();
+        const toMs = new Date(`${value.to}T00:00:00Z`).getTime();
+        const spanDays = (toMs - fromMs) / (1000 * 60 * 60 * 24);
+        if (spanDays > MAX_USAGE_RANGE_DAYS) {
+            ctx.addIssue({
+                code: "custom",
+                message: `Usage range must be at most ${MAX_USAGE_RANGE_DAYS} days.`,
+                path: ["to"],
+            });
+        }
+        if (toMs < fromMs) {
+            ctx.addIssue({
+                code: "custom",
+                message: "`to` must be after `from`.",
+                path: ["to"],
+            });
+        }
+    }
+});
+/**
+ * Usage bucket — one row per group. `sessionId` is the platform session id
+ * (`ss_…`) or `null` for the `''` stateless sentinel (mapped at the read
+ * seam); `day` is `YYYY-MM-DD` for `groupBy=day`, else `null`. `userId` is
+ * the end-user attribution dimension for `groupBy=user` (else `null`); the
+ * `''` tenant-level sentinel is emitted verbatim, not mapped to `null`, so
+ * callers can distinguish tenant-level usage from a named user.
+ */
+export const usageBucketSchema = z
+    .object({
+    day: z.string().nullable(),
+    agentId: agentIdSchema.nullable(),
+    sessionId: sessionIdSchema.nullable(),
+    userId: userIdSchema.nullable(),
+    provider: z.string().nullable(),
+    model: z.string().nullable(),
+    inputTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+    requestCount: z.number().int().nonnegative(),
+    durationMs: z.number().int().nonnegative(),
+})
+    .strict();
+export const usageTotalsSchema = z
+    .object({
+    inputTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+    requestCount: z.number().int().nonnegative(),
+    durationMs: z.number().int().nonnegative(),
+})
+    .strict();
+export const usageResponseSchema = z
+    .object({
+    buckets: z.array(usageBucketSchema),
+    totals: usageTotalsSchema,
+})
+    .strict();

package/dist/contracts/entities/workspaces.d.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+export declare const workspaceNameSchema: z.ZodString;
+export declare const workspaceBackupSchema: z.ZodObject<{
+    dir: z.ZodLiteral<"/workspace">;
+    id: z.ZodUUID;
+    localBucket: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const workspaceNetworkPolicySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    mode: z.ZodLiteral<"unrestricted">;
+}, z.core.$strict>, z.ZodObject<{
+    allowedHosts: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"allowlist">;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"offline">;
+}, z.core.$strict>], "mode">;
+export declare const workspaceSchema: z.ZodObject<{
+    id: z.ZodString;
+    tenantId: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    userId: z.ZodString;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    networkPolicy: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"unrestricted">;
+    }, z.core.$strict>, z.ZodObject<{
+        allowedHosts: z.ZodArray<z.ZodString>;
+        mode: z.ZodLiteral<"allowlist">;
+    }, z.core.$strict>, z.ZodObject<{
+        mode: z.ZodLiteral<"offline">;
+    }, z.core.$strict>], "mode">;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const createWorkspaceBodySchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    userId: z.ZodDefault<z.ZodString>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    networkPolicy: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"unrestricted">;
+    }, z.core.$strict>, z.ZodObject<{
+        allowedHosts: z.ZodArray<z.ZodString>;
+        mode: z.ZodLiteral<"allowlist">;
+    }, z.core.$strict>, z.ZodObject<{
+        mode: z.ZodLiteral<"offline">;
+    }, z.core.$strict>], "mode">>;
+}, z.core.$strict>;
+export declare const updateWorkspaceBodySchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    networkPolicy: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"unrestricted">;
+    }, z.core.$strict>, z.ZodObject<{
+        allowedHosts: z.ZodArray<z.ZodString>;
+        mode: z.ZodLiteral<"allowlist">;
+    }, z.core.$strict>, z.ZodObject<{
+        mode: z.ZodLiteral<"offline">;
+    }, z.core.$strict>], "mode">>;
+}, z.core.$strict>;
+export declare const workspaceListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    userId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const workspacesListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        tenantId: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        userId: z.ZodString;
+        metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        networkPolicy: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            mode: z.ZodLiteral<"unrestricted">;
+        }, z.core.$strict>, z.ZodObject<{
+            allowedHosts: z.ZodArray<z.ZodString>;
+            mode: z.ZodLiteral<"allowlist">;
+        }, z.core.$strict>, z.ZodObject<{
+            mode: z.ZodLiteral<"offline">;
+        }, z.core.$strict>], "mode">;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type Workspace = z.infer<typeof workspaceSchema>;
+export type WorkspaceBackup = z.infer<typeof workspaceBackupSchema>;
+export type WorkspaceNetworkPolicy = z.infer<typeof workspaceNetworkPolicySchema>;
+export type CreateWorkspaceBody = z.input<typeof createWorkspaceBodySchema>;
+export type UpdateWorkspaceBody = z.infer<typeof updateWorkspaceBodySchema>;
+export type WorkspaceListQuery = z.infer<typeof workspaceListQuerySchema>;
+export type WorkspacesListResponse = z.infer<typeof workspacesListResponseSchema>;