@dinoxx/dinox-cli 2.4.0 → 2.5.2

package/dist/gateway/threadStore.d.ts

@@ -105,20 +105,78 @@ export declare function withdrawQueuedRun(db: AbstractPowerSyncDatabase, input:
 }): Promise<ChatUIMessage>;
 /** Runs left non-terminal by a previous process can never finish; mark them interrupted. */
 export declare function interruptOrphanedRuns(db: Tx, userId: string): Promise<number>;
-/** Agent session bound to a thread, scoped to the thread's current topic. */
+/**
+ * One gateway's agent session on a thread, scoped to the thread's topic when it
+ * started. The thread can switch agents, so every gateway keeps its own session
+ * and remembers the last transcript message it saw.
+ */
 export type GatewaySessionBinding = {
     sessionId: string;
     topicId: string | null;
-    gatewayId: string;
+    /** Newest transcript message the session has seen; null when it has seen nothing of the topic yet. */
+    lastSeenMessageId: string | null;
+    /** Directory the session works in; absent for bindings written before it was recorded. */
+    cwd?: string;
+    /** Written before seen messages were tracked: the session is assumed to be up to date. */
+    legacy?: true;
 };
-export declare function readSessionBinding(db: Tx, threadId: string): Promise<GatewaySessionBinding | null>;
-export declare function writeSessionBinding(db: Tx, threadId: string, binding: GatewaySessionBinding): Promise<void>;
+export declare function readSessionBinding(db: Tx, threadId: string, gatewayId: string): Promise<GatewaySessionBinding | null>;
+/** Replaces this gateway's binding and keeps every other gateway's. */
+export declare function writeSessionBinding(db: AbstractPowerSyncDatabase, threadId: string, gatewayId: string, binding: GatewaySessionBinding): Promise<void>;
+/** Directories this gateway's sessions worked in, most recently used first. */
+export declare function readRecentSessionFolders(db: Tx, gatewayId: string, limit?: number): Promise<string[]>;
+/** The instructions the user wrote for the thread's agent (`c_project.agent_md`); empty when none. */
+export declare function readAgentInstructions(db: Tx, threadId: string): Promise<string>;
 /**
  * The thread's current topic: the latest "new topic" marker the app wrote
  * (`entry_type = 'internal'`, `meta_data.kind = 'context_reset'`). A new topic
- * starts a fresh agent session.
+ * starts a fresh agent session; like the app, it covers rows written after the marker.
+ */
+export declare function readCurrentTopic(db: Tx, threadId: string): Promise<{
+    id: string;
+    createdAt: string | null;
+} | null>;
+/** Marks a reply with the agent session that wrote it (`metadata.gateway`). */
+export declare function withGatewaySession(message: ChatUIMessage, gateway: {
+    gatewayId: string;
+    sessionId: string;
+}): ChatUIMessage;
+/**
+ * Waits until a message exists in the local replica (deleted or not), e.g. the
+ * last message the client saw before sending a turn. False when it has not
+ * synced within the timeout or the wait was aborted.
  */
-export declare function readCurrentTopicId(db: Tx, threadId: string): Promise<string | null>;
+export declare function waitForMessage(db: Tx, messageId: string, options: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<boolean>;
+/** A transcript message reduced to what another agent needs: who said what. */
+export type TranscriptMessage = {
+    id: string;
+    role: 'user' | 'assistant';
+    /** The answering agent's name; null for the user or an unknown agent. */
+    speaker: string | null;
+    text: string;
+    createdAt: string | null;
+};
+/**
+ * The newest transcript messages in a window, oldest first, with how many
+ * matching messages lie before the page. Bounds are exclusive: `since` is a
+ * topic start (by `created_at`, as the app scopes topics), `afterMessageId` and
+ * `beforeMessageId` are transcript positions; an id that no longer exists is no bound.
+ */
+export declare function readTranscriptPage(db: Tx, input: {
+    threadId: string;
+    since?: string | null;
+    afterMessageId?: string | null;
+    beforeMessageId?: string | null;
+    /** Leaves out the turns this agent session answered itself (its replies and their prompts). */
+    excludeSessionId?: string | null;
+    limit: number;
+}): Promise<{
+    messages: TranscriptMessage[];
+    earlier: number;
+}>;
 /** File parts resolve only to resources this user owns with an https storage URL. */
 export declare function resolveTrustedResource(db: Tx, input: {
     resourceId: string;
@@ -141,6 +199,13 @@ export type RobotRegistration = {
     /** Marks the robot as hosted by this installation, for reconciliation. */
     machineId: string;
     agentId?: string;
+    /** Owner-facing settings, synced so the app can show them while the computer is offline. */
+    settings?: RobotSettings;
+};
+export type RobotSettings = {
+    approval: 'ask' | 'auto_read';
+    paused: boolean;
+    dinoxTools: boolean;
 };
 export declare function upsertRobot(db: Tx, input: RobotRegistration): Promise<void>;
 /**

package/dist/gateway/threadStore.js

@@ -319,38 +319,199 @@ export async function interruptOrphanedRuns(db, userId) {
     }
     return rows.length;
 }
-export async function readSessionBinding(db, threadId) {
-    const row = await db.getOptional('SELECT robot_session_id FROM c_thread WHERE id = ? LIMIT 1', [threadId]);
-    const parsed = parseJson(row?.robot_session_id);
-    if (parsed?.v !== 1 || typeof parsed.sessionId !== 'string' || typeof parsed.gatewayId !== 'string')
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function toBinding(value, legacy = false) {
+    if (!isRecord(value) || typeof value.sessionId !== 'string' || !value.sessionId)
         return null;
     return {
-        sessionId: parsed.sessionId,
-        topicId: typeof parsed.topicId === 'string' ? parsed.topicId : null,
-        gatewayId: parsed.gatewayId,
+        sessionId: value.sessionId,
+        topicId: typeof value.topicId === 'string' ? value.topicId : null,
+        lastSeenMessageId: typeof value.lastSeenMessageId === 'string' ? value.lastSeenMessageId : null,
+        ...(typeof value.cwd === 'string' && value.cwd ? { cwd: value.cwd } : {}),
+        ...(legacy ? { legacy: true } : {}),
     };
 }
-export async function writeSessionBinding(db, threadId, binding) {
-    await db.execute('UPDATE c_thread SET robot_session_id = ?, updated_at = ? WHERE id = ?', [
-        safeJson({ v: 1, ...binding }),
-        new Date().toISOString(),
-        threadId,
-    ]);
+/** `c_thread.robot_session_id`: v2 keeps a binding per gateway; v1 held a single one. */
+function parseBindings(raw) {
+    const parsed = parseJson(raw);
+    const bindings = {};
+    if (parsed?.v === 1 && typeof parsed.gatewayId === 'string') {
+        const binding = toBinding(parsed, true);
+        if (binding)
+            bindings[parsed.gatewayId] = binding;
+    }
+    else if (parsed?.v === 2 && isRecord(parsed.sessions)) {
+        for (const [gatewayId, value] of Object.entries(parsed.sessions)) {
+            const binding = toBinding(value);
+            if (binding)
+                bindings[gatewayId] = binding;
+        }
+    }
+    return bindings;
+}
+async function readBindings(db, threadId) {
+    const row = await db.getOptional('SELECT robot_session_id FROM c_thread WHERE id = ? LIMIT 1', [threadId]);
+    return parseBindings(row?.robot_session_id);
+}
+export async function readSessionBinding(db, threadId, gatewayId) {
+    return (await readBindings(db, threadId))[gatewayId] ?? null;
+}
+/** Replaces this gateway's binding and keeps every other gateway's. */
+export async function writeSessionBinding(db, threadId, gatewayId, binding) {
+    const { legacy: _legacy, ...stored } = binding;
+    await withPowerSyncWriteTransaction(db, async (tx) => {
+        const sessions = { ...(await readBindings(tx, threadId)), [gatewayId]: stored };
+        await tx.execute('UPDATE c_thread SET robot_session_id = ?, updated_at = ? WHERE id = ?', [
+            safeJson({ v: 2, sessions }),
+            new Date().toISOString(),
+            threadId,
+        ]);
+    });
+}
+/** Directories this gateway's sessions worked in, most recently used first. */
+export async function readRecentSessionFolders(db, gatewayId, limit = 8) {
+    const rows = await db.getAll(`SELECT robot_session_id FROM c_thread
+     WHERE robot_session_id LIKE ? AND (is_del IS NULL OR is_del = 0)
+     ORDER BY updated_at DESC LIMIT 200`, [`%${gatewayId}%`]);
+    const folders = [];
+    for (const row of rows) {
+        const cwd = parseBindings(row.robot_session_id)[gatewayId]?.cwd;
+        if (cwd && !folders.includes(cwd))
+            folders.push(cwd);
+        if (folders.length >= limit)
+            break;
+    }
+    return folders;
+}
+/** The instructions the user wrote for the thread's agent (`c_project.agent_md`); empty when none. */
+export async function readAgentInstructions(db, threadId) {
+    const row = await db.getOptional(`SELECT p.agent_md FROM c_thread t JOIN c_project p ON p.id = t.project_id
+     WHERE t.id = ? AND (p.is_del IS NULL OR p.is_del = 0) LIMIT 1`, [threadId]);
+    return row?.agent_md?.trim() ?? '';
 }
 /**
  * The thread's current topic: the latest "new topic" marker the app wrote
  * (`entry_type = 'internal'`, `meta_data.kind = 'context_reset'`). A new topic
- * starts a fresh agent session.
+ * starts a fresh agent session; like the app, it covers rows written after the marker.
  */
-export async function readCurrentTopicId(db, threadId) {
-    const rows = await db.getAll(`SELECT id, meta_data FROM c_chat_message
+export async function readCurrentTopic(db, threadId) {
+    // Other markers (e.g. agent switches) share the entry type, so filter by kind in SQL.
+    const row = await db.getOptional(`SELECT id, created_at FROM c_chat_message
      WHERE type = ? AND source_id = ? AND entry_type = ? AND deleted_at IS NULL
-     ORDER BY julianday(created_at) DESC, id DESC LIMIT 20`, [THREAD_CHAT_TYPE, threadId, CONTEXT_RESET_ENTRY_TYPE]);
-    for (const row of rows) {
-        if (parseJson(row.meta_data)?.kind === 'context_reset')
-            return row.id;
+       AND json_extract(meta_data, '$.kind') = 'context_reset'
+     ORDER BY julianday(created_at) DESC, id DESC LIMIT 1`, [THREAD_CHAT_TYPE, threadId, CONTEXT_RESET_ENTRY_TYPE]);
+    return row ? { id: row.id, createdAt: row.created_at } : null;
+}
+/** Marks a reply with the agent session that wrote it (`metadata.gateway`). */
+export function withGatewaySession(message, gateway) {
+    return {
+        ...message,
+        metadata: { ...(message.metadata ?? {}), gateway: { id: gateway.gatewayId, sessionId: gateway.sessionId } },
+    };
+}
+const TAIL_POLL_INTERVAL_MS = 250;
+/**
+ * Waits until a message exists in the local replica (deleted or not), e.g. the
+ * last message the client saw before sending a turn. False when it has not
+ * synced within the timeout or the wait was aborted.
+ */
+export async function waitForMessage(db, messageId, options) {
+    const deadline = Date.now() + options.timeoutMs;
+    for (;;) {
+        const row = await db.getOptional('SELECT id FROM c_chat_message WHERE id = ? LIMIT 1', [messageId]);
+        if (row)
+            return true;
+        if (options.signal?.aborted || Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, TAIL_POLL_INTERVAL_MS));
+    }
+}
+function messageText(message) {
+    const lines = [];
+    for (const part of message?.parts ?? []) {
+        if (part.type === 'text' && typeof part.text === 'string' && part.text.trim())
+            lines.push(part.text.trim());
+        if (part.type === 'file') {
+            const name = part.filename;
+            lines.push(`[attachment: ${typeof name === 'string' && name ? name : String(part.mediaType ?? 'file')}]`);
+        }
     }
-    return null;
+    return lines.join('\n\n');
+}
+/**
+ * The newest transcript messages in a window, oldest first, with how many
+ * matching messages lie before the page. Bounds are exclusive: `since` is a
+ * topic start (by `created_at`, as the app scopes topics), `afterMessageId` and
+ * `beforeMessageId` are transcript positions; an id that no longer exists is no bound.
+ */
+export async function readTranscriptPage(db, input) {
+    const since = input.since ?? null;
+    const after = input.afterMessageId ?? null;
+    const before = input.beforeMessageId ?? null;
+    const ownSession = input.excludeSessionId ?? null;
+    const where = `type = ? AND source_id = ? AND deleted_at IS NULL AND ${MESSAGE_ENTRY_FILTER}
+     AND role IN ('user', 'assistant')
+     AND (? IS NULL OR julianday(created_at) > julianday(?))
+     AND order_index > COALESCE((SELECT order_index FROM c_chat_message WHERE id = ?), order_index - 1)
+     AND order_index < COALESCE((SELECT order_index FROM c_chat_message WHERE id = ?), order_index + 1)
+     AND (? IS NULL OR NOT (
+       COALESCE(json_extract(content, '$.metadata.gateway.sessionId'), '') = ?
+       OR id IN (SELECT parent_id FROM c_chat_message
+                 WHERE type = ? AND source_id = ? AND parent_id IS NOT NULL
+                   AND json_extract(content, '$.metadata.gateway.sessionId') = ?)
+     ))`;
+    const params = [
+        THREAD_CHAT_TYPE,
+        input.threadId,
+        MESSAGE_ENTRY_TYPE,
+        LEGACY_MESSAGE_ENTRY_TYPE,
+        since,
+        since,
+        after,
+        before,
+        ownSession,
+        ownSession,
+        THREAD_CHAT_TYPE,
+        input.threadId,
+        ownSession,
+    ];
+    const [rows, total] = await Promise.all([
+        db.getAll(`SELECT id, role, content, responser_id, created_at FROM c_chat_message WHERE ${where}
+       ORDER BY order_index DESC, created_at DESC, id DESC LIMIT ?`, [...params, input.limit]),
+        db.getOptional(`SELECT COUNT(*) AS count FROM c_chat_message WHERE ${where}`, params),
+    ]);
+    const parsed = rows.reverse().map((row) => {
+        const message = parseJson(row.content);
+        const responserId = message?.metadata?.responserId;
+        return {
+            row,
+            responserId: row.role === 'assistant' ? (typeof responserId === 'string' && responserId) || row.responser_id || null : null,
+            text: messageText(message),
+        };
+    });
+    const names = await readAgentNames(db, parsed.map((item) => item.responserId).filter((id) => Boolean(id)));
+    return {
+        messages: parsed
+            .filter((item) => item.text)
+            .map(({ row, responserId, text }) => ({
+            id: row.id,
+            role: row.role,
+            speaker: responserId ? (names.get(responserId) ?? null) : null,
+            text,
+            createdAt: row.created_at,
+        })),
+        earlier: Math.max(0, Number(total?.count ?? 0) - rows.length),
+    };
+}
+/** Agent (`c_project`) display names by id; unnamed agents are left out. */
+async function readAgentNames(db, ids) {
+    const unique = [...new Set(ids)];
+    if (unique.length === 0)
+        return new Map();
+    const rows = await db.getAll(`SELECT id, name FROM c_project WHERE id IN (${unique.map(() => '?').join(', ')})`, unique);
+    return new Map(rows.filter((row) => row.name?.trim()).map((row) => [row.id, row.name.trim()]));
 }
 /** File parts resolve only to resources this user owns with an https storage URL. */
 export async function resolveTrustedResource(db, input) {
@@ -361,7 +522,13 @@ export async function resolveTrustedResource(db, input) {
     return { url: row.storage_url, name: row.name ?? 'attachment', mediaType: row.mime_type };
 }
 function robotMetaData(input) {
-    return JSON.stringify({ gateway: { machineId: input.machineId, ...(input.agentId ? { agentId: input.agentId } : {}) } });
+    return JSON.stringify({
+        gateway: {
+            machineId: input.machineId,
+            ...(input.agentId ? { agentId: input.agentId } : {}),
+            ...(input.settings ? { settings: input.settings } : {}),
+        },
+    });
 }
 export async function upsertRobot(db, input) {
     const now = new Date().toISOString();

package/dist/gateway/types.d.ts

@@ -3,10 +3,16 @@
  * Claude Code, Codex, ... over ACP) as remote devices the Dinox app can drive.
  *
  * The app sees each gateway as one `dinox.remote-device.v2` device. The agent
- * owns its conversation context (gateway-session mode): each turn sends only
- * the new user message, while Dinox keeps a display/sync copy of the transcript.
+ * owns its conversation context (gateway-session mode): each turn sends the new
+ * user message plus any transcript messages its session has not seen (another
+ * agent answered meanwhile), while Dinox keeps the synced copy of the transcript.
  */
 export type GatewayKind = 'acp' | 'echo';
+/**
+ * When the agent must ask before acting: `ask` every time, or `auto_read`
+ * (reading and searching run without asking; edits and commands still ask).
+ */
+export type GatewayApprovalMode = 'ask' | 'auto_read';
 /** Local-only gateway definition (never synced: it may carry commands and env). */
 export type GatewayDefinition = {
     /** Stable id; also the `c_robot.id` the app binds agents to. */
@@ -20,13 +26,22 @@ export type GatewayDefinition = {
     /** ACP: executable started over stdio, e.g. `hermes` with args `["acp"]`. */
     command?: string;
     args?: string[];
-    /** Working directory handed to the agent's sessions. */
+    /** Working directory for new agent sessions (each session keeps the one it started in). */
     cwd?: string;
+    /**
+     * Directory of sessions bound before sessions recorded their own: the
+     * default directory as it was when it was first changed.
+     */
+    previousCwd?: string;
     /** Extra environment for the agent process (secrets stay on this machine). */
     env?: Record<string, string>;
     enabled: boolean;
     /** Offer the read-only Dinox knowledge tools (MCP) to the agent; default true. */
     dinoxTools?: boolean;
+    /** Default `ask`. */
+    approval?: GatewayApprovalMode;
+    /** Stays online but refuses new turns, so the owner can resume it from the app. */
+    paused?: boolean;
     createdAt: string;
 };
 export type GatewayToolStatus = 'pending' | 'running' | 'completed' | 'failed';
@@ -82,7 +97,11 @@ export type GatewayStopReason = 'end_turn' | 'cancelled' | 'max_tokens' | 'refus
 export type GatewayTurnInput = {
     /** Agent session to continue; absent starts a new one. */
     sessionId: string | null;
+    /** Working directory of the session (a new one starts here; a continued one is loaded with it). */
+    cwd: string;
     prompt: string;
+    /** Prepended to the prompt when the turn starts a new session, e.g. the agent's instructions. */
+    sessionPreamble?: string;
     /** Attachments the user sent with this turn (trusted, https). */
     resources: Array<{
         uri: string;

package/dist/gateway/types.js

@@ -3,7 +3,8 @@
  * Claude Code, Codex, ... over ACP) as remote devices the Dinox app can drive.
  *
  * The app sees each gateway as one `dinox.remote-device.v2` device. The agent
- * owns its conversation context (gateway-session mode): each turn sends only
- * the new user message, while Dinox keeps a display/sync copy of the transcript.
+ * owns its conversation context (gateway-session mode): each turn sends the new
+ * user message plus any transcript messages its session has not seen (another
+ * agent answered meanwhile), while Dinox keeps the synced copy of the transcript.
  */
 export {};

package/dist/gateway/workspaceFolders.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Folders an agent may work in, chosen from the app. The rules keep a remote
+ * choice inside the owner's own files: an existing directory under the home
+ * directory, never the home directory itself, nothing hidden (`~/.ssh`) and
+ * nothing in `~/Library`. Not a security boundary on its own (an agent with a
+ * shell can still `cd`); it keeps a tap from pointing an agent somewhere wrong.
+ */
+export type WorkspaceFolderErrorCode = 'not_found' | 'not_allowed';
+export declare class WorkspaceFolderError extends Error {
+    readonly code: WorkspaceFolderErrorCode;
+    constructor(code: WorkspaceFolderErrorCode, message: string);
+}
+export type WorkspaceFolder = {
+    name: string;
+    path: string;
+    /** Has a `.git` entry: likely a project the user works on. */
+    isProject: boolean;
+};
+/** The folder an agent may work in, resolved to its real path. */
+export declare function resolveWorkspaceFolder(input: string, home?: string): Promise<string>;
+/** `~/Dinox Agents/<agent name>`: a folder of the agent's own, offered as the default choice. */
+export declare function agentHomeFolder(agentName: string, home?: string): string;
+/** Creates the agent's own folder when missing; the only folder the app can create. */
+export declare function ensureAgentHomeFolder(agentName: string, home?: string): Promise<string>;
+/** The visible subfolders of a folder (the home folder included), for browsing. */
+export declare function listWorkspaceFolders(input: string | null | undefined, home?: string): Promise<{
+    path: string;
+    parent: string | null;
+    folders: WorkspaceFolder[];
+    truncated: boolean;
+}>;
+/** Folders worth offering first: the given candidates that exist and are allowed, deduplicated. */
+export declare function existingWorkspaceFolders(candidates: Array<string | null | undefined>, home?: string): Promise<WorkspaceFolder[]>;

package/dist/gateway/workspaceFolders.js

@@ -0,0 +1,129 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+export class WorkspaceFolderError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WorkspaceFolderError';
+    }
+}
+const MAX_FOLDERS = 200;
+/** Home-level folders that hold system data rather than the user's work. */
+const SYSTEM_FOLDERS = new Set(['Library', 'Applications']);
+const SKIPPED_FOLDERS = new Set(['node_modules']);
+const AGENT_HOME_PARENT = 'Dinox Agents';
+async function realHome(home) {
+    return fs.realpath(home).catch(() => path.resolve(home));
+}
+function expandHome(input, home) {
+    if (input === '~')
+        return home;
+    if (input.startsWith('~/'))
+        return path.join(home, input.slice(2));
+    return input;
+}
+/** Segments of `target` below `home`, or null when it is not inside it. */
+function segmentsBelow(home, target) {
+    const relative = path.relative(home, target);
+    if (relative === '')
+        return [];
+    if (relative.startsWith('..') || path.isAbsolute(relative))
+        return null;
+    return relative.split(path.sep);
+}
+function isAllowedBelowHome(segments) {
+    if (segments.some((segment) => segment.startsWith('.')))
+        return false;
+    return !SYSTEM_FOLDERS.has(segments[0] ?? '');
+}
+async function resolveDirectory(input, home) {
+    const expanded = expandHome(input.trim(), home);
+    if (!path.isAbsolute(expanded)) {
+        throw new WorkspaceFolderError('not_allowed', 'Folder must be an absolute path');
+    }
+    // Refused by its name whether or not it exists (`~/.ssh`), so the answer
+    // never depends on what this computer happens to have.
+    const named = segmentsBelow(path.resolve(home), path.resolve(expanded));
+    if (named !== null && !isAllowedBelowHome(named)) {
+        throw new WorkspaceFolderError('not_allowed', 'This folder cannot be used');
+    }
+    let real;
+    try {
+        real = await fs.realpath(expanded);
+    }
+    catch {
+        throw new WorkspaceFolderError('not_found', 'Folder does not exist');
+    }
+    const stat = await fs.stat(real);
+    if (!stat.isDirectory())
+        throw new WorkspaceFolderError('not_found', 'Not a folder');
+    const segments = segmentsBelow(await realHome(home), real);
+    if (segments === null || !isAllowedBelowHome(segments)) {
+        throw new WorkspaceFolderError('not_allowed', 'This folder cannot be used');
+    }
+    return { real, segments };
+}
+/** The folder an agent may work in, resolved to its real path. */
+export async function resolveWorkspaceFolder(input, home = os.homedir()) {
+    const { real, segments } = await resolveDirectory(input, home);
+    if (segments.length === 0) {
+        throw new WorkspaceFolderError('not_allowed', 'Choose a folder inside your home folder');
+    }
+    return real;
+}
+/** `~/Dinox Agents/<agent name>`: a folder of the agent's own, offered as the default choice. */
+export function agentHomeFolder(agentName, home = os.homedir()) {
+    const safeName = agentName.replace(/[\u0000-\u001f\u007f/\\:*?"<>|]/g, '').trim() || 'Agent';
+    return path.join(home, AGENT_HOME_PARENT, safeName.slice(0, 64));
+}
+/** Creates the agent's own folder when missing; the only folder the app can create. */
+export async function ensureAgentHomeFolder(agentName, home = os.homedir()) {
+    const folder = agentHomeFolder(agentName, home);
+    await fs.mkdir(folder, { recursive: true, mode: 0o755 });
+    return resolveWorkspaceFolder(folder, home);
+}
+async function hasGit(folder) {
+    return fs
+        .access(path.join(folder, '.git'))
+        .then(() => true)
+        .catch(() => false);
+}
+/** The visible subfolders of a folder (the home folder included), for browsing. */
+export async function listWorkspaceFolders(input, home = os.homedir()) {
+    const { real, segments } = await resolveDirectory(input?.trim() || home, home);
+    const entries = await fs.readdir(real, { withFileTypes: true });
+    const names = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .filter((name) => !name.startsWith('.') && !SKIPPED_FOLDERS.has(name))
+        .filter((name) => segments.length > 0 || !SYSTEM_FOLDERS.has(name))
+        .sort((a, b) => a.localeCompare(b));
+    const shown = names.slice(0, MAX_FOLDERS);
+    const folders = await Promise.all(shown.map(async (name) => {
+        const folder = path.join(real, name);
+        return { name, path: folder, isProject: await hasGit(folder) };
+    }));
+    return {
+        path: real,
+        parent: segments.length === 0 ? null : path.dirname(real),
+        folders,
+        truncated: names.length > shown.length,
+    };
+}
+/** Folders worth offering first: the given candidates that exist and are allowed, deduplicated. */
+export async function existingWorkspaceFolders(candidates, home = os.homedir()) {
+    const seen = new Set();
+    const folders = [];
+    for (const candidate of candidates) {
+        if (!candidate)
+            continue;
+        const folder = await resolveWorkspaceFolder(candidate, home).catch(() => null);
+        if (!folder || seen.has(folder))
+            continue;
+        seen.add(folder);
+        folders.push({ name: path.basename(folder), path: folder, isProject: await hasGit(folder) });
+    }
+    return folders;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dinoxx/dinox-cli",
-  "version": "2.4.0",
+  "version": "2.5.2",
   "description": "Dinox CLI",
   "main": "dist/dinox.js",
   "scripts": {