@lmctl-ai/lmctl 0.1.341 → 0.2.2

package/dist/providers/types.d.ts

@@ -0,0 +1,154 @@
+export type ProviderName = "claude" | "codex" | "gemini" | "copilot" | "opencode" | "lmplayer" | "qwen" | "agy" | "kimi" | "dsh" | "hermes" | "pi" | "ClaudeMock";
+export interface SessionTokenUsage {
+    inputTokens?: number;
+    cachedInputTokens?: number;
+    cacheWriteInputTokens?: number;
+    outputTokens?: number;
+    reasoningOutputTokens?: number;
+    totalTokens?: number;
+}
+export interface SessionSummary {
+    provider: ProviderName;
+    sessionId: string;
+    slug?: string;
+    cwd: string;
+    createdAt: Date;
+    modifiedAt: Date;
+    model?: string;
+    cliVersion?: string;
+    startCommand?: string;
+    firstUserMessage?: string;
+    lastUserMessage?: string;
+    messageCount: number;
+    filePath: string;
+    filePaths?: string[];
+    totalInputTokens?: number;
+    totalCachedInputTokens?: number;
+    totalCacheWriteInputTokens?: number;
+    totalOutputTokens?: number;
+    totalReasoningOutputTokens?: number;
+    lastInputTokens?: number;
+    lastTokenUsage?: SessionTokenUsage;
+    modelContextWindow?: number;
+}
+export interface SessionDetail extends SessionSummary {
+    /** Native external prompt text, excluding injected context and internal rows.
+     * When present (even empty), authoritative over user-role transcript messages. */
+    userPrompts?: string[];
+    gitBranch?: string;
+    turnStatus?: "in_progress" | "complete" | "aborted";
+    messages: ConversationMessage[];
+}
+export type MessageRole = "user" | "assistant" | "system" | "tool_use" | "tool_result" | "thinking";
+export interface ConversationMessage {
+    role: MessageRole;
+    timestamp: Date;
+    content: string;
+    toolName?: string;
+    toolInput?: string;
+    toolInputData?: Record<string, unknown>;
+    toolCallId?: string;
+    backgroundTaskId?: string;
+    toolDetailedContent?: string;
+    stopReason?: string;
+    model?: string;
+}
+export interface WatchPathInfo {
+    directory: string;
+    filePattern: RegExp;
+}
+export interface WatchTarget {
+    provider: ProviderName;
+    directory: string;
+    recursive: boolean;
+    filePattern?: RegExp;
+}
+export interface SessionProvider {
+    name: ProviderName;
+    discoverSessions(): Promise<SessionSummary[]>;
+    loadSession(sessionId: string): Promise<SessionDetail | null>;
+    resolveSessionPath(sessionId: string): Promise<string | null>;
+    deleteSession(sessionId: string): Promise<boolean>;
+    getWatchPaths?(): WatchPathInfo[];
+}
+export interface DeleteOptions {
+    provider?: ProviderName;
+    force?: boolean;
+    json?: boolean;
+}
+export interface MutationResult {
+    success: boolean;
+    sessionId: string;
+    provider?: ProviderName;
+    filePath: string;
+    error?: string;
+}
+export interface ListOptions {
+    provider?: ProviderName;
+    workspace?: string;
+    limit?: number;
+    from?: string;
+    to?: string;
+    json?: boolean;
+}
+export interface ViewOptions {
+    provider?: ProviderName;
+    detailed?: boolean;
+    noTools?: boolean;
+    noThinking?: boolean;
+    toolDetails?: boolean;
+    json?: boolean;
+}
+export interface ExtractOptions {
+    provider?: ProviderName;
+    detailed?: boolean;
+    last?: number;
+}
+export interface DumpMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+export interface DumpResult {
+    success: boolean;
+    messages: DumpMessage[];
+    error?: string;
+}
+export interface DumpOptions {
+    provider?: ProviderName;
+    format?: "text" | "bundle";
+}
+export type LoadMode = "patch" | "transplant";
+export interface LoadOptions {
+    provider?: ProviderName;
+    force?: boolean;
+    dryRun?: boolean;
+    preserve?: boolean;
+    mode?: LoadMode;
+}
+export interface EditableEntry {
+    role: "user" | "assistant";
+    recordIndex: number;
+    contentPath: string;
+    identityKey: string;
+    content: string;
+}
+export interface SessionBundle {
+    schemaVersion: 2;
+    provider: ProviderName;
+    toolVersion: string;
+    source: {
+        sessionId: string;
+        cwd: string;
+        dumpedAt: string;
+    };
+    raw: {
+        type: "jsonl" | "json";
+        records: string[];
+    };
+    editable: EditableEntry[];
+}
+export interface BundleResult {
+    success: boolean;
+    bundle?: SessionBundle;
+    error?: string;
+}

package/dist/providers/yolo-contract.d.ts

@@ -0,0 +1,131 @@
+/**
+ * YOLO contract — every provider transport spawns its CLI in
+ * full-auto / permission-bypass mode. Hardcoded; not user-configurable.
+ *
+ * Why this is non-negotiable: lmctl drives provider sessions
+ * non-interactively. If the provider asks for a tool-use permission,
+ * there is no human at the prompt and lmctl has no UI for forwarding
+ * the request. The session hangs until the per-tool internal timeout
+ * fires (could be 30+ minutes), with no recovery path.
+ *
+ * The opencode06 incident exposed this concretely: opencode was
+ * spawned without any permission-bypass flag, sent
+ * `session/request_permission` for its first bash tool call, lmctl
+ * silently dropped the request, opencode hung for 42+ minutes. See
+ * `commit 1cc1766` for the safety-net (reply with -32601) and this
+ * module for the upstream fix (force YOLO so the request is never
+ * sent in the first place).
+ *
+ * Users who want permission prompts should use the provider's CLI
+ * directly, not through lmctl. That's a deliberate scope boundary.
+ *
+ * ## Coverage
+ *
+ * Argv-based providers — flag must appear in the spawn argv:
+ *   claude   → --dangerously-skip-permissions       (stream-json transport)
+ *   qwen     → --approval-mode yolo                 (stream-json transport)
+ *   gemini   → -y                                   (acp transport)
+ *   copilot  → --yolo                               (acp transport)
+ *   agy      → --dangerously-skip-permissions       (one-shot print transport)
+ *   lmplayer → --dangerously-skip-permissions       (one-shot run transport)
+ *   opencode → --dangerously-skip-permissions       (acp transport)
+ *
+ * pi (NOT argv-based): pi has no tool-permission prompts by design —
+ * there is no approval UI to hang on, so no bypass flag exists or is
+ * needed. Routed through PROTOCOL_LEVEL_YOLO like codex so
+ * assertYoloFlagPresent documents the stance at every spawn.
+ *
+ * Codex (NOT argv-based): the `codex app-server` JSON-RPC speaks YOLO
+ * via per-call `thread/start` / `thread/resume` params:
+ *   approvalPolicy: "never"
+ *   sandbox:        "danger-full-access"
+ * These are asserted in `codex-app-server.ts` (see `sendCodexPrompt`),
+ * but are NOT covered by `assertYoloFlagPresent` here because the
+ * argv carries no flag — codex's YOLO is wire-protocol-level.
+ */
+/**
+ * Required YOLO flag(s) per argv-based provider. Each entry is a
+ * sequence of consecutive argv tokens (e.g. `["--approval-mode",
+ * "yolo"]`) that must appear in the spawn args for the contract to
+ * hold. Single-token entries (e.g. `["--yolo"]`) just check for the
+ * one token's presence.
+ *
+ * **Note: opencode is NOT here.** Opencode's ACP mode rejects every
+ * permission-bypass argv flag (verified empirically — `--dangerously-
+ * skip-permissions` is a `run`-subcommand-only flag, not recognized
+ * by `opencode acp`). Opencode's YOLO is satisfied via the
+ * `permission: "allow"` key in `<cwd>/.opencode/opencode.json`,
+ * written by `installOpencodeConfig` (see
+ * src/providers/opencode-config.ts). It belongs in the protocol-level
+ * set below, same shape as codex.
+ */
+export declare const YOLO_FLAGS: Record<string, string[]>;
+/**
+ * lmctl-controlled permission mode for a single chat call.
+ *
+ *   - `"yolo"`  — full-auto / permission-bypass (the historical default;
+ *                  what every spawn does without `--permission-mode`).
+ *   - `"plan"`  — provider should refuse tool calls that would write
+ *                  to the workspace, rather than prompt or auto-approve.
+ *
+ * Plan mode is for research / exploration sessions where the agent
+ * should produce a plan only and never modify the workspace. See
+ * `PERMISSION_FLAGS` (below) for the per-provider argv substitution.
+ *
+ * IMPORTANT (gemini caveat): gemini's `--approval-mode plan` only
+ * filters `write_file` by workspace path — an agent can still escape
+ * via `run_shell_command` (e.g. `bash -c 'echo > /tmp/x'`). This is
+ * a known limitation in gemini-cli; a tighter sandbox for plan mode
+ * is tracked as a follow-up. For this layer, plan mode means
+ * "ask the provider for plan-mode behavior" — guarantees depend on
+ * the provider.
+ */
+export type PermissionMode = "plan" | "yolo";
+/**
+ * Per-provider argv tokens for the two permission modes, for the
+ * providers whose permission selection is argv-based. The `yolo`
+ * column mirrors `YOLO_FLAGS` (preserved as the historical default);
+ * the `plan` column carries the substitution applied when the CLI
+ * receives `--permission-mode plan`.
+ *
+ * Verified against the actual provider CLIs:
+ *
+ *   claude :  --dangerously-skip-permissions    vs   --permission-mode plan
+ *   qwen   :  --approval-mode yolo              vs   --approval-mode plan
+ *   gemini :  -y                                vs   --approval-mode plan
+ *
+ * Codex and opencode are not here — they are protocol-/config-level
+ * (see `PROTOCOL_LEVEL_YOLO`). Codex's plan-mode substitution lives in
+ * the `sandbox: "danger-full-access"` → `sandbox: "read-only"` swap in
+ * codex-app-server.ts. Opencode plan mode is not yet wired and
+ * preserves the yolo (config-file) behavior.
+ *
+ * Copilot is not here — its CLI lacks a plan-mode flag in `--acp`
+ * mode (verified). Copilot in plan mode keeps `--yolo` so it doesn't
+ * hang on permission prompts; the limitation is documented in
+ * acp.ts.
+ */
+export declare const PERMISSION_FLAGS: Record<string, Record<PermissionMode, string[]>>;
+/**
+ * Resolve the argv tokens for `provider` under `mode`. Falls back to
+ * the yolo token sequence when no plan-mode entry exists, so the
+ * assertion in `assertYoloFlagPresent` stays meaningful for providers
+ * that do not yet support plan mode.
+ */
+export declare function flagsForPermissionMode(provider: string, mode: PermissionMode): string[] | undefined;
+/**
+ * Defense-in-depth pre-flight: assert that the YOLO flag for
+ * `provider` is present in `args` immediately before `spawn()` is
+ * called. Throws `TransportConnectionError` (and emits an
+ * unconditional debug-log record) on missing flag — catches the
+ * regression class "future refactor accidentally dropped the YOLO
+ * flag from the spawn args."
+ *
+ * Unknown providers (not in `YOLO_FLAGS` or `PROTOCOL_LEVEL_YOLO`)
+ * are treated as a hard error — the contract is global; new providers
+ * must opt in explicitly.
+ *
+ * Codex short-circuits with success — its YOLO is in the JSON-RPC
+ * params and verified separately at the call site.
+ */
+export declare function assertYoloFlagPresent(provider: string, args: readonly string[], mode?: PermissionMode): void;

package/dist/script/adapter.d.ts

@@ -0,0 +1,101 @@
+import { LMScript, type FunctionDoc, type ScriptModule } from './lmscript.js';
+import { type ResolvedMember } from '../cli/target-resolver.js';
+import type { BundleSession } from '../providers/bundle.js';
+import { type CliIo } from '../cli/common.js';
+import { resolveSelfIdentity } from '../cli/self-identity.js';
+import type { AgentInflightInput, TrackedInvocationFinishPatch } from '../db/index.js';
+export { LMScript, LMScriptExit, type FunctionDoc, type ScriptModule } from './lmscript.js';
+export interface BatchHandle {
+    kind?: 'team';
+    id: string;
+    teamfile: string;
+    alias: string;
+    batchfile: string;
+    member: ResolvedMember;
+    promptCount: number;
+    useBundle: boolean;
+    rootId: number | null;
+    rootFinish: TrackedInvocationFinishPatch;
+    heldLease?: {
+        row: AgentInflightInput;
+        leaseId: string;
+    };
+    bundleSession?: BundleSession;
+    heartbeatTimer?: {
+        stop: () => void;
+    };
+    closed: boolean;
+    env: NodeJS.ProcessEnv;
+}
+interface AgentBatchHandle {
+    kind: 'agent';
+    id: string;
+    member: Record<string, any>;
+    sourceMember: Record<string, any>;
+    options: Record<string, any>;
+    closed: boolean;
+    failed: boolean;
+    inFlight: boolean;
+}
+type ManagedBatchHandle = BatchHandle | AgentBatchHandle;
+export declare class ResourceRegistry {
+    private batchHandles;
+    private loggedErrors;
+    registerBatch(handle: ManagedBatchHandle): void;
+    getBatch(id: string): ManagedBatchHandle | undefined;
+    getOpenBatches(): ManagedBatchHandle[];
+    recordError(msg: string): void;
+    getErrors(): string[];
+    hasErrors(): boolean;
+    forceCloseAll(io: CliIo): Promise<void>;
+}
+export declare function bundleAvailable(member: ResolvedMember): Promise<boolean>;
+export declare function releaseBundleLease(io: CliIo, lease: {
+    row: AgentInflightInput;
+    leaseId: string;
+}): Promise<void>;
+export declare function resolveBundleSender(env: NodeJS.ProcessEnv, dal: Parameters<typeof resolveSelfIdentity>[1]): {
+    teamfile: string;
+    alias: string;
+} | null;
+export declare function startBatchRootInvocation(io: CliIo, input: {
+    member: ResolvedMember;
+    batchfile: string;
+    promptCount: number;
+    parentInvocationId: number | null;
+}): Promise<number | null>;
+export declare function finishBatchRootInvocationSync(io: CliIo, id: number, patch: TrackedInvocationFinishPatch, env?: NodeJS.ProcessEnv): void;
+export declare function closeBatchHandle(handle: ManagedBatchHandle, io: CliIo, status?: 'done' | 'error' | 'cancelled', errorDetail?: string): Promise<void>;
+export declare const LMCTL_FUNCTION_DOCS: FunctionDoc[];
+export declare function registerLmctlDocs(engine: LMScript): void;
+export interface BaseEngineOptions {
+    scriptArgs?: string[];
+    io?: CliIo;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Creates a bare, generic LMScript engine configured with the language and standard library.
+ * Free of lmctl-specific host functions or domain bindings.
+ * Suitable as a reusable substrate for any consumer (lmctl, lmbee, custom tools).
+ */
+export declare function createBaseScriptEngine(options?: BaseEngineOptions): LMScript;
+/**
+ * Registers all lmctl host functions onto an LMScript engine instance.
+ */
+export declare function registerLmctlHostFunctions(engine: LMScript, io: CliIo, registry: ResourceRegistry, env?: NodeJS.ProcessEnv): void;
+/**
+ * First-class ScriptModule defining the lmctl automation host extension.
+ */
+export declare const lmctlModule: ScriptModule;
+/**
+ * Registers the lmctl module and its host function documentation onto any LMScript engine.
+ */
+export declare function registerLmctlModule(engine: LMScript, io: CliIo, registry?: ResourceRegistry, env?: NodeJS.ProcessEnv): LMScript;
+/**
+ * Creates and configures an LMScript engine instance pre-wired with the lmctl module.
+ */
+export declare function createLmScriptEngine(io: CliIo, scriptArgs?: string[], registry?: ResourceRegistry, env?: NodeJS.ProcessEnv): LMScript;
+/**
+ * Executes an LMScript script source with full lifecycle and signal guarantees.
+ */
+export declare function runScriptEngine(source: string, scriptArgs: string[], io?: CliIo, env?: NodeJS.ProcessEnv, scriptFile?: string): Promise<number>;

package/dist/script/batch-script.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Test-only comparison implementation of `lmctl batch`.
+ * The production command remains procedural and independent of LMScript.
+ * examples/batchscript.lms exposes this asset through `lmctl script`; an
+ * equality test and shared behavioral suites keep the comparison repeatable.
+ */
+export declare const BATCH_LMS = "# batchscript.lms - Test-only comparison with procedural lmctl batch\n# Arguments: [teamfile, alias, batchfile, flags...]\n\nif (includes(args, \"--help\") || includes(args, \"-h\")) {\n  println(\"usage: lmctl batch <teamfile> <alias> <batchfile> [--legacy] [--single]\");\n  lm_exit(0);\n}\n\nif (len(args) < 3) {\n  lm_error(\"usage: lmctl batch <teamfile> <alias> <batchfile> [--legacy] [--single]\");\n  lm_exit(1);\n}\n\nteamfile = args[0];\nalias = args[1];\nbatchfile = args[2];\nlegacy = false;\nsingle = false;\nfor (flag_index = 3; flag_index < len(args); flag_index = flag_index + 1) {\n  if (args[flag_index] == \"--legacy\") {\n    legacy = true;\n  } else if (args[flag_index] == \"--single\") {\n    single = true;\n  } else {\n    lm_error(\"batch: unexpected argument: \" + args[flag_index]);\n    lm_exit(1);\n  }\n}\n\n# 1. Read prompts\nprompts = lm_read_prompts(batchfile, single);\n\nif (len(prompts) == 0) {\n  lm_error(\"batch: \" + batchfile + \": no prompts found\");\n  lm_exit(1);\n}\n\n# 2. Open batch session\nhandle = lm_batch_open(teamfile, alias, batchfile, {\n  promptCount: len(prompts),\n  legacy: legacy,\n  single: single\n});\n\nif (handle == null) {\n  lm_exit(1);\n}\n\n# 3. Sequential prompt execution\nfor (i = 0; i < len(prompts); i = i + 1) {\n  promptText = prompts[i];\n  res = lm_batch_turn(handle, promptText, i + 1, len(prompts));\n\n  # Output reply or partial reply on stall\n  if (res.reply != null && len(res.reply) > 0) {\n    print(res.reply);\n    print(\"\"); # Blank line separator\n  }\n\n  if (res.status != \"ok\") {\n    lm_batch_close(handle, \"error\", res.error);\n    lm_exit(1);\n  }\n}\n\nlm_batch_close(handle, \"done\");\nlm_exit(0);\n";

package/dist/script/index.d.ts

@@ -0,0 +1,3 @@
+export { LMScript, LMScriptExit, type FunctionDoc, type ScriptModule } from './lmscript.js';
+export { createBaseScriptEngine, createLmScriptEngine, registerLmctlModule, lmctlModule, registerLmctlHostFunctions, registerLmctlDocs, LMCTL_FUNCTION_DOCS, runScriptEngine, ResourceRegistry, type BatchHandle, type BaseEngineOptions, } from './adapter.js';
+export { BATCH_LMS } from './batch-script.js';