@agent-native/core 0.127.1 → 0.128.0

package/corpus/templates/tasks/.agents/skills/actions/SKILL.md

@@ -305,6 +305,38 @@ export default defineAction({
 
 On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
 
+### Authorization (`authorize`)
+
+`authorize` decides whether the caller may run the action at all. It wraps
+`run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
+hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
+agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
+to ask a human to bless one call a permitted caller is already allowed to make.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+The wrappers compose as `validate input -> authorize -> run -> validate output
+-> audit`: the gate sits inside input validation, so a guard reading `args` gets
+the parsed, coerced value, and auditing is outermost, so denials are recorded.
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. A guarded action
+needs a user identity, so an unattended CLI/cron caller with no user email is
+denied. `authorize` gates the operation; `accessFilter` / `assertAccess` still
+scope which rows a permitted caller may touch. See the `authentication` skill
+for `defineAppRoles` and the `sharing` skill for row scoping.
+
 ### Human-in-the-Loop Approval (`needsApproval`)
 
 For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call:

package/corpus/templates/tasks/.agents/skills/adding-a-feature/SKILL.md

@@ -179,8 +179,15 @@ If the feature stores **user-authored resources** (documents, dashboards, forms,
 
 TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSharesTable(...)`, call `registerShareableResource(...)`, wrap list/read queries with `accessFilter`, guard writes with `assertAccess`, and drop `<ShareButton>` in the resource header. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted framework-wide.
 
+## One more area — who inside the app may do it
+
+If the feature is one **only some teammates should be able to perform inside this app** (an admin-only import, a settings reset), that is a per-app role — not a new organization, and not a share grant. See the `authentication` skill.
+
+TL;DR: declare the vocabulary once with `defineAppRoles({ appId, roles, defaultRole })`, guard the action with `authorize: appAccess.requireAny("...")`, and render the picker with `<TeamPage appRoles={descriptor} />`. `defaultRole` is display only — it never satisfies a guard — and `authorize` gates the operation while `accessFilter` / `assertAccess` still scope the rows.
+
 ## Related Skills
 
+- **authentication** — Per-app member roles (`defineAppRoles`) when only some teammates may use a feature
 - **sharing** — How to make a new resource ownable (private by default, share with users/orgs/public)
 - **context-awareness** — How to expose UI state to the agent (area 4 in detail)
 - **actions** — How to create actions with `defineAction` and the `http` option (area 2 in detail)

package/corpus/templates/tasks/.agents/skills/security/SKILL.md

@@ -159,6 +159,35 @@ whole site. Data scoping lives in actions and API routes; the client gates
 private UI after the shell loads. See the `authentication` skill and
 `guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
 
+**Authorization beyond "is there a session" — `authorize`.** The auth guard only
+proves *someone* is signed in. To restrict an operation to some teammates, set
+`authorize` on the `defineAction`. It wraps `run`, so it applies at every
+dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
+`needsApproval`, which is honoured only in the agent loop.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. Guarded actions need
+a user identity — an unattended CLI/cron caller with no user email is denied.
+
+`authorize` is **not** a substitute for `accessFilter` / `assertAccess`. It
+decides whether this caller may perform the operation at all; `accessFilter` /
+`assertAccess` scope which rows a permitted caller may see or touch. A
+restricted write action needs both. See the `authentication` skill for
+`defineAppRoles` and the `actions` skill for the full surface.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.
@@ -274,6 +303,8 @@ Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org
 - [ ] New env vars in `.env` only, not committed
 - [ ] New user-data tables have `owner_email` column
 - [ ] Custom routes call `getSession` and reject unauthenticated requests
+- [ ] Actions only some teammates may run set `authorize` (in addition to any
+      `accessFilter` / `assertAccess` row scoping)
 
 ## Related Skills
 

package/corpus/templates/tasks/.agents/skills/sharing/SKILL.md

@@ -34,6 +34,8 @@ Visibility is coarse. Explicit share grants are fine-grained (per user or per or
 - **`editor`** — read + write.
 - **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
 
+There are three role systems and they never imply one another. A share role answers "what may this person do to **one row**". An org role (`org_members.role`) answers "what may this person do to the **team**". An app role (`defineAppRoles`, see the `authentication` skill) answers "what may this person do inside **one app**". A share `admin` is not an app admin and neither is an org admin.
+
 ### Anonymous public URLs stay separate
 
 Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
@@ -137,6 +139,8 @@ export default defineAction({
 
 For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
 
+`authorize` is a different axis, not an alternative: it gates whether the caller may run the operation at all, while `assertAccess` scopes which row they may touch. A write action restricted to some teammates needs both — `authorize: appAccess.requireAny(...)` on the action, `assertAccess` inside `run`.
+
 ## Create actions must set owner
 
 When inserting a new row, fill `ownerEmail` and `orgId` from the request context:

package/dist/a2a/artifact-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-response.d.ts","sourceRoot":"","sources":["../../src/a2a/artifact-response.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,8BAA8B,CAAC,EAAE,OAAO,CAAC;IACzC,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC,EAAE,OAAO,CAAC;CAC/C;AAED,MAAM,WAAW,0BAA0B;IACzC,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EACR,UAAU,GACV,MAAM,GACN,WAAW,GACX,UAAU,GACV,OAAO,GACP,QAAQ,GACR,SAAS,GACT,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AA4GD,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErE;AA4uBD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,oBAAoB,EAAE,EAC/B,OAAO,GAAE,0BAA+B,GACvC,mBAAmB,EAAE,CAsGvB;AA2YD,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,oBAAoB,EAAE,EACnC,OAAO,GAAE,0BAA+B,GACvC,0BAA0B,CA+J5B;AAED,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,oBAAoB,EAAE,EACnC,OAAO,GAAE,0BAA+B,GACvC,MAAM,CAER;AAED,wBAAgB,kCAAkC,CAChD,WAAW,EAAE,oBAAoB,EAAE,EACnC,OAAO,GAAE,0BAA+B,GACvC,MAAM,GAAG,IAAI,CA8Bf;AAmCD;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,oBAAoB,EAAE,EACnC,OAAO,GAAE,0BAA+B,GACvC,MAAM,GAAG,IAAI,CAqBf"}
+{"version":3,"file":"artifact-response.d.ts","sourceRoot":"","sources":["../../src/a2a/artifact-response.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,8BAA8B,CAAC,EAAE,OAAO,CAAC;IACzC,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC,EAAE,OAAO,CAAC;CAC/C;AAED,MAAM,WAAW,0BAA0B;IACzC,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EACR,UAAU,GACV,MAAM,GACN,WAAW,GACX,UAAU,GACV,OAAO,GACP,QAAQ,GACR,SAAS,GACT,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAiHD,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErE;AA8uBD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,oBAAoB,EAAE,EAC/B,OAAO,GAAE,0BAA+B,GACvC,mBAAmB,EAAE,CAsGvB;AA2YD,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,oBAAoB,EAAE,EACnC,OAAO,GAAE,0BAA+B,GACvC,0BAA0B,CA+J5B;AAED,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,oBAAoB,EAAE,EACnC,OAAO,GAAE,0BAA+B,GACvC,MAAM,CAER;AAED,wBAAgB,kCAAkC,CAChD,WAAW,EAAE,oBAAoB,EAAE,EACnC,OAAO,GAAE,0BAA+B,GACvC,MAAM,GAAG,IAAI,CA8Bf;AAmCD;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,oBAAoB,EAAE,EACnC,OAAO,GAAE,0BAA+B,GACvC,MAAM,GAAG,IAAI,CAqBf"}

package/dist/a2a/artifact-response.js

@@ -10,6 +10,11 @@ const ARTIFACT_IDENTITY_WRITE_TOOLS = new Set([
     "create-deck",
     "duplicate-deck",
     "add-slide",
+    "update-slide",
+    "patch-deck",
+    "save-deck",
+    "import-pptx",
+    "restore-deck-version",
     "update-dashboard",
     "rename-dashboard",
     "save-analysis",
@@ -333,25 +338,34 @@ function addImageArtifact(images, parsed) {
             stringValue(parsed.urlPath),
     });
 }
-function isReadyDeckArtifact(parsed) {
-    const slideCount = numberValue(parsed.slideCount);
-    if (slideCount !== undefined)
-        return slideCount > 0;
-    if (Array.isArray(parsed.slides))
-        return parsed.slides.length > 0;
-    return true;
-}
-function addDeckArtifact(decks, parsed, options) {
+function addDeckArtifact(decks, parsed) {
     const id = deckIdValue(parsed);
     if (!id)
         return;
-    if (options.requireReady && !isReadyDeckArtifact(parsed))
-        return;
     decks.set(id, {
         id,
         url: stringValue(parsed.url) ?? stringValue(parsed.urlPath),
     });
 }
+// Deck writes are spread across a dozen actions (create-deck, add-slide,
+// patch-deck, save-deck, update-slide, import-*, restore-deck-version), so a
+// per-tool allow-list refuses a real deck URL every time an action is added.
+// Trust any successful result that names a deck the way the deck routes do: an
+// explicit deckId, or a canonical /deck/<id> URL the action itself returned.
+function addDeckArtifactFromAnyResult(decks, parsed) {
+    const url = stringValue(parsed.url) ?? stringValue(parsed.urlPath);
+    const deckId = stringValue(parsed.deckId);
+    if (deckId) {
+        decks.set(deckId, {
+            id: deckId,
+            url: url && artifactUrlReferencesId(url, "deck", deckId) ? url : undefined,
+        });
+    }
+    const reference = url ? parseArtifactReferenceUrl(url) : null;
+    if (reference?.kind === "deck") {
+        decks.set(reference.id, { id: reference.id, url });
+    }
+}
 function addListedDeckArtifacts(decks, parsed) {
     const items = parsed.decks;
     if (!Array.isArray(items))
@@ -360,7 +374,7 @@ function addListedDeckArtifacts(decks, parsed) {
         const deck = asRecord(item);
         if (!deck)
             continue;
-        addDeckArtifact(decks, deck, { requireReady: false });
+        addDeckArtifact(decks, deck);
     }
 }
 function collectArtifacts(results) {
@@ -426,6 +440,7 @@ function collectArtifacts(results) {
         const parsed = parseToolResultJson(toolResult.result);
         if (!parsed)
             continue;
+        addDeckArtifactFromAnyResult(decks, parsed);
         if (toolResult.tool === "save-monitor") {
             const id = stringValue(parsed.id);
             const url = stringValue(parsed.monitorAppUrl);
@@ -507,29 +522,15 @@ function collectArtifacts(results) {
             addGenericDocumentReadArtifact(documents, parsed);
         }
         if (toolResult.tool === "create-deck" ||
-            toolResult.tool === "duplicate-deck") {
-            addDeckArtifact(decks, parsed, { requireReady: true });
-            continue;
-        }
-        if (toolResult.tool === "get-deck") {
-            addDeckArtifact(decks, parsed, { requireReady: false });
+            toolResult.tool === "duplicate-deck" ||
+            toolResult.tool === "get-deck") {
+            addDeckArtifact(decks, parsed);
             continue;
         }
         if (toolResult.tool === "list-decks") {
             addListedDeckArtifacts(decks, parsed);
             continue;
         }
-        if (toolResult.tool === "add-slide") {
-            const id = stringValue(parsed.deckId);
-            const slideCount = numberValue(parsed.slideCount);
-            if (id && slideCount !== undefined && slideCount > 0) {
-                decks.set(id, {
-                    id,
-                    url: stringValue(parsed.url) ?? stringValue(parsed.urlPath),
-                });
-            }
-            continue;
-        }
         if (toolResult.tool === "update-dashboard" ||
             toolResult.tool === "rename-dashboard" ||
             toolResult.tool === "get-dashboard") {