generalcontext 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+General Context SDK
+Copyright 2026 General Context Labs, Inc.
+
+This product includes software developed at General Context Labs, Inc.
+(https://generalcontextlabs.com).

package/README.md

@@ -1,3 +1,120 @@
-# Temporary Holding Version
+# generalcontext
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Record your agent's model calls for General Context. Your agent never waits on us, and a failure on our side is logged and dropped, never thrown. No runtime dependencies. Supports OpenAI (`chat.completions`, `responses`) and Anthropic (`messages`), streamed or not.
+
+## Install
+
+```sh
+npm install generalcontext
+```
+
+Set `GENERALCONTEXT_API_KEY` to the key from your workspace's Connect page.
+
+## Initialize
+
+Call once per process, before your agent makes model calls. Every OpenAI and Anthropic client is recorded, including ones created earlier.
+
+```ts
+import OpenAI from 'openai';
+import Anthropic from '@anthropic-ai/sdk';
+import { initialize } from 'generalcontext';
+
+initialize({ appName: 'support-agent', instrumentModules: { openAI: OpenAI, anthropic: Anthropic } });
+```
+
+## Configuration
+
+| Option | Default | |
+| - | - | - |
+| `apiKey` | `GENERALCONTEXT_API_KEY` | |
+| `baseUrl` | `GENERALCONTEXT_BASE_URL`, else `https://generalcontextlabs.com` | The option wins over the env var. Must be `https://`, except `http://localhost`, `127.0.0.1` or `[::1]`. Other URLs are refused and nothing is sent. |
+| `appName` | none | Sent with every batch. |
+| `redact` | `false` | See [Redaction](#redaction). |
+| `beforeSend` | none | `(call) => call \| null`. Runs at send time on each call, before redaction. Return the call (edited or not) to send it, or `null` to drop it. A throw drops the call. |
+| `instrumentModules` | installed `openai` and `@anthropic-ai/sdk` | Pass these whenever a bundler is involved. |
+| `instrumentFetch` | `false` | SDK clients are always recorded. Set `true` to also record raw `fetch` POSTs to any `/chat/completions` URL. |
+| `disableBatch` | `false` | Send each call right away. |
+
+| Env var | |
+| - | - |
+| `GENERALCONTEXT_API_KEY` | API key, if `apiKey` is not passed. |
+| `GENERALCONTEXT_BASE_URL` | Collector URL, if `baseUrl` is not passed. |
+| `GENERALCONTEXT_REDACT_SALT` | Secret that keeps redaction placeholders stable across processes. |
+| `GENERALCONTEXT_DISABLED` | `1`, `true` or `yes` makes `initialize()` do nothing. |
+
+Requests never follow redirects. A call over 4 MB is dropped, and the queue holds at most 5000 calls or 64 MB. Pending calls are flushed when the process is about to exit, for at most 2 seconds.
+
+## Proxies
+
+Node's built-in `fetch` ignores `HTTPS_PROXY` by default. On Node 24+, set `NODE_USE_ENV_PROXY=1`. On older versions, install a global dispatcher (for example undici's `setGlobalDispatcher(new EnvHttpProxyAgent())`). If your proxy inspects TLS, point `NODE_EXTRA_CA_CERTS` at its CA certificate.
+
+## Next.js
+
+Initialize in `instrumentation.ts` at the project root, not in a route file:
+
+```ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const { initialize } = await import('generalcontext');
+    const { OpenAI } = await import('openai');
+    const anthropic = await import('@anthropic-ai/sdk');
+    initialize({ appName: 'my-agent', instrumentModules: { openAI: OpenAI, anthropic } });
+  }
+}
+```
+
+Keep the SDKs out of the bundle so routes use the instance we patched:
+
+```ts
+// next.config.ts
+export default { serverExternalPackages: ['openai', '@anthropic-ai/sdk'] };
+```
+
+Use the Node.js runtime. The Edge runtime is not supported.
+
+## Sessions and tasks
+
+Tag calls with your own ids. Tags carry across `await`.
+
+```ts
+import { withSession, task } from 'generalcontext';
+
+await withSession({ sessionId: conversationId, userId: 'u_42', channel: 'chat' }, async () => {
+  await task('triage', () => client.chat.completions.create({ ... }));
+});
+```
+
+`withSession(conversationId, fn)` also works. `conversation({ id, ... }, fn)` is the older name.
+
+## Serverless and scripts
+
+Calls send in the background. Before a function or script exits:
+
+```ts
+await flush(); // never throws
+```
+
+## Outcomes and events
+
+Both flush pending calls first, so the session exists before the outcome or event arrives. Both return `true` when accepted and never throw.
+
+```ts
+await reportOutcome(conversationId, 'fail', 'customer reopened the ticket');
+
+await logEvent({ sessionId: conversationId, eventType: 'order.refunded', eventId: `refund-${refundId}`, properties: { amount: 42.5 } });
+await logEvent({ sessionId: conversationId, eventType: 'handoff.to_human', eventId: `handoff-${ticketId}` });
+```
+
+Pass a stable `eventId` so retries dedupe. `properties` are flat strings, numbers and booleans. `timestamp` defaults to now.
+
+## Redaction
+
+`initialize({ redact: true })` replaces emails, phone numbers and card or SSN-like numbers with placeholders such as `<email:3f9a1c>` before anything leaves your process. Set `GENERALCONTEXT_REDACT_SALT` to one secret in every process so the same value gets the same placeholder. Or pass your own `(text) => text`. Redaction also applies to `reportOutcome` and `logEvent`, so a redacted session id still matches its calls.
+
+## One client only
+
+`wrap(client, { redact })` records a single client instance without patching the SDK. Its `redact` applies to that client only. If `initialize()` already patched the SDK, the client is recorded with the `initialize()` settings.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+export declare const VERSION = "0.2.0";
+type Metadata = Record<string, string | number | boolean>;
+export type Session = {
+    sessionId: string;
+    userId?: string;
+    channel?: string;
+    product?: string;
+    metadata?: Metadata;
+};
+type Tags = {
+    id: string;
+    user_id?: string;
+    channel?: string;
+    product?: string;
+    metadata?: Metadata;
+};
+type Api = 'openai-chat' | 'openai-responses' | 'anthropic';
+export type Call = {
+    api: Api;
+    conversation: Tags | null;
+    task: string | null;
+    request: unknown;
+    response: unknown;
+    started_at: string;
+    ended_at: string;
+    error: string | null;
+};
+type Scrub = (text: string) => string;
+type BeforeSend = (call: Call) => Call | null | undefined;
+export type InitializeOptions = {
+    apiKey?: string;
+    /** Collector URL. Must be https://, except http://localhost, 127.0.0.1 or [::1]. */
+    baseUrl?: string;
+    appName?: string;
+    /** true for built-in email/phone/card/SSN placeholders, or your own (text) => text. */
+    redact?: boolean | Scrub;
+    /** Runs at send time on each call, before redaction. Return the call to send, or null to drop it. */
+    beforeSend?: BeforeSend;
+    /** SDK classes or modules to patch, e.g. { openAI: OpenAI, anthropic: Anthropic }. */
+    instrumentModules?: {
+        openAI?: unknown;
+        anthropic?: unknown;
+    };
+    /** Also record raw fetch POSTs to any URL ending /chat/completions. Default false. */
+    instrumentFetch?: boolean;
+    /** Send each call right away instead of batching. */
+    disableBatch?: boolean;
+};
+/** Configure recording once per process, before your agent makes model calls. */
+export declare function initialize(options?: InitializeOptions): void;
+/** Tag every call made inside `run` with one session. `conversation` is the same function. */
+export declare function withSession<T>(session: Session | string, run: () => T): T;
+/** Older name for withSession. Accepts { id } as well as { sessionId }. */
+export declare function conversation<T>(tags: Session | {
+    id: string;
+    channel?: string;
+    product?: string;
+    metadata?: Metadata;
+} | string, run: () => T): T;
+/** Tag every call made inside `run` with a task name, such as one step of your agent loop. */
+export declare function task<T>(name: string, run: () => T): T;
+/** Wait until recorded calls are sent. Call before a serverless function or script exits. Never throws. */
+export declare function flush(): Promise<void>;
+/** Mark how a session ended. Returns true when the platform accepted it. Never throws. */
+export declare function reportOutcome(sessionId: string, outcome: 'success' | 'fail', note?: string): Promise<boolean>;
+export type AppEvent = {
+    sessionId: string;
+    eventType: string;
+    properties?: Metadata;
+    eventId?: string;
+    timestamp?: string | Date;
+};
+/** Record something that happened in your systems, such as 'order.refunded'. Pass a stable eventId so retries dedupe. Never throws. */
+export declare function logEvent(event: AppEvent): Promise<boolean>;
+/**
+ * Record one client instance only, without initialize(). Returns the same client.
+ * `redact` applies to this client only. If initialize() already patched the SDK, its settings apply instead.
+ */
+export declare function wrap<C extends object>(client: C, options?: {
+    redact?: boolean | Scrub;
+}): C;
+export {};

package/dist/index.js

@@ -0,0 +1,591 @@
+// Copyright 2026 General Context Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+// Record your agent's model calls for General Context, without changing how it runs.
+//
+//   import OpenAI from 'openai';
+//   import { initialize, withSession } from 'generalcontext';
+//
+//   initialize({ instrumentModules: { openAI: OpenAI } });
+//   await withSession(conversationId, async () => { ... });
+//
+// Every SDK model call (history sent, tools offered, reply and tool calls) is queued and sent in
+// the background. Raw fetch capture is opt-in with instrumentFetch: true. Your agent never waits on General Context, and a failure on our side is
+// logged and dropped, never thrown. No runtime dependencies.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHmac, randomBytes, randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+export const VERSION = '0.2.0';
+const BATCH = 20;
+const MAX_QUEUE = 5000;
+const MAX_CALL_BYTES = 4_000_000; // the server rejects larger calls
+const MAX_QUEUE_BYTES = 64_000_000;
+const MAX_BATCH_BYTES = 4_000_000;
+const SEND_TIMEOUT_MS = 15_000;
+const DIRECT_TIMEOUT_MS = 10_000; // reportOutcome and logEvent
+const EXIT_FLUSH_MS = 2_000;
+const DEFAULT_BASE_URL = 'https://generalcontextlabs.com';
+const config = {
+    apiKey: undefined,
+    baseUrl: undefined,
+    appName: undefined,
+    scrub: null,
+    beforeSend: null,
+    disableBatch: false,
+};
+const scope = new AsyncLocalStorage();
+const queue = [];
+let queuedBytes = 0;
+let initialized = false;
+let sending = null;
+let timer = null;
+let originalFetch = globalThis.fetch;
+let exitHooked = false;
+let stopped = false; // set when the exit flush runs out of time
+const inflight = new Set();
+const apiKey = () => config.apiKey ?? process.env.GENERALCONTEXT_API_KEY;
+// Explicit option, then env var, then default. Trailing slashes are trimmed without a regex.
+const trimSlashes = (url) => { let end = url.length; while (end > 0 && url[end - 1] === '/')
+    end--; return url.slice(0, end); };
+const baseUrl = () => trimSlashes(config.baseUrl ?? process.env.GENERALCONTEXT_BASE_URL ?? DEFAULT_BASE_URL);
+const warn = (message) => console.warn(`[generalcontext] ${message}`);
+// Warn at most once per minute for each key, so a broken collector cannot flood logs.
+const lastWarned = new Map();
+function warnLimited(key, message) {
+    const now = Date.now();
+    if (now - (lastWarned.get(key) ?? -Infinity) < 60_000)
+        return;
+    lastWarned.set(key, now);
+    warn(message);
+}
+// Only send the API key over https, or plain http to this machine for local development.
+function secureUrl(url) {
+    try {
+        const u = new URL(url);
+        return u.protocol === 'https:' || (u.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(u.hostname));
+    }
+    catch {
+        return false;
+    }
+}
+const disabledByEnv = () => /^(1|true|yes)$/i.test((process.env.GENERALCONTEXT_DISABLED ?? '').trim());
+/** Configure recording once per process, before your agent makes model calls. */
+export function initialize(options = {}) {
+    if (initialized) {
+        warn('initialize was already called; ignoring the second call');
+        return;
+    }
+    initialized = true;
+    if (disabledByEnv()) {
+        warn('GENERALCONTEXT_DISABLED is set; recording is off');
+        return;
+    }
+    config.apiKey = options.apiKey ?? process.env.GENERALCONTEXT_API_KEY;
+    config.baseUrl = options.baseUrl;
+    config.appName = options.appName;
+    config.scrub = redactor(options.redact);
+    config.beforeSend = options.beforeSend ?? null;
+    config.disableBatch = options.disableBatch ?? false;
+    if (!config.apiKey)
+        warn('no API key; set GENERALCONTEXT_API_KEY or pass apiKey');
+    if (!secureUrl(baseUrl()))
+        warn(`baseUrl ${baseUrl()} is not https; nothing will be sent`);
+    const modules = options.instrumentModules ?? autoload();
+    if (modules.openAI)
+        patchOpenAI(modules.openAI);
+    if (modules.anthropic)
+        patchAnthropic(modules.anthropic);
+    if (options.instrumentFetch ?? false)
+        patchFetch();
+}
+// Load installed SDKs when the caller did not pass them. Bundlers can hide these; pass instrumentModules there.
+function autoload() {
+    const require = createRequire(import.meta.url);
+    const load = (name) => { try {
+        return require(name);
+    }
+    catch {
+        return undefined;
+    } };
+    return { openAI: load('openai'), anthropic: load('@anthropic-ai/sdk') };
+}
+// Accept a module namespace, its default export, or the client class itself.
+function clientClass(value, name) {
+    const v = value;
+    if (typeof v === 'function' && (v.Messages || v.Chat))
+        return v;
+    return v?.[name] ?? v?.default?.[name] ?? (typeof v === 'function' ? v : typeof v?.default === 'function' ? v.default : undefined);
+}
+function patchOpenAI(value) {
+    const OpenAI = clientClass(value, 'OpenAI');
+    patchMethod(OpenAI?.Chat?.Completions?.prototype, 'create', 'openai-chat');
+    patchMethod(OpenAI?.Responses?.prototype, 'create', 'openai-responses');
+}
+function patchAnthropic(value) {
+    const Anthropic = clientClass(value, 'Anthropic');
+    // messages.stream() calls messages.create({ stream: true }) internally, so it is covered too.
+    patchMethod(Anthropic?.Messages?.prototype, 'create', 'anthropic');
+}
+const MARK = Symbol.for('generalcontext.recorded');
+function patchMethod(owner, name, api) {
+    const original = owner?.[name];
+    if (typeof original !== 'function' || original[MARK])
+        return;
+    owner[name] = recording(original, api);
+}
+/** Tag every call made inside `run` with one session. `conversation` is the same function. */
+export function withSession(session, run) {
+    const s = typeof session === 'string' ? { sessionId: session } : session;
+    const tags = { id: String(s.sessionId) };
+    if (s.userId)
+        tags.user_id = s.userId;
+    if (s.channel)
+        tags.channel = s.channel;
+    if (s.product)
+        tags.product = s.product;
+    if (s.metadata)
+        tags.metadata = s.metadata;
+    return scope.run({ ...scope.getStore(), tags }, run);
+}
+/** Older name for withSession. Accepts { id } as well as { sessionId }. */
+export function conversation(tags, run) {
+    if (typeof tags === 'object' && 'id' in tags) {
+        const { id, ...rest } = tags;
+        return withSession({ ...rest, sessionId: id }, run);
+    }
+    return withSession(tags, run);
+}
+/** Tag every call made inside `run` with a task name, such as one step of your agent loop. */
+export function task(name, run) {
+    return scope.run({ ...scope.getStore(), task: name }, run);
+}
+// Runs before the caller's await continues, so only take the snapshot here. Redaction and beforeSend run at send time.
+function record(call, at, scrub) {
+    try {
+        if (!apiKey()) {
+            warnLimited('no-key', 'GENERALCONTEXT_API_KEY is not set; a model call was not recorded');
+            return;
+        }
+        const json = JSON.stringify({ ...call, conversation: at?.tags ?? null, task: at?.task ?? null });
+        const bytes = Buffer.byteLength(json);
+        if (bytes > MAX_CALL_BYTES) {
+            warnLimited('oversized', `a model call of ${bytes} bytes is over the ${MAX_CALL_BYTES} byte limit and was dropped`);
+            return;
+        }
+        if (queue.length >= MAX_QUEUE || queuedBytes + bytes > MAX_QUEUE_BYTES) {
+            warnLimited('queue-full', 'queue is full; a model call was dropped');
+            return;
+        }
+        queue.push({ json, bytes, scrub });
+        queuedBytes += bytes;
+        hookExit();
+        if (config.disableBatch || queue.length >= BATCH)
+            void send();
+        else if (!timer) {
+            timer = setTimeout(() => { timer = null; void send(); }, 500);
+            timer.unref?.();
+        }
+    }
+    catch (error) {
+        warnLimited('record', `could not record a model call: ${error.message}`);
+    }
+}
+// Flush once when the event loop empties, capped at EXIT_FLUSH_MS. Pending requests are aborted at the cap.
+function hookExit() {
+    if (exitHooked)
+        return;
+    exitHooked = true;
+    process.once('beforeExit', () => {
+        const cap = setTimeout(() => { stopped = true; for (const c of inflight)
+            c.abort(); }, EXIT_FLUSH_MS);
+        cap.unref?.();
+        void flush().finally(() => clearTimeout(cap));
+    });
+}
+// Apply beforeSend and redaction. Returns the JSON to send, or null to drop.
+function prepare(entry) {
+    let call = JSON.parse(entry.json);
+    if (config.beforeSend) {
+        try {
+            call = config.beforeSend(call);
+        }
+        catch (error) {
+            warnLimited('before-send', `beforeSend threw; a model call was dropped: ${error.message}`);
+            return null;
+        }
+        if (call == null)
+            return null;
+    }
+    return JSON.stringify(scrubbed(call, entry.scrub === undefined ? config.scrub : entry.scrub));
+}
+async function post(path, body, timeoutMs) {
+    const url = `${baseUrl()}${path}`;
+    if (!secureUrl(url)) {
+        warnLimited('insecure', `refusing to send to ${baseUrl()}: baseUrl must be https`);
+        return null;
+    }
+    if (stopped)
+        return null;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    timeout.unref?.();
+    inflight.add(controller);
+    try {
+        return await originalFetch(url, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${apiKey()}`, 'Content-Type': 'application/json' },
+            body,
+            redirect: 'error', // never forward the API key to another host
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        warnLimited(`send:${path}`, `could not reach ${path}: ${error.message}`);
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+        inflight.delete(controller);
+    }
+}
+function send() {
+    if (sending)
+        return sending;
+    sending = (async () => {
+        const envelope = JSON.stringify({ sdk: `node/${VERSION}`, app: config.appName });
+        while (queue.length && !stopped) {
+            // Up to BATCH calls and MAX_BATCH_BYTES per request.
+            const parts = [];
+            let size = envelope.length + 16;
+            while (queue.length && parts.length < BATCH) {
+                const entry = queue[0];
+                let json;
+                try {
+                    json = prepare(entry);
+                }
+                catch (error) {
+                    warnLimited('prepare', `could not prepare a model call: ${error.message}`);
+                    json = null;
+                }
+                const bytes = json === null ? 0 : Buffer.byteLength(json);
+                if (json !== null && bytes > MAX_CALL_BYTES) {
+                    warnLimited('oversized', `a model call of ${bytes} bytes is over the ${MAX_CALL_BYTES} byte limit and was dropped`);
+                    json = null;
+                }
+                if (json !== null && parts.length && size + bytes + 1 > MAX_BATCH_BYTES)
+                    break; // send what we have; retry this one next
+                queue.shift();
+                queuedBytes -= entry.bytes;
+                if (json === null)
+                    continue;
+                parts.push(json);
+                size += bytes + 1;
+            }
+            if (!parts.length)
+                continue;
+            const body = `{"calls":[${parts.join(',')}],${envelope.slice(1)}`;
+            const response = await post('/api/platform-collect/sdk', body, SEND_TIMEOUT_MS);
+            if (response && !response.ok)
+                warnLimited('rejected', `${parts.length} calls not accepted: ${response.status}`);
+        }
+    })().catch(() => { }).finally(() => { sending = null; });
+    return sending;
+}
+/** Wait until recorded calls are sent. Call before a serverless function or script exits. Never throws. */
+export async function flush() {
+    if (timer) {
+        clearTimeout(timer);
+        timer = null;
+    }
+    try {
+        await send();
+    }
+    catch { /* send already logs */ }
+}
+const scrubText = (value) => (config.scrub ? config.scrub(value) : value);
+/** Mark how a session ended. Returns true when the platform accepted it. Never throws. */
+export async function reportOutcome(sessionId, outcome, note) {
+    try {
+        if (!apiKey()) {
+            warnLimited('no-key', 'GENERALCONTEXT_API_KEY is not set; outcome not reported');
+            return false;
+        }
+        await flush();
+        const body = { session_id: scrubText(String(sessionId)), outcome, note: note == null ? null : scrubText(note) };
+        const response = await post('/api/platform-collect/outcomes', JSON.stringify(body), DIRECT_TIMEOUT_MS);
+        return Boolean(response?.ok);
+    }
+    catch {
+        return false;
+    }
+}
+/** Record something that happened in your systems, such as 'order.refunded'. Pass a stable eventId so retries dedupe. Never throws. */
+export async function logEvent(event) {
+    try {
+        if (!apiKey()) {
+            warnLimited('no-key', 'GENERALCONTEXT_API_KEY is not set; event not logged');
+            return false;
+        }
+        await flush();
+        const timestamp = event.timestamp instanceof Date ? event.timestamp.toISOString() : event.timestamp ?? new Date().toISOString();
+        const properties = Object.fromEntries(Object.entries(event.properties ?? {}).map(([k, v]) => [k, typeof v === 'string' ? scrubText(v) : v]));
+        const body = { events: [{
+                    event_id: event.eventId ?? randomUUID(), event_type: scrubText(event.eventType), timestamp,
+                    session_id: scrubText(String(event.sessionId)), properties,
+                }] };
+        const response = await post('/api/platform-collect/events', JSON.stringify(body), DIRECT_TIMEOUT_MS);
+        return Boolean(response?.ok);
+    }
+    catch {
+        return false;
+    }
+}
+// Wrap an SDK create method. The SDK's own promise is returned untouched; recording happens on a side branch.
+function recording(create, api, scrub) {
+    const wrapped = function (...args) {
+        const started = new Date().toISOString();
+        const at = scope.getStore();
+        const request = args[0];
+        // Mark the call so the fetch patch does not record it a second time.
+        const reply = scope.run({ ...at, inSdkCall: true }, () => create.apply(this, args));
+        if (!reply || typeof reply.then !== 'function')
+            return reply;
+        reply.then(response => {
+            const done = (result) => record({ api, request, response: result, started_at: started, ended_at: new Date().toISOString(), error: null }, at, scrub);
+            if (request?.stream && isStream(response))
+                observeStream(response, api, done);
+            else
+                done(response);
+        }, error => {
+            record({ api, request, response: null, started_at: started, ended_at: new Date().toISOString(), error: String(error?.message ?? error) }, at, scrub);
+        });
+        return reply;
+    };
+    wrapped[MARK] = true;
+    return wrapped;
+}
+const isStream = (value) => typeof value?.iterator === 'function';
+// Both SDKs' Stream classes read chunks through `this.iterator`, including tee() and toReadableStream().
+// Replacing it keeps the object, its type and its methods, and lets us see each chunk once.
+function observeStream(stream, api, done) {
+    const source = stream.iterator.bind(stream);
+    stream.iterator = async function* () {
+        const assemble = api === 'anthropic' ? anthropicAssembler() : openAIAssembler();
+        let finished = false;
+        try {
+            for await (const chunk of { [Symbol.asyncIterator]: source }) {
+                try {
+                    assemble.add(chunk);
+                }
+                catch { /* never break the caller's stream */ }
+                yield chunk;
+            }
+            finished = true;
+        }
+        finally {
+            if (finished)
+                done(assemble.result());
+        }
+    };
+}
+function openAIAssembler() {
+    let model, id, usage = null, final = null;
+    const choices = [];
+    return {
+        add(chunk) {
+            // Responses API events: the final response arrives whole.
+            if (chunk.type) {
+                if (chunk.type === 'response.completed')
+                    final = chunk.response;
+                return;
+            }
+            model ??= chunk.model;
+            id ??= chunk.id;
+            if (chunk.usage)
+                usage = chunk.usage;
+            for (const c of chunk.choices ?? []) {
+                const choice = choices[c.index] ??= { index: c.index, message: { role: 'assistant', content: null }, finish_reason: null };
+                const d = c.delta ?? {};
+                if (d.role)
+                    choice.message.role = d.role;
+                if (d.content)
+                    choice.message.content = (choice.message.content ?? '') + d.content;
+                for (const t of d.tool_calls ?? []) {
+                    const calls = choice.message.tool_calls ??= [];
+                    const call = calls[t.index] ??= { id: t.id, type: 'function', function: { name: '', arguments: '' } };
+                    if (t.id)
+                        call.id = t.id;
+                    if (t.function?.name)
+                        call.function.name += t.function.name;
+                    if (t.function?.arguments)
+                        call.function.arguments += t.function.arguments;
+                }
+                if (c.finish_reason)
+                    choice.finish_reason = c.finish_reason;
+            }
+        },
+        result: () => final ?? ({ id, object: 'chat.completion', model, choices: choices.filter(Boolean), usage }),
+    };
+}
+function anthropicAssembler() {
+    let message = null;
+    const json = [];
+    return {
+        add(event) {
+            if (event.type === 'message_start')
+                message = { ...event.message, content: [] };
+            else if (!message)
+                return;
+            else if (event.type === 'content_block_start') {
+                message.content[event.index] = { ...event.content_block };
+                json[event.index] = '';
+            }
+            else if (event.type === 'content_block_delta') {
+                const block = message.content[event.index], d = event.delta;
+                if (d.type === 'text_delta')
+                    block.text = (block.text ?? '') + d.text;
+                else if (d.type === 'input_json_delta')
+                    json[event.index] += d.partial_json;
+                else if (d.type === 'thinking_delta')
+                    block.thinking = (block.thinking ?? '') + d.thinking;
+            }
+            else if (event.type === 'content_block_stop') {
+                const block = message.content[event.index];
+                if (json[event.index]) {
+                    try {
+                        block.input = JSON.parse(json[event.index]);
+                    }
+                    catch {
+                        block.input = json[event.index];
+                    }
+                }
+            }
+            else if (event.type === 'message_delta') {
+                Object.assign(message, event.delta);
+                message.usage = { ...message.usage, ...event.usage };
+            }
+        },
+        result: () => message,
+    };
+}
+// Record raw fetch POSTs to chat-completions endpoints made without a patched SDK.
+function patchFetch() {
+    const current = globalThis.fetch;
+    if (typeof current !== 'function' || current[MARK])
+        return;
+    originalFetch = current;
+    const patched = async function (input, init) {
+        const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+        const at = scope.getStore();
+        const watch = method === 'POST' && /\/chat\/completions\/?(\?.*)?$/.test(url) && !at?.inSdkCall && !url.startsWith(`${baseUrl()}/api/platform-collect/`);
+        if (!watch)
+            return current(input, init);
+        const started = new Date().toISOString();
+        let request = null;
+        try {
+            request = typeof init?.body === 'string' ? JSON.parse(init.body) : input instanceof Request ? await input.clone().json() : null;
+        }
+        catch { /* not JSON */ }
+        const base = { api: 'openai-chat', request, started_at: started };
+        let response;
+        try {
+            response = await current(input, init);
+        }
+        catch (error) {
+            record({ ...base, response: null, ended_at: new Date().toISOString(), error: String(error?.message ?? error) }, at);
+            throw error;
+        }
+        try {
+            const copy = response.clone();
+            void (async () => {
+                try {
+                    const text = await copy.text();
+                    const ended = new Date().toISOString();
+                    if (!response.ok)
+                        return record({ ...base, response: null, ended_at: ended, error: `HTTP ${response.status}: ${text.slice(0, 500)}` }, at);
+                    const sse = (response.headers.get('content-type') ?? '').includes('text/event-stream');
+                    record({ ...base, response: sse ? assembleSSE(text) : JSON.parse(text), ended_at: ended, error: null }, at);
+                }
+                catch (error) {
+                    warn(`could not record a fetch call: ${error.message}`);
+                }
+            })();
+        }
+        catch { /* body already used */ }
+        return response;
+    };
+    patched[MARK] = true;
+    globalThis.fetch = patched;
+}
+function assembleSSE(text) {
+    const assemble = openAIAssembler();
+    for (const line of text.split('\n')) {
+        const data = line.startsWith('data:') ? line.slice(5).trim() : '';
+        if (data && data !== '[DONE]') {
+            try {
+                assemble.add(JSON.parse(data));
+            }
+            catch { /* skip bad event */ }
+        }
+    }
+    return assemble.result();
+}
+const PATTERNS = [
+    // Bounded repeats and a token-start lookbehind keep this linear on adversarial input.
+    ['email', /(?<![A-Za-z0-9._%+-])[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(?:\.[A-Za-z0-9-]{1,63}){0,8}\.[A-Za-z]{2,24}/g],
+    ['card', /\b(?:\d[ -]?){13,16}\b/g],
+    ['ssn', /\b\d{3}-\d{2}-\d{4}\b/g],
+    ['phone', /(?<![\w])\+?1?[\s.-]?\(?\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}(?![\w])/g],
+];
+function redactor(redact) {
+    if (typeof redact === 'function')
+        return redact;
+    if (!redact)
+        return null;
+    let salt = process.env.GENERALCONTEXT_REDACT_SALT;
+    if (!salt) {
+        warn('GENERALCONTEXT_REDACT_SALT is not set; placeholders will differ between processes');
+        salt = randomBytes(16).toString('hex');
+    }
+    const placeholder = (kind, value) => {
+        const digits = value.replace(/\D/g, '');
+        const normal = kind === 'email' ? value.toLowerCase() : kind === 'phone' ? digits.slice(-10) : digits;
+        return `<${kind}:${createHmac('sha256', salt).update(normal).digest('hex').slice(0, 6)}>`;
+    };
+    return text => PATTERNS.reduce((result, [kind, pattern]) => result.replace(pattern, match => placeholder(kind, match)), text);
+}
+function scrubbed(value, scrub) {
+    if (!scrub)
+        return value;
+    if (typeof value === 'string')
+        return scrub(value);
+    if (Array.isArray(value))
+        return value.map(item => scrubbed(item, scrub));
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, scrubbed(item, scrub)]));
+    return value;
+}
+/**
+ * Record one client instance only, without initialize(). Returns the same client.
+ * `redact` applies to this client only. If initialize() already patched the SDK, its settings apply instead.
+ */
+export function wrap(client, options = {}) {
+    if (disabledByEnv())
+        return client;
+    const scrub = options.redact === undefined ? undefined : redactor(options.redact);
+    const target = client;
+    const owners = [];
+    if (target.chat?.completions?.create)
+        owners.push([target.chat.completions, 'openai-chat']);
+    if (target.responses?.create)
+        owners.push([target.responses, 'openai-responses']);
+    if (!target.chat && target.messages?.create)
+        owners.push([target.messages, 'anthropic']);
+    if (!owners.length)
+        throw new TypeError('wrap expects an OpenAI or Anthropic client');
+    for (const [owner, api] of owners) {
+        if (!owner.create[MARK])
+            owner.create = recording(owner.create.bind(owner), api, scrub);
+    }
+    return client;
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "generalcontext",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Record your agent's OpenAI and Anthropic calls for General Context review and testing.",
+  "license": "Apache-2.0",
+  "author": "General Context Labs <research@generalcontextlabs.com>",
+  "homepage": "https://generalcontextlabs.com/platform/docs/sdk",
+  "bugs": "https://github.com/GeneralContext/sdk/issues",
+  "keywords": ["llm", "agents", "observability", "evaluation", "openai", "anthropic", "opentelemetry"],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "tsc -p . && node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^1.6.0",
+    "@types/node": "^22.20.5",
+    "openai": "^7.53.0",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GeneralContext/sdk.git",
+    "directory": "node"
+  }
+}