@abot-ai/runtime 1.3.0 → 1.4.0

package/dist/src/sessions/types.d.ts

@@ -1,3 +1,4 @@
+import type { SessionProject } from "./project-binding.js";
 import type { AgentMode } from "../shared/types.js";
 import type { RuntimeAttachmentReference } from "../shared/attachments.js";
 import type { SessionMemoryCheckpoint } from "./memory/contracts.js";
@@ -50,6 +51,8 @@ export type SessionRuntimeEvent = {
 export type SessionRequestRecord = {
     requestId: string;
     sessionId: string;
+    /** Absent for legacy records and records recreated by late event appends. */
+    generation?: string;
     status: SessionRequestStatus;
     createdAt: string;
     updatedAt: string;
@@ -68,10 +71,12 @@ export type SessionRequestFinalState = {
 export type SessionRequestReplay = {
     requestId: string;
     sessionId: string;
+    generation?: string;
     events: Record<string, unknown>[];
     finalState: SessionRequestFinalState | null;
 };
 export type SessionListItem = {
+    project?: SessionProject;
     id: string;
     title: string;
     createdAt: number;
@@ -110,6 +115,7 @@ export type SessionSnapshotRequest = {
     finalState: SessionRequestFinalState | null;
 };
 export type SessionSnapshot = {
+    project?: SessionProject;
     sessionId: string;
     title: string;
     messages: SessionSnapshotMessage[];
@@ -156,6 +162,7 @@ export type SessionMessage = {
     attachments?: RuntimeAttachmentReference[];
 };
 export type SessionRecord = {
+    project?: SessionProject;
     id: string;
     title: string;
     createdAt: string;

package/dist/src/shared/directory-authority/bootstrap.d.ts

@@ -0,0 +1 @@
+export declare function directoryAuthorityScript(mode: "task" | "command", messageLimit: number, task?: (input: never) => unknown): string;

package/dist/src/shared/directory-authority/bootstrap.js

@@ -0,0 +1,118 @@
+/**
+ * This function is serialized into a fresh Node process. It must remain
+ * closure-free and use only node: built-ins; the starting cwd is untrusted
+ * until its identity has been compared with the inherited directory handle.
+ */
+function directoryAuthorityBootstrap(mode, messageLimit, task) {
+    const fs = require("node:fs");
+    function fail(code, message) {
+        throw Object.assign(new Error(message), { code });
+    }
+    function verifyDirectoryAuthority() {
+        const expected = fs.fstatSync(3, { bigint: true });
+        const actual = fs.statSync(".", { bigint: true });
+        const matchesHeldDirectory = expected.isDirectory() &&
+            actual.isDirectory() &&
+            expected.dev === actual.dev &&
+            expected.ino === actual.ino;
+        if (matchesHeldDirectory)
+            return;
+        fail("directory_authority_changed", "The directory changed before the operation could establish its authority.");
+    }
+    function readRequest() {
+        const fd = mode === "task" ? 0 : 4;
+        const chunk = Buffer.alloc(64 * 1024);
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const length = fs.readSync(fd, chunk, 0, chunk.length, null);
+            if (length === 0)
+                break;
+            total += length;
+            if (total > messageLimit) {
+                fail("directory_authority_request_too_large", "The directory operation input exceeds the bridge byte limit.");
+            }
+            chunks.push(Buffer.from(chunk.subarray(0, length)));
+        }
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    function reportFailure(error) {
+        const detail = error;
+        const code = typeof detail?.code === "string"
+            ? detail.code.slice(0, 256)
+            : "directory_authority_failed";
+        const message = typeof detail?.message === "string"
+            ? detail.message.slice(0, 4096)
+            : "The directory operation failed.";
+        let encoded;
+        try {
+            encoded = JSON.stringify({
+                ok: false,
+                error: { code, message, data: detail?.data },
+            });
+            if (Buffer.byteLength(encoded) > messageLimit)
+                throw new Error();
+        }
+        catch {
+            encoded = JSON.stringify({ ok: false, error: { code, message } });
+        }
+        writeResponse(mode === "task" ? 1 : 2, encoded);
+        process.exitCode = mode === "task" ? 0 : 125;
+    }
+    function writeResponse(fd, encoded) {
+        const bytes = Buffer.from(encoded);
+        let offset = 0;
+        while (offset < bytes.length) {
+            offset += fs.writeSync(fd, bytes, offset, bytes.length - offset);
+        }
+    }
+    async function runTask(input) {
+        if (!task)
+            fail("directory_authority_failed", "The directory task is missing.");
+        const result = await task(input);
+        const encoded = JSON.stringify({ ok: true, result });
+        if (Buffer.byteLength(encoded) > messageLimit) {
+            fail("directory_authority_result_too_large", "The directory operation result exceeds the bridge byte limit.");
+        }
+        writeResponse(1, encoded);
+    }
+    function runCommand(input) {
+        const { spawn } = require("node:child_process");
+        const command = input;
+        // Omitting cwd inherits the kernel-pinned authority. Resolving cwd() back
+        // into a pathname here would reopen the race this bridge prevents.
+        const child = spawn(command.command, command.args, {
+            stdio: ["ignore", "inherit", "inherit"],
+            env: process.env,
+        });
+        child.once("error", reportFailure);
+        child.once("exit", (code, signal) => {
+            if (signal) {
+                process.kill(process.pid, signal);
+                return;
+            }
+            if (typeof code === "number")
+                process.exitCode = code;
+        });
+    }
+    try {
+        verifyDirectoryAuthority();
+        const input = readRequest();
+        if (mode === "command") {
+            runCommand(input);
+            return;
+        }
+        void runTask(input).catch(reportFailure);
+    }
+    catch (error) {
+        reportFailure(error);
+    }
+}
+export function directoryAuthorityScript(mode, messageLimit, task) {
+    const taskSource = task ? `(${task.toString()})` : "undefined";
+    // tsx preserves nested function names with esbuild's __name annotation.
+    // Include that annotation's definition so the same trusted task works in
+    // development and in the production bundle without rewriting its source.
+    const preserveFunctionName = "const __name=(target,value)=>Object.defineProperty(target,'name',{value,configurable:true});";
+    return `${preserveFunctionName}(${directoryAuthorityBootstrap.toString()})(${JSON.stringify(mode)},${messageLimit},${taskSource});`;
+}

package/dist/src/shared/directory-authority/command.d.ts

@@ -0,0 +1,8 @@
+import { type ChildProcessByStdio } from "node:child_process";
+import type { Readable } from "node:stream";
+import { type DirectoryAuthorityLocation } from "./protocol.js";
+export declare function spawnDirectoryAuthorityCommand(input: DirectoryAuthorityLocation & Readonly<{
+    command: string;
+    args: readonly string[];
+    env?: NodeJS.ProcessEnv;
+}>): ChildProcessByStdio<null, Readable, Readable>;

package/dist/src/shared/directory-authority/command.js

@@ -0,0 +1,27 @@
+import { spawn } from "node:child_process";
+import { directoryAuthorityScript } from "./bootstrap.js";
+import { assertDirectoryAuthorityLocation, authorityEnvironment, AUTHORITY_MESSAGE_LIMIT, encodeAuthorityRequest, } from "./protocol.js";
+export function spawnDirectoryAuthorityCommand(input) {
+    assertDirectoryAuthorityLocation(input);
+    const request = encodeAuthorityRequest({
+        command: input.command,
+        args: input.args,
+    });
+    const child = spawn(process.execPath, [
+        "--input-type=commonjs",
+        "-e",
+        directoryAuthorityScript("command", AUTHORITY_MESSAGE_LIMIT),
+    ], {
+        cwd: input.directoryPath,
+        env: authorityEnvironment(input.env),
+        detached: true,
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe", input.directoryFd, "pipe"],
+    });
+    const requestPipe = child.stdio[4];
+    // An early authority failure may close the request pipe before the parent
+    // finishes writing. The process result remains the authoritative error.
+    requestPipe?.on("error", () => undefined);
+    requestPipe?.end(request);
+    return child;
+}

package/dist/src/shared/directory-authority/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class DirectoryAuthorityError extends Error {
+    readonly code: string;
+    readonly data?: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: string, message: string, data?: Readonly<Record<string, unknown>> | undefined);
+}

package/dist/src/shared/directory-authority/errors.js

@@ -0,0 +1,10 @@
+export class DirectoryAuthorityError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = "DirectoryAuthorityError";
+    }
+}

package/dist/src/shared/directory-authority/index.d.ts

@@ -0,0 +1,3 @@
+export { spawnDirectoryAuthorityCommand } from "./command.js";
+export { DirectoryAuthorityError } from "./errors.js";
+export { runDirectoryAuthorityTask } from "./task.js";

package/dist/src/shared/directory-authority/index.js

@@ -0,0 +1,3 @@
+export { spawnDirectoryAuthorityCommand } from "./command.js";
+export { DirectoryAuthorityError } from "./errors.js";
+export { runDirectoryAuthorityTask } from "./task.js";

package/dist/src/shared/directory-authority/protocol.d.ts

@@ -0,0 +1,11 @@
+export declare const AUTHORITY_MESSAGE_LIMIT: number;
+export declare const AUTHORITY_STDERR_LIMIT: number;
+export declare const AUTHORITY_TASK_TIMEOUT_MS = 30000;
+export type DirectoryAuthorityLocation = Readonly<{
+    directoryPath: string;
+    directoryFd: number;
+}>;
+export declare function assertDirectoryAuthorityLocation(location: DirectoryAuthorityLocation): void;
+export declare function authorityEnvironment(environment?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function encodeAuthorityRequest(input: unknown): string;
+export declare function decodeAuthorityResult<Result>(output: string): Result;

package/dist/src/shared/directory-authority/protocol.js

@@ -0,0 +1,62 @@
+import { isAbsolute } from "node:path";
+import { DirectoryAuthorityError } from "./errors.js";
+export const AUTHORITY_MESSAGE_LIMIT = 8 * 1024 * 1024;
+export const AUTHORITY_STDERR_LIMIT = 16 * 1024;
+export const AUTHORITY_TASK_TIMEOUT_MS = 30_000;
+export function assertDirectoryAuthorityLocation(location) {
+    if (!isAbsolute(location.directoryPath)) {
+        throw new DirectoryAuthorityError("directory_authority_invalid_path", "The directory authority requires an absolute starting path.");
+    }
+    const hasOpenDescriptorNumber = Number.isInteger(location.directoryFd) && location.directoryFd >= 0;
+    if (hasOpenDescriptorNumber)
+        return;
+    throw new DirectoryAuthorityError("directory_authority_invalid_fd", "The directory authority requires an open directory descriptor.");
+}
+export function authorityEnvironment(environment = process.env) {
+    const sanitized = { ...environment };
+    delete sanitized.NODE_OPTIONS;
+    delete sanitized.NODE_PATH;
+    return sanitized;
+}
+export function encodeAuthorityRequest(input) {
+    let encoded;
+    try {
+        encoded = JSON.stringify(input);
+    }
+    catch {
+        throw new DirectoryAuthorityError("directory_authority_invalid_request", "The directory operation input must be JSON serializable.");
+    }
+    if (encoded === undefined) {
+        throw new DirectoryAuthorityError("directory_authority_invalid_request", "The directory operation input must be JSON serializable.");
+    }
+    if (Buffer.byteLength(encoded) <= AUTHORITY_MESSAGE_LIMIT)
+        return encoded;
+    throw new DirectoryAuthorityError("directory_authority_request_too_large", "The directory operation input exceeds the bridge byte limit.");
+}
+function isAuthorityMessageObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function decodeAuthorityResult(output) {
+    let message;
+    try {
+        message = JSON.parse(output);
+    }
+    catch {
+        throw new DirectoryAuthorityError("directory_authority_protocol_error", "The directory operation returned an invalid response.");
+    }
+    if (!isAuthorityMessageObject(message)) {
+        throw new DirectoryAuthorityError("directory_authority_protocol_error", "The directory operation returned an invalid response.");
+    }
+    if (message.ok === true)
+        return message.result;
+    const hasAuthorityError = message.ok === false && isAuthorityMessageObject(message.error);
+    if (!hasAuthorityError) {
+        throw new DirectoryAuthorityError("directory_authority_protocol_error", "The directory operation returned an invalid response.");
+    }
+    const { code, message: explanation, data, } = message.error;
+    const hasErrorDescription = typeof code === "string" && typeof explanation === "string";
+    if (!hasErrorDescription) {
+        throw new DirectoryAuthorityError("directory_authority_protocol_error", "The directory operation returned an invalid error response.");
+    }
+    throw new DirectoryAuthorityError(code, explanation, isAuthorityMessageObject(data) ? data : undefined);
+}

package/dist/src/shared/directory-authority/task.d.ts

@@ -0,0 +1,7 @@
+import { type DirectoryAuthorityLocation } from "./protocol.js";
+export declare function runDirectoryAuthorityTask<Input, Result>(input: DirectoryAuthorityLocation & Readonly<{
+    input: Input;
+    task: (input: Input) => Result | Promise<Result>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}>): Promise<Result>;

package/dist/src/shared/directory-authority/task.js

@@ -0,0 +1,97 @@
+import { spawn } from "node:child_process";
+import { directoryAuthorityScript } from "./bootstrap.js";
+import { DirectoryAuthorityError } from "./errors.js";
+import { assertDirectoryAuthorityLocation, authorityEnvironment, AUTHORITY_MESSAGE_LIMIT, AUTHORITY_STDERR_LIMIT, AUTHORITY_TASK_TIMEOUT_MS, decodeAuthorityResult, encodeAuthorityRequest, } from "./protocol.js";
+export async function runDirectoryAuthorityTask(input) {
+    assertDirectoryAuthorityLocation(input);
+    const request = encodeAuthorityRequest(input.input);
+    const timeoutMs = input.timeoutMs ?? AUTHORITY_TASK_TIMEOUT_MS;
+    const hasPositiveDeadline = Number.isFinite(timeoutMs) && timeoutMs > 0;
+    if (!hasPositiveDeadline) {
+        throw new DirectoryAuthorityError("directory_authority_invalid_timeout", "The directory operation deadline must be a positive finite duration.");
+    }
+    if (input.signal?.aborted) {
+        throw new DirectoryAuthorityError("directory_authority_aborted", "The directory operation was cancelled before it started.");
+    }
+    const child = spawn(process.execPath, [
+        "--input-type=commonjs",
+        "-e",
+        directoryAuthorityScript("task", AUTHORITY_MESSAGE_LIMIT, input.task),
+    ], {
+        cwd: input.directoryPath,
+        env: authorityEnvironment(),
+        detached: true,
+        windowsHide: true,
+        stdio: ["pipe", "pipe", "pipe", input.directoryFd],
+    });
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        const stderrChunks = [];
+        let bytes = 0;
+        let stderrBytes = 0;
+        let failure;
+        const stop = (error) => {
+            if (failure)
+                return;
+            failure = error;
+            if (typeof child.pid === "number") {
+                try {
+                    process.kill(-child.pid, "SIGKILL");
+                    return;
+                }
+                catch {
+                    // A process which has already exited may no longer own its group.
+                }
+            }
+            child.kill("SIGKILL");
+        };
+        const onAbort = () => stop(new DirectoryAuthorityError("directory_authority_aborted", "The directory operation was cancelled."));
+        const timer = setTimeout(() => stop(new DirectoryAuthorityError("directory_authority_timeout", "The directory operation exceeded its deadline.")), timeoutMs);
+        timer.unref();
+        input.signal?.addEventListener("abort", onAbort, { once: true });
+        if (input.signal?.aborted)
+            onAbort();
+        child.stdout.on("data", (chunk) => {
+            bytes += chunk.length;
+            if (bytes > AUTHORITY_MESSAGE_LIMIT) {
+                stop(new DirectoryAuthorityError("directory_authority_result_too_large", "The directory operation result exceeds the bridge byte limit."));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            const remaining = Math.max(AUTHORITY_STDERR_LIMIT - stderrBytes, 0);
+            if (remaining === 0)
+                return;
+            stderrChunks.push(chunk.subarray(0, remaining));
+            stderrBytes += Math.min(chunk.length, remaining);
+        });
+        child.stdin.on("error", () => undefined);
+        child.once("error", (error) => {
+            failure ??= new DirectoryAuthorityError("directory_authority_unavailable", `The directory operation could not start: ${error.message}`);
+        });
+        child.once("close", (code, signal) => {
+            clearTimeout(timer);
+            input.signal?.removeEventListener("abort", onAbort);
+            if (failure) {
+                reject(failure);
+                return;
+            }
+            if (code !== 0) {
+                reject(new DirectoryAuthorityError("directory_authority_failed", "The directory operation process did not complete successfully.", {
+                    exitCode: code,
+                    signal,
+                    stderr: Buffer.concat(stderrChunks).toString("utf8"),
+                }));
+                return;
+            }
+            try {
+                resolve(decodeAuthorityResult(Buffer.concat(chunks).toString("utf8")));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        child.stdin.end(request);
+    });
+}

package/dist/src/web-ui/app/ARCHITECTURE.md

@@ -48,6 +48,17 @@ the completion-event boundary: tool output, canonical evidence and model context
 are unchanged. The Web UI does not fetch a file or memory record again to recreate
 historical evidence. Passive Runtime memory remains outside tool activity.
 
+`tool-process-activity-fields.js` projects declared process display fields without
+branching on tool identities. Opted-in commands retain up to 4,096 characters and
+whitespace; shared `conversation-tool-evidence.js` renders them as inert
+preformatted text in both activity and approval disclosures. Working
+directory, target, exit code and recorded process evidence remain distinct from
+model-authored intent. Result output stays a bounded excerpt, and completion or
+exit zero does not establish an application window or independent outcome check.
+Terminal failures preserve recorded result fields and clipping flags. Old events
+without declared input/output evidence remain unavailable; the UI never guesses
+commands from rationale or opaque parameter summaries.
+
 Web sources appear in a separate Activity section alongside role cards and the event timeline. `web-source-event.js` projects only successful `web_search` and `web_fetch` completions; `web-sources.js` validates bounded plugin receipts and groups them by recorded call. `conversation-sources.js` renders links and retrieval/presentation states without interpreting answer text. Source-bearing events retain their own identity before display grouping, and stored session events use the same projection as live events. Session switching clears them with the existing Activity state.
 
 The optional `meta.webSources` version 1 receipt describes the final bounded **tool output**, not whether a later model invocation consumed or cited it. Older events can show found/fetched URLs with unknown output visibility; absent or unsupported receipts never imply full content. Favicons are best-effort browser requests to the source origin's `/favicon.ico`, loaded lazily with no referrer and a local fallback. No third-party icon service or server proxy is used. Source URL policy rejects unsafe schemes and credentials, and prevents automatic image loads for local/private IP literals; origin DNS, redirects, cookies, and browser image policy remain browser concerns. Icons carry no evidence and never block tool execution.
@@ -80,6 +91,36 @@ The native conversation list uses the existing `SessionService` disk reader and
 
 Read-state persistence is an optional Web UI projection. `session-read-state/availability.ts` isolates sidecar failures from listing, loading, clearing and deleting conversations. A failure returns `readStateStatus: "unavailable"` and unknown counts, preserves the sidecar for diagnosis, and leaves read acknowledgements unsuccessful. The browser keeps the last known receipt, labels unavailable tracking explicitly and resumes normal counts after a healthy list refresh. Canonical session and attachment failures remain errors. Workspace visibility is committed before change callbacks attempt to acknowledge visible messages, including drawer closure and responsive layout changes.
 
+## Conversation file preview
+
+`conversation-file-reference.js` projects only explicit successful file-output
+receipts from tool events. Activity keeps this reference separate from the
+historical sent/received fields and excerpt. `conversation-file-action.js` makes
+the existing filename an inline preview control inside the tool summary. Its click suppresses disclosure activation;
+other summary interactions retain the recorded evidence disclosure.
+
+`conversation-file-preview-controller.js` owns scoped loading and stale-response
+rejection. The feature adapter mounts the viewer outside the message subtree and
+preserves conversation scroll while the layout changes. Session resets and
+workspace departure close it; responsive focus and Escape behavior belong to
+`conversation-file-focus.js`. Transport stays in the conversation-files service.
+
+The local backend's `conversation-file-access.ts` admits only a saved or scoped
+active completion belonging to the requested environment, session and request.
+`conversation-file-target.ts` owns the held file and root/containment identity
+checks shared by content reads and native opening. The route revalidates request
+generation and completion before returning bytes or handing off to a Mac app.
+`conversation-file-native-request.ts` limits native opening to same-origin JSON
+POSTs from a local browser on macOS. `conversation-file-native-open.ts` restricts
+file types and invokes the fixed OS opener without a shell. The viewer exposes
+this action only when its preview response includes `nativeOpenAvailable: true`;
+its controller scopes busy/failure feedback to the selected file. The OS app
+resolves the original pathname after handoff; that asynchronous read is outside
+the preview reader's held-descriptor guarantee. The receipt
+is presentation-only: the optional filesystem report callback feeds event
+metadata, never the canonical tool result or model context. No file registry or
+historical content snapshot is created.
+
 ## Styles
 
 `styles.css` is the ordered manifest. The modules under `styles/` own:
@@ -97,7 +138,6 @@ Keep responsive overrides last and avoid moving declarations between modules wit
 
 Visual components may format or group events, but they never accept transport frames or construct Runtime API payloads. Realtime frame parsing belongs to `realtime-transport.js`; request sequence and terminal-state reduction belong to `realtime-event-controller.js`; endpoint construction and HTTP payload serialization belong to `runtime-web-client.js` and its feature request modules; and feature controllers own when those operations occur. Config remains explicit-save; presentation changes must never introduce autosave.
 
-
 ## Core schedules
 
 `schedules-feature.js` composes the scheduler browser feature from its controller,
@@ -125,3 +165,83 @@ run identity before activating the ordinary realtime request lifecycle. Duplicat
 trigger delivery cannot add another user message or reactivate a completed run.
 The scheduler page and chat card are presentation-only consumers; the runtime
 scheduler remains the sole owner of Job state and dispatch decisions.
+
+## Interactive setup and configuration activation
+
+The setup guide composes focused rendering/validation modules and receives
+configuration transport callbacks. Runtime onboarding retains catalog authority
+over chat readiness. Home suppresses its dashboard data and shortcuts while
+setup is required; the guide has one scroll owner in either Home or Chat.
+OpenAI credentials live only in the current password input and one save payload.
+They never enter browser state, HTML attributes, preferences or control logs.
+
+The setup sequence is Provider, Connection, Embedding, Plugins and Ready.
+The onboarding feature assembles transport dependencies outside app.js; focused
+step modules own embedding and plugin card selection. Chat connection writes
+defer activation in the wizard, while ordinary setup API callers retain their
+existing immediate-activation behavior. The pending-activation gate keeps the
+catalog unavailable until the explicit final apply, including browser reload in
+the same Web process. Optional choices are read back from canonical saved files.
+
+Embedding setup prepares only the requested provider and its private credential,
+then delegates to the existing memory probe-before-save service. Probe dimensions
+and fingerprints come from the provider response; the UI never invents them.
+Provider preparation may survive a later probe failure, which is reported without
+exposing credentials. The memory Web router resolves the current configuration
+path per request so first-time setup uses local/runtime.config.json correctly.
+Plugin cards reuse the existing manifest selection API, preserving sibling tools
+and saved policies. Fresh installations start with all plugins and tools selected.
+The onboarding plugin cards display every tool checkbox directly. Their dedicated
+stylesheet widens only this step and keeps the outer workspace as the scroll owner.
+
+Configuration composes a plugin manager using the canonical manifest selection
+projection. The separate activation control explicitly applies saved files.
+The server checks synchronous owner admission, refuses busy or externally owned
+environments, and refreshes its gateway through the owning lifecycle callback.
+Browser reload and saved selection are not evidence of live activation.
+
+### Additive model setup
+
+Configuration composes a separate Provider / Model / Ready dialog in
+components/model-setup/. It shares the wizard shell and connection form with
+first setup, while retaining its own additive save/apply lifecycle. The dialog
+is outside the dashboard so refresh and mutation locking cannot detach it.
+An entered API key remains only in the mounted password field until final save;
+review and back navigation do not copy it into state or markup.
+
+configuration-feature.js guards opening against existing configuration drafts,
+blocks workspace/environment navigation while the dialog is open, and holds the
+external mutation lock during save, Apply and refresh. Saved model identity
+survives Apply failure; successful Apply survives refresh failure. Completion
+refreshes Memory provider choices and chat models, selects the new profile, and
+focuses it only after closing the modal and releasing the lock.
+
+local-runtime/model-setup-\* owns catalog/input/credential/addition behavior.
+It uses the canonical configuration repository and shared CLI merge helper,
+preserving existing profiles, references, defaults and connection settings.
+Only new OpenAI/Ollama connections are created here; existing provider IDs are
+resolved by adapter type. The transport exposes no secret values and requires
+the same-origin JSON mutation guard. This flow does not invoke a model.
+
+## Projects and permission modes
+
+`projects-feature.js` composes project UI; `projects-controller.js` owns project
+and folder loading, creation and stale-response rejection. Presentation modules
+render the creation form and sidebar groups, while `runtime-web-client/projects.js`
+owns transport. The folder form occupies the chat canvas without resetting the
+active conversation or draft. It closes the file viewer through its existing
+presentation lifecycle. Creation calls the owner API; a saved project session is
+opened through the canonical conversation controller without a model request.
+
+The session controller remains the owner of session row actions and read state.
+Its injected group renderer places project groups above ordinary conversations,
+including projects with no sessions. The session's saved project snapshot also
+provides the visible working-folder label. Neither project presentation nor client
+request payloads overwrite global runtime paths.
+
+`tool-permission-mode-controller.js` owns the permission selector and explicit
+per-session preference changes; `lib/tool-permission-mode.js` owns known browser
+values and server compatibility. FULL+ requires advertised server support, and
+transport rejects unsupported requests without a silent downgrade. The existing
+composer queue keeps its captured mode. Project membership never selects FULL+.
+`app-state.js` constructs the same one shared browser state identity for `app.js`.

package/dist/src/web-ui/app/app-bootstrap.js

@@ -8,6 +8,7 @@ export async function bootstrapWebApp({
   homeComposer,
   dashboard,
   schedules,
+  projects,
   selection,
   client,
   bindables,
@@ -30,6 +31,7 @@ export async function bootstrapWebApp({
   renderMessages();
   state.config = await client.loadWebConfig();
   schedules.refreshAvailability();
+  projects?.refreshAvailability();
   selection.renderEnvironmentOptions();
   const options = selection.environmentOptions();
   const saved = preferences.environmentId();
@@ -42,6 +44,7 @@ export async function bootstrapWebApp({
   selection.renderAgentPicker();
   realtime.connect();
   await Promise.allSettled([
+    projects?.load(),
     selection.loadModels(),
     selection.loadAgentMode(),
     operations.loadRuntimeStatus(),

package/dist/src/web-ui/app/app-dom.js

@@ -26,6 +26,8 @@ export function findAppDom(documentRoot = document) {
     environmentSelect: documentRoot.getElementById("environmentSelect"),
     agentPickerButton: documentRoot.getElementById("agentPickerButton"),
     agentPickerMenu: documentRoot.getElementById("agentPickerMenu"),
+    newProjectButton: documentRoot.getElementById("newProjectButton"),
+    projectCreationRoot: documentRoot.getElementById("projectCreationRoot"),
     newSessionButton: documentRoot.getElementById("newSessionButton"),
     refreshSessionsButton: documentRoot.getElementById("refreshSessionsButton"),
     closeSessionsButton: documentRoot.getElementById("closeSessionsButton"),
@@ -33,6 +35,7 @@ export function findAppDom(documentRoot = document) {
     sessionSearchInput: documentRoot.getElementById("sessionSearchInput"),
     sessionsCount: documentRoot.getElementById("sessionsCount"),
     sessionsList: documentRoot.getElementById("sessionsList"),
+    currentProjectContext: documentRoot.getElementById("currentProjectContext"),
     sessionTitle: documentRoot.getElementById("sessionTitle"),
     agentModeButton: documentRoot.getElementById("agentModeButton"),
     agentModeMenu: documentRoot.getElementById("agentModeMenu"),

package/dist/src/web-ui/app/app-state.js

@@ -0,0 +1,38 @@
+export function createAppState() {
+  return {
+    config: null,
+    connected: false,
+    sessions: [],
+    pinnedSessionIds: [],
+    sessionModes: {},
+    sessionModels: {},
+    lastModelByEnvironment: {},
+    agentMode: "reasoning",
+    supportedAgentModes: ["fast", "reasoning", "deep", "auto"],
+    agentModeMenuOpen: false,
+    permissionModeMenuOpen: false,
+    agentPickerOpen: false,
+    busySessionIds: new Set(),
+    messages: [],
+    events: [],
+    taskProgressByRequest: new Map(),
+    contextWindowByRequest: new Map(),
+    submittedToolApprovalIds: new Set(),
+    requestMessages: new Map(),
+    currentSessionId: "",
+    activeRequestId: "",
+    sessionViewVersion: 0,
+    lastSeqByRequest: new Map(),
+    modelProfiles: [],
+    defaultModelProfileId: "",
+    runtimeAvailability: { status: "loading" },
+    pendingAttachments: [],
+    pendingAttachmentUploadCounts: new Map(),
+    composerAttachmentGeneration: 0,
+    composerSending: false,
+    composerQueueDrainingScopes: new Set(),
+    composerQueueRecoveredReleaseTokens: new Set(),
+    activeComposerQueueRecovery: null,
+    sessionQuery: "",
+  };
+}