@pylonsync/functions 0.3.197 → 0.3.198

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.197",
+  "version": "0.3.198",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/runtime.ts

@@ -21,6 +21,10 @@ import type {
   EmailSender,
   Stream,
   Scheduler,
+  Llm,
+  LlmCompleteRequest,
+  LlmCompleteResponse,
+  Connections,
   QueryCtx,
   MutationCtx,
   ActionCtx,
@@ -529,12 +533,103 @@ function buildEmail(callId: string): EmailSender {
   };
 }
 
+/**
+ * Build the LLM client that round-trips through the host runtime.
+ *
+ * Each call emits an `llm_complete` protocol message; the runtime
+ * forwards to the configured provider (PYLON_LLM_PROVIDER) and replies
+ * with the parsed response. The host enforces model-allowlist gating
+ * for non-admin callers — that's why the API key never leaves the
+ * server process.
+ *
+ * Errors carry an `err.code` so handlers can branch on `LLM_NOT_CONFIGURED`
+ * vs `PROVIDER_HTTP_429` vs `MODEL_NOT_ALLOWED` without parsing message
+ * strings.
+ */
+function buildLlm(callId: string): Llm {
+  return {
+    async complete(request: LlmCompleteRequest): Promise<LlmCompleteResponse> {
+      return (await rpc(callId, {
+        type: "llm_complete",
+        request,
+      })) as LlmCompleteResponse;
+    },
+  };
+}
+
+/**
+ * Build the connection registry that round-trips through the host.
+ * Each method emits a `{type:"connection", op:"..."}` message;
+ * the host's ConnectionManager runs the actual OAuth flow + DB
+ * read/write and returns the typed reply.
+ */
+function buildConnections(callId: string): Connections {
+  return {
+    async authorizeUrl(name, opts) {
+      const data = (await rpc(callId, {
+        type: "connection",
+        op: "authorize_url",
+        payload: {
+          name,
+          post_redirect: opts?.postRedirect,
+        },
+      })) as { url: string };
+      return data;
+    },
+    async get(name) {
+      const data = (await rpc(callId, {
+        type: "connection",
+        op: "get",
+        payload: { name },
+      })) as { access_token: string; scope: string | null; expires_at: number | null };
+      return {
+        accessToken: data.access_token,
+        scope: data.scope,
+        expiresAt: data.expires_at,
+      };
+    },
+    async list() {
+      const data = (await rpc(callId, {
+        type: "connection",
+        op: "list",
+        payload: {},
+      })) as {
+        connections: Array<{
+          name: string;
+          provider: string;
+          scope: string | null;
+          expires_at: number | null;
+          updated_at: number;
+        }>;
+      };
+      return {
+        connections: data.connections.map((c) => ({
+          name: c.name,
+          provider: c.provider,
+          scope: c.scope,
+          expiresAt: c.expires_at,
+          updatedAt: c.updated_at,
+        })),
+      };
+    },
+    async disconnect(name) {
+      return (await rpc(callId, {
+        type: "connection",
+        op: "disconnect",
+        payload: { name },
+      })) as { disconnected: boolean };
+    },
+  };
+}
+
 function buildActionCtx(
   callId: string,
   auth: AuthInfo,
   stream: Stream,
   scheduler: Scheduler,
   email: EmailSender,
+  llm: Llm,
+  connections: Connections,
   request?: unknown
 ): ActionCtx {
   // The host sends `request` as snake_case JSON (`raw_body`); normalize it
@@ -555,6 +650,8 @@ function buildActionCtx(
     stream,
     scheduler,
     email,
+    llm,
+    connections,
     env: process.env as Record<string, string>,
     async runQuery(fnName, args) {
       return rpc(callId, {
@@ -635,6 +732,8 @@ async function handleCall(msg: CallMessage): Promise<void> {
   const stream = buildStream(msg.call_id);
   const scheduler = buildScheduler(msg.call_id);
   const email = buildEmail(msg.call_id);
+  const llm = buildLlm(msg.call_id);
+  const connections = buildConnections(msg.call_id);
 
   // Normalize the Rust-side auth envelope (snake_case) to the camelCase
   // shape that AuthInfo documents. Handlers read `ctx.auth.userId`; the
@@ -680,6 +779,9 @@ async function handleCall(msg: CallMessage): Promise<void> {
   let ctx: QueryCtx | MutationCtx | ActionCtx;
   switch (def.type) {
     case "query":
+      // ctx.llm is intentionally absent on queries — reactive
+      // re-runs would re-bill the LLM call on every dep change.
+      // Move LLM calls into actions / mutations.
       ctx = { db: buildDbReader(msg.call_id), auth, env };
       break;
     case "mutation":
@@ -689,6 +791,8 @@ async function handleCall(msg: CallMessage): Promise<void> {
         stream,
         scheduler,
         env,
+        llm,
+        connections,
         error(code, message) {
           const err = new Error(message);
           (err as any).code = code;
@@ -697,17 +801,14 @@ async function handleCall(msg: CallMessage): Promise<void> {
       };
       break;
     case "action":
-      // Pass `msg.request` so actions invoked via `defineRoute` HTTP
-      // bindings can reach raw headers + body (for webhook signature
-      // verification). Programmatic invocations (runAction, jobs) get
-      // undefined here and `ctx.request` reads as undefined — the type
-      // is optional on purpose.
       ctx = buildActionCtx(
         msg.call_id,
         auth,
         stream,
         scheduler,
         email,
+        llm,
+        connections,
         (msg as unknown as { request?: unknown }).request,
       );
       break;

package/src/types.ts

@@ -305,11 +305,176 @@ export interface EmailSender {
   send(to: string, subject: string, body: string): Promise<void>;
 }
 
+// ---------------------------------------------------------------------------
+// LLM — provider-abstracted text/tool-use completion
+// ---------------------------------------------------------------------------
+
+/**
+ * Server-side LLM client. Available on every ctx variant (query,
+ * mutation, action) because agent loops often run as queries —
+ * read tool args from the message, ship the response back.
+ *
+ * Provider is configured at the server boot (PYLON_LLM_PROVIDER +
+ * ANTHROPIC_API_KEY or OPENAI_API_KEY). The wire shape is Anthropic
+ * Messages — OpenAI calls translate at the transport boundary, so
+ * the same caller code works against either provider.
+ *
+ * The framework does NOT expose this surface to the browser; clients
+ * that need streaming should call POST /api/ai/stream directly.
+ * `ctx.llm.complete` is server-only on purpose — the API key never
+ * leaves the runtime process.
+ */
+export interface Llm {
+  /**
+   * Send a completion request to the configured LLM provider. The
+   * shape is Anthropic Messages: a list of {role, content} pairs
+   * where content is either a string or a list of content blocks
+   * (text, tool_use, tool_result). Returns the full response once
+   * the model finishes generating.
+   *
+   * For agent tool-use loops, inspect `response.stopReason` — when
+   * it's `"tool_use"`, append the assistant's content (which
+   * includes the `tool_use` blocks) plus your `tool_result`
+   * follow-ups to the message list and call again. Loop until
+   * `stopReason === "end_turn"`.
+   *
+   * Errors are thrown as standard Error objects with an `err.code`
+   * property set to one of: `LLM_NOT_CONFIGURED`, `MODEL_NOT_ALLOWED`,
+   * `MODEL_OVERRIDE_FORBIDDEN`, `PROVIDER_HTTP_<code>`,
+   * `PROVIDER_UNREACHABLE`, `INVALID_REQUEST`.
+   */
+  complete(request: LlmCompleteRequest): Promise<LlmCompleteResponse>;
+}
+
+export interface LlmMessage {
+  role: "user" | "assistant" | "system" | "tool";
+  content: string | LlmContentBlock[];
+}
+
+export type LlmContentBlock =
+  | { type: "text"; text: string }
+  | {
+      type: "tool_use";
+      id: string;
+      name: string;
+      input: Record<string, unknown>;
+    }
+  | {
+      type: "tool_result";
+      tool_use_id: string;
+      content: string;
+      is_error?: boolean;
+    };
+
+export interface LlmTool {
+  name: string;
+  description?: string;
+  /** JSON Schema object describing the tool's input shape. */
+  input_schema: Record<string, unknown>;
+}
+
+export interface LlmCompleteRequest {
+  /** Override the server's default model. Subject to
+   *  PYLON_AI_MODELS_ALLOWED gating for non-admin callers. */
+  model?: string;
+  messages: LlmMessage[];
+  system?: string;
+  tools?: LlmTool[];
+  /** Defaults to 4096. */
+  max_tokens?: number;
+  temperature?: number;
+}
+
+export interface LlmCompleteResponse {
+  model: string;
+  content: LlmContentBlock[];
+  /** `end_turn` | `tool_use` | `max_tokens` | `stop_sequence` */
+  stop_reason: string;
+  usage: { input_tokens: number; output_tokens: number };
+}
+
+// ---------------------------------------------------------------------------
+// Connections — per-user OAuth integrations
+// ---------------------------------------------------------------------------
+
+/**
+ * Server-side OAuth connection registry. Apps declare connections
+ * via `defineConnection({...})` in `app.ts`; this surface lets
+ * actions fetch fresh access tokens (auto-refresh) and start the
+ * OAuth dance.
+ *
+ * Available on mutation + action ctx only — connections perform
+ * external I/O (token refresh, DB writes) that doesn't belong
+ * inside a reactive query.
+ *
+ * All ops require an authenticated caller (`ctx.auth.userId !==
+ * null`). Public functions must `ctx.auth.elevate({ admin: true,
+ * reason: "..." })` before reaching `ctx.connections.*`.
+ */
+export interface Connections {
+  /**
+   * Mint the URL the browser should navigate to so the user can
+   * link an external account. `name` matches a `defineConnection({...})`
+   * entry. `postRedirect` (optional) is where the browser lands
+   * after a successful callback — defaults to `/`.
+   *
+   * Throws `CONNECTIONS_NOT_CONFIGURED`, `CONNECTION_UNKNOWN`,
+   * `PROVIDER_NOT_CONFIGURED`, or `ENCRYPTION_REQUIRED` (refresh
+   * tokens are not allowed to land in plaintext).
+   */
+  authorizeUrl(
+    name: string,
+    opts?: { postRedirect?: string }
+  ): Promise<{ url: string }>;
+
+  /**
+   * Returns a fresh access token for `(ctx.auth.userId, name)`. If
+   * the stored token expires within 60s, the framework refreshes
+   * via the provider's refresh-token grant FIRST, persists the new
+   * token pair, then returns the new access token.
+   *
+   * Throws `CONNECTION_NOT_LINKED` when the user hasn't started
+   * the OAuth flow, `REFRESH_FAILED` when the provider rejects
+   * the refresh token (user must re-link).
+   */
+  get(name: string): Promise<{
+    accessToken: string;
+    scope: string | null;
+    expiresAt: number | null;
+  }>;
+
+  /** List the signed-in user's linked connections. Token values
+   *  are NOT included — call `get(name)` for those. */
+  list(): Promise<{
+    connections: Array<{
+      name: string;
+      provider: string;
+      scope: string | null;
+      expiresAt: number | null;
+      updatedAt: number;
+    }>;
+  }>;
+
+  /** Remove the stored connection. Provider-side revocation is
+   *  the caller's responsibility — most providers expose a separate
+   *  `/revoke` endpoint that this surface intentionally doesn't
+   *  call (revoke vs unlink semantics differ per provider). */
+  disconnect(name: string): Promise<{ disconnected: boolean }>;
+}
+
 // ---------------------------------------------------------------------------
 // Context objects — what handlers receive
 // ---------------------------------------------------------------------------
 
-/** Context for query handlers (read-only). */
+/** Context for query handlers (read-only).
+ *
+ * NOTE: `ctx.llm` is NOT exposed here. Queries are reactive: a
+ * subscribed query re-runs whenever its `ctx.db.*` reads change.
+ * Calling a stochastic, paid LLM from a query would (a) silently
+ * burn the framework's API key on every dep invalidation, and
+ * (b) violate the reactive purity contract (same inputs → same
+ * outputs). LLM calls belong in mutations (transactional) or
+ * actions (external I/O). */
 export interface QueryCtx<R extends AuthRequirement = "optional"> {
   db: DbReader;
   auth: AuthInfo<R>;
@@ -325,6 +490,10 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
   scheduler: Scheduler;
   /** Environment variables / secrets. */
   env: Record<string, string>;
+  /** Provider-abstracted LLM client. */
+  llm: Llm;
+  /** Per-user OAuth connection registry. */
+  connections: Connections;
   /** Create a typed error that triggers rollback. */
   error(code: string, message: string): Error;
 }
@@ -336,6 +505,10 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   scheduler: Scheduler;
   /** Send transactional email via the runtime's configured provider. */
   email: EmailSender;
+  /** Provider-abstracted LLM client. */
+  llm: Llm;
+  /** Per-user OAuth connection registry. */
+  connections: Connections;
   /** Environment variables / secrets. */
   env: Record<string, string>;
   /** Run a registered query within its own read transaction. */