libfx 0.0.13 → 0.0.14-dev.1561.g1a070af32cdf

package/types/durable-world.d.ts

@@ -0,0 +1,95 @@
+// `libfx/durable-world` (durable/world.mjs): sessions kept in a World the app
+// supplies, such as Workflow's Postgres World.
+import type { Durability } from "./libfx.cjs";
+
+export type { Durability } from "./libfx.cjs";
+
+/**
+ * What libfx uses of a World: its events, streams, and queue. Workflow's
+ * Worlds fit. Methods are typed loosely so any conforming World is accepted.
+ */
+export interface World {
+  readonly specVersion?: number;
+  readonly events: {
+    create(runId: string, data: unknown, params?: unknown): unknown;
+    list(params: unknown): unknown;
+  };
+  readonly streams: {
+    write(runId: string, name: string, chunk: string): unknown;
+    writeMulti?(runId: string, name: string, chunks: string[]): unknown;
+    get(runId: string, name: string, startIndex?: number): unknown;
+    getInfo(runId: string, name: string): unknown;
+  };
+  queue(queueName: string, message: unknown, options?: unknown): unknown;
+  createQueueHandler(prefix: string, handler: (message: unknown, meta: any) => Promise<unknown>): (request: Request) => Promise<Response>;
+  /** A World with `registerHandler` delivers to the agent in its process; any other delivers over HTTP to `agent.wakeHandler()`. */
+  registerHandler?(prefix: string, handler: (request: Request) => Promise<Response>): unknown;
+  getRuntimeDeadline?(): unknown;
+  getDeploymentId?(): unknown;
+  createRunId?(options?: Readonly<Record<string, unknown>>): string;
+  start?(): unknown;
+  close?(): unknown;
+}
+
+/** A lease as `alive()` sees it: the fields `holderInfo()` returned when it was taken, beside libfx's own. */
+export type WorldLease = Readonly<Record<string, unknown>>;
+
+/** A World, or a function that creates one. libfx starts and closes a World it creates; a World passed in stays the app's. */
+export type WorldSource = World | (() => World | Promise<World>);
+
+/** What `world()` cannot learn from the World itself. */
+export type WorldOptions = {
+  /** The durability's name in errors. Default `"world"`. */
+  name?: string;
+  /**
+   * The store this World keeps sessions in. Queue messages name it, so one route hands each delivery to the agents on
+   * its store, and on one store an agent name belongs to one configuration. Give each customer of an app a store of its
+   * own. Default the durability's `name`.
+   */
+  store?: string;
+  /** The queue keeps a message until a delivery acknowledges it, across crashes. `prompt()` stores the prompt first either way. Default false. */
+  queueDurable?: boolean;
+  /** How often a waiting worker reads the session again. Default 1000. */
+  pollMs?: number;
+  /**
+   * The queue keeps a message from every other delivery while one handles it, and delivers it again once that
+   * delivery's process is gone, as Vercel Queues does. Without liveness, a worker then holds its session for as long as
+   * its delivery runs, up to its deadline, and renews nothing: the next delivery of the same message takes the session
+   * over. The World must pass each handler call the queue's `messageId` and delivery `attempt`. A worker with no
+   * deadline renews its lease all the same. Default false.
+   */
+  queueLeases?: boolean;
+  /**
+   * With `queueLeases`: a prompt runs in the request that took it when no worker holds the session, and the queue keeps
+   * the prompt as a backstop it delivers only after that request's deadline. The request's lease names the backstop, so
+   * if the request died, the backstop takes the session over. Default true with `queueLeases`.
+   */
+  runInRequest?: boolean;
+  /** Keeps the request alive until `work`, a turn it runs after its response, settles, such as Vercel's `waitUntil` or Next's `after()`. */
+  waitUntil?(work: Promise<void>): void;
+  /** Without liveness, how long a lease lasts after its worker took or last renewed it; renewed every third of that. At least 1000. Default 15000. */
+  leaseMs?: number;
+  /** Each delivery stops `reserveMs` before `maxDurationMs`, or before the World's `getRuntimeDeadline()`. No limit by default. */
+  maxDurationMs?: number;
+  /** Default 30000. */
+  reserveMs?: number;
+  /** What a worker puts in each lease it takes, for `alive()` to read. */
+  holderInfo?(): Record<string, unknown>;
+  /** The AI Gateway credential when the agent has no `apiKey`. */
+  gatewayKey?(): string | Promise<string>;
+} & (
+  | {
+    /** `alive(lease)` answers whether a lease's holder still runs, so a crashed worker's session frees at once. */
+    livenessKnown: true;
+    /** True when the holder runs, false when it does not, and null when unknown. */
+    alive(lease: WorldLease): boolean | null;
+  }
+  | {
+    /** Without liveness, a worker renews its lease while it runs, and the session of one that died frees `leaseMs` after its last renewal. */
+    livenessKnown?: false;
+    alive?(lease: WorldLease): boolean | null;
+  }
+);
+
+/** Keeps sessions in a World the app supplies: its store, streams, and queue. */
+export declare function world(source: WorldSource, options?: WorldOptions): Durability;

package/types/grok.d.ts

@@ -0,0 +1,61 @@
+// `libfx/grok` (grok-sign-in.js): sign in with a Grok plan for a Grok agent.
+import type { FxProviderCredentials, FxFetch } from "./libfx.cjs";
+
+/** Options every network step accepts. */
+export interface GrokRequestOptions {
+  /** Replaces the global `fetch` for xAI's sign-in endpoints. */
+  fetch?: FxFetch;
+  signal?: AbortSignal;
+}
+
+/** A sign-in in progress. Keep it on the server: `verifier` is secret. */
+export interface GrokSignIn {
+  /** Where the user signs in. Afterwards xAI opens an address at `redirectUri` that does not load; the user pastes it back. */
+  readonly url: string;
+  readonly state: string;
+  readonly verifier: string;
+  readonly redirectUri: string;
+}
+
+/** A device code sign-in in progress. Plain data, so a later request can poll it. */
+export interface GrokDeviceSignIn {
+  /** Where the user enters `userCode`. */
+  readonly verificationUrl: string;
+  readonly userCode: string;
+  readonly deviceCode: string;
+  /** How often to poll, in milliseconds. */
+  readonly intervalMs: number;
+  /** Milliseconds since the epoch. */
+  readonly expiresAt: number;
+}
+
+/** The `code` of an error from this module. */
+export type GrokSignInErrorCode =
+  | "LIBFX_GROK_SIGN_IN_INVALID_ADDRESS"
+  | "LIBFX_GROK_SIGN_IN_STATE_MISMATCH"
+  | "LIBFX_GROK_SIGN_IN_DENIED"
+  | "LIBFX_GROK_SIGN_IN_EXPIRED"
+  | "LIBFX_GROK_SIGN_IN_FAILED"
+  | "LIBFX_GROK_DEVICE_CODE_UNAVAILABLE"
+  | "LIBFX_GROK_DEVICE_CODE_EXPIRED"
+  | "LIBFX_GROK_ACCOUNT_UNAVAILABLE"
+  | "LIBFX_GROK_ACCOUNT_CHANGED"
+  | "LIBFX_GROK_REFRESH_FAILED";
+
+/** Starts a sign-in where the user pastes back the address xAI opens. */
+export declare function startSignIn(): Promise<GrokSignIn>;
+
+/** Finishes a sign-in from the pasted address, its query, or either wrapped in quotes or backticks. */
+export declare function finishSignIn(signIn: GrokSignIn, address: string, options?: GrokRequestOptions): Promise<FxProviderCredentials>;
+
+/** Starts a device code sign-in. */
+export declare function startDeviceSignIn(options?: GrokRequestOptions): Promise<GrokDeviceSignIn>;
+
+/** Checks once: credentials after the user entered the code, otherwise null. */
+export declare function pollDeviceSignIn(device: GrokDeviceSignIn, options?: GrokRequestOptions): Promise<FxProviderCredentials | null>;
+
+/** Waits until the user enters the code, polling at xAI's interval. */
+export declare function completeDeviceSignIn(device: GrokDeviceSignIn, options?: GrokRequestOptions): Promise<FxProviderCredentials>;
+
+/** Refreshes credentials. Grok agents refresh on their own; this is for hosts. */
+export declare function refreshCredentials(credentials: FxProviderCredentials, options?: GrokRequestOptions): Promise<FxProviderCredentials>;