@permute/sdk 0.6.0 → 0.8.0

package/README.md

@@ -6,6 +6,32 @@ The SDK supports Node.js 20 and newer and includes TypeScript declarations.
 
 See the [changelog](https://permute.ai/docs/changelog) for release notes and upgrade guidance.
 
+## Sign in without an API key
+
+The CLI ships with `@permute/sdk`. Run it with `bunx`:
+
+```sh
+bunx @permute/sdk auth login
+# Or approve from another computer:
+bunx @permute/sdk auth login --device-code --no-browser
+bunx @permute/sdk auth status
+bunx @permute/sdk auth logout
+```
+
+Choose an organization, optionally limit the connection to one workspace, then select resources and permissions to approve in Permute. The CLI stores renewable credentials in your operating system’s credential store (no plaintext fallback). Active logins have no fixed maximum lifetime and expire after 30 days without renewal; company sign-in rules can require earlier authentication. Logging out revokes access before removing the local credential. Signing in again revokes the previous stored CLI session.
+
+```ts
+import { OAuthLogin } from '@permute/sdk/auth';
+
+const client = await new OAuthLogin().client();
+const workspace = client.withWorkspace('wksp_...');
+const apps = await workspace.apps.list();
+```
+
+The client renews access automatically. Existing permissions still control data, drafting, publication and action execution. Each request must fit both the approved selection and your current permissions. For organization-wide logins, use `client.withWorkspace(id)` for workspace API calls. Local stdio MCP can reuse this saved login when no API key is configured. Hosted app and hosted MCP credentials stay bound to their own audiences. API-key clients continue to work with `new PermuteClient({ apiKey })`.
+
+For a development environment, pass both `--issuer https://auth.example.test` and `--api-url https://api.example.test` to CLI commands, or the matching `issuer` and `apiUrl` to `OAuthLogin`. Only HTTPS origins and local loopback HTTP are accepted. Use the same environment for login and logout.
+
 ## Dashboard source authoring
 
 API-key clients with dashboard write access can read and replace the complete
@@ -96,10 +122,12 @@ replacement without checking the changes. Graph commands use `get`’s numeric f
 Publishing requires a successful run of the current flow version. Deleting a flow
 requires admin access; its owned operations are deleted with it.
 
-Data Flow and operation authoring are REST/SDK only. MCP serves end users reading
-and analyzing governed outputs; it does not expose code editing, draft inspection,
-execution, or publication. Hosted connectors also restrict access to selected sources. Flow scheduling and standalone operation
-creation are not part of this surface.
+Data Flow and operation authoring are REST/SDK only. MCP does not expose their code
+editing, draft inspection, execution, or publication. Hosted MCP access uses
+selected sources or a hosted app's current grants and published action bindings,
+intersected with the user's permissions. App actions require confirmation in
+Permute; see the [MCP guide](https://permute.ai/docs/mcp). Flow scheduling and
+standalone operation creation are not part of this surface.
 
 ## Publish write syncs
 
@@ -224,10 +252,36 @@ console.log(uploaded.sourceId, uploaded.status);
 ```
 
 The SDK infers `sizeBytes` for strings, buffers, typed arrays, ArrayBuffers, and
-Blobs. REST callers provide `sizeBytes`, then send a raw `PUT` to the returned
+Blobs. Omit `data` and provide `sizeBytes` to create the dataset and return its
+upload target without sending bytes. This lets an action approve upload metadata
+while the browser uploads a file directly to storage (outside action limits):
+
+```ts
+const prepared = await client.datasets.create({
+  type: 'file',
+  fileName: file.name,
+  contentType: file.type,
+  sizeBytes: file.size,
+});
+const upload = prepared.data.upload;
+if (!upload) throw new Error('Missing upload target');
+const response = await fetch(upload.url, {
+  method: upload.method,
+  headers: upload.headers,
+  body: file,
+});
+if (!response.ok) throw new Error('Upload failed');
+```
+
+For browser uploads, prepare the target on the server or inside a Business Action,
+then return the dataset ID and target to the browser. The storage PUT uses the
+signed target without an API key; keep API-key SDK clients on the server.
+
+Use every header returned with the target. REST callers provide `sizeBytes`, then send a raw `PUT` to the returned
 `data.upload.url` with every header in `data.upload.headers`. Poll
-`client.datasets.get(result.id)` for processing status; there is no completion
-API call.
+`client.datasets.get(result.id)` for processing status with dataset read permission.
+If the caller has only action invocation access, use a separate status action.
+There is no completion API call.
 
 CSV, TSV, JSON, NDJSON, and Parquet files can be up to 1 GiB (1,073,741,824
 bytes). Other supported file types can be up to 100 MiB (104,857,600 bytes).
@@ -353,6 +407,14 @@ query (materialized connector fields come from the stored SQL table). Warehouse
 sources use DuckDB SQL and can be queried together. Live remote sources use
 their native SQL dialect and must be queried one at a time.
 
+Warehouse SQL queries accept up to **20 distinct sources per query**. The shared
+[`WAREHOUSE_QUERY_SOURCE_LIMIT`](../core/src/constants/queryLimits.ts) keeps the
+SQL executor, natural-language query sessions, and UI source picker consistent.
+This cap bounds the number of sources prepared for a query (each source can
+contain many tables); it does not limit workspace connections or change access
+permissions. Select only the sources needed. Requests above the cap are rejected
+before source loading.
+
 ```ts
 const dataset = sources.items.find((source) => source.type === 'dataset');
 if (!dataset) throw new Error('No dataset is available');
@@ -382,7 +444,11 @@ the same transaction after an uncertain response.
 Schema definitions use `client.databases.definition(id)` and
 `client.databases.saveDefinition(id, { definition, expectedDraft })`. Save the
 complete table list, then publish the exact draft through `client.revisions`.
-Published schemas only support adding tables; rows are not part of schema history.
+Publication supports new tables and new nullable columns on existing tables.
+Set `nullable: true` for added columns; existing rows read `NULL` and keep their
+record-version tokens. Preserve existing columns, types, nullability and primary
+keys. Rows are not part of schema history. Publication applies DDL before moving
+the published ref; after a partial failure, retry the same definition to resume.
 
 **Upgrading from 0.3.x:** `createTable` now saves a draft. Publish the database
 before using the new table. Direct `transact` calls require database admin
@@ -394,6 +460,14 @@ handling).
 
 ## Error Handling
 
+App and Business Action authorization failures can return `permission_denied` with
+`error.details` containing `operation`, `requiredLevel` (`read`, `write`, or `admin`),
+and `reason`. Reasons are `caller_permission_required`, `application_grant_required`,
+`source_delegation_required`, or `declared_capability_required`. Both SDK entries
+preserve these fields on `PermuteApiError.details`. Details are optional: unreadable,
+missing, and foreign resources return the same opaque 404, so a caller cannot use
+denials to discover private resources. See [authentication](https://permute.ai/docs/authentication#authorization-errors).
+
 ```ts
 import { PermuteApiError } from '@permute/sdk';
 
@@ -425,7 +499,22 @@ const files = await client.apps.uploadFiles(app.id, [
   { path: 'index.html', data: await readFile('dist/index.html') },
   { path: 'assets/main.js', data: await readFile('dist/assets/main.js') },
 ]);
+const sourceFiles = await client.apps.uploadFiles(app.id, [
+  { path: 'package.json', data: await readFile('package.json') },
+  { path: 'bun.lock', data: await readFile('bun.lock') },
+  { path: 'src/main.tsx', data: await readFile('src/main.tsx') },
+  { path: 'index.html', data: await readFile('index.html') },
+  { path: 'vite.config.ts', data: await readFile('vite.config.ts') },
+]);
 const saved = await client.apps.saveSite(app.id, {
+  source: {
+    files: sourceFiles,
+    build: {
+      command: 'bun run build --base=./',
+      outputDirectory: 'dist',
+      runtime: 'bun@1.3.12',
+    },
+  },
   site: { files, spa: true },
   expectedDraft: app.draft,
 });
@@ -436,40 +525,62 @@ if (state.draft?.revisionId !== saved.draft.revisionId || state.draft.sequence !
 await client.revisions.publish(app.id, { expectedVersion: state.version });
 ```
 
-Import `readFile` from `node:fs/promises`. Supply the complete build directory; the filenames above are illustrative. Uploads hash the bytes and use signed, conditional S3 PUTs without forwarding API credentials. Uploading does not create a draft. `saveSite` verifies the uploaded files and saves the complete manifest as a draft revision; `revisions.publish` makes that draft live. The limits are 200 files, 4 MiB per file, and 50 MiB total.
+Import `readFile` from `node:fs/promises`. Supply complete source and compiled manifests, including every file required for a standalone build; the filenames above are illustrative. Uploads hash the bytes and use signed, conditional S3 PUTs without forwarding API credentials. Uploading does not create a draft. `saveSite` verifies the uploaded files and saves source, build instructions and compiled output as one draft revision; `revisions.publish` makes that draft live. Source allows 1,000 files; compiled output allows 200. Each manifest allows 4 MiB per file and 50 MiB total. Optional source-file `executable: true` preserves script permissions. Keep secrets outside source and browser bundles.
 
 Identical contents reuse existing files. Changed contents at the same path are stored separately, preserving earlier versions for rollback. Each save replaces the complete manifest (including unchanged files); omitted paths disappear from the live app when published. Resolve a 409 conflict against the current draft before retrying.
 
+Customize login appearance with `apps.update(app.id, { login, expectedDraft: app.draft })`. The optional `login` object accepts `header`, `subheader`, `title`, `subtitle`, `primaryColor` and `secondaryColor` (six-digit hex colors). For `sidePanelImage`, upload a PNG, JPEG or WebP image up to 2 MiB with `apps.uploadFiles` and pass the returned file descriptor. Publish the saved draft through `revisions.publish` to apply the same appearance to Permute sign-in and shared-password access. Set `login: null` to restore default styling. Images displayed before sign-in are public; normal site files stay gated.
+
+Set an app favicon with `apps.update(app.id, { favicon, expectedDraft: app.draft })`, where `favicon` is the descriptor returned by uploading a PNG up to 256 KiB through `apps.uploadFiles`. Publish to apply it to browser tabs and sign-in screens (independent of custom login styling). The configured icon overrides bundled icons; `favicon: null` removes the override. Only the current published icon is public before sign-in; historical published icons require an app session. Organization defaults are not supported.
+
 Visitors sign in through Permute and need app read permission. HTML receives a revision-specific base URL; use relative URLs for bundled and public assets. Inline scripts, external requests, workers, and server runtimes are not supported. Keep API keys and secrets out of compiled browser files. Restore a historical revision with `client.revisions.restore`, then publish the resulting draft to roll back. See the [complete app guide](https://permute.ai/docs/guides/deploy-app) for creation, directory uploads, updates, and rollback.
 
-### Deploy a build directory (SDK 0.6.0)
+### Deploy source and compiled output (SDK 0.7.0)
 
 The Node/Bun entry `@permute/sdk/deploy` combines validation, upload, draft save,
-and publication for an existing live app. Use SDK 0.6.0 for the grant-based app
-API shown here.
+and publication for an existing live app. Use SDK 0.7.0 for source-backed app saves. Builds still run locally.
 
 ```ts
 import { deployApp } from '@permute/sdk/deploy';
 
-const deployed = await deployApp(client, { appId, directory: './dist' });
+const deployed = await deployApp(client, {
+  appId,
+  directory: './dist',
+  expectedDraft: app.draft,
+  source: {
+    directory: '.',
+    build: {
+      command: 'bun run build --base=./',
+      outputDirectory: 'dist',
+      runtime: 'bun@1.3.12',
+    },
+  },
+});
 console.log(deployed.url, deployed.revisionId, deployed.changed);
 ```
 
 The helper rejects symbolic links, unsupported paths, missing `index.html`, and
-oversized builds before uploading. It requires the current draft to be published;
-after reviewing an existing draft, pass its exact `expectedDraft` to approve
-replacing it. Omitted `actions` preserve current bindings (an empty array clears them). To change action bindings, supply explicit published revisions:
+oversized builds before uploading. Pass the `expectedDraft` token from checkout or a reviewed app read. A stale token stops deployment before uploads; the helper never adopts a newer remote draft as the base of local files. Omitted `actions` preserve current bindings (an empty array clears them). To change action bindings, supply explicit published revisions:
 
 ```ts
 await deployApp(client, {
   appId,
+  expectedDraft: app.draft,
   directory: './dist',
+  source: {
+    directory: '.',
+    build: {
+      command: 'bun run build --base=./',
+      outputDirectory: 'dist',
+      runtime: 'bun@1.3.12',
+    },
+  },
   actions: [{ actionId, revisionId: publishedActionRevisionId }],
 });
 ```
 
 An unchanged build returns `changed: false` without uploading, saving, or publishing
-(files, SPA mode, and any supplied bindings must match). It rechecks refs before
+(source, build instructions, compiled files, SPA mode, and supplied bindings must match). It rechecks refs before
 reporting no change. An approved unpublished draft is still published so settings
 edits are preserved. Changed deployments return `changed: true`.
 
@@ -480,23 +591,107 @@ publication may already have completed. `deployment_conflict` requires review;
 when saving a draft for later review. The helper does not build, provision, or wait
 for hosting, and must not be imported into browser code.
 
+### Shared source checkpoints and checkout
+
+Source and compiled output share one App history. Source checkpoints advance the draft without publishing; publication checks that the saved build matches current source and build instructions. Settings-only edits reuse matching builds. Restore recovers both manifests together; older compiled-only revisions have no downloadable source.
+
+Invited editors can use **Download source** in App details with their Permute user session (no API key required). The ZIP contains project files under `source/` and a separate `app-source.json` with build instructions, the exact revision and the observed draft token. The SDK uses an API key with its own App write grant; a user editing invitation does not grant access to any API key.
+
+```ts
+import { checkoutApp, saveAppSource } from '@permute/sdk/deploy';
+
+const checkout = await checkoutApp(client, { appId, directory: './app-project' });
+// Edit the downloaded files. Retain the token from checkout for your save.
+if (!checkout.expectedDraft) throw new Error('Review the current draft first');
+const saved = await saveAppSource(client, {
+  appId,
+  expectedDraft: checkout.expectedDraft,
+  source: { directory: './app-project', build: checkout.source.build },
+});
+// Run the stored build command, then use deployApp with expectedDraft: saved.draft.
+```
+
+Checkout requires a new folder and verifies every downloaded file against its hash and size. Pass `revisionId` to select historical source; historical checkout returns no draft token unless it is also the current draft. A failed checkout may leave a partial folder; inspect it and choose a new folder before retrying.
+
+Source helpers apply root and nested `.gitignore` rules, including directory patterns and `!` exceptions, using [`ignore` 7.0.5](https://github.com/kaelzhang/node-ignore/tree/7.0.5). Visited `.gitignore` files stay in the source snapshot. Rules apply to all local files, including files tracked by Git; the Git index, local/global excludes and rules outside the selected source root are not consulted. Git installation and commits are unnecessary.
+
+Mandatory exclusions cover dependencies, credential files, common caches, the declared build output directory, and personal agent state (including `CLAUDE.local.md`, `.claude/settings.local.json`, agent worktrees, authentication files and session logs). Ignore exceptions cannot override these exclusions. Keep shared instructions, skills, setup scripts, lockfiles, tests and configuration inside the source root. Environment templates ending in `.example`, `.sample` or `.template` are allowed; remove actual secrets from their contents. Filename exclusions do not scan for secrets embedded in ordinary files.
+
+Internal source symlinks are copied as ordinary files or directories, and checkout restores executable scripts. External, dangling, cyclic and excluded-target links fail before uploads; compiled output rejects symlinks. Unsafe paths, case collisions and oversized manifests also fail. Checkout never executes project hooks or scripts. Build the exact source you intend to save and keep it unchanged while deploying; build pairing records the uploader’s declaration and does not independently verify compilation.
+
+App write/admin permission is required for source files and complete revision reads. App admins can grant editing access through Share; app read permission continues to govern hosted compiled files. Source files never enter hosted-file delivery.
+
 ### Inside a hosted app
 
 Use the browser entry with the app's existing sign-in session (no API key in frontend code):
 
+Use `app.sources.list()`, `app.sources.get(sourceId)`, and `app.query()` for ordinary
+reads, including counts, lists, filters, and aggregates. Create read actions only
+for deliberate delegated contracts, reusable business rules, or live connector
+calls outside the query API. The built-in assistant queries permitted sources
+directly; invoking any bound action requires viewer confirmation.
+
+Source reads require whole-resource read permission for both the app and viewer,
+including databases, datasets, connectors, and operation outputs. Table, row,
+and column grants within a shared source are unsupported; subResourceId is available
+only to revoke an existing scoped grant. Role-based reads can use separate filtered
+Data Table or Data Flow outputs shared with the appropriate viewers and apps while
+broader upstream sources stay restricted. Follow the
+[filtered-output guide](https://permute.ai/docs/guides/deploy-app#app-filtered-views)
+for allowed rows/columns, historical access, and refresh after assignment changes.
+Test source discovery and a bounded query as the intended viewer before testing the assistant; an empty
+source list describes that viewer's app access, not the workspace's contents.
+
+Plan app and viewer permissions separately. Use `client.apps.setGrant()` for exact
+approved app source IDs; an administrator uses Permute sharing for viewer app and
+source access. Authorized management clients can also use `client.permissions.list`,
+`create`, `update`, `delete`, and `inspect`; hosted app, delegated action, MCP, and
+connector sessions cannot manage grants. The management key needs its own access
+and delegation authority.
+Inspect the complete source before approval (a database may contain other apps’
+tables); never widen a rejected table grant automatically. Apps and keys do not
+inherit their creators’ access. The public
+[app guide](https://permute.ai/docs/guides/deploy-app#app-grants) includes the permission matrix.
+
+Use the built-in assistant rather than adding another AI backend or chat overlay.
+When migrating ordinary read actions, update their callers to the source/query API,
+publish without those bindings, revoke their app grants, and delete the actions
+after confirming no remaining callers. Keep approved write actions and revision pins.
+
 ```ts
 import { PermuteAppClient } from '@permute/sdk/app';
 
 const app = new PermuteAppClient();
+const user = await app.me(); // { id, name, email } for the current signed-in viewer
 const result = await app.query({
   sourceIds: ['dbas_example'],
   sql: 'SELECT * FROM app.contacts',
   limit: 100,
 });
+// Optional: only for an explicitly requested operation with a pinned action.
 const request = { requestId: crypto.randomUUID(), input: { name: 'Ada' } };
 const receipt = await app.actions.invoke('actn_example', request);
 ```
 
+`app.me()` returns the current user’s `id`, `name` and `email`, after checking the app session, membership and app access. Requests use the public API on the app origin (including custom domains), with the HttpOnly cookie and a validated `X-Permute-App-Revision` header. Source reads and lists intersect current user permissions and app grants; action invocation retains the served release’s pinned binding. Password demos cannot call these APIs.
+
+```ts
+const sources = await app.sources.list();
+const chat = await app.chats.create({
+  action: 'send_message',
+  clientRequestId: crypto.randomUUID(),
+  message: 'Show the pipeline',
+});
+const state = await app.chats.get(chat.id);
+await app.chats.send(chat.id, {
+  action: 'send_message',
+  clientRequestId: crypto.randomUUID(),
+  message: 'Group it by stage',
+});
+```
+
+`/v1/chats` preserves conversation and supports turns, cancellation and action decisions. `/v1/answer-jobs` remains one-shot analysis. Chat and basic-profile routes require user authentication; API keys cannot own chats. Other API routes retain their declared authentication requirements. Legacy hosted `__me`, `__queries` and `__actions/{actionId}/invoke` URLs forward to these public handlers. Port older apps by updating the SDK, rebuilding and publishing their bundles so these aliases can be removed. Existing users must sign in again when migrating from opaque cookies to app-scoped JWTs.
+
 The client reads the hosted page's revision-pinned base URL. Save
 `actions: [{ actionId, revisionId }]` with its site manifest, then publish the app revision.
 Queries require current app and user read permissions. The query request selects its
@@ -520,13 +715,110 @@ operation only after resolving any earlier uncertain write.
 
 ## Business actions
 
+Handlers can read declared managed database tables with
+`db.read({ sourceId, table, where, limit })`. Use trusted `caller: { id, type }`
+to choose permitted rows, return only approved fields, and grant invocation access
+without granting database Read. Declare the published schema revision and
+`readTables` in the action's source binding (`writeTables: []` for read-only use).
+Caller identity does not include membership roles; application-specific team rules
+can use a server-side roster. See the
+[caller-filtered database read example](https://permute.ai/docs/guides/business-actions#action-database-reads).
+
+Action handlers can receive a declared `platform` SDK facade. Add `platform.methods`
+and `platform.permissions` to the definition, then call
+`platform.withStep('upload').datasets.create({ type: 'file', fileName: input.fileName, contentType: input.contentType, sizeBytes: input.sizeBytes })`.
+Without `data`, the call returns dataset metadata and an upload target; the handler
+can return that target for the browser to upload bytes. Providing `data` also
+uploads bytes inside the action and must fit its execution and payload limits.
+The server runs the real SDK using the action's delegated grants (callers need
+only action invocation permission). Saving requires Edit draft on the action and
+Read on declared resources; publishing requires Publish and resource Admin to
+delegate those capabilities. Every SDK call needs a distinct, deterministic step ID, including reads.
+Completed calls replay their saved results; reusing an ID with a different method
+or arguments returns `request_conflict`. Calls with uncertain outcomes return
+`outcome_unknown` and block automatic resend. Earlier SDK effects aren't rolled
+back if the action fails.
+Calls share action time and payload limits; dataset helpers return plain data.
+See the [business-actions guide](https://permute.ai/docs/guides/business-actions)
+for supported methods, limits, and authoring examples.
+
+For hosted browser uploads, send file metadata through the bound action and return
+`{ datasetId: dataset.id, upload: dataset.upload }` in its declared output contract.
+Send the `File` as the raw body of `fetch(upload.url, { method: upload.method,
+headers: upload.headers, body: file, credentials: 'omit', redirect: 'error' })`.
+Keep every returned header (including `If-None-Match: *`); don't wrap bytes in
+`FormData` or send cookies or API keys to S3. File bytes bypass the action's
+100 KB input limit. Compiled signed-in apps permit connections to the stage's exact
+regional Datasets bucket; its CORS rule supports PUT and the returned headers,
+including from custom app domains.
+
+S3 object-created events start normal dataset processing. Use a separately bound
+status action declaring `datasets.get` to poll with a new invocation request ID
+for each fresh read; enforce any caller-specific ownership rules in that action.
+Hosted app sessions cannot call dataset APIs directly. Upload URLs are bearer
+capabilities valid for up to 15 minutes (temporary AWS credentials can expire
+earlier), so don't persist or log them. Replaying the create action returns the
+original target without renewing its expiry. After an uncertain PUT, inspect
+processing status before requesting another dataset; a 412 means an object
+already occupies the signed key.
+
 Use `client.actions.create`, `definition`, and `saveDefinition` to author a typed
-handler with selected database tables or connector accounts. Publish with
+handler with declared database, connector, or SDK capabilities. SDK-only and
+connector-only actions need no managed database. Publish with
 `client.revisions.publish`, then call `client.actions.invoke` with a stable
-`requestId` and input. `list` exposes published contracts; reading definitions
-requires admin permission. See the [business action guide](https://permute.ai/docs/guides/business-actions)
+`requestId` and input. `list` and `get` expose published contracts and declared capabilities; reading definitions
+requires View code permission. See the [business action guide](https://permute.ai/docs/guides/business-actions)
 for the complete create, save, publish, and invoke workflow.
 
+### Self-describing action contracts
+
+Use input/output schema descriptions to explain purpose, business terms,
+relationships, create/update behavior, consequential effects, and result meaning
+(external callers cannot inspect the handler). Declare known fields, enums,
+required/optional and nullable values, bounds, and typed outputs structurally.
+Keep field descriptions beside their fields and operation descriptions beside
+their alternatives. Reuse schema definitions for published contracts and handler
+validation where practical.
+
+Bounded `oneOf` alternatives support operation-specific inputs: give each
+alternative a required selector with a distinct `const` value. Exactly one must
+match. Limits are 32 alternatives per `oneOf`, 500 schema nodes, and depth 12.
+Regexes, references, formats, and other composition keywords remain unsupported.
+Keep authorization, normalization, formats, and live business-state checks in the handler.
+
+Supply input/output and field `examples`; save and publication validate them
+without executing the handler. Limits are 10 values per examples array and 50
+examples per input/output contract. Defaults are descriptive and are not inserted.
+Test the handler against examples, rejections, and conflicts as well: structural
+validation cannot guarantee a later write succeeds.
+
+`client.actions.list()` and `get()` return the current published contract, or
+`contract: null` before publication. App MCP discovery retains its app's permitted
+action bindings and exact revision pins. Draft changes do not update those views.
+Declared capabilities are bounds, not a preview of affected records. See the
+[contract-authoring guide](https://permute.ai/docs/guides/business-actions#action-contracts)
+for a complete schema example.
+
+Permute authenticates callers and checks the action’s required invocation
+permission. Hosted app calls also require app access, an app invocation grant,
+and the action revision pinned in the served release. Administrators approve
+delegated resources when authoring and publishing the action.
+
+Execution uses the action’s approved delegated capabilities; callers do not need
+direct access to the underlying sources. A bound connector uses the connected
+account’s access even when the caller has no connector access. Permute enforces
+declared execution capabilities and validates input/output schemas; the handler
+defines the operation exposed to callers.
+
+Handlers receive trusted `caller: { id, type }` (`type` is `user` or `apiKey`).
+An action can use that identity and server-side business data to check or deny a
+request when its rules warrant it (such as an ownership rule or allowed state transition).
+Apply those checks before the affected reads or writes. They supplement the
+platform checks. Permute does not require callers to hold the action’s underlying
+source permissions. Browser-supplied actor IDs or roles are not proof of identity
+or authority. The caller object contains no membership roles or general
+permission lookup API.
+
 ### Expected failures in handlers
 
 Use `reject(code, message, details?)` for a deliberate business rejection:
@@ -540,13 +832,17 @@ exports.handler = ({ input, db, reject }) => {
 ```
 
 Rejection stops the handler and discards staged database writes. It cannot undo
-connector calls already sent. Messages and details are public to callers; never
+connector or SDK effects already sent. Messages and details are public to callers; never
 put credentials or private diagnostic data in them. A rejection message permits
 1–1,000 characters, with up to 20 string detail fields (keys 1–100 characters,
 values up to 500). Invalid rejections and unexpected exceptions return a safe
 `execution_failed` response; exception text stays in server logs.
 
 Both SDK entries expose `PermuteApiError.code`, `.status`, and `.details`.
+Schema validation details include `path`, `rule`, and `schemaPath`, with bounded
+`allowedValues` or `constraint` where available. Compound errors can include
+`issues`; truncation flags indicate omitted diagnostics. Hosted MCP retains the
+same public error code and details in its error result.
 Branch on the code (not message text):
 
 | Code                             | HTTP     | Recovery                                                              |
@@ -567,7 +863,9 @@ does not establish that nothing happened; reconcile provider state first.
 ### Connector bindings
 
 An action definition can bind multiple connector accounts by name alongside its database
-schema bindings. Save and publish require admin permission on each selected resource.
+schema bindings. Saving requires Edit draft on the action and Read on each selected
+resource; publishing requires Publish on the action and source Admin to delegate
+the capabilities.
 The action runs with those delegated capabilities; callers need its invocation permission.
 
 ```ts
@@ -626,3 +924,41 @@ step IDs stable in code. The first attempt pins the revision; successful externa
 replay saved responses. Steps with uncertain outcomes block automatic resend and require
 provider-state reconciliation. There is no automatic rollback, reconciliation API, or
 long-running workflow runner. Connector-only actions can use `sources: []`.
+
+## Hosted app visitor access (next release)
+
+App admins can read `client.apps.access(appId)` and update access with
+`client.apps.setAccess(appId, { mode, expectedVersion, password? })`. Use the
+version returned by the read. `mode: 'password'` requires a new password on each
+save; `mode: 'permute'` clears it. These methods are not in SDK 0.6.0.
+
+Access changes take effect immediately and invalidate app sessions (without
+publishing a site revision). Shared passwords gate published frontend files only,
+including older releases. Use mocked data; demo sessions cannot query sources or
+invoke Business Actions. Permute sign-in retains existing permissions and app grants.
+
+### Custom app addresses
+
+An organization admin first connects a namespace in Organization Settings → App domains and completes the displayed DNS validation. App admins can then assign a name without a new build or CloudFront rollout (the generated Permute URL stays available):
+
+```ts
+const current = await client.apps.address(app.id);
+const namespace = current.namespaces[0]; // Ready namespaces in this organization.
+if (!namespace) throw new Error('Connect an organization app domain first.');
+await client.apps.setAddress(app.id, {
+  address: { namespaceId: namespace.id, label: 'crm' },
+  expectedUrl: current.address?.url ?? null,
+});
+```
+
+Set `address: null` with the currently observed URL to remove it. Stale edits and occupied names return 409. Each hostname uses its own app session; permissions and password-demo restrictions apply on every address. Namespace ownership management is restricted to signed-in organization admins, while these app-level methods support API keys with app admin permission.
+
+## Request missing access
+
+Use `client.accessRequests.create({ resourceId, level: 'read', reason: 'Need this app for customer support' })` to record a request for the authenticated caller. Recording a request does not grant access or confirm that the resource exists. List your requests with `client.accessRequests.list()`.
+
+Reviewers use `client.accessRequests.list({ view: 'review', state: 'pending' })`, then `client.accessRequests.decide(requestId, { decision: 'approved' })` to grant the requested caller access, verify effective access and close the request atomically. Approval never expands app grants (missing app access must be handled separately). Use `resolved` only to verify access already granted. Requesters can cancel with `{ decision: 'cancelled' }` (reviewers can reject with `{ decision: 'rejected' }`).
+
+Lists include a `total` count under the same authorization and filters as their rows. Use `{ view: 'mine', state: 'pending' }` for your pending requests and `{ view: 'history' }` for completed or expired requests you own or currently administer. Resource administrators can list across their authorized resources or narrow with `resourceId`. Expiry and visibility filters apply before cursor pagination.
+
+Hosted apps use `app.accessRequests.create/list/get/cancel`; the server derives app scope from the signed session. See the [access-request contract](../core/src/permissions/README.md) for expiry, reviewer authority and current limits.

package/dist/app.d.ts

@@ -1,6 +1,8 @@
-import type { ActionRequest, ActionReceipt, QueryRequest, QueryResponse } from './types.js';
+import type { AccessRequest, AccessRequestInput, AccessRequestList } from './types.js';
+export type { AccessRequest, AccessRequestInput, AccessRequestList } from './types.js';
+import type { ActionRequest, ActionReceipt, QueryRequest, QueryResponse, AppUser, ChatSendRequest, ChatDecisionRequest, ChatResponse, SourceList, SourceDetail } from './types.js';
 export { PermuteApiError } from './errors.js';
-export type { ActionRequest, ActionReceipt, QueryRequest, QueryResponse } from './types.js';
+export type { ActionRequest, ActionReceipt, QueryRequest, QueryResponse, AppUser, ChatSendRequest, ChatDecisionRequest, ChatResponse, SourceList, SourceDetail, } from './types.js';
 export interface PermuteAppClientOptions {
     /** Defaults to the hosted page's revision-pinned document.baseURI. */
     baseUrl?: string;
@@ -12,12 +14,32 @@ export interface AppRequestOptions {
 /** Browser client authenticated by the hosted app's HttpOnly session cookie. */
 export declare class PermuteAppClient {
     private readonly baseUrl;
+    private readonly revisionId;
     private readonly fetcher;
     constructor(options?: PermuteAppClientOptions);
+    readonly accessRequests: {
+        create: (body: AccessRequestInput, options?: AppRequestOptions) => Promise<AccessRequest>;
+        list: (cursor?: string, options?: AppRequestOptions) => Promise<AccessRequestList>;
+        get: (requestId: string, options?: AppRequestOptions) => Promise<AccessRequest>;
+        cancel: (requestId: string, options?: AppRequestOptions) => Promise<AccessRequest>;
+    };
     readonly actions: {
         /** Keep requestId and input unchanged when retrying an uncertain result. */
         invoke: (actionId: string, request: ActionRequest, options?: AppRequestOptions) => Promise<ActionReceipt>;
     };
+    readonly sources: {
+        list: (options?: AppRequestOptions) => Promise<SourceList>;
+        get: (sourceId: string, options?: AppRequestOptions) => Promise<SourceDetail>;
+    };
+    readonly chats: {
+        create: (request: ChatSendRequest, options?: AppRequestOptions) => Promise<ChatResponse>;
+        get: (chatId: string, options?: AppRequestOptions) => Promise<ChatResponse>;
+        send: (chatId: string, request: ChatSendRequest, options?: AppRequestOptions) => Promise<ChatResponse>;
+        stop: (chatId: string, options?: AppRequestOptions) => Promise<ChatResponse>;
+        decide: (chatId: string, request: ChatDecisionRequest, options?: AppRequestOptions) => Promise<ChatResponse>;
+    };
     query(request: QueryRequest, options?: AppRequestOptions): Promise<QueryResponse>;
+    /** Basic profile of the current Permute user. Password demos have no user identity. */
+    me(options?: AppRequestOptions): Promise<AppUser>;
     private request;
 }

package/dist/app.js

@@ -3,6 +3,7 @@ export { PermuteApiError } from './errors.js';
 /** Browser client authenticated by the hosted app's HttpOnly session cookie. */
 export class PermuteAppClient {
     baseUrl;
+    revisionId;
     fetcher;
     constructor(options = {}) {
         const base = options.baseUrl ?? (typeof document !== 'undefined' ? document.baseURI : undefined);
@@ -14,23 +15,48 @@ export class PermuteAppClient {
             throw new Error('Use a revision-pinned hosted app URL.');
         if (typeof location !== 'undefined' && url.origin !== location.origin)
             throw new Error('App requests must use the current origin.');
-        this.baseUrl = `${url.origin}${revision[0]}`;
+        this.baseUrl = `${url.origin}/v1/`;
+        this.revisionId = revision[1];
         this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
     }
+    accessRequests = {
+        create: (body, options) => this.request('access-requests', body, options),
+        list: (cursor, options) => this.request(`access-requests${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ''}`, undefined, options),
+        get: (requestId, options) => this.request(`access-requests/${encodeURIComponent(requestId)}`, undefined, options),
+        cancel: (requestId, options) => this.request(`access-requests/${encodeURIComponent(requestId)}/decisions`, { decision: 'cancelled' }, options),
+    };
     actions = {
         /** Keep requestId and input unchanged when retrying an uncertain result. */
-        invoke: (actionId, request, options) => this.request(`__actions/${encodeURIComponent(actionId)}/invoke`, request, options),
+        invoke: (actionId, request, options) => this.request(`actions/${encodeURIComponent(actionId)}/invoke`, request, options),
+    };
+    sources = {
+        list: (options) => this.request('sources', undefined, options),
+        get: (sourceId, options) => this.request(`sources/${encodeURIComponent(sourceId)}`, undefined, options),
+    };
+    chats = {
+        create: (request, options) => this.request('chats', request, options),
+        get: (chatId, options) => this.request(`chats/${encodeURIComponent(chatId)}`, undefined, options),
+        send: (chatId, request, options) => this.request(`chats/${encodeURIComponent(chatId)}/turns`, request, options),
+        stop: (chatId, options) => this.request(`chats/${encodeURIComponent(chatId)}/stop`, {}, options),
+        decide: (chatId, request, options) => this.request(`chats/${encodeURIComponent(chatId)}/decisions`, request, options),
     };
     query(request, options) {
-        return this.request('__queries', request, options);
+        return this.request('queries', request, options);
+    }
+    /** Basic profile of the current Permute user. Password demos have no user identity. */
+    me(options) {
+        return this.request('me', undefined, options);
     }
     async request(path, body, options) {
         const response = await this.fetcher(`${this.baseUrl}${path}`, {
-            method: 'POST',
+            method: body === undefined ? 'GET' : 'POST',
             credentials: 'same-origin',
             mode: 'same-origin',
             redirect: 'error',
-            headers: { 'Content-Type': 'application/json' },
+            headers: {
+                'X-Permute-App-Revision': this.revisionId,
+                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+            },
             body: JSON.stringify(body),
             signal: options?.signal,
         });