@calltelemetry/openclaw-linear 0.5.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Linear Agent plugin for OpenClaw — webhook-driven AI pipeline with OAuth, multi-agent routing, and issue triage",
   "type": "module",
   "license": "MIT",

package/src/artifacts.ts

@@ -0,0 +1,265 @@
+/**
+ * artifacts.ts — .claw/ per-worktree artifact convention.
+ *
+ * Provides a standard directory structure for storing artifacts during
+ * the lifecycle of a dispatched issue. Any OpenClaw plugin that works
+ * with a worktree can write to {worktreePath}/.claw/.
+ *
+ * Structure:
+ *   .claw/
+ *     manifest.json     — issue metadata + lifecycle timestamps
+ *     plan.md           — implementation plan
+ *     worker-{N}.md     — worker output per attempt (truncated)
+ *     audit-{N}.json    — audit verdict per attempt
+ *     log.jsonl         — append-only interaction log
+ *     summary.md        — agent-curated final summary
+ */
+import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import type { AuditVerdict } from "./pipeline.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const MAX_ARTIFACT_SIZE = 8192; // 8KB per output file
+const MAX_PREVIEW_SIZE = 500;   // For log entry previews
+const MAX_PROMPT_PREVIEW = 200; // For log entry prompt previews
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ClawManifest {
+  issueIdentifier: string;
+  issueTitle: string;
+  issueId: string;
+  tier: string;
+  model: string;
+  dispatchedAt: string;
+  worktreePath: string;
+  branch: string;
+  attempts: number;
+  status: string;
+  plugin: string;
+}
+
+export interface LogEntry {
+  ts: string;
+  phase: "worker" | "audit" | "verdict" | "dispatch";
+  attempt: number;
+  agent: string;
+  prompt: string;
+  outputPreview: string;
+  success: boolean;
+  durationMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Directory setup
+// ---------------------------------------------------------------------------
+
+function clawDir(worktreePath: string): string {
+  return join(worktreePath, ".claw");
+}
+
+/** Creates .claw/ directory. Returns the path. */
+export function ensureClawDir(worktreePath: string): string {
+  const dir = clawDir(worktreePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+/**
+ * Ensure .claw/ is in .gitignore at the worktree root.
+ * Appends if not already present. Idempotent.
+ */
+export function ensureGitignore(worktreePath: string): void {
+  const gitignorePath = join(worktreePath, ".gitignore");
+  try {
+    const content = existsSync(gitignorePath)
+      ? readFileSync(gitignorePath, "utf-8")
+      : "";
+    if (!content.split("\n").some((line) => line.trim() === ".claw" || line.trim() === ".claw/")) {
+      const nl = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+      appendFileSync(gitignorePath, `${nl}.claw/\n`, "utf-8");
+    }
+  } catch {
+    // Best effort — don't block pipeline
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Manifest
+// ---------------------------------------------------------------------------
+
+export function writeManifest(worktreePath: string, manifest: ClawManifest): void {
+  const dir = ensureClawDir(worktreePath);
+  writeFileSync(join(dir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+}
+
+export function readManifest(worktreePath: string): ClawManifest | null {
+  try {
+    const raw = readFileSync(join(clawDir(worktreePath), "manifest.json"), "utf-8");
+    return JSON.parse(raw) as ClawManifest;
+  } catch {
+    return null;
+  }
+}
+
+export function updateManifest(worktreePath: string, updates: Partial<ClawManifest>): void {
+  const current = readManifest(worktreePath);
+  if (!current) return;
+  writeManifest(worktreePath, { ...current, ...updates });
+}
+
+// ---------------------------------------------------------------------------
+// Phase artifacts
+// ---------------------------------------------------------------------------
+
+/** Save worker output for a given attempt. Truncated to MAX_ARTIFACT_SIZE. */
+export function saveWorkerOutput(worktreePath: string, attempt: number, output: string): void {
+  const dir = ensureClawDir(worktreePath);
+  const truncated = output.length > MAX_ARTIFACT_SIZE
+    ? output.slice(0, MAX_ARTIFACT_SIZE) + "\n\n--- truncated ---"
+    : output;
+  writeFileSync(join(dir, `worker-${attempt}.md`), truncated, "utf-8");
+}
+
+/** Save a plan (extracted from worker output or provided directly). */
+export function savePlan(worktreePath: string, plan: string): void {
+  const dir = ensureClawDir(worktreePath);
+  writeFileSync(join(dir, "plan.md"), plan, "utf-8");
+}
+
+/** Save audit verdict for a given attempt. */
+export function saveAuditVerdict(worktreePath: string, attempt: number, verdict: AuditVerdict): void {
+  const dir = ensureClawDir(worktreePath);
+  writeFileSync(join(dir, `audit-${attempt}.json`), JSON.stringify(verdict, null, 2) + "\n", "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Interaction log
+// ---------------------------------------------------------------------------
+
+/** Append a structured log entry to .claw/log.jsonl. */
+export function appendLog(worktreePath: string, entry: LogEntry): void {
+  const dir = ensureClawDir(worktreePath);
+  const truncated: LogEntry = {
+    ...entry,
+    prompt: entry.prompt.slice(0, MAX_PROMPT_PREVIEW),
+    outputPreview: entry.outputPreview.slice(0, MAX_PREVIEW_SIZE),
+  };
+  appendFileSync(join(dir, "log.jsonl"), JSON.stringify(truncated) + "\n", "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+
+/** Write the final curated summary. */
+export function writeSummary(worktreePath: string, summary: string): void {
+  const dir = ensureClawDir(worktreePath);
+  writeFileSync(join(dir, "summary.md"), summary, "utf-8");
+}
+
+/**
+ * Build a markdown summary from all .claw/ artifacts.
+ * Used at issue completion to generate a memory-friendly summary.
+ */
+export function buildSummaryFromArtifacts(worktreePath: string): string | null {
+  const manifest = readManifest(worktreePath);
+  if (!manifest) return null;
+
+  const parts: string[] = [];
+  parts.push(`# Dispatch: ${manifest.issueIdentifier} — ${manifest.issueTitle}`);
+  parts.push(`**Tier:** ${manifest.tier} | **Status:** ${manifest.status} | **Attempts:** ${manifest.attempts}`);
+  parts.push("");
+
+  // Include plan if exists
+  try {
+    const plan = readFileSync(join(clawDir(worktreePath), "plan.md"), "utf-8");
+    parts.push("## Plan");
+    parts.push(plan.slice(0, 2000));
+    parts.push("");
+  } catch { /* no plan */ }
+
+  // Include each attempt's worker + audit
+  for (let i = 0; i < manifest.attempts; i++) {
+    parts.push(`## Attempt ${i}`);
+
+    // Worker output preview
+    try {
+      const worker = readFileSync(join(clawDir(worktreePath), `worker-${i}.md`), "utf-8");
+      parts.push("### Worker Output");
+      parts.push(worker.slice(0, 1500));
+      parts.push("");
+    } catch { /* no worker output */ }
+
+    // Audit verdict
+    try {
+      const raw = readFileSync(join(clawDir(worktreePath), `audit-${i}.json`), "utf-8");
+      const verdict = JSON.parse(raw) as AuditVerdict;
+      parts.push(`### Audit: ${verdict.pass ? "PASS" : "FAIL"}`);
+      if (verdict.criteria.length) parts.push(`**Criteria:** ${verdict.criteria.join(", ")}`);
+      if (verdict.gaps.length) parts.push(`**Gaps:** ${verdict.gaps.join(", ")}`);
+      if (verdict.testResults) parts.push(`**Tests:** ${verdict.testResults}`);
+      parts.push("");
+    } catch { /* no audit */ }
+  }
+
+  parts.push("---");
+  parts.push(`*Artifacts: ${worktreePath}/.claw/*`);
+
+  return parts.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Memory integration
+// ---------------------------------------------------------------------------
+
+/**
+ * Write dispatch summary to the orchestrator's memory directory.
+ * Auto-indexed by OpenClaw's sqlite+embeddings memory system.
+ */
+export function writeDispatchMemory(
+  issueIdentifier: string,
+  summary: string,
+  workspaceDir: string,
+): void {
+  const memDir = join(workspaceDir, "memory");
+  if (!existsSync(memDir)) {
+    mkdirSync(memDir, { recursive: true });
+  }
+  writeFileSync(
+    join(memDir, `dispatch-${issueIdentifier}.md`),
+    summary,
+    "utf-8",
+  );
+}
+
+/**
+ * Resolve the orchestrator agent's workspace directory from config.
+ * Same config-based approach as resolveAgentDirs in agent.ts.
+ */
+export function resolveOrchestratorWorkspace(
+  api: any,
+  pluginConfig?: Record<string, unknown>,
+): string {
+  const home = process.env.HOME ?? "/home/claw";
+  const agentId = (pluginConfig?.defaultAgentId as string) ?? "default";
+
+  try {
+    const config = api.runtime.config.loadConfig() as Record<string, any>;
+    const agentList = config?.agents?.list as Array<Record<string, any>> | undefined;
+    const agentEntry = agentList?.find((a: any) => a.id === agentId);
+    return agentEntry?.workspace
+      ?? config?.agents?.defaults?.workspace
+      ?? join(home, ".openclaw", "workspace");
+  } catch {
+    return join(home, ".openclaw", "workspace");
+  }
+}

package/src/codex-worktree.ts

@@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, statSync, readdirSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
+import { ensureGitignore } from "./artifacts.js";
 
 const DEFAULT_BASE_REPO = "/home/claw/ai-workspace";
 const DEFAULT_WORKTREE_BASE_DIR = path.join(homedir(), ".openclaw", "worktrees");
@@ -90,6 +91,7 @@ export function createWorktree(
     try {
       // Verify it's a valid git worktree
       git(["rev-parse", "--git-dir"], worktreePath);
+      ensureGitignore(worktreePath);
       return { path: worktreePath, branch, resumed: true };
     } catch {
       // Directory exists but isn't a valid worktree — remove and recreate
@@ -105,11 +107,13 @@ export function createWorktree(
   if (branchExists) {
     // Recreate worktree from existing branch — preserves previous work
     git(["worktree", "add", worktreePath, branch], repo);
+    ensureGitignore(worktreePath);
     return { path: worktreePath, branch, resumed: true };
   }
 
   // Fresh start: new branch off HEAD
   git(["worktree", "add", "-b", branch, worktreePath], repo);
+  ensureGitignore(worktreePath);
   return { path: worktreePath, branch, resumed: false };
 }
 

package/src/dispatch-state.ts

@@ -57,6 +57,7 @@ export interface ActiveDispatch {
   workerSessionKey?: string;    // session key for current worker sub-agent
   auditSessionKey?: string;     // session key for current audit sub-agent
   stuckReason?: string;         // only set when status === "stuck"
+  issueTitle?: string;          // for artifact summaries and memory headings
 }
 
 export interface CompletedDispatch {

package/src/pipeline.ts

@@ -34,6 +34,16 @@ import {
   getActiveDispatch,
 } from "./dispatch-state.js";
 import { type NotifyFn } from "./notify.js";
+import {
+  saveWorkerOutput,
+  saveAuditVerdict,
+  appendLog,
+  updateManifest,
+  writeSummary,
+  buildSummaryFromArtifacts,
+  writeDispatchMemory,
+  resolveOrchestratorWorkspace,
+} from "./artifacts.js";
 
 // ---------------------------------------------------------------------------
 // Prompt loading
@@ -264,6 +274,9 @@ export async function triggerAudit(
 
   api.logger.info(`${TAG} worker completed, triggering audit (attempt ${dispatch.attempt})`);
 
+  // Update .claw/ manifest
+  try { updateManifest(dispatch.worktreePath, { status: "auditing", attempts: dispatch.attempt }); } catch {}
+
   // Fetch fresh issue details for audit context
   const issueDetails = await linearApi.getIssueDetails(dispatch.issueId).catch(() => null);
   const issue: IssueContext = {
@@ -371,6 +384,15 @@ export async function processVerdict(
     }
   }
 
+  // Log audit interaction to .claw/
+  try {
+    appendLog(dispatch.worktreePath, {
+      ts: new Date().toISOString(), phase: "audit", attempt: dispatch.attempt,
+      agent: "auditor", prompt: "(audit task)",
+      outputPreview: auditOutput.slice(0, 500), success: event.success,
+    });
+  } catch {}
+
   // Parse verdict
   const verdict = parseVerdict(auditOutput);
   if (!verdict) {
@@ -406,9 +428,13 @@ async function handleAuditPass(
   dispatch: ActiveDispatch,
   verdict: AuditVerdict,
 ): Promise<void> {
-  const { api, linearApi, notify, configPath } = hookCtx;
+  const { api, linearApi, notify, pluginConfig, configPath } = hookCtx;
   const TAG = `[${dispatch.issueIdentifier}]`;
 
+  // Save audit verdict to .claw/
+  try { saveAuditVerdict(dispatch.worktreePath, dispatch.attempt, verdict); } catch {}
+  try { updateManifest(dispatch.worktreePath, { status: "done", attempts: dispatch.attempt + 1 }); } catch {}
+
   // CAS transition: auditing → done
   try {
     await transitionDispatch(dispatch.issueIdentifier, "auditing", "done", undefined, configPath);
@@ -428,11 +454,26 @@ async function handleAuditPass(
     project: dispatch.project,
   }, configPath);
 
-  // Post approval comment
+  // Build summary from .claw/ artifacts and write to memory
+  let summary: string | null = null;
+  try {
+    summary = buildSummaryFromArtifacts(dispatch.worktreePath);
+    if (summary) {
+      writeSummary(dispatch.worktreePath, summary);
+      const wsDir = resolveOrchestratorWorkspace(api, pluginConfig);
+      writeDispatchMemory(dispatch.issueIdentifier, summary, wsDir);
+      api.logger.info(`${TAG} .claw/ summary and memory written`);
+    }
+  } catch (err) {
+    api.logger.warn(`${TAG} failed to write summary/memory: ${err}`);
+  }
+
+  // Post approval comment (with summary excerpt if available)
   const criteriaList = verdict.criteria.map((c) => `- ${c}`).join("\n");
+  const summaryExcerpt = summary ? `\n\n**Summary:**\n${summary.slice(0, 2000)}` : "";
   await linearApi.createComment(
     dispatch.issueId,
-    `## Audit Passed\n\n**Criteria verified:**\n${criteriaList}\n\n**Tests:** ${verdict.testResults || "N/A"}\n\n---\n*Attempt ${dispatch.attempt + 1} — audit passed.*`,
+    `## Audit Passed\n\n**Criteria verified:**\n${criteriaList}\n\n**Tests:** ${verdict.testResults || "N/A"}${summaryExcerpt}\n\n---\n*Attempt ${dispatch.attempt + 1} — audit passed. Artifacts: \`${dispatch.worktreePath}/.claw/\`*`,
   ).catch((err) => api.logger.error(`${TAG} failed to post audit pass comment: ${err}`));
 
   api.logger.info(`${TAG} audit PASSED — dispatch completed (attempt ${dispatch.attempt})`);
@@ -458,8 +499,13 @@ async function handleAuditFail(
   const maxAttempts = (pluginConfig?.maxReworkAttempts as number) ?? 2;
   const nextAttempt = dispatch.attempt + 1;
 
+  // Save audit verdict to .claw/ (both escalation and rework paths)
+  try { saveAuditVerdict(dispatch.worktreePath, dispatch.attempt, verdict); } catch {}
+
   if (nextAttempt > maxAttempts) {
     // Escalate — too many failures
+    try { updateManifest(dispatch.worktreePath, { status: "stuck", attempts: nextAttempt }); } catch {}
+
     try {
       await transitionDispatch(
         dispatch.issueIdentifier,
@@ -476,10 +522,20 @@ async function handleAuditFail(
       throw err;
     }
 
+    // Write summary + memory for stuck dispatches too
+    try {
+      const summary = buildSummaryFromArtifacts(dispatch.worktreePath);
+      if (summary) {
+        writeSummary(dispatch.worktreePath, summary);
+        const wsDir = resolveOrchestratorWorkspace(api, pluginConfig);
+        writeDispatchMemory(dispatch.issueIdentifier, summary, wsDir);
+      }
+    } catch {}
+
     const gapsList = verdict.gaps.map((g) => `- ${g}`).join("\n");
     await linearApi.createComment(
       dispatch.issueId,
-      `## Audit Failed — Escalating\n\n**Attempt ${nextAttempt} of ${maxAttempts + 1}**\n\n**Gaps:**\n${gapsList}\n\n**Tests:** ${verdict.testResults || "N/A"}\n\n---\n*Max rework attempts reached. Needs human review.*`,
+      `## Audit Failed — Escalating\n\n**Attempt ${nextAttempt} of ${maxAttempts + 1}**\n\n**Gaps:**\n${gapsList}\n\n**Tests:** ${verdict.testResults || "N/A"}\n\n---\n*Max rework attempts reached. Needs human review. Artifacts: \`${dispatch.worktreePath}/.claw/\`*`,
     ).catch((err) => api.logger.error(`${TAG} failed to post escalation comment: ${err}`));
 
     api.logger.warn(`${TAG} audit FAILED ${nextAttempt}x — escalating to human`);
@@ -608,6 +664,7 @@ export async function spawnWorker(
 
   api.logger.info(`${TAG} spawning worker agent session=${workerSessionId} (attempt ${dispatch.attempt})`);
 
+  const workerStartTime = Date.now();
   const result = await runAgent({
     api,
     agentId: (pluginConfig?.defaultAgentId as string) ?? "default",
@@ -616,6 +673,19 @@ export async function spawnWorker(
     timeoutMs: (pluginConfig?.codexTimeoutMs as number) ?? 10 * 60_000,
   });
 
+  // Save worker output to .claw/
+  const workerElapsed = Date.now() - workerStartTime;
+  try { saveWorkerOutput(dispatch.worktreePath, dispatch.attempt, result.output); } catch {}
+  try {
+    appendLog(dispatch.worktreePath, {
+      ts: new Date().toISOString(), phase: "worker", attempt: dispatch.attempt,
+      agent: (pluginConfig?.defaultAgentId as string) ?? "default",
+      prompt: workerPrompt.task.slice(0, 200),
+      outputPreview: result.output.slice(0, 500),
+      success: result.success, durationMs: workerElapsed,
+    });
+  } catch {}
+
   // runAgent returns inline — trigger audit directly.
   // Re-read dispatch state since it may have changed during worker run.
   const freshState = await readDispatchState(configPath);

package/src/webhook.ts

@@ -9,6 +9,7 @@ import { readDispatchState, getActiveDispatch, registerDispatch, updateDispatchS
 import { createDiscordNotifier, createNoopNotifier, type NotifyFn } from "./notify.js";
 import { assessTier } from "./tier-assess.js";
 import { createWorktree, prepareWorkspace } from "./codex-worktree.js";
+import { ensureClawDir, writeManifest } from "./artifacts.js";
 
 // ── Agent profiles (loaded from config, no hardcoded names) ───────
 interface AgentProfile {
@@ -1250,11 +1251,32 @@ async function handleDispatch(
     api.logger.warn(`@dispatch: could not create agent session: ${err}`);
   }
 
+  // 6b. Initialize .claw/ artifact directory
+  try {
+    ensureClawDir(worktree.path);
+    writeManifest(worktree.path, {
+      issueIdentifier: identifier,
+      issueTitle: enrichedIssue.title ?? "(untitled)",
+      issueId: issue.id,
+      tier: assessment.tier,
+      model: assessment.model,
+      dispatchedAt: new Date().toISOString(),
+      worktreePath: worktree.path,
+      branch: worktree.branch,
+      attempts: 0,
+      status: "dispatched",
+      plugin: "openclaw-linear",
+    });
+  } catch (err) {
+    api.logger.warn(`@dispatch: .claw/ init failed: ${err}`);
+  }
+
   // 7. Register dispatch in persistent state
   const now = new Date().toISOString();
   await registerDispatch(identifier, {
     issueId: issue.id,
     issueIdentifier: identifier,
+    issueTitle: enrichedIssue.title ?? "(untitled)",
     worktreePath: worktree.path,
     branch: worktree.branch,
     tier: assessment.tier,