dsh-plugin-standalone-session 0.0.0-stage → 0.1.0

package/lib/index.js

@@ -0,0 +1,545 @@
+// src/index.ts
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
+
+// src/shared/standalone.ts
+var STANDALONE_DIR_NAME = "dsh-standalone-sessions";
+var SESSION_ID_PREFIX = "session-";
+var REGISTRY_VERSION = 1;
+var REGISTRY_FILE_NAME = "registry.json";
+function emptyRegistry() {
+  return { version: REGISTRY_VERSION, sessions: {} };
+}
+function pathSegments(path) {
+  return path.split(/[\\/]+/).filter((segment) => segment !== "");
+}
+function isStandaloneCwd(cwd) {
+  if (typeof cwd !== "string" || cwd.trim() === "") return false;
+  const segments = pathSegments(cwd);
+  for (let index = 0; index < segments.length - 1; index += 1) {
+    if (segments[index]?.toLowerCase() === STANDALONE_DIR_NAME) return true;
+  }
+  return false;
+}
+function standaloneSessionIdFromCwd(cwd) {
+  if (!isStandaloneCwd(cwd)) return void 0;
+  const segments = pathSegments(cwd ?? "");
+  const last = segments.at(-1);
+  return last === void 0 || last === "" ? void 0 : last;
+}
+function assertSessionId(sessionId) {
+  if (typeof sessionId !== "string" || sessionId === "" || sessionId.length > 200) {
+    throw new Error("invalid standalone session id");
+  }
+  if (!sessionId.startsWith(SESSION_ID_PREFIX)) {
+    throw new Error(`standalone session id must start with "${SESSION_ID_PREFIX}"`);
+  }
+  if (sessionId.includes("/") || sessionId.includes("\\") || sessionId === "." || sessionId === "..") {
+    throw new Error("standalone session id must not contain a path separator");
+  }
+  return sessionId;
+}
+function cloneSessions(sessions) {
+  const copy = {};
+  for (const [id, entry] of Object.entries(sessions)) copy[id] = entry;
+  return copy;
+}
+function normalizeRegistry(value) {
+  if (typeof value !== "object" || value === null) return emptyRegistry();
+  const sessions = value.sessions;
+  if (typeof sessions !== "object" || sessions === null) return emptyRegistry();
+  const normalized = {};
+  for (const [id, raw] of Object.entries(sessions)) {
+    if (typeof raw !== "object" || raw === null) continue;
+    const candidate = raw;
+    let sessionId;
+    try {
+      sessionId = assertSessionId(id);
+    } catch {
+      continue;
+    }
+    if (typeof candidate.cwd !== "string" || !isStandaloneCwd(candidate.cwd)) continue;
+    if (standaloneSessionIdFromCwd(candidate.cwd) !== sessionId) continue;
+    const createdAt = typeof candidate.createdAt === "number" && Number.isFinite(candidate.createdAt) ? candidate.createdAt : Date.now();
+    const entry = {
+      sessionId,
+      cwd: candidate.cwd,
+      standalone: true,
+      createdAt,
+      hadMessage: candidate.hadMessage === true,
+      ...candidate.archived === true ? { archived: true } : {},
+      ...candidate.cleanupFailed === true ? { cleanupFailed: true } : {},
+      ...typeof candidate.cleanupError === "string" ? { cleanupError: candidate.cleanupError } : {},
+      ...typeof candidate.cleanedAt === "number" && Number.isFinite(candidate.cleanedAt) ? { cleanedAt: candidate.cleanedAt } : {}
+    };
+    normalized[sessionId] = entry;
+  }
+  return { version: REGISTRY_VERSION, sessions: normalized };
+}
+function upsertEntry(data, entry) {
+  const previous = data.sessions[entry.sessionId];
+  const merged = {
+    sessionId: entry.sessionId,
+    cwd: entry.cwd,
+    standalone: true,
+    createdAt: previous?.createdAt ?? entry.createdAt,
+    hadMessage: previous?.hadMessage === true || entry.hadMessage === true,
+    ...previous?.archived === true || entry.archived === true ? { archived: true } : {},
+    ...previous?.cleanupFailed === true ? { cleanupFailed: true } : {},
+    ...previous?.cleanupError !== void 0 ? { cleanupError: previous.cleanupError } : {},
+    ...previous?.cleanedAt !== void 0 ? { cleanedAt: previous.cleanedAt } : {}
+  };
+  if (previous !== void 0 && previous.cwd === merged.cwd && previous.hadMessage === merged.hadMessage && previous.archived === merged.archived) {
+    return data;
+  }
+  const sessions = cloneSessions(data.sessions);
+  sessions[entry.sessionId] = merged;
+  return { version: REGISTRY_VERSION, sessions };
+}
+function markHadMessage(data, sessionId) {
+  const previous = data.sessions[sessionId];
+  if (previous === void 0 || previous.hadMessage) return data;
+  const sessions = cloneSessions(data.sessions);
+  sessions[sessionId] = { ...previous, hadMessage: true };
+  return { version: REGISTRY_VERSION, sessions };
+}
+function markArchived(data, sessionId) {
+  const previous = data.sessions[sessionId];
+  if (previous === void 0 || previous.archived === true) return data;
+  const sessions = cloneSessions(data.sessions);
+  sessions[sessionId] = { ...previous, archived: true };
+  return { version: REGISTRY_VERSION, sessions };
+}
+function removeEntry(data, sessionId) {
+  if (data.sessions[sessionId] === void 0) return data;
+  const sessions = cloneSessions(data.sessions);
+  delete sessions[sessionId];
+  return { version: REGISTRY_VERSION, sessions };
+}
+function markCleanupFailed(data, sessionId, message) {
+  const previous = data.sessions[sessionId];
+  if (previous === void 0) return data;
+  const sessions = cloneSessions(data.sessions);
+  sessions[sessionId] = { ...previous, cleanupFailed: true, cleanupError: message };
+  return { version: REGISTRY_VERSION, sessions };
+}
+function listEntries(data) {
+  return Object.keys(data.sessions).sort((left, right) => left.localeCompare(right)).map((id) => data.sessions[id]).filter((entry) => entry !== void 0);
+}
+function cleanupPlan(entry, directoryState) {
+  if (!directoryState.exists) return { action: "remove-entry", reason: "missing" };
+  if (entry.hadMessage) return { action: "keep", reason: "used" };
+  if (!directoryState.empty) return { action: "keep", reason: "not-empty" };
+  return { action: "remove-tree", reason: "never-used" };
+}
+
+// src/host/registry.ts
+import { mkdir, readdir, readFile, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+function prefixedLogger(prefix = "[standalone-session]") {
+  return {
+    info: (message) => console.log(`${prefix} ${message}`),
+    warn: (message) => console.warn(`${prefix} ${message}`)
+  };
+}
+var defaultDirectoryOps = {
+  stat: (path) => stat(path),
+  rm: (path, options) => rm(path, options)
+};
+function errorCode(error) {
+  if (typeof error !== "object" || error === null) return void 0;
+  const code = error.code;
+  return typeof code === "string" ? code : void 0;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function isOwnedSessionDirectory(entry) {
+  if (!isAbsolute(entry.cwd)) return false;
+  if (!isStandaloneCwd(entry.cwd)) return false;
+  if (standaloneSessionIdFromCwd(entry.cwd) !== entry.sessionId) return false;
+  return basename(resolve(entry.cwd)) === entry.sessionId && basename(dirname(resolve(entry.cwd))).toLowerCase() === STANDALONE_DIR_NAME;
+}
+async function cleanupSessionDirectory(entry, ops = defaultDirectoryOps, logger = prefixedLogger()) {
+  if (!isOwnedSessionDirectory(entry)) {
+    const error = `refusing to clean ${JSON.stringify(entry.cwd)}: not this plugin's session directory`;
+    logger.warn(error);
+    return { kind: "failed", error };
+  }
+  const target = resolve(entry.cwd);
+  let exists = false;
+  try {
+    const info = await ops.stat(target);
+    exists = info.isDirectory();
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") {
+      const message = `could not inspect ${target}: ${errorMessage(error)}`;
+      logger.warn(message);
+      return { kind: "failed", error: message };
+    }
+  }
+  let empty = true;
+  if (exists) {
+    try {
+      empty = (await readdir(target)).length === 0;
+    } catch (error) {
+      if (errorCode(error) !== "ENOENT") {
+        const message = `could not list ${target}: ${errorMessage(error)}`;
+        logger.warn(message);
+        return { kind: "failed", error: message };
+      }
+    }
+  }
+  const plan = cleanupPlan(entry, { exists, empty });
+  try {
+    switch (plan.action) {
+      case "remove-entry":
+        logger.info(`session directory already gone: ${target}`);
+        return { kind: "removed" };
+      case "remove-tree":
+        await ops.rm(target, { recursive: true, force: true });
+        logger.info(`removed standalone session directory: ${target}`);
+        return { kind: "removed" };
+      case "keep":
+        logger.info(`retained standalone session directory: ${target}`);
+        return { kind: "retained", reason: plan.reason };
+      default: {
+        const exhaustive = plan;
+        return exhaustive;
+      }
+    }
+  } catch (error) {
+    const message = `failed to clean ${target}: ${errorMessage(error)}`;
+    logger.warn(message);
+    return { kind: "failed", error: message };
+  }
+}
+var DurableStandaloneRegistry = class {
+  rootDir;
+  filePath;
+  data = emptyRegistry();
+  queue = Promise.resolve();
+  loadPromise;
+  loaded = false;
+  logger;
+  ops;
+  /**
+   * @param rootDir - directory holding session directories and the registry file.
+   * @param logger - diagnostic sink.
+   * @param ops - directory operations, injectable for tests.
+   */
+  constructor(rootDir, logger = prefixedLogger(), ops = defaultDirectoryOps) {
+    this.rootDir = resolve(rootDir);
+    this.filePath = join(this.rootDir, REGISTRY_FILE_NAME);
+    this.logger = logger;
+    this.ops = ops;
+  }
+  /** Load the registry once, recovering a corrupt file by moving it aside. */
+  load() {
+    this.loadPromise ??= this.loadOnce();
+    return this.loadPromise;
+  }
+  async loadOnce() {
+    await mkdir(this.rootDir, { recursive: true });
+    try {
+      const text = await readFile(this.filePath, "utf8");
+      this.data = normalizeRegistry(JSON.parse(text));
+      this.loaded = true;
+      return;
+    } catch (error) {
+      if (errorCode(error) !== "ENOENT") {
+        const backup = `${this.filePath}.corrupt-${Date.now()}`;
+        try {
+          await rename(this.filePath, backup);
+          this.logger.warn(`registry was unreadable; moved it to ${backup}: ${errorMessage(error)}`);
+        } catch (moveError) {
+          this.logger.warn(
+            `registry was unreadable and could not be moved aside: ${errorMessage(moveError)}`
+          );
+        }
+      }
+      this.data = emptyRegistry();
+      this.loaded = true;
+    }
+  }
+  /** Current immutable snapshot. */
+  snapshot() {
+    return this.data;
+  }
+  /** All records in stable id order. */
+  list() {
+    return listEntries(this.data);
+  }
+  /** One record, if present. */
+  get(sessionId) {
+    return this.data.sessions[sessionId];
+  }
+  /** Await every queued mutation. */
+  async flush() {
+    await this.queue;
+  }
+  /**
+   * Announce one standalone session (idempotent).
+   * @param summary - Host session summary facts.
+   */
+  async announce(summary) {
+    let sessionId;
+    try {
+      sessionId = assertSessionId(summary.sessionId);
+    } catch {
+      return;
+    }
+    if (typeof summary.cwd !== "string" || !isStandaloneCwd(summary.cwd)) return;
+    const existing = this.data.sessions[sessionId];
+    const entry = {
+      sessionId,
+      cwd: summary.cwd,
+      standalone: true,
+      createdAt: existing?.createdAt ?? Date.now(),
+      hadMessage: existing?.hadMessage === true
+    };
+    await this.mutate((data) => upsertEntry(data, entry));
+  }
+  /**
+   * Mark one session as having carried a user-authored durable message.
+   * @param sessionId - session identity.
+   */
+  async markActivity(sessionId) {
+    if (this.data.sessions[sessionId] === void 0) return;
+    await this.mutate((data) => markHadMessage(data, sessionId));
+  }
+  /**
+   * Mark archived sessions and clean the ones whose archive is visible.
+   * @param archivedSessionIds - the Host's complete archive set.
+   * @returns cleanup outcomes keyed by session.
+   */
+  async reconcileArchived(archivedSessionIds, stillArchived) {
+    const outcomes = /* @__PURE__ */ new Map();
+    if (archivedSessionIds.size === 0) return outcomes;
+    for (const entry of this.list()) {
+      if (!archivedSessionIds.has(entry.sessionId)) continue;
+      if (stillArchived !== void 0 && !stillArchived(entry.sessionId)) continue;
+      await this.mutate((data) => markArchived(data, entry.sessionId));
+      const outcome = await cleanupSessionDirectory(entry, this.ops, this.logger);
+      outcomes.set(entry.sessionId, outcome);
+      if (outcome.kind === "failed") {
+        await this.mutate(
+          (data) => markCleanupFailed(data, entry.sessionId, outcome.error)
+        );
+      } else {
+        await this.mutate((data) => removeEntry(data, entry.sessionId));
+      }
+    }
+    return outcomes;
+  }
+  /**
+   * Remove old empty session directories that neither the registry nor the
+   * live session store references. These are the residue of a failed create or
+   * a crash between mkdir and the session announcement.
+   * @param liveSessionIds - identities the Host currently holds.
+   * @param minimumAgeMs - only directories older than this are eligible.
+   * @returns identities whose directory was removed.
+   */
+  async sweepOrphanDirectories(liveSessionIds, minimumAgeMs = 6e4) {
+    let names;
+    try {
+      names = await readdir(this.rootDir);
+    } catch (error) {
+      this.logger.warn(`could not list the standalone root: ${errorMessage(error)}`);
+      return [];
+    }
+    const removed = [];
+    const now = Date.now();
+    for (const name2 of names) {
+      if (!name2.startsWith("session-")) continue;
+      if (this.data.sessions[name2] !== void 0) continue;
+      if (liveSessionIds.has(name2)) continue;
+      const target = join(this.rootDir, name2);
+      try {
+        const info = await stat(target);
+        if (!info.isDirectory()) continue;
+        if (now - info.mtimeMs < minimumAgeMs) continue;
+        if ((await readdir(target)).length > 0) continue;
+        await rmdir(target);
+        removed.push(name2);
+        this.logger.info(`removed orphan standalone session directory: ${target}`);
+      } catch (error) {
+        if (errorCode(error) !== "ENOENT") {
+          this.logger.warn(`could not reclaim orphan ${target}: ${errorMessage(error)}`);
+        }
+      }
+    }
+    return removed;
+  }
+  /**
+   * Apply one pure mutation and persist it when the reference changed.
+   * @param mutator - pure registry transform.
+   */
+  async mutate(mutator) {
+    const run = async () => {
+      if (!this.loaded) await this.load();
+      const next = mutator(this.data);
+      if (next === this.data) return;
+      this.data = next;
+      await this.write();
+    };
+    const pending = this.queue.then(run, run);
+    this.queue = pending.then(
+      () => void 0,
+      () => void 0
+    );
+    await pending;
+  }
+  /** Atomically replace the registry file. */
+  async write() {
+    const temporary = `${this.filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const body = `${JSON.stringify(this.data, null, 2)}
+`;
+    try {
+      await writeFile(temporary, body, "utf8");
+      await rename(temporary, this.filePath);
+    } catch (error) {
+      await rm(temporary, { force: true }).catch(() => void 0);
+      this.logger.warn(`could not persist the standalone registry: ${errorMessage(error)}`);
+      throw error;
+    }
+  }
+};
+
+// src/index.ts
+var name = "standalone-session";
+var SWEEP_INTERVAL_MS = 2e3;
+var FIRST_SWEEP_DELAY_MS = 1500;
+function readProperty(value, key) {
+  if (typeof value !== "object" || value === null) return void 0;
+  try {
+    return value[key];
+  } catch {
+    return void 0;
+  }
+}
+function resolveStandaloneRoot(home = homedir()) {
+  return join2(home, ".dsh", STANDALONE_DIR_NAME);
+}
+function resolveWorkspaceRegistry(ctx) {
+  const candidates = [ctx.root?.get?.("workspaceRegistry"), ctx.get("workspaceRegistry")];
+  for (const candidate of candidates) {
+    if (candidate !== void 0 && candidate !== null) return candidate;
+  }
+  return void 0;
+}
+function collectLiveSessionIds(ctx) {
+  const ids = /* @__PURE__ */ new Set();
+  const store = ctx.get("sessions");
+  const list = readProperty(store, "list");
+  if (typeof list !== "function") return ids;
+  let sessions;
+  try {
+    sessions = list.call(store);
+  } catch {
+    return ids;
+  }
+  if (!Array.isArray(sessions)) return ids;
+  for (const session of sessions) {
+    const id = readProperty(session, "id") ?? readProperty(readProperty(session, "header"), "id");
+    if (typeof id === "string") ids.add(id);
+  }
+  return ids;
+}
+function readArchivedIds(registry) {
+  let value;
+  try {
+    value = readProperty(registry, "archivedSessionIds");
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+  if (!Array.isArray(value)) return /* @__PURE__ */ new Set();
+  return new Set(value.filter((id) => typeof id === "string"));
+}
+function apply(ctx) {
+  const baseLogger = prefixedLogger();
+  const logger = {
+    info: (message) => {
+      const write = ctx.logger?.info;
+      if (write === void 0) baseLogger.info(message);
+      else write.call(ctx.logger, message);
+    },
+    warn: (message) => {
+      const write = ctx.logger?.warn;
+      if (write === void 0) baseLogger.warn(message);
+      else write.call(ctx.logger, message);
+    }
+  };
+  const root = resolveStandaloneRoot();
+  const registry = new DurableStandaloneRegistry(root, logger);
+  logger.info(`standalone session root: ${root}`);
+  let disposed = false;
+  let sweeping = false;
+  const sweep = async () => {
+    if (disposed || sweeping) return;
+    sweeping = true;
+    try {
+      const workspaceRegistry = resolveWorkspaceRegistry(ctx);
+      if (workspaceRegistry !== void 0) {
+        const outcomes = await registry.reconcileArchived(
+          readArchivedIds(workspaceRegistry),
+          (sessionId) => readArchivedIds(workspaceRegistry).has(sessionId)
+        );
+        for (const [sessionId, outcome] of outcomes) {
+          if (outcome.kind === "failed") {
+            logger.warn(`cleanup for ${sessionId} will be retried: ${outcome.error}`);
+          }
+        }
+      } else {
+        logger.warn("workspace registry is unavailable; archive cleanup is deferred");
+      }
+      await registry.sweepOrphanDirectories(collectLiveSessionIds(ctx));
+    } catch (error) {
+      logger.warn(`cleanup sweep failed: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      sweeping = false;
+    }
+  };
+  const ready = registry.load().catch((error) => {
+    logger.warn(`registry load failed: ${error instanceof Error ? error.message : String(error)}`);
+  });
+  ctx.on("api-session/added", (summary) => {
+    const sessionId = summary?.sessionId;
+    const cwd = summary?.cwd;
+    if (typeof sessionId !== "string" || typeof cwd !== "string") return;
+    if (!isStandaloneCwd(cwd)) return;
+    logger.info(`observed standalone session ${sessionId}`);
+    void ready.then(() => registry.announce({ sessionId, cwd, blank: summary.blank })).catch((error) => {
+      logger.warn(
+        `could not record ${sessionId}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    });
+  });
+  ctx.on("api-session/activity", (sessionId) => {
+    if (typeof sessionId !== "string") return;
+    void ready.then(() => registry.markActivity(sessionId)).catch((error) => {
+      logger.warn(
+        `could not mark activity: ${error instanceof Error ? error.message : String(error)}`
+      );
+    });
+  });
+  ctx.effect(() => {
+    disposed = false;
+    const first = setTimeout(() => {
+      void ready.then(sweep);
+    }, FIRST_SWEEP_DELAY_MS);
+    const timer = setInterval(() => {
+      void ready.then(sweep);
+    }, SWEEP_INTERVAL_MS);
+    return () => {
+      disposed = true;
+      clearTimeout(first);
+      clearInterval(timer);
+    };
+  }, "standalone-session: archive cleanup");
+}
+export {
+  apply,
+  name,
+  resolveStandaloneRoot
+};

package/lib/types/client/actions.d.ts

@@ -0,0 +1,40 @@
+import type { ClientContext, Translate } from './dsh.js';
+/** Host home, or undefined while the connection has not delivered it. */
+export declare function hostHome(ctx: ClientContext): string | undefined;
+/**
+ * Create a standalone session without navigating. The launcher owns navigation
+ * so it can decline to steal focus after the user has already moved on.
+ * @param ctx - client root context.
+ * @param t - localized copy.
+ * @returns the created session id.
+ */
+export declare function createStandaloneSessionId(ctx: ClientContext, t: Translate): Promise<string>;
+/**
+ * Create a standalone session and open its native conversation.
+ * @param ctx - client root context.
+ * @param t - localized copy.
+ * @returns the created session id.
+ */
+export declare function startStandalone(ctx: ClientContext, t: Translate): Promise<string>;
+/**
+ * Open the existing management panel through the public layout service.
+ * @param ctx - client root context.
+ * @param t - localized copy.
+ */
+export declare function openManagementPanel(ctx: ClientContext, t: Translate): void;
+/**
+ * Rename through the native Session face, which updates the title projection.
+ * @param ctx - client root context.
+ * @param sessionId - target session.
+ * @param title - user-entered title.
+ */
+export declare function renameStandalone(ctx: ClientContext, sessionId: string, title: string): Promise<void>;
+/**
+ * Delete through DSH's native archive. The host half observes the archive set
+ * and performs the directory cleanup; DSH exposes no physical session delete.
+ * @param ctx - client root context.
+ * @param sessionId - target session.
+ */
+export declare function archiveStandalone(ctx: ClientContext, sessionId: string): Promise<void>;
+/** Human-readable error text. */
+export declare function messageOf(error: unknown): string;

package/lib/types/client/adapters.d.ts

@@ -0,0 +1,9 @@
+import type { ClientContext, Translate } from './dsh.js';
+/**
+ * Install the composer adapter for as long as the composer slot declaration
+ * lives.
+ * @param ctx - client root context.
+ * @param t - localized copy for the unlocked placeholder.
+ * @returns a disposer restoring every wrapped entry.
+ */
+export declare function patchComposer(ctx: ClientContext, t: Translate): () => void;

package/lib/types/client/components.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Browser components: the dedicated Standalone Sessions panel, the sidebar
+ * entry/action, the native-row badge decorations, the hero badge and the toast.
+ *
+ * The designer constraint is deliberately narrow: this plugin never renders a
+ * chat surface. Opening a row navigates to the native Conversation, and rename
+ * and delete call the native Session/Workspace controllers.
+ */
+import { type ReactElement } from 'react';
+import type { ClientContext, Translate } from './dsh.js';
+interface LocalizedProps {
+    readonly t?: Translate;
+}
+/** Small chat-with-spark mark used by the command and sidebar entry. */
+export declare function StandaloneIcon({ size, active, }: {
+    readonly size?: number;
+    readonly active?: boolean;
+}): ReactElement;
+/** Launcher glyph: a chat mark with a plus badge. */
+export declare function createLauncherEntryIcon(): ({ size, active, }: {
+    readonly size?: number;
+    readonly active?: boolean;
+}) => ReactElement;
+/** Sidebar footer action that opens the management panel. */
+export declare function createManageFooterAction(ctx: ClientContext): ({ wide, t, }: {
+    readonly wide?: boolean;
+} & LocalizedProps) => ReactElement;
+/**
+ * Launcher main panel. Selecting the sidebar row mounts this component, which
+ * creates (or reuses a blank) standalone session and then opens its native
+ * conversation. A real row click must have armed it; a layout restore without
+ * a gesture gets an explicit CTA instead of a silent session.
+ */
+export declare function createStandaloneLauncher(ctx: ClientContext): (props: LocalizedProps) => ReactElement;
+/** Badge in the native New Session hero options row. */
+export declare function createHeroBadge(ctx: ClientContext): ({ sessionId, t, }: {
+    readonly sessionId?: string;
+} & LocalizedProps) => ReactElement | null;
+/** Tiny leading mark on a native Ungrouped session row. */
+export declare function createRowLeading(ctx: ClientContext): ({ sessionId, t, }: {
+    readonly sessionId?: string;
+} & LocalizedProps) => ReactElement | null;
+/** Full badge line in the native session row hover card. */
+export declare function createRowHover(ctx: ClientContext): ({ sessionId, t, }: {
+    readonly sessionId?: string;
+} & LocalizedProps) => ReactElement | null;
+/** Frame-wide toast for creation and cleanup-adjacent failures. */
+export declare function StandaloneToast(): ReactElement | null;
+/**
+ * Factory for the keyed `main` panel.
+ * @param ctx - client root context.
+ * @returns the panel component.
+ */
+export declare function createStandalonePanel(ctx: ClientContext): (props: LocalizedProps) => ReactElement;
+export {};

package/lib/types/client/create.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The one browser-side creation path. Kept dependency-injected so the failure
+ * branch is unit-tested without a DSH runtime.
+ */
+import { type UuidSource } from '../shared/standalone.js';
+/** Injected collaborators for {@link createStandaloneSession}. */
+export interface StandaloneCreateDeps {
+    /** Host user home, from `ctx.remote.$host.home`. */
+    readonly home: string | undefined;
+    /** Localized message used when the host home is unavailable. */
+    readonly noHomeMessage: string;
+    /** Session Controller create. */
+    create(options: {
+        cwd: string;
+        sessionId: string;
+    }): Promise<string>;
+    /** Optional navigation: show the created session's conversation. */
+    open?(sessionId: string): void;
+    readonly randomUuid?: UuidSource;
+}
+/** Absolute POSIX or Windows path check without importing `node:path`. */
+export declare function isAbsoluteHostPath(path: string): boolean;
+/**
+ * Create a standalone session with a durable marker cwd.
+ *
+ * Failure semantics: a throw from `create` propagates before `open`, so no
+ * conversation is selected for a session that was never created. A throw from
+ * `open` also propagates; the session itself remains valid and is listed by the
+ * panel, which is better than deleting a session the Host already committed.
+ * @param deps - injected host home, create, and optional navigation.
+ * @returns the session identity returned by the Session Controller.
+ */
+export declare function createStandaloneSession(deps: StandaloneCreateDeps): Promise<string>;