@locusai/locus-gateway 0.22.13

package/dist/index.js

@@ -0,0 +1,550 @@
+// src/commands.ts
+var COMMAND_REGISTRY = {
+  run: { cliArgs: ["run"], streaming: true },
+  status: { cliArgs: ["status"], streaming: false },
+  issues: { cliArgs: ["issue", "list"], streaming: false },
+  issue: { cliArgs: ["issue", "show"], streaming: false },
+  sprint: { cliArgs: ["sprint"], streaming: false },
+  plan: { cliArgs: ["plan"], streaming: true },
+  review: { cliArgs: ["review"], streaming: true },
+  iterate: { cliArgs: ["iterate"], streaming: true },
+  discuss: {
+    cliArgs: ["discuss"],
+    streaming: true,
+    requiresArgs: `Please provide a discussion topic.
+
+Example: /discuss Should we use Redis or in-memory caching?`
+  },
+  exec: {
+    cliArgs: ["exec"],
+    streaming: true,
+    requiresArgs: `Please provide a prompt.
+
+Example: /exec Add error handling to the API`
+  },
+  logs: { cliArgs: ["logs"], streaming: false },
+  config: { cliArgs: ["config"], streaming: false },
+  artifacts: { cliArgs: ["artifacts"], streaming: false }
+};
+var STREAMING_COMMANDS = new Set(Object.entries(COMMAND_REGISTRY).filter(([, def]) => def.streaming).map(([name]) => name));
+function getCommandDefinition(command) {
+  return COMMAND_REGISTRY[command] ?? null;
+}
+// src/executor.ts
+import { exec as execCb } from "node:child_process";
+import { promisify } from "node:util";
+
+// ../sdk/dist/index.js
+import { spawn, spawnSync } from "node:child_process";
+function invokeLocusStream(args, cwd) {
+  return spawn("locus", args, {
+    cwd: cwd ?? process.cwd(),
+    stdio: ["ignore", "pipe", "pipe"],
+    env: process.env,
+    shell: false
+  });
+}
+var colorEnabled = () => process.stderr.isTTY === true && process.env.NO_COLOR === undefined;
+var wrap = (open, close) => (text) => colorEnabled() ? `${open}${text}${close}` : text;
+var bold = wrap("\x1B[1m", "\x1B[22m");
+var dim = wrap("\x1B[2m", "\x1B[22m");
+var red = wrap("\x1B[31m", "\x1B[39m");
+var yellow = wrap("\x1B[33m", "\x1B[39m");
+var cyan = wrap("\x1B[36m", "\x1B[39m");
+var gray = wrap("\x1B[90m", "\x1B[39m");
+function formatData(data) {
+  if (!data || Object.keys(data).length === 0)
+    return "";
+  return ` ${dim(JSON.stringify(data))}`;
+}
+function createLogger(name) {
+  const prefix = dim(`[${name}]`);
+  return {
+    info(msg, data) {
+      process.stderr.write(`${bold(cyan("●"))} ${prefix} ${msg}${formatData(data)}
+`);
+    },
+    warn(msg, data) {
+      process.stderr.write(`${bold(yellow("⚠"))}  ${prefix} ${yellow(msg)}${formatData(data)}
+`);
+    },
+    error(msg, data) {
+      process.stderr.write(`${bold(red("✗"))} ${prefix} ${red(msg)}${formatData(data)}
+`);
+    },
+    debug(msg, data) {
+      if (!process.env.LOCUS_DEBUG)
+        return;
+      process.stderr.write(`${gray("⋯")} ${prefix} ${gray(msg)}${formatData(data)}
+`);
+    }
+  };
+}
+
+// src/executor.ts
+var exec = promisify(execCb);
+var STREAM_UPDATE_INTERVAL = 2000;
+
+class CommandExecutor {
+  tracker;
+  constructor(tracker) {
+    this.tracker = tracker;
+  }
+  getTracker() {
+    return this.tracker;
+  }
+  async executeLocusCommand(sessionId, command, args, callbacks) {
+    const definition = getCommandDefinition(command);
+    if (!definition) {
+      return {
+        text: `Unknown command: /${command}`,
+        format: "plain",
+        exitCode: 1
+      };
+    }
+    if (definition.requiresArgs && args.length === 0) {
+      return {
+        text: definition.requiresArgs,
+        format: "plain",
+        exitCode: 1
+      };
+    }
+    const conflict = this.tracker.checkExclusiveConflict(sessionId, command);
+    if (conflict) {
+      return {
+        text: formatConflictText(command, conflict),
+        format: "plain",
+        exitCode: 1
+      };
+    }
+    const fullArgs = [...definition.cliArgs, ...args];
+    if (definition.streaming && callbacks) {
+      return this.executeStreaming(sessionId, command, args, fullArgs, callbacks);
+    }
+    return this.executeBuffered(sessionId, command, args, fullArgs);
+  }
+  async executeGit(sessionId, command, args, gitArgs) {
+    const conflict = this.tracker.checkExclusiveConflict(sessionId, command);
+    if (conflict) {
+      return {
+        text: formatConflictText(command, conflict),
+        format: "plain",
+        exitCode: 1
+      };
+    }
+    const trackingId = this.tracker.track(sessionId, command, args);
+    try {
+      const { stdout } = await exec(`git ${gitArgs}`, { cwd: process.cwd() });
+      return {
+        text: stdout,
+        format: "plain",
+        exitCode: 0
+      };
+    } catch (error) {
+      const errStr = String(error);
+      return {
+        text: errStr,
+        format: "plain",
+        exitCode: 1
+      };
+    } finally {
+      this.tracker.untrack(sessionId, trackingId);
+    }
+  }
+  async executeStreaming(sessionId, command, args, fullArgs, callbacks) {
+    const child = invokeLocusStream(fullArgs);
+    const trackingId = this.tracker.track(sessionId, command, args, child);
+    let output = "";
+    let lastUpdateTime = 0;
+    let updateTimer = null;
+    let messageId = "";
+    const displayCmd = `locus ${fullArgs.join(" ")}`;
+    const startResult = await callbacks.onStart(formatStreamingText(displayCmd, "", false));
+    if (startResult)
+      messageId = startResult;
+    const pushUpdate = async () => {
+      const now = Date.now();
+      if (now - lastUpdateTime < STREAM_UPDATE_INTERVAL)
+        return;
+      lastUpdateTime = now;
+      try {
+        await callbacks.onUpdate(messageId, formatStreamingText(displayCmd, output, false));
+      } catch {}
+    };
+    child.stdout?.on("data", (chunk) => {
+      output += chunk.toString();
+      if (updateTimer)
+        clearTimeout(updateTimer);
+      updateTimer = setTimeout(pushUpdate, STREAM_UPDATE_INTERVAL);
+    });
+    child.stderr?.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    return new Promise((resolve) => {
+      child.on("close", async (exitCode) => {
+        this.tracker.untrack(sessionId, trackingId);
+        if (updateTimer)
+          clearTimeout(updateTimer);
+        const code = exitCode ?? 0;
+        await callbacks.onComplete(messageId, formatStreamingText(displayCmd, output, true), code);
+        resolve({
+          text: output,
+          format: "plain",
+          streaming: true,
+          exitCode: code
+        });
+      });
+    });
+  }
+  async executeBuffered(sessionId, command, args, fullArgs) {
+    const child = invokeLocusStream(fullArgs);
+    const trackingId = this.tracker.track(sessionId, command, args, child);
+    let output = "";
+    child.stdout?.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    return new Promise((resolve) => {
+      child.on("close", (exitCode) => {
+        this.tracker.untrack(sessionId, trackingId);
+        const code = exitCode ?? 0;
+        resolve({
+          text: output,
+          format: "plain",
+          exitCode: code
+        });
+      });
+    });
+  }
+}
+function formatConflictText(blockedCommand, conflict) {
+  const running = conflict.runningCommand;
+  const runningLabel = `/${running.command}${running.args.length ? ` ${running.args.join(" ")}` : ""}`;
+  return `/${blockedCommand} cannot start — ${runningLabel} is already running.
+
+Send /cancel to abort it, or wait for it to finish.`;
+}
+function formatStreamingText(command, output, isComplete) {
+  const status = isComplete ? "[DONE]" : "[RUNNING]";
+  const header = `${status} ${command}`;
+  if (!output.trim()) {
+    return isComplete ? `${header}
+
+Completed.` : `${header}
+
+Running...
+
+Send /cancel to abort`;
+  }
+  const lines = output.trim().split(`
+`);
+  const lastLines = lines.slice(-30).join(`
+`);
+  const hint = isComplete ? "" : `
+
+Send /cancel to abort`;
+  return `${header}
+
+${lastLines}${hint}`;
+}
+// src/formatter.ts
+function bestFormat(capabilities) {
+  if (capabilities.supportsHTML)
+    return "html";
+  if (capabilities.supportsMarkdown)
+    return "markdown";
+  return "plain";
+}
+function splitMessage(text, maxLength) {
+  if (text.length <= maxLength)
+    return [text];
+  const chunks = [];
+  let remaining = text;
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLength) {
+      chunks.push(remaining);
+      break;
+    }
+    let splitIdx = remaining.lastIndexOf(`
+`, maxLength);
+    if (splitIdx === -1 || splitIdx < maxLength / 2) {
+      splitIdx = maxLength;
+    }
+    chunks.push(remaining.slice(0, splitIdx));
+    remaining = remaining.slice(splitIdx);
+  }
+  return chunks;
+}
+function truncate(text, maxLength) {
+  if (text.length <= maxLength)
+    return text;
+  return `${text.slice(0, maxLength - 20)}
+
+... (truncated)`;
+}
+// src/router.ts
+class CommandRouter {
+  prefix;
+  constructor(prefix = "/") {
+    this.prefix = prefix;
+  }
+  parse(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith(this.prefix)) {
+      return { type: "freetext", text: trimmed };
+    }
+    const withoutPrefix = trimmed.slice(this.prefix.length);
+    const parts = withoutPrefix.split(/\s+/);
+    const rawCommand = parts[0] ?? "";
+    const command = rawCommand.replace(/@\S+$/, "").toLowerCase();
+    if (!command) {
+      return { type: "freetext", text: trimmed };
+    }
+    const args = parts.slice(1);
+    return {
+      type: "command",
+      command,
+      args,
+      raw: trimmed
+    };
+  }
+}
+
+// src/tracker.ts
+var WORKSPACE_EXCLUSIVE = new Set(["run", "plan", "iterate", "exec"]);
+var GIT_EXCLUSIVE = new Set(["stage", "commit", "checkout", "stash", "pr"]);
+function getExclusivityGroup(command) {
+  if (WORKSPACE_EXCLUSIVE.has(command))
+    return "workspace";
+  if (GIT_EXCLUSIVE.has(command))
+    return "git";
+  return null;
+}
+var nextId = 1;
+
+class CommandTracker {
+  active = new Map;
+  track(sessionId, command, args, childProcess = null) {
+    const id = String(nextId++);
+    const entry = {
+      id,
+      command,
+      args,
+      childProcess,
+      startedAt: new Date
+    };
+    const list = this.active.get(sessionId);
+    if (list) {
+      list.push(entry);
+    } else {
+      this.active.set(sessionId, [entry]);
+    }
+    return id;
+  }
+  untrack(sessionId, id) {
+    const list = this.active.get(sessionId);
+    if (!list)
+      return;
+    const idx = list.findIndex((c) => c.id === id);
+    if (idx !== -1)
+      list.splice(idx, 1);
+    if (list.length === 0)
+      this.active.delete(sessionId);
+  }
+  getActive(sessionId) {
+    return this.active.get(sessionId) ?? [];
+  }
+  checkExclusiveConflict(sessionId, command) {
+    const group = getExclusivityGroup(command);
+    if (!group)
+      return null;
+    const list = this.active.get(sessionId);
+    if (!list)
+      return null;
+    for (const entry of list) {
+      if (getExclusivityGroup(entry.command) === group) {
+        return { blocked: true, runningCommand: entry, group };
+      }
+    }
+    return null;
+  }
+  kill(sessionId, id) {
+    const list = this.active.get(sessionId);
+    if (!list)
+      return false;
+    const entry = list.find((c) => c.id === id);
+    if (!entry)
+      return false;
+    if (entry.childProcess && !entry.childProcess.killed) {
+      entry.childProcess.kill("SIGTERM");
+    }
+    this.untrack(sessionId, id);
+    return true;
+  }
+  killAll(sessionId) {
+    const list = this.active.get(sessionId);
+    if (!list)
+      return 0;
+    let killed = 0;
+    for (const entry of list) {
+      if (entry.childProcess && !entry.childProcess.killed) {
+        entry.childProcess.kill("SIGTERM");
+      }
+      killed++;
+    }
+    this.active.delete(sessionId);
+    return killed;
+  }
+}
+
+// src/gateway.ts
+var logger = createLogger("gateway");
+
+class Gateway {
+  adapters = new Map;
+  router;
+  executor;
+  tracker;
+  onEvent;
+  constructor(options = {}) {
+    this.router = new CommandRouter;
+    this.tracker = new CommandTracker;
+    this.executor = new CommandExecutor(this.tracker);
+    this.onEvent = options.onEvent;
+  }
+  register(adapter) {
+    if (this.adapters.has(adapter.platform)) {
+      throw new Error(`Adapter already registered for platform: ${adapter.platform}`);
+    }
+    this.adapters.set(adapter.platform, adapter);
+    logger.info(`Registered adapter: ${adapter.platform}`);
+  }
+  getAdapter(platform) {
+    return this.adapters.get(platform);
+  }
+  getRouter() {
+    return this.router;
+  }
+  getExecutor() {
+    return this.executor;
+  }
+  getTracker() {
+    return this.tracker;
+  }
+  async handleMessage(message) {
+    this.emit({ type: "message_received", message });
+    const adapter = this.adapters.get(message.platform);
+    if (!adapter) {
+      logger.warn(`No adapter registered for platform: ${message.platform}`);
+      return;
+    }
+    const parsed = this.router.parse(message.text);
+    if (parsed.type === "freetext") {
+      await this.executeCommand(adapter, message.sessionId, "exec", [parsed.text], message);
+      return;
+    }
+    await this.executeCommand(adapter, message.sessionId, parsed.command, parsed.args, message);
+  }
+  async start() {
+    const platforms = Array.from(this.adapters.keys());
+    logger.info(`Starting gateway with adapters: ${platforms.join(", ")}`);
+    for (const [platform, adapter] of this.adapters) {
+      try {
+        await adapter.start();
+        logger.info(`Started adapter: ${platform}`);
+      } catch (error) {
+        logger.error(`Failed to start adapter: ${platform}`, {
+          error: String(error)
+        });
+        throw error;
+      }
+    }
+  }
+  async stop() {
+    for (const [platform, adapter] of this.adapters) {
+      try {
+        await adapter.stop();
+        logger.info(`Stopped adapter: ${platform}`);
+      } catch (error) {
+        logger.warn(`Error stopping adapter: ${platform}`, {
+          error: String(error)
+        });
+      }
+    }
+  }
+  async executeCommand(adapter, sessionId, command, args, _originalMessage) {
+    this.emit({
+      type: "command_started",
+      sessionId,
+      command,
+      args
+    });
+    let streamCallbacks;
+    if (adapter.capabilities.supportsStreaming && adapter.edit) {
+      const adapterRef = adapter;
+      const sentMessageId = "";
+      streamCallbacks = {
+        async onStart(text) {
+          await adapterRef.send(sessionId, {
+            text,
+            format: "plain"
+          });
+          return sentMessageId;
+        },
+        async onUpdate(messageId, text) {
+          if (adapterRef.edit) {
+            await adapterRef.edit(sessionId, messageId, {
+              text,
+              format: "plain"
+            });
+          }
+        },
+        async onComplete(messageId, text, _exitCode) {
+          if (adapterRef.edit) {
+            await adapterRef.edit(sessionId, messageId, {
+              text,
+              format: "plain"
+            });
+          }
+        }
+      };
+    }
+    const result = await this.executor.executeLocusCommand(sessionId, command, args, streamCallbacks);
+    this.emit({
+      type: "command_completed",
+      sessionId,
+      command,
+      exitCode: result.exitCode
+    });
+    if (!result.streaming) {
+      await adapter.send(sessionId, {
+        text: result.text,
+        format: result.format,
+        actions: result.actions
+      });
+    }
+  }
+  emit(event) {
+    if (this.onEvent) {
+      try {
+        this.onEvent(event);
+      } catch (error) {
+        logger.warn("Event handler error", { error: String(error) });
+      }
+    }
+  }
+}
+export {
+  truncate,
+  splitMessage,
+  getCommandDefinition,
+  bestFormat,
+  STREAMING_COMMANDS,
+  Gateway,
+  CommandTracker,
+  CommandRouter,
+  CommandExecutor,
+  COMMAND_REGISTRY
+};

package/dist/router.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CommandRouter — parses inbound text into structured commands or free-text.
+ *
+ * Platform adapters can customize the prefix (default "/") and
+ * how arguments are extracted from raw message text.
+ */
+import type { FreeText, ParsedCommand } from "./types.js";
+export declare class CommandRouter {
+    private prefix;
+    constructor(prefix?: string);
+    /** Parse a message text into a command or free-text. */
+    parse(text: string): ParsedCommand | FreeText;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE1D,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,SAAM;IAIxB,wDAAwD;IACxD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,QAAQ;CA4B9C"}

package/dist/tracker.d.ts

@@ -0,0 +1,25 @@
+/**
+ * CommandTracker — tracks active commands per session for visibility,
+ * cleanup, and conflict detection.
+ *
+ * Generalized from the Telegram-specific tracker to work with
+ * string-based session IDs across any platform.
+ */
+import type { ChildProcess } from "node:child_process";
+import type { ActiveCommand, ConflictResult } from "./types.js";
+export declare class CommandTracker {
+    private active;
+    /** Register a new command for a session. Returns the assigned tracking ID. */
+    track(sessionId: string, command: string, args: string[], childProcess?: ChildProcess | null): string;
+    /** Remove a tracked command by session and ID. */
+    untrack(sessionId: string, id: string): void;
+    /** Get all active commands for a session. */
+    getActive(sessionId: string): readonly ActiveCommand[];
+    /** Check if a command would conflict with an already-running exclusive command. */
+    checkExclusiveConflict(sessionId: string, command: string): ConflictResult | null;
+    /** Kill a specific command's child process and untrack it. */
+    kill(sessionId: string, id: string): boolean;
+    /** Kill all active commands for a session. */
+    killAll(sessionId: string): number;
+}
+//# sourceMappingURL=tracker.d.ts.map

package/dist/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../src/tracker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EAEf,MAAM,YAAY,CAAC;AAqBpB,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAsC;IAEpD,8EAA8E;IAC9E,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,YAAY,GAAE,YAAY,GAAG,IAAW,GACvC,MAAM;IAoBT,kDAAkD;IAClD,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAU5C,6CAA6C;IAC7C,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,aAAa,EAAE;IAItD,mFAAmF;IACnF,sBAAsB,CACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,cAAc,GAAG,IAAI;IAgBxB,8DAA8D;IAC9D,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO;IAe5C,8CAA8C;IAC9C,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;CAenC"}