Merge pull request #889 from andrewyng/fix/sdk-release-qualification

Explain SDK agent registration conflicts
This commit is contained in:
Rohit Prasad
2026-11-13 14:14:22 -08:00
committed by GitHub
16 changed files with 257 additions and 23 deletions
+3 -3
View File
@@ -62,7 +62,7 @@ jobs:
timeout-minutes: 25
run: |
rustup show active-toolchain
cargo test --locked -p openworker-sdk --features test-support --lib --test desktop_api --test agent_team --test attachments -- --test-threads=1
cargo test --locked -p openworker-sdk --features test-support --lib --test registration_errors --test desktop_api --test agent_team --test attachments -- --test-threads=1
cargo test --locked -p openworker-runtime --lib direct::windows::tests -- --test-threads=1
cargo test --locked -p openworker-runtime --test windows --test connections --test model_endpoints --test direct_macos --test coding --test coding_extended --test assistant
cargo test --locked -p openworker-sdk --features test-support --test coding --test assistant -- --test-threads=1
@@ -82,7 +82,7 @@ jobs:
run: node --test --test-reporter=tap typescript-sdk/test/agent-team.test.mjs
- name: TypeScript callbacks, approvals and crash recovery
timeout-minutes: 5
run: node --test --test-reporter=tap typescript-sdk/test/desktop-api.test.mjs
run: node --test --test-reporter=tap typescript-sdk/test/desktop-api.test.mjs typescript-sdk/test/registration-errors.test.mjs
- name: TypeScript coding and assistant tools
timeout-minutes: 5
run: node --test --test-reporter=tap typescript-sdk/test/coding.test.mjs typescript-sdk/test/assistant.test.mjs
@@ -231,7 +231,7 @@ jobs:
npm --prefix typescript-sdk run test:integration
npm --prefix typescript-sdk run test:dynamic-agents
node --test --test-concurrency=2 --test-reporter=tap typescript-sdk/test/chat-usage.test.mjs typescript-sdk/test/openrouter-streaming.test.mjs typescript-sdk/test/anthropic-caching.test.mjs typescript-sdk/test/gemini-compat.test.mjs typescript-sdk/test/session-options.test.mjs typescript-sdk/test/application-guidance.test.mjs typescript-sdk/test/stream-events.test.mjs typescript-sdk/test/attachments.test.mjs
node --test --test-reporter=tap typescript-sdk/test/desktop-api.test.mjs typescript-sdk/test/agent-team.test.mjs typescript-sdk/test/standalone-subagents.test.mjs
node --test --test-reporter=tap typescript-sdk/test/desktop-api.test.mjs typescript-sdk/test/registration-errors.test.mjs typescript-sdk/test/agent-team.test.mjs typescript-sdk/test/standalone-subagents.test.mjs
node --test --test-reporter=tap typescript-sdk/test/coding.test.mjs typescript-sdk/test/assistant.test.mjs
- name: Starter and partner packaging
run: |
+6 -3
View File
@@ -19,9 +19,12 @@ provider tokens, prompts, file contents and private state directories.
## Agent registration is rejected
A generic “Harness rejected the request” can mean that the agent name already
belongs to a different immutable definition. Check changes to instructions,
tools and approval mode. Re-register the identical definition, or use a new name
A changed immutable definition returns `AgentDefinitionConflict` in Rust.
TypeScript retains error code `Remote` and exposes
`context.reason: "agent_definition_conflict"`, `context.agentId` and
`context.conflictingFields`. The diagnostic contains field names such as
`instructions`, `tools` or `approvals`, never their values. Older hosts may still
return the generic “Harness rejected the request” message. Re-register the identical definition, or use a new name
for the new definition; a new session alone does not change it. Keep existing
state for old sessions. Do not log prompts or credentials to diagnose the conflict.
+7
View File
@@ -4,6 +4,13 @@ use anyhow::{ensure, Result};
use std::sync::Arc;
struct Endpoint(Arc<Host>);
impl openworker_runtime::protocol::Endpoint for Endpoint {
fn request_error(&self, error: &anyhow::Error) -> serde_json::Value {
error
.downcast_ref::<crate::AgentDefinitionConflict>()
.filter(|diagnostic| diagnostic.valid())
.and_then(|diagnostic| serde_json::to_value(diagnostic).ok())
.unwrap_or(serde_json::Value::Null)
}
fn application_events(&self) -> Option<tokio::sync::broadcast::Receiver<serde_json::Value>> {
Some(self.0.callbacks.events.subscribe())
}
@@ -0,0 +1,96 @@
//! Safe registration diagnostics contain identities and field names, never values.
use crate::agents::Agent;
use serde::{Deserialize, Serialize};
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AgentDefinitionConflict {
pub agent_id: String,
pub conflicting_fields: Vec<String>,
}
impl AgentDefinitionConflict {
pub(crate) fn between(existing: &Agent, requested: &Agent) -> anyhow::Result<Option<Self>> {
let old = serde_json::to_value(existing)?;
let new = serde_json::to_value(requested)?;
let fields = FIELDS
.iter()
.filter(|field| old[**field] != new[**field])
.map(|field| (*field).to_owned())
.collect::<Vec<_>>();
Ok((!fields.is_empty()).then(|| Self {
agent_id: requested.id.clone(),
conflicting_fields: fields,
}))
}
pub(crate) fn valid(&self) -> bool {
!self.agent_id.is_empty()
&& self.agent_id.len() <= 64
&& self
.agent_id
.bytes()
.all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
&& !self.conflicting_fields.is_empty()
&& self.conflicting_fields.len() <= FIELDS.len()
&& self
.conflicting_fields
.iter()
.all(|f| FIELDS.contains(&f.as_str()))
}
}
const FIELDS: &[&str] = &[
"name",
"description",
"instructions",
"limits",
"builtin_tools",
"tools",
"model",
"provider",
"fallback_model",
"planning",
"memory",
"memory_scope",
"scheduling",
"approvals",
"auto_skip_questions",
"auto_approver_context",
"compaction",
"subagents",
"standalone_subagents",
"servers",
"tool_policy",
"runtime_policy",
];
impl std::fmt::Display for AgentDefinitionConflict {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
f,
"Agent '{}' already has a different definition ({}); use a new agent name",
self.agent_id,
self.conflicting_fields.join(", ")
)
}
}
impl std::error::Error for AgentDefinitionConflict {}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn reports_field_names_without_definition_values() {
let first = Agent::new("guide").instructions("SECRET_ORIGINAL");
assert!(AgentDefinitionConflict::between(&first, &first)
.unwrap()
.is_none());
let error =
AgentDefinitionConflict::between(&first, &first.clone().instructions("SECRET_NEW"))
.unwrap()
.unwrap();
assert!(error.valid());
assert_eq!(error.conflicting_fields, ["instructions"]);
assert!(!format!("{error:?} {error}").contains("SECRET"));
let mut malformed = error;
malformed.conflicting_fields = vec!["SECRET_VALUE".into()];
assert!(!malformed.valid());
}
}
+3 -4
View File
@@ -632,10 +632,9 @@ impl Host {
{
let registry = self.registry.read().unwrap();
if let Some(existing) = registry.definitions.get(&agent.id) {
ensure!(
serde_json::to_value(existing)? == serde_json::to_value(&agent)?,
"Agent identity already has a different definition; use a new name"
);
if let Some(conflict) = crate::AgentDefinitionConflict::between(existing, &agent)? {
return Err(conflict.into());
}
// Also persist a definition originally supplied in HostConfig when
// the application explicitly registers it through this API.
self.catalog.insert(&agent)?;
+7 -9
View File
@@ -115,10 +115,10 @@ impl Catalog {
)
.optional()?;
if let Some(previous) = previous {
ensure!(
previous == encoded,
"Agent identity already has a different definition"
);
let existing = serde_json::from_str::<Agent>(&previous)?;
if let Some(conflict) = crate::AgentDefinitionConflict::between(&existing, agent)? {
return Err(conflict.into());
}
} else {
tx.execute(
"INSERT INTO agents(id,definition) VALUES(?1,?2)",
@@ -134,11 +134,9 @@ pub(super) fn merge(startup: &[Agent], saved: Vec<Agent>) -> Result<Vec<Agent>>
let mut result = startup.to_vec();
for agent in saved {
if let Some(existing) = result.iter().find(|a| a.id == agent.id) {
ensure!(
serde_json::to_value(existing)? == serde_json::to_value(&agent)?,
"Startup agent conflicts with persisted registration: {}",
agent.id
);
if let Some(conflict) = crate::AgentDefinitionConflict::between(existing, &agent)? {
return Err(conflict.into());
}
} else {
result.push(agent);
}
+4
View File
@@ -17,7 +17,9 @@ mod desktop;
mod mcp;
pub use agents::Approvals;
pub use mcp::McpServer;
mod definition_error;
mod driver;
pub use definition_error::AgentDefinitionConflict;
pub mod host;
mod providers;
pub use agents::{
@@ -93,6 +95,7 @@ pub enum Error {
InvalidInput(String),
Remote(String),
Provider(openworker_runtime::provider::Diagnostic),
AgentDefinitionConflict(AgentDefinitionConflict),
Setup(String),
Unavailable,
/// May have committed or started. Reconcile durable IDs; do not blindly retry.
@@ -104,6 +107,7 @@ impl std::fmt::Display for Error {
match self {
Self::InvalidInput(s) | Self::Remote(s) | Self::Setup(s) => f.write_str(s),
Self::Provider(diagnostic) => std::fmt::Display::fmt(diagnostic, f),
Self::AgentDefinitionConflict(diagnostic) => std::fmt::Display::fmt(diagnostic, f),
Self::Unavailable => f.write_str("Harness unavailable or recovering; request not sent"),
Self::OutcomeUnknown => f.write_str("Harness response lost; execution outcome unknown. Reconcile saved session before retrying."),
Self::Closed => f.write_str("Harness client closed"),
+12
View File
@@ -7,6 +7,9 @@ use tokio::{
};
fn provider_error(error: anyhow::Error) -> Error {
if let Some(diagnostic) = error.downcast_ref::<crate::AgentDefinitionConflict>() {
return Error::AgentDefinitionConflict(diagnostic.clone());
}
match error.downcast_ref::<openworker_runtime::provider::Error>() {
Some(error) => Error::Provider(error.diagnostic()),
None => Error::Remote(error.to_string()),
@@ -387,6 +390,15 @@ impl Backend {
return Err(Error::OutcomeUnknown);
}
if let Some(message) = v["error"]["message"].as_str() {
if let Ok(diagnostic) =
serde_json::from_value::<crate::AgentDefinitionConflict>(
v["error"]["agent_definition_conflict"].clone(),
)
{
if diagnostic.valid() {
return Err(Error::AgentDefinitionConflict(diagnostic));
}
}
if let Ok(diagnostic) =
serde_json::from_value::<openworker_runtime::provider::Diagnostic>(
v["error"]["provider_error"].clone(),
@@ -0,0 +1,46 @@
//! Real embedded host/catalog, no model requests or tool execution.
use openworker_sdk::{Agent, Approvals, Error, Harness, Sandbox};
fn guide() -> Agent {
Agent::new("guide-v1")
.instructions("PRIVATE_ORIGINAL_PROMPT")
.tools([] as [&str; 0])
.planning(false)
.memory(false)
.scheduling(false)
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn definition_conflicts_survive_catalog_restart_without_exposing_values() {
let root = tempfile::tempdir().unwrap();
for pass in 0..2 {
let h = Harness::builder()
.state_dir(root.path().canonicalize().unwrap())
.executable(std::path::PathBuf::from(env!(
"CARGO_BIN_EXE_openworker-harness"
)))
.sandbox(Sandbox::Off)
.start()
.await
.unwrap();
h.create_agent(guide()).await.unwrap();
h.create_agent(guide()).await.unwrap();
let error = h
.create_agent(
guide()
.instructions("PRIVATE_NEW_PROMPT")
.approvals(Approvals::Never),
)
.await
.err()
.expect("immutable definition must reject changes");
let Error::AgentDefinitionConflict(diagnostic) = &error else {
panic!("Expected structured conflict on pass {pass}, got {error:?}");
};
assert_eq!(diagnostic.agent_id, "guide-v1");
assert_eq!(diagnostic.conflicting_fields, ["instructions", "approvals"]);
assert!(!format!("{error:?} {error}").contains("PRIVATE_"));
h.create_agent(guide()).await.unwrap();
h.shutdown().await.unwrap();
}
}
+5 -1
View File
@@ -4,6 +4,10 @@ use serde_json::{json, Value};
use std::{collections::HashSet, sync::Arc};
pub trait Endpoint: Send + Sync {
/// Explicitly allowlisted structured diagnostics; never arbitrary error context.
fn request_error(&self, _error: &anyhow::Error) -> Value {
Value::Null
}
fn application_events(&self) -> Option<tokio::sync::broadcast::Receiver<Value>> {
None
}
@@ -132,7 +136,7 @@ pub async fn serve_endpoint(rt: impl Endpoint + 'static) -> Result<()> {
if method=="session/attach"{subscribed.insert(p["session_id"].as_str().unwrap().to_owned());}
Ok::<_,anyhow::Error>(result)
}.await;
match result{Ok(result)=>json!({"jsonrpc":"2.0","id":id,"result":result}),Err(e)=>json!({"jsonrpc":"2.0","id":id,"error":{"code":-32000,"message":e.to_string(),"attachment_inspection_unsupported":e.is::<crate::attachments::InspectionUnsupported>(),"provider_error":e.downcast_ref::<crate::provider::Error>().map(|e|e.diagnostic())}})}
match result{Ok(result)=>json!({"jsonrpc":"2.0","id":id,"result":result}),Err(e)=>json!({"jsonrpc":"2.0","id":id,"error":{"code":-32000,"message":e.to_string(),"agent_definition_conflict":rt.request_error(&e),"attachment_inspection_unsupported":e.is::<crate::attachments::InspectionUnsupported>(),"provider_error":e.downcast_ref::<crate::provider::Error>().map(|e|e.diagnostic())}})}
}
}
},
+7 -2
View File
@@ -11,6 +11,7 @@ import {
ResolvedHarnessOptions,
record,
providerDiagnostic,
agentDefinitionConflict,
type ConnectionState,
} from "./types.js";
@@ -328,11 +329,15 @@ export class Transport {
? frame.error.provider_error
: undefined,
);
const conflict = agentDefinitionConflict(
typeof frame.error === "object" && "agent_definition_conflict" in frame.error
? frame.error.agent_definition_conflict : undefined,
);
p.reject(
new HarnessError(
"Remote",
typeof frame.error === "object" && "attachment_inspection_unsupported" in frame.error && frame.error.attachment_inspection_unsupported === true ? "Binary attachments cannot be inspected by configured text-only input guardrails" : diagnostic ? `Provider ${diagnostic.category}${diagnostic.httpStatus ? ` (HTTP ${diagnostic.httpStatus})` : ""}` : "Harness rejected the request; inspect its configuration or durable session state",
diagnostic ? { providerError: diagnostic } : undefined,
conflict ? `Agent '${conflict.agentId}' already has a different definition (${conflict.conflictingFields.join(", ")}); use a new agent name` : typeof frame.error === "object" && "attachment_inspection_unsupported" in frame.error && frame.error.attachment_inspection_unsupported === true ? "Binary attachments cannot be inspected by configured text-only input guardrails" : diagnostic ? `Provider ${diagnostic.category}${diagnostic.httpStatus ? ` (HTTP ${diagnostic.httpStatus})` : ""}` : "Harness rejected the request; inspect its configuration or durable session state",
conflict ?? (diagnostic ? { providerError: diagnostic } : undefined),
),
);
} else p.resolve(frame.result);
+12
View File
@@ -403,6 +403,9 @@ export class HarnessError extends Error {
submissionId?: string;
requestId?: string;
providerError?: ProviderDiagnostic;
reason?: "agent_definition_conflict";
agentId?: string;
conflictingFields?: string[];
},
) {
super(message);
@@ -410,6 +413,15 @@ export class HarnessError extends Error {
}
}
/** Accept only identity/field metadata, never arbitrary remote error messages or values. */
export function agentDefinitionConflict(value: unknown): {reason: "agent_definition_conflict"; agentId: string; conflictingFields: string[]} | undefined {
if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
const v = value as Record<string, unknown>;
const fields = ["name","description","instructions","limits","builtin_tools","tools","model","provider","fallback_model","planning","memory","memory_scope","scheduling","approvals","auto_skip_questions","auto_approver_context","compaction","subagents","standalone_subagents","servers","tool_policy","runtime_policy"];
if (typeof v.agent_id !== "string" || !/^[a-zA-Z0-9_-]{1,64}$/.test(v.agent_id) || !Array.isArray(v.conflicting_fields) || v.conflicting_fields.length === 0 || v.conflicting_fields.length > fields.length || v.conflicting_fields.some(f => typeof f !== "string" || !fields.includes(f))) return undefined;
return {reason: "agent_definition_conflict", agentId: v.agent_id, conflictingFields: [...v.conflicting_fields] as string[]};
}
export type ProviderFailure = "rate_limit" | "transient" | "transport" | "incomplete_stream" | "invalid_response" | "context_overflow" | "truncated" | "authentication" | "configuration" | "safety_blocked";
export interface ProviderDiagnostic {
category: ProviderFailure;
@@ -78,7 +78,7 @@ for (const database of ["sqlite", "postgres"]) {
await harness.createAgent(definition).ready();
await assert.rejects(
harness.createAgent({ ...definition, instructions: "Changed" }).ready(),
{ code: "Remote" },
e => e.code === "Remote" && e.context?.reason === "agent_definition_conflict" && e.context.agentId === "builder" && e.context.conflictingFields.includes("instructions"),
);
const session = await builder.newSession({ workspace });
const ref = session.reference();
@@ -50,6 +50,8 @@ for await (const line of lines) {
} else if (method === "malformed") process.stdout.write("invalid\n");
else if (method === "huge") process.stdout.write("x".repeat(1024 * 1024 + 1));
else if (method === "hang") await new Promise(() => {});
else if (method === "diagnostic_error")
process.stdout.write(JSON.stringify({jsonrpc:"2.0",id,error:{code:-1,message:"sk-do-not-leak-this-value",agent_definition_conflict:params.diagnostic}})+"\n");
else if (method === "error")
process.stdout.write(
JSON.stringify({
@@ -0,0 +1,30 @@
// Real managed host/catalog; no provider credentials or model calls.
import test from 'node:test';
import assert from 'node:assert/strict';
import {mkdtemp, rm} from 'node:fs/promises';
import {tmpdir} from 'node:os';
import {join} from 'node:path';
import {Harness} from '../dist/index.js';
test('registration conflict diagnostics survive managed-host restart', {
skip: !process.env.OW_TS_TEST_HOST, timeout: 90000,
}, async t => {
const stateDir = await mkdtemp(join(tmpdir(), 'ow-definition-conflict-'));
t.after(() => rm(stateDir, {recursive:true, force:true}));
const definition = {name:'guide-v1', instructions:'PRIVATE_ORIGINAL_PROMPT',tools:[],planning:false,memory:false,scheduling:false};
for (let pass = 0; pass < 2; pass++) {
const h = await Harness.start({stateDir,executable:process.env.OW_TS_TEST_HOST,sandbox:'off'});
try {
await h.createAgent(definition).ready();
await h.createAgent(definition).ready();
await assert.rejects(h.createAgent({...definition,instructions:'PRIVATE_NEW_PROMPT',approvals:{mode:'never'}}).ready(), e => {
assert.equal(e.code,'Remote');
assert.deepEqual(e.context,{reason:'agent_definition_conflict',agentId:'guide-v1',conflictingFields:['instructions','approvals']});
assert.match(e.message,/use a new agent name/);
assert.ok(!JSON.stringify(e).includes('PRIVATE_'));
return true;
});
await h.createAgent(definition).ready();
} finally { await h.shutdown(); }
}
});
@@ -231,3 +231,19 @@ test("read recovery cannot be used for mutations; a full queue never busy-spins"
await Promise.all(queued);
assert.equal(h.state, "ready");
});
test("agent conflict errors expose only bounded structured identity and field names", async t => {
const {h}=await setup(t);
const diagnostic={agent_id:"builder-v1",conflicting_fields:["instructions","approvals"],secret:"sk-never-reflect"};
await assert.rejects(h.request("diagnostic_error",{diagnostic}),e=>{
assert.equal(e.code,"Remote");
assert.deepEqual(e.context,{reason:"agent_definition_conflict",agentId:"builder-v1",conflictingFields:["instructions","approvals"]});
assert.match(e.message,/use a new agent name/);
assert.ok(!JSON.stringify(e).includes("sk-"));
return true;
});
for(const bad of [null,{}, {...diagnostic,agent_id:"../outside"},{...diagnostic,conflicting_fields:["sk-secret"]},{...diagnostic,conflicting_fields:[]},{...diagnostic,conflicting_fields:Array(100).fill("instructions")}]) {
await assert.rejects(h.request("diagnostic_error",{diagnostic:bad}),e=>e.code==="Remote"&&e.context===undefined&&!e.message.includes("sk-"));
}
assert.deepEqual(await h.request("echo",{alive:true}),{alive:true});
});