@agent-native/core 0.130.2 → 0.131.3

package/docs/content/recurring-jobs.mdx

@@ -1,19 +1,27 @@
 ---
 title: "Recurring Jobs"
-description: "Cron-scheduled prompts the agent runs on its own — daily digests, weekly reports, hourly polling."
+description: "Legacy compatibility reference for scheduled automations, cron execution, organization scope, and advanced job fields."
 ---
 
 # Recurring Jobs
 
-A **recurring job** is a prompt that runs on a cron schedule. It's how the agent does things on its own: "every morning at 7 summarize my overnight emails," "every Monday post last week's signup numbers to Slack," "every hour sweep for stale drafts and delete them."
+A **recurring job** is the legacy name for a **scheduled automation**: a prompt
+that runs on a cron schedule. New product guidance uses
+[Automations](/docs/automations) as the umbrella, with **Scheduled** and
+**Event** as trigger types.
 
-Recurring jobs fire on a clock. To react to _events_ (a booking created, an email received) — same `jobs/` file format plus conditions — see [Automations](/docs/automations).
+The Jobs name remains in file paths, APIs, and tools for compatibility.
+`manage-jobs` is schedule-only; new Scheduled and Event work uses
+`manage-automations`, including organization scope, model overrides, and MCP
+allowlists. This page remains the compatibility and scheduler reference.
 
 Jobs live in [Agent Resources](/docs/agent-resources) at `jobs/<name>.md` — just a Markdown file with YAML frontmatter. No registration, no wiring. Drop the file in and the framework picks it up.
 
 <Callout id="doc-block-rj1" tone="info">
 
-**New to recurring jobs?** Jump to [Creating a job](#creating) — most people create one by asking the agent or with the Resources tab `+` menu, not by hand-editing the file format below.
+**Creating new scheduled work?** Use the
+[Automations workflow](/docs/automations#creating). Continue here when you need
+the legacy `manage-jobs` API, delivery metadata, or scheduler internals.
 
 </Callout>
 
@@ -66,6 +74,7 @@ That's it. The body is a prompt the agent runs at each scheduled firing. The age
 | `lastStatus` | `"success"` \| `"error"` \| … | _(managed)_  | Latest outcome.                                                                                        |
 | `lastError`  | string                        | _(managed)_  | Error message if the last run failed.                                                                  |
 | `nextRun`    | ISO timestamp                 | _(managed)_  | Computed from `schedule`; used by the scheduler to decide when to fire next.                           |
+| `model`      | model id                      | _(default)_  | Optional model override for this automation.                                                           |
 | `mcpTools`   | array of MCP tool names       | _(none)_     | Optional explicit allowlist such as `mcp__server__tool`; credentials stay in the connected MCP grant.  |
 
 The `last*` and `nextRun` fields are written by the scheduler. You can read them to see the history, but don't edit them by hand — the next run will overwrite.
@@ -90,12 +99,13 @@ and external ids, a short citation, and the recording URL. Do not import the
 full transcript.
 ```
 
-The job stores tool names, not MCP URLs, access tokens, or OAuth refresh
-tokens. At run time, the framework resolves the connected grant in the job's
-creator or organization request context and exposes only the allowlisted
-tools. Keep the list narrow, and use an idempotent app action for the final
-import so overlapping runs do not create duplicates. See [MCP Clients](/docs/mcp-clients)
-for connection and OAuth setup.
+The automation stores tool names, not MCP URLs, access tokens, or OAuth refresh
+tokens. At run time, the shared background runner resolves the connected grant
+in the creator and organization request context and exposes only the
+allowlisted tools. A missing configured tool fails the run rather than widening
+access. Keep the list narrow, and use an idempotent app action for the final
+import so overlapping runs do not create duplicates. See
+[MCP Clients](/docs/mcp-clients) for connection and OAuth setup.
 
 ## Cron syntax {#cron}
 
@@ -115,9 +125,11 @@ The framework includes cron utilities (`isValidCron()` and `describeCron()`) for
 
 ## Creating a job {#creating}
 
-### From the Resources tab
+### From the Automations UI
 
-`+` → **Scheduled Task** in the Resources tab. Fill in the prompt and schedule. Saves as `jobs/<slug>.md` and starts running on the next matching tick.
+Open **Automations** on the full-page Agent surface, then create a
+**Scheduled** automation. The stable compatibility URL is `/agent#jobs`; the
+hash does not change when the visible tab name changes.
 
 ### By asking the agent
 
@@ -147,7 +159,7 @@ Summarize overnight emails.`,
 
 The scheduler is a framework plugin (the internal `processRecurringJobs()` routine) that runs in-process: a `setInterval` fires every 60 seconds (with a 10-second startup delay) inside the agent chat plugin, wherever the server is running.
 
-<Diagram id="doc-block-14nqnkx" title="One scheduler tick" summary="Every 60s the scheduler finds due jobs, runs each as a fresh agent thread, and writes the outcome back to the job file.">
+<Diagram id="doc-block-14nqnkx" title="One scheduler tick" summary="Every 60s the scheduler finds due jobs, then sends them through the same background execution lifecycle as event automations.">
 
 ```html
 <div class="sched">
@@ -170,8 +182,8 @@ The scheduler is a framework plugin (the internal `processRecurringJobs()` routi
   <div class="diagram-card accent">
     <span class="diagram-pill accent">3 &middot; run</span
     ><small class="diagram-muted"
-      >fresh agent thread, job body as the user message &mdash; actions, SQL,
-      A2A, email</small
+      >shared runner validates identity and resolves the model, MCP allowlist,
+      continuation, delivery, and usage</small
     >
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
@@ -223,13 +235,18 @@ The scheduler is a framework plugin (the internal `processRecurringJobs()` routi
 
 ## Debugging a job {#debugging}
 
-- Open `jobs/<name>.md` in Agent Resources — the frontmatter shows `lastRun`, `lastStatus`, `lastError`, `nextRun`.
+- Open the automation's details in **Automations**, or inspect
+  `jobs/<name>.md` in Agent Resources — the frontmatter shows `lastRun`,
+  `lastStatus`, `lastError`, and `nextRun`.
 - **Test it without waiting:** there's no force-fire tool. To exercise the same work on demand, either paste the job's prompt into the agent chat and let it run there, or temporarily set the schedule to the next minute so the scheduler picks it up on the next tick (then restore the real cron). This only works if the scheduler is actually running — see the local-dev caveat above; set `AGENT_NATIVE_ENABLE_LOCAL_RECURRING_JOBS=1` first if you're testing on localhost.
 - **Pause it:** flip `enabled: false`. The file stays put, just stops running.
 
 ## Agent tool {#agent-tool}
 
-A single `manage-jobs` tool is registered in every template. The `action` parameter selects the operation:
+`manage-jobs` is the compatibility tool for existing schedule-only
+integrations. New Scheduled and Event automations—including organization
+scope, model overrides, and MCP allowlists—use `manage-automations`. The
+`action` parameter selects the legacy operation:
 
 | Action   | Parameters                                                                             | Purpose                                                      |
 | -------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
@@ -240,7 +257,12 @@ A single `manage-jobs` tool is registered in every template. The `action` parame
 
 `model` is optional on both `create` and `update` — pass a model id to override the channel/app/engine default for that one routine.
 
-**Personal vs shared scope.** Each job lives in either personal scope (runs as and is visible only to the creator) or shared/org scope (runs on behalf of the creator but is visible to org members). The `scope` and `runAs` parameters control this at create time. Org admins can update or delete any shared job; non-admin members can only manage their own.
+**Personal vs shared scope.** Each automation lives in either personal scope
+(runs as and is visible only to the creator) or organization scope (visible to
+org members, but runs as the creator). Organization administrators can update
+or delete shared definitions but cannot change the creator identity. Before
+each organization run, the framework verifies that the creator still exists
+and remains a member; otherwise it does not execute.
 
 ## Different from the scheduling package {#vs-scheduling-package}
 
@@ -253,7 +275,7 @@ Recurring jobs are "how do I make the agent act on its own?" The scheduling pack
 
 ## What's next
 
-- [**Automations**](/docs/automations) — add event triggers and conditions to the same `jobs/` format
+- [**Automations**](/docs/automations) — the primary Scheduled/Event product model and management workflow
 - [**Agent Resources**](/docs/agent-resources) — where jobs live alongside skills, memory, and custom agents
 - [**Actions**](/docs/actions) — the tools a job calls
 - [**MCP Clients**](/docs/mcp-clients) — connect remote or local MCP tools and OAuth grants

package/docs/content/template-dispatch-operations.mdx

@@ -1,15 +1,26 @@
 ---
-title: "Operating the workspace: jobs, Dreams, and the operator console"
-description: "Recurring jobs, the Dreams memory review loop, the /operations console's Monitoring and Database tabs, and where to look for thread history, change history, and usage."
+title: "Operating the workspace: automations, Dreams, and the operator console"
+description: "Scheduled automations, the Dreams memory review loop, the /operations console's Monitoring and Database tabs, and where to look for thread history, change history, and usage."
 ---
 
-# Operating the workspace: jobs, Dreams, and the operator console
+# Operating the workspace: automations, Dreams, and the operator console
 
-Once Dispatch is coordinating a workspace, this is where you keep it healthy day to day: recurring jobs, the Dreams review loop that watches how agents are actually doing, and the operator console for monitoring, database admin, thread debugging, audit history, and usage. It's for whoever runs the workspace.
+Once Dispatch is coordinating a workspace, this is where you keep it healthy day to day: scheduled automations, the Dreams review loop that watches how agents are actually doing, and the operator console for monitoring, database admin, thread debugging, audit history, and usage. It's for whoever runs the workspace.
 
-## Scheduled jobs hub {#jobs}
+## Automations hub {#jobs}
 
-Cross-app [recurring jobs](/docs/recurring-jobs) live here: "every weekday at 7, pull yesterday's key metrics from analytics and draft a morning summary email." The **Automations** page shows enabled state, last run, next run, and last error for every job, sourced from the underlying `jobs/*.md` schedules, and lets you enable or disable a job without editing files by hand. A failed job's row links straight to **Troubleshoot in Thread Debug**. To create one, describe what you want automated in the composer — personal or organization scope — and the agent turns it into a job with `manage-automations`.
+Cross-app scheduled automations live here: "every weekday at 7, pull
+yesterday's key metrics from analytics and draft a morning summary email." The
+**Automations** page shows enabled state, last run, next run, and last error,
+sourced from the underlying `jobs/*.md` resources, and lets you enable or
+disable scheduled work without editing files by hand. A failed row links
+straight to **Troubleshoot in Thread Debug**.
+
+Describe new scheduled work in the composer and the agent creates it. Personal
+automations use the trigger-aware `manage-automations` workflow. Existing
+organization-scoped schedules remain legacy recurring jobs managed through
+`manage-jobs`; event-triggered and trigger-aware automations do not support
+organization scope today.
 
 ## Dreams {#dreams}
 
@@ -156,5 +167,6 @@ Use these for concrete thread, change-history, and usage investigations instead
 - [**Dispatch**](/docs/template-dispatch) — the workspace control plane overview
 - [**Secrets, integrations, and workspace connections**](/docs/template-dispatch-vault-integrations) — the vault and provider integrations
 - [**Messaging, routing, and approvals**](/docs/template-dispatch-messaging-routing) — channels and the approval queue
-- [**Recurring Jobs**](/docs/recurring-jobs) — scheduled tasks Dispatch runs
+- [**Automations**](/docs/automations) — scheduled and event-triggered tasks
+- [**Recurring Jobs**](/docs/recurring-jobs) — legacy scheduled-job compatibility and organization scope
 - [**Observability**](/docs/observability) — the dashboard the Monitoring tab reuses

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.130.2",
+  "version": "0.131.3",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -72,8 +72,10 @@
     "./server/sse": "./dist/server/sse.js",
     "./server/short-lived-token": "./dist/server/short-lived-token.js",
     "./integrations": "./dist/integrations/index.js",
+    "./integrations/computer-supervision": "./dist/integrations/computer-supervision.js",
     "./integrations/runtime": "./dist/integrations/runtime.js",
     "./ingestion": "./dist/ingestion/index.js",
+    "./browser-context": "./dist/browser-context/index.js",
     "./search-utils": "./dist/search-utils/index.js",
     "./search": "./dist/search/index.js",
     "./embeddings": "./dist/embeddings/index.js",
@@ -394,7 +396,7 @@
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.5.1",
-    "@agent-native/toolkit": "^0.10.12"
+    "@agent-native/toolkit": "^0.11.1"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/a2a/types.ts

@@ -85,6 +85,12 @@ export interface AgentSkill {
   requiresAuth?: boolean;
   isConsequential?: boolean;
   publicAgent?: PublicAgentActionConfig;
+  /**
+   * JSON Schema for the action's `input`. Advertising a skill without it tells a
+   * caller the action exists but not how to call it, so callers invoke with `{}`
+   * and get a required-property error back.
+   */
+  inputSchema?: Record<string, unknown>;
 }
 
 export interface AgentCapabilities {

package/src/action.ts

@@ -121,6 +121,12 @@ export interface ActionRunContext {
   /** Concrete execution id for this agent-loop attempt. */
   runId?: string;
   turnId?: string;
+  /**
+   * Stable key for this exact tool call when the agent loop accepted a human
+   * approval grant. This is trusted loop metadata; action input can never set
+   * it.
+   */
+  approvedToolCallKey?: string;
 }
 
 /**
@@ -194,6 +200,52 @@ export interface PublicAgentActionConfig {
   isConsequential?: boolean;
   title?: string;
   description?: string;
+  /**
+   * Allow a sibling app to invoke this action over A2A even though its input is
+   * a free-form query or program (`sql`, `query`, `code`, `script`,
+   * `expression`).
+   *
+   * Off by default and rarely correct. The app that owns the data owns its
+   * schema, data dictionary, and reference queries; a caller has none of that,
+   * so passing raw SQL across apps makes every caller reimplement the owner's
+   * schema knowledge and silently break when it changes. Prefer a semantic
+   * action the owner implements, or let the caller ask in natural language and
+   * form the query yourself.
+   */
+  allowRawQueryInput?: boolean;
+}
+
+export type ActionPlanModeEffect = "read" | "write" | "unknown";
+
+/**
+ * Declares how an action behaves in Plan mode.
+ *
+ * A fixed `"read"` effect makes the action callable while planning. Mixed
+ * tools can classify each call from its arguments; only a returned `"read"`
+ * is allowed. Classifier errors and `"unknown"` fail closed.
+ */
+export interface ActionPlanModeConfig<TInput = unknown> {
+  effect: ActionPlanModeEffect | ((args: TInput) => ActionPlanModeEffect);
+  /**
+   * Optional argument values advertised and accepted in Plan mode. This keeps
+   * mixed-tool schemas focused on their read variants while the runtime gate
+   * independently rechecks every invocation.
+   */
+  allowedValues?: Record<string, readonly string[]>;
+  /**
+   * Optional Plan-mode input-property allowlist. Other properties are hidden
+   * from the advertised schema and rejected by the runtime gate.
+   */
+  allowedProperties?: readonly string[];
+  /** Properties required by the Plan-mode schema. */
+  requiredProperties?: readonly string[];
+  /**
+   * Properties hidden and rejected in Plan mode (for example persistence or
+   * notification options on an otherwise read-only request).
+   */
+  omittedProperties?: readonly string[];
+  /** Additional Plan-mode guidance appended to the tool description. */
+  description?: string;
 }
 
 /** A deep link an external agent (MCP / A2A) can surface to the user so they
@@ -413,6 +465,9 @@ interface DefineActionWithSchema<
    *  must not run during Plan mode because they perform substantive work
    *  rather than lightweight inspection. Defaults to allowed when read-only. */
   allowInPlanMode?: boolean;
+  /** First-class Plan-mode effect policy. Prefer this over `readOnly` for
+   *  mixed tools whose effect depends on their arguments. */
+  planMode?: ActionPlanModeConfig<StandardSchemaV1.InferInput<TSchema>>;
   /** If true, the agent may execute this action concurrently with other
    *  read-only or parallel-safe tool calls emitted in the same model turn.
    *  Only set this for mutating actions that are internally concurrency-safe
@@ -567,6 +622,9 @@ interface DefineActionWithParams<
   /** Set false for read-only tools that should stay available in Act mode but
    *  must not run during Plan mode. See the schema overload above. */
   allowInPlanMode?: boolean;
+  /** First-class Plan-mode effect policy. Prefer this over `readOnly` for
+   *  mixed tools whose effect depends on their arguments. */
+  planMode?: ActionPlanModeConfig<InferParams<TParams>>;
   /** If true, the agent may execute this action concurrently with other
    *  read-only or parallel-safe tool calls emitted in the same model turn. */
   parallelSafe?: boolean;
@@ -639,6 +697,7 @@ export interface ActionDefinition<TInput, TReturn> {
   readonly agentTool?: boolean;
   readonly readOnly?: boolean;
   readonly allowInPlanMode?: boolean;
+  readonly planMode?: ActionPlanModeConfig<TInput>;
   readonly parallelSafe?: boolean;
   readonly dedupe?: boolean;
   readonly toolCallable?: boolean;
@@ -900,6 +959,15 @@ export function defineAction(options: any) {
     ...(typeof options.allowInPlanMode === "boolean"
       ? { allowInPlanMode: options.allowInPlanMode }
       : {}),
+    ...(options.planMode &&
+    typeof options.planMode === "object" &&
+    !Array.isArray(options.planMode) &&
+    (typeof options.planMode.effect === "function" ||
+      options.planMode.effect === "read" ||
+      options.planMode.effect === "write" ||
+      options.planMode.effect === "unknown")
+      ? { planMode: options.planMode }
+      : {}),
     ...(typeof parallelSafe === "boolean" ? { parallelSafe } : {}),
     ...(typeof dedupe === "boolean" ? { dedupe } : {}),
     ...(typeof toolCallable === "boolean" ? { toolCallable } : {}),

package/src/agent/engine/builder-engine.ts

@@ -720,9 +720,9 @@ async function* parseJsonlStream(
               Boolean(explicitErrMsg) &&
               !isCredentialAuthError &&
               isBuilderCredentialAuthError(String(errMsg));
-            // Anthropic's bare "Connection error." often arrives here with no
-            // gateway code. Tag it as a network error so in-run retries and
-            // run-level resume treat it as transient instead of terminal.
+            // Providers can report a bare "Connection error." or AI SDK's
+            // retry-wrapped "Cannot connect to API" without a gateway code.
+            // Tag both as network errors so retries can recover the turn.
             const isProviderConnectionError =
               typeof explicitErrMsg === "string" &&
               isProviderConnectionErrorMessage(String(explicitErrMsg));
@@ -1138,7 +1138,11 @@ function isBuilderGatewayNetworkError(err: unknown): boolean {
 }
 
 function isProviderConnectionErrorMessage(message: string): boolean {
-  return message.trim().toLowerCase() === "connection error.";
+  const normalized = message.trim().toLowerCase();
+  return (
+    normalized === "connection error." ||
+    normalized.includes("cannot connect to api:")
+  );
 }
 
 function captureBuilderGatewayTransportError(