@lmctl-ai/lmctl 0.1.341 → 0.2.2

package/dist/cli/batch.d.ts

@@ -0,0 +1,2 @@
+import { type CliIo } from './common.js';
+export declare function runBatch(args: string[], io?: CliIo): Promise<number>;

package/dist/cli/busy-evidence.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared "who holds this, and are they alive / how long" evidence for busy/held
+ * errors — the same instinct as the #80 terminal busy/held-evidence, factored
+ * out so the chat busy-now path and terminal.ts do not each re-derive the
+ * live/dead verdict.
+ */
+export type HolderLiveness = 'live' | 'dead' | null;
+export interface BusyHolderEvidence {
+    holder_pid: number | null;
+    holder_liveness: HolderLiveness;
+    /** ISO timestamp the current turn/hold started. */
+    since: string;
+    /** Wall-clock ms since `since` (time the target has been active) — the
+     * "time-since-last-activity" evidence; null when `since` is unparseable. */
+    idle_ms: number | null;
+}
+/** live/dead/null verdict for a holder pid — null means "no pid recorded". */
+export declare function holderLiveness(holderPid: number | null): HolderLiveness;
+export declare function busyHolderEvidence(input: {
+    holderPid: number | null;
+    since: string;
+    nowMs?: number;
+}): BusyHolderEvidence;
+/** Human duration via lmformat, e.g. "0s", "45s", "3m 12s", "2h 5m". */
+export declare function formatElapsed(ms: number): string;
+/** Parenthesised evidence suffix: `(active 3m 12s; holder_pid=123, live)`. */
+export declare function formatBusyEvidence(ev: BusyHolderEvidence): string;

package/dist/cli/chat-cycle.d.ts

@@ -0,0 +1,59 @@
+import type { Dal } from '../db/index.js';
+export declare const CYCLE_FRESH_WINDOW_MS = 60000;
+/**
+ * How many cross-team hops must be SIMULTANEOUSLY IN FLIGHT before a revisit is
+ * treated as a runaway loop rather than a normal exchange.
+ *
+ * WHY THIS IS A HOP COUNT AND NOT A COUNT OF REVISITS. The obvious reading of
+ * the name is "how many times has this target already appeared in the chain",
+ * but that number can never exceed 1: `ancestorChain` walks parent pointers and
+ * breaks on the first node it has already seen, so the chain it returns is
+ * DEDUPLICATED. Gating on `priorTargetEntries.length >= 2` would therefore be
+ * dead code that disables cycle detection entirely.
+ *
+ * Counting repeats over time does not work either: `releaseAgentInflight`
+ * deletes the row when an exchange completes, so a finished hop leaves no trace
+ * here, and the lease forbids two concurrent holds of the same lane. The live
+ * table only ever shows what is in flight RIGHT NOW.
+ *
+ * What that table can tell us is how deep the live cross-team call stack is,
+ * and that is the signal that actually separates the two cases:
+ *
+ *   1 hop  — A is holding B, and B messages A back. One outstanding call: a
+ *            reply, an acknowledgement, a bounded handshake. NOT a loop. This
+ *            is the case that was being blocked (`lmmol → diagramkit → lmmol`,
+ *            a 3-node chain), stalling a real cross-team review.
+ *   2 hops — A is holding B AND B is holding A, and another cross-team call is
+ *            being opened on top. Both parties are now blocked inside each
+ *            other; nothing can unwind. That is a live deadlock, and it is what
+ *            this mechanism exists to stop.
+ *
+ * So: one outstanding hop is allowed, two or more is refused. Raising this
+ * further would let genuinely stuck stacks keep growing, which is the failure
+ * mode the whole check is here to prevent.
+ */
+export declare const CYCLE_MAX_REVISITS = 2;
+export interface ChatCycleNode {
+    teamfile: string;
+    alias: string;
+}
+export interface DetectCrossTeamCycleInput {
+    root: string;
+    sender: ChatCycleNode;
+    receiverTeamfile: string;
+    receiverAlias: string;
+    now: Date;
+}
+export interface DetectCrossTeamCycleResult {
+    stop: boolean;
+    chain: string;
+}
+type ChatCycleDal = Pick<Dal, 'listAgentInflight' | 'clearAgentInflightOlderThan'>;
+export declare function detectCrossTeamCycle(dal: ChatCycleDal, input: DetectCrossTeamCycleInput): DetectCrossTeamCycleResult;
+export declare function deriveRootFromLiveInflight(dal: ChatCycleDal, input: {
+    sender: ChatCycleNode;
+    now: Date;
+}): string | null;
+export declare function agentInflightTtlMsFromEnv(env?: NodeJS.ProcessEnv): number;
+export declare function crossTeamCycleMessage(chain: string): string;
+export {};

package/dist/cli/chat-exec.d.ts

@@ -0,0 +1,83 @@
+import type { ProgressEvent } from '../providers/index.js';
+import type { BundleSession } from '../providers/bundle.js';
+import type { PermissionMode } from '../providers/yolo-contract.js';
+import type { AgentInflightInput } from '../db/index.js';
+import { type CliIo } from './common.js';
+export type AiTeamChatEvent = {
+    kind: 'delta';
+    chunk: string;
+} | {
+    kind: 'progress';
+    alias: string;
+    event: ProgressEvent;
+} | {
+    kind: 'warning';
+    message: string;
+};
+export type AiTeamChatResult = {
+    status: 'ok';
+    replyText: string;
+    wroteDelta: boolean;
+    teamChatLogId: number | null;
+    messageId: string | null;
+    durationMs?: number;
+} | {
+    status: 'stalled';
+    replyText: string;
+    wroteDelta: boolean;
+    teamChatLogId: number | null;
+    messageId: string | null;
+    durationMs?: number;
+} | {
+    status: 'busy';
+    message: string;
+    teamChatLogId: number | null;
+} | {
+    status: 'error';
+    errorKind: 'cycle' | 'provider' | 'target';
+    message: string;
+    teamChatLogId: number | null;
+    messageId: string | null;
+};
+export interface ExecuteAiTeamChatTurnInput {
+    teamfile: string;
+    alias: string;
+    prompt: string;
+    /** Refuse to dispatch if a multi-turn caller's target session changed. */
+    expectedSession?: {
+        provider: string;
+        sessionid: string;
+    };
+    permissionMode: PermissionMode;
+    idleTimeoutMs?: number;
+    rootFlag?: string;
+    env?: NodeJS.ProcessEnv;
+    /** v61: per-message framing for the team_chat_log row — 'batch' when this
+     * turn is one prompt of a `lmctl batch` run; omitted (NULL) otherwise. */
+    messageType?: 'batch';
+    /**
+     * Caller-held in-flight lease (batch bundle mode): the caller
+     * acquired the `agent_inflight` lease once for the whole bundle, so this
+     * turn skips the receiver busy check AND the acquire/release/heartbeat —
+     * they all moved to bundle scope. Instead the turn VERIFIES per prompt
+     * that the caller still holds the lease, matched by lease identity AND
+     * holder pid (the heartbeat call doubles as a lease-CAS touch); a lost
+     * lease fails the turn, aborting the bundle instead of dispatching
+     * unsynchronized. The per-turn chat pointer, tracked_invocation, and
+     * team_chat_log row are unaffected.
+     */
+    heldLease?: {
+        row: AgentInflightInput;
+        leaseId: string;
+    };
+    /**
+     * Caller-held bundle provider session (batch bundle mode): the turn
+     * goes through the already-open provider process. See
+     * src/providers/bundle.ts for the lifecycle contract.
+     */
+    bundleSession?: BundleSession;
+    io: CliIo;
+    onEvent?: (event: AiTeamChatEvent) => void;
+    onAccepted?: (messageId: string) => void;
+}
+export declare function executeAiTeamChatTurn(input: ExecuteAiTeamChatTurnInput): Promise<AiTeamChatResult>;

package/dist/cli/chat-policy.d.ts

@@ -0,0 +1,22 @@
+export interface ChatPolicyTeam {
+    teamfile: string;
+    aliases: readonly string[];
+    leadAlias: string | null;
+}
+export interface ChatPolicyRegistry {
+    teams: readonly ChatPolicyTeam[];
+}
+export interface CanSendInput {
+    rootTeamfile: string;
+    fromTeamfile: string;
+    fromAlias: string;
+    toTeamfile: string;
+    toAlias: string;
+    registry: ChatPolicyRegistry;
+}
+export interface CanSendResult {
+    allowed: boolean;
+    reason: string;
+    outOfPolicy: boolean;
+}
+export declare function canSend(input: CanSendInput): CanSendResult;

package/dist/cli/chat.d.ts

@@ -0,0 +1,23 @@
+import { type CliIo } from './common.js';
+export declare function runChat(args: string[], io?: CliIo): Promise<number>;
+/**
+ * Resolve `--prompt-file` to the prompt text. Reads the file (or stdin for
+ * `-`) as UTF-8 and returns it byte-for-byte EXCEPT for exactly one trailing
+ * newline, which is stripped so `--prompt-file f` matches what the author sees
+ * in the editor (files conventionally end with a newline). A CRLF terminator
+ * counts as that one newline.
+ *
+ * No shell is involved at any point, which is the entire purpose.
+ */
+export declare function resolvePromptInput(promptFile: string, io: CliIo, stdin?: NodeJS.ReadableStream): Promise<string | {
+    error: string;
+}>;
+/**
+ * Parse `--idle-timeout <duration>` per lmctl0 grammar: `<n>(s|m|h|d)`,
+ * a bare integer >= 1000 (raw milliseconds), or `0` (disables the timer —
+ * libraryChat semantics). A bare integer under 1000 is refused (see inline
+ * comment) rather than silently treated as milliseconds — always give an
+ * explicit unit for anything meant as seconds. Returns ms (number), or an
+ * error string the caller surfaces verbatim. Pure.
+ */
+export declare function parseIdleTimeoutMs(value: string): number | string;

package/dist/cli/code-resolver.d.ts

@@ -0,0 +1,8 @@
+import type { Dal, ProjectRow, TeamMemberRow, TeamRow } from '../db/index.js';
+import { type CliIo } from './common.js';
+export interface ProjectResolvingIo extends CliIo {
+    cwd?: string;
+}
+export declare function resolveProject(io: ProjectResolvingIo, dal: Dal, override?: string): ProjectRow | number;
+export declare function resolveTeam(io: ProjectResolvingIo, dal: Dal, project: ProjectRow, override?: string): TeamRow | number;
+export declare function resolveAlias(io: ProjectResolvingIo, dal: Dal, team: TeamRow, override?: string): TeamMemberRow | number;

package/dist/cli/common.d.ts

@@ -0,0 +1,54 @@
+import { type Dal } from '../db/index.js';
+export interface CliWriter {
+    write(chunk: string): unknown;
+}
+export interface CliReader {
+    isTTY?: boolean;
+    setEncoding?(encoding: BufferEncoding): unknown;
+    resume?(): unknown;
+    pause?(): unknown;
+    once(event: 'data', listener: (chunk: string | Buffer) => void): unknown;
+}
+export interface CliIo {
+    stdout: CliWriter;
+    stderr: CliWriter;
+    stdin?: CliReader;
+    dal?: Dal;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface ParsedFlags {
+    positionals: string[];
+    flags: Record<string, string | boolean>;
+    error?: string;
+}
+export declare function withDal<T>(io: CliIo, fn: (dal: Dal) => Promise<T> | T): Promise<T>;
+export declare function parseFlags(args: string[], valueFlags: string[], boolFlags?: string[]): ParsedFlags;
+export declare function flagString(parsed: ParsedFlags, name: string): string | undefined;
+export declare function flagBool(parsed: ParsedFlags, name: string): boolean;
+export declare function writeJson(io: CliIo, value: unknown): void;
+export declare function userError(io: CliIo, message: string): number;
+/** Local wall-clock `HH:MM:SS` for progress-narration lines (batch, and any
+ * command whose stderr narration benefits from a when-did-this-happen marker
+ * without a full date). */
+export declare function hhmmss(): string;
+/** Silence-aware heartbeat for waits that can run long (provider seed spawn,
+ * a multi-minute chat turn, a batch prompt). Writes `renderLine(elapsedSeconds)`
+ * to stderr every `intervalMs`, but SKIPS the tick when `poke()` was called
+ * within the last interval -- streaming events already tell the user work is
+ * happening, so only true silence earns a "still running" line. The timer is
+ * unref'd; callers must `stop()` in a finally. */
+export declare function startSilenceHeartbeat(io: CliIo, renderLine: (elapsedSeconds: number) => string, intervalMs?: number): {
+    poke: () => void;
+    stop: () => void;
+};
+export declare function internalError(io: CliIo, error: unknown): number;
+/** Reads the LMCTL_INVOCATION_ID env var a parent turn's own dispatch set on
+ * this process -- the dispatch-lineage edge `lmctl running --tree` walks.
+ * Malformed/absent -> null (this dispatch is a root, e.g. a human's direct
+ * `lmctl prompt`/`lmctl terminal`). Shared by chat-exec.ts and terminal.ts,
+ * the two places a tracked_invocation row gets created. */
+export declare function parseInvocationIdEnv(value: string | undefined): number | null;
+export declare function installStdoutEpipeGuard(io: CliIo): void;
+/** Test-only: reset the once-flag so install behaviour can be asserted. */
+export declare function _resetStdoutEpipeGuardForTests(): void;

package/dist/cli/context.d.ts

@@ -0,0 +1,12 @@
+import type { Dal, ProjectRow } from '../db/index.js';
+/**
+ * Walk from `cwd` (and each ancestor up to the filesystem root) looking
+ * for a project whose `local_path` is that exact path. Returns the first
+ * hit, or `null` when none match.
+ *
+ * Path comparison is exact-string after `resolve()` normalization on
+ * both the query path and the DB value. On Linux + WSL2 (per § 12 of the
+ * design decisions) we don't normalize case or separators beyond what
+ * `node:path` provides.
+ */
+export declare function resolveActiveProject(cwd: string, dal: Dal): ProjectRow | null;

package/dist/cli/cost.d.ts

@@ -0,0 +1,2 @@
+import { type CliIo } from './common.js';
+export declare function runCost(args: string[], io?: CliIo): Promise<number>;

package/dist/cli/export.d.ts

@@ -0,0 +1,2 @@
+import { type CliIo } from './common.js';
+export declare function runExport(args: string[], io?: CliIo): Promise<number>;

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+import type { CliIo } from './common.js';
+export declare const COMMANDS: Set<string>;
+export declare function runCli(args: string[], io?: CliIo): Promise<number>;