cortex-agents 2.3.0 → 3.4.0

package/dist/tools/task.js

@@ -2,35 +2,12 @@ import { tool } from "@opencode-ai/plugin";
 import * as fs from "fs";
 import * as path from "path";
 import { detectWorktreeInfo } from "../utils/worktree-detect.js";
-import { findPlanContent, extractPlanSections, buildPrBodyFromPlan, } from "../utils/plan-extract.js";
-import { git, gh, which } from "../utils/shell.js";
+import { findPlanContent, extractPlanSections, extractIssueRefs, buildPrBodyFromPlan, } from "../utils/plan-extract.js";
+import { git, gh } from "../utils/shell.js";
+import { checkGhAvailability } from "../utils/github.js";
 const PROTECTED_BRANCHES = ["main", "master", "develop", "production", "staging"];
 const DOCS_DIR = "docs";
 // ─── Helpers ─────────────────────────────────────────────────────────────────
-/**
- * Check if `gh` CLI is installed and authenticated.
- */
-async function checkGhCli(cwd) {
-    // Check if gh exists
-    const ghPath = await which("gh");
-    if (!ghPath) {
-        return {
-            ok: false,
-            error: "GitHub CLI (gh) is not installed. Install it from https://cli.github.com/ and run `gh auth login`.",
-        };
-    }
-    // Check if authenticated
-    try {
-        await gh(cwd, "auth", "status");
-    }
-    catch {
-        return {
-            ok: false,
-            error: "GitHub CLI is not authenticated. Run `gh auth login` to authenticate.",
-        };
-    }
-    return { ok: true };
-}
 /**
  * Check if a remote named "origin" is configured.
  */
@@ -117,9 +94,13 @@ export const finalize = tool({
             .boolean()
             .optional()
             .describe("Create as draft PR (default: false)"),
+        issueRefs: tool.schema
+            .array(tool.schema.number())
+            .optional()
+            .describe("GitHub issue numbers to link in PR body (adds 'Closes #N' for each)"),
     },
     async execute(args, context) {
-        const { commitMessage, prTitle, prBody: customPrBody, baseBranch: customBaseBranch, planFilename, draft = false, } = args;
+        const { commitMessage, prTitle, prBody: customPrBody, baseBranch: customBaseBranch, planFilename, draft = false, issueRefs: explicitIssueRefs, } = args;
         const cwd = context.worktree;
         const output = [];
         const warnings = [];
@@ -162,9 +143,12 @@ Create a feature/bugfix branch first with branch_create or worktree_create.`;
             output.push(`Worktree detected (main tree: ${wtInfo.mainWorktreePath})`);
         }
         // ── 4. Check prerequisites ────────────────────────────────
-        const ghCheck = await checkGhCli(cwd);
-        if (!ghCheck.ok) {
-            return `✗ ${ghCheck.error}`;
+        const ghStatus = await checkGhAvailability(cwd);
+        if (!ghStatus.installed) {
+            return "✗ GitHub CLI (gh) is not installed. Install it from https://cli.github.com/ and run `gh auth login`.";
+        }
+        if (!ghStatus.authenticated) {
+            return "✗ GitHub CLI is not authenticated. Run `gh auth login` to authenticate.";
         }
         const remoteCheck = await checkRemote(cwd);
         if (!remoteCheck.ok) {
@@ -218,6 +202,7 @@ All previous steps succeeded (changes committed). Try pushing manually:
         }
         // ── 9. Build PR body ──────────────────────────────────────
         let prBodyContent = customPrBody || "";
+        let issueRefs = explicitIssueRefs ?? [];
         if (!prBodyContent) {
             // Try to build from plan
             const plan = findPlanContent(cwd, planFilename, branchName);
@@ -225,6 +210,10 @@ All previous steps succeeded (changes committed). Try pushing manually:
                 const sections = extractPlanSections(plan.content, plan.filename);
                 prBodyContent = buildPrBodyFromPlan(sections);
                 output.push(`PR body generated from plan: ${plan.filename}`);
+                // Extract issue refs from plan frontmatter if not explicitly provided
+                if (issueRefs.length === 0) {
+                    issueRefs = extractIssueRefs(plan.content);
+                }
             }
             else {
                 // Fall back to commit log
@@ -237,6 +226,12 @@ All previous steps succeeded (changes committed). Try pushing manually:
                 }
             }
         }
+        // Append issue closing references to PR body
+        if (issueRefs.length > 0) {
+            const closingRefs = issueRefs.map((n) => `Closes #${n}`).join("\n");
+            prBodyContent += `\n\n## Linked Issues\n\n${closingRefs}`;
+            output.push(`Linked issues: ${issueRefs.map((n) => `#${n}`).join(", ")}`);
+        }
         // ── 10. Create PR via gh ──────────────────────────────────
         const finalPrTitle = prTitle || commitMessage;
         let prUrl = "";

package/dist/tools/worktree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/tools/worktree.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAiBvD,KAAK,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;AACpC,KAAK,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;AAE9B;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;;;;;;;;;EAuF1C;AAED,eAAO,MAAM,IAAI;;;;CAiCf,CAAC;AAEH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;EAkI1C;AAED,eAAO,MAAM,IAAI;;;;;;;;CAgDf,CAAC;AAkUH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;;;;;;;;;;;;;;;;;;;;EAsIxD"}
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/tools/worktree.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAiBvD,KAAK,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;AACpC,KAAK,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;AAE9B;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;;;;;;;;;EAuF1C;AAED,eAAO,MAAM,IAAI;;;;CAiCf,CAAC;AAEH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;EAkI1C;AAED,eAAO,MAAM,IAAI;;;;;;;;CAgDf,CAAC;AA8UH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;;;;;;;;;;;;;;;;;;;;EAsIxD"}

package/dist/tools/worktree.js

@@ -2,8 +2,8 @@ import { tool } from "@opencode-ai/plugin";
 import * as fs from "fs";
 import * as path from "path";
 import { propagatePlan } from "../utils/propagate.js";
-import { git, which, kill, spawn as shellSpawn } from "../utils/shell.js";
-import { detectDriver, closeSession, writeSession, readSession, } from "../utils/terminal.js";
+import { git, which, shellEscape, kill, spawn as shellSpawn } from "../utils/shell.js";
+import { detectTerminalDriver, closeSession, writeSession, readSession, } from "../utils/terminal.js";
 const WORKTREE_ROOT = ".worktrees";
 /**
  * Factory function that creates the worktree_create tool with access
@@ -171,8 +171,8 @@ Use worktree_list to see existing worktrees.`;
                         // PTY may already be closed
                     }
                 }
-                else if (session.mode === "terminal") {
-                    // Close terminal tab via driver
+                else if (session.mode === "terminal" || session.mode === "ide") {
+                    // Close terminal/IDE tab via driver
                     closedSession = await closeSession(session);
                 }
                 else if (session.mode === "background" && session.pid) {
@@ -351,7 +351,11 @@ async function launchTerminalTab(client, worktreePath, branchName, opencodeBin,
             // Toast failure is non-fatal
         }
     };
-    const driver = detectDriver();
+    // KEY FIX: Use multi-strategy terminal detection that NEVER returns IDE drivers.
+    // This ensures "Open in terminal tab" always opens in the user's actual terminal
+    // emulator (iTerm2, Ghostty, kitty, etc.), not in a new IDE window.
+    const detection = await detectTerminalDriver(worktreePath);
+    const driver = detection.driver;
     const opts = {
         worktreePath,
         opencodeBin,
@@ -373,13 +377,20 @@ async function launchTerminalTab(client, worktreePath, branchName, opencodeBin,
             ...result,
         };
         writeSession(worktreePath, session);
-        await notify(`Opened ${driver.name} tab with agent '${agent}'`);
-        return `✓ Opened ${driver.name} tab in worktree\n\nBranch: ${branchName}\nTerminal: ${driver.name}`;
+        const strategyNote = detection.strategy !== "env"
+            ? ` (detected via ${detection.strategy})`
+            : "";
+        await notify(`Opened ${driver.name} tab with agent '${agent}'${strategyNote}`);
+        return `✓ Opened ${driver.name} tab in worktree\n\nBranch: ${branchName}\nTerminal: ${driver.name}\nDetection: ${detection.strategy}${detection.detail ? ` — ${detection.detail}` : ""}`;
     }
     catch (error) {
         await notify(`Could not open terminal: ${error.message || error}`, "error");
-        const innerCmd = `cd "${worktreePath}" && "${opencodeBin}" --agent ${agent}`;
-        return `✗ Could not open terminal (${driver.name}). Manual command:\n  ${innerCmd}`;
+        // Escape all user-controlled inputs in the manual command to prevent injection
+        const safePath = shellEscape(worktreePath);
+        const safeBin = shellEscape(opencodeBin);
+        const safeAgent = shellEscape(agent);
+        const innerCmd = `cd "${safePath}" && "${safeBin}" --agent "${safeAgent}"`;
+        return `✗ Could not open terminal (${driver.name}, detected via ${detection.strategy}). Manual command:\n  ${innerCmd}`;
     }
 }
 // ─── Mode B: In-App PTY ─────────────────────────────────────────────────────
@@ -597,14 +608,14 @@ export function createLaunch(client, shell) {
             agent: tool.schema
                 .string()
                 .optional()
-                .describe("Agent to use in the new session (default: 'build')"),
+                .describe("Agent to use in the new session (default: 'implement')"),
             prompt: tool.schema
                 .string()
                 .optional()
                 .describe("Custom prompt for the new session (auto-generated from plan if omitted)"),
         },
         async execute(args, context) {
-            const { name, mode, plan: planFilename, agent = "build", prompt: customPrompt, } = args;
+            const { name, mode, plan: planFilename, agent = "implement", prompt: customPrompt, } = args;
             const worktreePath = path.join(context.worktree, WORKTREE_ROOT, name);
             const absoluteWorktreePath = path.resolve(worktreePath);
             // ── Validate worktree exists ───────────────────────────────

package/dist/utils/github.d.ts

@@ -0,0 +1,104 @@
+export interface GhStatus {
+    installed: boolean;
+    authenticated: boolean;
+    hasRemote: boolean;
+    repoOwner?: string;
+    repoName?: string;
+    projects: {
+        id: string;
+        number: number;
+        title: string;
+    }[];
+}
+export interface GitHubIssue {
+    number: number;
+    title: string;
+    state: string;
+    labels: string[];
+    assignees: string[];
+    milestone?: string;
+    body: string;
+    url: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GitHubProjectItem {
+    id: string;
+    title: string;
+    type: "ISSUE" | "PULL_REQUEST" | "DRAFT_ISSUE";
+    status?: string;
+    assignees: string[];
+    labels: string[];
+    issueNumber?: number;
+    url?: string;
+    body?: string;
+}
+/**
+ * Check full GitHub CLI availability and repo context.
+ * Returns a status object with installation, authentication, and repo info.
+ */
+export declare function checkGhAvailability(cwd: string): Promise<GhStatus>;
+/**
+ * Parse a git remote URL to extract owner and repo name.
+ * Handles HTTPS, SSH, and GitHub CLI formats.
+ * Supports both github.com and GitHub Enterprise Server URLs (e.g., github.mycompany.com).
+ *
+ * The regex requires "github" to appear at a hostname boundary (after `//` or `@`)
+ * to prevent false positives like "notgithub.com" or "fakegithub.evil.com".
+ */
+export declare function parseRepoUrl(url: string): {
+    owner: string;
+    name: string;
+} | null;
+/**
+ * Truncate a string to the given length, appending "..." if truncated.
+ */
+export declare function truncate(str: string, maxLen: number): string;
+/**
+ * Format a single GitHub issue into a compact list entry.
+ * Used when presenting multiple issues for selection.
+ */
+export declare function formatIssueListEntry(issue: GitHubIssue): string;
+/**
+ * Format multiple issues into a numbered selection list.
+ */
+export declare function formatIssueList(issues: GitHubIssue[]): string;
+/**
+ * Format a GitHub issue into a planning-friendly markdown block.
+ * Used by the architect agent to seed plan content from selected issues.
+ */
+export declare function formatIssueForPlan(issue: GitHubIssue): string;
+/**
+ * Format a single GitHub Project item into a compact list entry.
+ */
+export declare function formatProjectItemEntry(item: GitHubProjectItem): string;
+/**
+ * Format multiple project items into a list.
+ */
+export declare function formatProjectItemList(items: GitHubProjectItem[]): string;
+/**
+ * Fetch GitHub projects associated with the repo owner.
+ */
+export declare function fetchProjects(cwd: string, owner: string): Promise<{
+    id: string;
+    number: number;
+    title: string;
+}[]>;
+/**
+ * Fetch issues from the current repository using gh CLI.
+ */
+export declare function fetchIssues(cwd: string, options?: {
+    state?: string;
+    labels?: string;
+    milestone?: string;
+    assignee?: string;
+    limit?: number;
+}): Promise<GitHubIssue[]>;
+/**
+ * Fetch project items from a specific GitHub Project.
+ */
+export declare function fetchProjectItems(cwd: string, owner: string, projectNumber: number, options?: {
+    status?: string;
+    limit?: number;
+}): Promise<GitHubProjectItem[]>;
+//# sourceMappingURL=github.d.ts.map

package/dist/utils/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../src/utils/github.ts"],"names":[],"mappings":"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"}

package/dist/utils/github.js

@@ -0,0 +1,243 @@
+import { gh, which, git } from "./shell.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** Maximum character length for issue body in list views to avoid overwhelming context. */
+const BODY_TRUNCATE_LENGTH = 200;
+/** Maximum character length for issue body in detail views (plan formatting). */
+const BODY_DETAIL_LENGTH = 2000;
+// ─── GitHub CLI Availability ─────────────────────────────────────────────────
+/**
+ * Check full GitHub CLI availability and repo context.
+ * Returns a status object with installation, authentication, and repo info.
+ */
+export async function checkGhAvailability(cwd) {
+    const status = {
+        installed: false,
+        authenticated: false,
+        hasRemote: false,
+        projects: [],
+    };
+    // 1. Check if gh is installed
+    const ghPath = await which("gh");
+    if (!ghPath)
+        return status;
+    status.installed = true;
+    // 2. Check if authenticated
+    try {
+        await gh(cwd, "auth", "status");
+        status.authenticated = true;
+    }
+    catch {
+        return status;
+    }
+    // 3. Extract repo owner/name from remote
+    try {
+        const { stdout } = await git(cwd, "remote", "get-url", "origin");
+        const parsed = parseRepoUrl(stdout.trim());
+        if (parsed) {
+            status.hasRemote = true;
+            status.repoOwner = parsed.owner;
+            status.repoName = parsed.name;
+        }
+    }
+    catch {
+        // No remote configured — hasRemote stays false
+    }
+    return status;
+}
+/**
+ * Parse a git remote URL to extract owner and repo name.
+ * Handles HTTPS, SSH, and GitHub CLI formats.
+ * Supports both github.com and GitHub Enterprise Server URLs (e.g., github.mycompany.com).
+ *
+ * The regex requires "github" to appear at a hostname boundary (after `//` or `@`)
+ * to prevent false positives like "notgithub.com" or "fakegithub.evil.com".
+ */
+export function parseRepoUrl(url) {
+    // HTTPS: https://github.com/owner/repo.git  OR  https://github.mycompany.com/owner/repo.git
+    // The `//` anchor ensures "github" is at the start of the hostname, not mid-word.
+    const httpsMatch = url.match(/\/\/github[^/]*\/([^/]+)\/([^/.]+?)(?:\.git)?$/);
+    if (httpsMatch) {
+        return { owner: httpsMatch[1], name: httpsMatch[2] };
+    }
+    // SSH: git@github.com:owner/repo.git  OR  git@github.mycompany.com:owner/repo.git
+    // The `git@` prefix already anchors to the hostname start.
+    const sshMatch = url.match(/git@github[^:]*:([^/]+)\/([^/.]+?)(?:\.git)?$/);
+    if (sshMatch) {
+        return { owner: sshMatch[1], name: sshMatch[2] };
+    }
+    return null;
+}
+// ─── Issue Formatting ────────────────────────────────────────────────────────
+/**
+ * Truncate a string to the given length, appending "..." if truncated.
+ */
+export function truncate(str, maxLen) {
+    if (!str)
+        return "";
+    if (str.length <= maxLen)
+        return str;
+    return str.substring(0, maxLen).trimEnd() + "...";
+}
+/**
+ * Format a single GitHub issue into a compact list entry.
+ * Used when presenting multiple issues for selection.
+ */
+export function formatIssueListEntry(issue) {
+    const labels = issue.labels.length > 0 ? ` [${issue.labels.join(", ")}]` : "";
+    const assignees = issue.assignees.length > 0 ? ` → ${issue.assignees.join(", ")}` : "";
+    const body = issue.body ? `\n   ${truncate(issue.body.replace(/\n/g, " "), BODY_TRUNCATE_LENGTH)}` : "";
+    return `#${issue.number}: ${issue.title}${labels}${assignees}${body}`;
+}
+/**
+ * Format multiple issues into a numbered selection list.
+ */
+export function formatIssueList(issues) {
+    if (issues.length === 0)
+        return "No issues found.";
+    return issues.map((issue) => formatIssueListEntry(issue)).join("\n\n");
+}
+/**
+ * Format a GitHub issue into a planning-friendly markdown block.
+ * Used by the architect agent to seed plan content from selected issues.
+ */
+export function formatIssueForPlan(issue) {
+    const parts = [];
+    parts.push(`### Issue #${issue.number}: ${issue.title}`);
+    parts.push("");
+    if (issue.labels.length > 0) {
+        parts.push(`**Labels:** ${issue.labels.join(", ")}`);
+    }
+    if (issue.assignees.length > 0) {
+        parts.push(`**Assignees:** ${issue.assignees.join(", ")}`);
+    }
+    if (issue.milestone) {
+        parts.push(`**Milestone:** ${issue.milestone}`);
+    }
+    parts.push(`**URL:** ${issue.url}`);
+    parts.push("");
+    if (issue.body) {
+        parts.push("**Description:**");
+        parts.push("");
+        parts.push(truncate(issue.body, BODY_DETAIL_LENGTH));
+    }
+    return parts.join("\n");
+}
+// ─── Project Item Formatting ─────────────────────────────────────────────────
+/**
+ * Format a single GitHub Project item into a compact list entry.
+ */
+export function formatProjectItemEntry(item) {
+    const status = item.status ? ` (${item.status})` : "";
+    const type = item.type === "DRAFT_ISSUE" ? " [Draft]" : item.type === "PULL_REQUEST" ? " [PR]" : "";
+    const labels = item.labels.length > 0 ? ` [${item.labels.join(", ")}]` : "";
+    const assignees = item.assignees.length > 0 ? ` → ${item.assignees.join(", ")}` : "";
+    const ref = item.issueNumber ? `#${item.issueNumber}: ` : "";
+    return `${ref}${item.title}${type}${status}${labels}${assignees}`;
+}
+/**
+ * Format multiple project items into a list.
+ */
+export function formatProjectItemList(items) {
+    if (items.length === 0)
+        return "No project items found.";
+    return items.map((item) => formatProjectItemEntry(item)).join("\n");
+}
+// ─── GitHub CLI Data Fetching ────────────────────────────────────────────────
+/**
+ * Fetch GitHub projects associated with the repo owner.
+ */
+export async function fetchProjects(cwd, owner) {
+    try {
+        const { stdout } = await gh(cwd, "project", "list", "--owner", owner, "--format", "json");
+        const parsed = JSON.parse(stdout);
+        // gh project list --format json returns { projects: [...] }
+        const projects = parsed.projects ?? parsed ?? [];
+        return projects.map((p) => ({
+            id: String(p.id ?? ""),
+            number: Number(p.number ?? 0),
+            title: String(p.title ?? "Untitled"),
+        }));
+    }
+    catch (error) {
+        // Surface auth errors — these are actionable for the user.
+        // Other errors (no projects, API format changes) are non-critical.
+        const msg = error?.message ?? String(error);
+        if (msg.includes("auth") || msg.includes("401") || msg.includes("403")) {
+            throw new Error(`GitHub authentication error while fetching projects: ${msg}`);
+        }
+        return [];
+    }
+}
+/**
+ * Fetch issues from the current repository using gh CLI.
+ */
+export async function fetchIssues(cwd, options = {}) {
+    const args = [
+        "issue", "list",
+        "--json", "number,title,state,labels,assignees,milestone,body,url,createdAt,updatedAt",
+        "--limit", String(options.limit ?? 20),
+    ];
+    if (options.state)
+        args.push("--state", options.state);
+    if (options.labels)
+        args.push("--label", options.labels);
+    if (options.milestone)
+        args.push("--milestone", options.milestone);
+    if (options.assignee)
+        args.push("--assignee", options.assignee);
+    const { stdout } = await gh(cwd, ...args);
+    const raw = JSON.parse(stdout);
+    return raw.map((item) => ({
+        number: item.number,
+        title: item.title ?? "",
+        state: item.state ?? "open",
+        labels: (item.labels ?? []).map((l) => (typeof l === "string" ? l : l.name ?? "")),
+        assignees: (item.assignees ?? []).map((a) => (typeof a === "string" ? a : a.login ?? "")),
+        milestone: item.milestone?.title ?? undefined,
+        body: item.body ?? "",
+        url: item.url ?? "",
+        createdAt: item.createdAt ?? "",
+        updatedAt: item.updatedAt ?? "",
+    }));
+}
+/**
+ * Fetch project items from a specific GitHub Project.
+ */
+export async function fetchProjectItems(cwd, owner, projectNumber, options = {}) {
+    const { stdout } = await gh(cwd, "project", "item-list", String(projectNumber), "--owner", owner, "--format", "json", "--limit", String(options.limit ?? 30));
+    const parsed = JSON.parse(stdout);
+    // gh project item-list --format json returns { items: [...] }
+    const raw = parsed.items ?? parsed ?? [];
+    const items = raw.map((item) => ({
+        id: String(item.id ?? ""),
+        title: item.title ?? "",
+        type: normalizeItemType(item.type),
+        status: item.status ?? undefined,
+        assignees: Array.isArray(item.assignees)
+            ? item.assignees.map((a) => (typeof a === "string" ? a : a.login ?? ""))
+            : [],
+        labels: Array.isArray(item.labels)
+            ? item.labels.map((l) => (typeof l === "string" ? l : l.name ?? ""))
+            : [],
+        issueNumber: item.content?.number ?? undefined,
+        url: item.content?.url ?? undefined,
+        body: item.content?.body ?? undefined,
+    }));
+    // Apply status filter client-side if provided
+    if (options.status) {
+        const filterStatus = options.status.toLowerCase();
+        return items.filter((item) => item.status?.toLowerCase().includes(filterStatus));
+    }
+    return items;
+}
+/**
+ * Normalize the item type string from GitHub's API into our union type.
+ */
+function normalizeItemType(type) {
+    const t = String(type ?? "").toUpperCase();
+    if (t.includes("PULL") || t === "PULL_REQUEST")
+        return "PULL_REQUEST";
+    if (t.includes("DRAFT") || t === "DRAFT_ISSUE")
+        return "DRAFT_ISSUE";
+    return "ISSUE";
+}

package/dist/utils/ide.d.ts

@@ -0,0 +1,76 @@
+/**
+ * IDE Detection System
+ *
+ * Detects the current Integrated Development Environment or editor context.
+ * This is used to offer appropriate worktree launch options that match
+ * the user's current workflow.
+ *
+ * Detection is based on environment variables set by various IDEs when
+ * running terminal sessions within them.
+ */
+export type IDEType = "vscode" | "cursor" | "windsurf" | "jetbrains" | "zed" | "terminal" | "unknown";
+export interface IDEDetection {
+    type: IDEType;
+    name: string;
+    version?: string;
+    hasIntegratedTerminal: boolean;
+    canOpenInTerminal: boolean;
+    canOpenInWindow: boolean;
+    cliAvailable?: boolean;
+    cliBinary?: string;
+    cliInstallHint?: string;
+    detectionSource: string;
+}
+export interface EnvironmentRecommendation {
+    option: string;
+    priority: "high" | "medium" | "low";
+    reason: string;
+    mode?: "ide" | "terminal" | "pty" | "background" | "stay";
+}
+/**
+ * Detect the current IDE/editor environment.
+ * Checks environment variables, process hierarchy, and context clues.
+ */
+export declare function detectIDE(): IDEDetection;
+/**
+ * Get the command to open a worktree in the IDE's integrated terminal.
+ * Returns null if the IDE doesn't support CLI-based opening.
+ *
+ * Note: This function is currently unused but kept for future use.
+ * All inputs are escaped to prevent command injection.
+ */
+export declare function getIDEOpenCommand(ide: IDEDetection, worktreePath: string): string | null;
+/**
+ * Get the name of the CLI binary for the detected IDE.
+ * Returns null if no CLI is available or known.
+ */
+export declare function getIDECliBinary(ide: IDEDetection): string | null;
+/**
+ * Get a human-readable hint for installing an IDE's CLI binary.
+ * Each IDE has a different installation method.
+ */
+export declare function getInstallHint(type: IDEType, binary: string): string;
+/**
+ * Async version of detectIDE() that also checks whether the IDE's CLI binary
+ * is actually available in PATH. Use this in tools where you need to verify
+ * runtime availability before offering IDE launch options.
+ *
+ * The sync detectIDE() is preserved for non-async contexts.
+ */
+export declare function detectIDEWithCLICheck(): Promise<IDEDetection>;
+/**
+ * Check if we're already inside an IDE terminal.
+ * This helps determine if we should offer "stay here" as primary option.
+ */
+export declare function isInIDETerminal(): boolean;
+/**
+ * Generate contextual recommendations based on detected environment.
+ * Used by agents to offer appropriate launch options to users.
+ */
+export declare function generateEnvironmentRecommendations(ide: IDEDetection): EnvironmentRecommendation[];
+/**
+ * Format environment detection as a human-readable report.
+ * Used by the detect_environment tool.
+ */
+export declare function formatEnvironmentReport(ide: IDEDetection, terminalName: string): string;
+//# sourceMappingURL=ide.d.ts.map

package/dist/utils/ide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ide.d.ts","sourceRoot":"","sources":["../../src/utils/ide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,MAAM,OAAO,GACf,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,WAAW,GACX,KAAK,GACL,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,KAAK,GAAG,UAAU,GAAG,KAAK,GAAG,YAAY,GAAG,MAAM,CAAC;CAC3D;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,YAAY,CAoGxC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA6BxF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAahE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAapE;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,YAAY,CAAC,CAgBnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAGzC;AAED;;;GAGG;AACH,wBAAgB,kCAAkC,CAAC,GAAG,EAAE,YAAY,GAAG,yBAAyB,EAAE,CAkDjG;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAgDvF"}