@gea-ai/agent-sdk 0.1.260910-alpha.0 → 0.1.260910-alpha.2

package/src/channels/README.md

@@ -0,0 +1,298 @@
+# Programmable Channels
+
+Last verified: 2026-09-10
+
+This document is for Agent developers adding a transport or provider to a GEA Agent.
+A Channel owns protocol validation, external identity, conversation addressing,
+message conversion and output delivery. The framework owns installation authority,
+stable Agent sessions, execution, the event journal and durable delivery.
+
+## File discovery and the executable definition
+
+Default-export a Channel from `channels/**/*.ts` beside its owning `agent.ts`.
+The CLI discovers it automatically. A multi-main application gives each Agent its
+own channel directory. No manual registration in `agent.ts` is required.
+
+```ts
+// channels/api.ts
+import { defineChannel, POST } from "@gea-ai/agent-sdk/channels";
+import { env } from "@gea-ai/agent-sdk";
+import { z } from "zod";
+
+const inputSchema = z.object({
+  principalId: z.string().min(1),
+  conversation: z.string().min(1),
+  id: z.string().min(1),
+  text: z.string().min(1),
+});
+
+export default defineChannel({
+  key: "api",
+  path: "/channels/api",
+  env: { CHANNEL_TOKEN: env.secret() },
+  routes: [
+    POST("/", async (request, ctx) => {
+      const token = ctx.env.CHANNEL_TOKEN;
+      if (
+        !token ||
+        request.headers.get("authorization") !== `Bearer ${token}`
+      ) {
+        return new Response("Unauthorized", { status: 401 });
+      }
+      const input = inputSchema.parse(await request.json());
+      const receipt = await ctx
+        .from(input.conversation, {
+          principal: { principalType: "user", principalId: input.principalId },
+        })
+        .send(input.text, {
+          operationId: input.id,
+        });
+      return Response.json(
+        {
+          operationId: receipt.operationId,
+          sessionId: receipt.session.sessionId,
+          duplicate: receipt.duplicate,
+        },
+        { status: 202 },
+      );
+    }),
+  ],
+});
+```
+
+The route base path belongs to the Channel; `/` is its base path and `/events`
+becomes `<base>/events`. A WebSocket route occupies its GET endpoint. Routes,
+callbacks and schemas remain executable code in the Worker bundle. Only the
+`descriptor` is serialized into the package snapshot. Environment declarations
+merge into the owning Agent; conflicting declarations fail composition. Secret
+values never enter the snapshot. Custom Channels use `queue` and preserve stable
+key, adapter version and state version independently from the filename.
+
+## Input and session handles
+
+`from(address, { principal }).send(message, options)` waits for durable acceptance, not model
+completion. Await it before acknowledging a provider webhook. External address
+and operation IDs are converted into the installation's internal namespace.
+Duplicate IDs and identical input return the same acceptance; reusing an ID with
+different input fails.
+
+A message is a string or one UI user message:
+
+```ts
+{ role: "user", parts: [
+  { type: "text", text: "Describe this image" },
+  { type: "file", mediaType: "image/png", url: "data:image/png;base64,..." },
+] }
+```
+
+Remote provider files must be read through authorized `ctx.fetch` and converted
+to inline data. Arbitrary remote URLs, uploaded history, system messages and
+platform identity are not accepted. Inputs are limited to 32 parts and 8 MiB;
+text parts are limited to 64 KiB.
+
+`initialState` initializes a new address; `data` travels with one operation;
+`actor` records external identity without granting GEA permissions.
+The Channel must authenticate the sender before selecting a required external user
+principal; `gea:` is reserved. The example token is a trusted-backend credential,
+not an end-user credential. A session handle captures its principal. Addresses,
+history and events are isolated by principal ID; attributes are not isolation keys.
+Personal Connections use the existing Studio Project/environment principal scope.
+Missing authorization returns the existing link in the private reply; after
+authorizing, send a new operation rather than replaying the completed one. Keep reply
+message IDs in `data`, never in a mutable "latest message" state field.
+
+The receipt contains the accepted operation’s `executionTarget` and a stable session handle. New messages on that handle follow the current Worker deployment; accepted work keeps its target. A handle exposes
+`send`, `history({ after, limit })` and `events({ after, signal })`.
+`resolveSession(address, { principal })` returns the current handle, or null if the address has
+never received input. A handle is not a bearer credential; calls still enforce
+installation authority.
+
+## Journal, state and output
+
+The journal exposes `run.started`, `run.succeeded` and `run.failed`, plus model
+stream event types such as `text-delta` and Tool input/output events. Every event
+has `id`, `sequence`, `operationId`, `runId`, `attempt`, `type` and JSON `data`.
+`run.succeeded` carries `{ reply: { messageId, text } }` after the Agent result has
+been committed; a model stream `finish` does not establish that guarantee.
+
+Live consumers use the same cursor-based journal as durable event handlers. An
+HTTP handler can return an SSE Response over `session.events()`; a `WS()` handler
+can send any text or binary framing it chooses. Its optional third argument
+`{ authorize(request, ctx), protocols }` authenticates the handshake before
+upgrade; return a rejection Response to deny it. Socket callbacks can also inspect
+`ctx.request`, the original handshake. Disconnecting a subscriber does
+not cancel accepted work. Keep and resume from the last observed sequence.
+
+Declare `state` and `stateSchema` for durable channel state; `context(state)`
+reconstructs temporary values for each projection. Event callbacks receive
+`{ state, context, input, outbox }` and are the only authors of persistent state.
+They do not perform network requests. State, output intents and the event
+checkpoint commit together. Invalid state fails rather than resetting silently.
+
+Use `outbox.enqueue(key, payload)` in an event and validate it with
+`outboundSchema`. The same event/key combination always denotes the same payload.
+`outbound(delivery, ctx)` receives an immutable task with a stable UUID, attempt
+and persisted first-attempt time. It returns one of:
+
+- `sent`, optionally with a JSON provider receipt.
+- `retryable`, for a known unsent failure, optionally with `retryAfterMs`.
+- `failed`, for a definitive permanent failure.
+- `unknown`, when the provider may have sent the message.
+
+Declare `idempotencyWindowMs` only if the provider guarantees deduplication for
+the supplied stable delivery ID. Expired or unsupported ambiguous deliveries
+require an operator decision. An unknown send pauses later output for that address
+while its accepted Agent inputs continue. The authorized operator can confirm
+sent, retry explicitly or abandon; retry preserves the original UUID and first
+attempt time. Delivery outcomes and operator confirmations appear in the same
+journal as `delivery.sent`, `delivery.failed`, `delivery.retryable` and
+`delivery.unknown`. Agent execution and output delivery are separate statuses.
+Provider rules and error classification belong in the Channel.
+
+## Framework-managed receivers
+
+Declare `receiver: { kind: "websocket", version: 1, start(ctx), timer?(name, ctx) }`
+on `defineChannel()` to receive events without an inbound request. A receiver can
+use `routes: []`; its Channel still owns its base path. The snapshot stores only
+the receiver kind/version. Callbacks remain executable Worker code, and old HTTP
+descriptors omit the receiver field entirely.
+
+`start` performs one discovery and `await ctx.connectWebSocket(url, handlers)`
+then returns. Never keep it pending for the lifetime of the connection. Native
+Runtime retains the socket, dispatches finite `open`, `message`, `close` and
+`error` callbacks, and exclusively schedules reconnects. Every callback receives
+a fresh `ChannelReceiverContext`; retain protocol data keyed by the socket ID,
+not a previous context. `ctx.signal` cancels operations on stop or loss of access.
+
+Use `ctx.setTimer(name, delayMs)` and `ctx.clearTimer(name)` for protocol timers;
+timers dispatch `receiver.timer(name, currentContext)` and are removed on cancel.
+They can run while a message awaits admission. Call `ctx.ready()` only after the
+provider protocol is usable, `ctx.retry({ code, message, retryAfterMs? })` for a
+temporary failure, or `ctx.fail({ code, message })` for a configuration failure.
+Keep error messages free of URLs, tickets and credentials. `connectWebSocket`
+accepts `responseHeaders` to select handshake metadata needed by the adapter;
+`ChannelWebSocketError` preserves status and only those selected headers.
+
+Both HTTP and receiver contexts extend `ChannelInputContext` with the same
+`from`/`resolveSession`, bounded fetch and declared env. A durable receipt can be
+acknowledged without waiting for model completion. `ChannelInputError` exposes
+the structured `code` and `status` for ACK classification. Retry the same
+operation ID and payload after an ACK is lost; changing transport does not change
+address-scoped deduplication or stable session identities.
+
+Receiver artifacts require the explicit `channel-receiver-v1` Runtime capability.
+An unsupported Host or Runtime rejects deployment. Transport changes use the
+flow “disable installation → publish the whole Worker → configure the provider
+→ enable installation”. Channel builds also require `channel-operation-target-v1`, `channel-principal-v1`
+and `controlled-do-call-v1`;
+rollback artifacts must be built with the updated SDK/CLI. Internal protocol
+upgrades require stopping ingress and receivers and draining all accepted work
+and admission leases before replacing SDK, CLI, Host, Runtime and Worker builds. Ordinary compatible releases preserve installed identity;
+already accepted execution and outbox work retain their deployment.
+
+## Built-in Feishu and extension example
+
+The canonical [Feishu implementation](feishu.ts) uses only this public API. It is
+both the built-in preset and the complete authoring example; there is no
+privileged provider branch in the framework.
+
+```ts
+// channels/feishu.ts
+import { env } from "@gea-ai/agent-sdk";
+import { feishuChannel } from "@gea-ai/agent-sdk/channels/feishu";
+
+export default feishuChannel({
+  transport: "websocket",
+  env: {
+    FEISHU_APP_ID: env.value(),
+    FEISHU_APP_SECRET: env.secret(),
+  },
+  configure(ctx) {
+    return {
+      appId: ctx.env.FEISHU_APP_ID,
+      appSecret: ctx.env.FEISHU_APP_SECRET,
+      allowedSenders: "*",
+    };
+  },
+});
+```
+
+`env` declares configuration requirements and their secret classification. These
+merge into the owning Agent snapshot and the CLI's generated bindings.
+`configure(ctx)` receives the current invocation's `env` and `environment`
+(`local`, `preview`, or `production`). Its `ctx.env` keys are inferred from this
+Channel's declarations; values can be undefined until configured. It runs only
+at HTTP input, receiver discovery/event handling, and outbound delivery, never
+while discovering, inspecting or packing the project. It must synchronously
+return configuration; do not perform side effects or retain the context.
+The preset owns a statically discoverable route/receiver descriptor and uses the
+ordinary `defineChannel` handlers to resolve configuration at those boundaries.
+
+Configure the two values in the existing Agent environment settings, separately
+for Preview and Production. Locally export them before `gea agent dev`; the CLI
+does not automatically load a project `.env` file. The old zero-argument preset
+and `appIdEnv`/`appSecretEnv` options are replaced by this explicit declaration and
+callback. No default credential variable names are read implicitly.
+
+`allowedSenders: "*"` accepts every authenticated sender supported by the preset.
+The application identity, event authentication and matching tenant checks still
+apply; each sender retains an isolated principal and session. To restrict access,
+return a list instead:
+
+```ts
+allowedSenders: [{ tenantKey: "your-tenant", openId: "ou_allowed-user" }];
+```
+
+For a configurable policy, declare `FEISHU_ALLOWED_SENDERS: env.value()` and return
+`allowedSenders: ctx.env.FEISHU_ALLOWED_SENDERS`. Its value can be `*` or a JSON
+sender array. Omission, blank text and an empty list deny input. Malformed JSON
+or sender entries produce an explicit input failure.
+
+Publish the Agent and create an installation for its Preview or Production
+environment. In `websocket` mode the Channel exposes no HTTP callback route and
+does not use a Verification Token. Enable long-connection event delivery for an
+enterprise self-built application in Feishu. The framework host must support
+managed receivers. An open socket becomes ready after a provider pong; this
+status alone does not prove event subscriptions or a real message round trip.
+Use separate Feishu apps for preview and production: multiple clients of one app
+compete for events rather than each receiving them.
+
+For HTTP, set `transport: "http"` (the default), add
+`FEISHU_VERIFICATION_TOKEN: env.secret()` to `env`, and return
+`verificationToken: ctx.env.FEISHU_VERIFICATION_TOKEN` from `configure`.
+Use the installation's returned callback URL in Feishu's event subscription
+configuration. Enable the bot and the permissions for receiving private messages
+and sending bot messages; subscribe to `im.message.receive_v1`. The preset supports
+private text messages and unencrypted HTTP event callbacks. Encrypt Key callbacks,
+groups, cards and provider attachments require another adapter extension.
+Verification Token is checked for challenges and messages; app ID and tenant/open
+ID are checked before accepting messages.
+
+The preset obtains an endpoint through the controlled HTTP capability and
+declares `*.feishu.cn` for dynamic China-site endpoints. Dialing requires WSS on
+port 443 and native public-DNS validation, address pinning and TLS verification;
+other domains are rejected. All
+socket operations and protocol timers use Channel capabilities; framework
+reconnection is the only reconnect loop. See [the receiver protocol notes](feishu-websocket.md)
+for correlation, limits and acknowledgement behavior.
+
+Outbound uses the reply API with the task UUID. Feishu documents a one-hour
+UUID deduplication window in its [official SDK](https://github.com/larksuite/oapi-sdk-go/blob/v3_main/service/im/v1/model.go).
+The preset does not restart that clock after process recovery. API references:
+[reply message](https://open.feishu.cn/document/server-docs/im-v1/message/reply),
+[event callback setup](https://open.feishu.cn/document/server-docs/event-subscription-guide/event-subscription-configure-/request-url-configuration-case).
+
+Unit tests exercise challenge verification, durable acknowledgement, sender
+filtering, event projection, stable UUIDs and ambiguous transport outcomes. A real
+Feishu application and credentials are still required for deployment acceptance.
+
+## Changelog
+
+[2026-09-07] #184 — Add executable Channel authoring, generic delivery contracts and the public-API Feishu preset.
+[2026-09-07] #184 — Add the Feishu websocket transport with shared admission and framework-owned connections.
+
+[2026-09-08] #184 — Use stable session handles and operation targets with unified Worker publication.
+
+[2026-09-10] #184 — Require sender principals, isolate private sessions and reuse Studio authorization links.
+
+[2026-09-10] #403 — Resolve explicit Feishu credentials through typed runtime configure(ctx), and support open sender access with `*` while retaining identity isolation.

package/src/channels/feishu.ts

@@ -0,0 +1,295 @@
+import { z } from "zod";
+import type { AgentEnvironmentRequirement } from "../index";
+import {
+  defineChannel,
+  POST,
+  type AgentChannelOutboundResult,
+  type ChannelCapabilities,
+} from "./index";
+import {
+  acceptFeishuEvent,
+  feishuHeaderSchema,
+  feishuSenderSchema,
+} from "./feishu-inbound";
+import { createFeishuReceiver } from "./feishu-websocket";
+
+const API_ORIGIN = "https://open.feishu.cn";
+const IDENTITY_WINDOW_MS = 60 * 60 * 1000;
+const envelopeSchema = z.object({
+  type: z.string().optional(),
+  token: z.string().optional(),
+  challenge: z.string().optional(),
+  encrypt: z.string().optional(),
+  header: feishuHeaderSchema.extend({ token: z.string() }).optional(),
+  event: z.unknown().optional(),
+});
+const inputDataSchema = z
+  .object({ chatId: z.string().min(1), messageId: z.string().min(1) })
+  .strict();
+const replySchema = z
+  .object({ messageId: z.string().min(1), text: z.string().min(1) })
+  .strict();
+const completedEventSchema = z.object({
+  reply: z.object({ text: z.string() }),
+});
+const tokenResponseSchema = z.object({
+  code: z.number(),
+  tenant_access_token: z.string().optional(),
+});
+const replyResponseSchema = z.object({
+  code: z.number(),
+  data: z.object({ message_id: z.string() }).optional(),
+});
+
+export type FeishuChannelConfiguration = {
+  appId: string | undefined;
+  appSecret: string | undefined;
+  verificationToken?: string;
+  /** A sender list, its JSON representation, or "*". Missing/empty denies all senders. */
+  allowedSenders?: string | readonly z.output<typeof feishuSenderSchema>[];
+};
+
+export type FeishuChannelOptions<TEnv extends string = string> = {
+  transport?: "http" | "websocket";
+  key?: string;
+  path?: string;
+  env: Readonly<Record<TEnv, AgentEnvironmentRequirement>>;
+  /** Runs with the current invocation's environment, never during package discovery. */
+  configure(context: {
+    readonly env: Readonly<Record<TEnv, string | undefined>>;
+    readonly environment: ChannelCapabilities["environment"];
+  }): FeishuChannelConfiguration;
+};
+
+async function equalToken(left: string, right: string): Promise<boolean> {
+  const [a, b] = await Promise.all(
+    [left, right].map((value) =>
+      crypto.subtle.digest("SHA-256", new TextEncoder().encode(value)),
+    ),
+  );
+  const aBytes = new Uint8Array(a);
+  const bBytes = new Uint8Array(b);
+  let difference = 0;
+  for (let i = 0; i < aBytes.length; i++) difference |= aBytes[i]! ^ bBytes[i]!;
+  return difference === 0;
+}
+
+/** The built-in adapter is an ordinary public Channel definition; it has no host-specific privileges. */
+export function feishuChannel<TEnv extends string>(
+  options: FeishuChannelOptions<TEnv>,
+) {
+  const transport = options.transport ?? "http";
+  return defineChannel({
+    key: options.key ?? "feishu",
+    path: options.path ?? "/channels/feishu",
+    env: options.env,
+    networkHosts:
+      transport === "websocket" ? ["*.feishu.cn"] : ["open.feishu.cn"],
+    ...(transport === "websocket"
+      ? { receiver: createFeishuReceiver(options.configure) }
+      : {}),
+    stateSchema: z.object({ replies: z.number().int().nonnegative() }).strict(),
+    state: { replies: 0 },
+    dataSchema: inputDataSchema,
+    context(state) {
+      return { replyCount: state.replies };
+    },
+    routes:
+      transport === "websocket"
+        ? []
+        : [
+            POST("/", async (request, ctx) => {
+              // HTTP callback boundary translates malformed provider input and acceptance failures into HTTP status.
+              try {
+                const raw = await request.text();
+                if (new TextEncoder().encode(raw).byteLength > 128 * 1024)
+                  return new Response("Event too large", { status: 413 });
+                const envelope = envelopeSchema.safeParse(JSON.parse(raw));
+                if (!envelope.success)
+                  return new Response("Invalid event", { status: 400 });
+                if (envelope.data.encrypt)
+                  return new Response(
+                    "Encrypted events are not supported by this preset",
+                    { status: 400 },
+                  );
+                const configuration = options.configure(ctx);
+                const expectedToken = configuration.verificationToken;
+                if (!expectedToken)
+                  return new Response(
+                    "Channel verification is not configured",
+                    {
+                      status: 503,
+                    },
+                  );
+                if (
+                  !(await equalToken(
+                    envelope.data.header?.token ?? envelope.data.token ?? "",
+                    expectedToken,
+                  ))
+                )
+                  return new Response("Invalid verification token", {
+                    status: 401,
+                  });
+                if (envelope.data.type === "url_verification") {
+                  if (!envelope.data.challenge)
+                    return new Response("Missing challenge", { status: 400 });
+                  return Response.json({ challenge: envelope.data.challenge });
+                }
+                const accepted = await acceptFeishuEvent(
+                  envelope.data,
+                  configuration,
+                  ctx,
+                );
+                return accepted.match({
+                  ok: () => Response.json({ code: 0 }),
+                  err: (error) =>
+                    new Response(error.message, { status: error.status }),
+                });
+              } catch {
+                return new Response("Channel callback could not be accepted", {
+                  status: 500,
+                });
+              }
+            }),
+          ],
+    events: {
+      "run.succeeded"(event, channel) {
+        const { reply } = completedEventSchema.parse(event.data);
+        if (!reply.text) return;
+        const data = inputDataSchema.parse(channel.input.data);
+        channel.outbox.enqueue("reply", {
+          messageId: data.messageId,
+          text: reply.text,
+        });
+        channel.state.replies += 1;
+      },
+    },
+    outboundSchema: replySchema,
+    idempotencyWindowMs: IDENTITY_WINDOW_MS,
+    async outbound(delivery, ctx): Promise<AgentChannelOutboundResult> {
+      let phase: "configuration" | "token" | "send" = "configuration";
+      // Provider callback boundary: once the send starts, a transport failure has an unknown outcome.
+      try {
+        const { appId, appSecret } = options.configure(ctx);
+        if (!appId || !appSecret)
+          return {
+            status: "failed",
+            error: {
+              code: "feishu_configuration",
+              message: "Feishu application credentials are missing.",
+              retryable: false,
+            },
+          };
+        phase = "token";
+        const tokenResponse = await ctx.fetch(
+          `${API_ORIGIN}/open-apis/auth/v3/tenant_access_token/internal`,
+          {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+            signal: ctx.signal,
+          },
+        );
+        if (!tokenResponse.ok) return providerFailure(tokenResponse, false);
+        const token = tokenResponseSchema.parse(await tokenResponse.json());
+        if (token.code !== 0 || !token.tenant_access_token)
+          return {
+            status: "failed",
+            error: {
+              code: "feishu_auth",
+              message: `Feishu token request failed (${token.code}).`,
+              retryable: false,
+            },
+          };
+        phase = "send";
+        const response = await ctx.fetch(
+          `${API_ORIGIN}/open-apis/im/v1/messages/${encodeURIComponent(delivery.payload.messageId)}/reply`,
+          {
+            method: "POST",
+            headers: {
+              authorization: `Bearer ${token.tenant_access_token}`,
+              "content-type": "application/json",
+            },
+            body: JSON.stringify({
+              msg_type: "text",
+              content: JSON.stringify({ text: delivery.payload.text }),
+              uuid: delivery.id,
+            }),
+            signal: ctx.signal,
+          },
+        );
+        if (!response.ok) return providerFailure(response, true);
+        const body = replyResponseSchema.parse(await response.json());
+        if (body.code !== 0)
+          return {
+            status: "failed",
+            error: {
+              code: "feishu_message",
+              message: `Feishu rejected the message (${body.code}).`,
+              retryable: false,
+            },
+          };
+        if (!body.data)
+          return {
+            status: "unknown",
+            error: {
+              code: "feishu_receipt",
+              message: "Feishu returned no message receipt.",
+              retryable: false,
+            },
+          };
+        return { status: "sent", receipt: { messageId: body.data.message_id } };
+      } catch {
+        if (phase === "configuration")
+          return {
+            status: "failed",
+            error: {
+              code: "feishu_configuration",
+              message: "Feishu application configuration failed.",
+              retryable: false,
+            },
+          };
+        return {
+          status: phase === "send" ? "unknown" : "retryable",
+          error: {
+            code: "feishu_transport",
+            message:
+              phase === "send"
+                ? "The Feishu message delivery outcome is unknown."
+                : "The Feishu token request failed.",
+            retryable: phase !== "send",
+          },
+        };
+      }
+    },
+  });
+}
+
+function providerFailure(
+  response: Response,
+  sending: boolean,
+): AgentChannelOutboundResult {
+  const retryAfter = response.headers.get("retry-after");
+  const retryAfterMs =
+    retryAfter && /^\d+$/u.test(retryAfter)
+      ? Math.max(1, Number(retryAfter) * 1000)
+      : undefined;
+  if (response.status === 429 || (!sending && response.status >= 500))
+    return {
+      status: "retryable",
+      error: {
+        code: "feishu_http",
+        message: `Feishu returned HTTP ${response.status}.`,
+        retryable: true,
+      },
+      ...(retryAfterMs ? { retryAfterMs } : {}),
+    };
+  return {
+    status: sending && response.status >= 500 ? "unknown" : "failed",
+    error: {
+      code: "feishu_http",
+      message: `Feishu returned HTTP ${response.status}.`,
+      retryable: false,
+    },
+  };
+}