@agent-native/core 0.124.5 → 0.124.6

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @agent-native/core
 
+## 0.124.6
+
+### Patch Changes
+
+- ac8794b: Clarify credential resolver organization scope in generated workspace guidance.
+
 ## 0.124.5
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.124.5",
+  "version": "0.124.6",
   "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": {

package/corpus/core/src/templates/default/.agents/skills/secrets/SKILL.md

@@ -177,9 +177,34 @@ workspace repo:
 npx agent-native doctor --only no-env-credentials
 ```
 
-Findings in files that already call `resolveCredential` are usually the
-sanctioned `resolveCredential(key, ctx) ?? process.env.KEY` fallback. The bugs
-are the files with **no** resolver at all.
+## `resolveCredential` sees exactly one organization
+
+`resolveCredential(key, { userEmail, orgId })` checks the user scope, then the
+one `orgId` you pass, then the solo workspace. That is the whole search. It is
+correct for a signed-in request, and wrong for two common cases:
+
+- **The caller has no organization.** A cron, a scheduled job, or any CLI run
+  without a real member identity resolves no `orgId`, so only the user and solo
+  scopes are ever consulted — and a shared key is in neither.
+- **The key was synced under a different organization.** `app_secrets` has no
+  scope visible to every org (`readAppSecret` is strict equality on
+  `(scope, scope_id, key)`), so a key the vault UI advertises as available to
+  every app is unreadable from any org except the one that ran the sync.
+
+Both produce the same misleading "not set" that the split brain above produces,
+which is why swapping `process.env` for `resolveCredential` can look like a fix
+and change nothing. A workspace app should read shared keys through a resolver
+that also sweeps the caller's other memberships and a designated vault org —
+see `resolveConnectorSecret` and `AGENT_VAULT_ORG_ID` in the builder-workspace
+repo for the shape, including the boot-time assertion that the deployment really
+is single-tenant before a non-membership-gated fallback is safe.
+
+**The doctor guard does not catch this second form** — it looks for
+`process.env` reads, and `resolveCredential` is not one. Grep for
+`resolveCredential` yourself and confirm each call sits somewhere a single-org
+lookup is genuinely the right question. Findings that pair it with a
+`?? process.env.KEY` fallback are the sanctioned deploy-level escape hatch; the
+bugs are calls whose value can only live in another org's vault.
 
 ## HTTP routes
 

package/corpus/core/src/templates/headless/.agents/skills/secrets/SKILL.md

@@ -177,9 +177,34 @@ workspace repo:
 npx agent-native doctor --only no-env-credentials
 ```
 
-Findings in files that already call `resolveCredential` are usually the
-sanctioned `resolveCredential(key, ctx) ?? process.env.KEY` fallback. The bugs
-are the files with **no** resolver at all.
+## `resolveCredential` sees exactly one organization
+
+`resolveCredential(key, { userEmail, orgId })` checks the user scope, then the
+one `orgId` you pass, then the solo workspace. That is the whole search. It is
+correct for a signed-in request, and wrong for two common cases:
+
+- **The caller has no organization.** A cron, a scheduled job, or any CLI run
+  without a real member identity resolves no `orgId`, so only the user and solo
+  scopes are ever consulted — and a shared key is in neither.
+- **The key was synced under a different organization.** `app_secrets` has no
+  scope visible to every org (`readAppSecret` is strict equality on
+  `(scope, scope_id, key)`), so a key the vault UI advertises as available to
+  every app is unreadable from any org except the one that ran the sync.
+
+Both produce the same misleading "not set" that the split brain above produces,
+which is why swapping `process.env` for `resolveCredential` can look like a fix
+and change nothing. A workspace app should read shared keys through a resolver
+that also sweeps the caller's other memberships and a designated vault org —
+see `resolveConnectorSecret` and `AGENT_VAULT_ORG_ID` in the builder-workspace
+repo for the shape, including the boot-time assertion that the deployment really
+is single-tenant before a non-membership-gated fallback is safe.
+
+**The doctor guard does not catch this second form** — it looks for
+`process.env` reads, and `resolveCredential` is not one. Grep for
+`resolveCredential` yourself and confirm each call sits somewhere a single-org
+lookup is genuinely the right question. Findings that pair it with a
+`?? process.env.KEY` fallback are the sanctioned deploy-level escape hatch; the
+bugs are calls whose value can only live in another org's vault.
 
 ## HTTP routes
 

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

@@ -177,9 +177,34 @@ workspace repo:
 npx agent-native doctor --only no-env-credentials
 ```
 
-Findings in files that already call `resolveCredential` are usually the
-sanctioned `resolveCredential(key, ctx) ?? process.env.KEY` fallback. The bugs
-are the files with **no** resolver at all.
+## `resolveCredential` sees exactly one organization
+
+`resolveCredential(key, { userEmail, orgId })` checks the user scope, then the
+one `orgId` you pass, then the solo workspace. That is the whole search. It is
+correct for a signed-in request, and wrong for two common cases:
+
+- **The caller has no organization.** A cron, a scheduled job, or any CLI run
+  without a real member identity resolves no `orgId`, so only the user and solo
+  scopes are ever consulted — and a shared key is in neither.
+- **The key was synced under a different organization.** `app_secrets` has no
+  scope visible to every org (`readAppSecret` is strict equality on
+  `(scope, scope_id, key)`), so a key the vault UI advertises as available to
+  every app is unreadable from any org except the one that ran the sync.
+
+Both produce the same misleading "not set" that the split brain above produces,
+which is why swapping `process.env` for `resolveCredential` can look like a fix
+and change nothing. A workspace app should read shared keys through a resolver
+that also sweeps the caller's other memberships and a designated vault org —
+see `resolveConnectorSecret` and `AGENT_VAULT_ORG_ID` in the builder-workspace
+repo for the shape, including the boot-time assertion that the deployment really
+is single-tenant before a non-membership-gated fallback is safe.
+
+**The doctor guard does not catch this second form** — it looks for
+`process.env` reads, and `resolveCredential` is not one. Grep for
+`resolveCredential` yourself and confirm each call sits somewhere a single-org
+lookup is genuinely the right question. Findings that pair it with a
+`?? process.env.KEY` fallback are the sanctioned deploy-level escape hatch; the
+bugs are calls whose value can only live in another org's vault.
 
 ## HTTP routes
 

package/dist/collab/routes.d.ts

@@ -41,9 +41,9 @@ export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import
  * Body: { text: string, fieldName?: string, requestSource?: string }
  */
 export declare const postCollabText: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    text?: undefined;
     ok?: undefined;
     error: string;
-    text?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/file-upload/actions/upload-image.d.ts

@@ -17,12 +17,12 @@ declare const _default: import("../../action.js").ActionDefinition<{
     id?: undefined;
     provider?: undefined;
 } | {
+    error?: undefined;
     configured?: undefined;
     connectPath?: undefined;
     url: string;
     id: string;
     provider: string;
-    error?: undefined;
 }>;
 export default _default;
 //# sourceMappingURL=upload-image.d.ts.map

package/dist/notifications/routes.d.ts

@@ -13,13 +13,13 @@
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
     count: number;
     updated?: undefined;
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
 } | {
     count?: undefined;
     updated: number;
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
 } | {
     count?: undefined;
     updated?: undefined;
@@ -28,7 +28,7 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
 } | {
     count?: undefined;
     updated?: undefined;
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;
 //# sourceMappingURL=routes.d.ts.map

package/dist/secrets/routes.d.ts

@@ -34,37 +34,37 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    status?: undefined;
     ok?: undefined;
+    status?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     status: string;
-    error?: undefined;
 } | {
+    ok?: undefined;
     error: string;
     removed?: undefined;
-    ok?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — re-run the validator against the
  * current stored value without changing anything. Useful for the "Test" button.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    ok?: undefined;
     error: string;
     note?: undefined;
-    ok?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note?: undefined;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note: string;
-    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,12 +95,12 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;
 //# sourceMappingURL=routes.d.ts.map

package/dist/server/realtime-token.d.ts

@@ -26,9 +26,9 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
-    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
+    error?: undefined;
 }>>;
 //# sourceMappingURL=realtime-token.d.ts.map

package/dist/templates/default/.agents/skills/secrets/SKILL.md

@@ -177,9 +177,34 @@ workspace repo:
 npx agent-native doctor --only no-env-credentials
 ```
 
-Findings in files that already call `resolveCredential` are usually the
-sanctioned `resolveCredential(key, ctx) ?? process.env.KEY` fallback. The bugs
-are the files with **no** resolver at all.
+## `resolveCredential` sees exactly one organization
+
+`resolveCredential(key, { userEmail, orgId })` checks the user scope, then the
+one `orgId` you pass, then the solo workspace. That is the whole search. It is
+correct for a signed-in request, and wrong for two common cases:
+
+- **The caller has no organization.** A cron, a scheduled job, or any CLI run
+  without a real member identity resolves no `orgId`, so only the user and solo
+  scopes are ever consulted — and a shared key is in neither.
+- **The key was synced under a different organization.** `app_secrets` has no
+  scope visible to every org (`readAppSecret` is strict equality on
+  `(scope, scope_id, key)`), so a key the vault UI advertises as available to
+  every app is unreadable from any org except the one that ran the sync.
+
+Both produce the same misleading "not set" that the split brain above produces,
+which is why swapping `process.env` for `resolveCredential` can look like a fix
+and change nothing. A workspace app should read shared keys through a resolver
+that also sweeps the caller's other memberships and a designated vault org —
+see `resolveConnectorSecret` and `AGENT_VAULT_ORG_ID` in the builder-workspace
+repo for the shape, including the boot-time assertion that the deployment really
+is single-tenant before a non-membership-gated fallback is safe.
+
+**The doctor guard does not catch this second form** — it looks for
+`process.env` reads, and `resolveCredential` is not one. Grep for
+`resolveCredential` yourself and confirm each call sits somewhere a single-org
+lookup is genuinely the right question. Findings that pair it with a
+`?? process.env.KEY` fallback are the sanctioned deploy-level escape hatch; the
+bugs are calls whose value can only live in another org's vault.
 
 ## HTTP routes
 

package/dist/templates/headless/.agents/skills/secrets/SKILL.md

@@ -177,9 +177,34 @@ workspace repo:
 npx agent-native doctor --only no-env-credentials
 ```
 
-Findings in files that already call `resolveCredential` are usually the
-sanctioned `resolveCredential(key, ctx) ?? process.env.KEY` fallback. The bugs
-are the files with **no** resolver at all.
+## `resolveCredential` sees exactly one organization
+
+`resolveCredential(key, { userEmail, orgId })` checks the user scope, then the
+one `orgId` you pass, then the solo workspace. That is the whole search. It is
+correct for a signed-in request, and wrong for two common cases:
+
+- **The caller has no organization.** A cron, a scheduled job, or any CLI run
+  without a real member identity resolves no `orgId`, so only the user and solo
+  scopes are ever consulted — and a shared key is in neither.
+- **The key was synced under a different organization.** `app_secrets` has no
+  scope visible to every org (`readAppSecret` is strict equality on
+  `(scope, scope_id, key)`), so a key the vault UI advertises as available to
+  every app is unreadable from any org except the one that ran the sync.
+
+Both produce the same misleading "not set" that the split brain above produces,
+which is why swapping `process.env` for `resolveCredential` can look like a fix
+and change nothing. A workspace app should read shared keys through a resolver
+that also sweeps the caller's other memberships and a designated vault org —
+see `resolveConnectorSecret` and `AGENT_VAULT_ORG_ID` in the builder-workspace
+repo for the shape, including the boot-time assertion that the deployment really
+is single-tenant before a non-membership-gated fallback is safe.
+
+**The doctor guard does not catch this second form** — it looks for
+`process.env` reads, and `resolveCredential` is not one. Grep for
+`resolveCredential` yourself and confirm each call sits somewhere a single-org
+lookup is genuinely the right question. Findings that pair it with a
+`?? process.env.KEY` fallback are the sanctioned deploy-level escape hatch; the
+bugs are calls whose value can only live in another org's vault.
 
 ## HTTP routes
 

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

@@ -177,9 +177,34 @@ workspace repo:
 npx agent-native doctor --only no-env-credentials
 ```
 
-Findings in files that already call `resolveCredential` are usually the
-sanctioned `resolveCredential(key, ctx) ?? process.env.KEY` fallback. The bugs
-are the files with **no** resolver at all.
+## `resolveCredential` sees exactly one organization
+
+`resolveCredential(key, { userEmail, orgId })` checks the user scope, then the
+one `orgId` you pass, then the solo workspace. That is the whole search. It is
+correct for a signed-in request, and wrong for two common cases:
+
+- **The caller has no organization.** A cron, a scheduled job, or any CLI run
+  without a real member identity resolves no `orgId`, so only the user and solo
+  scopes are ever consulted — and a shared key is in neither.
+- **The key was synced under a different organization.** `app_secrets` has no
+  scope visible to every org (`readAppSecret` is strict equality on
+  `(scope, scope_id, key)`), so a key the vault UI advertises as available to
+  every app is unreadable from any org except the one that ran the sync.
+
+Both produce the same misleading "not set" that the split brain above produces,
+which is why swapping `process.env` for `resolveCredential` can look like a fix
+and change nothing. A workspace app should read shared keys through a resolver
+that also sweeps the caller's other memberships and a designated vault org —
+see `resolveConnectorSecret` and `AGENT_VAULT_ORG_ID` in the builder-workspace
+repo for the shape, including the boot-time assertion that the deployment really
+is single-tenant before a non-membership-gated fallback is safe.
+
+**The doctor guard does not catch this second form** — it looks for
+`process.env` reads, and `resolveCredential` is not one. Grep for
+`resolveCredential` yourself and confirm each call sits somewhere a single-org
+lookup is genuinely the right question. Findings that pair it with a
+`?? process.env.KEY` fallback are the sanctioned deploy-level escape hatch; the
+bugs are calls whose value can only live in another org's vault.
 
 ## HTTP routes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.124.5",
+  "version": "0.124.6",
   "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": {

package/src/templates/default/.agents/skills/secrets/SKILL.md

@@ -177,9 +177,34 @@ workspace repo:
 npx agent-native doctor --only no-env-credentials
 ```
 
-Findings in files that already call `resolveCredential` are usually the
-sanctioned `resolveCredential(key, ctx) ?? process.env.KEY` fallback. The bugs
-are the files with **no** resolver at all.
+## `resolveCredential` sees exactly one organization
+
+`resolveCredential(key, { userEmail, orgId })` checks the user scope, then the
+one `orgId` you pass, then the solo workspace. That is the whole search. It is
+correct for a signed-in request, and wrong for two common cases:
+
+- **The caller has no organization.** A cron, a scheduled job, or any CLI run
+  without a real member identity resolves no `orgId`, so only the user and solo
+  scopes are ever consulted — and a shared key is in neither.
+- **The key was synced under a different organization.** `app_secrets` has no
+  scope visible to every org (`readAppSecret` is strict equality on
+  `(scope, scope_id, key)`), so a key the vault UI advertises as available to
+  every app is unreadable from any org except the one that ran the sync.
+
+Both produce the same misleading "not set" that the split brain above produces,
+which is why swapping `process.env` for `resolveCredential` can look like a fix
+and change nothing. A workspace app should read shared keys through a resolver
+that also sweeps the caller's other memberships and a designated vault org —
+see `resolveConnectorSecret` and `AGENT_VAULT_ORG_ID` in the builder-workspace
+repo for the shape, including the boot-time assertion that the deployment really
+is single-tenant before a non-membership-gated fallback is safe.
+
+**The doctor guard does not catch this second form** — it looks for
+`process.env` reads, and `resolveCredential` is not one. Grep for
+`resolveCredential` yourself and confirm each call sits somewhere a single-org
+lookup is genuinely the right question. Findings that pair it with a
+`?? process.env.KEY` fallback are the sanctioned deploy-level escape hatch; the
+bugs are calls whose value can only live in another org's vault.
 
 ## HTTP routes
 

package/src/templates/headless/.agents/skills/secrets/SKILL.md

@@ -177,9 +177,34 @@ workspace repo:
 npx agent-native doctor --only no-env-credentials
 ```
 
-Findings in files that already call `resolveCredential` are usually the
-sanctioned `resolveCredential(key, ctx) ?? process.env.KEY` fallback. The bugs
-are the files with **no** resolver at all.
+## `resolveCredential` sees exactly one organization
+
+`resolveCredential(key, { userEmail, orgId })` checks the user scope, then the
+one `orgId` you pass, then the solo workspace. That is the whole search. It is
+correct for a signed-in request, and wrong for two common cases:
+
+- **The caller has no organization.** A cron, a scheduled job, or any CLI run
+  without a real member identity resolves no `orgId`, so only the user and solo
+  scopes are ever consulted — and a shared key is in neither.
+- **The key was synced under a different organization.** `app_secrets` has no
+  scope visible to every org (`readAppSecret` is strict equality on
+  `(scope, scope_id, key)`), so a key the vault UI advertises as available to
+  every app is unreadable from any org except the one that ran the sync.
+
+Both produce the same misleading "not set" that the split brain above produces,
+which is why swapping `process.env` for `resolveCredential` can look like a fix
+and change nothing. A workspace app should read shared keys through a resolver
+that also sweeps the caller's other memberships and a designated vault org —
+see `resolveConnectorSecret` and `AGENT_VAULT_ORG_ID` in the builder-workspace
+repo for the shape, including the boot-time assertion that the deployment really
+is single-tenant before a non-membership-gated fallback is safe.
+
+**The doctor guard does not catch this second form** — it looks for
+`process.env` reads, and `resolveCredential` is not one. Grep for
+`resolveCredential` yourself and confirm each call sits somewhere a single-org
+lookup is genuinely the right question. Findings that pair it with a
+`?? process.env.KEY` fallback are the sanctioned deploy-level escape hatch; the
+bugs are calls whose value can only live in another org's vault.
 
 ## HTTP routes
 

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

@@ -177,9 +177,34 @@ workspace repo:
 npx agent-native doctor --only no-env-credentials
 ```
 
-Findings in files that already call `resolveCredential` are usually the
-sanctioned `resolveCredential(key, ctx) ?? process.env.KEY` fallback. The bugs
-are the files with **no** resolver at all.
+## `resolveCredential` sees exactly one organization
+
+`resolveCredential(key, { userEmail, orgId })` checks the user scope, then the
+one `orgId` you pass, then the solo workspace. That is the whole search. It is
+correct for a signed-in request, and wrong for two common cases:
+
+- **The caller has no organization.** A cron, a scheduled job, or any CLI run
+  without a real member identity resolves no `orgId`, so only the user and solo
+  scopes are ever consulted — and a shared key is in neither.
+- **The key was synced under a different organization.** `app_secrets` has no
+  scope visible to every org (`readAppSecret` is strict equality on
+  `(scope, scope_id, key)`), so a key the vault UI advertises as available to
+  every app is unreadable from any org except the one that ran the sync.
+
+Both produce the same misleading "not set" that the split brain above produces,
+which is why swapping `process.env` for `resolveCredential` can look like a fix
+and change nothing. A workspace app should read shared keys through a resolver
+that also sweeps the caller's other memberships and a designated vault org —
+see `resolveConnectorSecret` and `AGENT_VAULT_ORG_ID` in the builder-workspace
+repo for the shape, including the boot-time assertion that the deployment really
+is single-tenant before a non-membership-gated fallback is safe.
+
+**The doctor guard does not catch this second form** — it looks for
+`process.env` reads, and `resolveCredential` is not one. Grep for
+`resolveCredential` yourself and confirm each call sits somewhere a single-org
+lookup is genuinely the right question. Findings that pair it with a
+`?? process.env.KEY` fallback are the sanctioned deploy-level escape hatch; the
+bugs are calls whose value can only live in another org's vault.
 
 ## HTTP routes