Skip to content

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/.gitignore
index 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.ts
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
index 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 -eu
mkdir -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 &
-fi
exec node /app/packages/daemon/src/cli.ts
diff --git a/docs/design.md b/docs/design.md
index 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.ts
index 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 conne
await 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", async
test("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.ts
deleted file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
deleted file mode 100644
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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", () => {