@renseiai/agentfactory-linear 0.8.0

package/dist/src/agent-session.d.ts

@@ -0,0 +1,303 @@
+import type { Issue } from '@linear/sdk';
+import type { AgentSessionState, AgentSessionConfig, CreateActivityOptions, AgentPlan, AgentPlanItem, AgentPlanItemState, SessionOperationResult, AgentActivityContentPayload, AgentActivitySignal, AgentActivityResult, IssueRelationResult, IssueRelationInfo } from './types.js';
+import { type EnvironmentIssueType } from './constants.js';
+import { type CheckboxItem, type CheckboxUpdate } from './checkbox-utils.js';
+/**
+ * Agent Session Handler
+ * Manages the lifecycle of an agent working on a Linear issue
+ */
+export declare class AgentSession {
+    private readonly client;
+    private readonly issueId;
+    private readonly autoTransition;
+    private readonly workType;
+    private sessionId;
+    private state;
+    private currentPlan;
+    private issue;
+    private activityLog;
+    constructor(config: AgentSessionConfig);
+    get currentState(): AgentSessionState;
+    get id(): string | null;
+    get plan(): AgentPlan;
+    get activities(): Array<{
+        type: string;
+        timestamp: Date;
+        content: string;
+    }>;
+    /**
+     * Add or update an external URL for the session
+     * External URLs appear in the Linear issue view, linking to dashboards, logs, or PRs
+     *
+     * @param label - Display label for the URL (e.g., "Pull Request", "Logs")
+     * @param url - The URL to link to
+     */
+    addExternalUrl(label: string, url: string): Promise<void>;
+    /**
+     * Set the pull request URL for this session
+     * This unlocks additional PR-related features in Linear
+     *
+     * @param prUrl - The GitHub pull request URL
+     * @see https://linear.app/developers/agents
+     */
+    setPullRequestUrl(prUrl: string): Promise<void>;
+    /**
+     * Start the agent session
+     *
+     * Transitions issue status based on work type:
+     * - development: Backlog -> Started
+     * - Other work types: No transition on start (issue stays in current status)
+     */
+    start(): Promise<SessionOperationResult>;
+    /**
+     * Mark session as awaiting user input
+     */
+    awaitInput(prompt: string): Promise<void>;
+    /**
+     * Complete the session successfully
+     *
+     * Transitions issue status based on work type:
+     * - development/inflight: Started -> Finished
+     * - qa: Finished -> Delivered (only if workResult === 'passed')
+     * - acceptance: Delivered -> Accepted (only if workResult === 'passed')
+     * - refinement: Rejected -> Backlog
+     * - research: No transition (user decides when to move to Backlog)
+     *
+     * @param summary - Optional completion summary to post as a comment
+     * @param workResult - For QA/acceptance: 'passed' promotes, 'failed' transitions to fail status, undefined skips transition
+     */
+    complete(summary?: string, workResult?: 'passed' | 'failed'): Promise<SessionOperationResult>;
+    /**
+     * Mark session as failed
+     * Emits an error activity (auto-generates comment) if session ID is available,
+     * otherwise falls back to creating a comment directly.
+     */
+    fail(errorMessage: string): Promise<SessionOperationResult>;
+    /**
+     * Emit a generic activity (legacy method for backward compatibility)
+     * @deprecated Use createActivity for native Linear Agent API
+     */
+    emitActivity(options: CreateActivityOptions): Promise<void>;
+    /**
+     * Create an activity using the native Linear Agent API
+     *
+     * @param content - The activity content payload
+     * @param ephemeral - Whether the activity should disappear after the next activity
+     * @param signal - Optional modifier for how the activity should be interpreted
+     * @returns Result containing success status and activity ID
+     */
+    createActivity(content: AgentActivityContentPayload, ephemeral?: boolean, signal?: AgentActivitySignal): Promise<AgentActivityResult>;
+    /**
+     * Emit a thought activity (persistent by default for visibility in Linear)
+     */
+    emitThought(text: string, ephemeral?: boolean): Promise<void>;
+    /**
+     * Emit an action activity (tool call)
+     */
+    emitAction(toolName: string, input: Record<string, unknown>, ephemeral?: boolean): Promise<void>;
+    /**
+     * Emit a tool result activity
+     */
+    emitToolResult(toolName: string, output: unknown, ephemeral?: boolean): Promise<void>;
+    /**
+     * Emit a response activity (persisted)
+     */
+    emitResponse(text: string): Promise<void>;
+    /**
+     * Emit an error activity using native API
+     */
+    emitError(error: Error): Promise<void>;
+    /**
+     * Emit an elicitation activity - asking for clarification from the user
+     */
+    emitElicitation(text: string, ephemeral?: boolean): Promise<AgentActivityResult | void>;
+    /**
+     * Emit a prompt activity - prompts/instructions for the user
+     */
+    emitPrompt(text: string, ephemeral?: boolean): Promise<AgentActivityResult | void>;
+    /**
+     * Emit an authentication required activity
+     * Shows an authentication prompt to the user with a link to authorize
+     *
+     * @param authUrl - The URL the user should visit to authenticate
+     * @param providerName - Optional name of the auth provider (e.g., "GitHub", "Google")
+     * @param body - Optional custom message body
+     * @returns Activity result with ID
+     *
+     * @see https://linear.app/developers/agent-signals
+     */
+    emitAuthRequired(authUrl: string, providerName?: string, body?: string): Promise<AgentActivityResult>;
+    /**
+     * Emit a selection prompt activity
+     * Shows a multiple choice selection to the user
+     *
+     * @param prompt - The question or prompt for the user
+     * @param options - Array of option strings the user can select from
+     * @returns Activity result with ID
+     *
+     * @see https://linear.app/developers/agent-signals
+     */
+    emitSelect(prompt: string, options: string[]): Promise<AgentActivityResult>;
+    /**
+     * Report an environment issue for self-improvement.
+     * Creates a bug in the Agent project backlog to track infrastructure improvements.
+     *
+     * This is a best-effort operation - failures are logged but don't propagate.
+     *
+     * @param title - Short description of the issue
+     * @param description - Detailed explanation of what happened
+     * @param context - Additional context about the issue
+     * @returns The created issue, or null if creation failed
+     */
+    reportEnvironmentIssue(title: string, description: string, context?: {
+        issueType?: EnvironmentIssueType;
+        sourceIssueId?: string;
+        errorStack?: string;
+        additionalContext?: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+        identifier: string;
+        url: string;
+    } | null>;
+    /**
+     * Report a human-needed blocker issue.
+     * Creates an issue in Icebox with "Needs Human" label, linked as blocking the current issue.
+     *
+     * This is a best-effort operation - failures are logged but don't propagate.
+     *
+     * @param title - Short description of what the human needs to do
+     * @param description - Detailed steps or context for the human
+     * @param options - Optional overrides for project and assignee
+     * @returns The created blocker issue, or null if creation failed
+     */
+    reportHumanBlocker(title: string, description: string, options?: {
+        projectId?: string;
+        assigneeId?: string;
+    }): Promise<{
+        id: string;
+        identifier: string;
+        url: string;
+    } | null>;
+    /**
+     * Create an agent session on a sub-issue for activity reporting
+     *
+     * The coordinator uses this to emit activities to individual sub-issue threads,
+     * making sub-agent progress visible on each sub-issue in Linear.
+     *
+     * @param subIssueId - The sub-issue ID (UUID) to create a session on
+     * @returns The session ID for the sub-issue, or null if creation failed
+     */
+    createSubIssueSession(subIssueId: string): Promise<string | null>;
+    /**
+     * Emit an activity to a sub-issue's agent session
+     *
+     * Used by the coordinator to report progress on individual sub-issues.
+     * Falls back to creating a comment if the activity emission fails.
+     *
+     * @param subIssueSessionId - The agent session ID for the sub-issue
+     * @param content - The activity content to emit
+     * @param ephemeral - Whether the activity is ephemeral (default: false)
+     */
+    emitSubIssueActivity(subIssueSessionId: string, content: AgentActivityContentPayload, ephemeral?: boolean): Promise<void>;
+    /**
+     * Get the current issue description
+     * Refreshes the issue data from Linear if needed
+     */
+    getDescription(): Promise<string | undefined>;
+    /**
+     * Parse checkboxes from the issue description
+     *
+     * @returns Array of checkbox items, or empty array if no description
+     */
+    getDescriptionCheckboxes(): Promise<CheckboxItem[]>;
+    /**
+     * Update checkboxes in the issue description
+     *
+     * @param updates - Array of updates to apply
+     * @returns The updated issue, or null if no changes were made
+     */
+    updateDescriptionCheckboxes(updates: CheckboxUpdate[]): Promise<Issue | null>;
+    /**
+     * Mark a specific task as complete in the issue description
+     *
+     * @param textPattern - String or regex to match the task text
+     * @returns The updated issue, or null if task not found
+     */
+    completeDescriptionTask(textPattern: string | RegExp): Promise<Issue | null>;
+    /**
+     * Mark a specific task as incomplete in the issue description
+     *
+     * @param textPattern - String or regex to match the task text
+     * @returns The updated issue, or null if task not found
+     */
+    uncompleteDescriptionTask(textPattern: string | RegExp): Promise<Issue | null>;
+    /**
+     * Link this issue as related to another issue
+     *
+     * @param relatedIssueId - The issue ID or identifier to link to
+     * @returns Result with relation ID, or null if relation already exists
+     */
+    linkRelatedIssue(relatedIssueId: string): Promise<IssueRelationResult | null>;
+    /**
+     * Mark this issue as blocked by another issue
+     *
+     * @param blockingIssueId - The issue ID or identifier that blocks this one
+     * @returns Result with relation ID, or null if relation already exists
+     */
+    markAsBlockedBy(blockingIssueId: string): Promise<IssueRelationResult | null>;
+    /**
+     * Mark this issue as blocking another issue
+     *
+     * @param blockedIssueId - The issue ID or identifier that this issue blocks
+     * @returns Result with relation ID, or null if relation already exists
+     */
+    markAsBlocking(blockedIssueId: string): Promise<IssueRelationResult | null>;
+    /**
+     * Mark this issue as a duplicate of another issue
+     *
+     * @param originalIssueId - The original issue ID or identifier
+     * @returns Result with relation ID, or null if relation already exists
+     */
+    markAsDuplicateOf(originalIssueId: string): Promise<IssueRelationResult | null>;
+    /**
+     * Get issues that are blocking this issue
+     *
+     * @returns Array of relation info for blocking issues
+     */
+    getBlockers(): Promise<IssueRelationInfo[]>;
+    /**
+     * Check if this issue is blocked by any other issues
+     *
+     * @returns True if blocked, false otherwise
+     */
+    isBlocked(): Promise<boolean>;
+    /**
+     * Update the agent's plan (full replacement)
+     *
+     * Uses Linear's native agentSessionUpdate mutation to display the plan
+     * as checkboxes in the Linear UI. Also maintains internal plan state
+     * for checkbox sync and completion tracking.
+     */
+    updatePlan(items: Omit<AgentPlanItem, 'id'>[]): Promise<void>;
+    /**
+     * Flatten nested plan items into Linear's flat format
+     * Converts: { title, state, children } -> { content, status }
+     */
+    private flattenPlanItems;
+    /**
+     * Update a single plan item's state
+     * Also updates the plan in Linear's native API and syncs description checkboxes
+     */
+    updatePlanItemState(itemId: string, state: AgentPlanItemState): Promise<void>;
+    /**
+     * Create a plan item helper
+     */
+    createPlanItem(title: string, state?: AgentPlanItemState, details?: string): Omit<AgentPlanItem, 'id'>;
+    private formatActivityAsComment;
+    private postCompletionComment;
+}
+/**
+ * Create a new agent session
+ */
+export declare function createAgentSession(config: AgentSessionConfig): AgentSession;
+//# sourceMappingURL=agent-session.d.ts.map

package/dist/src/agent-session.d.ts.map

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