@ai-agent-forge/agent-forge 0.85.0

package/dist/cli/serve.js

@@ -0,0 +1,124 @@
+/**
+ * CLI remote server entry (E3 tail): serves the coding-agent session runtime
+ * behind the programmatic `startCodingAgentRemoteServer` entry.
+ *
+ * The default listener is the ws gateway: it negotiates WebSocket protocol
+ * connections and serves the gateway HTTP surface (healthz plus the
+ * token-protected artifact stat/read routes from B-H2b). Read tokens are
+ * issued through the protocol path (`artifact_token_issue`) against the same
+ * attach/lease gate as `artifact_read`; the direct HTTP face has no
+ * `authorize` hook — the token is a single-use, short-lived projection of that
+ * access.
+ *
+ * Experimental, single-user local trust only: the default listener binds
+ * loopback, there is no authentication, and the session source accepts
+ * whatever cwd clients submit, so any local process can drive the agent in an
+ * arbitrary directory. An opt-in workspace boundary is available via
+ * `--serve-workspace-root` (forwarded here as `workspaceRoots`).
+ */
+import { join } from "node:path";
+import { createWsServerListener } from "@agent-forge/server";
+import { getAgentDir, getSessionsDir } from "../config.js";
+import { createDurableService, createFileDurableStoreBackend } from "../durable/durable-service.js";
+import { readOrCreateWriterId, startCodingAgentRemoteServer, } from "../remote/server-entry.js";
+/**
+ * Server-level ops log relative to the agent dir. Parallels the default
+ * session journal (`<agentDir>/remote-server-journal.jsonl`): one shared
+ * server domain, never the process cwd. The backend's lock acquisition
+ * creates parent directories, so no mkdir is needed before the first persist.
+ */
+const DEFAULT_DURABLE_LOG_RELATIVE_PATH = join("durable", "remote-server-ops.jsonl");
+/** Detects the transport-level "address already in use" failure. */
+function isAddrInUse(error) {
+    return typeof error === "object" && error !== null && error.code === "EADDRINUSE";
+}
+/** Starts the remote server on the given port and keeps the process alive until SIGINT/SIGTERM. */
+export async function runServeMode(port, options) {
+    // Assigned once `startServer` resolves; until then the HTTP handler falls
+    // through to the listener's default paths (no requests arrive before the
+    // address is announced).
+    let handle;
+    const createListener = options?.createListener ??
+        (() => createWsServerListener({
+            port,
+            // Token-protected artifact stat/read over the gateway HTTP surface
+            // (B-H2b): routes live behind the server boundary so the token store
+            // and the artifact data plane stay single-source.
+            httpRequestHandler: (request, response) => handle?.server.handleArtifactHttpRequest(request, response) ?? false,
+            // Listener-lifetime socket errors (post-startup) otherwise disappear:
+            // route them to the same one-line stderr sink as server errors.
+            onError: (error) => {
+                console.error(`remote-server error: ${error.message}`);
+            },
+        }));
+    const startServer = options?.startServer ?? startCodingAgentRemoteServer;
+    const workspaceRoots = options?.workspaceRoots;
+    const sessionDir = options?.sessionDir;
+    // Default durable service persists operations and artifacts across
+    // restarts; without it those surfaces answer durable_unavailable.
+    const durable = options?.durable ??
+        createDurableService({
+            backend: createFileDurableStoreBackend({
+                path: join(getAgentDir(), DEFAULT_DURABLE_LOG_RELATIVE_PATH),
+            }),
+        });
+    // Host-level writer identity: one writer serves the whole process — the
+    // server assembly claims the lease with it (claim/recover unchanged), and
+    // sessions persist their agent task terminal records with it
+    // (agent-result-replay-v1). A host-supplied durable rides the same writer.
+    // The id is stable across restarts (see readOrCreateWriterId).
+    const writerId = readOrCreateWriterId(getAgentDir());
+    try {
+        handle = await startServer({
+            sessionSourceOptions: {
+                sessionsDir: sessionDir ?? getSessionsDir(),
+                cwd: process.cwd(),
+                agentDir: getAgentDir(),
+                ...(workspaceRoots === undefined || workspaceRoots.length === 0 ? {} : { workspaceRoots }),
+                agentTaskResults: { store: durable, writerId },
+                // 承载退役切片 2：serve 会话经自动池化获得委派载体（与交互模式同纪律）。
+                subagentPoolFromSelfInvocation: true,
+                // D-067 第一期 S3：serve 会话进程日志接缝——补上此前 no-op 的缺口。
+                ...(options?.hostLogger === undefined ? {} : { hostLogger: options.hostLogger }),
+            },
+            listeners: [createListener()],
+            // Without this sink the server swallows every internal error; keep
+            // the output one-line so console noise stays greppable.
+            onError: (error) => {
+                console.error(`remote-server error: ${error.message}`);
+            },
+            durable,
+            writerId,
+        });
+    }
+    catch (error) {
+        // Startup failures otherwise bubble to top level as a raw stack trace;
+        // the dominant day-to-day case (port already taken) deserves one line.
+        if (isAddrInUse(error)) {
+            console.error(`Port ${port} is already in use`);
+            process.exit(1);
+        }
+        throw error;
+    }
+    let closing = false;
+    const shutdown = () => {
+        if (closing)
+            return;
+        closing = true;
+        void handle
+            .close()
+            .then(() => {
+            // Explicit exit so listener or signal handles cannot keep the
+            // process alive after a successful shutdown.
+            process.exit(0);
+        })
+            .catch((error) => {
+            console.error(`Remote server shutdown failed: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        });
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    console.log(`Remote server listening on ${handle.addresses.join(", ")}`);
+}
+//# sourceMappingURL=serve.js.map

package/dist/cli/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../src/cli/serve.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * CLI remote server entry (E3 tail): serves the coding-agent session runtime\n * behind the programmatic `startCodingAgentRemoteServer` entry.\n *\n * The default listener is the ws gateway: it negotiates WebSocket protocol\n * connections and serves the gateway HTTP surface (healthz plus the\n * token-protected artifact stat/read routes from B-H2b). Read tokens are\n * issued through the protocol path (`artifact_token_issue`) against the same\n * attach/lease gate as `artifact_read`; the direct HTTP face has no\n * `authorize` hook — the token is a single-use, short-lived projection of that\n * access.\n *\n * Experimental, single-user local trust only: the default listener binds\n * loopback, there is no authentication, and the session source accepts\n * whatever cwd clients submit, so any local process can drive the agent in an\n * arbitrary directory. An opt-in workspace boundary is available via\n * `--serve-workspace-root` (forwarded here as `workspaceRoots`).\n */\nimport { join } from \"node:path\";\nimport { createWsServerListener, type PiServerListener } from \"@agent-forge/server\";\nimport { getAgentDir, getSessionsDir } from \"../config.ts\";\nimport type { HostLogger } from \"../core/logger.ts\";\nimport { createDurableService, createFileDurableStoreBackend } from \"../durable/durable-service.ts\";\nimport type { CodingAgentServerAssemblyOptions } from \"../remote/server-assembly.ts\";\nimport {\n\ttype CodingAgentRemoteServerHandle,\n\treadOrCreateWriterId,\n\ttype StartCodingAgentRemoteServerOptions,\n\tstartCodingAgentRemoteServer,\n} from \"../remote/server-entry.ts\";\n\n/**\n * Server-level ops log relative to the agent dir. Parallels the default\n * session journal (`<agentDir>/remote-server-journal.jsonl`): one shared\n * server domain, never the process cwd. The backend's lock acquisition\n * creates parent directories, so no mkdir is needed before the first persist.\n */\nconst DEFAULT_DURABLE_LOG_RELATIVE_PATH = join(\"durable\", \"remote-server-ops.jsonl\");\n\n/** Overridable collaborators for `runServeMode`, injected in tests. */\nexport interface RunServeModeOptions {\n\t/** Defaults to a loopback ws gateway listener on `port` with the artifact HTTP read routes. */\n\treadonly createListener?: () => PiServerListener;\n\t/** Defaults to `startCodingAgentRemoteServer`. */\n\treadonly startServer?: (options: StartCodingAgentRemoteServerOptions) => Promise<CodingAgentRemoteServerHandle>;\n\t/**\n\t * Opt-in workspace boundary forwarded to the session source: remote creates\n\t * are then restricted to cwds inside one of these roots. Omitted (or empty)\n\t * keeps the unrestricted local-trust behavior.\n\t */\n\treadonly workspaceRoots?: readonly string[];\n\t/**\n\t * Explicit session directory forwarded to the session source. Serve mode\n\t * never reads the settings/env sessionDir chain, so only an explicit CLI\n\t * `--session-dir` value arrives here; without it `getSessionsDir()` is used.\n\t */\n\treadonly sessionDir?: string;\n\t/**\n\t * Explicit durable service override. Omitted (undefined) constructs a default\n\t * file-backed durable service under the agent dir, so serve mode persists\n\t * operations and artifacts across restarts. Hosts that need a custom backend\n\t * or a shared service pass it here.\n\t */\n\treadonly durable?: CodingAgentServerAssemblyOptions[\"durable\"];\n\t/**\n\t * Host-process logger forwarded into every session the server builds\n\t * (D-067 phase 1 seam). The CLI passes the process file logger; omitted\n\t * keeps the SDK's explicit no-op contract.\n\t */\n\treadonly hostLogger?: HostLogger;\n}\n\n/** Detects the transport-level \"address already in use\" failure. */\nfunction isAddrInUse(error: unknown): boolean {\n\treturn typeof error === \"object\" && error !== null && (error as { readonly code?: unknown }).code === \"EADDRINUSE\";\n}\n\n/** Starts the remote server on the given port and keeps the process alive until SIGINT/SIGTERM. */\nexport async function runServeMode(port: number, options?: RunServeModeOptions): Promise<void> {\n\t// Assigned once `startServer` resolves; until then the HTTP handler falls\n\t// through to the listener's default paths (no requests arrive before the\n\t// address is announced).\n\tlet handle: CodingAgentRemoteServerHandle | undefined;\n\tconst createListener =\n\t\toptions?.createListener ??\n\t\t((): PiServerListener =>\n\t\t\tcreateWsServerListener({\n\t\t\t\tport,\n\t\t\t\t// Token-protected artifact stat/read over the gateway HTTP surface\n\t\t\t\t// (B-H2b): routes live behind the server boundary so the token store\n\t\t\t\t// and the artifact data plane stay single-source.\n\t\t\t\thttpRequestHandler: (request, response) =>\n\t\t\t\t\thandle?.server.handleArtifactHttpRequest(request, response) ?? false,\n\t\t\t\t// Listener-lifetime socket errors (post-startup) otherwise disappear:\n\t\t\t\t// route them to the same one-line stderr sink as server errors.\n\t\t\t\tonError: (error: Error): void => {\n\t\t\t\t\tconsole.error(`remote-server error: ${error.message}`);\n\t\t\t\t},\n\t\t\t}));\n\tconst startServer = options?.startServer ?? startCodingAgentRemoteServer;\n\tconst workspaceRoots = options?.workspaceRoots;\n\tconst sessionDir = options?.sessionDir;\n\t// Default durable service persists operations and artifacts across\n\t// restarts; without it those surfaces answer durable_unavailable.\n\tconst durable =\n\t\toptions?.durable ??\n\t\tcreateDurableService({\n\t\t\tbackend: createFileDurableStoreBackend({\n\t\t\t\tpath: join(getAgentDir(), DEFAULT_DURABLE_LOG_RELATIVE_PATH),\n\t\t\t}),\n\t\t});\n\t// Host-level writer identity: one writer serves the whole process — the\n\t// server assembly claims the lease with it (claim/recover unchanged), and\n\t// sessions persist their agent task terminal records with it\n\t// (agent-result-replay-v1). A host-supplied durable rides the same writer.\n\t// The id is stable across restarts (see readOrCreateWriterId).\n\tconst writerId = readOrCreateWriterId(getAgentDir());\n\ttry {\n\t\thandle = await startServer({\n\t\t\tsessionSourceOptions: {\n\t\t\t\tsessionsDir: sessionDir ?? getSessionsDir(),\n\t\t\t\tcwd: process.cwd(),\n\t\t\t\tagentDir: getAgentDir(),\n\t\t\t\t...(workspaceRoots === undefined || workspaceRoots.length === 0 ? {} : { workspaceRoots }),\n\t\t\t\tagentTaskResults: { store: durable, writerId },\n\t\t\t\t// 承载退役切片 2：serve 会话经自动池化获得委派载体（与交互模式同纪律）。\n\t\t\t\tsubagentPoolFromSelfInvocation: true,\n\t\t\t\t// D-067 第一期 S3：serve 会话进程日志接缝——补上此前 no-op 的缺口。\n\t\t\t\t...(options?.hostLogger === undefined ? {} : { hostLogger: options.hostLogger }),\n\t\t\t},\n\t\t\tlisteners: [createListener()],\n\t\t\t// Without this sink the server swallows every internal error; keep\n\t\t\t// the output one-line so console noise stays greppable.\n\t\t\tonError: (error: Error): void => {\n\t\t\t\tconsole.error(`remote-server error: ${error.message}`);\n\t\t\t},\n\t\t\tdurable,\n\t\t\twriterId,\n\t\t});\n\t} catch (error) {\n\t\t// Startup failures otherwise bubble to top level as a raw stack trace;\n\t\t// the dominant day-to-day case (port already taken) deserves one line.\n\t\tif (isAddrInUse(error)) {\n\t\t\tconsole.error(`Port ${port} is already in use`);\n\t\t\tprocess.exit(1);\n\t\t}\n\t\tthrow error;\n\t}\n\n\tlet closing = false;\n\tconst shutdown = (): void => {\n\t\tif (closing) return;\n\t\tclosing = true;\n\t\tvoid handle\n\t\t\t.close()\n\t\t\t.then(() => {\n\t\t\t\t// Explicit exit so listener or signal handles cannot keep the\n\t\t\t\t// process alive after a successful shutdown.\n\t\t\t\tprocess.exit(0);\n\t\t\t})\n\t\t\t.catch((error: unknown) => {\n\t\t\t\tconsole.error(`Remote server shutdown failed: ${error instanceof Error ? error.message : String(error)}`);\n\t\t\t\tprocess.exit(1);\n\t\t\t});\n\t};\n\tprocess.on(\"SIGINT\", shutdown);\n\tprocess.on(\"SIGTERM\", shutdown);\n\n\tconsole.log(`Remote server listening on ${handle.addresses.join(\", \")}`);\n}\n"]}

package/dist/cli/session-picker.d.ts

@@ -0,0 +1,30 @@
+/**
+ * TUI session selector for --resume flag
+ */
+import { type SessionInfo, type SessionListProgress } from "../core/session-manager.ts";
+import type { SettingsManager } from "../core/settings-manager.ts";
+type SessionsLoader = (onProgress?: SessionListProgress) => Promise<SessionInfo[]>;
+/** Result from resolving a session argument */
+export type ResolvedSession = {
+    type: "path";
+    path: string;
+} | {
+    type: "local";
+    path: string;
+} | {
+    type: "global";
+    path: string;
+    cwd: string;
+} | {
+    type: "not_found";
+    arg: string;
+};
+/**
+ * Resolve a session argument to a file path.
+ * If it looks like a path, use as-is. Otherwise try to match as session ID prefix.
+ */
+export declare function resolveSessionPath(sessionArg: string, cwd: string, sessionDir?: string): Promise<ResolvedSession>;
+/** Show TUI session selector and return selected session path or null if cancelled */
+export declare function selectSession(currentSessionsLoader: SessionsLoader, allSessionsLoader: SessionsLoader, settingsManager: SettingsManager): Promise<string | null>;
+export {};
+//# sourceMappingURL=session-picker.d.ts.map

package/dist/cli/session-picker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-picker.d.ts","sourceRoot":"","sources":["../../src/cli/session-picker.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,mBAAmB,EAAkB,MAAM,4BAA4B,CAAC;AACxG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAKnE,KAAK,cAAc,GAAG,CAAC,UAAU,CAAC,EAAE,mBAAmB,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;AAEnF,+CAA+C;AAC/C,MAAM,MAAM,eAAe,GACxB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC;;;GAGG;AACH,wBAAsB,kBAAkB,CACvC,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,UAAU,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CA0B1B;AAED,sFAAsF;AACtF,wBAAsB,aAAa,CAClC,qBAAqB,EAAE,cAAc,EACrC,iBAAiB,EAAE,cAAc,EACjC,eAAe,EAAE,eAAe,GAC9B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoCxB","sourcesContent":["/**\n * TUI session selector for --resume flag\n */\n\nimport { setKeybindings } from \"@agent-forge/tui\";\nimport { KeybindingsManager } from \"../core/keybindings.ts\";\nimport { type SessionInfo, type SessionListProgress, SessionManager } from \"../core/session-manager.ts\";\nimport type { SettingsManager } from \"../core/settings-manager.ts\";\nimport { SessionSelectorComponent } from \"../modes/interactive/components/session-selector.ts\";\nimport { resolvePath } from \"../utils/paths.ts\";\nimport { createStartupTui, startStartupTui } from \"./startup-ui.ts\";\n\ntype SessionsLoader = (onProgress?: SessionListProgress) => Promise<SessionInfo[]>;\n\n/** Result from resolving a session argument */\nexport type ResolvedSession =\n\t| { type: \"path\"; path: string } // Direct file path\n\t| { type: \"local\"; path: string } // Found in current project\n\t| { type: \"global\"; path: string; cwd: string } // Found in different project\n\t| { type: \"not_found\"; arg: string }; // Not found anywhere\n\n/**\n * Resolve a session argument to a file path.\n * If it looks like a path, use as-is. Otherwise try to match as session ID prefix.\n */\nexport async function resolveSessionPath(\n\tsessionArg: string,\n\tcwd: string,\n\tsessionDir?: string,\n): Promise<ResolvedSession> {\n\t// If it looks like a file path, resolve it before handing it to the session manager.\n\tif (sessionArg.includes(\"/\") || sessionArg.includes(\"\\\\\") || sessionArg.endsWith(\".jsonl\")) {\n\t\treturn { type: \"path\", path: resolvePath(sessionArg, cwd) };\n\t}\n\n\t// Try to match as session ID in current project first\n\tconst localSessions = await SessionManager.list(cwd, sessionDir);\n\tconst localMatch =\n\t\tlocalSessions.find((s) => s.id === sessionArg) ?? localSessions.find((s) => s.id.startsWith(sessionArg));\n\n\tif (localMatch) {\n\t\treturn { type: \"local\", path: localMatch.path };\n\t}\n\n\t// Try global search across all projects\n\tconst allSessions = await SessionManager.listAll(sessionDir);\n\tconst globalMatch =\n\t\tallSessions.find((s) => s.id === sessionArg) ?? allSessions.find((s) => s.id.startsWith(sessionArg));\n\n\tif (globalMatch) {\n\t\treturn { type: \"global\", path: globalMatch.path, cwd: globalMatch.cwd };\n\t}\n\n\t// Not found anywhere\n\treturn { type: \"not_found\", arg: sessionArg };\n}\n\n/** Show TUI session selector and return selected session path or null if cancelled */\nexport async function selectSession(\n\tcurrentSessionsLoader: SessionsLoader,\n\tallSessionsLoader: SessionsLoader,\n\tsettingsManager: SettingsManager,\n): Promise<string | null> {\n\tconst ui = await createStartupTui(settingsManager);\n\treturn new Promise((resolve) => {\n\t\tconst keybindings = KeybindingsManager.create();\n\t\tsetKeybindings(keybindings);\n\t\tlet resolved = false;\n\n\t\tconst selector = new SessionSelectorComponent(\n\t\t\tcurrentSessionsLoader,\n\t\t\tallSessionsLoader,\n\t\t\t(path: string) => {\n\t\t\t\tif (!resolved) {\n\t\t\t\t\tresolved = true;\n\t\t\t\t\tui.stop();\n\t\t\t\t\tresolve(path);\n\t\t\t\t}\n\t\t\t},\n\t\t\t() => {\n\t\t\t\tif (!resolved) {\n\t\t\t\t\tresolved = true;\n\t\t\t\t\tui.stop();\n\t\t\t\t\tresolve(null);\n\t\t\t\t}\n\t\t\t},\n\t\t\t() => {\n\t\t\t\tui.stop();\n\t\t\t\tprocess.exit(0);\n\t\t\t},\n\t\t\t() => ui.requestRender(),\n\t\t\t{ showRenameHint: false, keybindings },\n\t\t);\n\n\t\tui.addChild(selector);\n\t\tui.setFocus(selector.getSessionList());\n\t\tstartStartupTui(ui, settingsManager);\n\t});\n}\n"]}

package/dist/cli/session-picker.js

@@ -0,0 +1,62 @@
+/**
+ * TUI session selector for --resume flag
+ */
+import { setKeybindings } from "@agent-forge/tui";
+import { KeybindingsManager } from "../core/keybindings.js";
+import { SessionManager } from "../core/session-manager.js";
+import { SessionSelectorComponent } from "../modes/interactive/components/session-selector.js";
+import { resolvePath } from "../utils/paths.js";
+import { createStartupTui, startStartupTui } from "./startup-ui.js";
+/**
+ * Resolve a session argument to a file path.
+ * If it looks like a path, use as-is. Otherwise try to match as session ID prefix.
+ */
+export async function resolveSessionPath(sessionArg, cwd, sessionDir) {
+    // If it looks like a file path, resolve it before handing it to the session manager.
+    if (sessionArg.includes("/") || sessionArg.includes("\\") || sessionArg.endsWith(".jsonl")) {
+        return { type: "path", path: resolvePath(sessionArg, cwd) };
+    }
+    // Try to match as session ID in current project first
+    const localSessions = await SessionManager.list(cwd, sessionDir);
+    const localMatch = localSessions.find((s) => s.id === sessionArg) ?? localSessions.find((s) => s.id.startsWith(sessionArg));
+    if (localMatch) {
+        return { type: "local", path: localMatch.path };
+    }
+    // Try global search across all projects
+    const allSessions = await SessionManager.listAll(sessionDir);
+    const globalMatch = allSessions.find((s) => s.id === sessionArg) ?? allSessions.find((s) => s.id.startsWith(sessionArg));
+    if (globalMatch) {
+        return { type: "global", path: globalMatch.path, cwd: globalMatch.cwd };
+    }
+    // Not found anywhere
+    return { type: "not_found", arg: sessionArg };
+}
+/** Show TUI session selector and return selected session path or null if cancelled */
+export async function selectSession(currentSessionsLoader, allSessionsLoader, settingsManager) {
+    const ui = await createStartupTui(settingsManager);
+    return new Promise((resolve) => {
+        const keybindings = KeybindingsManager.create();
+        setKeybindings(keybindings);
+        let resolved = false;
+        const selector = new SessionSelectorComponent(currentSessionsLoader, allSessionsLoader, (path) => {
+            if (!resolved) {
+                resolved = true;
+                ui.stop();
+                resolve(path);
+            }
+        }, () => {
+            if (!resolved) {
+                resolved = true;
+                ui.stop();
+                resolve(null);
+            }
+        }, () => {
+            ui.stop();
+            process.exit(0);
+        }, () => ui.requestRender(), { showRenameHint: false, keybindings });
+        ui.addChild(selector);
+        ui.setFocus(selector.getSessionList());
+        startStartupTui(ui, settingsManager);
+    });
+}
+//# sourceMappingURL=session-picker.js.map

package/dist/cli/session-picker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-picker.js","sourceRoot":"","sources":["../../src/cli/session-picker.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * TUI session selector for --resume flag\n */\n\nimport { setKeybindings } from \"@agent-forge/tui\";\nimport { KeybindingsManager } from \"../core/keybindings.ts\";\nimport { type SessionInfo, type SessionListProgress, SessionManager } from \"../core/session-manager.ts\";\nimport type { SettingsManager } from \"../core/settings-manager.ts\";\nimport { SessionSelectorComponent } from \"../modes/interactive/components/session-selector.ts\";\nimport { resolvePath } from \"../utils/paths.ts\";\nimport { createStartupTui, startStartupTui } from \"./startup-ui.ts\";\n\ntype SessionsLoader = (onProgress?: SessionListProgress) => Promise<SessionInfo[]>;\n\n/** Result from resolving a session argument */\nexport type ResolvedSession =\n\t| { type: \"path\"; path: string } // Direct file path\n\t| { type: \"local\"; path: string } // Found in current project\n\t| { type: \"global\"; path: string; cwd: string } // Found in different project\n\t| { type: \"not_found\"; arg: string }; // Not found anywhere\n\n/**\n * Resolve a session argument to a file path.\n * If it looks like a path, use as-is. Otherwise try to match as session ID prefix.\n */\nexport async function resolveSessionPath(\n\tsessionArg: string,\n\tcwd: string,\n\tsessionDir?: string,\n): Promise<ResolvedSession> {\n\t// If it looks like a file path, resolve it before handing it to the session manager.\n\tif (sessionArg.includes(\"/\") || sessionArg.includes(\"\\\\\") || sessionArg.endsWith(\".jsonl\")) {\n\t\treturn { type: \"path\", path: resolvePath(sessionArg, cwd) };\n\t}\n\n\t// Try to match as session ID in current project first\n\tconst localSessions = await SessionManager.list(cwd, sessionDir);\n\tconst localMatch =\n\t\tlocalSessions.find((s) => s.id === sessionArg) ?? localSessions.find((s) => s.id.startsWith(sessionArg));\n\n\tif (localMatch) {\n\t\treturn { type: \"local\", path: localMatch.path };\n\t}\n\n\t// Try global search across all projects\n\tconst allSessions = await SessionManager.listAll(sessionDir);\n\tconst globalMatch =\n\t\tallSessions.find((s) => s.id === sessionArg) ?? allSessions.find((s) => s.id.startsWith(sessionArg));\n\n\tif (globalMatch) {\n\t\treturn { type: \"global\", path: globalMatch.path, cwd: globalMatch.cwd };\n\t}\n\n\t// Not found anywhere\n\treturn { type: \"not_found\", arg: sessionArg };\n}\n\n/** Show TUI session selector and return selected session path or null if cancelled */\nexport async function selectSession(\n\tcurrentSessionsLoader: SessionsLoader,\n\tallSessionsLoader: SessionsLoader,\n\tsettingsManager: SettingsManager,\n): Promise<string | null> {\n\tconst ui = await createStartupTui(settingsManager);\n\treturn new Promise((resolve) => {\n\t\tconst keybindings = KeybindingsManager.create();\n\t\tsetKeybindings(keybindings);\n\t\tlet resolved = false;\n\n\t\tconst selector = new SessionSelectorComponent(\n\t\t\tcurrentSessionsLoader,\n\t\t\tallSessionsLoader,\n\t\t\t(path: string) => {\n\t\t\t\tif (!resolved) {\n\t\t\t\t\tresolved = true;\n\t\t\t\t\tui.stop();\n\t\t\t\t\tresolve(path);\n\t\t\t\t}\n\t\t\t},\n\t\t\t() => {\n\t\t\t\tif (!resolved) {\n\t\t\t\t\tresolved = true;\n\t\t\t\t\tui.stop();\n\t\t\t\t\tresolve(null);\n\t\t\t\t}\n\t\t\t},\n\t\t\t() => {\n\t\t\t\tui.stop();\n\t\t\t\tprocess.exit(0);\n\t\t\t},\n\t\t\t() => ui.requestRender(),\n\t\t\t{ showRenameHint: false, keybindings },\n\t\t);\n\n\t\tui.addChild(selector);\n\t\tui.setFocus(selector.getSessionList());\n\t\tstartStartupTui(ui, settingsManager);\n\t});\n}\n"]}

package/dist/cli/startup-ui.d.ts

@@ -0,0 +1,20 @@
+import { type TUI } from "@agent-forge/tui";
+import { SettingsManager } from "../core/settings-manager.ts";
+export declare function createStartupTui(settingsManager: SettingsManager): Promise<TUI>;
+export declare function startStartupTui(ui: TUI, settingsManager: SettingsManager): void;
+/**
+ * First-time setup runs when all of these hold:
+ * - this is the official Agent Forge distribution (not a fork/rebrand)
+ * - experimental features are enabled (AGENT_FORGE_EXPERIMENTAL=1)
+ * - the default agent directory is used (no custom agent dir override)
+ * - setup was not completed before (settings.json does not exist)
+ */
+export declare function shouldRunFirstTimeSetup(settingsPath?: string): boolean;
+export declare function showStartupSelector<T>(settingsManager: SettingsManager, title: string, options: Array<{
+    label: string;
+    value: T;
+}>): Promise<T | undefined>;
+/** Show the first-time setup dialog and persist the result */
+export declare function showFirstTimeSetup(settingsManager: SettingsManager): Promise<void>;
+export declare function showStartupInput(settingsManager: SettingsManager, title: string, placeholder?: string): Promise<string | undefined>;
+//# sourceMappingURL=startup-ui.d.ts.map

package/dist/cli/startup-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-ui.d.ts","sourceRoot":"","sources":["../../src/cli/startup-ui.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2D,KAAK,GAAG,EAAiB,MAAM,kBAAkB,CAAC;AAMpH,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAsE9D,wBAAsB,gBAAgB,CAAC,eAAe,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,CASrF;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,GAAG,EAAE,eAAe,EAAE,eAAe,GAAG,IAAI,CAG/E;AAkBD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,GAAE,MAA0B,GAAG,OAAO,CAiBzF;AAED,wBAAsB,mBAAmB,CAAC,CAAC,EAC1C,eAAe,EAAE,eAAe,EAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC,GACzC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAyBxB;AAED,8DAA8D;AAC9D,wBAAsB,kBAAkB,CAAC,eAAe,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCxF;AAED,wBAAsB,gBAAgB,CACrC,eAAe,EAAE,eAAe,EAChC,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA4B7B","sourcesContent":["import { ProcessTerminal, setCapabilityOverrides, setKeybindings, type TUI, TuiMainScreen } from \"@agent-forge/tui\";\nimport { existsSync } from \"fs\";\nimport { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR, getAgentDir, getSettingsPath, PACKAGE_NAME } from \"../config.ts\";\nimport { areExperimentalFeaturesEnabled } from \"../core/experimental.ts\";\nimport { KeybindingsManager } from \"../core/keybindings.ts\";\nimport { DefaultPackageManager, type ResolvedResource } from \"../core/package-manager.ts\";\nimport { SettingsManager } from \"../core/settings-manager.ts\";\nimport { DialogInputComponent } from \"../modes/interactive/components/dialog-input.ts\";\nimport { DialogSelectorComponent } from \"../modes/interactive/components/dialog-selector.ts\";\nimport {\n\tFirstTimeSetupComponent,\n\ttype FirstTimeSetupResult,\n} from \"../modes/interactive/components/first-time-setup.ts\";\nimport {\n\tdetectTerminalBackgroundFromEnv,\n\tdetectTerminalThemeForAuto,\n\tinitTheme,\n\tloadThemeFromPath,\n\tparseAutoThemeSetting,\n\tresolveThemeSetting,\n\tsetRegisteredThemes,\n\tsetTheme,\n\ttype Theme,\n} from \"../modes/interactive/theme/theme.ts\";\n\nconst OFFICIAL_PACKAGE_NAME = \"@ai-agent-forge/agent-forge\";\nconst OFFICIAL_APP_NAME = \"agent-forge\";\nconst OFFICIAL_CONFIG_DIR_NAME = \".agent-forge\";\n\ninterface DistributionMetadata {\n\tpackageName: string;\n\tappName: string;\n\tconfigDirName: string;\n}\n\nfunction isOfficialDistribution({ packageName, appName, configDirName }: DistributionMetadata): boolean {\n\treturn (\n\t\tpackageName === OFFICIAL_PACKAGE_NAME &&\n\t\tappName === OFFICIAL_APP_NAME &&\n\t\tconfigDirName === OFFICIAL_CONFIG_DIR_NAME\n\t);\n}\n\nfunction loadThemes(resources: ResolvedResource[]): Theme[] {\n\tconst themes: Theme[] = [];\n\tconst seen = new Set<string>();\n\tfor (const resource of resources) {\n\t\tif (!resource.enabled) continue;\n\t\ttry {\n\t\t\tconst loadedTheme = loadThemeFromPath(resource.path);\n\t\t\tif (loadedTheme.name) {\n\t\t\t\tif (seen.has(loadedTheme.name)) continue;\n\t\t\t\tseen.add(loadedTheme.name);\n\t\t\t}\n\t\t\tthemes.push(loadedTheme);\n\t\t} catch {\n\t\t\t// Startup prompts should not fail because a theme is broken. The normal\n\t\t\t// resource loader reports theme diagnostics later in startup.\n\t\t}\n\t}\n\treturn themes;\n}\n\nasync function loadStartupThemes(settingsManager: SettingsManager): Promise<Theme[]> {\n\tconst globalSettingsManager = SettingsManager.inMemory(settingsManager.getGlobalSettings(), {\n\t\tprojectTrusted: false,\n\t});\n\tconst packageManager = new DefaultPackageManager({\n\t\tcwd: process.cwd(),\n\t\tagentDir: getAgentDir(),\n\t\tsettingsManager: globalSettingsManager,\n\t});\n\tconst resolvedPaths = await packageManager.resolve(async () => \"skip\");\n\treturn loadThemes(resolvedPaths.themes);\n}\n\nexport async function createStartupTui(settingsManager: SettingsManager): Promise<TUI> {\n\tsetCapabilityOverrides(settingsManager.getTerminalCapabilityOverrides());\n\tsetRegisteredThemes(await loadStartupThemes(settingsManager));\n\tconst terminalTheme = detectTerminalBackgroundFromEnv().theme;\n\tinitTheme(resolveThemeSetting(settingsManager.getThemeSetting(), terminalTheme) ?? terminalTheme);\n\tsetKeybindings(KeybindingsManager.create());\n\tconst ui: TUI = new TuiMainScreen(new ProcessTerminal(), settingsManager.getShowHardwareCursor(), getAgentDir());\n\tui.setClearOnShrink(settingsManager.getClearOnShrink());\n\treturn ui;\n}\n\nexport function startStartupTui(ui: TUI, settingsManager: SettingsManager): void {\n\tui.start();\n\tvoid applyDetectedStartupTheme(ui, settingsManager);\n}\n\nasync function applyDetectedStartupTheme(ui: TUI, settingsManager: SettingsManager): Promise<void> {\n\tconst themeSetting = settingsManager.getThemeSetting();\n\tif (themeSetting && !parseAutoThemeSetting(themeSetting)) return;\n\n\tconst terminalTheme = await detectTerminalThemeForAuto({ ui, timeoutMs: 100 });\n\tsetTheme(resolveThemeSetting(themeSetting, terminalTheme) ?? terminalTheme);\n\tui.invalidate();\n\tui.requestRender();\n}\n\nasync function clearStartupTui(ui: TUI): Promise<void> {\n\tui.clear();\n\tui.requestRender();\n\tawait new Promise((resolve) => setTimeout(resolve, 25));\n}\n\n/**\n * First-time setup runs when all of these hold:\n * - this is the official Agent Forge distribution (not a fork/rebrand)\n * - experimental features are enabled (AGENT_FORGE_EXPERIMENTAL=1)\n * - the default agent directory is used (no custom agent dir override)\n * - setup was not completed before (settings.json does not exist)\n */\nexport function shouldRunFirstTimeSetup(settingsPath: string = getSettingsPath()): boolean {\n\tif (\n\t\t!isOfficialDistribution({\n\t\t\tpackageName: PACKAGE_NAME,\n\t\t\tappName: APP_NAME,\n\t\t\tconfigDirName: CONFIG_DIR_NAME,\n\t\t})\n\t) {\n\t\treturn false;\n\t}\n\tif (!areExperimentalFeaturesEnabled()) {\n\t\treturn false;\n\t}\n\tif (process.env[ENV_AGENT_DIR]) {\n\t\treturn false;\n\t}\n\treturn !existsSync(settingsPath);\n}\n\nexport async function showStartupSelector<T>(\n\tsettingsManager: SettingsManager,\n\ttitle: string,\n\toptions: Array<{ label: string; value: T }>,\n): Promise<T | undefined> {\n\tconst ui = await createStartupTui(settingsManager);\n\treturn new Promise((resolve) => {\n\t\tlet settled = false;\n\t\tconst finish = async (result: T | undefined) => {\n\t\t\tif (settled) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsettled = true;\n\t\t\tawait clearStartupTui(ui);\n\t\t\tui.stop();\n\t\t\tresolve(result);\n\t\t};\n\n\t\tconst selector = new DialogSelectorComponent(\n\t\t\ttitle,\n\t\t\toptions.map((option) => option.label),\n\t\t\t(option) => void finish(options.find((entry) => entry.label === option)?.value),\n\t\t\t() => void finish(undefined),\n\t\t\t{ tui: ui },\n\t\t);\n\t\tui.addChild(selector);\n\t\tui.setFocus(selector);\n\t\tstartStartupTui(ui, settingsManager);\n\t});\n}\n\n/** Show the first-time setup dialog and persist the result */\nexport async function showFirstTimeSetup(settingsManager: SettingsManager): Promise<void> {\n\tconst ui = await createStartupTui(settingsManager);\n\treturn new Promise((resolve) => {\n\t\tlet settled = false;\n\t\tconst finish = async (result: FirstTimeSetupResult | undefined) => {\n\t\t\tif (settled) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsettled = true;\n\t\t\tif (result) {\n\t\t\t\tsettingsManager.setTheme(result.theme);\n\t\t\t\tsettingsManager.setEnableAnalytics(result.shareAnalytics);\n\t\t\t\tawait settingsManager.flush();\n\t\t\t}\n\t\t\tawait clearStartupTui(ui);\n\t\t\tui.stop();\n\t\t\tresolve();\n\t\t};\n\n\t\tconst showSetup = async () => {\n\t\t\tui.start();\n\t\t\tconst detectedTheme = await detectTerminalThemeForAuto({ ui, timeoutMs: 100 });\n\t\t\tsetTheme(detectedTheme);\n\t\t\tconst component = new FirstTimeSetupComponent({\n\t\t\t\tdetectedTheme,\n\t\t\t\tonThemePreview: (themeName) => {\n\t\t\t\t\tsetTheme(themeName);\n\t\t\t\t\tui.requestRender();\n\t\t\t\t},\n\t\t\t\tonSubmit: (result) => void finish(result),\n\t\t\t\tonCancel: () => void finish(undefined),\n\t\t\t});\n\t\t\tui.addChild(component);\n\t\t\tui.setFocus(component);\n\t\t\tui.requestRender();\n\t\t};\n\n\t\tvoid showSetup();\n\t});\n}\n\nexport async function showStartupInput(\n\tsettingsManager: SettingsManager,\n\ttitle: string,\n\tplaceholder?: string,\n): Promise<string | undefined> {\n\tconst ui = await createStartupTui(settingsManager);\n\treturn new Promise((resolve) => {\n\t\tlet settled = false;\n\t\tconst finish = async (result: string | undefined) => {\n\t\t\tif (settled) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsettled = true;\n\t\t\tinput.dispose();\n\t\t\tawait clearStartupTui(ui);\n\t\t\tui.stop();\n\t\t\tresolve(result);\n\t\t};\n\n\t\tconst input = new DialogInputComponent(\n\t\t\ttitle,\n\t\t\tplaceholder,\n\t\t\t(value) => void finish(value),\n\t\t\t() => void finish(undefined),\n\t\t\t{\n\t\t\t\ttui: ui,\n\t\t\t},\n\t\t);\n\t\tui.addChild(input);\n\t\tui.setFocus(input);\n\t\tstartStartupTui(ui, settingsManager);\n\t});\n}\n"]}

package/dist/cli/startup-ui.js

@@ -0,0 +1,185 @@
+import { ProcessTerminal, setCapabilityOverrides, setKeybindings, TuiMainScreen } from "@agent-forge/tui";
+import { existsSync } from "fs";
+import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR, getAgentDir, getSettingsPath, PACKAGE_NAME } from "../config.js";
+import { areExperimentalFeaturesEnabled } from "../core/experimental.js";
+import { KeybindingsManager } from "../core/keybindings.js";
+import { DefaultPackageManager } from "../core/package-manager.js";
+import { SettingsManager } from "../core/settings-manager.js";
+import { DialogInputComponent } from "../modes/interactive/components/dialog-input.js";
+import { DialogSelectorComponent } from "../modes/interactive/components/dialog-selector.js";
+import { FirstTimeSetupComponent, } from "../modes/interactive/components/first-time-setup.js";
+import { detectTerminalBackgroundFromEnv, detectTerminalThemeForAuto, initTheme, loadThemeFromPath, parseAutoThemeSetting, resolveThemeSetting, setRegisteredThemes, setTheme, } from "../modes/interactive/theme/theme.js";
+const OFFICIAL_PACKAGE_NAME = "@ai-agent-forge/agent-forge";
+const OFFICIAL_APP_NAME = "agent-forge";
+const OFFICIAL_CONFIG_DIR_NAME = ".agent-forge";
+function isOfficialDistribution({ packageName, appName, configDirName }) {
+    return (packageName === OFFICIAL_PACKAGE_NAME &&
+        appName === OFFICIAL_APP_NAME &&
+        configDirName === OFFICIAL_CONFIG_DIR_NAME);
+}
+function loadThemes(resources) {
+    const themes = [];
+    const seen = new Set();
+    for (const resource of resources) {
+        if (!resource.enabled)
+            continue;
+        try {
+            const loadedTheme = loadThemeFromPath(resource.path);
+            if (loadedTheme.name) {
+                if (seen.has(loadedTheme.name))
+                    continue;
+                seen.add(loadedTheme.name);
+            }
+            themes.push(loadedTheme);
+        }
+        catch {
+            // Startup prompts should not fail because a theme is broken. The normal
+            // resource loader reports theme diagnostics later in startup.
+        }
+    }
+    return themes;
+}
+async function loadStartupThemes(settingsManager) {
+    const globalSettingsManager = SettingsManager.inMemory(settingsManager.getGlobalSettings(), {
+        projectTrusted: false,
+    });
+    const packageManager = new DefaultPackageManager({
+        cwd: process.cwd(),
+        agentDir: getAgentDir(),
+        settingsManager: globalSettingsManager,
+    });
+    const resolvedPaths = await packageManager.resolve(async () => "skip");
+    return loadThemes(resolvedPaths.themes);
+}
+export async function createStartupTui(settingsManager) {
+    setCapabilityOverrides(settingsManager.getTerminalCapabilityOverrides());
+    setRegisteredThemes(await loadStartupThemes(settingsManager));
+    const terminalTheme = detectTerminalBackgroundFromEnv().theme;
+    initTheme(resolveThemeSetting(settingsManager.getThemeSetting(), terminalTheme) ?? terminalTheme);
+    setKeybindings(KeybindingsManager.create());
+    const ui = new TuiMainScreen(new ProcessTerminal(), settingsManager.getShowHardwareCursor(), getAgentDir());
+    ui.setClearOnShrink(settingsManager.getClearOnShrink());
+    return ui;
+}
+export function startStartupTui(ui, settingsManager) {
+    ui.start();
+    void applyDetectedStartupTheme(ui, settingsManager);
+}
+async function applyDetectedStartupTheme(ui, settingsManager) {
+    const themeSetting = settingsManager.getThemeSetting();
+    if (themeSetting && !parseAutoThemeSetting(themeSetting))
+        return;
+    const terminalTheme = await detectTerminalThemeForAuto({ ui, timeoutMs: 100 });
+    setTheme(resolveThemeSetting(themeSetting, terminalTheme) ?? terminalTheme);
+    ui.invalidate();
+    ui.requestRender();
+}
+async function clearStartupTui(ui) {
+    ui.clear();
+    ui.requestRender();
+    await new Promise((resolve) => setTimeout(resolve, 25));
+}
+/**
+ * First-time setup runs when all of these hold:
+ * - this is the official Agent Forge distribution (not a fork/rebrand)
+ * - experimental features are enabled (AGENT_FORGE_EXPERIMENTAL=1)
+ * - the default agent directory is used (no custom agent dir override)
+ * - setup was not completed before (settings.json does not exist)
+ */
+export function shouldRunFirstTimeSetup(settingsPath = getSettingsPath()) {
+    if (!isOfficialDistribution({
+        packageName: PACKAGE_NAME,
+        appName: APP_NAME,
+        configDirName: CONFIG_DIR_NAME,
+    })) {
+        return false;
+    }
+    if (!areExperimentalFeaturesEnabled()) {
+        return false;
+    }
+    if (process.env[ENV_AGENT_DIR]) {
+        return false;
+    }
+    return !existsSync(settingsPath);
+}
+export async function showStartupSelector(settingsManager, title, options) {
+    const ui = await createStartupTui(settingsManager);
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = async (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            await clearStartupTui(ui);
+            ui.stop();
+            resolve(result);
+        };
+        const selector = new DialogSelectorComponent(title, options.map((option) => option.label), (option) => void finish(options.find((entry) => entry.label === option)?.value), () => void finish(undefined), { tui: ui });
+        ui.addChild(selector);
+        ui.setFocus(selector);
+        startStartupTui(ui, settingsManager);
+    });
+}
+/** Show the first-time setup dialog and persist the result */
+export async function showFirstTimeSetup(settingsManager) {
+    const ui = await createStartupTui(settingsManager);
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = async (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (result) {
+                settingsManager.setTheme(result.theme);
+                settingsManager.setEnableAnalytics(result.shareAnalytics);
+                await settingsManager.flush();
+            }
+            await clearStartupTui(ui);
+            ui.stop();
+            resolve();
+        };
+        const showSetup = async () => {
+            ui.start();
+            const detectedTheme = await detectTerminalThemeForAuto({ ui, timeoutMs: 100 });
+            setTheme(detectedTheme);
+            const component = new FirstTimeSetupComponent({
+                detectedTheme,
+                onThemePreview: (themeName) => {
+                    setTheme(themeName);
+                    ui.requestRender();
+                },
+                onSubmit: (result) => void finish(result),
+                onCancel: () => void finish(undefined),
+            });
+            ui.addChild(component);
+            ui.setFocus(component);
+            ui.requestRender();
+        };
+        void showSetup();
+    });
+}
+export async function showStartupInput(settingsManager, title, placeholder) {
+    const ui = await createStartupTui(settingsManager);
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = async (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            input.dispose();
+            await clearStartupTui(ui);
+            ui.stop();
+            resolve(result);
+        };
+        const input = new DialogInputComponent(title, placeholder, (value) => void finish(value), () => void finish(undefined), {
+            tui: ui,
+        });
+        ui.addChild(input);
+        ui.setFocus(input);
+        startStartupTui(ui, settingsManager);
+    });
+}
+//# sourceMappingURL=startup-ui.js.map

package/dist/cli/startup-ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-ui.js","sourceRoot":"","sources":["../../src/cli/startup-ui.ts"],"names":[],"mappings":"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","sourcesContent":["import { ProcessTerminal, setCapabilityOverrides, setKeybindings, type TUI, TuiMainScreen } from \"@agent-forge/tui\";\nimport { existsSync } from \"fs\";\nimport { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR, getAgentDir, getSettingsPath, PACKAGE_NAME } from \"../config.ts\";\nimport { areExperimentalFeaturesEnabled } from \"../core/experimental.ts\";\nimport { KeybindingsManager } from \"../core/keybindings.ts\";\nimport { DefaultPackageManager, type ResolvedResource } from \"../core/package-manager.ts\";\nimport { SettingsManager } from \"../core/settings-manager.ts\";\nimport { DialogInputComponent } from \"../modes/interactive/components/dialog-input.ts\";\nimport { DialogSelectorComponent } from \"../modes/interactive/components/dialog-selector.ts\";\nimport {\n\tFirstTimeSetupComponent,\n\ttype FirstTimeSetupResult,\n} from \"../modes/interactive/components/first-time-setup.ts\";\nimport {\n\tdetectTerminalBackgroundFromEnv,\n\tdetectTerminalThemeForAuto,\n\tinitTheme,\n\tloadThemeFromPath,\n\tparseAutoThemeSetting,\n\tresolveThemeSetting,\n\tsetRegisteredThemes,\n\tsetTheme,\n\ttype Theme,\n} from \"../modes/interactive/theme/theme.ts\";\n\nconst OFFICIAL_PACKAGE_NAME = \"@ai-agent-forge/agent-forge\";\nconst OFFICIAL_APP_NAME = \"agent-forge\";\nconst OFFICIAL_CONFIG_DIR_NAME = \".agent-forge\";\n\ninterface DistributionMetadata {\n\tpackageName: string;\n\tappName: string;\n\tconfigDirName: string;\n}\n\nfunction isOfficialDistribution({ packageName, appName, configDirName }: DistributionMetadata): boolean {\n\treturn (\n\t\tpackageName === OFFICIAL_PACKAGE_NAME &&\n\t\tappName === OFFICIAL_APP_NAME &&\n\t\tconfigDirName === OFFICIAL_CONFIG_DIR_NAME\n\t);\n}\n\nfunction loadThemes(resources: ResolvedResource[]): Theme[] {\n\tconst themes: Theme[] = [];\n\tconst seen = new Set<string>();\n\tfor (const resource of resources) {\n\t\tif (!resource.enabled) continue;\n\t\ttry {\n\t\t\tconst loadedTheme = loadThemeFromPath(resource.path);\n\t\t\tif (loadedTheme.name) {\n\t\t\t\tif (seen.has(loadedTheme.name)) continue;\n\t\t\t\tseen.add(loadedTheme.name);\n\t\t\t}\n\t\t\tthemes.push(loadedTheme);\n\t\t} catch {\n\t\t\t// Startup prompts should not fail because a theme is broken. The normal\n\t\t\t// resource loader reports theme diagnostics later in startup.\n\t\t}\n\t}\n\treturn themes;\n}\n\nasync function loadStartupThemes(settingsManager: SettingsManager): Promise<Theme[]> {\n\tconst globalSettingsManager = SettingsManager.inMemory(settingsManager.getGlobalSettings(), {\n\t\tprojectTrusted: false,\n\t});\n\tconst packageManager = new DefaultPackageManager({\n\t\tcwd: process.cwd(),\n\t\tagentDir: getAgentDir(),\n\t\tsettingsManager: globalSettingsManager,\n\t});\n\tconst resolvedPaths = await packageManager.resolve(async () => \"skip\");\n\treturn loadThemes(resolvedPaths.themes);\n}\n\nexport async function createStartupTui(settingsManager: SettingsManager): Promise<TUI> {\n\tsetCapabilityOverrides(settingsManager.getTerminalCapabilityOverrides());\n\tsetRegisteredThemes(await loadStartupThemes(settingsManager));\n\tconst terminalTheme = detectTerminalBackgroundFromEnv().theme;\n\tinitTheme(resolveThemeSetting(settingsManager.getThemeSetting(), terminalTheme) ?? terminalTheme);\n\tsetKeybindings(KeybindingsManager.create());\n\tconst ui: TUI = new TuiMainScreen(new ProcessTerminal(), settingsManager.getShowHardwareCursor(), getAgentDir());\n\tui.setClearOnShrink(settingsManager.getClearOnShrink());\n\treturn ui;\n}\n\nexport function startStartupTui(ui: TUI, settingsManager: SettingsManager): void {\n\tui.start();\n\tvoid applyDetectedStartupTheme(ui, settingsManager);\n}\n\nasync function applyDetectedStartupTheme(ui: TUI, settingsManager: SettingsManager): Promise<void> {\n\tconst themeSetting = settingsManager.getThemeSetting();\n\tif (themeSetting && !parseAutoThemeSetting(themeSetting)) return;\n\n\tconst terminalTheme = await detectTerminalThemeForAuto({ ui, timeoutMs: 100 });\n\tsetTheme(resolveThemeSetting(themeSetting, terminalTheme) ?? terminalTheme);\n\tui.invalidate();\n\tui.requestRender();\n}\n\nasync function clearStartupTui(ui: TUI): Promise<void> {\n\tui.clear();\n\tui.requestRender();\n\tawait new Promise((resolve) => setTimeout(resolve, 25));\n}\n\n/**\n * First-time setup runs when all of these hold:\n * - this is the official Agent Forge distribution (not a fork/rebrand)\n * - experimental features are enabled (AGENT_FORGE_EXPERIMENTAL=1)\n * - the default agent directory is used (no custom agent dir override)\n * - setup was not completed before (settings.json does not exist)\n */\nexport function shouldRunFirstTimeSetup(settingsPath: string = getSettingsPath()): boolean {\n\tif (\n\t\t!isOfficialDistribution({\n\t\t\tpackageName: PACKAGE_NAME,\n\t\t\tappName: APP_NAME,\n\t\t\tconfigDirName: CONFIG_DIR_NAME,\n\t\t})\n\t) {\n\t\treturn false;\n\t}\n\tif (!areExperimentalFeaturesEnabled()) {\n\t\treturn false;\n\t}\n\tif (process.env[ENV_AGENT_DIR]) {\n\t\treturn false;\n\t}\n\treturn !existsSync(settingsPath);\n}\n\nexport async function showStartupSelector<T>(\n\tsettingsManager: SettingsManager,\n\ttitle: string,\n\toptions: Array<{ label: string; value: T }>,\n): Promise<T | undefined> {\n\tconst ui = await createStartupTui(settingsManager);\n\treturn new Promise((resolve) => {\n\t\tlet settled = false;\n\t\tconst finish = async (result: T | undefined) => {\n\t\t\tif (settled) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsettled = true;\n\t\t\tawait clearStartupTui(ui);\n\t\t\tui.stop();\n\t\t\tresolve(result);\n\t\t};\n\n\t\tconst selector = new DialogSelectorComponent(\n\t\t\ttitle,\n\t\t\toptions.map((option) => option.label),\n\t\t\t(option) => void finish(options.find((entry) => entry.label === option)?.value),\n\t\t\t() => void finish(undefined),\n\t\t\t{ tui: ui },\n\t\t);\n\t\tui.addChild(selector);\n\t\tui.setFocus(selector);\n\t\tstartStartupTui(ui, settingsManager);\n\t});\n}\n\n/** Show the first-time setup dialog and persist the result */\nexport async function showFirstTimeSetup(settingsManager: SettingsManager): Promise<void> {\n\tconst ui = await createStartupTui(settingsManager);\n\treturn new Promise((resolve) => {\n\t\tlet settled = false;\n\t\tconst finish = async (result: FirstTimeSetupResult | undefined) => {\n\t\t\tif (settled) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsettled = true;\n\t\t\tif (result) {\n\t\t\t\tsettingsManager.setTheme(result.theme);\n\t\t\t\tsettingsManager.setEnableAnalytics(result.shareAnalytics);\n\t\t\t\tawait settingsManager.flush();\n\t\t\t}\n\t\t\tawait clearStartupTui(ui);\n\t\t\tui.stop();\n\t\t\tresolve();\n\t\t};\n\n\t\tconst showSetup = async () => {\n\t\t\tui.start();\n\t\t\tconst detectedTheme = await detectTerminalThemeForAuto({ ui, timeoutMs: 100 });\n\t\t\tsetTheme(detectedTheme);\n\t\t\tconst component = new FirstTimeSetupComponent({\n\t\t\t\tdetectedTheme,\n\t\t\t\tonThemePreview: (themeName) => {\n\t\t\t\t\tsetTheme(themeName);\n\t\t\t\t\tui.requestRender();\n\t\t\t\t},\n\t\t\t\tonSubmit: (result) => void finish(result),\n\t\t\t\tonCancel: () => void finish(undefined),\n\t\t\t});\n\t\t\tui.addChild(component);\n\t\t\tui.setFocus(component);\n\t\t\tui.requestRender();\n\t\t};\n\n\t\tvoid showSetup();\n\t});\n}\n\nexport async function showStartupInput(\n\tsettingsManager: SettingsManager,\n\ttitle: string,\n\tplaceholder?: string,\n): Promise<string | undefined> {\n\tconst ui = await createStartupTui(settingsManager);\n\treturn new Promise((resolve) => {\n\t\tlet settled = false;\n\t\tconst finish = async (result: string | undefined) => {\n\t\t\tif (settled) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsettled = true;\n\t\t\tinput.dispose();\n\t\t\tawait clearStartupTui(ui);\n\t\t\tui.stop();\n\t\t\tresolve(result);\n\t\t};\n\n\t\tconst input = new DialogInputComponent(\n\t\t\ttitle,\n\t\t\tplaceholder,\n\t\t\t(value) => void finish(value),\n\t\t\t() => void finish(undefined),\n\t\t\t{\n\t\t\t\ttui: ui,\n\t\t\t},\n\t\t);\n\t\tui.addChild(input);\n\t\tui.setFocus(input);\n\t\tstartStartupTui(ui, settingsManager);\n\t});\n}\n"]}

package/dist/cli/trace-view.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `--trace <session>` viewer (设计 docs/design/会话轨迹与日志设计.md §8 第 3 期第 1 条).
+ *
+ * Resolves a session argument to its paired trace file (getTraceFilePathForSession
+ * is the single source of the pairing convention) and renders the records as a
+ * deterministic text timeline or structured JSON. Read-only: the JSONL reader
+ * tolerates trailing partial lines but never repairs or appends to the file
+ * (loadEntriesFromFile is deliberately not reused — its header validation
+ * rejects trace files and it has an append side effect).
+ */
+import type { TraceRecordV1 } from "../plugins/observability-types.ts";
+export interface TraceReadResult {
+    readonly records: TraceRecordV1[];
+    /**
+     * Lines that failed JSON.parse and were skipped. Blank lines are skipped
+     * like parseSessionEntryLine does, without counting (a trailing newline
+     * must not look like corruption).
+     */
+    readonly skippedMalformedLines: number;
+}
+/**
+ * Stream a JSONL trace file line by line (same bounded-buffer pattern as
+ * loadEntriesFromFile) and parse every line independently. Blank and
+ * malformed lines are skipped; malformed ones are counted.
+ */
+export declare function readTraceFile(path: string): TraceReadResult;
+export type ResolvedTraceTarget = {
+    readonly ok: true;
+    readonly sessionFile: string;
+    readonly traceFile: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export interface ResolveTraceTargetOptions {
+    readonly cwd: string;
+    /** Explicit session directory (--session-dir chain); default is the per-cwd default session dir. */
+    readonly sessionDir?: string;
+    /** Injectable agent dir for the subagent-session lookup; defaults to getAgentDir(). */
+    readonly agentDir?: string;
+}
+/**
+ * Four-level fallback from a session argument to a trace file:
+ * 1. path-like argument (separators or a `.jsonl` suffix) → used directly;
+ *    getTraceFilePathForSession maps an already-paired `.trace.jsonl` input
+ *    to itself (idempotent by convention).
+ * 2. otherwise resolveSessionPath (exact session id or prefix, local then global).
+ * 3. otherwise findSessionFile under <agentDir>/sessions/_agents (subagent
+ *    sessions live outside the user's session list; exact id).
+ * 4. empty argument → findMostRecentSession in the session dir.
+ */
+export declare function resolveTraceTarget(sessionArg: string, options: ResolveTraceTargetOptions): Promise<ResolvedTraceTarget>;
+/** Render the deterministic text timeline (ISO-8601 UTC time column by default). */
+export declare function renderTraceText(sessionFile: string, traceFile: string, records: readonly TraceRecordV1[], skippedMalformedLines: number, formatTime?: (epochMs: number) => string, filtered?: boolean): string;
+export interface TraceViewOptions {
+    /** Structured records output instead of the text timeline. */
+    readonly json?: boolean;
+    readonly cwd: string;
+    readonly sessionDir?: string;
+    /** Injectable agent dir for the subagent-session lookup; defaults to getAgentDir(). */
+    readonly agentDir?: string;
+    /**
+     * When true, exit the process with the resolved exit code after emitting
+     * output. Default false: return the structured result and let the caller
+     * (main.ts --trace dispatch) decide.
+     */
+    readonly exitProcess?: boolean;
+    /** Injectable time formatter for deterministic tests; defaults to toISOString. */
+    readonly formatTime?: (epochMs: number) => string;
+    /**
+     * Whitelist of trace record kinds to show (CLI `--trace-kind`). `undefined`
+     * means no kind filter; records keep their original seq numbers.
+     */
+    readonly kinds?: readonly string[];
+    /** Show only the last N records after the kind filter (CLI `--trace-limit`). */
+    readonly limit?: number;
+}
+export interface TraceViewResult {
+    readonly ok: boolean;
+    readonly exitCode: number;
+    /** Failure message; surfaced by the caller on stderr. */
+    readonly message?: string;
+}
+/** Entry point for the `--trace` view command: resolve, read, render, and report. */
+export declare function runTraceView(sessionArg: string, options: TraceViewOptions): Promise<TraceViewResult>;
+//# sourceMappingURL=trace-view.d.ts.map