@decibelsystems/tools 3.0.0 → 3.1.0

package/dist/pty/sessions.d.ts

@@ -0,0 +1,167 @@
+import { type BrokerPeer } from '../peerBroker.js';
+import { SessionError } from './errors.js';
+import { type TmuxSession } from './tmux.js';
+type NodePty = typeof import('node-pty');
+export declare function loadPty(): Promise<NodePty | null>;
+export type SessionOrigin = 'spawned' | 'adopted' | 'peer';
+/** One row of GET /sessions. Unknown fields are omitted, never null. */
+export interface HostedSession {
+    session_key: string;
+    /** Omitted when the session's cwd is in no registered project. */
+    project_id?: string;
+    origin: SessionOrigin;
+    state: 'live' | 'exited';
+    attachable: boolean;
+    attach_handle?: string;
+    /** Live spawned sessions: the exact argv to attach from a terminal (ADR-0018). */
+    attach_argv?: string[];
+    claude_session_id?: string;
+    peer_id?: string;
+    pid?: number;
+    tty?: string;
+    cwd?: string;
+    branch?: string;
+    issue_label?: string;
+    summary?: string;
+    created?: string;
+}
+export { SessionError };
+export declare function isUuid(v: unknown): v is string;
+export interface StrictProject {
+    id: string;
+    path: string;
+}
+/** Exact id or alias in projects.json, available on this device. Nothing else. */
+export declare function resolveRegisteredProject(projectId: string): StrictProject;
+export declare function isWithin(child: string, parent: string): boolean;
+export interface ListDeps {
+    ownedSessions?: () => Promise<TmuxSession[]>;
+    userSessions?: () => Promise<TmuxSession[]>;
+    ttyMap?: () => Promise<Map<string, string>>;
+    peers?: () => Promise<BrokerPeer[]>;
+    ptyAvailable?: () => Promise<boolean>;
+    projects?: () => StrictProject[];
+}
+/** Every registered project available on this device. */
+export declare function availableProjects(): StrictProject[];
+/**
+ * The registered project a path belongs to: the LONGEST registered path that
+ * contains it, so a checkout nested inside another project belongs to itself.
+ * Undefined when nothing contains it (a session in ~/Documents/GitHub itself,
+ * or in a repo that was never registered).
+ */
+export declare function projectForPath(path: string, projects: StrictProject[]): StrictProject | undefined;
+/**
+ * The session roster. With a project id, that project's sessions only (and an
+ * unregistered id is an error, never a fallback). Without one, every session
+ * on the machine; `project_id` is present where the session resolves to a
+ * registered project and omitted where it does not.
+ */
+export declare function listHostedSessions(projectId?: string, deps?: ListDeps): Promise<HostedSession[]>;
+/**
+ * What an attach token may be minted for: a live spawned session, or a tmux
+ * session that is hosting a claude-peers session. Never an arbitrary tmux
+ * session — the user's other tmux work is not HQ's to open.
+ */
+export declare function resolveAttachable(key: string): Promise<TmuxSession>;
+/**
+ * launchd gives the daemon no login PATH. Find claude by absolute path, then
+ * run it under a login shell so it gets the user's environment.
+ */
+export declare function resolveClaude(): string;
+/**
+ * argv for the pane: `$SHELL -lc 'exec "$0" "$@"' <claude> <args...>`. The
+ * claude path and arguments travel as positional parameters, so nothing is
+ * interpolated into the shell script.
+ */
+export declare function claudeCommand(claudeArgs: string[]): string[];
+export declare function sessionNameFor(projectId: string): string;
+export interface SpawnInput {
+    project_id?: unknown;
+    branch?: unknown;
+    issue_label?: unknown;
+    resume?: unknown;
+}
+/**
+ * Daemon-internal spawn options. Never read from a request body: a caller
+ * that can choose the cwd chooses where `claude` runs.
+ */
+export interface SpawnInternal {
+    /**
+     * Fleet restore (ADR-0018): the cwd the session was recorded in. Claude
+     * keys transcripts by cwd, so a session started in a subdirectory resumes
+     * only from that subdirectory. Must lie inside the registered project.
+     */
+    cwd?: string;
+}
+export interface SpawnResult {
+    session_key: string;
+    claude_session_id: string;
+    attach_argv: string[];
+    /** Set when the dev-channels dialog could not be confirmed (ADR-0018 D4). */
+    needs_attention?: {
+        code: AttentionCode;
+        error: string;
+    };
+}
+/**
+ * The argv for attaching to an owned session from a terminal (ADR-0018). The
+ * absolute tmux path, because launchd's PATH and a login shell's can resolve
+ * different binaries, and a client/server version mismatch refuses to attach.
+ * `=key` is an exact-match target. Not secret.
+ */
+export declare function attachArgv(key: string): string[];
+/**
+ * Apply launch.json's tmux options to the owned server, if it is running.
+ * Spawns apply them too; this covers a daemon restart, where the tmux server
+ * and its sessions outlive the daemon. A missing server or a bad launch.json
+ * is logged, never thrown: the daemon must still boot.
+ */
+export declare function applyTmuxProfile(): Promise<void>;
+/**
+ * Scroll a session's pane through tmux copy-mode, for a client with no
+ * scrollback of its own (HQ's xterm.js pane: tmux draws on the alternate
+ * screen, and the owned server runs with mouse off). Never a keystroke into
+ * the session: copy-mode is tmux's own view.
+ *
+ *   {lines: n<0}    enter copy-mode -e and scroll up |n| lines
+ *   {lines: n>0}    scroll down; -e leaves copy-mode at the bottom by itself
+ *   {cancel: true}  leave copy-mode
+ *
+ * Down and cancel do nothing when the pane is not in copy-mode. HQ's line
+ * counter can overcount past the top of history, and it sends cancel before
+ * the first keystroke after any scroll, so both arrive when nothing is
+ * scrolled. tmux answers "not in a mode" then, which is the no-op.
+ */
+export declare function scrollPane(key: string, frame: {
+    lines?: unknown;
+    cancel?: unknown;
+}): Promise<void>;
+export declare function spawnSession(input: SpawnInput, internal?: SpawnInternal): Promise<SpawnResult>;
+export type AttentionCode = 'DIALOG_UNRECOGNISED' | 'DIALOG_TIMEOUT' | 'CLAUDE_EXITED';
+export declare const DIALOG_TIMEOUT_MS = 15000;
+/** Exact match for the dev-channels warning, cursor on "1.". */
+export declare function isDevChannelsDialog(screen: string): boolean;
+export interface ConfirmDeps {
+    capture?: (key: string) => Promise<string | null>;
+    isDead?: (key: string) => Promise<boolean>;
+    sendEnter?: (key: string) => Promise<boolean>;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    timeoutMs?: number;
+}
+/** Null when confirmed; the attention code and message otherwise. */
+export declare function confirmDevChannels(key: string, deps?: ConfirmDeps): Promise<{
+    code: AttentionCode;
+    error: string;
+} | null>;
+export type ControlAction = 'interrupt' | 'kill' | 'resume';
+export declare function controlSession(key: string, action: unknown): Promise<{
+    ok: true;
+    action: ControlAction;
+    needs_attention?: {
+        code: AttentionCode;
+        error: string;
+    };
+}>;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/pty/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/pty/sessions.ts"],"names":[],"mappings":"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"}