@timurproko/a1 0.2.6 → 0.2.7-dev.1222

package/dist/cli/tabs.js

@@ -0,0 +1,151 @@
+import { resolveProductPaths } from "../foundation/lifecycle/index.js";
+import { materializeRelease } from "../foundation/release/index.js";
+import { readResidentTabLaunchSettings, runTerminalHostMaintenance, writeDoctorBundle, } from "../foundation/resident-tabs/index.js";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../product-identity.js";
+/** `a1 tabs`: inspect or stop resident tabs without attaching, and never start a host to report state. */
+export async function runTabsCommand(request, options = {}) {
+    const environment = options.environment ?? process.env;
+    const stdout = options.stdout ?? (message => process.stdout.write(message));
+    const stderr = options.stderr ?? (message => process.stderr.write(message));
+    const paths = resolveProductPaths(environment);
+    const profileRoot = environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir;
+    const releaseRoots = await invokingReleaseRoots(paths.dataDir, options.packageRoot, environment);
+    const maintenance = options.maintenance ?? runTerminalHostMaintenance;
+    const report = await maintenance({
+        action: request.action === "doctor" ? "host-status" : request.action,
+        ...(request.tabId === undefined ? {} : { tabId: request.tabId }),
+        profileRoot,
+        dataDir: paths.dataDir,
+        runtimeDir: paths.runtimeDir,
+        releaseRoots,
+        environment,
+    });
+    if (request.action === "doctor") {
+        if (!report.stateDir) {
+            stderr(`${PRODUCT_TEXT.diagnostic(`tabs doctor could not locate resident state: ${report.message ?? report.host}`)}\n`);
+            return 1;
+        }
+        const settings = await readResidentTabLaunchSettings(environment.PI_CODING_AGENT_DIR ?? paths.configDir, PRODUCT_IDENTITY.commandName, paths.configDir, "a1");
+        const bundle = await (options.doctor ?? writeDoctorBundle)({
+            stateDir: report.stateDir,
+            hostStatus: report,
+            releaseRoots,
+            settings: { tabsAutoName: settings.tabsAutoName },
+        });
+        if (request.json)
+            stdout(`${JSON.stringify({ schema: "a1-tabs-doctor-v1", path: bundle.path, bytes: bundle.bytes, dropped: bundle.dropped })}\n`);
+        else
+            stdout(`Wrote ${bundle.path}\n`);
+        return 0;
+    }
+    if (request.json) {
+        const { exitCode: _exitCode, ...printed } = report;
+        stdout(`${JSON.stringify(printed)}\n`);
+    }
+    else {
+        const text = describe(request, report);
+        if (report.exitCode === 0)
+            stdout(text);
+        else
+            stderr(text);
+    }
+    return report.exitCode === 0 ? 0 : 1;
+}
+async function invokingReleaseRoots(dataDir, packageRoot, environment) {
+    if (!packageRoot)
+        return [];
+    if (environment[PRODUCT_IDENTITY.environment.developmentInstanceId])
+        return [packageRoot];
+    try {
+        // Invariant: immutable materialization selects exact payload bytes without activating or starting a host.
+        return [(await materializeRelease(packageRoot, dataDir)).releaseRoot];
+    }
+    catch {
+        return [];
+    }
+}
+const NO_TABS = "No resident tabs are running.\n";
+function describe(request, report) {
+    const command = PRODUCT_TEXT.commandName;
+    if (report.host === "none")
+        return NO_TABS;
+    if (report.host === "unavailable")
+        return `${PRODUCT_TEXT.diagnostic(`tabs could not run maintenance: ${report.message ?? "terminal host unavailable"}`)}\n`;
+    if (report.host === "unresponsive") {
+        return `The resident host (pid ${report.pid ?? "unknown"}) is not responding. Run \`${command} tabs host stop\` to stop it.\n`;
+    }
+    if (report.host === "incompatible") {
+        return `${PRODUCT_TEXT.diagnostic(report.message ?? "running tabs use another version")} Run \`${command} tabs host stop\` from that version.\n`;
+    }
+    if (report.host === "unverifiable" || report.host === "refused") {
+        return `${PRODUCT_TEXT.diagnostic(report.message ?? "the resident host could not be verified; nothing was changed")}\n`;
+    }
+    const result = report.result ?? {};
+    if (request.action === "list")
+        return listing(result);
+    if (request.action === "host-status")
+        return status(result);
+    if (request.action === "host-stop") {
+        if (report.host === "stopped")
+            return "Stopped every tab and the resident host.\n";
+        return `Could not stop every tab: ${remaining(result)}. The host is still running.\n`;
+    }
+    if (result.accepted === false && typeof result.message === "string") {
+        return `${PRODUCT_TEXT.diagnostic(`tabs stop: ${result.message === "unknown tab" ? `no tab ${request.tabId ?? ""}` : result.message}`)}\n`;
+    }
+    const stopped = Array.isArray(result.stopped) ? result.stopped.length : 0;
+    if (result.accepted === false)
+        return `Could not stop: ${remaining(result)}.\n`;
+    if (request.action === "stop")
+        return `Stopped tab ${request.tabId ?? ""}; its session can be resumed.\n`;
+    return stopped === 0 ? NO_TABS : `Stopped ${stopped} tab${stopped === 1 ? "" : "s"}; their sessions can be resumed.\n`;
+}
+function remaining(result) {
+    return Array.isArray(result.remaining) && result.remaining.length > 0 ? result.remaining.join(", ") : "unknown tabs";
+}
+function listing(result) {
+    const tabs = Array.isArray(result.tabs) ? result.tabs : [];
+    if (tabs.length === 0)
+        return NO_TABS;
+    const rows = [
+        ["ID", "NAME", "STATUS", "CWD", "RELEASE", "HOLDER"],
+        ...tabs.map(tab => [tab.tabId, tab.name, tab.status, tab.cwd, tab.release, tab.holderPid ?? "-"].map(value => String(value ?? "-"))),
+    ];
+    const widths = rows[0].map((_, column) => Math.max(...rows.map(row => row[column].length)));
+    return `${rows.map(row => row.map((cell, column) => column === row.length - 1 ? cell : cell.padEnd(widths[column])).join("  ")).join("\n")}\n`;
+}
+function status(result) {
+    const limits = (result.limits ?? {});
+    const counters = (result.counters ?? {});
+    const byStatus = (result.tabsByStatus ?? {});
+    const lines = [
+        `pid: ${String(result.pid ?? "-")}`,
+        `build: ${String(result.build ?? "-")}`,
+        `release: ${String(result.release ?? "-")}`,
+        `generation: ${String(result.generation ?? "-")}`,
+        `epoch: ${String(result.epoch ?? "-")}`,
+        `uptime: ${String(result.uptimeSeconds ?? "-")}s`,
+        `detachment: ${String(result.detachmentMode ?? "unknown")}${result.detachmentVerified === false ? " (not verified)" : ""}`,
+        `tabs: ${String(result.tabs ?? 0)}${Object.keys(byStatus).length > 0 ? ` (${Object.entries(byStatus).map(([key, value]) => `${key} ${String(value)}`).join(", ")})` : ""}`,
+        `clients: ${String(result.clients ?? 0)}`,
+        ...startsAndLifecycle(result),
+        `limits: ${Object.entries(limits).map(([key, value]) => `${key} ${String(value)}`).join(", ")}`,
+        `counters: ${Object.entries(counters).map(([key, value]) => `${key} ${String(value)}`).join(", ")}`,
+        ...(Array.isArray(result.logs) ? result.logs.map(path => `log: ${String(path)}`) : []),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+/** Lifecycle work running this long means a terminal's tab requests are stuck. */
+const LIFECYCLE_STALL_MS = 10_000;
+function startsAndLifecycle(result) {
+    const lines = [];
+    const starts = result.starts;
+    if (starts)
+        lines.push(`starts: active ${String(starts.active ?? 0)}, waiting ${String(starts.interactiveWaiting ?? 0)}, recovering ${String(starts.recoverySlots ?? 0)}`);
+    const lifecycle = result.lifecycle;
+    if (lifecycle) {
+        const oldest = typeof lifecycle.oldestMs === "number" ? lifecycle.oldestMs : 0;
+        lines.push(`lifecycle: pending ${String(lifecycle.pending ?? 0)}, oldest ${oldest}ms${oldest > LIFECYCLE_STALL_MS ? " (stalled)" : ""}`);
+    }
+    return lines;
+}

package/dist/cli/version-stats.js

@@ -12,19 +12,26 @@ export async function runVersionStats(options) {
     const output = options.output ?? defaultOutput;
     const runner = options.runner ?? createVersionProcessRunner();
     let installed;
+    let installedPullRequest;
     try {
         const manifest = JSON.parse(await readFile(resolve(options.packageRoot, "package.json"), "utf8"));
         installed = parseVersion(manifest.version, "installed package");
+        installedPullRequest = recordedPullRequest(manifest);
     }
     catch (error) {
         output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its installed version: ${message(error)}`)}\n`);
         return 1;
     }
     // Rationale: unlike Pi, stable builds also show the release channel head so users can see they are
-    // behind without starting a session. Only development builds show the preview channel.
+    // behind without starting a session. Only development builds show the preview channel, and only
+    // they carry the pull request a preview's manifest records; a missing record is silently omitted.
     const remote = await queryDistTags(runner, options.fetcher ?? defaultRegistryFetcher);
-    const develop = prerelease(installed) === null ? "" : `Develop: ${remote.develop ?? "unavailable"}\n`;
-    output.stdout(`Current: ${installed}\n${develop}Release: ${remote.release ?? "unavailable"}\n`);
+    const developmentBuild = prerelease(installed) !== null;
+    const headPullRequest = developmentBuild && remote.develop !== null ? await queryRecordedPullRequest(runner, remote.develop) : null;
+    const develop = developmentBuild
+        ? `Develop: ${remote.develop === null ? "unavailable" : withPullRequest(remote.develop, headPullRequest)}\n`
+        : "";
+    output.stdout(`Current: ${withPullRequest(installed, developmentBuild ? installedPullRequest : null)}\n${develop}Release: ${remote.release ?? "unavailable"}\n`);
     if (remote.error)
         output.stderr(`${PRODUCT_TEXT.diagnostic(`could not resolve npm dist-tags: ${remote.error}`)}\n`);
     return 0;
@@ -88,6 +95,34 @@ function parseDistTags(metadata, source) {
 function unavailable(error) {
     return { release: null, develop: null, error };
 }
+function withPullRequest(version, pullRequest) {
+    return pullRequest === null ? version : `${version} (#${pullRequest})`;
+}
+/** The pull request a manifest records under `publication.pullRequest`, when it is a positive integer. */
+function recordedPullRequest(manifest) {
+    if (typeof manifest !== "object" || manifest === null)
+        return null;
+    const publication = manifest.publication;
+    if (typeof publication !== "object" || publication === null)
+        return null;
+    const value = publication.pullRequest;
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : null;
+}
+/** The pull request the published head records, read through npm; any failure means no record. */
+async function queryRecordedPullRequest(runner, version) {
+    try {
+        const result = await runner("npm", ["view", `${PRODUCT_TEXT.packageName}@${version}`, "publication.pullRequest", "--json"]);
+        if (result.code !== 0 || result.stdout.trim().length === 0)
+            return null;
+        const parsed = JSON.parse(result.stdout);
+        // Compatibility: npm 12 wraps single-field `npm view --json` output in a one-element array.
+        const value = Array.isArray(parsed) && parsed.length === 1 ? parsed[0] : parsed;
+        return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
 const defaultRegistryFetcher = async (url) => await fetch(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
 function createVersionProcessRunner() {
     return async (command, arguments_) => await new Promise((resolvePromise, rejectPromise) => {

package/dist/composition/owned-settings.d.ts

@@ -0,0 +1,12 @@
+import type { AgentSettingsPort } from "../contracts/agent-engine/index.js";
+import { OwnedSettingsManager } from "../ui/settings/manager.js";
+export interface OwnedSettingsManagerFactoryOptions {
+    readonly profileId: string;
+    readonly hideTabSettings?: boolean;
+    readonly agent?: AgentSettingsPort | null;
+    readonly agentProvider?: () => AgentSettingsPort | null;
+}
+/** Builds the profile-global settings manager shared by the Agent and slim utility compositions. */
+export declare function createOwnedSettingsManager(options: OwnedSettingsManagerFactoryOptions): OwnedSettingsManager;
+/** Rereads the shared settings document whenever its stat changes; returns the stop. */
+export declare function watchSharedSettings(settings: Pick<OwnedSettingsManager, "file" | "refresh">): () => void;

package/dist/composition/owned-settings.js

@@ -0,0 +1,36 @@
+import { unwatchFile, watchFile } from "node:fs";
+import { resolveLaunchProfilePaths } from "../features/launch/profile-paths.js";
+import { resolveProductPaths } from "../foundation/lifecycle/paths.js";
+import { PRODUCT_IDENTITY } from "../product-identity.js";
+import { OwnedSettingsManager } from "../ui/settings/manager.js";
+/** Builds the profile-global settings manager shared by the Agent and slim utility compositions. */
+export function createOwnedSettingsManager(options) {
+    const profilePaths = resolveLaunchProfilePaths();
+    const productPaths = resolveProductPaths();
+    return new OwnedSettingsManager({
+        profileDir: profilePaths.agentProfile,
+        profileId: options.profileId,
+        namespace: PRODUCT_IDENTITY.commandName,
+        legacyConfigDir: productPaths.configDir,
+        ...(options.agent === undefined ? {} : { agent: options.agent }),
+        ...(options.agentProvider === undefined ? {} : { agentProvider: options.agentProvider }),
+        ...(options.hideTabSettings ? { hiddenOwnedSettingIds: ["tabsAutoName", "tabsPosition", "tabBarPlusMenu"] } : {}),
+        hiddenAgentSettingIds: ["fullscreenWheelScrollLines"],
+        agentSettingLabelOverrides: { fullscreenCopyOnSelect: "Copy on select" },
+    });
+}
+const SHARED_SETTINGS_POLL_MS = 250;
+/** Rereads the shared settings document whenever its stat changes; returns the stop. */
+export function watchSharedSettings(settings) {
+    const file = settings.file;
+    const listener = () => {
+        try {
+            settings.refresh();
+        }
+        catch {
+            // Compatibility: an unreadable peer write resolves on the next stat change.
+        }
+    };
+    watchFile(file, { interval: SHARED_SETTINGS_POLL_MS, persistent: false }, listener);
+    return () => unwatchFile(file, listener);
+}

package/dist/composition/owned-ui.d.ts

@@ -1,29 +1,16 @@
 import type { AvailableRelease, StartupReleaseCheckOptions } from "../foundation/release/latest-release.js";
 import type { NativeProcessIdentity } from "../foundation/lifecycle/model.js";
 import type { SessionSelection } from "../foundation/lifecycle/session-selection.js";
-import { type PiEngineHostOptions, type PiEngineSessionRequest } from "../integrations/pi/engine/host.js";
-import { type PiSessionPresenterBackend } from "../integrations/pi/session-presenters/index.js";
+import { type PiEngineHostOptions } from "../integrations/pi/engine/host.js";
 import type { PiProjectTrustPreflightPrompt } from "../integrations/pi/engine/project-trust-preflight.js";
 import type { PiSessionForkPrompt } from "../integrations/pi/engine/session-selection.js";
-import { OwnedSettingsManager } from "../ui/settings/manager.js";
+import type { OwnedSettingsManager } from "../ui/settings/manager.js";
 import type { OwnedUiApplicationPort, PresentationTerminalPort } from "../contracts/presentation/index.js";
-import type { AgentSettingsPort } from "../contracts/agent-engine/index.js";
-import type { OwnedUiPromptSuggestionGeneratorPort, UiAccentColor } from "../contracts/owned-ui/index.js";
 import type { ReleaseNoteCatalog } from "../features/owned-ui/release-notes.js";
-/**
- * The session backend composition wires: the owned-UI port, the prompt-suggestion generator, and
- * the agent settings port. `settingsPort` stays outside the owned-UI contract because its type
- * belongs to the agent-engine contracts, which the owned-UI contract may not import.
- */
-export interface ComposedSessionBackend extends PiSessionPresenterBackend, OwnedUiPromptSuggestionGeneratorPort {
-    settingsPort(): AgentSettingsPort | null;
-}
-/** The process-level engine host as composition drives it: sessions, the live accent, and disposal. */
-export interface ComposedEngineHost {
-    create(request: PiEngineSessionRequest): Promise<ComposedSessionBackend>;
-    setAccentColor(color: UiAccentColor): void;
-    dispose(): Promise<void>;
-}
+import type { TabBridgeClient } from "../foundation/resident-tabs/bridge-client.js";
+import type { ComposedEngineHost } from "./session-backend.js";
+export type { ComposedEngineHost, ComposedSessionBackend } from "./session-backend.js";
+export { bindResidentTabBridge, correlateResidentTabSubmission } from "./resident-tab-bridge.js";
 export interface OwnedUiCompositionOptions {
     readonly cwd?: string;
     readonly terminal?: PresentationTerminalPort;
@@ -33,15 +20,11 @@ export interface OwnedUiCompositionOptions {
     readonly sessionPath?: string;
     readonly sessionSelection?: SessionSelection;
     readonly sessionForkPrompt?: PiSessionForkPrompt;
-    /**
-     * A1 profile whose settings this session reads and writes. Omitted keeps the
-     * session settings-free, which is what the pinned comparison paths use.
-     */
+    /** A1 settings profile; comparison paths omit it. */
     readonly profileId?: string;
-    /**
-     * Whether A1's product-specific surfaces are reachable. Comparison profiles
-     * use the same composition with those surfaces withheld.
-     */
+    /** Hide resident-only tab controls for the explicit direct single-agent launch. */
+    readonly hideTabSettings?: boolean;
+    /** `off` withholds A1-specific surfaces from comparison profiles. */
     readonly ownedSurfaces?: "on" | "off";
     readonly projectTrustPrompt?: PiProjectTrustPreflightPrompt;
     /** Explicit local diagnostic destination; ignored by comparison/settings-free compositions. */
@@ -50,16 +33,32 @@ export interface OwnedUiCompositionOptions {
     readonly clipboardDiagnosticsPath?: string;
     /** Deterministic release-note seams for composition tests. */
     readonly packageVersion?: string;
+    readonly notificationVersion?: string | undefined;
     readonly releaseNotes?: ReleaseNoteCatalog;
     /** Startup release-availability seam; defaults to the throttled registry check. */
     readonly checkForNewerRelease?: (options: StartupReleaseCheckOptions) => Promise<AvailableRelease | null>;
-    /** Exact native process inspection injected by the shipped entry; absent SDK seams do not publish claims. */
     readonly inspectProcess?: (pid: number) => Promise<NativeProcessIdentity | null>;
+    readonly tab?: {
+        readonly bridge: TabBridgeClient;
+        readonly dataDir: string;
+        readonly incarnation: number;
+    };
+    readonly residentFallbackNotice?: string;
 }
 export interface OwnedUiComposition {
     readonly application: OwnedUiApplicationPort;
     /** Present when a profile was supplied, so the caller can resolve settings before start. */
     readonly settings: OwnedSettingsManager | null;
 }
+export declare function residentStartupPresentation(resident: boolean, fallbackNotice?: string): {
+    readonly startup?: {
+        readonly quiet?: boolean;
+        readonly notices?: readonly [{
+            readonly kind: "warning";
+            readonly message: string;
+        }];
+    };
+};
 export declare function composeOwnedUiApplication(options?: OwnedUiCompositionOptions): Promise<OwnedUiApplicationPort>;
 export declare function composeOwnedUi(options?: OwnedUiCompositionOptions): Promise<OwnedUiComposition>;
+export { watchSharedSettings } from "./owned-settings.js";