@finalai/final-agent-provider 0.6.2 → 0.7.0

package/dist/modules/channels/linear.mjs

@@ -0,0 +1,621 @@
+import {
+  defineChannel,
+  packageRef,
+  jsonObjectSchema,
+  jsonValueSchema
+} from "@finalai/agent-provider";
+import * as z from "zod";
+import { shareReplyReceipt } from "./reply-receipts.mjs";
+import {
+  channelBaseUrl,
+  providerPlaceKey,
+  confirmOAuth,
+  deliveryRetention,
+  decisionChoices,
+  decisionAnswer,
+  decisionSummary,
+  externalKey,
+  inTenant,
+  providerOriginSchema,
+  parseJson,
+  personFor,
+  receivePersonMessage,
+  refString,
+  responseJson,
+  startOAuth,
+  stateKey,
+  takeOAuth,
+  textOf,
+  completionText,
+  verifyHmac
+} from "./channel-utils.mjs";
+const configSchema = z.object({ baseUrl: z.string().url().optional() });
+const pendingDecisionsSchema = z.array(
+  z.object({
+    decisionId: z.string(),
+    user: z.string(),
+    choices: z.array(
+      z.object({
+        label: z.string(),
+        outcome: jsonValueSchema,
+        answer: z.union([z.literal("approve"), z.literal("deny")])
+      })
+    )
+  })
+);
+const graphql = async (ctx, query, variables, token) => {
+  const accessToken = token ?? (await ctx.credentials.app({ tenant: ctx.origin?.place.tenant })).accessToken;
+  const response = z.object({
+    data: jsonObjectSchema.optional(),
+    errors: z.array(z.object({ message: z.string() })).optional()
+  }).parse(
+    await responseJson(
+      await ctx.credentials.fetch("https://api.linear.app/graphql", {
+        method: "POST",
+        headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
+        body: JSON.stringify({ query, variables })
+      })
+    )
+  );
+  if (response.errors != null || response.data == null)
+    throw new Error(
+      `Linear GraphQL: ${response.errors?.map((error) => error.message).join("; ") ?? "missing data"}`
+    );
+  return response.data;
+};
+const createActivity = async (ctx, sessionId, content, key) => {
+  if (content.type === "response" && (typeof content.body !== "string" || content.body.trim().length === 0))
+    return;
+  if (key != null && await ctx.store.get(key) != null) return;
+  const data = await graphql(
+    ctx,
+    "mutation ChannelActivity($input: AgentActivityCreateInput!) { agentActivityCreate(input: $input) { success agentActivity { id } } }",
+    { input: { agentSessionId: sessionId, content } }
+  );
+  const result = z.object({
+    agentActivityCreate: z.object({
+      success: z.boolean(),
+      agentActivity: z.object({ id: z.string() }).nullish()
+    })
+  }).parse(data).agentActivityCreate;
+  if (!result.success || result.agentActivity == null) throw new Error("Linear activity rejected");
+  if (key != null) await ctx.store.set(key, result.agentActivity.id, deliveryRetention);
+};
+const activitySession = async (ctx) => {
+  const savedSession = z.string().safeParse(
+    await ctx.store.get(stateKey("linear-session-for-place", providerPlaceKey(ctx.origin.place)))
+  );
+  return refString(ctx.origin.ref, "sessionId") ?? (ctx.origin.place.kind === "agent-session" ? ctx.origin.place.id : savedSession.success ? savedSession.data : null);
+};
+const activity = async (ctx, content, key) => {
+  const sessionId = await activitySession(ctx);
+  if (sessionId != null) await createActivity(ctx, sessionId, content, key);
+};
+const sessionSchema = z.object({
+  type: z.literal("AgentSessionEvent"),
+  action: z.string(),
+  organizationId: z.string(),
+  webhookTimestamp: z.number(),
+  agentSession: z.object({
+    id: z.string(),
+    creatorId: z.string().nullish(),
+    creator: z.object({ id: z.string(), name: z.string() }).nullish(),
+    issue: z.object({ id: z.string(), title: z.string(), description: z.string().nullish() }).nullish(),
+    comment: z.object({ id: z.string(), body: z.string(), userId: z.string().optional() }).nullish()
+  }),
+  agentActivity: z.object({
+    id: z.string(),
+    userId: z.string(),
+    user: z.object({ id: z.string(), name: z.string() }),
+    content: jsonObjectSchema,
+    signal: z.string().nullish(),
+    sourceCommentId: z.string().nullish()
+  }).nullish()
+});
+const linearChannel = (options = {}) => {
+  const config = configSchema.parse(options);
+  return defineChannel({
+    name: "linear",
+    config,
+    installed: packageRef("@finalai/final-agent-provider/channels/linear"),
+    credentials: { app: "linear" },
+    identity: {
+      kind: "redirect",
+      start: async (args, ctx) => {
+        const app = await ctx.credentials.appInfo();
+        return startOAuth(
+          {
+            ...args,
+            authorizeUrl: "https://linear.app/oauth/authorize",
+            clientId: app.clientId,
+            redirectUri: `${channelBaseUrl(config)}/b/${ctx.binding.id}/oauth/callback`,
+            scope: "read",
+            extra: { actor: "user" }
+          },
+          ctx
+        );
+      }
+    },
+    places: {
+      kinds: ["agent-session", "issue"],
+      defaults: (place) => place.kind === "agent-session" || place.kind === "issue" ? { create: "group", replies: "origin", audience: "members" } : null
+    },
+    routes: [
+      {
+        method: "GET",
+        path: "/oauth/callback",
+        handler: async (ctx) => {
+          const saved = await takeOAuth(ctx.request, ctx);
+          if (saved == null)
+            return new Response("Invalid or expired link request", { status: 400 });
+          const app = await ctx.credentials.appInfo();
+          const token = z.object({ access_token: z.string() }).parse(
+            await responseJson(
+              await ctx.credentials.fetch("https://api.linear.app/oauth/token", {
+                method: "POST",
+                body: new URLSearchParams({
+                  client_id: app.clientId,
+                  client_secret: app.clientSecret,
+                  grant_type: "authorization_code",
+                  code: saved.code,
+                  redirect_uri: saved.redirectUri
+                })
+              })
+            )
+          );
+          const user = z.object({
+            viewer: z.object({
+              id: z.string(),
+              name: z.string(),
+              organization: z.object({ id: z.string() })
+            })
+          }).parse(
+            await graphql(
+              ctx,
+              "query ChannelIdentity { viewer { id name organization { id } } }",
+              {},
+              token.access_token
+            )
+          ).viewer;
+          return confirmOAuth(
+            {
+              ticket: saved.ticket,
+              expected: saved.principal,
+              actual: { id: user.id, tenant: user.organization.id, displayName: user.name }
+            },
+            ctx
+          );
+        }
+      },
+      {
+        method: "POST",
+        path: "/webhook",
+        handler: async (ctx) => {
+          const body = await ctx.request.text();
+          const app = await ctx.credentials.appInfo();
+          const secret = app.signingSecret;
+          const signature = ctx.request.headers.get("linear-signature");
+          if (secret == null || signature == null || !await verifyHmac({ secret, signature, body }))
+            return new Response(null, { status: 401 });
+          const raw = jsonValueSchema.parse(parseJson(body));
+          const timestamp = z.object({ webhookTimestamp: z.number() }).safeParse(raw);
+          if (!timestamp.success || Math.abs(Date.now() - timestamp.data.webhookTimestamp) > 3e5)
+            return new Response(null, { status: 401 });
+          await ctx.receive(raw);
+          return new Response("ok");
+        }
+      }
+    ],
+    receive: async (input, baseContext) => {
+      const tenant = z.object({ organizationId: z.string() }).safeParse(input);
+      const ctx = tenant.success ? inTenant(baseContext, tenant.data.organizationId) : baseContext;
+      const lifecycle = z.object({ type: z.string(), action: z.string() }).safeParse(input);
+      if (lifecycle.success && lifecycle.data.type === "OAuthApp" && lifecycle.data.action === "revoked") {
+        if (!tenant.success) return { ignored: true, reason: "missing-tenant" };
+        await ctx.people.revoke({ tenant: tenant.data.organizationId, reason: "uninstalled" });
+        return { accepted: true };
+      }
+      const mutation = z.object({
+        type: z.string(),
+        action: z.string(),
+        actor: z.object({ id: z.string() }).optional(),
+        data: z.object({
+          id: z.string(),
+          body: z.string().optional(),
+          userId: z.string().optional(),
+          commentId: z.string().optional(),
+          emoji: z.string().optional()
+        })
+      }).safeParse(input);
+      if (mutation.success && (mutation.data.type === "Comment" || mutation.data.type === "Reaction")) {
+        const event2 = mutation.data;
+        const saved = providerOriginSchema.safeParse(
+          await ctx.store.get(stateKey("linear-origin", event2.data.commentId ?? event2.data.id))
+        );
+        if (!saved.success) return { ignored: true, reason: "unknown-origin" };
+        const userId = event2.actor?.id ?? event2.data.userId;
+        if (userId == null || !tenant.success) return { ignored: true, reason: "missing-actor" };
+        const by2 = await personFor(ctx, { id: userId, tenant: tenant.data.organizationId });
+        if (typeof by2 !== "string") return { accepted: false, refusal: by2 };
+        const route = await ctx.places.resolve(saved.data.place);
+        if (route.kind !== "connected") return { ignored: true, reason: "unconnected" };
+        const conversation = ctx.conversation(route.conversation);
+        if (event2.type === "Comment" && event2.action === "update" && event2.data.body != null) {
+          const result2 = await conversation.edit({
+            externalKey: saved.data.externalKey,
+            by: by2,
+            content: [{ type: "text", text: event2.data.body }]
+          });
+          return "refused" in result2 ? { accepted: false, refusal: result2 } : { accepted: true };
+        }
+        if (event2.type === "Comment" && event2.action === "remove") {
+          const result2 = await conversation.remove({ externalKey: saved.data.externalKey, by: by2 });
+          return "refused" in result2 ? { accepted: false, refusal: result2 } : { accepted: true };
+        }
+        if (event2.type === "Reaction" && event2.data.emoji != null) {
+          const result2 = await conversation.react({
+            target: { externalKey: saved.data.externalKey },
+            by: by2,
+            emoji: event2.data.emoji,
+            op: event2.action === "remove" ? "remove" : "add"
+          });
+          return "refused" in result2 ? { accepted: false, refusal: result2 } : { accepted: true };
+        }
+        return { ignored: true, reason: "unsupported-mutation" };
+      }
+      const parsed = sessionSchema.safeParse(input);
+      if (!parsed.success) return { ignored: true, reason: "not-agent-session" };
+      const event = parsed.data;
+      if (event.action !== "created" && event.action !== "prompted")
+        return { ignored: true, reason: "unsupported-action" };
+      const session = event.agentSession;
+      const user = event.agentActivity?.userId ?? session.creatorId;
+      if (user == null) return { ignored: true, reason: "no-human-requester" };
+      const principal = {
+        id: user,
+        tenant: event.organizationId,
+        displayName: event.agentActivity?.user.name ?? session.creator?.name ?? user
+      };
+      const content = event.agentActivity?.content.body;
+      const text = typeof content === "string" ? content : session.comment?.body ?? session.issue?.title ?? "Please help with this issue.";
+      const by = await personFor(ctx, principal);
+      const routePlace = session.issue == null ? { kind: "agent-session", id: session.id, tenant: event.organizationId } : {
+        kind: "issue",
+        id: session.issue.id,
+        tenant: event.organizationId,
+        title: session.issue.title
+      };
+      const place = session.issue == null ? routePlace : {
+        kind: "agent-session",
+        id: session.id,
+        tenant: event.organizationId,
+        title: session.issue.title,
+        parent: routePlace
+      };
+      if (event.agentActivity?.signal === "stop") {
+        const activityId = event.agentActivity.id;
+        const refuseStop = async (reason) => {
+          await createActivity(
+            ctx,
+            session.id,
+            {
+              type: "error",
+              body: "Could not stop this run from this account. Open Final to manage it."
+            },
+            stateKey("linear-stop-refused", session.id, activityId)
+          );
+          return { accepted: false, refusal: reason };
+        };
+        const route = await ctx.places.resolve(routePlace);
+        if (route.kind !== "connected")
+          return refuseStop({
+            refused: "unconnected",
+            message: "This place is not connected to Final.",
+            connectUrl: route.connectUrl
+          });
+        if (typeof by !== "string" && !(by.refused === "unlinked" && route.policy.audience === "anyone" && session.creatorId === user))
+          return refuseStop(by);
+        const key2 = stateKey(
+          "linear-stop",
+          providerPlaceKey(place),
+          session.id,
+          event.agentActivity.id
+        );
+        const saved = z.string().safeParse(await ctx.store.get(key2));
+        let message;
+        if (saved.success) message = saved.data;
+        else {
+          const target = z.object({ turnId: z.string() }).safeParse(await ctx.store.get(stateKey("linear-session-turn", session.id)));
+          if (!target.success)
+            message = "There is no accepted turn in this session to stop. Open Final to manage pending work.";
+          else {
+            const cancelled = await ctx.turns.cancel({
+              conversation: route.conversation,
+              by: typeof by === "string" ? by : void 0,
+              turnId: target.data.turnId
+            });
+            if ("refused" in cancelled) return refuseStop(cancelled);
+            message = cancelled.accepted ? "The agent has stopped." : "There is no active turn this account may stop. Continue in Final.";
+          }
+          await ctx.store.set(key2, message, deliveryRetention);
+        }
+        await createActivity(
+          ctx,
+          session.id,
+          { type: "response", body: message },
+          stateKey("linear-stop-confirmed", session.id, event.agentActivity.id)
+        );
+        return { accepted: true };
+      }
+      const answerKey = event.action === "prompted" && event.agentActivity != null ? stateKey("linear-answer-activity", session.id, event.agentActivity.id) : null;
+      const replay = z.object({ decisionId: z.string(), outcome: jsonValueSchema }).safeParse(answerKey == null ? null : await ctx.store.get(answerKey));
+      if (replay.success) {
+        if (typeof by !== "string") return { accepted: false, refusal: by };
+        const result2 = await ctx.decisions.resolve({ ...replay.data, by });
+        return "refused" in result2 ? { accepted: false, refusal: result2 } : { accepted: true };
+      }
+      const pending = pendingDecisionsSchema.safeParse(
+        await ctx.store.get(stateKey("linear-decision", session.id)) ?? []
+      );
+      const owned = pending.success ? pending.data.filter((entry) => entry.user === user) : [];
+      if (event.action === "prompted" && owned.length > 0 && typeof by === "string") {
+        const normalized = text.trim().toLowerCase().replace(/[.!?]$/g, "");
+        const answer = ["yes", "no", "approve", "deny"].includes(normalized);
+        if (pending.success && pending.data.length > 1) {
+          if (answer || owned.some((entry) => decisionAnswer(entry.choices, text) != null)) {
+            await createActivity(ctx, session.id, {
+              type: "response",
+              body: "Multiple actions need approval. Answer them in Final."
+            });
+            return { accepted: true };
+          }
+        } else {
+          const current = owned[0];
+          const choice = current == null ? null : decisionAnswer(current.choices, text);
+          if (current != null && choice != null) {
+            if (answerKey != null)
+              await ctx.store.set(
+                answerKey,
+                { decisionId: current.decisionId, outcome: choice.outcome },
+                deliveryRetention
+              );
+            const result2 = await ctx.decisions.resolve({
+              decisionId: current.decisionId,
+              outcome: choice.outcome,
+              by
+            });
+            if ("refused" in result2) {
+              await createActivity(ctx, session.id, { type: "error", body: result2.message });
+              return { accepted: false, refusal: result2 };
+            }
+            const latest = pendingDecisionsSchema.safeParse(
+              await ctx.store.get(stateKey("linear-decision", session.id)) ?? []
+            );
+            if (latest.success) {
+              const remaining = latest.data.filter(
+                (entry) => entry.decisionId !== current.decisionId
+              );
+              await ctx.store.set(
+                stateKey("linear-decision", session.id),
+                remaining.length === 0 ? null : jsonValueSchema.parse(remaining),
+                { ttlSeconds: 3600 }
+              );
+            }
+            if (!result2.resolved) {
+              const message = "This decision is no longer waiting in Final.";
+              await createActivity(ctx, session.id, { type: "error", body: message });
+              return { accepted: false, refusal: { refused: "no-access", message } };
+            }
+            return { accepted: true };
+          }
+          if (answer) {
+            await createActivity(ctx, session.id, {
+              type: "response",
+              body: "Choose the exact approval option in Final."
+            });
+            return { accepted: true };
+          }
+        }
+      }
+      await createActivity(
+        ctx,
+        session.id,
+        { type: "thought", body: "I\u2019m looking into this." },
+        stateKey("linear-ack", session.id, event.agentActivity?.id ?? "created")
+      );
+      await ctx.store.set(
+        stateKey("linear-session-for-place", providerPlaceKey(routePlace)),
+        session.id,
+        deliveryRetention
+      );
+      await ctx.store.set(
+        stateKey("linear-session-for-place", providerPlaceKey(place)),
+        session.id,
+        deliveryRetention
+      );
+      const key = externalKey(place, event.agentActivity?.id ?? session.comment?.id ?? session.id);
+      const sourceComment = event.agentActivity?.sourceCommentId ?? (event.agentActivity == null ? session.comment?.id : void 0);
+      if (sourceComment != null)
+        await ctx.store.set(
+          stateKey("linear-origin", sourceComment),
+          jsonValueSchema.parse({ place, externalKey: key }),
+          deliveryRetention
+        );
+      const result = await receivePersonMessage({
+        ctx,
+        principal,
+        place,
+        routePlace,
+        onAccepted: async ({ turnId }) => {
+          if (turnId != null)
+            await ctx.store.set(
+              stateKey("linear-session-turn", session.id),
+              { turnId },
+              deliveryRetention
+            );
+        },
+        text,
+        externalKey: key,
+        context: session.issue == null ? [] : [
+          `Issue: ${session.issue.title}`,
+          ...session.issue.description == null ? [] : [session.issue.description]
+        ],
+        ref: {
+          externalKey: key,
+          sessionId: session.id,
+          requester: user,
+          tenant: event.organizationId
+        }
+      });
+      if ("accepted" in result && !result.accepted) {
+        await createActivity(
+          ctx,
+          session.id,
+          {
+            type: "response",
+            body: `${result.refusal.message} ${result.refusal.linkUrl ?? result.refusal.connectUrl ?? ""}`
+          },
+          stateKey("linear-refusal", key)
+        );
+        await createActivity(
+          ctx,
+          session.id,
+          {
+            type: "error",
+            body: "Open Final to resolve this request, then mention the agent again."
+          },
+          stateKey("linear-refusal-error", key)
+        );
+      }
+      return result;
+    },
+    events: {
+      "turn.started": async (data, ctx) => {
+        const sessionId = refString(ctx.origin.ref, "sessionId") ?? (ctx.origin.place.kind === "agent-session" ? ctx.origin.place.id : null);
+        if (sessionId != null)
+          await ctx.store.set(
+            stateKey("linear-session-turn", sessionId),
+            { turnId: data.turnId },
+            deliveryRetention
+          );
+      },
+      "message.posted": async (data, ctx) => activity(
+        ctx,
+        {
+          type: "response",
+          body: `From ${data.author.displayName} in Final
+
+${textOf(data.message.content)}`
+        },
+        stateKey("linear-mirror", providerPlaceKey(ctx.origin.place), data.message.id)
+      ),
+      "turn.completed": async (data, ctx) => {
+        const sessionId = await activitySession(ctx);
+        if (sessionId == null) return;
+        await shareReplyReceipt({
+          bindingId: ctx.binding.id,
+          store: ctx.store,
+          destination: stateKey("linear", ctx.origin.place.tenant ?? null, sessionId),
+          messageIds: data.messages?.map((message) => message.id) ?? [],
+          originKey: stateKey("linear-response", providerPlaceKey(ctx.origin.place), ctx.turn.id),
+          send: (key) => createActivity(
+            ctx,
+            sessionId,
+            {
+              type: data.stopReason === "error" || data.stopReason === "timed_out" ? "error" : "response",
+              body: completionText(data)
+            },
+            key
+          )
+        });
+      },
+      "tool.started": async (data, ctx) => activity(
+        ctx,
+        { type: "action", action: data.title, parameter: "In progress" },
+        stateKey(
+          "linear-tool",
+          providerPlaceKey(ctx.origin.place),
+          ctx.turn.id,
+          data.toolCallId,
+          "started"
+        )
+      ),
+      "tool.completed": async (data, ctx) => activity(
+        ctx,
+        {
+          type: "action",
+          action: data.title,
+          parameter: data.status,
+          result: data.content == null ? data.status : textOf(data.content)
+        },
+        stateKey(
+          "linear-tool",
+          providerPlaceKey(ctx.origin.place),
+          ctx.turn.id,
+          data.toolCallId,
+          "completed"
+        )
+      ),
+      "plan.updated": async (data, ctx) => {
+        const sessionId = refString(ctx.origin.ref, "sessionId") ?? (ctx.origin.place.kind === "agent-session" ? ctx.origin.place.id : null);
+        if (sessionId == null) return;
+        const plan = data.entries.flatMap(
+          (entry) => typeof entry.content === "string" ? [
+            {
+              content: entry.content,
+              status: entry.status === "completed" ? "completed" : entry.status === "in_progress" || entry.status === "inProgress" ? "inProgress" : entry.status === "canceled" ? "canceled" : "pending"
+            }
+          ] : []
+        );
+        await graphql(
+          ctx,
+          "mutation ChannelPlan($id: String!, $input: AgentSessionUpdateInput!) { agentSessionUpdate(id: $id, input: $input) { success } }",
+          { id: sessionId, input: { plan } }
+        );
+      },
+      "decision.resolved": async (data, ctx) => {
+        const sessionId = refString(ctx.origin.ref, "sessionId") ?? (ctx.origin.place.kind === "agent-session" ? ctx.origin.place.id : null);
+        if (sessionId == null) return;
+        const pending = pendingDecisionsSchema.safeParse(
+          await ctx.store.get(stateKey("linear-decision", sessionId)) ?? []
+        );
+        if (pending.success) {
+          const remaining = pending.data.filter((entry) => entry.decisionId !== data.decisionId);
+          await ctx.store.set(
+            stateKey("linear-decision", sessionId),
+            remaining.length === 0 ? null : jsonValueSchema.parse(remaining),
+            { ttlSeconds: 3600 }
+          );
+        }
+      },
+      "decision.created": async (data, ctx) => {
+        const sessionId = refString(ctx.origin.ref, "sessionId") ?? (ctx.origin.place.kind === "agent-session" ? ctx.origin.place.id : null);
+        const user = refString(ctx.origin.ref, "requester");
+        if (sessionId == null || user == null) return;
+        const choices = decisionChoices(data.request);
+        const pending = pendingDecisionsSchema.safeParse(
+          await ctx.store.get(stateKey("linear-decision", sessionId)) ?? []
+        );
+        const existing = pending.success ? pending.data.filter((entry) => entry.decisionId !== data.decisionId) : [];
+        await ctx.store.set(
+          stateKey("linear-decision", sessionId),
+          jsonValueSchema.parse([...existing, { decisionId: data.decisionId, user, choices }]),
+          { ttlSeconds: 3600 }
+        );
+        await activity(
+          ctx,
+          {
+            type: "elicitation",
+            body: `${decisionSummary(data.request)}
+${choices.length === 0 ? "Answer in Final \u2192" : choices.map((choice) => choice.label).join(" / ")}`
+          },
+          stateKey("linear-elicitation", providerPlaceKey(ctx.origin.place), data.decisionId)
+        );
+      }
+    }
+  });
+};
+export {
+  linearChannel
+};
+//# sourceMappingURL=linear.mjs.map