@moldea.ai/adapter-openai-agents-sdk 3.0.0 → 3.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +10 -1
- package/docs/evidence-and-diagnostics.md +49 -0
- package/docs/index.md +29 -0
- package/docs/limitations.md +25 -0
- package/docs/verified-target.md +37 -0
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ The package implements the official `openai-agents-sdk` runtime adapter for `@mo
|
|
|
8
8
|
|
|
9
9
|
## Supported target
|
|
10
10
|
|
|
11
|
-
Version `3.0.
|
|
11
|
+
Version `3.0.1` supports:
|
|
12
12
|
|
|
13
13
|
- Repository Format version `1`
|
|
14
14
|
- `@moldea.ai/core ^4.0.0`
|
|
@@ -88,3 +88,12 @@ pnpm --filter @moldea.ai/adapter-openai-agents-sdk build
|
|
|
88
88
|
```
|
|
89
89
|
|
|
90
90
|
Unit and integration tests are colocated with their implementation modules. Adapter-specific conformance fixtures live under `/fixtures/adapter-openai-agents-sdk`.
|
|
91
|
+
|
|
92
|
+
## Documentation
|
|
93
|
+
|
|
94
|
+
These guides are included in the installed package. Open only the page relevant to your task.
|
|
95
|
+
|
|
96
|
+
- [Package overview](docs/index.md)
|
|
97
|
+
- [Verified target](docs/verified-target.md)
|
|
98
|
+
- [Evidence and diagnostics](docs/evidence-and-diagnostics.md)
|
|
99
|
+
- [Limitations](docs/limitations.md)
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Evidence and diagnostics
|
|
3
|
+
description: Emitted evidence, stable diagnostic contracts, ambiguity, and all-or-nothing Core integration.
|
|
4
|
+
order: 20
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Evidence and diagnostics
|
|
8
|
+
|
|
9
|
+
## Evidence
|
|
10
|
+
|
|
11
|
+
The verified target may emit `agent-definition`, `handoff-registration`, `instruction-loader`, `language`, `runtime-package`, `schema`, and `tool-registration` evidence. Records are grounded in existing logical source references and may identify the relevant agent, capability, target agent, configuration property, schema role, or routing-description source.
|
|
12
|
+
|
|
13
|
+
Agent-definition evidence uses the exact supported static Agent name only when it satisfies Core's non-empty, single-line, NUL-free, Unicode-scalar machine-string contract without surrounding Repository Format whitespace. Otherwise it uses the bound runtime-agent symbol. A target Agent name that cannot satisfy the same contract is omitted from handoff details.
|
|
14
|
+
|
|
15
|
+
Handoff evidence maps a target only when exactly one registered `moldea` agent has the detected runtime binding. It reports a runtime name only for a supported static, non-empty `toolNameOverride` representable as a Core machine string. The adapter does not invent a manifest handoff graph or SDK-generated default name.
|
|
16
|
+
|
|
17
|
+
Evidence contains no repository content, instructions, descriptions, credentials, API keys, tool arguments, provider payloads, or model responses. Missing local evidence is not itself a diagnostic.
|
|
18
|
+
|
|
19
|
+
## Diagnostic catalog
|
|
20
|
+
|
|
21
|
+
| Code | Meaning |
|
|
22
|
+
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
23
|
+
| `OPENAI_AGENTS_SDK_PACKAGE_MANIFEST_INVALID` | The owning manifest cannot establish valid dependency data. |
|
|
24
|
+
| `OPENAI_AGENTS_SDK_VERSION_UNSUPPORTED` | The observed SDK range is disjoint from the eligible versions. |
|
|
25
|
+
| `OPENAI_AGENTS_SDK_SOURCE_TEXT_INVALID` | Referenced source is not valid normalized text. |
|
|
26
|
+
| `OPENAI_AGENTS_SDK_SOURCE_SYNTAX_INVALID` | Referenced source contains invalid TypeScript syntax. |
|
|
27
|
+
| `OPENAI_AGENTS_SDK_RUNTIME_AGENT_SYMBOL_NOT_FOUND` | The bound runtime-agent symbol is absent. |
|
|
28
|
+
| `OPENAI_AGENTS_SDK_INSTRUCTION_LOADER_SYMBOL_NOT_FOUND` | The bound instruction-loader symbol is absent. |
|
|
29
|
+
| `OPENAI_AGENTS_SDK_AGENT_OUTPUT_SCHEMA_SYMBOL_NOT_FOUND` | The bound agent output-schema symbol is absent. |
|
|
30
|
+
| `OPENAI_AGENTS_SDK_TOOL_IMPLEMENTATION_SYMBOL_NOT_FOUND` | The bound tool-implementation symbol is absent. |
|
|
31
|
+
| `OPENAI_AGENTS_SDK_TOOL_REGISTRATION_SYMBOL_NOT_FOUND` | The bound tool-registration symbol is absent. |
|
|
32
|
+
| `OPENAI_AGENTS_SDK_TOOL_INPUT_SCHEMA_SYMBOL_NOT_FOUND` | The bound tool input-schema symbol is absent. |
|
|
33
|
+
| `OPENAI_AGENTS_SDK_TOOL_OUTPUT_SCHEMA_SYMBOL_NOT_FOUND` | The bound tool output-schema symbol is absent. |
|
|
34
|
+
| `OPENAI_AGENTS_SDK_INSTRUCTION_LOADER_NOT_WIRED` | Closed source proves that the declared loader is not used. |
|
|
35
|
+
| `OPENAI_AGENTS_SDK_AGENT_OUTPUT_SCHEMA_NOT_WIRED` | Closed source proves that the declared agent output schema is not used. |
|
|
36
|
+
| `OPENAI_AGENTS_SDK_TOOL_IMPLEMENTATION_NOT_WIRED` | Closed source proves that the declared tool implementation is not used. |
|
|
37
|
+
| `OPENAI_AGENTS_SDK_TOOL_REGISTRATION_NOT_WIRED` | Closed source proves that the declared function tool is not registered on the agent. |
|
|
38
|
+
| `OPENAI_AGENTS_SDK_TOOL_NAME_MISMATCH` | A static function-tool name contradicts the declared capability name. |
|
|
39
|
+
| `OPENAI_AGENTS_SDK_TOOL_INPUT_SCHEMA_NOT_WIRED` | Closed source proves that the declared tool input schema is not used. |
|
|
40
|
+
| `OPENAI_AGENTS_SDK_TOOL_OUTPUT_SCHEMA_NOT_WIRED` | Closed source proves that the declared tool output schema is not used. |
|
|
41
|
+
| `OPENAI_AGENTS_SDK_HANDOFF_TARGET_AMBIGUOUS` | A target runtime binding maps to multiple registered agents. |
|
|
42
|
+
| `OPENAI_AGENTS_SDK_HANDOFF_ROUTING_DESCRIPTION_MISSING` | A proved handoff registration has no effective canonical routing description. |
|
|
43
|
+
| `OPENAI_AGENTS_SDK_HANDOFF_ROUTING_DESCRIPTION_NOT_WIRED` | A proved handoff uses routing text that differs from its target's effective description. |
|
|
44
|
+
|
|
45
|
+
Diagnostics use Core's shared adapter shape, preserve logical source locations, and remain deterministically ordered. Dynamic or indirect patterns yield partial or no evidence rather than guessed failures. Core validates adapter output and applies all-or-nothing inspection semantics.
|
|
46
|
+
|
|
47
|
+
## Package detection
|
|
48
|
+
|
|
49
|
+
Detection stops at the nearest existing `package.json` owning each runtime-agent source. Supported dependency fields are considered collectively. A collectively disjoint range produces the unsupported-version diagnostic without package evidence; an ambiguous range remains evidence rather than being promoted to verified support. Invalid UTF-8 or NUL in the owning manifest produces only `OPENAI_AGENTS_SDK_PACKAGE_MANIFEST_INVALID`; source text failures remain source diagnostics.
|
package/docs/index.md
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: OpenAI Agents SDK runtime adapter
|
|
3
|
+
navigationTitle: Overview
|
|
4
|
+
description: Deterministic evidence and diagnostics for the verified OpenAI Agents SDK TypeScript target.
|
|
5
|
+
order: 0
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# OpenAI Agents SDK runtime adapter
|
|
9
|
+
|
|
10
|
+
`@moldea.ai/adapter-openai-agents-sdk` implements the official `openai-agents-sdk` runtime adapter for Core. It statically inspects explicitly bound TypeScript source through Core's source-neutral repository reader and produces deterministic evidence and diagnostics for one verified SDK target.
|
|
11
|
+
|
|
12
|
+
```typescript
|
|
13
|
+
import { openAiAgentsSdkAdapter } from '@moldea.ai/adapter-openai-agents-sdk';
|
|
14
|
+
import { createCore } from '@moldea.ai/core';
|
|
15
|
+
|
|
16
|
+
const core = createCore({ adapters: [openAiAgentsSdkAdapter] });
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The local CLI registers the adapter automatically. Applications composing Core directly register the immutable singleton explicitly.
|
|
20
|
+
|
|
21
|
+
## Current state
|
|
22
|
+
|
|
23
|
+
The package is available. Its current technical compatibility target covers TypeScript ESM using direct OpenAI Agents SDK agent, instruction, function-tool, schema, handoff, and routing-description patterns with npm `@openai/agents >=0.16.1`, Repository Format version `1`, and compatible Core `^4.0.0`.
|
|
24
|
+
|
|
25
|
+
The adapter never imports or calls the SDK, requires no API key, executes no repository code, and makes no network request. It proves supported static relationships in source; it does not verify credentials, provider behavior, runtime handoff decisions, model availability, prompts, tool execution, or schema semantics.
|
|
26
|
+
|
|
27
|
+
## Public surface
|
|
28
|
+
|
|
29
|
+
The package exports only `openAiAgentsSdkAdapter`. It has no default export, configuration factory, SDK facade, parser export, public diagnostic registry, or mutable runtime state. The generated [API reference](https://packages.moldea.ai/adapters/openai-agents-sdk/api/) derives that surface from the package export.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Boundaries and limitations
|
|
3
|
+
description: Unsupported SDK surfaces, source forms, dynamic behavior, and the adapter security boundary.
|
|
4
|
+
order: 30
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Boundaries and limitations
|
|
8
|
+
|
|
9
|
+
The current verified target does not claim support for:
|
|
10
|
+
|
|
11
|
+
- JavaScript, Python, CommonJS, or source outside the verified TypeScript ESM boundary
|
|
12
|
+
- `@openai/agents-core`, `@openai/agents-realtime`, sandbox agents, or subpath imports
|
|
13
|
+
- custom `Handoff` construction, dynamically assembled agent graphs, or manager-style agents as tools
|
|
14
|
+
- hosted, MCP-generated, namespaced, or tool-search tools
|
|
15
|
+
- arbitrary compiler resolution, `tsconfig` path aliases, directory indexes, package exports, or re-export graphs
|
|
16
|
+
- runtime-generated or transformed routing descriptions
|
|
17
|
+
- omitted function-tool names or names requiring SDK normalization
|
|
18
|
+
- schema-content validation
|
|
19
|
+
- handoff input schemas, callbacks, filters, enablement, runtime variables, guardrails, prompt templates, sessions, tracing, approvals, models, or provider behavior
|
|
20
|
+
|
|
21
|
+
Package detection uses nearest manifests, not lockfiles or installed `node_modules`. Static dependency ranges are observations; the adapter does not prove which package build executes at runtime.
|
|
22
|
+
|
|
23
|
+
Each invocation sees one declared agent, exact same-runtime binding resolution, and only the bounded operations Core supplies through `IRuntimeAdapterRepository`. It receives no complete agent collection, project body index, host path, OpenAI credential, environment variable, network client, or runtime process. It does not execute TypeScript, dynamically import source, load the inspected SDK, or follow source symlinks. These constraints preserve deterministic, source-grounded behavior while deliberately leaving dynamic runtime semantics unresolved.
|
|
24
|
+
|
|
25
|
+
The [Runtime Compatibility Matrix](https://packages.moldea.ai/compatibility/) remains authoritative. A focused specification or future design does not broaden this page until the canonical matrix and released implementation do.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Verified target
|
|
3
|
+
description: Exact source, package, agent, tool, schema, handoff, and routing-description support.
|
|
4
|
+
order: 10
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Verified target
|
|
8
|
+
|
|
9
|
+
The canonical Runtime Compatibility Matrix defines the technical target `typescript-agent-handoffs-0-16`.
|
|
10
|
+
|
|
11
|
+
## Supported boundary
|
|
12
|
+
|
|
13
|
+
- TypeScript ESM `.ts`, `.tsx`, and `.mts` files
|
|
14
|
+
- a nearest owning package manifest declaring npm `@openai/agents >=0.16.1`
|
|
15
|
+
- named value imports from the `@openai/agents` package root, including aliases
|
|
16
|
+
- a directly exported module-local `const` initialized through `new Agent({ ... })` or `Agent.create({ ... })`
|
|
17
|
+
- direct, awaited, referenced, or supported single-return-wrapper instruction-loader wiring
|
|
18
|
+
- direct agent output schemas through `outputType`
|
|
19
|
+
- directly exported function tools created through `tool({ ... })`
|
|
20
|
+
- direct tool implementations through `execute`, input schemas through `parameters`, and output schemas through `outputSchema`
|
|
21
|
+
- closed inline or immutable module-local arrays for agent tools and handoffs
|
|
22
|
+
- direct target-agent handoffs and closed `handoff(target, { ... })` registrations
|
|
23
|
+
- effective routing descriptions from a non-empty static `toolDescriptionOverride`, target `handoffDescription`, or the canonical agent-description fallback
|
|
24
|
+
|
|
25
|
+
Bindings must remain lexically visible at each matched use. Supported relative named imports resolve an exact TypeScript path, `.js` to `.ts` or `.tsx`, and `.mjs` to `.mts`. Re-exports, directory indexes, path aliases, CommonJS, and package-export resolution are outside the target.
|
|
26
|
+
|
|
27
|
+
## Relationship closure
|
|
28
|
+
|
|
29
|
+
Agent configurations, function tools, and configured handoffs are analyzed independently by relationship. Unrelated dynamic properties do not erase a proved relationship. A computed or duplicate relationship property, object spread, unsupported value, or relevant post-construction mutation leaves only the relationships it could obscure unresolved.
|
|
30
|
+
|
|
31
|
+
Negative wiring diagnostics require supported closed source to prove the declared relationship absent or contradictory. Dynamic and unsupported candidates remain unestablished rather than becoming definite failures.
|
|
32
|
+
|
|
33
|
+
## Static strings and routing
|
|
34
|
+
|
|
35
|
+
Agent names, tool names, `handoffDescription`, `toolNameOverride`, and `toolDescriptionOverride` support string literals, no-substitution templates, immutable module-local constants, and directly imported immutable string constants. Values are compiler-parsed and are not trimmed or normalized.
|
|
36
|
+
|
|
37
|
+
A non-empty static `toolDescriptionOverride` is authoritative for one configured registration. A static empty override falls back to target metadata. Without an authoritative override, the target's canonical handoff description is preferred and its canonical agent description is the fallback.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@moldea.ai/adapter-openai-agents-sdk",
|
|
3
|
-
"version": "3.0.
|
|
3
|
+
"version": "3.0.1",
|
|
4
4
|
"description": "Deterministic runtime evidence and diagnostics for direct OpenAI Agents SDK integrations.",
|
|
5
5
|
"homepage": "https://github.com/moldea-ai/packages/tree/main/projects/adapter-openai-agents-sdk#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -18,6 +18,7 @@
|
|
|
18
18
|
"files": [
|
|
19
19
|
"cover.png",
|
|
20
20
|
"dist",
|
|
21
|
+
"docs",
|
|
21
22
|
"LICENSE",
|
|
22
23
|
"README.md"
|
|
23
24
|
],
|