@dahrk/linear 0.1.0

package/dist/linear-client.js

@@ -0,0 +1,198 @@
+/**
+ * The real Agent Session client over `@linear/sdk` (build spec section 14). This is the
+ * LIVE path - it makes authenticated GraphQL calls to Linear - so it is only constructed
+ * when a Connection carries a bearer token; the offline harness uses the recording client.
+ *
+ * Verified against @linear/sdk v86: `createAgentActivity({ agentSessionId, content, signal?,
+ * signalMetadata?, ephemeral? })` (content is an untyped JSONObject - the typed payload shapes
+ * are in Linear's agent-interaction docs), `updateAgentSession(id, { plan, externalUrls })`,
+ * `agentSession(id)` (resolves the issue), `updateIssue(id, { stateId, delegateId })`,
+ * `team(id).states({ filter })`, `viewer`, and `createAttachment({ issueId, url, title, ... })`.
+ * There is no app-settable session `state`: Linear derives it from activities and signals, so
+ * `setState` is a no-op here.
+ */
+import { AgentActivitySignal, LinearClient } from "@linear/sdk";
+import { filterExternalUrls } from "./index.js";
+/** Build the (untyped) activity content payload Linear expects for each activity type. */
+function contentOf(a) {
+    switch (a.type) {
+        case "thought":
+            return { type: "thought", body: a.text };
+        case "response":
+            return { type: "response", body: a.text };
+        case "error":
+            return { type: "error", body: a.text };
+        case "action":
+            return { type: "action", action: a.tool ?? "tool", parameter: a.text };
+    }
+}
+/** Normalise an elicitation option into Linear's `{ label?, value }` shape. */
+function optionOf(o) {
+    return typeof o === "string" ? { value: o } : { ...(o.label ? { label: o.label } : {}), value: o.value };
+}
+export function createLinearClient(token) {
+    const client = new LinearClient({ accessToken: token });
+    return {
+        async postActivity(sessionId, activity) {
+            await client.createAgentActivity({
+                agentSessionId: sessionId,
+                content: contentOf(activity),
+                // Only thought/action may be ephemeral; the caller guarantees this, Linear ignores it otherwise.
+                ...(activity.ephemeral ? { ephemeral: true } : {}),
+            });
+        },
+        async raiseElicitation(sessionId, prompt, options) {
+            await client.createAgentActivity({
+                agentSessionId: sessionId,
+                content: { type: "elicitation", body: prompt },
+                signal: AgentActivitySignal.Select,
+                ...(options ? { signalMetadata: { options: options.map(optionOf) } } : {}),
+            });
+        },
+        async suggestRepositories(issueId, candidates) {
+            // Linear ranks the candidates we already have access to; we keep its order and never re-sort by
+            // confidence ourselves (ordering only - the human picks). `hostname` is required by the API.
+            const payload = await client.issueRepositorySuggestions(candidates.map((c) => ({ hostname: c.hostname ?? "", repositoryFullName: c.repositoryFullName })), issueId);
+            return payload.suggestions.map((s) => ({
+                repositoryFullName: s.repositoryFullName,
+                ...(s.hostname ? { hostname: s.hostname } : {}),
+                confidence: s.confidence,
+            }));
+        },
+        async addIssueLabel(issueId, name) {
+            // Get-or-create the label by name (issueAddLabel needs an id), then attach it. Idempotent:
+            // createIssueLabel only runs when the name is absent, and issueAddLabel no-ops on a label the
+            // issue already carries, so a repeat stamp is a safe no-op.
+            const labels = await client.issueLabels();
+            while (labels.pageInfo.hasNextPage)
+                await labels.fetchNext();
+            let labelId = labels.nodes.find((l) => l.name === name)?.id;
+            if (!labelId) {
+                const created = await client.createIssueLabel({ name });
+                labelId = (await created.issueLabel)?.id;
+            }
+            if (labelId)
+                await client.issueAddLabel(issueId, labelId);
+        },
+        async requestAuth(sessionId, prompt, auth) {
+            // The `auth` signal renders Linear's native account-linking UI from an elicitation; the user
+            // completes the link at `auth.url`, then the agent resumes on the follow-up `prompted` webhook.
+            await client.createAgentActivity({
+                agentSessionId: sessionId,
+                content: { type: "elicitation", body: prompt },
+                signal: AgentActivitySignal.Auth,
+                signalMetadata: {
+                    url: auth.url,
+                    ...(auth.userId ? { userId: auth.userId } : {}),
+                    ...(auth.providerName ? { providerName: auth.providerName } : {}),
+                },
+            });
+        },
+        async startIssue(sessionId) {
+            // Resolve the issue from the session itself, so no issue id has to be threaded through the engine.
+            const session = await client.agentSession(sessionId);
+            const issue = await session.issue;
+            if (!issue)
+                return;
+            // Self-delegate (idempotent: assignment already sets the app as delegate; @mention does not).
+            const me = await client.viewer;
+            const update = { delegateId: me.id };
+            // Move to the team's first `started` state, but only from a not-yet-started status.
+            const current = await issue.state;
+            if (current && current.type !== "started" && current.type !== "completed" && current.type !== "canceled") {
+                const team = await issue.team;
+                if (team) {
+                    const states = await team.states({ filter: { type: { eq: "started" } } });
+                    const first = [...states.nodes].sort((a, b) => a.position - b.position)[0];
+                    if (first)
+                        update.stateId = first.id;
+                }
+            }
+            await client.updateIssue(issue.id, update);
+        },
+        async moveIssueToReview(sessionId) {
+            const session = await client.agentSession(sessionId);
+            const issue = await session.issue;
+            if (!issue)
+                return;
+            // Never disturb a closed issue.
+            const current = await issue.state;
+            if (current && (current.type === "completed" || current.type === "canceled"))
+                return;
+            const team = await issue.team;
+            if (!team)
+                return;
+            // Linear has no "review" state TYPE, so match by name. Prefer an explicit configured name,
+            // else the first state whose name looks review-ish. No match = leave the issue in `started`
+            // (never auto-complete), so a human keeps iterating and can re-summon @Skakel on the same PR.
+            const wanted = (process.env.SKAKEL_REVIEW_STATE_NAME ?? "").trim().toLowerCase();
+            const states = [...(await team.states()).nodes].sort((a, b) => a.position - b.position);
+            const pick = wanted
+                ? states.find((s) => s.name.toLowerCase() === wanted)
+                : states.find((s) => /review|in review|qa/i.test(s.name));
+            if (!pick || (current && pick.id === current.id))
+                return;
+            await client.updateIssue(issue.id, { stateId: pick.id });
+        },
+        async commentOnIssue(sessionId, body) {
+            // A normal top-level issue comment (not an agent activity), so a run summary lands in the
+            // issue's comment thread where a human reads it, rather than only in the agent session panel.
+            const session = await client.agentSession(sessionId);
+            const issue = await session.issue;
+            if (!issue)
+                return;
+            await client.createComment({ issueId: issue.id, body });
+        },
+        async attachPr(sessionId, pr) {
+            // Idempotent by URL: Linear's `attachmentCreate` upserts on (issueId, url) - a second call with
+            // the same `pr.url` on the same issue UPDATES the existing attachment rather than creating a
+            // duplicate. This is what lets the host loop retry `open-pr` (e.g. after a crash/replay) without
+            // littering the issue with duplicate PR attachments; the reporter relies on the same invariant.
+            const session = await client.agentSession(sessionId);
+            const issue = await session.issue;
+            if (!issue)
+                return;
+            await client.createAttachment({
+                issueId: issue.id,
+                url: pr.url,
+                title: pr.title,
+                ...(pr.subtitle ? { subtitle: pr.subtitle } : {}),
+                ...(pr.iconUrl ? { iconUrl: pr.iconUrl } : {}),
+            });
+        },
+        async createDocument(sessionId, doc) {
+            // Resolve the issue from the session so no issue id has to be threaded through the engine,
+            // mirroring attachPr. `documentCreate` with an issueId links the document to the issue.
+            const session = await client.agentSession(sessionId);
+            const issue = await session.issue;
+            const payload = await client.createDocument({
+                title: doc.title,
+                content: doc.content,
+                ...(issue ? { issueId: issue.id } : {}),
+            });
+            const created = await payload.document;
+            return { id: created?.id ?? payload.documentId ?? "", url: created?.url ?? "" };
+        },
+        async setPlan(sessionId, items) {
+            // Linear expects the plan as a full array of { content, status } steps (replaced wholesale),
+            // NOT a wrapper object. Our PlanItem.status values (pending|inProgress|completed|canceled)
+            // already match Linear's enum; show the human title (falling back to the stage id) as content.
+            await client.updateAgentSession(sessionId, {
+                plan: items.map((i) => ({ content: i.title ?? i.stageId, status: i.status })),
+            });
+        },
+        async setExternalUrls(sessionId, urls) {
+            // Linear rejects non-http(s) URLs (e.g. internal skakel:// run refs) and requires each URL to be
+            // unique; filterExternalUrls drops the rest. The array is replaced wholesale, so no-op on empty
+            // rather than clobber any existing links with nothing.
+            const valid = filterExternalUrls(urls);
+            if (valid.length === 0)
+                return;
+            await client.updateAgentSession(sessionId, { externalUrls: valid });
+        },
+        async setState() {
+            // Linear derives the agent-session state from activities/signals; not app-settable.
+        },
+    };
+}
+//# sourceMappingURL=linear-client.js.map

package/dist/linear-client.js.map

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

package/dist/oauth.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Linear OAuth 2.0 helpers for the agent install + token rotation (build spec section 14).
+ *
+ * An agent becomes assignable/mentionable in a workspace only while the app is INSTALLED via
+ * the authorization-code flow with `actor=app` and the `app:assignable` / `app:mentionable`
+ * scopes (admin consent). That flow also yields the access + refresh tokens the hub posts with.
+ * Access tokens last ~24h, so the hub refreshes them with the refresh token (see the hub's
+ * `resolveClient`). Plain `fetch`, no SDK; cyrus is a reference, not a dependency.
+ */
+/** The agent scopes: read/write plus the two that make the app assignable + mentionable. */
+export declare const DEFAULT_AGENT_SCOPES: readonly ["read", "write", "app:assignable", "app:mentionable"];
+export interface LinearTokens {
+    accessToken: string;
+    /** Absent on some refresh responses; callers keep the prior refresh token when so. */
+    refreshToken?: string;
+    /** When the access token expires (computed from `expires_in`). */
+    expiresAt: Date;
+    scope?: string;
+}
+/**
+ * Build the Linear consent URL. The admin opens this; approving installs the agent (with
+ * `actor=app`) and redirects to `redirectUri?code=...&state=...`. `state` is opaque here - the
+ * caller signs it (CSRF) and recovers the connection from it in the callback.
+ */
+export declare function authorizeUrl(params: {
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    scopes?: readonly string[];
+    actor?: "app" | "user";
+}): string;
+/** Exchange the callback `code` for access + refresh tokens (one-time, at install). */
+export declare function exchangeCode(params: {
+    clientId: string;
+    clientSecret: string;
+    code: string;
+    redirectUri: string;
+}, now?: () => Date): Promise<LinearTokens>;
+/**
+ * Resolve the workspace (organization) id the access token belongs to. Used at install to backfill
+ * a connection's `workspaceIds` from the token, so an operator need not paste the org id by hand and
+ * intake can match the workspace on the very first webhook. Plain GraphQL fetch, no SDK.
+ */
+export declare function fetchOrganizationId(accessToken: string): Promise<string>;
+/** The agent identity + bound workspace a token resolves to, for the connection Probe. */
+export interface LinearProbe {
+    viewer?: {
+        id: string;
+        name?: string;
+    };
+    organization?: {
+        id: string;
+        name?: string;
+        urlKey?: string;
+    };
+}
+/**
+ * Probe a stored access token: query `viewer` (the app/agent user) and `organization` (the bound
+ * workspace) so the portal can confirm a connection's token is valid and show which workspace it
+ * binds to. Throws on an auth failure / GraphQL error, which the caller renders as "token invalid".
+ */
+export declare function probeToken(accessToken: string): Promise<LinearProbe>;
+/** Rotate the access token using the stored refresh token (the hub calls this near expiry / on 401). */
+export declare function refreshTokens(params: {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+}, now?: () => Date): Promise<LinearTokens>;
+/**
+ * Mint an `app` actor token via the `client_credentials` grant: headless (no user, no redirect, no
+ * callback, no refresh token), scoped to the app's workspace, valid ~30 days. Linear's documented
+ * renewal is simply to mint a fresh one on a 401/expiry. Requires the app's "Client credentials"
+ * toggle to be enabled. This is the durable token path for a headless agent, vs the interactive
+ * authorization-code flow (24h token + fragile refresh + "already installed" install UX).
+ */
+export declare function mintAppToken(params: {
+    clientId: string;
+    clientSecret: string;
+    scopes?: readonly string[];
+}, now?: () => Date): Promise<LinearTokens>;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,4FAA4F;AAC5F,eAAO,MAAM,oBAAoB,iEAAkE,CAAC;AAEpG,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,SAAS,EAAE,IAAI,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACxB,GAAG,MAAM,CAWT;AA+BD,uFAAuF;AACvF,wBAAgB,YAAY,CAC1B,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EACrF,GAAG,GAAE,MAAM,IAAuB,GACjC,OAAO,CAAC,YAAY,CAAC,CAWvB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB9E;AAED,0FAA0F;AAC1F,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,YAAY,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/D;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAoB1E;AAED,wGAAwG;AACxG,wBAAgB,aAAa,CAC3B,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EACxE,GAAG,GAAE,MAAM,IAAuB,GACjC,OAAO,CAAC,YAAY,CAAC,CAUvB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAC9E,GAAG,GAAE,MAAM,IAAuB,GACjC,OAAO,CAAC,YAAY,CAAC,CAUvB"}

package/dist/oauth.js

@@ -0,0 +1,127 @@
+/**
+ * Linear OAuth 2.0 helpers for the agent install + token rotation (build spec section 14).
+ *
+ * An agent becomes assignable/mentionable in a workspace only while the app is INSTALLED via
+ * the authorization-code flow with `actor=app` and the `app:assignable` / `app:mentionable`
+ * scopes (admin consent). That flow also yields the access + refresh tokens the hub posts with.
+ * Access tokens last ~24h, so the hub refreshes them with the refresh token (see the hub's
+ * `resolveClient`). Plain `fetch`, no SDK; cyrus is a reference, not a dependency.
+ */
+const AUTHORIZE_URL = "https://linear.app/oauth/authorize";
+const TOKEN_URL = "https://api.linear.app/oauth/token";
+const GRAPHQL_URL = "https://api.linear.app/graphql";
+/** The agent scopes: read/write plus the two that make the app assignable + mentionable. */
+export const DEFAULT_AGENT_SCOPES = ["read", "write", "app:assignable", "app:mentionable"];
+/**
+ * Build the Linear consent URL. The admin opens this; approving installs the agent (with
+ * `actor=app`) and redirects to `redirectUri?code=...&state=...`. `state` is opaque here - the
+ * caller signs it (CSRF) and recovers the connection from it in the callback.
+ */
+export function authorizeUrl(params) {
+    const u = new URL(AUTHORIZE_URL);
+    u.searchParams.set("client_id", params.clientId);
+    u.searchParams.set("redirect_uri", params.redirectUri);
+    u.searchParams.set("response_type", "code");
+    u.searchParams.set("scope", (params.scopes ?? DEFAULT_AGENT_SCOPES).join(","));
+    u.searchParams.set("state", params.state);
+    u.searchParams.set("actor", params.actor ?? "app");
+    // Force the consent screen so re-installing always re-grants (and re-issues a refresh token).
+    u.searchParams.set("prompt", "consent");
+    return u.toString();
+}
+async function postToken(body, now) {
+    const res = await fetch(TOKEN_URL, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(body).toString(),
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok || !json.access_token) {
+        const detail = json.error_description || json.error || `${res.status}`;
+        throw new Error(`linear token endpoint failed: ${detail}`);
+    }
+    const expiresIn = typeof json.expires_in === "number" ? json.expires_in : 86_399;
+    return {
+        accessToken: json.access_token,
+        ...(json.refresh_token ? { refreshToken: json.refresh_token } : {}),
+        expiresAt: new Date(now().getTime() + expiresIn * 1000),
+        ...(json.scope ? { scope: json.scope } : {}),
+    };
+}
+/** Exchange the callback `code` for access + refresh tokens (one-time, at install). */
+export function exchangeCode(params, now = () => new Date()) {
+    return postToken({
+        grant_type: "authorization_code",
+        client_id: params.clientId,
+        client_secret: params.clientSecret,
+        code: params.code,
+        redirect_uri: params.redirectUri,
+    }, now);
+}
+/**
+ * Resolve the workspace (organization) id the access token belongs to. Used at install to backfill
+ * a connection's `workspaceIds` from the token, so an operator need not paste the org id by hand and
+ * intake can match the workspace on the very first webhook. Plain GraphQL fetch, no SDK.
+ */
+export async function fetchOrganizationId(accessToken) {
+    const res = await fetch(GRAPHQL_URL, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: accessToken },
+        body: JSON.stringify({ query: "query { organization { id } }" }),
+    });
+    const json = (await res.json().catch(() => ({})));
+    const id = json.data?.organization?.id;
+    if (!res.ok || !id) {
+        const detail = json.errors?.[0]?.message || `${res.status}`;
+        throw new Error(`linear organization query failed: ${detail}`);
+    }
+    return id;
+}
+/**
+ * Probe a stored access token: query `viewer` (the app/agent user) and `organization` (the bound
+ * workspace) so the portal can confirm a connection's token is valid and show which workspace it
+ * binds to. Throws on an auth failure / GraphQL error, which the caller renders as "token invalid".
+ */
+export async function probeToken(accessToken) {
+    const res = await fetch(GRAPHQL_URL, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: accessToken },
+        body: JSON.stringify({ query: "query { viewer { id name } organization { id name urlKey } }" }),
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok || json.errors?.length || !json.data) {
+        const detail = json.errors?.[0]?.message || `${res.status}`;
+        throw new Error(`linear probe failed: ${detail}`);
+    }
+    const v = json.data.viewer;
+    const o = json.data.organization;
+    return {
+        ...(v?.id ? { viewer: { id: v.id, ...(v.name ? { name: v.name } : {}) } } : {}),
+        ...(o?.id ? { organization: { id: o.id, ...(o.name ? { name: o.name } : {}), ...(o.urlKey ? { urlKey: o.urlKey } : {}) } } : {}),
+    };
+}
+/** Rotate the access token using the stored refresh token (the hub calls this near expiry / on 401). */
+export function refreshTokens(params, now = () => new Date()) {
+    return postToken({
+        grant_type: "refresh_token",
+        client_id: params.clientId,
+        client_secret: params.clientSecret,
+        refresh_token: params.refreshToken,
+    }, now);
+}
+/**
+ * Mint an `app` actor token via the `client_credentials` grant: headless (no user, no redirect, no
+ * callback, no refresh token), scoped to the app's workspace, valid ~30 days. Linear's documented
+ * renewal is simply to mint a fresh one on a 401/expiry. Requires the app's "Client credentials"
+ * toggle to be enabled. This is the durable token path for a headless agent, vs the interactive
+ * authorization-code flow (24h token + fragile refresh + "already installed" install UX).
+ */
+export function mintAppToken(params, now = () => new Date()) {
+    return postToken({
+        grant_type: "client_credentials",
+        client_id: params.clientId,
+        client_secret: params.clientSecret,
+        scope: (params.scopes ?? DEFAULT_AGENT_SCOPES).join(","),
+    }, now);
+}
+//# sourceMappingURL=oauth.js.map

package/dist/oauth.js.map

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

package/dist/recording-client.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A credential-free AgentSessionClient that records every call instead of touching
+ * Linear. It is the offline-acceptance counterpart to the mock Runner: the hub harness
+ * and unit tests inject it and assert on the ordered call log, so the whole control
+ * surface (plan, activities, elicitation, auth, issue-start, PR attach, state,
+ * externalUrls) is verified with no Linear credentials. The real `@linear/sdk` client is
+ * the live path (./linear-client.ts).
+ */
+import type { Activity, AgentSessionClient, AuthRequest, DocumentInput, ElicitOption, ExternalUrl, PlanItem, PrAttachment, RepoCandidate, SessionState } from "./index.js";
+export type RecordedCall = {
+    call: "postActivity";
+    sessionId: string;
+    activity: Activity;
+} | {
+    call: "setPlan";
+    sessionId: string;
+    items: PlanItem[];
+} | {
+    call: "raiseElicitation";
+    sessionId: string;
+    prompt: string;
+    options?: ElicitOption[];
+} | {
+    call: "suggestRepositories";
+    issueId: string;
+    candidates: RepoCandidate[];
+} | {
+    call: "addIssueLabel";
+    issueId: string;
+    name: string;
+} | {
+    call: "requestAuth";
+    sessionId: string;
+    prompt: string;
+    auth: AuthRequest;
+} | {
+    call: "startIssue";
+    sessionId: string;
+} | {
+    call: "moveIssueToReview";
+    sessionId: string;
+} | {
+    call: "commentOnIssue";
+    sessionId: string;
+    body: string;
+} | {
+    call: "attachPr";
+    sessionId: string;
+    pr: PrAttachment;
+} | {
+    call: "createDocument";
+    sessionId: string;
+    doc: DocumentInput;
+} | {
+    call: "setExternalUrls";
+    sessionId: string;
+    urls: ExternalUrl[];
+} | {
+    call: "setState";
+    sessionId: string;
+    state: SessionState;
+};
+export interface RecordingClient extends AgentSessionClient {
+    /** Every call made, in order. */
+    readonly calls: RecordedCall[];
+}
+export declare function createRecordingClient(): RecordingClient;
+//# sourceMappingURL=recording-client.d.ts.map

package/dist/recording-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording-client.d.ts","sourceRoot":"","sources":["../src/recording-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EACV,QAAQ,EACR,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,YAAY,EAAE,CAAA;CAAE,GACzF;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,aAAa,EAAE,CAAA;CAAE,GAC7E;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC7E;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,YAAY,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,aAAa,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,EAAE,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CAAC;AAEjE,MAAM,WAAW,eAAgB,SAAQ,kBAAkB;IACzD,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC;CAChC;AAED,wBAAgB,qBAAqB,IAAI,eAAe,CAkDvD"}

package/dist/recording-client.js

@@ -0,0 +1,52 @@
+export function createRecordingClient() {
+    const calls = [];
+    return {
+        calls,
+        async postActivity(sessionId, activity) {
+            calls.push({ call: "postActivity", sessionId, activity });
+        },
+        async setPlan(sessionId, items) {
+            calls.push({ call: "setPlan", sessionId, items });
+        },
+        async raiseElicitation(sessionId, prompt, options) {
+            calls.push({ call: "raiseElicitation", sessionId, prompt, ...(options ? { options } : {}) });
+        },
+        async suggestRepositories(issueId, candidates) {
+            calls.push({ call: "suggestRepositories", issueId, candidates });
+            // No opinion offline: the caller then falls back to registry order (exercised by the unit tests
+            // of the pure ordering function, which take real suggestions).
+            return [];
+        },
+        async addIssueLabel(issueId, name) {
+            calls.push({ call: "addIssueLabel", issueId, name });
+        },
+        async requestAuth(sessionId, prompt, auth) {
+            calls.push({ call: "requestAuth", sessionId, prompt, auth });
+        },
+        async startIssue(sessionId) {
+            calls.push({ call: "startIssue", sessionId });
+        },
+        async moveIssueToReview(sessionId) {
+            calls.push({ call: "moveIssueToReview", sessionId });
+        },
+        async commentOnIssue(sessionId, body) {
+            calls.push({ call: "commentOnIssue", sessionId, body });
+        },
+        async attachPr(sessionId, pr) {
+            calls.push({ call: "attachPr", sessionId, pr });
+        },
+        async createDocument(sessionId, doc) {
+            calls.push({ call: "createDocument", sessionId, doc });
+            // Deterministic fake id/url so offline runs and tests have a stable document reference.
+            const slug = doc.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+            return { id: `doc-${slug}`, url: `https://linear.app/doc/${slug}` };
+        },
+        async setExternalUrls(sessionId, urls) {
+            calls.push({ call: "setExternalUrls", sessionId, urls });
+        },
+        async setState(sessionId, state) {
+            calls.push({ call: "setState", sessionId, state });
+        },
+    };
+}
+//# sourceMappingURL=recording-client.js.map

package/dist/recording-client.js.map

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dahrk/linear",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "description": "The Linear Agent Session API client and webhook verification. The native control surface: activities, agent-plan checklist, elicitation gates, prompted-drive, stop signal, externalUrls.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skakel/dahrk.git"
+  },
+  "homepage": "https://github.com/skakel/dahrk#readme",
+  "bugs": {
+    "url": "https://github.com/skakel/dahrk/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@linear/sdk": "^86.0.0",
+    "@dahrk/contracts": "0.1.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "spike/live": "tsx spike/run.ts"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}