@calltelemetry/openclaw-linear 0.3.1 → 0.4.1

package/index.ts

@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { registerLinearProvider } from "./src/auth.js";
 import { registerCli } from "./src/cli.js";
@@ -5,6 +6,7 @@ import { createLinearTools } from "./src/tools.js";
 import { handleLinearWebhook } from "./src/webhook.js";
 import { handleOAuthCallback } from "./src/oauth-callback.js";
 import { resolveLinearToken } from "./src/linear-api.js";
+import { createDispatchService } from "./src/dispatch-service.js";
 
 export default function register(api: OpenClawPluginApi) {
   const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
@@ -22,7 +24,7 @@ export default function register(api: OpenClawPluginApi) {
   registerLinearProvider(api);
 
   // Register CLI commands: openclaw openclaw-linear auth|status
-  api.registerCli(({ program }) => registerCli(program, api), {
+  api.registerCli(({ program }) => registerCli(program as any, api), {
     commands: ["openclaw-linear"],
   });
 
@@ -55,8 +57,58 @@ export default function register(api: OpenClawPluginApi) {
     },
   });
 
+  // Register dispatch monitor service (stale detection, session hydration, cleanup)
+  api.registerService(createDispatchService(api));
+
+  // Narration Guard: catch short "Let me explore..." responses that narrate intent
+  // without actually calling tools, and append a warning for the user.
+  const NARRATION_PATTERNS = [
+    /let me (explore|look|investigate|check|dig|analyze|search|find|review|examine)/i,
+    /i('ll| will) (explore|look into|investigate|check|dig into|analyze|search|find|review)/i,
+    /let me (take a look|dive into|pull up|go through)/i,
+  ];
+  const MAX_SHORT_RESPONSE = 250;
+
+  api.on("message_sending", (event: { content?: string }) => {
+    const text = event?.content ?? "";
+    if (!text || text.length > MAX_SHORT_RESPONSE) return {};
+    const isNarration = NARRATION_PATTERNS.some((p) => p.test(text));
+    if (!isNarration) return {};
+    api.logger.warn(`Narration guard triggered: "${text.slice(0, 80)}..."`);
+    return {
+      content:
+        text +
+        "\n\n⚠️ _Agent acknowledged but may not have completed the task. Try asking again or rephrase your request._",
+    };
+  });
+
+  // Check CLI availability (Codex, Claude, Gemini)
+  const cliChecks: Record<string, string> = {};
+  const cliBins: [string, string, string][] = [
+    ["codex", "/home/claw/.npm-global/bin/codex", "npm install -g @openai/codex"],
+    ["claude", "/home/claw/.npm-global/bin/claude", "npm install -g @anthropic-ai/claude-code"],
+    ["gemini", "/home/claw/.npm-global/bin/gemini", "npm install -g @anthropic-ai/gemini-cli"],
+  ];
+  for (const [name, bin, installCmd] of cliBins) {
+    try {
+      const raw = execFileSync(bin, ["--version"], {
+        encoding: "utf8",
+        timeout: 5_000,
+        env: { ...process.env, CLAUDECODE: undefined } as any,
+      }).trim();
+      cliChecks[name] = raw || "unknown";
+    } catch {
+      cliChecks[name] = "not found";
+      api.logger.warn(
+        `${name} CLI not found at ${bin}. The ${name}_run tool will fail. Install with: ${installCmd}`,
+      );
+    }
+  }
+
   const agentId = (pluginConfig?.defaultAgentId as string) ?? "default";
+  const orchestration = pluginConfig?.enableOrchestration !== false ? "enabled" : "disabled";
+  const cliSummary = Object.entries(cliChecks).map(([k, v]) => `${k}: ${v}`).join(", ");
   api.logger.info(
-    `Linear agent extension registered (agent: ${agentId}, token: ${tokenInfo.source !== "none" ? `${tokenInfo.source}` : "missing"})`,
+    `Linear agent extension registered (agent: ${agentId}, token: ${tokenInfo.source !== "none" ? `${tokenInfo.source}` : "missing"}, ${cliSummary}, orchestration: ${orchestration})`,
   );
 }

package/openclaw.plugin.json

@@ -5,13 +5,21 @@
   "version": "0.2.0",
   "configSchema": {
     "type": "object",
+    "additionalProperties": false,
     "properties": {
+      "enabled": { "type": "boolean" },
       "clientId": { "type": "string", "description": "Linear OAuth Client ID" },
       "clientSecret": { "type": "string", "description": "Linear OAuth Client Secret", "sensitive": true },
       "redirectUri": { "type": "string", "description": "Linear OAuth Redirect URI (optional, defaults to gateway URL)" },
       "accessToken": { "type": "string", "description": "Linear API access token for agent activities", "sensitive": true },
       "defaultAgentId": { "type": "string", "description": "OpenClaw agent ID to use for pipeline stages" },
-      "enableAudit": { "type": "boolean", "description": "Run auditor stage after implementation", "default": true }
+      "enableAudit": { "type": "boolean", "description": "Run auditor stage after implementation", "default": true },
+      "codexBaseRepo": { "type": "string", "description": "Path to git repo for Codex worktrees", "default": "/home/claw/ai-workspace" },
+      "codexModel": { "type": "string", "description": "Default Codex model (optional — uses Codex default if omitted)" },
+      "codexTimeoutMs": { "type": "number", "description": "Default Codex timeout in milliseconds", "default": 600000 },
+      "enableOrchestration": { "type": "boolean", "description": "Allow agents to spawn sub-agents via spawn_agent/ask_agent tools", "default": true },
+      "worktreeBaseDir": { "type": "string", "description": "Base directory for persistent git worktrees (default: ~/.openclaw/worktrees)" },
+      "dispatchStatePath": { "type": "string", "description": "Path to dispatch state JSON file (default: ~/.openclaw/linear-dispatch-state.json)" }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Linear Agent plugin for OpenClaw — webhook-driven AI pipeline with OAuth, multi-agent routing, and issue triage",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "openclaw": "^2026.2.13"
+    "openclaw": "^2026.2.13",
+    "typescript": "^5.9.3"
   },
   "openclaw": {
     "extensions": [

package/src/active-session.ts

@@ -0,0 +1,106 @@
+/**
+ * active-session.ts — Idempotent registry of active Linear agent sessions.
+ *
+ * When the pipeline starts work on an issue, it registers the session here.
+ * Any tool (code_run, etc.) can look up the active session for the current
+ * issue to stream activities without relying on the LLM agent to pass params.
+ *
+ * This runs in the gateway process. Tool execution also happens in the gateway,
+ * so tools can read from this registry directly.
+ *
+ * The in-memory Map is the fast-path for tool lookups. On startup, the
+ * dispatch service calls hydrateFromDispatchState() to rebuild it from
+ * the persistent dispatch-state.json file.
+ */
+
+import { readDispatchState } from "./dispatch-state.js";
+
+export interface ActiveSession {
+  agentSessionId: string;
+  issueIdentifier: string;
+  issueId: string;
+  agentId?: string;
+  startedAt: number;
+}
+
+// Keyed by issue ID — one active session per issue at a time.
+const sessions = new Map<string, ActiveSession>();
+
+/**
+ * Register the active session for an issue. Idempotent — calling again
+ * for the same issue just updates the session.
+ */
+export function setActiveSession(session: ActiveSession): void {
+  sessions.set(session.issueId, session);
+}
+
+/**
+ * Clear the active session for an issue.
+ */
+export function clearActiveSession(issueId: string): void {
+  sessions.delete(issueId);
+}
+
+/**
+ * Look up the active session for an issue by issue ID.
+ */
+export function getActiveSession(issueId: string): ActiveSession | null {
+  return sessions.get(issueId) ?? null;
+}
+
+/**
+ * Look up the active session by issue identifier (e.g. "API-472").
+ * Slower than by ID — scans all sessions.
+ */
+export function getActiveSessionByIdentifier(identifier: string): ActiveSession | null {
+  for (const session of sessions.values()) {
+    if (session.issueIdentifier === identifier) return session;
+  }
+  return null;
+}
+
+/**
+ * Get the current active session. If there's exactly one, return it.
+ * If there are multiple (concurrent pipelines), returns null — caller
+ * must specify which issue.
+ */
+export function getCurrentSession(): ActiveSession | null {
+  if (sessions.size === 1) {
+    return sessions.values().next().value ?? null;
+  }
+  return null;
+}
+
+/**
+ * Hydrate the in-memory session Map from dispatch-state.json.
+ * Called on startup by the dispatch service to restore sessions
+ * that were active before a gateway restart.
+ *
+ * Returns the number of sessions restored.
+ */
+export async function hydrateFromDispatchState(configPath?: string): Promise<number> {
+  const state = await readDispatchState(configPath);
+  const active = state.dispatches.active;
+  let restored = 0;
+
+  for (const [, dispatch] of Object.entries(active)) {
+    if (dispatch.status === "dispatched" || dispatch.status === "running") {
+      sessions.set(dispatch.issueId, {
+        agentSessionId: dispatch.agentSessionId ?? "",
+        issueIdentifier: dispatch.issueIdentifier,
+        issueId: dispatch.issueId,
+        startedAt: new Date(dispatch.dispatchedAt).getTime(),
+      });
+      restored++;
+    }
+  }
+
+  return restored;
+}
+
+/**
+ * Get the count of currently tracked sessions.
+ */
+export function getSessionCount(): number {
+  return sessions.size;
+}

package/src/agent.ts

@@ -1,21 +1,193 @@
+import { randomUUID } from "node:crypto";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { LinearAgentApi, ActivityContent } from "./linear-api.js";
+
+// Import extensionAPI for embedded agent runner (internal, not in public SDK)
+let _extensionAPI: typeof import("/home/claw/.npm-global/lib/node_modules/openclaw/dist/extensionAPI.js") | null = null;
+async function getExtensionAPI() {
+  if (!_extensionAPI) {
+    // Dynamic import to avoid blocking module load if unavailable
+    _extensionAPI = await import(
+      "/home/claw/.npm-global/lib/node_modules/openclaw/dist/extensionAPI.js"
+    );
+  }
+  return _extensionAPI;
+}
 
 export interface AgentRunResult {
   success: boolean;
   output: string;
 }
 
+export interface AgentStreamCallbacks {
+  linearApi: LinearAgentApi;
+  agentSessionId: string;
+}
+
+/**
+ * Run an agent using the embedded runner with streaming callbacks.
+ * Falls back to subprocess if the embedded runner is unavailable.
+ */
 export async function runAgent(params: {
   api: OpenClawPluginApi;
   agentId: string;
   sessionId: string;
   message: string;
   timeoutMs?: number;
+  streaming?: AgentStreamCallbacks;
 }): Promise<AgentRunResult> {
-  const { api, agentId, sessionId, message, timeoutMs = 5 * 60_000 } = params;
+  const { api, agentId, sessionId, message, timeoutMs = 5 * 60_000, streaming } = params;
 
   api.logger.info(`Dispatching agent ${agentId} for session ${sessionId}`);
 
+  // Try embedded runner first (has streaming callbacks)
+  if (streaming) {
+    try {
+      return await runEmbedded(api, agentId, sessionId, message, timeoutMs, streaming);
+    } catch (err) {
+      api.logger.warn(`Embedded runner failed, falling back to subprocess: ${err}`);
+    }
+  }
+
+  // Fallback: subprocess (no streaming)
+  return runSubprocess(api, agentId, sessionId, message, timeoutMs);
+}
+
+/**
+ * Embedded agent runner with real-time streaming to Linear.
+ */
+async function runEmbedded(
+  api: OpenClawPluginApi,
+  agentId: string,
+  sessionId: string,
+  message: string,
+  timeoutMs: number,
+  streaming: AgentStreamCallbacks,
+): Promise<AgentRunResult> {
+  const ext = await getExtensionAPI();
+
+  const workspaceDir = ext.resolveAgentWorkspaceDir({ agentId });
+  const sessionFile = ext.resolveSessionFilePath(sessionId);
+  const agentDir = ext.resolveAgentDir({ agentId });
+  const runId = randomUUID();
+
+  // Load config so embedded runner can resolve providers, API keys, etc.
+  const config = await api.runtime.config.loadConfig();
+
+  // Resolve model/provider from config — default is anthropic which requires
+  // a separate API key. Our agents use openrouter.
+  const configAny = config as Record<string, any>;
+  const agentList = configAny?.agents?.list as Array<Record<string, any>> | undefined;
+  const agentEntry = agentList?.find((a) => a.id === agentId);
+  const modelRef: string =
+    agentEntry?.model?.primary ??
+    configAny?.agents?.defaults?.model?.primary ??
+    `${ext.DEFAULT_PROVIDER}/${ext.DEFAULT_MODEL}`;
+
+  // Parse "provider/model-id" format (e.g. "openrouter/moonshotai/kimi-k2.5")
+  const slashIdx = modelRef.indexOf("/");
+  const provider = slashIdx > 0 ? modelRef.slice(0, slashIdx) : ext.DEFAULT_PROVIDER;
+  const model = slashIdx > 0 ? modelRef.slice(slashIdx + 1) : modelRef;
+
+  api.logger.info(`Embedded agent run: agent=${agentId} session=${sessionId} runId=${runId} provider=${provider} model=${model}`);
+
+  const emit = (content: ActivityContent) => {
+    streaming.linearApi.emitActivity(streaming.agentSessionId, content).catch((err) => {
+      api.logger.warn(`Activity emit failed: ${err}`);
+    });
+  };
+
+  // Track last emitted tool to avoid duplicates
+  let lastToolAction = "";
+
+  const result = await ext.runEmbeddedPiAgent({
+    sessionId,
+    sessionFile,
+    workspaceDir,
+    agentDir,
+    prompt: message,
+    agentId,
+    runId,
+    timeoutMs,
+    config,
+    provider,
+    model,
+    shouldEmitToolResult: () => true,
+    shouldEmitToolOutput: () => true,
+
+    // Stream reasoning/thinking to Linear
+    onReasoningStream: (payload) => {
+      const text = payload.text?.trim();
+      if (text && text.length > 10) {
+        emit({ type: "thought", body: text.slice(0, 500) });
+      }
+    },
+
+    // Stream tool results to Linear
+    onToolResult: (payload) => {
+      const text = payload.text?.trim();
+      if (text) {
+        // Truncate tool results for activity display
+        const truncated = text.length > 300 ? text.slice(0, 300) + "..." : text;
+        emit({ type: "action", action: lastToolAction || "Tool result", parameter: truncated });
+      }
+    },
+
+    // Raw agent events — capture tool starts/ends
+    onAgentEvent: (evt) => {
+      const { stream, data } = evt;
+
+      if (stream !== "tool") return;
+
+      const phase = String(data.phase ?? "");
+      const toolName = String(data.name ?? "tool");
+      const meta = typeof data.meta === "string" ? data.meta : "";
+
+      // Tool execution start — emit action with tool name + meta
+      if (phase === "start") {
+        lastToolAction = toolName;
+        emit({ type: "action", action: `Running ${toolName}`, parameter: meta.slice(0, 200) || toolName });
+      }
+
+      // Tool execution result with error
+      if (phase === "result" && data.isError) {
+        emit({ type: "action", action: `${toolName} failed`, parameter: meta.slice(0, 200) || "error" });
+      }
+    },
+
+    // Partial assistant text (for long responses)
+    onPartialReply: (payload) => {
+      // We don't emit every partial chunk to avoid flooding Linear
+      // The final response will be posted as a comment
+    },
+  });
+
+  // Extract output text from payloads
+  const payloads = result.payloads ?? [];
+  const outputText = payloads
+    .map((p) => p.text)
+    .filter(Boolean)
+    .join("\n\n");
+
+  if (result.meta?.error) {
+    api.logger.error(`Embedded agent error: ${result.meta.error.kind}: ${result.meta.error.message}`);
+    return { success: false, output: outputText || result.meta.error.message };
+  }
+
+  api.logger.info(`Embedded agent completed: agent=${agentId} session=${sessionId} duration=${result.meta.durationMs}ms`);
+  return { success: true, output: outputText || "(no output)" };
+}
+
+/**
+ * Subprocess fallback (no streaming, used when no Linear session context).
+ */
+async function runSubprocess(
+  api: OpenClawPluginApi,
+  agentId: string,
+  sessionId: string,
+  message: string,
+  timeoutMs: number,
+): Promise<AgentRunResult> {
   const command = [
     "openclaw",
     "agent",

package/src/auth.ts

@@ -46,7 +46,7 @@ export function registerLinearProvider(api: OpenClawPluginApi) {
       {
         id: "oauth",
         label: "OAuth",
-        kind: "oauth",
+        kind: "oauth" as const,
         run: async (ctx: ProviderAuthContext): Promise<ProviderAuthResult> => {
           // This is a placeholder for the actual OAuth flow.
           // In a real implementation, we would use ctx.oauth.createVpsAwareHandlers
@@ -112,8 +112,12 @@ export function registerLinearProvider(api: OpenClawPluginApi) {
               {
                 profileId: "linear:default",
                 credential: {
-                  type: "oauth",
+                  type: "oauth" as const,
                   provider: "linear",
+                  access: tokens.access_token,
+                  refresh: tokens.refresh_token,
+                  expires: Date.now() + (tokens.expires_in * 1000),
+                  // Keep aliases for backward compat with linear-api.ts resolveLinearToken
                   accessToken: tokens.access_token,
                   refreshToken: tokens.refresh_token,
                   expiresAt: Date.now() + (tokens.expires_in * 1000),