diff --git a/.github/workflows/rust-sdk.yml b/.github/workflows/rust-sdk.yml index 87c05b99..818dfe58 100644 --- a/.github/workflows/rust-sdk.yml +++ b/.github/workflows/rust-sdk.yml @@ -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: | diff --git a/docs/harness/guides/troubleshooting.md b/docs/harness/guides/troubleshooting.md index 5c84eaf4..abac1a99 100644 --- a/docs/harness/guides/troubleshooting.md +++ b/docs/harness/guides/troubleshooting.md @@ -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. diff --git a/harness/harness-sdk/src/cli.rs b/harness/harness-sdk/src/cli.rs index 7218b5ad..2a268aee 100644 --- a/harness/harness-sdk/src/cli.rs +++ b/harness/harness-sdk/src/cli.rs @@ -4,6 +4,13 @@ use anyhow::{ensure, Result}; use std::sync::Arc; struct Endpoint(Arc); impl openworker_runtime::protocol::Endpoint for Endpoint { + fn request_error(&self, error: &anyhow::Error) -> serde_json::Value { + error + .downcast_ref::() + .filter(|diagnostic| diagnostic.valid()) + .and_then(|diagnostic| serde_json::to_value(diagnostic).ok()) + .unwrap_or(serde_json::Value::Null) + } fn application_events(&self) -> Option> { Some(self.0.callbacks.events.subscribe()) } diff --git a/harness/harness-sdk/src/definition_error.rs b/harness/harness-sdk/src/definition_error.rs new file mode 100644 index 00000000..6ffccd8b --- /dev/null +++ b/harness/harness-sdk/src/definition_error.rs @@ -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, +} +impl AgentDefinitionConflict { + pub(crate) fn between(existing: &Agent, requested: &Agent) -> anyhow::Result> { + 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::>(); + 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()); + } +} diff --git a/harness/harness-sdk/src/host.rs b/harness/harness-sdk/src/host.rs index 8e402913..6b988dca 100644 --- a/harness/harness-sdk/src/host.rs +++ b/harness/harness-sdk/src/host.rs @@ -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)?; diff --git a/harness/harness-sdk/src/host_catalog.rs b/harness/harness-sdk/src/host_catalog.rs index 37cfc623..7da78f6e 100644 --- a/harness/harness-sdk/src/host_catalog.rs +++ b/harness/harness-sdk/src/host_catalog.rs @@ -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::(&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) -> Result> 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); } diff --git a/harness/harness-sdk/src/lib.rs b/harness/harness-sdk/src/lib.rs index 8be8f7bd..adf85065 100644 --- a/harness/harness-sdk/src/lib.rs +++ b/harness/harness-sdk/src/lib.rs @@ -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"), diff --git a/harness/harness-sdk/src/transport.rs b/harness/harness-sdk/src/transport.rs index 3287f34b..e429d8be 100644 --- a/harness/harness-sdk/src/transport.rs +++ b/harness/harness-sdk/src/transport.rs @@ -7,6 +7,9 @@ use tokio::{ }; fn provider_error(error: anyhow::Error) -> Error { + if let Some(diagnostic) = error.downcast_ref::() { + return Error::AgentDefinitionConflict(diagnostic.clone()); + } match error.downcast_ref::() { 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::( + v["error"]["agent_definition_conflict"].clone(), + ) + { + if diagnostic.valid() { + return Err(Error::AgentDefinitionConflict(diagnostic)); + } + } if let Ok(diagnostic) = serde_json::from_value::( v["error"]["provider_error"].clone(), diff --git a/harness/harness-sdk/tests/registration_errors.rs b/harness/harness-sdk/tests/registration_errors.rs new file mode 100644 index 00000000..490686f7 --- /dev/null +++ b/harness/harness-sdk/tests/registration_errors.rs @@ -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(); + } +} diff --git a/harness/runtime/src/protocol.rs b/harness/runtime/src/protocol.rs index dc5e12b9..20e67521 100644 --- a/harness/runtime/src/protocol.rs +++ b/harness/runtime/src/protocol.rs @@ -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> { 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::(),"provider_error":e.downcast_ref::().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::(),"provider_error":e.downcast_ref::().map(|e|e.diagnostic())}})} } } }, diff --git a/harness/typescript-sdk/src/transport.ts b/harness/typescript-sdk/src/transport.ts index ed53712e..db3f1ea8 100644 --- a/harness/typescript-sdk/src/transport.ts +++ b/harness/typescript-sdk/src/transport.ts @@ -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); diff --git a/harness/typescript-sdk/src/types.ts b/harness/typescript-sdk/src/types.ts index 6c43b4c2..8bd199dd 100644 --- a/harness/typescript-sdk/src/types.ts +++ b/harness/typescript-sdk/src/types.ts @@ -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; + 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; diff --git a/harness/typescript-sdk/test/dynamic-agents.test.mjs b/harness/typescript-sdk/test/dynamic-agents.test.mjs index c98465fa..858d222e 100644 --- a/harness/typescript-sdk/test/dynamic-agents.test.mjs +++ b/harness/typescript-sdk/test/dynamic-agents.test.mjs @@ -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(); diff --git a/harness/typescript-sdk/test/fake-host.mjs b/harness/typescript-sdk/test/fake-host.mjs index 0503dcca..7696cf1a 100755 --- a/harness/typescript-sdk/test/fake-host.mjs +++ b/harness/typescript-sdk/test/fake-host.mjs @@ -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({ diff --git a/harness/typescript-sdk/test/registration-errors.test.mjs b/harness/typescript-sdk/test/registration-errors.test.mjs new file mode 100644 index 00000000..6f087dc1 --- /dev/null +++ b/harness/typescript-sdk/test/registration-errors.test.mjs @@ -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(); } + } +}); diff --git a/harness/typescript-sdk/test/transport.test.mjs b/harness/typescript-sdk/test/transport.test.mjs index cd4eff26..fd2fccba 100644 --- a/harness/typescript-sdk/test/transport.test.mjs +++ b/harness/typescript-sdk/test/transport.test.mjs @@ -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}); +});