@timurproko/a1 0.2.7-dev.754 → 0.2.7-dev.772

package/README.md

@@ -57,6 +57,12 @@ Launch A1 (profile: `~/.a1/agent`):
 a1
 ```
 
+Launch A1 in single agent mode:
+
+```text
+a1 solo
+```
+
 Show all commands:
 
 ```text
@@ -77,6 +83,30 @@ a1 pi
 
 <p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme/separator-dark.svg"><img src="docs/assets/readme/separator.svg" alt="" width="280"></picture></p>
 
+## Tabs
+
+Tabs keep running after their terminal closes. List them, or stop one; its session stays resumable:
+
+```text
+a1 tabs
+a1 tabs stop <id>
+```
+
+Stop every tab and the resident host, for example before going back to single agent mode with `a1 solo`:
+
+```text
+a1 tabs host stop
+```
+
+Show host health, or write a redacted diagnostic bundle:
+
+```text
+a1 tabs host status
+a1 tabs doctor
+```
+
+<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme/separator-dark.svg"><img src="docs/assets/readme/separator.svg" alt="" width="280"></picture></p>
+
 ## Update
 
 Install the release:

package/bin/cli.js

@@ -69,6 +69,10 @@ process.exitCode = await dispatchCli(process.argv.slice(2), {
       },
     });
   },
+  tabs: async request => {
+    const { runTabsCommand } = await import("../dist/cli/tabs.js");
+    return await runTabsCommand(request, { packageRoot: fileURLToPath(packageRoot) });
+  },
 }, {
   stdout: message => process.stdout.write(message),
   stderr: message => process.stderr.write(message),

package/bin/guardian.js

@@ -16,8 +16,13 @@ const profileId = readLaunchContext(process.env, "profile").launchProfile;
 if (releaseRoot === undefined || profileId === undefined) throw new Error("A1 launch context is incomplete");
 
 const sessionSelection = parseSessionSelection(process.argv.slice(2));
+const rootCommand = launchContext.residentRootExecutable === undefined ? undefined : {
+  executable: launchContext.residentRootExecutable,
+  arguments: JSON.parse(launchContext.residentRootArguments ?? "[]"),
+};
 Promise.resolve().then(() => runLaunchGuardian({
   ...(sessionSelection === undefined ? {} : { sessionSelection }),
+  ...(rootCommand === undefined ? {} : { rootCommand }),
   profileId,
   releaseRoot,
   uiEntry: resolve(releaseRoot, "bin", "ui.js"),

package/bin/tab-launch-context.d.ts

@@ -0,0 +1,26 @@
+export interface TabLaunchCredentials {
+  readonly tabId: string;
+  readonly token: string;
+  readonly endpoint: string;
+}
+
+export function formatResidentFallbackNotice(reason: string): string;
+
+export function assignFreshSessionRuntimeId(
+  environment: Record<string, string | undefined>,
+  name: string,
+  createId: () => string,
+): string;
+
+export function waitForStandbyPromotion(input: NodeJS.ReadStream, promotionFile?: string): Promise<void>;
+
+export function consumeTabLaunchContext(
+  arguments_: readonly string[],
+  environment: Record<string, string | undefined>,
+): {
+  readonly uiArguments: string[];
+  readonly tabCredentials: TabLaunchCredentials | undefined;
+  readonly tabDataDir?: string;
+  readonly tabIncarnation?: number;
+  readonly tabStandby: boolean;
+};

package/bin/tab-launch-context.js

@@ -0,0 +1,94 @@
+import { existsSync } from "node:fs";
+
+const TAB_ENVIRONMENT_NAMES = ["A1_TAB_ID", "A1_TAB_TOKEN", "A1_TAB_ENDPOINT"];
+
+/** @param {string} reason */
+export function formatResidentFallbackNotice(reason) {
+  // Protocol: a host of another generation is never replaced automatically; only the user stops it.
+  if (reason === "incompatible generation") {
+    return "A1 normal mode unavailable (running tabs use another version); running in single agent mode. Run `a1 tabs host stop` to restart them on this version.";
+  }
+  return `A1 normal mode unavailable (${reason}); running in single agent mode.`;
+}
+
+/**
+ * @param {Record<string, string | undefined>} environment
+ * @param {string} name
+ * @param {() => string} createId
+ */
+export function assignFreshSessionRuntimeId(environment, name, createId) {
+  const id = createId();
+  if (typeof id !== "string" || id.length === 0 || id.includes("\0")) throw new Error("Session runtime identity generation failed");
+  environment[name] = id;
+  return id;
+}
+
+/**
+ * Keep the standby below the session/runtime boundary until its authenticated holder promotes it.
+ * Platform: Windows ConPTY may drop the in-band marker, so the holder also creates the promotion
+ * file inside the tab's private data directory; whichever arrives first promotes the standby.
+ * @param {NodeJS.ReadStream} input
+ * @param {string} [promotionFile]
+ */
+export function waitForStandbyPromotion(input, promotionFile) {
+  return /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
+    const marker = Buffer.from("\x1b]a1;standby-promote\x07");
+    let buffered = Buffer.alloc(0);
+    /** @type {NodeJS.Timeout | undefined} */
+    let poll;
+    const cleanup = () => {
+      if (poll !== undefined) clearInterval(poll);
+      input.off("data", onData);
+      input.off("error", onError);
+      input.pause();
+      if (input.isTTY) input.setRawMode(false);
+    };
+    /** @param {Error} error */
+    const onError = error => { cleanup(); reject(error); };
+    /** @param {Buffer | string} chunk */
+    const onData = chunk => {
+      const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+      buffered = Buffer.concat([buffered, bytes]).subarray(-marker.length);
+      if (buffered.equals(marker)) { cleanup(); resolve(undefined); }
+    };
+    if (input.isTTY) input.setRawMode(true);
+    input.on("data", onData);
+    input.on("error", onError);
+    input.resume();
+    if (promotionFile !== undefined) {
+      poll = setInterval(() => {
+        if (existsSync(promotionFile)) { cleanup(); resolve(undefined); }
+      }, 10);
+    }
+  }));
+}
+
+/**
+ * Security: consume bridge credentials into caller-private memory and erase their inheritable
+ * environment entries before any extension-capable module loads.
+ * @param {readonly string[]} arguments_
+ * @param {Record<string, string | undefined>} environment
+ */
+export function consumeTabLaunchContext(arguments_, environment) {
+  const uiArguments = [...arguments_];
+  const tabArgument = uiArguments.indexOf("--tab");
+  const tabMode = tabArgument !== -1;
+  if (tabMode) uiArguments.splice(tabArgument, 1);
+  const standbyArgument = uiArguments.indexOf("--tab-standby");
+  const tabStandby = standbyArgument !== -1;
+  if (tabStandby) uiArguments.splice(standbyArgument, 1);
+  const dataArgument = uiArguments.indexOf("--tab-data-dir");
+  const tabDataDir = dataArgument === -1 ? undefined : uiArguments[dataArgument + 1];
+  if (dataArgument !== -1) uiArguments.splice(dataArgument, 2);
+  const incarnationArgument = uiArguments.indexOf("--tab-incarnation");
+  const tabIncarnation = incarnationArgument === -1 ? undefined : Number(uiArguments[incarnationArgument + 1]);
+  if (incarnationArgument !== -1) uiArguments.splice(incarnationArgument, 2);
+  const [tabId, token, endpoint] = TAB_ENVIRONMENT_NAMES.map(name => environment[name]);
+  for (const name of TAB_ENVIRONMENT_NAMES) delete environment[name];
+  if (!tabMode) return { uiArguments, tabCredentials: undefined, tabStandby: false };
+  if (!tabId || !token || !endpoint || !tabDataDir || tabDataDir.includes("\0")
+    || typeof tabIncarnation !== "number" || !Number.isSafeInteger(tabIncarnation) || tabIncarnation < 1) {
+    throw new Error("A1 tab mode requires bridge credentials, recovery directory, and incarnation");
+  }
+  return { uiArguments, tabCredentials: { tabId, token, endpoint }, tabDataDir, tabIncarnation, tabStandby };
+}

package/bin/ui.js

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 
+// Security: this helper has no A1, Pi, tool, or extension dependency and erases credentials before those modules load.
+const { assignFreshSessionRuntimeId, consumeTabLaunchContext, formatResidentFallbackNotice, waitForStandbyPromotion } = await import("./tab-launch-context.js");
+const { uiArguments, tabCredentials, tabDataDir, tabIncarnation, tabStandby } = consumeTabLaunchContext(process.argv.slice(2), process.env);
+
 // Invariant: one terminal module identity per process, decided before any A1 or Pi module loads.
 const { installPinnedPiTuiResolver } = await import("./module-resolver.js");
 installPinnedPiTuiResolver(new URL("..", import.meta.url).pathname.replace(/^\/(.:)/, "$1").replace(/\/$/, ""));
 const startup = await import("../dist/foundation/startup/startup-runtime.js");
 startup.enableEnvironmentCompileCache(process.env);
-const { readLaunchContext } = await import("../dist/foundation/launch-context/index.js");
+const { hidesTabSettings, readLaunchContext } = await import("../dist/foundation/launch-context/index.js");
 const launchContext = readLaunchContext(process.env, "profile");
 const profile = launchContext.launchProfile;
 if (profile === undefined) throw new Error("A1 launch profile is missing");
@@ -14,15 +18,17 @@ if (profile === "a1") {
     import("node:crypto"),
     import("../dist/product-identity.js"),
   ]);
-  process.env[PRODUCT_IDENTITY.environment.sessionRuntimeId] = randomUUID();
+  assignFreshSessionRuntimeId(process.env, PRODUCT_IDENTITY.environment.sessionRuntimeId, randomUUID);
 }
 const { installFatalExit } = await import("../dist/foundation/terminal-cleanup/fatal-exit.js");
 const { resolveProductPaths } = await import("../dist/foundation/lifecycle/paths.js");
-const { join } = await import("node:path");
+const { dirname, join } = await import("node:path");
 /** @type {{ dispose(): void | Promise<unknown> } | undefined} */
 let runningApplication;
 const fatal = profile === "a1" ? installFatalExit({
-  directory: join(resolveProductPaths().runtimeDir, "crashes"),
+  directory: tabDataDir === undefined
+    ? join(resolveProductPaths().runtimeDir, "crashes")
+    : join(dirname(tabDataDir), "diagnostics"),
   ...(launchContext.releaseId === undefined ? {} : { releaseId: launchContext.releaseId }),
   dispose: () => runningApplication?.dispose(),
 }) : undefined;
@@ -46,13 +52,20 @@ const [
   { composeOwnedUi },
 ] = await modules;
 
+if (tabStandby) await waitForStandbyPromotion(process.stdin, tabDataDir === undefined ? undefined : join(tabDataDir, "standby-promote"));
+
 // Compatibility: before the composition uses pinned Pi's terminal stack: confirm A1 and Pi
 // resolve it to the same copy, so extensions and the owned UI share one module identity.
 identity.assertSinglePiTuiModuleAtLaunch(packageRootPath, (/** @type {string} */ message) => process.stderr.write(message));
 await startup.markStartupPhase(process.env, "ui-modules-loaded");
 
-const sessionSelection = parseSessionSelection(process.argv.slice(2));
-Promise.resolve().then(() => {
+const sessionSelection = parseSessionSelection(uiArguments);
+Promise.resolve().then(async () => {
+  const tab = tabCredentials === undefined ? undefined : {
+    bridge: new (await import("../dist/foundation/resident-tabs/bridge-client.js")).TabBridgeClient({ credentials: tabCredentials }),
+    dataDir: /** @type {string} */ (tabDataDir),
+    incarnation: /** @type {number} */ (tabIncarnation),
+  };
   if (sessionSelection && profile !== "a1") throw new Error("session selection requires the normal A1 profile");
   return runSelectedInteractiveRuntime(profile, {
     ownedUi: async (profileId, ownedSurfaces) => {
@@ -65,10 +78,15 @@ Promise.resolve().then(() => {
         cwd: process.cwd(),
         profileId,
         ownedSurfaces,
+        ...(hidesTabSettings(launchContext) ? { hideTabSettings: true } : {}),
         ...(processInspector === null ? {} : { inspectProcess: pid => processInspector.observe(pid) }),
         projectTrustPrompt: createConsoleProjectTrustPrompt({ presentation: profile === "a1" ? "bare" : "comparison" }),
         sessionForkPrompt: createConsoleSessionForkPrompt(),
         ...(sessionSelection === undefined ? {} : { sessionSelection }),
+        ...(tab === undefined ? {} : { tab }),
+        ...(launchContext.residentFallback === undefined ? {} : {
+          residentFallbackNotice: formatResidentFallbackNotice(launchContext.residentFallback),
+        }),
       });
       runningApplication = application;
       return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });

package/dist/app/session-shell/helper-pool.d.ts

@@ -12,16 +12,14 @@ export interface HelperPoolOptions {
     readonly stop: (child: ChildProcess) => void;
     readonly idleMs?: number;
 }
-/**
- * Keeps one forked IPC helper ready so a request takes a live child instead of paying fork and module
- * load on its own critical path. The spare stays idle on its channel until it is taken; a spare that
- * exits or idles too long is dropped, and the next request forks cold and warms a replacement afterwards.
- */
+/** Holds one idle IPC helper; requests take it, and exits, expiry, or use trigger replacement. */
 export declare class HelperPool {
     #private;
     constructor(options: HelperPoolOptions);
     /** Whether a spare is currently held (ready or still starting). */
     get warmed(): boolean;
+    /** Whether the held spare has announced that module loading is complete. */
+    get ready(): boolean;
     /** Opts the pool in and forks the first spare; from here on `replenish` keeps one ready after each request. */
     warm(): void;
     /** Forks the next spare after a request released its child; a no-op until the owner warmed the pool. A fork failure leaves the pool empty. */

package/dist/app/session-shell/helper-pool.js

@@ -1,10 +1,6 @@
 /** How long an unused spare helper may idle before it is stopped so a background session holds no extra process. */
 export const HELPER_SPARE_IDLE_MS = 5 * 60_000;
-/**
- * Keeps one forked IPC helper ready so a request takes a live child instead of paying fork and module
- * load on its own critical path. The spare stays idle on its channel until it is taken; a spare that
- * exits or idles too long is dropped, and the next request forks cold and warms a replacement afterwards.
- */
+/** Holds one idle IPC helper; requests take it, and exits, expiry, or use trigger replacement. */
 export class HelperPool {
     #fork;
     #stop;
@@ -19,6 +15,8 @@ export class HelperPool {
     }
     /** Whether a spare is currently held (ready or still starting). */
     get warmed() { return this.#spare !== undefined; }
+    /** Whether the held spare has announced that module loading is complete. */
+    get ready() { return this.#spare?.ready === true; }
     /** Opts the pool in and forks the first spare; from here on `replenish` keeps one ready after each request. */
     warm() {
         if (this.#disposed)

package/dist/app/session-shell/session-shell-root.d.ts

@@ -43,6 +43,33 @@ export interface OwnedUiShellEngineOptions {
     };
     /** Bare A1 selects the owned bounded viewport; comparison profiles stay pinned. */
     readonly sessionLayout?: "pinned" | "custom-viewport";
+    /** Resident tab quit routes detach the outer client without stopping this engine session. */
+    readonly residentTab?: {
+        requestDetach(): Promise<boolean>;
+        reportStatus?(status: "working" | "idle" | "stalled"): void;
+        readonly stallNoticeSeconds?: number;
+        admit?(input: {
+            readonly sessionId: string;
+            readonly sessionFile: string | null;
+            readonly kind: "prompt" | "steer" | "follow-up";
+            readonly text: string;
+            readonly images?: readonly unknown[];
+        }): Promise<{
+            readonly id: string;
+        }>;
+        dispatched?(): void;
+        correlated?(submissionId: string, entryId: string): Promise<void>;
+        checkpoint?(text: string): void;
+        gracefulStop?(sessionFile: string | null): Promise<void>;
+        readonly recovered?: {
+            readonly prompts: readonly {
+                readonly id: string;
+                readonly text: string;
+            }[];
+            readonly draft: string | null;
+        };
+        readonly unavailableNotice?: string;
+    };
 }
 /** Terminal, startup, viewport, and presentation-cadence seams; production leaves most at their defaults. */
 export interface OwnedUiShellPresentationOptions {
@@ -182,7 +209,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         readonly onPromptSuggestionAccepted?: (text: string) => void;
         readonly onInputSurfaceChanged?: () => void;
         readonly onPromptSuggestionEligibilityChanged?: () => void;
-        readonly onCopyText?: (text: string) => void;
+        readonly onCopyText?: (text: string, cut: boolean) => void;
         readonly readClipboardContent?: (signal?: AbortSignal) => Promise<PiShellClipboardContent | null>;
         readonly captureClipboardPaste?: () => PasteSource;
         readonly pasteDiagnostics?: (event: PasteEvent) => void;

package/dist/app/session-shell/session-shell-root.js

@@ -458,7 +458,7 @@ export class OwnedUiSessionShellRoot {
             && snapshot.inputSurface === inputSurface
             && snapshot.viewportRevision === viewportRevision
             && snapshot.selectionRevision === selectionRevision
-            ? this.#viewportController.composeDockOnly(dockRows, width, height)
+            ? this.#viewportController.composeDockOnly(dockRows, width, height, dock.footerRows)
             : null;
         if (frame === null) {
             frame = this.#viewportController.compose({
@@ -474,6 +474,7 @@ export class OwnedUiSessionShellRoot {
                 ...(document.liveTailStartRow === undefined ? {} : { liveTailStartRow: document.liveTailStartRow }),
                 bottomAlignedTailRowCount: steeringRows.length + statusRows.length,
                 dockRows,
+                explicitCopyDockRows: dock.footerRows,
                 promptAnchors: document.promptAnchors,
                 width,
                 height,
@@ -603,7 +604,6 @@ export class OwnedUiSessionShellRoot {
         const transientRows = [...queued, ...statusRows, ...this.#renderDockNotice(width)];
         const aboveWidgets = this.#renderWidgets("aboveEditor", width);
         const input = this.#inputSurface.render(width);
-        // Invariant: pointer rows describe the body, not the autocomplete block now preceding it.
         const body = this.usesDefaultInputSurface() ? this.editor.bodyGeometry?.() : undefined;
         const belowWidgets = this.#renderWidgets("belowEditor", width);
         const footer = this.#renderFooter(width);
@@ -614,6 +614,7 @@ export class OwnedUiSessionShellRoot {
             inputOffset,
             editorOffset: inputOffset + (body?.rowOffset ?? 0),
             inputRows: body?.rowCount ?? input.length,
+            footerRows: footer.length,
         };
     }
     #renderCopyAcknowledgement(width) {
@@ -915,7 +916,7 @@ export class OwnedUiSessionShellRoot {
         if (result.command === "hotkeys" && result.outcome === "completed") {
             this.#lastWorkflowStatusId = undefined;
             const presentation = this.hotkeysPresentation();
-            const hotkeys = createPiShellHotkeys(presentation.bindings, presentation.getShortcuts, presentation.profile);
+            const hotkeys = createPiShellHotkeys(presentation.bindings, presentation.getShortcuts, presentation.profile, presentation.residentTabs);
             this.#appendAnchoredWorkflowComponent(width => hotkeys.render(width), () => hotkeys.dispose?.());
             return;
         }