agency-lang 0.13.0 → 0.13.1

package/dist/lib/cli/remote/commands/keys.d.ts

@@ -0,0 +1,10 @@
+import type { AccountCommandOptions, RemoteCommandContext } from "./util.js";
+export type CreateKeyOptions = AccountCommandOptions & {
+    project: string;
+};
+/** `agency remote keys` — list the account's API keys. */
+export declare function runKeysList(options: AccountCommandOptions, context: RemoteCommandContext): Promise<void>;
+/** `agency remote keys create <name> --project <slug>` — mint a project-scoped
+ *  key. `--project` is the public slug; the client resolves it to the internal
+ *  id. The plaintext key is printed once. */
+export declare function runKeysCreate(name: string, options: CreateKeyOptions, context: RemoteCommandContext): Promise<void>;

package/dist/lib/cli/remote/commands/keys.js

@@ -0,0 +1,30 @@
+import { createAccountClient } from "../../statelog/accountClient.js";
+import { renderKeys, renderCreatedKey } from "../render.js";
+import { resolveAccountTarget, failAccount } from "./util.js";
+/** `agency remote keys` — list the account's API keys. */
+export async function runKeysList(options, context) {
+    const target = resolveAccountTarget(context, options);
+    try {
+        const keys = await createAccountClient(target.origin, target.apiKey).listKeys();
+        console.log(renderKeys(keys));
+    }
+    catch (error) {
+        failAccount(error, target.apiKeyEnvName);
+    }
+}
+/** `agency remote keys create <name> --project <slug>` — mint a project-scoped
+ *  key. `--project` is the public slug; the client resolves it to the internal
+ *  id. The plaintext key is printed once. */
+export async function runKeysCreate(name, options, context) {
+    const target = resolveAccountTarget(context, options);
+    try {
+        const created = await createAccountClient(target.origin, target.apiKey).createProjectKey({
+            name,
+            projectId: options.project,
+        });
+        console.log(renderCreatedKey(created));
+    }
+    catch (error) {
+        failAccount(error, target.apiKeyEnvName);
+    }
+}

package/dist/lib/cli/remote/commands/projects.d.ts

@@ -0,0 +1,9 @@
+import type { AccountCommandOptions, RemoteCommandContext } from "./util.js";
+export type CreateProjectOptions = AccountCommandOptions & {
+    name: string;
+    description?: string;
+};
+/** `agency remote projects` — list the account's projects. */
+export declare function runProjectsList(options: AccountCommandOptions, context: RemoteCommandContext): Promise<void>;
+/** `agency remote projects create <project_id>` — create a project. */
+export declare function runProjectsCreate(projectId: string, options: CreateProjectOptions, context: RemoteCommandContext): Promise<void>;

package/dist/lib/cli/remote/commands/projects.js

@@ -0,0 +1,36 @@
+import { createAccountClient } from "../../statelog/accountClient.js";
+import { renderProjects, renderProjectCreated } from "../render.js";
+import { resolveAccountTarget, failAccount, fail } from "./util.js";
+// Matches statelog's server rule so a bad slug fails instantly, before any call.
+const PROJECT_ID_PATTERN = /^[a-z0-9-]+$/;
+const MAX_PROJECT_ID_LENGTH = 20;
+/** `agency remote projects` — list the account's projects. */
+export async function runProjectsList(options, context) {
+    const target = resolveAccountTarget(context, options);
+    try {
+        const projects = await createAccountClient(target.origin, target.apiKey).listProjects();
+        console.log(renderProjects(projects));
+    }
+    catch (error) {
+        failAccount(error, target.apiKeyEnvName);
+    }
+}
+/** `agency remote projects create <project_id>` — create a project. */
+export async function runProjectsCreate(projectId, options, context) {
+    if (!PROJECT_ID_PATTERN.test(projectId) || projectId.length > MAX_PROJECT_ID_LENGTH) {
+        fail(`Invalid project id "${projectId}" — lowercase letters, digits, and dashes only, ` +
+            `${MAX_PROJECT_ID_LENGTH} characters or fewer.`);
+    }
+    const target = resolveAccountTarget(context, options);
+    try {
+        const project = await createAccountClient(target.origin, target.apiKey).createProject({
+            name: options.name,
+            projectId,
+            description: options.description,
+        });
+        console.log(renderProjectCreated(project));
+    }
+    catch (error) {
+        failAccount(error, target.apiKeyEnvName);
+    }
+}

package/dist/lib/cli/remote/commands/util.d.ts

@@ -5,11 +5,42 @@ export type RemoteCommandContext = {
     config: AgencyConfig;
     configPath: string;
 };
+/** The API key together with the environment variable it came from, so a command
+ *  can name that variable in its guidance without the HTTP client knowing it. */
+export type ResolvedApiKey = {
+    apiKey: string;
+    apiKeyEnvName: string;
+};
+/** An account-management target: a canonical origin plus the resolved key. */
+export type AccountTarget = ResolvedApiKey & {
+    origin: string;
+};
+/** Options common to every account-management command. */
+export type AccountCommandOptions = {
+    host?: string;
+    apiKeyEnv?: string;
+};
 /** Print an error and exit non-zero. Typed `never` so callers can use it in an
  *  expression position (`const x = maybe() ?? fail(...)`). */
 export declare function fail(message: string): never;
-/** The API key from its environment variable, or exit with a clear message.
- *  The key is only ever read from the environment, never a flag. */
+/** The API key and its variable name, or exit with a clear message. The key is
+ *  only ever read from the environment, never a flag. */
+export declare function resolveApiKey(options: {
+    apiKeyEnv?: string;
+}): ResolvedApiKey;
+/** The API key value alone, for callers that do not need the variable name. */
 export declare function apiKeyOrExit(options: {
     apiKeyEnv?: string;
 }): string;
+/** Resolve where an account-management command talks to: a canonical origin (from
+ *  `--host`, then `agency.json` `log.host`, then an existing binding's origin)
+ *  and the resolved API key. Exits with a clear message on a missing or invalid
+ *  origin, or a missing key. */
+export declare function resolveAccountTarget(context: RemoteCommandContext, options: {
+    host?: string;
+    apiKeyEnv?: string;
+}): AccountTarget;
+/** Turn a client error into a clean CLI exit. An AccountScopeError becomes
+ *  guidance naming the resolved API-key variable — the one place that knows both
+ *  the scope error (from the client) and the variable name (from the target). */
+export declare function failAccount(error: unknown, apiKeyEnvName: string): never;

package/dist/lib/cli/remote/commands/util.js

@@ -1,6 +1,10 @@
-// Command-error presentation and API-key lookup, shared by the remote command
-// recipes. Owns exit/error output; never renders successful values.
+// Command-error presentation, API-key lookup, and account-target resolution,
+// shared by the remote command recipes. Owns exit/error output; never renders
+// successful values.
 import { color } from "../../../utils/termcolors.js";
+import { readBinding } from "../binding.js";
+import { canonicalOrigin } from "../../statelog/serveUrl.js";
+import { AccountScopeError } from "../../statelog/accountClient.js";
 const DEFAULT_API_KEY_ENV = "STATELOG_API_KEY";
 /** Print an error and exit non-zero. Typed `never` so callers can use it in an
  *  expression position (`const x = maybe() ?? fail(...)`). */
@@ -8,13 +12,45 @@ export function fail(message) {
     console.error(color.red(message));
     process.exit(1);
 }
-/** The API key from its environment variable, or exit with a clear message.
- *  The key is only ever read from the environment, never a flag. */
+/** The API key and its variable name, or exit with a clear message. The key is
+ *  only ever read from the environment, never a flag. */
+export function resolveApiKey(options) {
+    const apiKeyEnvName = options.apiKeyEnv ?? DEFAULT_API_KEY_ENV;
+    const apiKey = process.env[apiKeyEnvName];
+    if (!apiKey) {
+        fail(`Missing API key — set $${apiKeyEnvName}.`);
+    }
+    return { apiKey, apiKeyEnvName };
+}
+/** The API key value alone, for callers that do not need the variable name. */
 export function apiKeyOrExit(options) {
-    const name = options.apiKeyEnv ?? DEFAULT_API_KEY_ENV;
-    const key = process.env[name];
-    if (!key) {
-        fail(`Missing API key — set $${name}.`);
+    return resolveApiKey(options).apiKey;
+}
+/** Resolve where an account-management command talks to: a canonical origin (from
+ *  `--host`, then `agency.json` `log.host`, then an existing binding's origin)
+ *  and the resolved API key. Exits with a clear message on a missing or invalid
+ *  origin, or a missing key. */
+export function resolveAccountTarget(context, options) {
+    const bindingOrigin = readBinding(context.configPath)?.origin;
+    const selected = options.host ?? context.config.log?.host ?? bindingOrigin;
+    if (!selected) {
+        fail("No statelog host. Set log.host in agency.json, pass --host, or link this directory first.");
+    }
+    const origin = canonicalOrigin(selected);
+    if (!origin) {
+        fail(`Invalid statelog host "${selected}". Use an HTTP(S) origin with no path, credentials, query, or fragment.`);
+    }
+    return { origin, ...resolveApiKey(options) };
+}
+/** Turn a client error into a clean CLI exit. An AccountScopeError becomes
+ *  guidance naming the resolved API-key variable — the one place that knows both
+ *  the scope error (from the client) and the variable name (from the target). */
+export function failAccount(error, apiKeyEnvName) {
+    if (error instanceof AccountScopeError) {
+        fail(`$${apiKeyEnvName} is a project-scoped key; this needs an account-scoped key. Create one in the statelog web UI.`);
+    }
+    if (error instanceof Error) {
+        fail(error.message);
     }
-    return key;
+    fail(String(error));
 }

package/dist/lib/cli/remote/commands/whoami.d.ts

@@ -0,0 +1,4 @@
+import type { AccountCommandOptions, RemoteCommandContext } from "./util.js";
+/** `agency remote whoami` — resolve and print the authenticated user. Accepts an
+ *  account- or project-scoped key, so it doubles as a "is my key valid" check. */
+export declare function runWhoami(options: AccountCommandOptions, context: RemoteCommandContext): Promise<void>;

package/dist/lib/cli/remote/commands/whoami.js

@@ -0,0 +1,15 @@
+import { createAccountClient } from "../../statelog/accountClient.js";
+import { renderWhoami } from "../render.js";
+import { resolveAccountTarget, fail } from "./util.js";
+/** `agency remote whoami` — resolve and print the authenticated user. Accepts an
+ *  account- or project-scoped key, so it doubles as a "is my key valid" check. */
+export async function runWhoami(options, context) {
+    const target = resolveAccountTarget(context, options);
+    try {
+        const { userId } = await createAccountClient(target.origin, target.apiKey).whoami();
+        console.log(renderWhoami(userId, target.origin));
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+}

package/dist/lib/cli/remote/render.d.ts

@@ -1,5 +1,11 @@
 import type { ServeManifest } from "../statelog/serveClient.js";
 import type { RemoteBinding } from "./binding.js";
+import type { ProjectSummary, KeySummary, CreatedKey } from "../statelog/accountClient.js";
 export declare function renderManifest(manifest: ServeManifest, binding: RemoteBinding): string;
 export declare function renderResult(value: unknown): string;
 export declare function renderLink(binding: RemoteBinding): string;
+export declare function renderWhoami(userId: string, origin: string): string;
+export declare function renderProjects(projects: ProjectSummary[]): string;
+export declare function renderProjectCreated(project: ProjectSummary): string;
+export declare function renderKeys(keys: KeySummary[]): string;
+export declare function renderCreatedKey(key: CreatedKey): string;

package/dist/lib/cli/remote/render.js

@@ -2,6 +2,7 @@
 // call result, and the link status. Owns formatting so the command recipes
 // don't; all colour goes through termcolors.
 import { color } from "../../utils/termcolors.js";
+const NONE = "—";
 export function renderManifest(manifest, binding) {
     const lines = [
         color.bold(binding.filename) + color.dim(` — ${binding.serveUrl}`),
@@ -34,3 +35,56 @@ export function renderLink(binding) {
 function effectsSuffix(interruptEffects) {
     return interruptEffects.length ? color.dim(`  raises ${interruptEffects.join(", ")}`) : "";
 }
+export function renderWhoami(userId, origin) {
+    return [
+        `${color.bold("User:")} ${userId}`,
+        `${color.bold("Host:")} ${color.dim(origin)}`,
+    ].join("\n");
+}
+export function renderProjects(projects) {
+    if (projects.length === 0) {
+        return color.dim("No projects yet.");
+    }
+    const rows = projects.map((project) => [
+        project.projectId,
+        project.name,
+        project.description ?? NONE,
+    ]);
+    return formatStaticTable(["PROJECT", "NAME", "DESCRIPTION"], rows);
+}
+export function renderProjectCreated(project) {
+    return `${color.green("Created project")} ${color.bold(project.projectId)} — ${project.name}`;
+}
+export function renderKeys(keys) {
+    if (keys.length === 0) {
+        return color.dim("No API keys yet.");
+    }
+    const rows = keys.map((key) => [
+        key.name ?? NONE,
+        key.scope,
+        key.projectId ?? NONE,
+        key.createdAt,
+        key.id,
+    ]);
+    return formatStaticTable(["NAME", "SCOPE", "PROJECT", "CREATED", "ID"], rows);
+}
+export function renderCreatedKey(key) {
+    const project = key.scope === "project" ? ` · ${key.projectId}` : "";
+    return [
+        `${color.green("Created API key")} ${color.bold(key.name ?? NONE)} (${key.scope}${project})`,
+        "",
+        color.yellow("Copy this key now — it will not be shown again:"),
+        `  ${key.plainKey}`,
+    ].join("\n");
+}
+/** A plain, ANSI-free aligned table. Colour is applied around the table by the
+ *  renderers, never inside a cell, so byte-width never skews alignment. */
+function formatStaticTable(headers, rows) {
+    const widths = headers.map((header, columnIndex) => {
+        const values = rows.map((row) => row[columnIndex] ?? "");
+        return Math.max(header.length, ...values.map((value) => value.length));
+    });
+    return [headers, ...rows]
+        .map((row) => row.map((value, index) => value.padEnd(widths[index] ?? 0)).join("  ").trimEnd())
+        .join("\n");
+}

package/dist/lib/cli/statelog/accountClient.d.ts

@@ -0,0 +1,50 @@
+export type ProjectSummary = {
+    projectId: string;
+    name: string;
+    description: string | null;
+};
+export type CreateProjectInput = {
+    name: string;
+    projectId: string;
+    description?: string;
+};
+type KeySummaryBase = {
+    id: string;
+    name: string | null;
+    createdAt: string;
+};
+/** A key summary in public terms: a project key's `projectId` is the slug (the
+ *  client has already translated it from the internal id). */
+export type KeySummary = (KeySummaryBase & {
+    scope: "account";
+    projectId: null;
+}) | (KeySummaryBase & {
+    scope: "project";
+    projectId: string;
+});
+export type CreatedKey = KeySummary & {
+    plainKey: string;
+};
+export type CreateProjectKeyInput = {
+    name: string;
+    projectId: string;
+};
+/** Any account request that did not produce a usable result. */
+export declare class AccountRequestError extends Error {
+}
+/** A 403 whose server error is the known account-scope error. The command layer
+ *  decorates it with the resolved API-key env var name; this file never knows
+ *  that name. */
+export declare class AccountScopeError extends AccountRequestError {
+}
+export type AccountClient = {
+    whoami(): Promise<{
+        userId: string;
+    }>;
+    listProjects(): Promise<ProjectSummary[]>;
+    createProject(input: CreateProjectInput): Promise<ProjectSummary>;
+    listKeys(): Promise<KeySummary[]>;
+    createProjectKey(input: CreateProjectKeyInput): Promise<CreatedKey>;
+};
+export declare function createAccountClient(origin: string, apiKey: string): AccountClient;
+export {};

package/dist/lib/cli/statelog/accountClient.js

@@ -0,0 +1,205 @@
+// The statelog account-management API, sealed here. This is the only file that
+// knows the `/api/*` routes, the `Result` envelope, statelog's wire field names,
+// and — critically — the split between the public project slug (`project_id`) and
+// the internal database id (`id`). Callers speak only the public slug; the
+// internal id never leaves this file. Every failure — network, HTTP, JSON,
+// schema, or a `success:false` body — surfaces as an AccountRequestError.
+/** Any account request that did not produce a usable result. */
+export class AccountRequestError extends Error {
+}
+/** A 403 whose server error is the known account-scope error. The command layer
+ *  decorates it with the resolved API-key env var name; this file never knows
+ *  that name. */
+export class AccountScopeError extends AccountRequestError {
+}
+const ACCOUNT_SCOPE_ERROR = "This endpoint requires an account-scoped API key";
+function accountRouteUrl(origin, route) {
+    return new URL(`/api/${route}`, origin).toString();
+}
+export function createAccountClient(origin, apiKey) {
+    async function request(method, route, body) {
+        const headers = { Authorization: `Bearer ${apiKey}` };
+        const init = { method, headers };
+        if (method === "POST") {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(body ?? {});
+        }
+        let response;
+        try {
+            response = await fetch(accountRouteUrl(origin, route), init);
+        }
+        catch (error) {
+            throw new AccountRequestError(`could not reach ${origin} (${message(error)})`);
+        }
+        let json;
+        let parsed = true;
+        try {
+            json = await response.json();
+        }
+        catch {
+            parsed = false;
+        }
+        // Non-2xx first: auth middleware returns a bare `{ error }`, not an envelope.
+        if (!response.ok) {
+            const serverError = parsed ? asObject(json)?.error : undefined;
+            if (response.status === 403 && serverError === ACCOUNT_SCOPE_ERROR) {
+                throw new AccountScopeError(ACCOUNT_SCOPE_ERROR);
+            }
+            if (typeof serverError === "string") {
+                throw new AccountRequestError(serverError);
+            }
+            if (response.status === 401) {
+                throw new AccountRequestError("not authenticated (HTTP 401)");
+            }
+            throw new AccountRequestError(`statelog request failed (HTTP ${response.status})`);
+        }
+        if (!parsed) {
+            throw new AccountRequestError(`statelog returned a non-JSON response (HTTP ${response.status})`);
+        }
+        const envelope = asObject(json);
+        if (!envelope || typeof envelope.success !== "boolean") {
+            throw new AccountRequestError("unexpected account response shape");
+        }
+        if (!envelope.success) {
+            throw new AccountRequestError(typeof envelope.error === "string" ? envelope.error : "account request failed");
+        }
+        return envelope.value;
+    }
+    async function listProjectsRaw() {
+        const value = await request("GET", "projects");
+        return asArray(value, "projects").map(validateRawProject);
+    }
+    return {
+        async whoami() {
+            return validateWhoami(await request("GET", "whoami"));
+        },
+        async listProjects() {
+            return (await listProjectsRaw()).map(toProjectSummary);
+        },
+        async createProject(input) {
+            const value = await request("POST", "projects", {
+                name: input.name,
+                project_id: input.projectId,
+                description: input.description ?? null,
+            });
+            return toProjectSummary(validateRawProject(value));
+        },
+        async listKeys() {
+            const projects = await listProjectsRaw();
+            const value = await request("GET", "api_keys");
+            const slugById = slugByInternalId(projects);
+            return asArray(value, "api_keys").map((entry) => toKeySummary(validateRawKeySummary(entry), slugById));
+        },
+        async createProjectKey(input) {
+            const projects = await listProjectsRaw();
+            const match = projects.find((project) => project.project_id === input.projectId);
+            if (!match) {
+                throw new AccountRequestError(`unknown project '${input.projectId}'`);
+            }
+            const value = await request("POST", "api_keys", {
+                name: input.name,
+                scope: "project",
+                projectId: match.id,
+            });
+            return validateCreatedKey(value, slugByInternalId(projects));
+        },
+    };
+}
+function toProjectSummary(raw) {
+    return { projectId: raw.project_id, name: raw.name, description: raw.description };
+}
+function validateWhoami(value) {
+    const obj = asObject(value);
+    if (!obj || typeof obj.userId !== "string") {
+        throw new AccountRequestError("whoami response missing userId");
+    }
+    return { userId: obj.userId };
+}
+function validateRawProject(value) {
+    const obj = asObject(value);
+    if (!obj) {
+        throw new AccountRequestError("each project entry must be an object");
+    }
+    const id = requireString(obj.id, "project id");
+    const project_id = requireString(obj.project_id, "project project_id");
+    const name = requireString(obj.name, "project name");
+    if (obj.description !== null && typeof obj.description !== "string") {
+        throw new AccountRequestError("project description must be a string or null");
+    }
+    return { id, project_id, name, description: obj.description };
+}
+/** internal id → public slug, so a listed key's project can be shown by slug.
+ *  Null-prototype: the keys are server-provided ids, so an id like `__proto__`
+ *  or `constructor` must be a plain data property, not a prototype write. */
+function slugByInternalId(projects) {
+    const map = Object.create(null);
+    for (const project of projects) {
+        map[project.id] = project.project_id;
+    }
+    return map;
+}
+function validateRawKeySummary(value) {
+    const obj = asObject(value);
+    if (!obj) {
+        throw new AccountRequestError("each key entry must be an object");
+    }
+    const id = requireString(obj.id, "key id");
+    if (obj.name !== null && typeof obj.name !== "string") {
+        throw new AccountRequestError("key name must be a string or null");
+    }
+    const createdAt = requireString(obj.createdAt, "key createdAt");
+    const base = { id, name: obj.name, createdAt };
+    if (obj.scope === "account") {
+        if (obj.projectId !== null) {
+            throw new AccountRequestError("account key must have a null projectId");
+        }
+        return { ...base, scope: "account", projectId: null };
+    }
+    if (obj.scope === "project") {
+        return { ...base, scope: "project", projectId: requireString(obj.projectId, "project key projectId") };
+    }
+    throw new AccountRequestError(`unknown key scope ${String(obj.scope)}`);
+}
+/** Replace a project key's internal id with its public slug (or a placeholder
+ *  when the project no longer exists — never the raw id). */
+function toKeySummary(raw, slugById) {
+    if (raw.scope === "account") {
+        return { id: raw.id, name: raw.name, createdAt: raw.createdAt, scope: "account", projectId: null };
+    }
+    return {
+        id: raw.id,
+        name: raw.name,
+        createdAt: raw.createdAt,
+        scope: "project",
+        projectId: slugById[raw.projectId] ?? "(unknown project)",
+    };
+}
+function validateCreatedKey(value, slugById) {
+    const summary = toKeySummary(validateRawKeySummary(value), slugById);
+    const obj = asObject(value);
+    if (!obj || typeof obj.plainKey !== "string") {
+        throw new AccountRequestError("created key missing plainKey");
+    }
+    return { ...summary, plainKey: obj.plainKey };
+}
+function asObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function asArray(value, label) {
+    if (!Array.isArray(value)) {
+        throw new AccountRequestError(`${label} must be an array`);
+    }
+    return value;
+}
+function requireString(value, label) {
+    if (typeof value !== "string") {
+        throw new AccountRequestError(`${label} must be a string`);
+    }
+    return value;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/cli/statelog/serveUrl.d.ts

@@ -27,3 +27,9 @@ export declare function parseServeBaseUrl(rawUrl: string): ServeAddress | null;
 export declare function serveRouteUrl(serveUrl: string, segments: string[]): string;
 /** The statelog web-app page for an agent's project. */
 export declare function projectPageUrl(address: ServeAddress): string;
+/** Reduce a host string to a bare origin (`scheme://host[:port]`), or null if it
+ *  is not a usable statelog origin. Account-management routes are built from this
+ *  with `new URL(...)`, so anything ambiguous is rejected: non-HTTP(S) schemes,
+ *  embedded credentials, a query or fragment, or a non-root path (statelog is
+ *  served at the root). A trailing slash is canonicalized away. */
+export declare function canonicalOrigin(host: string): string | null;

package/dist/lib/cli/statelog/serveUrl.js

@@ -90,3 +90,30 @@ export function projectPageUrl(address) {
     url.searchParams.set("id", address.projectId);
     return url.toString();
 }
+/** Reduce a host string to a bare origin (`scheme://host[:port]`), or null if it
+ *  is not a usable statelog origin. Account-management routes are built from this
+ *  with `new URL(...)`, so anything ambiguous is rejected: non-HTTP(S) schemes,
+ *  embedded credentials, a query or fragment, or a non-root path (statelog is
+ *  served at the root). A trailing slash is canonicalized away. */
+export function canonicalOrigin(host) {
+    let parsed;
+    try {
+        parsed = new URL(host);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return null;
+    }
+    if (parsed.username || parsed.password) {
+        return null;
+    }
+    if (parsed.search || parsed.hash) {
+        return null;
+    }
+    if (parsed.pathname !== "/" && parsed.pathname !== "") {
+        return null;
+    }
+    return parsed.origin;
+}

package/dist/lib/runtime/interrupts.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { approve, reject } from "./interruptResponse.js";
 import { runInBootstrapFrame } from "./asyncContext.js";
 import { __initAllRegisteredCallbacks } from "./crossModuleInitRegistry.js";
+import { reinstallRootBudget } from "./rootBudget.js";
 import { AgencyCancelledError, HandlerRecursionError, RestoreSignal, } from "./errors.js";
 import { isAborted } from "./abortedResult.js";
 import { mergeFor, mergeForIpc } from "./effectMerge.js";
@@ -633,6 +634,11 @@ export async function respondToInterrupts(args) {
     // and lib/runtime/asyncContext.ts (`runInBootstrapFrame`).
     await runInBootstrapFrame(execCtx, () => __initAllRegisteredCallbacks(execCtx));
     execCtx.restoreState(checkpoint);
+    // Re-assert the root budget's LIMIT from the host context (the checkpoint's
+    // ceiling is caller-controllable on a stateless resume), while preserving the
+    // guard's accumulated spend so the trusted CLI resume path stays cumulative.
+    // No-op in IPC.
+    reinstallRootBudget(execCtx.stateStack, execCtx.budget);
     execCtx.setInterruptResponses(responseMap);
     if (metadata.callbacks)
         Object.assign(execCtx.callbacks, metadata.callbacks);

package/dist/lib/runtime/rootBudget.d.ts

@@ -1,22 +1,36 @@
 import type { StateStack } from "./state/stateStack.js";
-/** Install a root cost/time guard from the CLI flags (AGENCY_MAX_COST /
- *  AGENCY_MAX_TIME env vars) or, when a flag is absent for that dimension, the
- *  resolved config `budget` (passed as `contextBudget`). The flag wins per
- *  dimension, so `agency run --max-cost` still overrides an `agency.json`
- *  budget; a served agent, which has no flag, is governed by the budget its
- *  host bound via runtime-config overrides.
+/** Install a root cost/time budget. Applies the disable rule: cost < 0 installs
+ *  nothing; time <= 0 installs nothing (cost 0 IS a real limit — no paid spend,
+ *  local-models-only). Called once at the root, next to installRunPolicyHandler,
+ *  before the node body runs, so the budget is outermost and cannot be bypassed.
+ *  No-op in IPC subprocesses — a child's budget is owned by the parent's guard,
+ *  which meters the subprocess through the branch clone.
  *
- *  Applies the disable rule: cost < 0 installs nothing; time <= 0 installs
- *  nothing (cost 0 IS a real limit — no paid spend, local-models-only).
- *  Called once at the root, next to installRunPolicyHandler, before the
- *  node body runs, so the budget is outermost and cannot be bypassed.
- *  No-op in IPC subprocesses — a child's budget is owned by the parent's
- *  guard, which meters the subprocess through the branch clone.
- *
- *  pushGuard() installs immediately, so a time budget's clock starts at
- *  run start — the intended whole-run semantics. Interrupt halts and
- *  input() waits still pause it like any other time guard. */
+ *  pushGuard() installs immediately, so a time budget's clock starts at run
+ *  start — the intended whole-run semantics. Interrupt halts and input() waits
+ *  still pause it like any other time guard. */
 export declare function installRootBudget(stack: StateStack, contextBudget?: {
     maxCost?: number;
     maxTimeMs?: number;
 }): void;
+/** Re-assert the root budget on a RESUMED exec context. The root guard is
+ *  serialized with the checkpoint, so on a stateless served resume its limit
+ *  arrives from a client-controllable payload — a crafted resume could raise the
+ *  ceiling. Clamp the restored root guard's LIMIT to the host value while
+ *  KEEPING the guard (and its accumulated spend/elapsed):
+ *
+ *  - the limit becomes host-authoritative and un-raisable from the client;
+ *  - accumulated spend is preserved, so the trusted in-process CLI resume path
+ *    stays cumulative across legs — no regression — and a served client that
+ *    lowers its own reported spend only hurts itself (same residual gap a
+ *    stateless resume always has);
+ *  - arming is untouched (restored guards are un-armed by restoreState), so this
+ *    can't reintroduce a timer pop-race.
+ *
+ *  A dimension the host no longer caps has its restored root guard dropped
+ *  (through `uninstall`); a dimension the host caps but the checkpoint had no
+ *  root guard for gets a fresh guard. No-op in IPC. */
+export declare function reinstallRootBudget(stack: StateStack, contextBudget?: {
+    maxCost?: number;
+    maxTimeMs?: number;
+}): void;

package/dist/lib/runtime/rootBudget.js

@@ -1,50 +1,111 @@
 import { AGENCY_MAX_COST, AGENCY_MAX_TIME } from "../constants.js";
 import { CostGuard, TimeGuard } from "./guard.js";
 import { isIpcMode } from "./subprocessRunInfo.js";
-/** Install a root cost/time guard from the CLI flags (AGENCY_MAX_COST /
- *  AGENCY_MAX_TIME env vars) or, when a flag is absent for that dimension, the
- *  resolved config `budget` (passed as `contextBudget`). The flag wins per
- *  dimension, so `agency run --max-cost` still overrides an `agency.json`
- *  budget; a served agent, which has no flag, is governed by the budget its
- *  host bound via runtime-config overrides.
- *
- *  Applies the disable rule: cost < 0 installs nothing; time <= 0 installs
- *  nothing (cost 0 IS a real limit — no paid spend, local-models-only).
- *  Called once at the root, next to installRunPolicyHandler, before the
- *  node body runs, so the budget is outermost and cannot be bypassed.
- *  No-op in IPC subprocesses — a child's budget is owned by the parent's
- *  guard, which meters the subprocess through the branch clone.
- *
- *  pushGuard() installs immediately, so a time budget's clock starts at
- *  run start — the intended whole-run semantics. Interrupt halts and
- *  input() waits still pause it like any other time guard. */
-export function installRootBudget(stack, contextBudget) {
-    if (isIpcMode())
-        return;
+/** The host-authoritative root limits: the CLI flag (AGENCY_MAX_COST /
+ *  AGENCY_MAX_TIME env vars) if set, else the resolved config `budget`. The flag
+ *  wins per dimension, so `agency run --max-cost` still overrides an
+ *  `agency.json` budget; a served agent, which has no flag, is governed by the
+ *  budget its host bound via runtime-config overrides. `undefined` means "no
+ *  cap this dimension"; a value still passes through the disable rule at the
+ *  call site (cost < 0 / time <= 0 install nothing). FAILS CLOSED on a
+ *  malformed value. */
+function resolveRootLimits(contextBudget) {
     const rawCost = process.env[AGENCY_MAX_COST];
     const cost = rawCost !== undefined
         ? parseBudgetValue(rawCost, AGENCY_MAX_COST)
         : contextBudget?.maxCost !== undefined
             ? finiteContextBudget(contextBudget.maxCost, "budget.maxCost")
             : undefined;
-    if (cost !== undefined && cost >= 0) {
-        const g = new CostGuard(cost);
-        // The operator's ceiling: never raises an interrupt, never
-        // extendable by user code. Serialized with the guard.
-        g.isRootBudget = true;
-        stack.pushGuard(g);
-    }
     const rawTime = process.env[AGENCY_MAX_TIME];
-    const ms = rawTime !== undefined
+    const timeMs = rawTime !== undefined
         ? parseBudgetValue(rawTime, AGENCY_MAX_TIME)
         : contextBudget?.maxTimeMs !== undefined
             ? finiteContextBudget(contextBudget.maxTimeMs, "budget.maxTime")
             : undefined;
-    if (ms !== undefined && ms > 0) {
-        const g = new TimeGuard(ms);
-        g.isRootBudget = true;
-        stack.pushGuard(g);
+    return { cost, timeMs };
+}
+function pushRootGuard(stack, guard) {
+    // The operator's ceiling: never raises an interrupt, never extendable by user
+    // code. Serialized with the guard.
+    guard.isRootBudget = true;
+    stack.pushGuard(guard);
+}
+/** Install a root cost/time budget. Applies the disable rule: cost < 0 installs
+ *  nothing; time <= 0 installs nothing (cost 0 IS a real limit — no paid spend,
+ *  local-models-only). Called once at the root, next to installRunPolicyHandler,
+ *  before the node body runs, so the budget is outermost and cannot be bypassed.
+ *  No-op in IPC subprocesses — a child's budget is owned by the parent's guard,
+ *  which meters the subprocess through the branch clone.
+ *
+ *  pushGuard() installs immediately, so a time budget's clock starts at run
+ *  start — the intended whole-run semantics. Interrupt halts and input() waits
+ *  still pause it like any other time guard. */
+export function installRootBudget(stack, contextBudget) {
+    if (isIpcMode())
+        return;
+    const { cost, timeMs } = resolveRootLimits(contextBudget);
+    if (cost !== undefined && cost >= 0)
+        pushRootGuard(stack, new CostGuard(cost));
+    if (timeMs !== undefined && timeMs > 0)
+        pushRootGuard(stack, new TimeGuard(timeMs));
+}
+/** Re-assert the root budget on a RESUMED exec context. The root guard is
+ *  serialized with the checkpoint, so on a stateless served resume its limit
+ *  arrives from a client-controllable payload — a crafted resume could raise the
+ *  ceiling. Clamp the restored root guard's LIMIT to the host value while
+ *  KEEPING the guard (and its accumulated spend/elapsed):
+ *
+ *  - the limit becomes host-authoritative and un-raisable from the client;
+ *  - accumulated spend is preserved, so the trusted in-process CLI resume path
+ *    stays cumulative across legs — no regression — and a served client that
+ *    lowers its own reported spend only hurts itself (same residual gap a
+ *    stateless resume always has);
+ *  - arming is untouched (restored guards are un-armed by restoreState), so this
+ *    can't reintroduce a timer pop-race.
+ *
+ *  A dimension the host no longer caps has its restored root guard dropped
+ *  (through `uninstall`); a dimension the host caps but the checkpoint had no
+ *  root guard for gets a fresh guard. No-op in IPC. */
+export function reinstallRootBudget(stack, contextBudget) {
+    if (isIpcMode())
+        return;
+    const { cost, timeMs } = resolveRootLimits(contextBudget);
+    const hostCost = cost !== undefined && cost >= 0 ? cost : undefined;
+    const hostTimeMs = timeMs !== undefined && timeMs > 0 ? timeMs : undefined;
+    let sawCost = false;
+    let sawTime = false;
+    const dropped = [];
+    for (const guard of stack.guards) {
+        if (!guard.isRootBudget)
+            continue;
+        if (guard instanceof CostGuard) {
+            sawCost = true;
+            // Direct clamp (not extendBudget, which only grants upward): the host
+            // ceiling replaces whatever the checkpoint carried, preserving `spent`.
+            if (hostCost !== undefined)
+                guard.costLimit = hostCost;
+            else
+                dropped.push(guard);
+        }
+        else if (guard instanceof TimeGuard) {
+            sawTime = true;
+            if (hostTimeMs !== undefined)
+                guard.timeLimit = hostTimeMs;
+            else
+                dropped.push(guard);
+        }
+    }
+    if (dropped.length > 0) {
+        for (const guard of dropped)
+            guard.uninstall(stack);
+        stack.guards = stack.guards.filter((g) => !dropped.includes(g));
+        stack.rebuildAbortSignal();
     }
+    // The host caps a dimension the checkpoint had no root guard for.
+    if (!sawCost && hostCost !== undefined)
+        pushRootGuard(stack, new CostGuard(hostCost));
+    if (!sawTime && hostTimeMs !== undefined)
+        pushRootGuard(stack, new TimeGuard(hostTimeMs));
 }
 /** FAIL CLOSED on a malformed budget value. The env is an internal
  *  carrier and the CLI validates before setting it, so a non-finite

package/dist/lib/runtime/state/context.js

@@ -316,6 +316,10 @@ export class RuntimeContext {
         execCtx.maxRestores = this.maxRestores;
         execCtx.maxCallDepth = this.maxCallDepth;
         execCtx.failurePropagation = this.failurePropagation;
+        // Non-serialized field — must be copied here (see the class comment) so
+        // installRootBudget, which reads execCtx.budget, actually sees the resolved
+        // config/override budget. Without this the root budget is a silent no-op.
+        execCtx.budget = this.budget;
         execCtx.checkpoints = new CheckpointStore(this.maxRestores);
         // The execution context is built via Object.create, bypassing the
         // constructor, so carry the clock over from the global context. Without

package/dist/lib/serve/http/adapter.js

@@ -1,6 +1,8 @@
 import http from "http";
 import { errorMessage, toArgs, parseJsonBody } from "../util.js";
 import { validateResumeBatch } from "../../runtime/interrupts.js";
+import { readCause } from "../../runtime/errors.js";
+import { formatBudgetExceeded } from "../../runtime/budgetExit.js";
 import { DEFAULT_HOST, defaultAllowedHosts, enforceNoKeyOnNonLoopback, logServerStart, makeGuardedRequestListener, } from "./security.js";
 function ok(value) {
     return { status: 200, body: { success: true, value } };
@@ -20,14 +22,44 @@ function interruptResult(data) {
  * avoid leaking secrets, file paths, model API responses, etc.
  */
 const TOOL_ERROR_MESSAGE = "Tool execution failed";
+/** A tripped ROOT budget is a spend/time stop, not a generic tool failure.
+ *  Return a typed, structured result (HTTP 402) carrying the dimension, limit,
+ *  and spend, so a caller and traces can tell it apart without string-matching
+ *  the generic message. Unlike other errors, the budget numbers are safe to
+ *  surface — they are the operator's own limit, not server internals. */
+function budgetExceeded(cause) {
+    return {
+        status: 402,
+        body: {
+            success: false,
+            code: "budgetExceeded",
+            error: formatBudgetExceeded(cause),
+            dimension: cause.dimension,
+            limit: cause.limit,
+            spent: cause.spent,
+        },
+    };
+}
+/** Map a thrown error to a route result: a root-budget trip becomes a typed
+ *  budgetExceeded (402); anything else is logged and returned as the generic
+ *  tool error so no server detail leaks. Detection is by CAUSE (mirrors
+ *  budgetExit), so it catches a root trip however it surfaced. */
+function errorResult(err, logger, what) {
+    const cause = readCause(err);
+    if (cause?.kind === "guardTrip") {
+        logger.error(`${what}: ${formatBudgetExceeded(cause)}`);
+        return budgetExceeded(cause);
+    }
+    logger.error(`${what} threw: ${errorMessage(err)}`);
+    return fail(TOOL_ERROR_MESSAGE);
+}
 async function callFunction(fn, body, logger) {
     try {
         const result = await fn.invoke(toArgs(body));
         return ok(result);
     }
     catch (err) {
-        logger.error(`function ${fn.name} threw: ${errorMessage(err)}`);
-        return fail(TOOL_ERROR_MESSAGE);
+        return errorResult(err, logger, `function ${fn.name}`);
     }
 }
 async function callNode(node, body, hasInterrupts, logger) {
@@ -40,8 +72,7 @@ async function callNode(node, body, hasInterrupts, logger) {
         return ok(result.data);
     }
     catch (err) {
-        logger.error(`node ${node.name} threw: ${errorMessage(err)}`);
-        return fail(TOOL_ERROR_MESSAGE);
+        return errorResult(err, logger, `node ${node.name}`);
     }
 }
 async function resumeInterrupts(respondToInterrupts, hasInterrupts, body, logger) {
@@ -62,8 +93,7 @@ async function resumeInterrupts(respondToInterrupts, hasInterrupts, body, logger
         return ok(result.data);
     }
     catch (err) {
-        logger.error(`resume threw: ${errorMessage(err)}`);
-        return fail(TOOL_ERROR_MESSAGE);
+        return errorResult(err, logger, "resume");
     }
 }
 const FUNCTION_ROUTE = /^\/function\/([^/]+)$/;

package/dist/scripts/agency.js

@@ -8,6 +8,9 @@ import { runDeploy } from "../lib/cli/remote/commands/deploy.js";
 import { runLs } from "../lib/cli/remote/commands/ls.js";
 import { runCall } from "../lib/cli/remote/commands/call.js";
 import { runOpen } from "../lib/cli/remote/commands/open.js";
+import { runWhoami } from "../lib/cli/remote/commands/whoami.js";
+import { runProjectsList, runProjectsCreate } from "../lib/cli/remote/commands/projects.js";
+import { runKeysList, runKeysCreate } from "../lib/cli/remote/commands/keys.js";
 import { lintSource } from "../lib/linter/registry.js";
 import { formatFindings } from "../lib/cli/lint.js";
 import { resolveBudget } from "../lib/cli/budget.js";
@@ -306,6 +309,49 @@ export function createProgram(deps = {}) {
         .command("open")
         .description("Open the linked agent's project page in a browser")
         .action(() => runOpen(getConfigContext()));
+    const HOST_OPTION = "--host <origin>";
+    const HOST_DESC = "statelog host (overrides agency.json log.host)";
+    const API_KEY_ENV_OPTION = "--api-key-env <name>";
+    const API_KEY_ENV_DESC = "env var to read the API key from (default: STATELOG_API_KEY)";
+    remoteCmd
+        .command("whoami")
+        .description("Show the authenticated statelog user")
+        .option(HOST_OPTION, HOST_DESC)
+        .option(API_KEY_ENV_OPTION, API_KEY_ENV_DESC)
+        .action((opts) => runWhoami(opts, getConfigContext()));
+    const projectsCmd = remoteCmd
+        .command("projects")
+        .description("List or create statelog projects (account-scoped key)");
+    projectsCmd
+        .command("list", { isDefault: true })
+        .description("List the account's projects")
+        .option(HOST_OPTION, HOST_DESC)
+        .option(API_KEY_ENV_OPTION, API_KEY_ENV_DESC)
+        .action((opts) => runProjectsList(opts, getConfigContext()));
+    projectsCmd
+        .command("create <project_id>")
+        .description("Create a project")
+        .requiredOption("--name <name>", "human-readable project name")
+        .option("--description <text>", "optional project description")
+        .option(HOST_OPTION, HOST_DESC)
+        .option(API_KEY_ENV_OPTION, API_KEY_ENV_DESC)
+        .action((projectId, opts) => runProjectsCreate(projectId, opts, getConfigContext()));
+    const keysCmd = remoteCmd
+        .command("keys")
+        .description("List or create statelog API keys (account-scoped key)");
+    keysCmd
+        .command("list", { isDefault: true })
+        .description("List the account's API keys")
+        .option(HOST_OPTION, HOST_DESC)
+        .option(API_KEY_ENV_OPTION, API_KEY_ENV_DESC)
+        .action((opts) => runKeysList(opts, getConfigContext()));
+    keysCmd
+        .command("create <name>")
+        .description("Create a project-scoped API key")
+        .requiredOption("--project <slug>", "project slug the key is scoped to")
+        .option(HOST_OPTION, HOST_DESC)
+        .option(API_KEY_ENV_OPTION, API_KEY_ENV_DESC)
+        .action((name, opts) => runKeysCreate(name, opts, getConfigContext()));
     const traceCmd = program
         .command("trace")
         .description("Trace-related commands");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agency-lang",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "The Agency language",
   "main": "./dist/lib/index.js",
   "bin": {