@agent-native/core 0.149.6 → 0.151.1

package/src/templates/default/.agents/skills/delegate-to-agent/SKILL.md

@@ -49,6 +49,34 @@ sendToAgentChat({
 });
 ```
 
+### Keep user text separate from injected context
+
+Treat the visible `message` as the user's request or the shortest clear
+description of an app-initiated operation. Put context the user did not type —
+IDs, URLs, filenames, current selection or screen state, serialized records,
+upload instructions, and bounded source excerpts — in the `context` field.
+`context` is model input carried through the agent turn; it is stripped from
+the rendered user message, so do not concatenate it into `message` with labels,
+blank-line sections, or `<context>` tags yourself.
+
+Use the related surface for each kind of supporting input:
+
+| Surface | Use for |
+| --- | --- |
+| `message` | User-authored intent or a concise app action description |
+| `context` | Derived metadata and bounded text needed to carry out that intent |
+| `setAgentChatContextItem` | Context staged for a later user-submitted prompt; keep it keyed so updates replace stale context |
+| `images`, `referenceImagePaths`, attachments | Binary or visual inputs; describe only the handling instructions in `context` |
+
+If an app builds a prompt from a form, selection, upload, or editor state, keep
+the visible message short and pass the assembled details as `context`. Preserve
+the user's actual freeform text in `message` when it is the request; do not
+restate it as metadata in `context` unless the agent needs a structured copy.
+
+This boundary applies to auto-submitted turns and prefills. A hidden context
+field is not a license to send unbounded records or secrets: cap excerpts,
+prefer stable IDs and URLs, and use an action or resource lookup for full data.
+
 **From the UI, in the background:**
 
 ```ts

package/src/templates/workspace-core/.agents/skills/authentication/SKILL.md

@@ -168,10 +168,33 @@ Set `A2A_SECRET` (same value) on all apps that must verify each other's identity
 Each hosted `*.agent-native.com` app has its **own user store**, so "sign in once" is identity federation, not a shared cookie. **Dispatch is the identity authority.**
 
 - **Opt-in per app via one env var:** set `AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com` and the app shows a "Sign in with Agent-Native" option. **Unset = zero behavior change** — the whole path is dormant. Reversible at any time.
-- **Flow:** app → `GET <hub>/_agent-native/identity/authorize?app=&redirect_uri=&state=` → user logs in at Dispatch → 302 back with a short-lived (`≤5min`) `A2A_SECRET`-signed identity JWT (`sub`/`email`/`name`/`org_domain`/`scope:"identity"`). Strict `redirect_uri` allowlist (`*.agent-native.com` + localhost). App verifies the token, **JIT-links strictly by verified email** (existing same-email user → reused unchanged; new email → created), then mints a normal local session.
+- **Flow:** app → `GET <hub>/_agent-native/identity/authorize?app=&redirect_uri=&state=` → user logs in at Dispatch → 302 back with a short-lived (`≤5min`) `A2A_SECRET`-signed identity JWT (`sub`/`email`/`name`/`org_domain`/`scope:"identity"`). Canonical clients require an exact registered app ID, origin, and callback path; localhost remains available for development. App verifies the token, **JIT-links strictly by verified email** (existing same-email user → reused unchanged; new email → created), then mints a normal local session.
 - **Invariant (do not break):** identity rows are only ever **added** — never modified, renamed, or deleted. Enabling SSO logs users out, but they always log back into the **same email-matched account with data intact**. Email is the only thing that crosses the trust boundary; the app never trusts a user id, role, or org from the wire.
 - **Canary rollout:** deploy with the env unset everywhere (no-op) → set it on **one** app (mail) only → verify (logout → SSO → Dispatch → back to the same pre-existing account, data intact, direct logins still work) → expand app-by-app → rollback = unset the env on that app's deploy (instant, no data change).
 
+### Packaged Desktop workspace sign-in
+
+For canonical first-party hosted apps, the packaged Desktop SSO Canary may compose the same
+federation into one workspace sign-in. Dispatch owns the default-off
+`desktop.workspace-sso` availability flag; every app still owns its local
+session. The flag is never an auth or authorization boundary. Keep nonce,
+signature, exact origin/callback, authenticated-session, app-binding, cookie
+allowlist, revocation, and credential-custody checks unconditional. When the
+flag is Off or unreadable, Desktop must leave ordinary per-app sign-in, sign-out,
+and Settings unchanged. Never extend the broker to custom or third-party apps,
+and never expose cookies, identity tokens, or provider credentials through IPC.
+Canonical hosted apps recognize packaged Desktop requests without per-app
+identity-hub environment configuration. Ordinary browsers and self-hosted apps
+still require `AGENT_NATIVE_IDENTITY_HUB_URL`.
+Stable Desktop builds must not initialize the broker until a later release is
+separately approved.
+Treat the Canary user-agent marker only as an availability hint, never as
+remote attestation or an authentication boundary. Bind supervised acceptance
+to exact signed-artifact provenance.
+The Canary must not intercept anonymous app sign-in navigation. The user
+explicitly chooses workspace sign-in in Desktop Settings for the active
+registered app; ordinary app sign-in remains the default path.
+
 Full runbook + flow detail: [Cross-App SSO doc](/docs/cross-app-sso).
 
 ## Builder Browser Access

package/src/templates/workspace-core/.agents/skills/delegate-to-agent/SKILL.md

@@ -49,6 +49,34 @@ sendToAgentChat({
 });
 ```
 
+### Keep user text separate from injected context
+
+Treat the visible `message` as the user's request or the shortest clear
+description of an app-initiated operation. Put context the user did not type —
+IDs, URLs, filenames, current selection or screen state, serialized records,
+upload instructions, and bounded source excerpts — in the `context` field.
+`context` is model input carried through the agent turn; it is stripped from
+the rendered user message, so do not concatenate it into `message` with labels,
+blank-line sections, or `<context>` tags yourself.
+
+Use the related surface for each kind of supporting input:
+
+| Surface | Use for |
+| --- | --- |
+| `message` | User-authored intent or a concise app action description |
+| `context` | Derived metadata and bounded text needed to carry out that intent |
+| `setAgentChatContextItem` | Context staged for a later user-submitted prompt; keep it keyed so updates replace stale context |
+| `images`, `referenceImagePaths`, attachments | Binary or visual inputs; describe only the handling instructions in `context` |
+
+If an app builds a prompt from a form, selection, upload, or editor state, keep
+the visible message short and pass the assembled details as `context`. Preserve
+the user's actual freeform text in `message` when it is the request; do not
+restate it as metadata in `context` unless the agent needs a structured copy.
+
+This boundary applies to auto-submitted turns and prefills. A hidden context
+field is not a license to send unbounded records or secrets: cap excerpts,
+prefer stable IDs and URLs, and use an action or resource lookup for full data.
+
 **From the UI, in the background:**
 
 ```ts

package/src/templates/workspace-core/.agents/skills/extensions/SKILL.md

@@ -129,8 +129,12 @@ Extensions have full access to app data via helpers injected into the iframe
   in chat, record passive control/selection output at
   `inline-ui:<extensionId>:output` in application state so the agent can read it
   later with `readAppState`.
-- `agentNative.chat.send(message, opts?)` — send a visible prompt or selected
-  value back into the current agent chat.
+- `agentNative.chat.send(message, opts?)` - send a visible prompt or selected
+  value back into the current agent chat. The extension bridge keeps messages
+  draft-only unless `opts.submit === true`; pass `{ submit: true }` only from a
+  user-triggered Apply or Submit action. Never call it from polling, refresh, or
+  error handlers; use application state or `agentNative.ui.output` for passive
+  results.
 
 For transient inline generative UI, `extensionData` is host-browser
 `localStorage`: the agent cannot read it, it does not sync across devices, it

package/src/templates/workspace-core/.agents/skills/extensions/references/api.md

@@ -137,7 +137,7 @@ await dbExec("UPDATE notes SET title = 'Updated Title' WHERE id = 'abc'");
 | `extensionData.get(collection, id, opts?)`       | Get a single item by id                                  | `extensionData.get('todos', 'todo-1')`                                                                           |
 | `extensionData.remove(collection, id, opts?)`    | Delete an item                                           | `extensionData.remove('todos', 'todo-1')`                                                                        |
 | `agentNative.ui.output(value, opts?)`            | Record passive inline UI output in application state     | `agentNative.ui.output({ threshold })`                                                                           |
-| `agentNative.chat.send(message, opts?)`          | Send a visible prompt or selected value back to chat     | `agentNative.chat.send('Use Q2', { context: { q: 2 } })`                                                         |
+| `agentNative.chat.send(message, opts?)`          | Send a visible prompt or selected value back to chat     | `agentNative.chat.send('Use Q2', { submit: true, context: { q: 2 } })`                                           |
 
 ## Persisting Custom Data
 

package/src/templates/workspace-core/.agents/skills/generative-ui/SKILL.md

@@ -76,7 +76,9 @@ The stored payload includes `value`, `updatedAt`, `extensionId`, and
 
 Use `agentNative.chat.send(message, opts?)` or `sendToAgentChat(message, opts?)`
 for a visible Apply/Submit button that should send a prompt or selected value
-into the chat.
+into the chat. Pass `{ submit: true }` explicitly for that user-triggered
+action; extension messages are draft-only otherwise. Never call these helpers
+from polling, refresh, or error handlers.
 
 ## App Data And State