A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.
TypeScript
fix: return to the first accounts step, explain the access key, and drop the unused container memory server
Alan Buscagliaac86f640a862
diff --git a/.gitignore b/.gitignoreindex 327c780..d7a6399 100644--- a/.gitignore+++ b/.gitignore@@ -8,3 +8,6 @@ apps/desktop/src-tauri/target/apps/desktop/src-tauri/gen/*.log.DS_Store++# Declarations emitted next to sources by accident+packages/*/src/**/*.d.tsdiff --git a/docker/entrypoint.sh b/docker/entrypoint.shindex aad8977..b476b02 100755--- a/docker/entrypoint.sh+++ b/docker/entrypoint.sh@@ -1,8 +1,5 @@#!/bin/sh-# Starts the memory server, then the Gentle Dot daemon in the foreground.+# Starts the Gentle Dot daemon in the foreground. The engine starts its own memory server.set -eumkdir -p "$GENTLE_DOT_DATA_DIR" "$GENTLE_DOT_WORKSPACE"-if command -v engram >/dev/null 2>&1; then- engram serve >"$GENTLE_DOT_DATA_DIR/engram.log" 2>&1 &-fiexec node /app/packages/daemon/src/cli.tsdiff --git a/docs/design.md b/docs/design.mdindex 1c99ef7..11af339 100644--- a/docs/design.md+++ b/docs/design.md@@ -61,7 +61,9 @@ docs/ design, deployment guide, security checklist## 3. Agent supervisor-- Spawns `gentle-shell --mode rpc --session-dir <dataDir>/sessions --append-system-prompt <identity file>` with `cwd` = configured workspace (default: home directory).+- Spawns the bundled engine (`node <gentle-pi>/bin/gentle-shell.mjs --home <dataDir>/agent --mode rpc --session-dir <dataDir>/sessions --append-system-prompt <identity file>`) with `cwd` = configured workspace (default: `<dataDir>/workspace`, so the engine never reads a `.pi` project config from the user's home).+- Isolation (S12): the child runs with its own `HOME=<dataDir>/home` (0700) and `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_CACHE_HOME`, and `XDG_STATE_HOME` under it, plus `GENTLE_PI_CONFIG_HOME=<dataDir>/gentle-ai`. `PATH` is kept, and `GIT_CONFIG_GLOBAL` points at the user's real `~/.gitconfig` when it exists, to keep their git identity. Inherited `PI_CODING_AGENT_DIR`, `GENTLE_PI_AGENT_HOME`, `GENTLE_SHELL_CONFIG`, and `ENGRAM_URL` are removed. The engine's first run otherwise writes into the real `~` (`~/.gentle-shell`, `~/.pi/agent/pi-pretty`, `~/.gentle-ai`), which `--home` alone does not prevent.+- Memory: with its own HOME, the engine's memory plugin treats the user's Engram server as foreign, so the assistant runs its own Engram on `ENGRAM_PORT=7438` (override `GENTLE_DOT_ENGRAM_PORT`), with its memory stored under `<dataDir>/home/.engram`. The user's Engram on 7437 is never touched.- Parses stdout with strict LF framing on a byte stream. Never Node `readline` (it splits on U+2028/U+2029, which are valid inside JSON).- Correlates commands by `id`; stdout records without `id` are session events.- Reads stderr only as diagnostics (logged, never parsed).@@ -177,7 +179,7 @@ Every daemon message carries `seq` (monotonic per connection) so the UI can dete- Pi sessions persist under `~/.gentle-dot/sessions`, and the daemon reopens the last active one after any restart.- After a crash, the turn that was in flight is lost. The conversation history remains, and the UI shows "I was interrupted. Continue?" with a Continue button that sends "Continue where you left off."-- Engram keeps decisions and progress across conversations; the Gentle workflow already consults it when resuming.+- The assistant's own Engram (port 7438) keeps decisions and progress across conversations; the Gentle workflow already consults it when resuming.- Pi Durable is reconsidered only for unattended or scheduled work.## 8. Security (local)@@ -194,7 +196,7 @@ The desktop app bundles the built UI (`packages/ui/dist/app`) as its frontend, s| Label | Size | URL | Properties ||---|---|---|---|-| `dot` | 64 × 84 (the rose's aspect) | `index.html?surface=dot` | transparent, no decorations, always on top, not resizable, skip taskbar, visible on all workspaces, shadow off |+| `dot` | 72 × 72 pt (the rose in a 66 pt black disc) | `index.html?surface=dot` | transparent outside the disc, no decorations, always on top, not resizable, skip taskbar, visible on all workspaces, shadow off; placed in logical points || `panel` | 420 × 640 | `index.html?surface=panel` | transparent with macOS vibrancy (`HudWindow`), no decorations, always on top, hidden at start, skip taskbar |When the panel opens, it is placed next to the Dot on the side with more room, and it stays inside the monitor.@@ -230,7 +232,9 @@ On launch, the app checks `GET /health`. If the daemon does not answer, the app`~/.gentle-dot/config.json`, all optional:```json-{ "port": 4317, "workspace": "~", "shortcut": "Alt+Space", "launchAtLogin": false }+{ "port": 4317, "workspace": "~/Documents", "shortcut": "Alt+Space", "launchAtLogin": false }```-Environment overrides: `GENTLE_DOT_AGENT_HOME` (default `~/.gentle-dot/agent`), `GENTLE_DOT_PORT`, `GENTLE_DOT_HOST` (default `127.0.0.1`; `0.0.0.0` only inside a container), `GENTLE_DOT_DATA_DIR`, `GENTLE_DOT_WORKSPACE`, `GENTLE_DOT_UI_DIR`, `GENTLE_DOT_AGENT_BIN`, `GENTLE_DOT_AGENT_ARGS` (JSON array), `GENTLE_DOT_ALLOWED_ORIGINS` (JSON array).+All keys are optional; `workspace` defaults to `<dataDir>/workspace`.++Environment overrides: `GENTLE_DOT_AGENT_HOME` (default `~/.gentle-dot/agent`), `GENTLE_DOT_ENGRAM_PORT` (default `7438`), `GENTLE_DOT_PORT`, `GENTLE_DOT_HOST` (default `127.0.0.1`; `0.0.0.0` only inside a container), `GENTLE_DOT_DATA_DIR`, `GENTLE_DOT_WORKSPACE`, `GENTLE_DOT_UI_DIR`, `GENTLE_DOT_AGENT_BIN`, `GENTLE_DOT_AGENT_ARGS` (JSON array), `GENTLE_DOT_ALLOWED_ORIGINS` (JSON array).diff --git a/e2e/web.spec.ts b/e2e/web.spec.tsindex 2c8fcf3..96685ae 100644--- a/e2e/web.spec.ts+++ b/e2e/web.spec.ts@@ -104,9 +104,8 @@ test("opens accounts with /login, offers subscriptions without Claude, and conneawait key.fill("sk-e2e-not-real");await accounts.getByRole("button", { name: "Continue" }).click();await expect(accounts.getByRole("status")).toHaveText("Connected to OpenAI.");+ // "Back to accounts" returns to the first step, which lists connected accounts.await accounts.getByRole("button", { name: "Back to accounts" }).click();- // Back to the API key list; connected accounts are listed on the first step.- await accounts.getByRole("button", { name: "Back", exact: true }).click();const signOut = accounts.getByRole("region", { name: "Connected" }).getByRole("button", { name: "Sign out of OpenAI" });@@ -167,10 +166,10 @@ test("creates a profile with /profiles, edits a role, and switches to it", asynctest("explains a rejected access key", async ({ page }) => {await page.goto("/#token=wrong-token");- await expect(page.getByRole("status")).toContainText("This link is not valid anymore");+ await expect(page.getByRole("status")).toContainText("This access key is not valid anymore");});-test("asks for the printed link when there is no access key", async ({ page }) => {+test("asks for the access key when there is none", async ({ page }) => {await page.goto("/");- await expect(page.getByRole("status")).toContainText("Open the link the assistant printed");+ await expect(page.getByRole("status")).toContainText("This page needs your access key");});diff --git a/packages/daemon/src/bridge.d.ts b/packages/daemon/src/bridge.d.tsdeleted file mode 100644index 7e80514..0000000--- a/packages/daemon/src/bridge.d.ts+++ /dev/null@@ -1,51 +0,0 @@-import type { AgentState, ClientMessage, ServerPayload } from "@gentle-dot/protocol";-import type { AgentSupervisor } from "./supervisor.ts";-export interface BridgeClient {- send(payload: ServerPayload): void;-}-export interface BridgeOptions {- dataDir: string;- log?: (line: string) => void;-}-/**- * Translates between protocol v1 clients and the supervised agent: it keeps- * the derived agent state, the pending asks, and the streaming message ids,- * and broadcasts every agent event to all connected clients.- */-export declare class DotBridge {- private readonly clients;- private readonly asks;- private readonly runningTools;- private readonly seenRequestIds;- private readonly sessionDir;- private readonly supervisor;- private readonly options;- private state;- private interrupted;- private nextMessage;- private assistantId;- constructor(supervisor: AgentSupervisor, options: BridgeOptions);- get agentState(): AgentState;- attach(client: BridgeClient): () => void;- handle(client: BridgeClient, message: ClientMessage): Promise<void>;- private dispatch;- private afterConversationChange;- private loadHistory;- private conversationsPayload;- private conversationRef;- private activeRef;- private onAgentEvent;- private onMessageStart;- private onMessageUpdate;- private onMessageEnd;- private onTool;- private onUiRequest;- private resolveAsk;- private clearRun;- private deriveState;- private refreshState;- private alreadySeen;- private broadcast;- private deliver;- private log;-}diff --git a/packages/daemon/src/cli.d.ts b/packages/daemon/src/cli.d.tsdeleted file mode 100644index b798801..0000000--- a/packages/daemon/src/cli.d.ts+++ /dev/null@@ -1,2 +0,0 @@-#!/usr/bin/env node-export {};diff --git a/packages/daemon/src/config.d.ts b/packages/daemon/src/config.d.tsdeleted file mode 100644index ca6786e..0000000--- a/packages/daemon/src/config.d.ts+++ /dev/null@@ -1,12 +0,0 @@-export interface DotConfig {- port: number;- host: string;- dataDir: string;- workspace: string;- uiDir: string;- agentCommand: string;- agentArgs: string[];- allowedOrigins: string[];-}-/** Resolves configuration from environment variables, then `~/.gentle-dot/config.json`, then defaults. */-export declare function loadConfig(env?: NodeJS.ProcessEnv): DotConfig;diff --git a/packages/daemon/src/conversations.d.ts b/packages/daemon/src/conversations.d.tsdeleted file mode 100644index 60ad2a6..0000000--- a/packages/daemon/src/conversations.d.ts+++ /dev/null@@ -1,8 +0,0 @@-import type { ConversationSummary, HistoryMessage } from "@gentle-dot/protocol";-/** Session files under `sessionDir` (and one level of subfolders), newest first. */-export declare function listConversations(sessionDir: string): ConversationSummary[];-export declare function conversationIdOf(sessionDir: string, sessionFile: string): string;-/** Resolves a client-supplied id to a session file inside `sessionDir`, or undefined. */-export declare function resolveConversation(sessionDir: string, id: string): string | undefined;-/** Converts Pi `get_messages` output into display messages; consecutive assistant messages form one turn. */-export declare function historyFromMessages(messages: unknown[]): HistoryMessage[];diff --git a/packages/daemon/src/daemon.d.ts b/packages/daemon/src/daemon.d.tsdeleted file mode 100644index 3debd73..0000000--- a/packages/daemon/src/daemon.d.ts+++ /dev/null@@ -1,29 +0,0 @@-import { DotBridge } from "./bridge.ts";-import { AgentSupervisor } from "./supervisor.ts";-export interface DaemonOptions {- port: number;- host: string;- dataDir: string;- workspace: string;- /** Directory with the built web UI (`index.html`). */- uiDir: string;- agentCommand: string;- agentArgs?: string[];- agentExtraArgs?: string[];- agentEnv?: NodeJS.ProcessEnv;- /** Origins allowed to open the WebSocket, besides the daemon's own and the desktop app's. */- allowedOrigins?: string[];- backoffMs?: number[];- log?: (line: string) => void;-}-export interface DotDaemon {- port: number;- token: string;- url: string;- bridge: DotBridge;- supervisor: AgentSupervisor;- close(): Promise<void>;-}-/** Reads the access token from `<dataDir>/token`, creating a random one (mode 0600) when absent. */-export declare function ensureToken(dataDir: string): string;-export declare function startDaemon(options: DaemonOptions): Promise<DotDaemon>;diff --git a/packages/daemon/src/jsonl.d.ts b/packages/daemon/src/jsonl.d.tsdeleted file mode 100644index 36c2d7c..0000000--- a/packages/daemon/src/jsonl.d.ts+++ /dev/null@@ -1,14 +0,0 @@-/**- * Strict JSONL framing for the Pi RPC protocol: records are split on LF bytes- * only. Node's `readline` is deliberately avoided because it also splits on- * U+2028 and U+2029, which are valid inside JSON strings.- */-export declare class JsonlDecoder {- private pending;- private readonly onRecord;- private readonly onMalformed;- constructor(onRecord: (record: unknown) => void, onMalformed?: (line: string) => void);- push(chunk: Buffer): void;- private emit;-}-export declare function encodeRecord(record: unknown): string;diff --git a/packages/daemon/src/presentation.d.ts b/packages/daemon/src/presentation.d.tsdeleted file mode 100644index b62c910..0000000--- a/packages/daemon/src/presentation.d.ts+++ /dev/null@@ -1,14 +0,0 @@-import type { ActivityKind } from "@gentle-dot/protocol";-/**- * Turns an internal tool call into a neutral activity. Tool names never reach- * the user; only the kind and a short human title do.- */-export declare function describeTool(- toolName: string,- args: unknown,-): {- kind: ActivityKind;- title: string;-};-/** Plain text of a user or assistant message whose content is a string or content blocks. */-export declare function textOf(message: unknown): string;diff --git a/packages/daemon/src/supervisor.d.ts b/packages/daemon/src/supervisor.d.tsdeleted file mode 100644index fedda1c..0000000--- a/packages/daemon/src/supervisor.d.ts+++ /dev/null@@ -1,94 +0,0 @@-/** A record the agent wrote to stdout that is not a command response. */-export type AgentRecord = {- type: string;- [key: string]: unknown;-};-export type RpcResponse = {- type: "response";- id?: string;- command: string;- success: boolean;- data?: unknown;- error?: string;-};-export type SupervisorState = "stopped" | "starting" | "ready" | "restarting";-export type SupervisorEvent =- | AgentRecord- | {- type: "supervisor_state";- state: SupervisorState;- }- | {- type: "interrupted";- };-export interface SupervisorOptions {- /** Executable to run, for example `gentle-shell`. */- command: string;- /** Arguments placed before the RPC arguments (used to run a script with node). */- args?: string[];- /** Arguments placed after the RPC arguments. */- extraArgs?: string[];- cwd: string;- /** Directory for `sessions/` and `state.json`. */- dataDir: string;- env?: NodeJS.ProcessEnv;- /** Respawn delays; the last value repeats. Default 1s, 2s, 4s, 8s, 16s, 30s. */- backoffMs?: number[];- /** Uptime after which the backoff starts over. Default 30s. */- stableMs?: number;- /** Deadline for one command response. Default 5 minutes. */- requestTimeoutMs?: number;- /** Deadline for the agent to answer its first `get_state`. Default 60s. */- startTimeoutMs?: number;- /** Grace period after closing stdin before SIGTERM. Default 5s. */- stopTimeoutMs?: number;- log?: (line: string) => void;-}-/**- * Runs the agent (`gentle-shell --mode rpc`) as a child process, correlates- * commands with responses, forwards session events, and respawns the agent- * after an unexpected exit, reopening the same conversation.- */-export declare class AgentSupervisor {- state: SupervisorState;- busy: boolean;- sessionFile: string | undefined;- sessionId: string | undefined;- model: string | undefined;- private child;- private readonly pending;- private readonly listeners;- private nextId;- private attempts;- private spawnedAt;- private stopping;- private interrupted;- private restartTimer;- private closeWaiters;- private readonly sessionDir;- private readonly stateFile;- private readonly options;- constructor(options: SupervisorOptions);- get pid(): number | undefined;- onEvent(listener: (event: SupervisorEvent) => void): () => void;- /** Spawns the agent and resolves once it answered `get_state`. */- start(): Promise<void>;- /** Sends a command and resolves with its successful response. */- request(command: AgentRecord): Promise<RpcResponse>;- /** Writes a record that has no response, such as `extension_ui_response`. */- send(record: AgentRecord): void;- stop(): Promise<void>;- private spawnAndInitialize;- private spawnChild;- private rawRequest;- private handleRecord;- private handleClose;- private scheduleRestart;- private refreshSession;- private applyState;- private readPersistedSession;- private persistSession;- private setState;- private emit;- private log;-}diff --git a/packages/daemon/src/white-label.d.ts b/packages/daemon/src/white-label.d.tsdeleted file mode 100644index 3c9d98c..0000000--- a/packages/daemon/src/white-label.d.ts+++ /dev/null@@ -1,10 +0,0 @@-/** Internal names that must never reach the user (docs/design.md §5). */-export declare const HIDDEN_NAMES: RegExp[];-/** Rewrites internal names in harness-generated text shown to the user. */-export declare function presentText(text: string): string;-/** Informational notifications are harness chatter; warnings and errors still reach the user. */-export declare function shouldShowToast(level: "info" | "warning" | "error"): boolean;-/** Internal slash commands are not part of the product. */-export declare function isBlockedInput(text: string): boolean;-/** Writes the identity prompt to `<dataDir>/identity.md` and returns the agent arguments that load it. */-export declare function identityArgs(dataDir: string): string[];diff --git a/packages/ui/src/App.tsx b/packages/ui/src/App.tsxindex 0b654ad..30d30fe 100644--- a/packages/ui/src/App.tsx+++ b/packages/ui/src/App.tsx@@ -86,7 +86,7 @@ export function App() {return (<div className="chat chat-web"><div className="status" role="status">- Open the link the assistant printed when it started; it includes your access key.+ This page needs your access key. Open it from the Gentle Dot menu (Open in browser).</div></div>);diff --git a/packages/ui/src/components/AccountsPanel.tsx b/packages/ui/src/components/AccountsPanel.tsxindex 46c07e7..2c19d00 100644--- a/packages/ui/src/components/AccountsPanel.tsx+++ b/packages/ui/src/components/AccountsPanel.tsx@@ -70,7 +70,14 @@ export function AccountsPanel({ auth, send, dispatch, openUrl }: AccountsPanelPr</button>) : null}{flow.done ? (- <button type="button" onClick={() => dispatch({ type: "accounts", open: true })}>+ <button+ type="button"+ onClick={() => {+ setMethod(undefined);+ setFilter("");+ dispatch({ type: "accounts", open: true });+ }}+ >Back to accounts</button>) : null}diff --git a/packages/ui/src/components/ChatSurface.tsx b/packages/ui/src/components/ChatSurface.tsxindex 53c9b3f..06ac038 100644--- a/packages/ui/src/components/ChatSurface.tsx+++ b/packages/ui/src/components/ChatSurface.tsx@@ -23,7 +23,7 @@ const CONTINUE_TEXT = "Continue where you left off.";function statusText(state: DotState): string | undefined {if (state.connection === "unauthorized") {- return "This link is not valid anymore. Please open the link the assistant printed when it started.";+ return "This access key is not valid anymore. Open the page again from the Gentle Dot menu (Open in browser).";}if (state.connection === "closed") return "Reconnecting to the assistant…";if (state.connection === "connecting") return "Connecting…";diff --git a/packages/ui/test/accounts.test.tsx b/packages/ui/test/accounts.test.tsxindex e5237fc..eb4b1fd 100644--- a/packages/ui/test/accounts.test.tsx+++ b/packages/ui/test/accounts.test.tsx@@ -89,6 +89,28 @@ describe("AccountsPanel", () => {],}).auth;+ it("returns to the method choice after a finished sign-in", async () => {+ const dispatch = vi.fn();+ const { rerender } = render(+ <AccountsPanel auth={mixed()} send={vi.fn()} dispatch={dispatch} openUrl={vi.fn()} />,+ );+ await userEvent.click(screen.getByRole("button", { name: /Use an API key/ }));+ let s = reduce({ ...base(), auth: mixed() }, { type: "auth_started", providerId: "openai" });+ s = apply(s, { type: "auth_done", flowId: "f1", providerId: "openai", ok: true });+ rerender(<AccountsPanel auth={s.auth} send={vi.fn()} dispatch={dispatch} openUrl={vi.fn()} />);+ await userEvent.click(screen.getByRole("button", { name: "Back to accounts" }));+ expect(dispatch).toHaveBeenCalledWith({ type: "accounts", open: true });+ rerender(+ <AccountsPanel+ auth={reduce(s, { type: "accounts", open: true }).auth}+ send={vi.fn()}+ dispatch={dispatch}+ openUrl={vi.fn()}+ />,+ );+ expect(screen.getByRole("button", { name: /Use a subscription/ })).toBeInTheDocument();+ });+it("asks for the method first, like Pi's /login", () => {render(<AccountsPanel auth={mixed()} send={vi.fn()} dispatch={vi.fn()} openUrl={vi.fn()} />);expect(screen.getByRole("button", { name: /Use a subscription/ })).toBeInTheDocument();diff --git a/packages/ui/test/components.test.tsx b/packages/ui/test/components.test.tsxindex b97b4c0..2076306 100644--- a/packages/ui/test/components.test.tsx+++ b/packages/ui/test/components.test.tsx@@ -172,7 +172,7 @@ describe("ChatSurface", () => {dismiss={vi.fn()}/>,);- expect(screen.getByRole("status")).toHaveTextContent("open the link the assistant printed");+ expect(screen.getByRole("status")).toHaveTextContent("Open the page again from the Gentle Dot menu");});it("shows notices that can be dismissed", () => {