@finalai/final-agent-provider 0.8.0 → 0.10.0

package/dist/modules/channels/linear.mjs

@@ -1,621 +0,0 @@
-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