@agent-native/core 0.152.0 → 0.153.0

package/dist/templates/workspace-core/.agents/skills/turn-into-app/references/spreadsheet-source.md

@@ -0,0 +1,148 @@
+# Spreadsheet source review
+
+Use this reference after a workbook upload or Google Sheets link is supplied to
+`/turn-into-app`. It defines the bounded review contract before app creation.
+
+## 1. Establish the source boundary
+
+Record the source before interpreting it:
+
+| Field        | Record                                                                            |
+| ------------ | --------------------------------------------------------------------------------- |
+| Source kind  | `xlsx`, `xls`, `csv`, or Google Sheets URL                                        |
+| Provenance   | Original file name or spreadsheet ID and URL; never credentials or workbook bytes |
+| Access       | Upload preview, authenticated provider read, or unavailable                       |
+| Coverage     | Worksheet names, selected range(s), row/column bounds, and sample counts          |
+| Completeness | Complete within the requested bound, partial, truncated, unreadable, or empty     |
+| Refresh      | One-time snapshot or live refreshable source                                      |
+
+For an uploaded XLS/XLSX file, the framework preview contains worksheet names,
+dimensions, and representative displayed values within bounds. It does not
+currently preserve cell fills or font colors in that text preview. Treat the
+original workbook as the formatting authority only when a tool actually returns
+cell formatting metadata. Never describe a text-only upload as style-verified.
+
+For a Google Sheets URL:
+
+1. Parse the spreadsheet ID and preserve the original URL as provenance.
+2. Use the authenticated `google_drive` provider path. Inspect
+   `provider-api-catalog` first, use `provider-api-docs` if the endpoint or
+   fields are uncertain, and then call `provider-api-request`.
+3. Read spreadsheet metadata and only bounded worksheet/range data. Request
+   formatting metadata when the I/O decision depends on colors, including
+   `userEnteredFormat.backgroundColor` and
+   `userEnteredFormat.textFormat.foregroundColor` where the provider supports
+   it. Do not use a public export URL to bypass access.
+4. Preserve the spreadsheet ID, worksheet title, A1 range, account/connection
+   choice without secrets, row limits, and refresh behavior in the brief.
+
+Keep provider responses bounded. For large sheets, stage or save the response
+and reduce it with the available dataset/code tools. A failed page, truncated
+response, or unavailable connection is not an empty sheet.
+
+## 2. Infer cells and ranges, then show the evidence
+
+Classify source material into three separate buckets. Include representative
+cell addresses or ranges and the evidence behind each classification.
+
+| Bucket             | Default signal                                                                                                     | App treatment                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Inputs             | Yellow cell background, editable assumptions, user-entered constants, or labels such as `assumption` / `driver`    | Editable controls or bounded source parameters                         |
+| Outputs            | Blue text, formula-derived result cells, summary blocks, or labels such as `forecast` / `recommendation`           | Read-only results, charts, recommendations, exports, or review actions |
+| Static historicals | Black text used intentionally for prior-period/source records, raw rows, or labels such as `actual` / `historical` | Read-only context; never turn into editable inputs by default          |
+
+These are conventions, not permission to guess. A default black font with no
+explicit style metadata is not enough to label a range as historical. Resolve
+conflicts using labels, formulas, neighboring headers, repeated patterns, and
+the user's stated goal. If the evidence still conflicts, lower confidence and
+ask the user to confirm the proposed mapping.
+
+Keep source cells and app behavior distinct:
+
+- `Source inputs` are the workbook cells or ranges the user is expected to
+  change or refresh.
+- `Source outputs` are the workbook cells or ranges the source already derives
+  or presents.
+- `Static historicals` are context the app may filter, compare, or summarize,
+  but should not edit.
+- `App outputs` are the new app's visible results, saved records, exports,
+  alerts, or downstream handoffs. Do not invent these until the repeatable job
+  or user confirmation makes them clear.
+
+## 3. Offer candidate apps, not a tab dump
+
+Group related worksheets into candidate repeatable jobs. A candidate should
+have a recognizable user, trigger, inputs, transformation or judgment, and
+outputs. Utility tabs such as lookups, raw imports, instructions, pivots, and
+calculation helpers can support a candidate without becoming destinations.
+
+Present a compact Q&A review with multi-select options. In generated app code,
+use `askUserQuestion` from `@agent-native/core/client/agent-chat` with
+`allowMultiple: true`, stable candidate IDs as option values, and
+`allowFreeText: true` for corrections. It renders inline in the agent panel;
+do not build a custom modal. Each option should fit in a scannable row or
+choice card:
+
+```text
+Candidate: Pipeline forecast
+Uses: Assumptions, Historical Pipeline, Forecast
+Inputs: yellow assumptions in Assumptions!B4:B12 (high confidence)
+Outputs: blue forecast summary in Forecast!B3:H10 (medium confidence)
+Historical context: Historical Pipeline!A1:K500
+Question: Confirm that forecast assumptions should be editable?
+```
+
+Mark the strongest recommendation with `recommended: true`, but do not silently
+select it. Let the user select none, one, or several candidates, correct a
+proposed tab/range, or answer the unresolved question. Keep each question to
+2-4 grouped candidate jobs; for a larger workbook, group related tabs into
+jobs rather than showing a tab dump or asking a separate question for every
+worksheet. If there is only one high-confidence candidate, keep the review
+compact and ask for confirmation only when the I/O mapping or source access is
+unclear.
+
+When several candidates are selected, pass a stable candidate ID, display name,
+source worksheet/ranges, I/O mapping, confidence, and confirmation status for
+each. The generated app should expose them as separate named left-navigation
+destinations or tabs, not merge them into an opaque dashboard and not create a
+separate workspace app for every worksheet.
+
+## 4. Confirm before building or publishing
+
+The confirmation view is a source-integrity checkpoint, not a product-design
+questionnaire. Show:
+
+- the source file or spreadsheet ID and snapshot/live choice;
+- selected candidate destinations and their source tabs/ranges;
+- editable inputs, read-only outputs, and static historical context;
+- the evidence and confidence for each mapping;
+- truncation, unreadable, missing-connection, and refresh limitations;
+- the app outputs/actions that will be created.
+
+Use clear actions such as `Confirm and build`, `Edit mapping`, and `Use a
+different source`. If the host has a structured question or multi-select UI,
+use it. Otherwise, ask one concise assistant message that presents the same
+options and requires an explicit confirmation/correction before handoff.
+
+After confirmation, the online host may call
+`start-workspace-app-creation`; the Builder run itself remains autonomous and
+must record any remaining non-blocking assumptions. In a local generated app,
+persist the confirmation state in SQL/application state and keep the user on
+the review surface while the agent builds. Never claim a full import, live
+refresh, or output write until the corresponding source/action has succeeded.
+
+## 5. Failure and recovery states
+
+Keep these states distinct in the review and in the handoff:
+
+- `unreadable` - parser/provider could not read the source;
+- `partial` - only some worksheets, ranges, rows, or pages were read;
+- `truncated` - the bounded preview ended before full coverage;
+- `empty` - the requested readable range contains no values;
+- `not-connected` - authenticated Google access is required but unavailable;
+- `confirmed` - the user approved the candidate and I/O mapping.
+
+For unreadable or not-connected sources, request a CSV/XLSX export or the
+required connection. For partial or truncated sources, continue only with a
+clearly bounded snapshot or ask for a narrower range. Do not coerce any of
+these states into a successful empty source.

package/dist/templates/workspace-core/.agents/skills/workspace-conventions/SKILL.md

@@ -20,8 +20,9 @@ resources, or looking up framework APIs.
 Read `agent-native-docs` for the lookup workflow (`framework-search` first, then
 the focused `docs-search` / `source-search` readers, and the `rg` fallback).
 
-The workspace-specific slugs it does not list are `workspace`,
-`multi-app-workspace`, and `feature-flags`. Use package docs for framework APIs,
+The workspace-specific slugs it does not list are `workspace` and
+`multi-app-workspace`. Feature flags and other specialized workflows are
+optional; read their skill only when the app uses them. Use package docs for framework APIs,
 the package corpus for reusable framework/template patterns, and this
 `AGENTS.md` plus `.agents/skills/` for workspace-specific conventions.
 

package/dist/templates/workspace-core/AGENTS.md

@@ -11,16 +11,22 @@ Read the matching skill in `.agents/skills/` before working in that area.
 | Skill | Read before |
 | --- | --- |
 | `workspace-conventions` | Shared vs app-owned code, file/blob storage, env and secrets, scratch files, Dispatch Resources |
-| `adding-workspace-apps` | Creating, scaffolding, mounting, or branding an app under `apps/<app-name>` |
+| `adding-a-feature` | Adding a cross-cutting feature or capability |
 | `agent-native-docs` | Looking up version-matched framework docs, slugs, or the bundled source corpus |
 | `agent-native-toolkit` | Building workspace or agent UI, app chrome, settings, sharing, or collaboration |
 | `customizing-agent-native` | Adapting, overriding, or ejecting shared framework UI |
 | `delegate-to-agent` | Building agent-driven UI or any "AI" feature |
 | `actions` | Adding or changing an app operation the agent and UI share |
-| `composable-mini-apps` | Cross-app workflows, headless mini-apps, and A2A handoffs |
+| `frontend-design` | Any user-facing UI change |
+| `real-time-sync` | Keeping UI queries current after agent or action writes |
 | `shadcn-ui` | Adding, updating, or debugging a shadcn/ui primitive |
 | `security`, `sharing` | Access scoping, ownable data, and sharing user-authored resources |
-| `automations` | Event-triggered or scheduled background work (with `recurring-jobs`) |
+| `secrets`, `storing-data` | Credentials or persisted application data |
+| `self-modifying-code` | Agent-editable app source and protected paths |
+
+This is the complete default inherited set. Feature flags, translations,
+changelogs, integrations, automations, A2A workflows, and release/promotion
+helpers stay available as opt-in skills for the apps that use them.
 
 ## Shared Context
 

package/dist/templates/workspace-root/AGENTS.md

@@ -6,6 +6,12 @@ in `apps/<app>/AGENTS.md`; shared cross-app behavior belongs in
 The root `.agents/skills` path points at the shared package's skills so local
 coding agents can discover the same workspace-wide guidance from the root.
 
+The inherited skill set is intentionally small: actions, data, security,
+secrets, sync, shared UI, agent delegation, and workspace conventions. Skills
+for feature flags, translations, changelogs, providers, automations, release
+workflows, and other specialized work are opt-in. Add an optional skill to the
+workspace core or the app that needs it; do not copy it into every app.
+
 ## Framework Docs Lookup
 
 Version-matched Agent Native docs ship with `@agent-native/core` in
@@ -22,7 +28,8 @@ template patterns ships in `node_modules/@agent-native/core/corpus`.
   and `node_modules/@agent-native/core/dist/` for framework internals.
 - For advanced workspace features, start with `workspace`, `multi-app-workspace`,
   `a2a-protocol`, `pure-agent-apps`, `automations`, `recurring-jobs`,
-  `external-agents`, `mcp-protocol`, `feature-flags`, `sharing`, and `security`.
+  `external-agents`, `mcp-protocol`, `sharing`, and `security`. These are
+  optional skills; read them only when the app or workspace uses that feature.
 
 Use package docs for framework APIs, the package corpus for reusable
 template patterns, and `packages/shared/AGENTS.md` plus
@@ -45,6 +52,24 @@ After a manual core bump only, `pnpm skills:update` (or
 refreshes framework-provided shared skills and repairs `CLAUDE.md` /
 `.claude/skills` compatibility links.
 
+## Lightweight defaults
+
+New apps use English as the source locale and do not generate changelog
+entries. To opt into additional translations or changelog generation, edit
+`agent-native.config.ts` at the workspace root:
+
+```ts
+import { defineAgentNativeConfig } from "@agent-native/core";
+
+export default defineAgentNativeConfig({
+  translations: { locales: ["en-US", "es-ES"] },
+  changelog: { enabled: true },
+});
+```
+
+An app-local config can override the workspace policy when only one app needs
+an additional locale or changelog.
+
 ## Core Agent Rule
 
 - All AI/LLM behavior goes through the app's agent chat. UI and server code

package/dist/templates/workspace-root/agent-native.config.ts

@@ -0,0 +1,8 @@
+import { defineAgentNativeConfig } from "@agent-native/core";
+
+export default defineAgentNativeConfig({
+  // English is the source locale. Add supported locale codes here when this
+  // workspace is intentionally translated.
+  translations: { locales: ["en-US"] },
+  changelog: { enabled: false },
+});

package/dist/triggers/actions.js

@@ -279,7 +279,7 @@ export function createAutomationToolEntries(getCurrentUser, appId) {
 
 - **list-events**: List all registered event types that automations can subscribe to. Returns event names, descriptions, and payload schemas. Call this BEFORE defining an automation to discover available events.
 - **list**: List all automations (triggers). Shows trigger, status, model, MCP allowlist, and delivery metadata. Optional params: scope, domain, enabled_only.
-- **define**: Create a new automation. IMPORTANT: Always confirm with the user before calling — show them a summary of what will be created. Required params: name, trigger_type, body. Optional: scope, event, schedule, timezone, condition, mode, domain, delegated_policy_id, model, mcpTools.
+- **define**: Create a new automation. IMPORTANT: Always confirm with the user before calling — show them a summary of what will be created. Required params: name, trigger_type, body. Optional: scope, event, schedule, timezone, condition, mode, domain, delegated_policy_id, model, mcpTools. A scheduled automation with no schedule defaults to once per hour; use an event trigger when it should run only when something changes.
 - **update**: Update an existing automation's settings without changing its creator (enabled, schedule, timezone, condition, body, policy, model, MCP allowlist). Required param: name. Use the same scope it was created in.
 - **delete**: Delete an automation. Always confirm with the user first. Required param: name.
 - **fire-test**: Fire a test event to validate automations. Emits a test.event.fired event. Optional param: data (JSON string).
@@ -316,7 +316,7 @@ export function createAutomationToolEntries(getCurrentUser, appId) {
                         },
                         schedule: {
                             type: "string",
-                            description: 'For schedule triggers: cron expression. Example: "0 9 * * 1-5" (9am weekdays).',
+                            description: 'For schedule triggers: cron expression. If omitted, defaults to "0 * * * *" (once per hour). Example: "0 9 * * 1-5" (9am weekdays).',
                         },
                         condition: {
                             type: "string",

package/dist/usage/actions/get-usage-alerts.d.ts

@@ -0,0 +1,5 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    scope?: "user" | "workspace";
+    appId?: string;
+}, import("../alerts-store.js").UsageAlertRule[]>;
+export default _default;

package/dist/usage/actions/get-usage-alerts.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { listUsageAlerts } from "../alerts-store.js";
+export default defineAction({
+    description: "List the current user's or active organization's LLM usage alert rules, including the current window, threshold status, delivery channels, and recent dismissal state.",
+    http: { method: "GET" },
+    schema: z.object({
+        scope: z.enum(["user", "workspace"]).default("user"),
+        appId: z.string().trim().max(200).nullable().optional(),
+    }),
+    run: async ({ scope, appId }, ctx) => {
+        if (!ctx?.userEmail)
+            throw new Error("Not authenticated.");
+        return listUsageAlerts({ scope: scope, appId }, { ownerEmail: ctx.userEmail, orgId: ctx.orgId });
+    },
+});

package/dist/usage/actions/get-usage-metrics.d.ts

@@ -0,0 +1,7 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    sinceDays?: unknown;
+    scope?: "me" | "workspace";
+    userEmail?: string;
+    appId?: string;
+}, import("../metrics-store.js").AppUsageMetrics>;
+export default _default;

package/dist/usage/actions/get-usage-metrics.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { listAppUsageMetrics } from "../metrics-store.js";
+export default defineAction({
+    description: "Get compact, app-scoped LLM usage metrics for Settings: lookback totals, daily spend trend, top drivers, recent prompts, and user filtering.",
+    http: { method: "GET" },
+    schema: z.object({
+        sinceDays: z.coerce.number().int().min(1).max(365).default(30),
+        scope: z.enum(["me", "workspace"]).default("me"),
+        userEmail: z.string().trim().min(1).optional(),
+        appId: z.string().trim().max(200).optional(),
+    }),
+    run: async ({ sinceDays, scope, userEmail, appId }, ctx) => {
+        if (!ctx?.userEmail)
+            throw new Error("Not authenticated.");
+        return listAppUsageMetrics({ sinceDays, scope, userEmail }, {
+            ownerEmail: ctx.userEmail,
+            orgId: ctx.orgId,
+            app: ctx.appId ??
+                appId ??
+                process.env.AGENT_APP ??
+                process.env.APP_NAME ??
+                "app",
+        });
+    },
+});

package/dist/usage/actions/manage-usage-alert.d.ts

@@ -0,0 +1,14 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    operation: "dismiss" | "save" | "set-enabled";
+    scope?: "user" | "workspace";
+    ruleId?: string;
+    appId?: string;
+    unit?: "builder-credits" | "tokens" | "usd";
+    period?: "day" | "month";
+    limit?: number;
+    channels?: ("email" | "in-app")[];
+    enabled?: boolean;
+}, import("../alerts-store.js").UsageAlertMutationResult | {
+    dismissed: import("../alerts-store.js").UsageAlertMutationResult;
+}>;
+export default _default;

package/dist/usage/actions/manage-usage-alert.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { dismissUsageAlert, saveUsageAlert, setUsageAlertEnabled, } from "../alerts-store.js";
+const channel = z.enum(["in-app", "email"]);
+export default defineAction({
+    description: "Create or edit an LLM usage alert, enable or disable it, or dismiss the current alert event. Alerts can be scoped to the current user or active organization and filtered to an app.",
+    schema: z.object({
+        operation: z.enum(["save", "set-enabled", "dismiss"]),
+        scope: z.enum(["user", "workspace"]).default("user"),
+        ruleId: z.string().trim().max(200).optional(),
+        appId: z.string().trim().max(200).nullable().optional(),
+        unit: z.enum(["usd", "builder-credits", "tokens"]).optional(),
+        period: z.enum(["day", "month"]).optional(),
+        /** Display units: dollars, Builder credits, or raw tokens. */
+        limit: z.number().finite().positive().max(9_000_000_000_000).optional(),
+        channels: z.array(channel).min(1).optional(),
+        enabled: z.boolean().optional(),
+    }),
+    run: async ({ operation, scope, ruleId, appId, unit, period, limit, channels, enabled }, ctx) => {
+        if (!ctx?.userEmail)
+            throw new Error("Not authenticated.");
+        const access = { ownerEmail: ctx.userEmail, orgId: ctx.orgId };
+        const alertScope = scope;
+        if (operation === "dismiss") {
+            if (!ruleId)
+                throw new Error("ruleId is required to dismiss an alert.");
+            return {
+                dismissed: await dismissUsageAlert(ruleId, alertScope, access),
+            };
+        }
+        if (operation === "set-enabled") {
+            if (!ruleId || enabled === undefined) {
+                throw new Error("ruleId and enabled are required to change an alert.");
+            }
+            return setUsageAlertEnabled(ruleId, alertScope, enabled, access);
+        }
+        return saveUsageAlert({
+            scope: alertScope,
+            ruleId,
+            appId,
+            unit: unit,
+            period: period,
+            limit,
+            channels: channels,
+            enabled,
+        }, access);
+    },
+});

package/dist/usage/alerts-store.d.ts

@@ -0,0 +1,78 @@
+export declare const USAGE_ALERT_DEFAULT_DAILY_USD = 100;
+export declare const USAGE_ALERT_UNIT_SCALE: {
+    readonly usd: 100;
+    readonly "builder-credits": 1;
+    readonly tokens: 1;
+};
+export type UsageAlertScope = "user" | "workspace";
+export type UsageAlertUnit = "usd" | "builder-credits" | "tokens";
+export type UsageAlertPeriod = "day" | "month";
+export type UsageAlertChannel = "in-app" | "email";
+export type UsageAlertStatus = "ok" | "triggered" | "dismissed";
+export interface UsageAlertAccess {
+    ownerEmail: string;
+    orgId?: string | null;
+}
+export interface UsageAlertRule {
+    id: string;
+    appId: string | null;
+    scope: UsageAlertScope;
+    unit: UsageAlertUnit;
+    period: UsageAlertPeriod;
+    limit: number;
+    channels: UsageAlertChannel[];
+    enabled: boolean;
+    isDefault: boolean;
+    status: UsageAlertStatus;
+    current: number;
+    percent: number;
+    windowStart: number;
+    windowEnd: number;
+    dismissedAt: number | null;
+    updatedAt: number;
+}
+export interface UsageAlertEventSummary {
+    status: UsageAlertStatus;
+    current: number;
+    limit: number;
+    percent: number;
+    windowStart: number;
+    windowEnd: number;
+}
+export interface UsageAlertListOptions {
+    scope?: UsageAlertScope;
+    appId?: string | null;
+}
+export interface SaveUsageAlertInput {
+    scope: UsageAlertScope;
+    ruleId?: string;
+    appId?: string | null;
+    unit?: UsageAlertUnit;
+    period?: UsageAlertPeriod;
+    limit?: number;
+    channels?: UsageAlertChannel[];
+    enabled?: boolean;
+}
+export interface UsageAlertMutationResult {
+    rule: UsageAlertRule;
+    rules: UsageAlertRule[];
+    current: UsageAlertEventSummary | null;
+}
+export declare function listUsageAlerts(input: UsageAlertListOptions, access: UsageAlertAccess): Promise<UsageAlertRule[]>;
+export declare function saveUsageAlert(input: SaveUsageAlertInput, access: UsageAlertAccess): Promise<UsageAlertMutationResult>;
+export declare function setUsageAlertEnabled(ruleId: string, scope: UsageAlertScope, enabled: boolean, access: UsageAlertAccess): Promise<UsageAlertMutationResult>;
+export declare function dismissUsageAlert(ruleId: string, scope: UsageAlertScope, access: UsageAlertAccess): Promise<UsageAlertMutationResult>;
+interface UsageAlertEvaluationRecord {
+    ownerEmail: string;
+    app?: string;
+    orgId?: string | null;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    costCentsX100?: number;
+}
+export declare function enqueueUsageAlertEvaluation(record: UsageAlertEvaluationRecord): void;
+export declare function _resetUsageAlertStoreForTests(): void;
+export declare function _waitForUsageAlertEvaluationsForTests(): Promise<void>;
+export {};