@agent-native/core 0.157.28 → 0.158.2

package/dist/cli/code-agent-executor.js

@@ -647,6 +647,7 @@ function buildClaudeCliPrompt(run, prompt) {
     const additionalSkillsRoot = process.env.AGENT_NATIVE_CODE_AGENT_SKILLS_ROOT?.trim();
     return [
         `You are running from Agent-Native Code in ${run.cwd || process.cwd()}.`,
+        `Treat ${run.cwd || process.cwd()} as the only project checkout for this run. Keep shell commands, file operations, git pushes, and pull requests rooted there; do not use absolute paths or .. to reach another checkout.`,
         "Follow the repository AGENTS.md and any relevant skill instructions.",
         ...(additionalSkillsRoot
             ? [
@@ -1465,6 +1466,7 @@ function buildCodexCliPrompt(run, prompt) {
     const additionalSkillsRoot = process.env.AGENT_NATIVE_CODE_AGENT_SKILLS_ROOT?.trim();
     return [
         `You are running from Agent-Native Code in ${run.cwd || process.cwd()}.`,
+        `Treat ${run.cwd || process.cwd()} as the only project checkout for this run. Keep shell commands, file operations, git pushes, and pull requests rooted there; do not use absolute paths or .. to reach another checkout.`,
         "Follow the repository AGENTS.md and any relevant skill instructions.",
         ...(additionalSkillsRoot
             ? [
@@ -2164,6 +2166,7 @@ You bring a senior engineer's judgment to the work, but you let it arrive throug
 - When you search for text or files, reach first for \`rg\` or \`rg --files\`; they are much faster than \`grep\` or \`find\`. If \`rg\` is unavailable, use the next best tool without fuss.
 - Parallelize independent read-only work (file reads, searches) so you gather context quickly. Keep mutating steps ordered.
 - Read relevant files before editing them. Do not edit a file you have not actually read.
+- Treat ${cwd} as the only project checkout for this run. Keep shell commands, file operations, git pushes, and pull requests rooted there; do not use absolute paths or .. to reach another checkout.
 
 # Engineering judgment
 

package/dist/coding-tools/index.js

@@ -1,6 +1,5 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
 const DEFAULT_MAX_OUTPUT_CHARS = 50_000;
@@ -63,6 +62,9 @@ export function createCodingToolRegistry(options = {}) {
                 if (!commandCwd) {
                     return "Error: cwd must stay inside the workspace.";
                 }
+                if (restrictToCwd && commandReferencesOutsideWorkspace(command, cwd)) {
+                    return "Error: command paths must stay inside the workspace.";
+                }
                 const requestedTimeoutMs = Number(args.timeoutMs);
                 const timeoutMs = Number.isFinite(requestedTimeoutMs) && requestedTimeoutMs > 0
                     ? Math.min(requestedTimeoutMs, 10 * 60_000)
@@ -367,7 +369,12 @@ export async function runCodingCommand(command, cwd, timeoutMs, options = {}) {
  * calling registry).
  */
 export function spawnBackgroundCommand(command, cwd) {
-    const logFile = path.join(os.tmpdir(), `an-bg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.log`);
+    const logDirectory = resolveCodingPath(cwd, path.join(".agent-native", "background-logs"), { restrictToCwd: true });
+    if (!logDirectory) {
+        throw new Error("Background log path must stay inside the workspace.");
+    }
+    fs.mkdirSync(logDirectory, { recursive: true });
+    const logFile = path.join(logDirectory, `an-bg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.log`);
     const logFd = fs.openSync(logFile, "a");
     const child = spawn(command, {
         cwd,
@@ -464,11 +471,65 @@ function resolveCodingPath(cwd, value, options) {
         : path.resolve(cwd, target);
     if (!options.restrictToCwd)
         return resolved;
-    const relative = path.relative(cwd, resolved);
+    const workspaceRoot = resolveRealPath(cwd);
+    const targetPath = resolveRealPathWithMissingTail(resolved);
+    if (!workspaceRoot || !targetPath)
+        return null;
+    const relative = path.relative(workspaceRoot, targetPath);
     if (relative.startsWith("..") || path.isAbsolute(relative))
         return null;
     return resolved;
 }
+function resolveRealPath(value) {
+    try {
+        return fs.realpathSync(value);
+    }
+    catch {
+        // coercion-ok: an unreadable workspace cannot safely authorize a path.
+        return null;
+    }
+}
+function resolveRealPathWithMissingTail(value) {
+    let candidate = value;
+    const missingTail = [];
+    while (true) {
+        try {
+            fs.lstatSync(candidate);
+            const existingPath = resolveRealPath(candidate);
+            return existingPath ? path.resolve(existingPath, ...missingTail) : null;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                // coercion-ok: an unreadable path cannot safely authorize a workspace path.
+                return null;
+            }
+            const parent = path.dirname(candidate);
+            if (parent === candidate)
+                return null;
+            missingTail.unshift(path.basename(candidate));
+            candidate = parent;
+        }
+    }
+}
+function commandReferencesOutsideWorkspace(command, cwd) {
+    if (/(^|[\s"'=:(])\.\.(?:[/\s"';&|<>)]|$)/.test(command)) {
+        return true;
+    }
+    const workspaceRoot = resolveRealPath(cwd) ?? path.resolve(cwd);
+    const absolutePathPattern = /(?:^|[\s"'=:(])((?:\/(?!\/)|~(?:\/|$))[^\s"';&|<>)]*)/g;
+    for (const match of command.matchAll(absolutePathPattern)) {
+        const value = match[1];
+        if (!value || value.startsWith("~"))
+            return true;
+        const targetPath = resolveRealPathWithMissingTail(path.resolve(value));
+        if (!targetPath)
+            return true;
+        const relative = path.relative(workspaceRoot, targetPath);
+        if (relative.startsWith("..") || path.isAbsolute(relative))
+            return true;
+    }
+    return false;
+}
 function formatFileReadOutput(cwd, filePath, content, args) {
     const lines = content.split("\n");
     const offset = positiveInteger(args.offset, 1);

package/dist/integrations/remote-browser-actions.js

@@ -11,6 +11,7 @@ const CONTROL_ACTIONS = new Set([
     "type",
     "key",
     "navigate",
+    "open-tab",
     "scroll",
 ]);
 const BROWSER_KEYS = new Set([
@@ -142,7 +143,7 @@ function buildReadAction(args) {
 function buildControlAction(args) {
     const action = readString(args, "action");
     if (!action || (!CONTROL_ACTIONS.has(action) && action !== "stop")) {
-        throw new Error("Control action must be attach, click, type, key, navigate, scroll, or stop");
+        throw new Error("Control action must be attach, click, type, key, navigate, open-tab, scroll, or stop");
     }
     if (action === "attach") {
         return {
@@ -201,6 +202,16 @@ function buildControlAction(args) {
             input: { url },
         };
     }
+    if (action === "open-tab") {
+        const url = readString(args, "url");
+        if (!url)
+            throw new Error("url is required");
+        return {
+            type: "browser.open-tab",
+            target: null,
+            input: { url },
+        };
+    }
     if (action === "scroll") {
         return {
             type: "browser.scroll",
@@ -388,7 +399,7 @@ export function createRemoteBrowserActionEntries(options) {
             timeoutMs: 30_000,
             needsApproval: (args) => args.action !== "stop",
             tool: {
-                description: "Attach to and control a user-granted Chrome page. Attach once per conversation before observing or acting. Targets must come from the latest observation. Control actions require inline user approval.",
+                description: "Attach to and control a user-granted Chrome page. Attach once per conversation before observing or acting. Targets must come from the latest observation. The approved open-tab action creates an inactive same-origin tab and moves the lease without focusing Chrome. Control actions require inline user approval.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -401,6 +412,7 @@ export function createRemoteBrowserActionEntries(options) {
                                 "type",
                                 "key",
                                 "navigate",
+                                "open-tab",
                                 "scroll",
                                 "stop",
                             ],

package/dist/observability/routes.d.ts

@@ -42,22 +42,22 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     avgEvalScore: number;
 } | {
     error?: undefined;
+    ok?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-    ok?: undefined;
 } | {
     error?: undefined;
+    ok?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;
-    ok?: undefined;
 } | {
+    ok?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
-    ok?: undefined;
 } | {
     error?: undefined;
     summary?: undefined;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

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 — validate an optional candidate value
  * or the current stored value without changing anything.
  */
 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,11 +95,11 @@ 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;
 }>>;

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

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
+    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
-    error?: undefined;
 }>>;

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    text: string;
     error?: undefined;
+    text: string;
 }>>;

package/docs/content/authentication.mdx

@@ -179,14 +179,17 @@ flag state. Custom and third-party apps are excluded.
 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` to opt in.
-Stable Desktop builds do not initialize the broker until a later release is
-separately approved.
+Every Desktop build may initialize the broker when the per-device
+`desktopSsoEnabled` preference is true (the default); an explicit persisted
+`false` remains an opt-out. The `desktop.workspace-sso` Dispatch flag must also
+be enabled. The Canary user-agent marker no longer gates broker initialization;
+it only identifies the update channel.
 The Canary user-agent marker is an availability hint rather than remote
 attestation. Authentication and authorization never trust it; supervised
 acceptance binds the client through exact signed-artifact provenance.
-The Canary does not intercept anonymous app sign-in navigation. The user must
-explicitly choose workspace sign-in in Desktop Settings for the active
-registered app; ordinary app sign-in remains the default path.
+For an eligible registered app, Desktop presents the workspace sign-in surface
+over the app's sign-in flow. If the rollout is unavailable or the app is not
+eligible, ordinary per-app sign-in remains available.
 
 ## QA Accounts {#qa-accounts}
 

package/docs/content/cross-app-sso.mdx

@@ -37,6 +37,22 @@ cookie**. Each separately hosted app still creates and owns its own local
 session. Dispatch proves the user's identity at the app's front door, and the
 app then continues with its normal local auth and access checks.
 
+## Mobile and app-scoped embed sessions {#mobile-embed-sessions}
+
+Mobile chat and Dispatch panes use a different contract from MCP-hosted iframe
+embeds. The mobile client first authenticates the parent session, then requests
+an app-scoped, one-time embed ticket for the target workspace app. The ticket
+is exchanged at the target app's embed-start endpoint for a short-lived local
+embed session and is consumed once. It is not a reusable bearer token, is not
+placed in a long-lived URL, and does not grant access to another app.
+
+This flow lets a mobile WebView or Dispatch pane open a target app while the
+target app still owns its session and authorization checks. A missing, expired,
+replayed, or cross-app ticket must fail closed; it must not be treated as an
+anonymous session or silently fall back to the parent bearer. The `embed
+session` described in [MCP Apps](/docs/mcp-apps) is a separate MCP-host iframe
+feature and is not this mobile handoff contract.
+
 The packaged Desktop Canary is deliberately more explicit: it never intercepts
 anonymous app sign-in navigation. The user chooses workspace sign-in once in
 Desktop Settings; Desktop then provisions every currently eligible registered
@@ -352,14 +368,21 @@ Desktop leaves ordinary per-app sign-in, sign-out, and Settings unchanged.
 Canonical hosted apps recognize the packaged Desktop request and ordinary web
 browsers without requiring `AGENT_NATIVE_IDENTITY_HUB_URL` on every deployment;
 self-hosted apps still require that explicit configuration.
-Stable Desktop builds do not initialize the broker until a later release is
-separately approved.
+Every Desktop build may initialize the broker when the per-device
+`desktopSsoEnabled` preference is true (the default); an explicit persisted
+`false` remains an opt-out. The `desktop.workspace-sso` Dispatch flag must also
+be enabled. The Canary user-agent marker no longer gates broker initialization;
+it only identifies the update channel.
 The Canary user-agent marker is an availability hint, not remote attestation;
 the server cannot infer code signature from HTTP. No authentication or
 authorization decision trusts it. Supervised acceptance therefore binds the
 tested client through the signed artifact's exact commit, manifest, hashes, and
 notarization evidence.
 
+For an eligible registered app, Desktop presents the workspace sign-in surface
+over the app's sign-in flow. If the rollout is unavailable or the app is not
+eligible, ordinary per-app sign-in remains available.
+
 ## Self-hosting {#self-hosting}
 
 Any Dispatch deployment can serve as the identity hub — you are not limited to `dispatch.agent-native.com`. Set `AGENT_NATIVE_IDENTITY_HUB_URL` on each client app to point at your Dispatch instance:

package/docs/content/portal.mdx

@@ -0,0 +1,61 @@
+---
+title: "Portal"
+description: "Pair a computer and continue Agent-Native work across devices with Portal."
+---
+
+# Portal
+
+Portal connects a phone or browser to a registered computer so an Agent-Native
+workspace can continue work on the machine that owns the local tools. It is a
+device handoff feature, not a second chat or a cloud runner.
+
+## Pair a computer
+
+In the app, open **Settings → Workspace** and choose **Pair or repair**. The
+pairing flow shows a relay URL and workspace path. Open the URL on the computer
+you want to pair and confirm the workspace path there. The computer registers
+itself with the workspace through:
+
+```text
+POST /_agent-native/integrations/remote/register
+```
+
+The registration returns a device token. Store that token in the computer's
+private `~/.agent-native/remote-device.json` file. Do not put it in source
+control, a URL, or a client-visible application setting. If pairing is lost,
+use **Pair or repair** again to replace the device registration.
+
+## Execution modes
+
+The chat composer can target the execution environment that fits the task:
+
+- **Local** runs on the current app/runtime.
+- **Computer** runs on a paired computer through Portal, so local files and
+  installed coding tools are available there.
+- **Cloud** is a waitlisted execution mode. Until access is enabled, choosing
+  Cloud does not start a run; it only shows the waitlist state.
+
+The selected mode is part of the run request. Pairing a computer does not copy
+credentials or grant it access to unrelated workspaces; the device and
+workspace registration remain scoped to the authenticated account.
+
+## Troubleshooting
+
+If Computer is unavailable, confirm the paired computer is online, the relay
+URL is reachable, and the workspace path still exists. Repair the pairing when
+the device token was rotated or the workspace moved. If Cloud is unavailable,
+the run has not started - use Local or Computer instead of retrying a queued
+cloud request.
+
+## Environment variables
+
+Self-hosted deployments can customize the Portal connection with:
+
+| Variable                             | Purpose                                                              |
+| ------------------------------------ | -------------------------------------------------------------------- |
+| `WORKSPACE_GATEWAY_URL`              | Public workspace gateway used for device handoff.                    |
+| `AGENT_NATIVE_REMOTE_DEVICE_PATH`    | Override the local device registration file path.                    |
+| `AGENT_NATIVE_COMPUTER_BRIDGE_URL`   | Computer bridge URL used by remote execution.                        |
+| `AGENT_NATIVE_COMPUTER_BRIDGE_TOKEN` | Token used to authenticate with that bridge.                         |
+| `AGENT_NATIVE_REMOTE_ENGINES`        | Comma-separated remote execution engines available to the workspace. |
+| `AGENT_NATIVE_IDENTITY_HUB_URL`      | Optional Dispatch identity hub for self-hosted cross-app sign-in.    |

package/package.json

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