@flowajs/chat-service 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Centre for Population Genomics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# `@flowajs/chat-service`
+
+Stateless service that orchestrates LLM conversations over flowa artifacts.
+Reads aggregates and papers from a configurable storage backend, applies edits
+to a Zod-validated artifact schema, persists draft versions back to storage,
+and streams SSE chat responses.
+
+Two consumption modes:
+
+- The flowa demo (`examples/demo`) depends on it via `workspace:*` and runs
+  the default env-driven entry (`node dist/index.js`).
+- External and production deployments install via npm (`pnpm add
+  @flowajs/chat-service`) and wrap the programmatic API (`createApp(...)`)
+  with custom storage / LLM / auth wiring. See
+  [Production deployment](#production-deployment).
+
+## Architecture
+
+```text
+┌─ HTTP (Hono) ───────────────────────────────────────────┐
+│  POST /sessions   POST /chat/:id   GET /health          │
+└────────────┬────────────────────────────────────────────┘
+             │
+       createApp({ storage, provider, jwtSecret, ... })
+             │
+   ┌─────────┴─────────┐
+   ▼                   ▼
+Storage              LlmProvider
+  fs | s3 | gcs   anthropic | bedrock | google-gla
+                  google-vertex | openai
+```
+
+The HTTP surface is provider-agnostic. Backends and the LLM provider are
+constructed by the caller (env-driven default in `index.ts`, or programmatic
+in a custom entry).
+
+### Storage
+
+`Storage` is a thin interface (5 ops: `read` / `write` / `writeIfAbsent` /
+`exists` / `list`). Three backends are available:
+
+- **`fs`** — POSIX local filesystem. Atomic create-only via
+  `O_CREAT|O_EXCL`.
+- **`s3`** — `@aws-sdk/client-s3`. Atomic create-only via `IfNoneMatch: '*'`.
+  Region, endpoint, and credentials are resolved from the AWS SDK's standard
+  env vars (`AWS_REGION`, `AWS_ENDPOINT_URL_S3`, `fromNodeProviderChain`); for
+  S3-compatible providers (Cloudflare R2, Backblaze B2, MinIO, DigitalOcean
+  Spaces, Wasabi, Hetzner, etc.) set those env vars to point at the provider.
+  For knobs the SDK doesn't surface as env vars (e.g. `forcePathStyle`,
+  custom retry policy), use the `{ client }` programmatic form.
+- **`gcs`** — `@google-cloud/storage`. Atomic create-only via the
+  `ifGenerationMatch: 0` precondition. Credentials come from Google Cloud's
+  Application Default Credentials chain (`GOOGLE_APPLICATION_CREDENTIALS`,
+  gcloud user creds, GCE metadata server, etc.). For deployments needing
+  Workload Identity Federation or other custom cred-mint flows, use the
+  `{ client }` programmatic form with a pre-built `Storage` client.
+
+An Azure Blob backend is the next adapter when a consumer surfaces it; same
+factory shape (`{ bucket, prefix? } | { client, bucket, prefix? }`).
+
+### LLM providers
+
+`LlmProvider` is a thin interface around a Vercel AI SDK `LanguageModel` plus
+two optional knobs: `providerOptions` (per-provider thinking/reasoning
+config) and `prepareStep(messages)` (per-step messages transformation, used
+by Bedrock for prompt-cache point injection).
+
+Five providers are supported: `anthropic`, `bedrock`, `google-gla`,
+`google-vertex`, `openai`. Each ai-sdk package is an optional peer — install
+only what you use. Selection at runtime via `LLM_MODEL=<provider>:<model>`.
+
+### Authentication
+
+chat-service issues and verifies its own session JWT (`POST /sessions` →
+token; `POST /chat/:id` requires the token). Upstream-IDP authentication
+(validating that the caller of `POST /sessions` is who they claim) is a
+separate concern, exposed as a generic OIDC middleware:
+
+```ts
+import { createOidcMiddleware } from "@flowajs/chat-service/auth/oidc";
+
+app.use("/sessions", createOidcMiddleware({
+  jwksUrl: process.env.OIDC_JWKS_URL!,
+  issuer: process.env.OIDC_ISSUER!,
+  audience: process.env.OIDC_AUDIENCE!,
+  // dev mode: decode the JWT body without verifying signature.
+  // Useful for local dev with a stub IDP. NEVER enable in production.
+  devMode: process.env.NODE_ENV === "development",
+}));
+```
+
+The middleware works against any OIDC IDP (Auth0, Keycloak, Okta, GitHub,
+etc.). The default env-driven `index.ts` applies it on `/sessions` when
+`OIDC_JWKS_URL` is set; otherwise the route is unauthenticated.
+
+## Environment configuration (default `index.ts`)
+
+| Var | Required? | Purpose |
+|-----|-----------|---------|
+| `LLM_MODEL` | yes | `<provider>:<model>` — e.g. `bedrock:au.anthropic.claude-sonnet-4-6`, `anthropic:claude-sonnet-4-6`, `google-gla:gemini-2.5-pro`, `google-vertex:gemini-2.5-pro`, `openai:gpt-5`. |
+| `STORAGE_BACKEND` | yes | One of `fs`, `s3`, `gcs`. |
+| `STORAGE_FS_ROOT` | when `fs` | Absolute path to the storage root directory. |
+| `STORAGE_S3_BUCKET` | when `s3` | Bucket name. Region, endpoint, and credentials come from the AWS SDK's standard env vars (`AWS_REGION`, `AWS_ENDPOINT_URL_S3`, `AWS_ACCESS_KEY_ID`, etc.); set those to point at AWS S3 or any S3-compat provider. |
+| `STORAGE_GCS_BUCKET` | when `gcs` | Bucket name. Credentials come from Google Cloud's Application Default Credentials chain (`GOOGLE_APPLICATION_CREDENTIALS`, gcloud user creds, GCE metadata server, etc.). |
+| `STORAGE_PREFIX` | no | Prefix prepended to every storage key (regardless of backend). |
+| `CHAT_JWT_SECRET` | yes | Session JWT signing key. |
+| `CHAT_PROMPT_DIR` | no, default `./prompts` | Directory containing `aggregation_edit_prompt.txt`. |
+| `CHAT_JWT_TTL_SECONDS` | no, default `14400` | Session token lifetime (4h). |
+| `PORT` | no, default `8000` | HTTP listen port. |
+| `OTEL_ENABLED` | no, default `false` | When `true`, `instrumentation.ts` boots the OpenTelemetry SDK with SigV4 OTLP transport. The demo leaves this unset; production sets it to enable CloudWatch / X-Ray. |
+| `BEDROCK_INFERENCE_PROFILE` | no | Application inference profile ARN for Bedrock cost attribution; only used when `LLM_MODEL` starts with `bedrock:`. |
+| `OIDC_JWKS_URL`, `OIDC_ISSUER`, `OIDC_AUDIENCE` | no | When all three are set, `index.ts` applies the OIDC middleware on `POST /sessions`. |
+
+Provider creds are read by each ai-sdk package via standard env vars
+(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`,
+`GOOGLE_APPLICATION_CREDENTIALS` + `GOOGLE_VERTEX_PROJECT` +
+`GOOGLE_VERTEX_LOCATION`, `AWS_REGION` + `AWS_ACCESS_KEY_ID` etc.). AWS S3
+storage uses the AWS SDK's default credential chain
+(`fromNodeProviderChain`).
+
+## HTTP API
+
+- `POST /sessions { variant_id, user_id, category, initial_artifact, initial_version }`
+  → `{ session_id, token, expires_at }`
+- `POST /chat/:sessionId { messages, triage_state? }` → SSE stream
+- `GET /health` → `{ status: "ok" }`
+
+## Production deployment
+
+The default `index.ts` is sufficient when standard credential chains
+(AWS env vars, IAM role, IRSA, etc.) cover your cred-mint flow. For
+deployments that need custom cred minting (e.g. minting AWS STS credentials
+from an OIDC IDP token in-process), write a small entry that uses the
+programmatic API and injects pre-built SDK clients:
+
+```ts
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { S3Client } from "@aws-sdk/client-s3";
+import { createAmazonBedrock } from "@ai-sdk/amazon-bedrock";
+import { createApp } from "@flowajs/chat-service/server";
+import { createS3Storage } from "@flowajs/chat-service/storage/s3";
+import { createBedrockProvider } from "@flowajs/chat-service/llm/bedrock";
+import { createOidcMiddleware } from "@flowajs/chat-service/auth/oidc";
+import { yourCustomCredentialProvider } from "./creds.js";
+
+// Build a credential provider that refreshes on expiry. The AWS SDK
+// invokes it on each request that needs creds.
+const credentials = yourCustomCredentialProvider();
+
+// Storage: pre-built S3Client bound to the custom credential provider.
+const s3 = new S3Client({ region: "us-east-1", credentials });
+const storage = createS3Storage({
+  client: s3,
+  bucket: "my-bucket",
+  prefix: "flowa/",
+});
+
+// LLM: pre-built bedrock client bound to the same credential provider.
+const bedrockClient = createAmazonBedrock({
+  region: "us-east-1",
+  credentialProvider: async () => {
+    const c = await credentials();
+    return {
+      accessKeyId: c.accessKeyId,
+      secretAccessKey: c.secretAccessKey,
+      sessionToken: c.sessionToken,
+    };
+  },
+});
+const provider = createBedrockProvider({
+  modelId: "us.anthropic.claude-sonnet-4-6",
+  client: bedrockClient,
+});
+
+const chatApp = createApp({
+  storage,
+  provider,
+  jwtSecret: process.env.CHAT_JWT_SECRET!,
+  promptDir: "./prompts",
+});
+
+// Compose with custom auth middleware. The OIDC validator shipped with
+// chat-service handles standard JWKS verification; substitute your own
+// middleware if your IDP needs something else.
+const app = new Hono();
+app.use("/sessions", createOidcMiddleware({
+  jwksUrl: process.env.OIDC_JWKS_URL!,
+  issuer: process.env.OIDC_ISSUER!,
+  audience: process.env.OIDC_AUDIENCE!,
+}));
+app.route("/", chatApp);
+
+serve({ fetch: app.fetch, port: 8000 });
+```
+
+## Build and run
+
+```bash
+pnpm install
+pnpm --filter @flowajs/chat-service typecheck
+pnpm --filter @flowajs/chat-service test
+pnpm --filter @flowajs/chat-service build
+node packages/chat-service/dist/index.js
+```
+
+A reference `Dockerfile` is included as a starting point. Production
+deployments that need a custom entry install `@flowajs/chat-service` from
+npm and write their own thin entry that calls `createApp(...)` — see
+[Production deployment](#production-deployment).

package/dist/artifact.d.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+/**
+ * Citation-grounded fields shared by every chat-service artifact. Deployments
+ * extend the schema by calling `ArtifactSchema.extend({...})` with their
+ * additional fields:
+ *
+ * ```ts
+ * import { ArtifactSchema } from "@flowajs/chat-service";
+ *
+ * export const MyArtifactSchema = ArtifactSchema.extend({
+ *   classification: z.string(),
+ *   classification_rationale: z.string(),
+ * });
+ * ```
+ *
+ * `.extend(...)` preserves the shape's TypeScript type, so the resulting
+ * schema stays assignable to `z.ZodType<Artifact>` at the
+ * `createApp({ schema })` call site. Spreading `...artifactFields` into a
+ * fresh `z.object({...})` works at runtime but widens the inferred shape
+ * to `Record<string, any>`, which fails the static type. `artifactFields`
+ * is exported anyway for runtime inspection / reflection.
+ *
+ * Deployments must keep these fields with these names; chat-service reads
+ * them directly. Refining their types (e.g. constraining `category` to a
+ * Zod enum) is fine; renaming is not.
+ */
+export declare const artifactFields: {
+    readonly category: z.ZodString;
+    readonly description: z.ZodString;
+    readonly notes: z.ZodString;
+    readonly papers: z.ZodArray<z.ZodObject<{
+        paper_id: z.ZodString;
+        rank_rationale: z.ZodString;
+    }, z.core.$strip>>;
+    readonly claims: z.ZodArray<z.ZodObject<{
+        paper_id: z.ZodString;
+        text: z.ZodString;
+        citations: z.ZodArray<z.ZodObject<{
+            quote: z.ZodString;
+            bboxes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                page: z.ZodNumber;
+                top: z.ZodNumber;
+                left: z.ZodNumber;
+                bottom: z.ZodNumber;
+                right: z.ZodNumber;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+};
+/**
+ * The minimal Zod schema chat-service can operate on. Any plugin's schema is
+ * a superset: it spreads `artifactFields` and adds deployment fields.
+ */
+export declare const ArtifactSchema: z.ZodObject<{
+    category: z.ZodString;
+    description: z.ZodString;
+    notes: z.ZodString;
+    papers: z.ZodArray<z.ZodObject<{
+        paper_id: z.ZodString;
+        rank_rationale: z.ZodString;
+    }, z.core.$strip>>;
+    claims: z.ZodArray<z.ZodObject<{
+        paper_id: z.ZodString;
+        text: z.ZodString;
+        citations: z.ZodArray<z.ZodObject<{
+            quote: z.ZodString;
+            bboxes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                page: z.ZodNumber;
+                top: z.ZodNumber;
+                left: z.ZodNumber;
+                bottom: z.ZodNumber;
+                right: z.ZodNumber;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * The citation-grounded artifact type. Deployments may name their own
+ * extended type; this is the base chat-service operates on.
+ */
+export type Artifact = z.infer<typeof ArtifactSchema>;
+/**
+ * Render a Zod schema as a JSON Schema string for inclusion in the system
+ * prompt. The descriptions on each field serve as documentation.
+ */
+export declare function schemaForPrompt(schema: z.ZodType): string;
+//# sourceMappingURL=artifact.d.ts.map

package/dist/artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../src/artifact.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoDxB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;CAwBjB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;iBAA2B,CAAC;AAEvD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,MAAM,CAEzD"}

package/dist/artifact.js

@@ -0,0 +1,99 @@
+// Citation-grounded artifact core. chat-service hardcodes a small fixed
+// set of fields (`category`, `description`, `notes`, `papers`, `claims`)
+// because those are what the chat-tool design — `view`, `search`,
+// `str_replace`, `insert`, `write` over a citation-grounded synthesis —
+// actually depends on. Deployments extend by calling
+// `ArtifactSchema.extend({...})` with their additional fields; they do
+// not rename the core fields.
+//
+// Field names mirror flowa's `prompts/generic/aggregation_schema.py`.
+import { z } from "zod";
+const CitationBbox = z.object({
+    page: z.number().describe("Page number in the source document."),
+    top: z.number().describe("Top edge of the highlight rectangle."),
+    left: z.number().describe("Left edge of the highlight rectangle."),
+    bottom: z.number().describe("Bottom edge of the highlight rectangle."),
+    right: z.number().describe("Right edge of the highlight rectangle."),
+});
+const ArtifactCitation = z.object({
+    quote: z
+        .string()
+        .describe("Verbatim passage from the source document. Must be copied exactly — enough context to validate the claim."),
+    bboxes: z
+        .array(CitationBbox)
+        .optional()
+        .describe("Pre-computed highlight rectangles for the quote. Present on pipeline-generated citations; absent on citations added during editing."),
+});
+const ArtifactClaim = z.object({
+    paper_id: z
+        .string()
+        .describe("Identifier of the source document. Must appear in the papers[] list."),
+    text: z
+        .string()
+        .describe("The factual statement supported by the source document. One atomic fact per claim."),
+    citations: z
+        .array(ArtifactCitation)
+        .min(1)
+        .describe("One or more supporting verbatim quotes from the document identified by paper_id."),
+});
+const RankedPaper = z.object({
+    paper_id: z.string().describe("Identifier of the source document."),
+    rank_rationale: z
+        .string()
+        .describe("One sentence explaining why this document sits at this rank in the synthesis."),
+});
+/**
+ * Citation-grounded fields shared by every chat-service artifact. Deployments
+ * extend the schema by calling `ArtifactSchema.extend({...})` with their
+ * additional fields:
+ *
+ * ```ts
+ * import { ArtifactSchema } from "@flowajs/chat-service";
+ *
+ * export const MyArtifactSchema = ArtifactSchema.extend({
+ *   classification: z.string(),
+ *   classification_rationale: z.string(),
+ * });
+ * ```
+ *
+ * `.extend(...)` preserves the shape's TypeScript type, so the resulting
+ * schema stays assignable to `z.ZodType<Artifact>` at the
+ * `createApp({ schema })` call site. Spreading `...artifactFields` into a
+ * fresh `z.object({...})` works at runtime but widens the inferred shape
+ * to `Record<string, any>`, which fails the static type. `artifactFields`
+ * is exported anyway for runtime inspection / reflection.
+ *
+ * Deployments must keep these fields with these names; chat-service reads
+ * them directly. Refining their types (e.g. constraining `category` to a
+ * Zod enum) is fine; renaming is not.
+ */
+export const artifactFields = {
+    category: z
+        .string()
+        .describe("Selector identifying which result this artifact represents within its aggregate. Mirrors aggregation.results[].category in flowa's prompts/generic/aggregation_schema.py."),
+    description: z
+        .string()
+        .describe("Short human-readable summary of the synthesis."),
+    notes: z
+        .string()
+        .describe('Long-form synthesis in Markdown. Uses inline citation links: [text](#cite:paper_id "verbatim quote").'),
+    papers: z
+        .array(RankedPaper)
+        .describe("Source documents contributing to the synthesis, ordered by contribution. List position is the rank. paper_id values must be unique."),
+    claims: z
+        .array(ArtifactClaim)
+        .describe("Factual claims supporting the synthesis. Grouped by paper_id in the same order as papers[]."),
+};
+/**
+ * The minimal Zod schema chat-service can operate on. Any plugin's schema is
+ * a superset: it spreads `artifactFields` and adds deployment fields.
+ */
+export const ArtifactSchema = z.object(artifactFields);
+/**
+ * Render a Zod schema as a JSON Schema string for inclusion in the system
+ * prompt. The descriptions on each field serve as documentation.
+ */
+export function schemaForPrompt(schema) {
+    return JSON.stringify(z.toJSONSchema(schema), null, 2);
+}
+//# sourceMappingURL=artifact.js.map

package/dist/artifact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.js","sourceRoot":"","sources":["../src/artifact.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,yEAAyE;AACzE,kEAAkE;AAClE,wEAAwE;AACxE,qDAAqD;AACrD,uEAAuE;AACvE,8BAA8B;AAC9B,EAAE;AACF,sEAAsE;AAEtE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;IAChE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;IAChE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;IAClE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yCAAyC,CAAC;IACtE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;CACrE,CAAC,CAAC;AAEH,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,CACP,2GAA2G,CAC5G;IACH,MAAM,EAAE,CAAC;SACN,KAAK,CAAC,YAAY,CAAC;SACnB,QAAQ,EAAE;SACV,QAAQ,CACP,qIAAqI,CACtI;CACJ,CAAC,CAAC;AAEH,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,CACP,sEAAsE,CACvE;IACH,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,QAAQ,CACP,oFAAoF,CACrF;IACH,SAAS,EAAE,CAAC;SACT,KAAK,CAAC,gBAAgB,CAAC;SACvB,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,kFAAkF,CACnF;CACJ,CAAC,CAAC;AAEH,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;IACnE,cAAc,EAAE,CAAC;SACd,MAAM,EAAE;SACR,QAAQ,CACP,+EAA+E,CAChF;CACJ,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,CACP,2KAA2K,CAC5K;IACH,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,CAAC,gDAAgD,CAAC;IAC7D,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,CACP,uGAAuG,CACxG;IACH,MAAM,EAAE,CAAC;SACN,KAAK,CAAC,WAAW,CAAC;SAClB,QAAQ,CACP,qIAAqI,CACtI;IACH,MAAM,EAAE,CAAC;SACN,KAAK,CAAC,aAAa,CAAC;SACpB,QAAQ,CACP,6FAA6F,CAC9F;CACK,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;AAQvD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC"}

package/dist/audit.d.ts

@@ -0,0 +1,28 @@
+/** Audit logging — per-session JSON files written to storage. */
+import type { UIMessage } from "ai";
+import type { Storage } from "./storage/interface.js";
+export declare function logRequest(params: {
+    sessionId: string;
+    userId: string;
+    variantId: string;
+    messages: UIMessage[];
+}): Promise<void>;
+export declare function logStep(params: {
+    sessionId: string;
+    finishReason: string;
+    text: string;
+    toolCalls: unknown[];
+    toolResults: unknown[];
+}): Promise<void>;
+export declare function markTurnTruncated(sessionId: string): void;
+export declare function logResponse(storage: Storage, params: {
+    sessionId: string;
+    userId: string;
+    response: string;
+    toolCalls: unknown;
+    usage: unknown;
+}): Promise<void>;
+export declare function logError(storage: Storage, sessionId: string, error: string): Promise<void>;
+/** For tests: clear the per-session audit log map. */
+export declare function clearAuditLogs(): void;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAEjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAgDtD,wBAAsB,UAAU,CAAC,MAAM,EAAE;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,SAAS,EAAE,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAED,wBAAsB,OAAO,CAAC,MAAM,EAAE;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,EAAE,CAAC;IACrB,WAAW,EAAE,OAAO,EAAE,CAAC;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAsB,WAAW,CAC/B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE;IACN,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB,GACA,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,sDAAsD;AACtD,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/dist/audit.js

@@ -0,0 +1,73 @@
+/** Audit logging — per-session JSON files written to storage. */
+import { auditLogKey } from "./storage-keys.js";
+/** In-memory accumulator per session, flushed to storage after each turn completes. */
+const logs = new Map();
+function getOrCreateLog(sessionId, userId, variantId) {
+    let log = logs.get(sessionId);
+    if (!log) {
+        log = { sessionId, userId, variantId, turns: [] };
+        logs.set(sessionId, log);
+    }
+    return log;
+}
+export async function logRequest(params) {
+    const log = getOrCreateLog(params.sessionId, params.userId, params.variantId);
+    log.turns.push({
+        timestamp: new Date().toISOString(),
+        request: { messages: params.messages },
+        steps: [],
+    });
+}
+export async function logStep(params) {
+    const log = logs.get(params.sessionId);
+    if (!log)
+        return;
+    const lastTurn = log.turns.at(-1);
+    if (lastTurn) {
+        lastTurn.steps ??= [];
+        lastTurn.steps.push({
+            finishReason: params.finishReason,
+            text: params.text,
+            toolCalls: params.toolCalls,
+            toolResults: params.toolResults,
+        });
+    }
+}
+export function markTurnTruncated(sessionId) {
+    const log = logs.get(sessionId);
+    if (!log)
+        return;
+    const lastTurn = log.turns.at(-1);
+    if (lastTurn) {
+        lastTurn.truncated = true;
+    }
+}
+export async function logResponse(storage, params) {
+    const log = logs.get(params.sessionId);
+    if (!log)
+        return;
+    const lastTurn = log.turns.at(-1);
+    if (lastTurn) {
+        lastTurn.response = {
+            text: params.response,
+            toolCalls: params.toolCalls,
+            usage: params.usage,
+        };
+    }
+    await storage.writeJson(auditLogKey(log.variantId, log.sessionId), log);
+}
+export async function logError(storage, sessionId, error) {
+    const log = logs.get(sessionId);
+    if (!log)
+        return;
+    const lastTurn = log.turns.at(-1);
+    if (lastTurn) {
+        lastTurn.error = error;
+    }
+    await storage.writeJson(auditLogKey(log.variantId, log.sessionId), log);
+}
+/** For tests: clear the per-session audit log map. */
+export function clearAuditLogs() {
+    logs.clear();
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"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"}

package/dist/auth/jwt.d.ts

@@ -0,0 +1,18 @@
+export interface SessionClaims {
+    session_id: string;
+    variant_id: string;
+    user_id: string;
+    category: string;
+}
+export interface SessionTokenConfig {
+    secret: string;
+    ttlSeconds: number;
+}
+export declare function signSessionToken(claims: SessionClaims, config: SessionTokenConfig): Promise<{
+    token: string;
+    expiresAt: Date;
+}>;
+export declare function verifySessionToken(token: string, config: SessionTokenConfig): Promise<SessionClaims & {
+    expiresAt: Date;
+}>;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/auth/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/auth/jwt.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CAS7C;AAED,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,aAAa,GAAG;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CAU9C"}

package/dist/auth/jwt.js

@@ -0,0 +1,23 @@
+import { SignJWT, jwtVerify } from "jose";
+export async function signSessionToken(claims, config) {
+    const expiresAt = new Date(Date.now() + config.ttlSeconds * 1000);
+    const secret = new TextEncoder().encode(config.secret);
+    const token = await new SignJWT(claims)
+        .setProtectedHeader({ alg: "HS256" })
+        .setExpirationTime(expiresAt)
+        .setIssuedAt()
+        .sign(secret);
+    return { token, expiresAt };
+}
+export async function verifySessionToken(token, config) {
+    const secret = new TextEncoder().encode(config.secret);
+    const { payload } = await jwtVerify(token, secret);
+    return {
+        session_id: payload.session_id,
+        variant_id: payload.variant_id,
+        user_id: payload.user_id,
+        category: payload.category,
+        expiresAt: new Date(payload.exp * 1000),
+    };
+}
+//# sourceMappingURL=jwt.js.map

package/dist/auth/jwt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.js","sourceRoot":"","sources":["../../src/auth/jwt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAc1C,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAqB,EACrB,MAA0B;IAE1B,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,MAAM,IAAI,OAAO,CAAC,MAA4C,CAAC;SAC1E,kBAAkB,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;SACpC,iBAAiB,CAAC,SAAS,CAAC;SAC5B,WAAW,EAAE;SACb,IAAI,CAAC,MAAM,CAAC,CAAC;IAChB,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAC9B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAa,EACb,MAA0B;IAE1B,MAAM,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACvD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACnD,OAAO;QACL,UAAU,EAAE,OAAO,CAAC,UAAoB;QACxC,UAAU,EAAE,OAAO,CAAC,UAAoB;QACxC,OAAO,EAAE,OAAO,CAAC,OAAiB;QAClC,QAAQ,EAAE,OAAO,CAAC,QAAkB;QACpC,SAAS,EAAE,IAAI,IAAI,CAAE,OAAO,CAAC,GAAc,GAAG,IAAI,CAAC;KACpD,CAAC;AACJ,CAAC"}

package/dist/auth/oidc.d.ts

@@ -0,0 +1,30 @@
+import { type JWTPayload } from "jose";
+import type { MiddlewareHandler } from "hono";
+export interface OidcValidatorConfig {
+    jwksUrl: string;
+    issuer: string;
+    audience: string;
+    /**
+     * When true, decode the JWT body without verifying the signature. Useful
+     * for local development against a stub IDP. NEVER enable in production —
+     * the token is trusted as-is.
+     */
+    devMode?: boolean;
+}
+/**
+ * Validate a Bearer token from an Authorization header against an OIDC
+ * IDP. Returns the decoded claims on success; throws on missing header,
+ * malformed token, or signature/audience/issuer mismatch.
+ *
+ * Generic over IDP — works against any OIDC-compliant provider (Auth0,
+ * Keycloak, Okta, GitHub, etc.).
+ */
+export declare function validateOidcToken(authHeader: string | undefined, config: OidcValidatorConfig): Promise<JWTPayload>;
+/**
+ * Hono middleware factory that validates the Authorization header against
+ * the configured OIDC IDP. The decoded claims are stored on the context
+ * variable `oidcClaims` for downstream handlers to read via
+ * `c.get("oidcClaims")`.
+ */
+export declare function createOidcMiddleware(config: OidcValidatorConfig): MiddlewareHandler;
+//# sourceMappingURL=oidc.d.ts.map

package/dist/auth/oidc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc.d.ts","sourceRoot":"","sources":["../../src/auth/oidc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAE9C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAaD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,UAAU,CAAC,CA0BrB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,mBAAmB,GAC1B,iBAAiB,CAanB"}