@neurarelay/openai-agents

Alpha release candidate for governing OpenAI Agents SDK function tools with the frozen Neura P1A contract. The source is publication-prepared but remains unpublished until an exact release approval is granted.

The adapter wraps an existing FunctionTool. It derives a refs-only exact-call request, asks one explicitly configured Local, Relay, or custom authority provider for a Decision Receipt, maps escalate to the SDK approval interruption, requires a fresh proceed receipt after resume, revalidates immediately before execution, consumes the receipt once, invokes the application-owned tool, and records terminal evidence.

Only function tools are supported. Hosted tools, hosted MCP tools, computer, shell, apply-patch, handoffs, and agent-as-tool paths are not governed by this alpha. There is no silent Local-to-Relay fallback.

import { tool } from "@openai/agents";
import { z } from "zod";
import { governNeuraFunctionTool } from "@neurarelay/openai-agents";

const updateRecordParameters = z.object({
  recordRef: z.string(),
  status: z.string(),
});

const updateRecord = tool({
  name: "update_record",
  description: "Update one application-owned record.",
  parameters: updateRecordParameters,
  execute: async ({ recordRef, status }) => ({ recordRef, status }),
});

const governedUpdateRecord = governNeuraFunctionTool(updateRecord, {
  provider,
  actionContext: async (input) => {
    const { recordRef } = updateRecordParameters.parse(input);
    return {
      actor_ref: "actor_ref:application_agent",
      runtime_ref: "runtime_ref:openai_agents_sdk",
      session_ref: "session_ref:current_run",
      workspace_ref: "workspace_ref:application_workspace",
      action_family: "external_mutation",
      target_ref: recordRef,
      target_refs: [recordRef],
      affected_subject_refs: ["subject_ref:record_owner"],
      policy_context_ref: "policy_context_ref:record_update",
      evidence_refs: ["evidence_ref:validated_record_scope"],
      profile_ref: "profile_ref:record_update_v1",
      profile_version: "record-update-v1",
      policy_source_ref: "policy_source_ref:record_update_policy",
      policy_digest: "sha256:policy:replace_with_real_digest",
      authority_principal_ref: "principal_ref:record_owner",
      discovery_receipt_ref: null,
      terminal_outcome_requirement: "typed_reconciliation" as const,
    };
  },
});

The authority provider owns risk resolution, receipt issuance, approval resumption, revocation/currentness checks, and terminal-record persistence. The adapter never calls OpenAI or a downstream system on Neura's behalf.

Local and Relay HTTP providers

The package includes two explicit HTTP provider constructors. They share one refs-only transport envelope but never fall back between sources:

import {
  createLocalNeuraAuthorityProvider,
  createRelayNeuraAuthorityProvider,
} from "@neurarelay/openai-agents";

const localProvider = createLocalNeuraAuthorityProvider({
  endpoint: "http://127.0.0.1:4317/v1/openai-agents/authority",
  authorization: async () => `Bearer ${await readScopedLocalToken()}`,
});

const relayProvider = createRelayNeuraAuthorityProvider({
  endpoint: "https://relay.example.com/v1/openai-agents/authority",
  authorization: async () => `Bearer ${await readScopedRelayToken()}`,
});

Local endpoints are restricted to HTTP(S) loopback. Relay endpoints require HTTPS. Both use POST, disable redirects and browser credentials, require caller-supplied bearer authorization, and exchange only the exact evaluate, revalidate, resume_after_approval, and record_terminal_outcome operations. Responses must bind the requested operation and authority source and preserve the refs-only, no-private-payload, no-Neura-execution boundary.

This alpha does not ship or activate an authority server endpoint, token reader, silent Local-to-Relay fallback, or live provider connection. Applications and deployments must supply an endpoint implementing the exported transport envelope. The deterministic package verifier injects a no-effect Fetch implementation and performs no live Local, Relay, Registry, OpenAI, or downstream request.

Examples and run ownership

The package ships two TypeScript examples:

• examples/governed-function-tool.ts wraps one application-owned function tool and selects Relay explicitly;
• examples/human-approval-resume.ts shows the SDK interruption and resume boundary with pre-approval input guardrails enabled.

The application still owns the OpenAI run loop, the human approval decision, token retrieval, and downstream function. OpenAI approval alone never becomes Neura authority: an escalated call must receive a fresh exact proceed receipt from the configured provider after resume.