@renseiai/agentfactory-linear 0.8.0

package/dist/src/issue-tracker-proxy.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Platform-Agnostic Issue Tracker Proxy Interface
+ *
+ * Defines the contract between agents/governors and the centralized proxy.
+ * Agents call these methods without knowing whether the backend is Linear,
+ * Jira, GitHub Issues, or any future platform.
+ *
+ * The proxy translates these generic operations into platform-specific API calls.
+ */
+/**
+ * Every proxy request carries authentication and workspace context.
+ */
+export interface ProxyRequest {
+    /** The operation to perform */
+    method: IssueTrackerMethod;
+    /** Arguments for the operation (method-specific) */
+    args: unknown[];
+    /** Workspace/organization ID for multi-tenant routing */
+    organizationId?: string;
+}
+/**
+ * Standard proxy response envelope.
+ */
+export interface ProxyResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+    /** Rate limit info from the upstream platform */
+    quota?: {
+        requestsRemaining?: number;
+        complexityRemaining?: number;
+        resetAt?: number;
+    };
+}
+/**
+ * All operations that can be routed through the proxy.
+ *
+ * Named generically (not Linear-specific) so future platforms
+ * can implement the same interface.
+ */
+export type IssueTrackerMethod = 'getIssue' | 'updateIssue' | 'createIssue' | 'createComment' | 'getIssueComments' | 'getTeamStatuses' | 'updateIssueStatus' | 'createAgentActivity' | 'updateAgentSession' | 'createAgentSessionOnIssue' | 'createIssueRelation' | 'getIssueRelations' | 'deleteIssueRelation' | 'getSubIssues' | 'getSubIssueStatuses' | 'getSubIssueGraph' | 'isParentIssue' | 'isChildIssue' | 'listProjectIssues' | 'getProjectRepositoryUrl' | 'getViewer' | 'getTeam' | 'unassignIssue';
+/**
+ * Serialized issue — all relations pre-resolved to plain JSON.
+ * No SDK-specific Promise fields or lazy loaders.
+ */
+export interface SerializedIssue {
+    id: string;
+    identifier: string;
+    title: string;
+    description?: string;
+    url: string;
+    priority: number;
+    state?: {
+        id: string;
+        name: string;
+        type: string;
+    };
+    labels: Array<{
+        id: string;
+        name: string;
+    }>;
+    assignee?: {
+        id: string;
+        name: string;
+        email?: string;
+    } | null;
+    team?: {
+        id: string;
+        name: string;
+        key: string;
+    };
+    parent?: {
+        id: string;
+        identifier: string;
+    } | null;
+    project?: {
+        id: string;
+        name: string;
+    } | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Serialized comment.
+ */
+export interface SerializedComment {
+    id: string;
+    body: string;
+    createdAt: string;
+    updatedAt: string;
+    user?: {
+        id: string;
+        name: string;
+    } | null;
+}
+/**
+ * Serialized viewer (authenticated user).
+ */
+export interface SerializedViewer {
+    id: string;
+    name: string;
+    email: string;
+}
+/**
+ * Serialized team.
+ */
+export interface SerializedTeam {
+    id: string;
+    name: string;
+    key: string;
+}
+/**
+ * Health status for the proxy endpoint.
+ */
+export interface ProxyHealthStatus {
+    /** Whether the proxy can process requests */
+    healthy: boolean;
+    /** Circuit breaker state */
+    circuitBreaker: {
+        state: string;
+        failures: number;
+        msSinceOpened: number | null;
+    };
+    /** Rate limiter status */
+    rateLimiter: {
+        availableTokens: number;
+    };
+    /** Upstream platform quota from response headers */
+    quota: {
+        requestsRemaining: number | null;
+        complexityRemaining: number | null;
+        resetAt: number | null;
+        updatedAt: number;
+    };
+}
+//# sourceMappingURL=issue-tracker-proxy.d.ts.map

package/dist/src/issue-tracker-proxy.d.ts.map

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

package/dist/src/issue-tracker-proxy.js

@@ -0,0 +1,10 @@
+/**
+ * Platform-Agnostic Issue Tracker Proxy Interface
+ *
+ * Defines the contract between agents/governors and the centralized proxy.
+ * Agents call these methods without knowing whether the backend is Linear,
+ * Jira, GitHub Issues, or any future platform.
+ *
+ * The proxy translates these generic operations into platform-specific API calls.
+ */
+export {};

package/dist/src/platform-adapter.d.ts

@@ -0,0 +1,132 @@
+/**
+ * LinearPlatformAdapter
+ *
+ * Extends LinearFrontendAdapter with Governor event integration methods.
+ * Structurally satisfies the PlatformAdapter interface from @renseiai/agentfactory
+ * without an explicit `implements` clause, avoiding a circular package dependency
+ * (core depends on linear, so linear cannot import core).
+ *
+ * Responsibilities:
+ * - Normalize Linear webhook payloads into GovernorEvents
+ * - Scan Linear projects for non-terminal issues
+ * - Convert Linear SDK Issue objects to GovernorIssue
+ */
+import { LinearFrontendAdapter } from './frontend-adapter.js';
+import type { LinearAgentClient } from './agent-client.js';
+/**
+ * Minimal issue representation used by the Governor.
+ * Structurally identical to GovernorIssue in @renseiai/agentfactory.
+ */
+export interface GovernorIssue {
+    id: string;
+    identifier: string;
+    title: string;
+    description?: string;
+    status: string;
+    labels: string[];
+    createdAt: number;
+    parentId?: string;
+    project?: string;
+}
+/** Where an event originated. */
+type EventSource = 'webhook' | 'poll' | 'manual';
+/**
+ * Fired when an issue's workflow status changes.
+ * Structurally identical to IssueStatusChangedEvent in @renseiai/agentfactory.
+ */
+interface IssueStatusChangedEvent {
+    type: 'issue-status-changed';
+    issueId: string;
+    issue: GovernorIssue;
+    previousStatus?: string;
+    newStatus: string;
+    timestamp: string;
+    source: EventSource;
+}
+/**
+ * Fired when a comment is added to an issue.
+ * Structurally identical to CommentAddedEvent in @renseiai/agentfactory.
+ */
+interface CommentAddedEvent {
+    type: 'comment-added';
+    issueId: string;
+    issue: GovernorIssue;
+    commentId: string;
+    commentBody: string;
+    userId?: string;
+    userName?: string;
+    timestamp: string;
+    source: EventSource;
+}
+/** Union of events this adapter can produce. */
+type GovernorEvent = IssueStatusChangedEvent | CommentAddedEvent;
+/**
+ * Linear platform adapter for the EventDrivenGovernor.
+ *
+ * Extends LinearFrontendAdapter to inherit all frontend operations
+ * (status mapping, issue read/write, agent sessions) and adds
+ * Governor-specific methods for webhook normalization, project scanning,
+ * and issue conversion.
+ *
+ * Structurally satisfies PlatformAdapter from @renseiai/agentfactory.
+ */
+export declare class LinearPlatformAdapter extends LinearFrontendAdapter {
+    /**
+     * The underlying Linear client, exposed to subclass methods.
+     * Re-declared here because the parent's `client` field is private.
+     */
+    private readonly linearAgentClient;
+    constructor(client: LinearAgentClient);
+    /**
+     * Normalize a raw Linear webhook payload into GovernorEvents.
+     *
+     * Handles two payload types:
+     * - Issue updates with state changes -> IssueStatusChangedEvent
+     * - Comment creations -> CommentAddedEvent
+     *
+     * Returns `null` for unrecognized payloads (e.g., label changes,
+     * AgentSession events, or other resource types).
+     *
+     * @param payload - Raw Linear webhook payload
+     * @returns Array of GovernorEvents, or null if not relevant
+     */
+    normalizeWebhookEvent(payload: unknown): GovernorEvent[] | null;
+    /**
+     * Scan a Linear project for all non-terminal issues.
+     *
+     * Uses a single GraphQL query via `listProjectIssues()` to fetch all
+     * issue data in one API call, eliminating the N+1 problem of lazy-loading
+     * state/labels/parent/project for each issue.
+     *
+     * @param project - Linear project name to scan
+     * @returns Array of GovernorIssue for all active issues
+     */
+    scanProjectIssues(project: string): Promise<GovernorIssue[]>;
+    /**
+     * Scan a project and return both GovernorIssues and a set of parent issue IDs.
+     *
+     * The parent issue IDs are derived from `childCount > 0` in the single
+     * GraphQL query, allowing callers to skip per-issue `isParentIssue()` API calls.
+     *
+     * @param project - Linear project name to scan
+     * @returns Issues and a set of parent issue IDs
+     */
+    scanProjectIssuesWithParents(project: string): Promise<{
+        issues: GovernorIssue[];
+        parentIssueIds: Set<string>;
+    }>;
+    /**
+     * Convert a Linear SDK Issue object to a GovernorIssue.
+     *
+     * The `native` parameter is typed as `unknown` to satisfy the
+     * PlatformAdapter interface. Internally it is cast to the Linear SDK
+     * `Issue` type. Callers must ensure they pass a valid Linear Issue.
+     *
+     * @param native - Linear SDK Issue object
+     * @returns GovernorIssue representation
+     * @throws Error if the native object is not a valid Linear Issue
+     */
+    toGovernorIssue(native: unknown): Promise<GovernorIssue>;
+}
+export {};
+//# sourceMappingURL=platform-adapter.d.ts.map

package/dist/src/platform-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-adapter.d.ts","sourceRoot":"","sources":["../../src/platform-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAY1D;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,iCAAiC;AACjC,KAAK,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEhD;;;GAGG;AACH,UAAU,uBAAuB;IAC/B,IAAI,EAAE,sBAAsB,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,aAAa,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,WAAW,CAAA;CACpB;AAED;;;GAGG;AACH,UAAU,iBAAiB;IACzB,IAAI,EAAE,eAAe,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,aAAa,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,WAAW,CAAA;CACpB;AAED,gDAAgD;AAChD,KAAK,aAAa,GAAG,uBAAuB,GAAG,iBAAiB,CAAA;AAmJhE;;;;;;;;;GASG;AACH,qBAAa,qBAAsB,SAAQ,qBAAqB;IAC9D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAmB;gBAEzC,MAAM,EAAE,iBAAiB;IAOrC;;;;;;;;;;;;OAYG;IACH,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,EAAE,GAAG,IAAI;IA0D/D;;;;;;;;;OASG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAgBlE;;;;;;;;OAQG;IACG,4BAA4B,CAChC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,MAAM,EAAE,aAAa,EAAE,CAAC;QAAC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;IA0BpE;;;;;;;;;;OAUG;IACG,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC;CAS/D"}

package/dist/src/platform-adapter.js

@@ -0,0 +1,260 @@
+/**
+ * LinearPlatformAdapter
+ *
+ * Extends LinearFrontendAdapter with Governor event integration methods.
+ * Structurally satisfies the PlatformAdapter interface from @renseiai/agentfactory
+ * without an explicit `implements` clause, avoiding a circular package dependency
+ * (core depends on linear, so linear cannot import core).
+ *
+ * Responsibilities:
+ * - Normalize Linear webhook payloads into GovernorEvents
+ * - Scan Linear projects for non-terminal issues
+ * - Convert Linear SDK Issue objects to GovernorIssue
+ */
+import { LinearFrontendAdapter } from './frontend-adapter.js';
+// ---------------------------------------------------------------------------
+// Terminal statuses
+// ---------------------------------------------------------------------------
+/**
+ * Statuses that represent terminal states in Linear.
+ * Issues in these states are excluded from project scans.
+ */
+const TERMINAL_STATUSES = ['Accepted', 'Canceled', 'Duplicate'];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Generate an ISO-8601 timestamp for the current moment.
+ * Equivalent to `eventTimestamp()` from @renseiai/agentfactory.
+ */
+function eventTimestamp() {
+    return new Date().toISOString();
+}
+/**
+ * Build a GovernorIssue from Linear webhook issue data.
+ * Does not make API calls -- uses only the data present in the webhook payload.
+ */
+function webhookIssueToGovernorIssue(issueData) {
+    return {
+        id: issueData.id,
+        identifier: issueData.identifier,
+        title: issueData.title,
+        description: issueData.description ?? undefined,
+        status: issueData.state?.name ?? 'Backlog',
+        labels: issueData.labels?.map((l) => l.name) ?? [],
+        createdAt: issueData.createdAt
+            ? new Date(issueData.createdAt).getTime()
+            : Date.now(),
+        parentId: issueData.parent?.id,
+        project: issueData.project?.name,
+    };
+}
+/**
+ * Convert a Linear SDK Issue object to a GovernorIssue.
+ * Resolves lazy-loaded relations (state, labels, parent, project).
+ */
+async function sdkIssueToGovernorIssue(issue) {
+    const state = await issue.state;
+    const labels = await issue.labels();
+    const parent = await issue.parent;
+    const project = await issue.project;
+    return {
+        id: issue.id,
+        identifier: issue.identifier,
+        title: issue.title,
+        description: issue.description ?? undefined,
+        status: state?.name ?? 'Backlog',
+        labels: labels.nodes.map((l) => l.name),
+        createdAt: issue.createdAt.getTime(),
+        parentId: parent?.id,
+        project: project?.name,
+    };
+}
+// ---------------------------------------------------------------------------
+// Type guards for webhook payloads
+// ---------------------------------------------------------------------------
+/**
+ * Check if a payload looks like a Linear issue webhook.
+ */
+function isIssuePayload(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return false;
+    const p = payload;
+    return (p.type === 'Issue' &&
+        typeof p.action === 'string' &&
+        typeof p.data === 'object' &&
+        p.data !== null);
+}
+/**
+ * Check if a payload looks like a Linear comment webhook.
+ */
+function isCommentPayload(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return false;
+    const p = payload;
+    return (p.type === 'Comment' &&
+        typeof p.action === 'string' &&
+        typeof p.data === 'object' &&
+        p.data !== null);
+}
+// ---------------------------------------------------------------------------
+// LinearPlatformAdapter
+// ---------------------------------------------------------------------------
+/**
+ * Linear platform adapter for the EventDrivenGovernor.
+ *
+ * Extends LinearFrontendAdapter to inherit all frontend operations
+ * (status mapping, issue read/write, agent sessions) and adds
+ * Governor-specific methods for webhook normalization, project scanning,
+ * and issue conversion.
+ *
+ * Structurally satisfies PlatformAdapter from @renseiai/agentfactory.
+ */
+export class LinearPlatformAdapter extends LinearFrontendAdapter {
+    /**
+     * The underlying Linear client, exposed to subclass methods.
+     * Re-declared here because the parent's `client` field is private.
+     */
+    linearAgentClient;
+    constructor(client) {
+        super(client);
+        this.linearAgentClient = client;
+    }
+    // ---- PlatformAdapter methods ----
+    /**
+     * Normalize a raw Linear webhook payload into GovernorEvents.
+     *
+     * Handles two payload types:
+     * - Issue updates with state changes -> IssueStatusChangedEvent
+     * - Comment creations -> CommentAddedEvent
+     *
+     * Returns `null` for unrecognized payloads (e.g., label changes,
+     * AgentSession events, or other resource types).
+     *
+     * @param payload - Raw Linear webhook payload
+     * @returns Array of GovernorEvents, or null if not relevant
+     */
+    normalizeWebhookEvent(payload) {
+        // Handle Issue update with state change
+        if (isIssuePayload(payload)) {
+            // Only handle updates (not creates/removes)
+            if (payload.action !== 'update')
+                return null;
+            // Only produce an event if the state actually changed
+            const hasStateChange = payload.updatedFrom?.stateId !== undefined;
+            if (!hasStateChange)
+                return null;
+            const issue = webhookIssueToGovernorIssue(payload.data);
+            const event = {
+                type: 'issue-status-changed',
+                issueId: payload.data.id,
+                issue,
+                newStatus: issue.status,
+                // Previous status name is not directly available from stateId alone;
+                // we only know the stateId changed. The previous status name would
+                // require an API call, so we leave it undefined.
+                previousStatus: undefined,
+                timestamp: eventTimestamp(),
+                source: 'webhook',
+            };
+            return [event];
+        }
+        // Handle Comment creation
+        if (isCommentPayload(payload)) {
+            if (payload.action !== 'create')
+                return null;
+            const commentData = payload.data;
+            const issueData = commentData.issue;
+            if (!issueData)
+                return null;
+            const issue = webhookIssueToGovernorIssue(issueData);
+            const event = {
+                type: 'comment-added',
+                issueId: issueData.id,
+                issue,
+                commentId: commentData.id,
+                commentBody: commentData.body,
+                userId: commentData.user?.id,
+                userName: commentData.user?.name,
+                timestamp: eventTimestamp(),
+                source: 'webhook',
+            };
+            return [event];
+        }
+        // Unrecognized payload type
+        return null;
+    }
+    /**
+     * Scan a Linear project for all non-terminal issues.
+     *
+     * Uses a single GraphQL query via `listProjectIssues()` to fetch all
+     * issue data in one API call, eliminating the N+1 problem of lazy-loading
+     * state/labels/parent/project for each issue.
+     *
+     * @param project - Linear project name to scan
+     * @returns Array of GovernorIssue for all active issues
+     */
+    async scanProjectIssues(project) {
+        const issues = await this.linearAgentClient.listProjectIssues(project);
+        return issues.map((issue) => ({
+            id: issue.id,
+            identifier: issue.identifier,
+            title: issue.title,
+            description: issue.description,
+            status: issue.status,
+            labels: issue.labels,
+            createdAt: issue.createdAt,
+            parentId: issue.parentId,
+            project: issue.project,
+        }));
+    }
+    /**
+     * Scan a project and return both GovernorIssues and a set of parent issue IDs.
+     *
+     * The parent issue IDs are derived from `childCount > 0` in the single
+     * GraphQL query, allowing callers to skip per-issue `isParentIssue()` API calls.
+     *
+     * @param project - Linear project name to scan
+     * @returns Issues and a set of parent issue IDs
+     */
+    async scanProjectIssuesWithParents(project) {
+        const rawIssues = await this.linearAgentClient.listProjectIssues(project);
+        const parentIssueIds = new Set();
+        const issues = [];
+        for (const issue of rawIssues) {
+            if (issue.childCount > 0) {
+                parentIssueIds.add(issue.id);
+            }
+            issues.push({
+                id: issue.id,
+                identifier: issue.identifier,
+                title: issue.title,
+                description: issue.description,
+                status: issue.status,
+                labels: issue.labels,
+                createdAt: issue.createdAt,
+                parentId: issue.parentId,
+                project: issue.project,
+            });
+        }
+        return { issues, parentIssueIds };
+    }
+    /**
+     * Convert a Linear SDK Issue object to a GovernorIssue.
+     *
+     * The `native` parameter is typed as `unknown` to satisfy the
+     * PlatformAdapter interface. Internally it is cast to the Linear SDK
+     * `Issue` type. Callers must ensure they pass a valid Linear Issue.
+     *
+     * @param native - Linear SDK Issue object
+     * @returns GovernorIssue representation
+     * @throws Error if the native object is not a valid Linear Issue
+     */
+    async toGovernorIssue(native) {
+        const issue = native;
+        if (!issue || typeof issue.id !== 'string') {
+            throw new Error('LinearPlatformAdapter.toGovernorIssue: expected a Linear SDK Issue object');
+        }
+        return sdkIssueToGovernorIssue(issue);
+    }
+}

package/dist/src/platform-adapter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=platform-adapter.test.d.ts.map

package/dist/src/platform-adapter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-adapter.test.d.ts","sourceRoot":"","sources":["../../src/platform-adapter.test.ts"],"names":[],"mappings":""}