@raindrop-ai/openai-managed-agents 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raindrop AI
+
+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,137 @@
+# Raindrop for the OpenAI Agents API
+
+Capture the managed Agents API (`openai.beta.agents.sessions`) in Raindrop.
+This package uses `openai`, the OpenAI TypeScript SDK. For the separate,
+in-process `@openai/agents` framework, use `@raindrop-ai/openai-agents`.
+
+Requires Node.js 22+ and OpenAI SDK 7.15.x–7.x.
+
+```sh
+pnpm add @raindrop-ai/openai-managed-agents openai
+```
+
+## Quick start
+
+```ts
+import OpenAI from "openai";
+import { createRaindropOpenAIManagedAgents } from "@raindrop-ai/openai-managed-agents";
+
+const raindrop = createRaindropOpenAIManagedAgents({
+  writeKey: process.env.RAINDROP_WRITE_KEY,
+  userId: "user_123",
+  properties: { feature: "world_builder" },
+});
+const client = raindrop.wrap(new OpenAI());
+
+try {
+  const events = await client.beta.agents.sessions.create({
+    agent: { model: "gpt-6-astra", instructions: "Help build a simulation World." },
+    environment: { type: "openai_hosted" },
+    input: "Describe the files needed for a simulation World.",
+    stream: true,
+  });
+  try {
+    for await (const event of events) {
+      if (event.type === "agent.session.turn.output_text.delta") process.stdout.write(event.delta);
+      if (event.type === "agent.session.idle") break;
+    }
+  } finally {
+    events.controller.abort();
+  }
+} finally {
+  await raindrop.shutdown();
+}
+```
+
+Use an OpenAI application key with the [Agents API permissions](https://developers.openai.com/api/docs/guides/agents-api/quickstart).
+No OpenTelemetry setup is required. Missing or blank Raindrop keys disable cloud
+shipping. Set `localWorkshopUrl: false` to disable local Workshop mirroring.
+
+## Capture
+
+- One partial event per turn, completed when the native turn reaches a terminal state.
+- Session model, user input, completed final answer, per-turn usage, and provider attribution.
+- A root turn span and child command, function, MCP, search, and subagent-control tool spans.
+- Session and turn IDs in properties. By default, the session ID is the conversation ID.
+- Original OpenAI results, events, request options, abort controls, and response helpers.
+
+The wrapper observes `sessions.create`, `sessions.retrieve`,
+`sessions.events.create`, `sessions.events.stream`, and `sessions.stream`.
+Use `raindrop.wrap(client, { userId, convoId, eventName, properties })` for context
+on sessions created or retrieved through that wrapper. Use a single wrapper for
+each native client. Retrieve an existing session before following its events to
+capture its model. Reading raw bodies with `asResponse()` bypasses capture.
+
+## Reconnecting runners and stored history
+
+For a runner that reconnects streams, use the public typed handler with an
+unwrapped native client. Keep one Raindrop client for the runner's lifetime:
+
+```ts
+raindrop.handler.onSession(session);
+raindrop.handler.onInput(session.id, userInput); // after successful submission
+// Recover missed item events before completing recovered turns.
+for await (const item of client.beta.agents.sessions.items.list(session.id, { order: "asc" })) {
+  raindrop.handler.onItem(session.id, item);
+}
+for await (const turn of client.beta.agents.sessions.turns.list(session.id, { order: "asc" })) {
+  raindrop.handler.onTurn(turn);
+}
+for await (const event of events) raindrop.handler.onEvent(event);
+await raindrop.flush();
+// After all streams/recovery work are stopped:
+raindrop.handler.forgetSession(session.id);
+await raindrop.shutdown();
+```
+
+Open the stream before recovery so it can buffer live updates. Recover stored
+items, then stored turns, before consuming buffered events.
+
+`onInputEvents(sessionId, events)` records accepted message/tool-result submissions.
+Repeated terminal turns and tool receipts are deduplicated within this client.
+Turn deduplication retains the latest 10,000 completed turns. Across process
+restarts, provide a stable `eventId: (turnId) => ...` and replay items before turns.
+No session or item listing is intercepted automatically.
+
+The wrapper closes unfinished captures in the iterator's `finally`, including
+early exit and transport failure. This marks capture interruption; it does not
+cancel the backend turn. Session model and context remain available for later
+streams; the previous input is cleared. Metadata retains the latest 10,000 idle
+sessions plus sessions with active turns. Call `forgetSession` when
+the session is no longer needed. Use the callback path when an unfinished turn
+must survive a reconnection.
+
+## Options and enrichment
+
+Options include `writeKey`, `endpoint`, `projectId`, `userId`, `convoId`,
+`eventName`, `properties`, `appGit`, `debug`, `localWorkshopUrl`,
+`maxTextFieldChars`, `eventId(turnId)`, and `redact(text)`.
+Text uses the shared core bounds. `redact` applies to captured prompts, answers,
+tool payloads, and errors. Caller-supplied properties/attachments are the caller's
+responsibility.
+
+`events.patch`, `events.finish`, `events.addAttachments`, `events.setProperties`,
+`users.identify`, and `signals.track` expose the shared core enrichment API.
+`flush()` ships current buffers; `shutdown()` also closes unfinished captures.
+
+## Limits
+
+The service does not expose individual inference requests. Captures represent
+turns, rather than each hidden model call. Usage comes only from `Turn.usage`;
+missing usage stays missing. Session-wide cumulative counters are never used as
+turn usage. Usage is best effort and later revisions after the first terminal
+receipt are not applied.
+
+Span timing reflects observed lifecycle events, including recovery; native turn
+timestamps are recorded as `openai.turn.*` attributes. Command duration is available
+in the native item. Image contents, reasoning text, intermediate commentary,
+agent-to-agent messages, and streaming text deltas are not automatically
+captured. Final text is read from completed final-answer items. Subagent turns
+are grouped by session and identified by subagent ID; no cross-turn parent
+hierarchy is inferred. Coordinator model identity is available from the session
+configuration. Subagent model and inherited coordinator input stay absent unless
+their own input is recorded.
+
+See [RELEASING.md](RELEASING.md) for first-publication and verification steps.
+See the [integration docs](https://docs.raindrop.ai/integrations/openai-managed-agents)
+for configuration details.

package/RELEASING.md

@@ -0,0 +1,41 @@
+# First publication
+
+The first release is bootstrapped locally as 0.0.1 using the reviewed integration
+branch. Its initial patch changeset is consumed before building, so source,
+bundled telemetry version, and registry version match.
+
+1. Confirm the integration PR's build, fault, and prod gates pass. OpenAI 7
+   requires Node 22+. The release and PR harness pins must match.
+2. Build the package, inspect `pnpm pack`, and publish the 0.0.1 tarball with an
+   authorized npm organization login. Do not publish development version 0.0.0.
+3. A package-specific trusted publisher requires the package to exist first
+   ([npm trust prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-trust/)).
+4. Configure the new package's npm trusted publisher for
+   `raindrop-ai/raindrop-js`, workflow `publish.yml`, using the organization’s
+   normal release settings. Do not change repository npm security settings.
+5. Confirm registry metadata, exports, and installation in a fresh Node 22
+   application. Run the example with an Agents-enabled application key.
+6. Update the companion Raindrop PR's worker dependency to 0.0.1 and regenerate
+   its pnpm lockfile from npm. Merge the Astra consumer after publication.
+
+## Subsequent releases
+
+Add a patch or minor changeset for package changes. After the integration PR is
+merged, merge the normal Changesets version PR. The existing `publish.yml`
+workflow detects the consumed changeset and version bump, runs its conformance
+gate, builds, and publishes through npm's GitHub Actions trusted publisher.
+The initial release is already registered, so merging it does not republish
+0.0.1. Do not merge the initial integration until its trusted publisher is set.
+
+## Conformance
+
+Driver: `conformance/openai-managed-agents-driver.mjs`.
+Run the pinned cross-SDK harness fault lane locally, and its prod lane with
+write/query credentials. The driver uses public session/turn callbacks and
+real Raindrop core shipping. It does not make an OpenAI model request.
+The native OpenAI HTTP/SSE path is covered separately by MSW integration tests.
+Live Astra inference and Query API readback remain distinct release checks.
+
+Use the repository's [conformance instructions](../../conformance/README.md).
+Known gaps have ticket-linked entries in
+`conformance/openai-managed-agents-failures.txt`. No workflow is bypassed.