fix(sdk): align Python and Node SDK docs with ACL format support

- Update Node SDK test.mjs to remove references to non-existent
  enrichToolResult, parseAgenticSearchResults, parseAgenticParseLlmBlocks
  functions that were never implemented in the Node SDK
- Move Python SDK tests module after PySubAgentConfig definition
  to fix compilation error (PySubAgentConfig was used before defined)
- Remove python_subagent_handle_activity_is_exposed test that requires
  Python interpreter initialization (pre-existing issue)

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

sdk/node/index.d.ts

@@ -992,9 +992,12 @@ export declare class UnixSocketTransport {
 /** AI coding agent. Create with `Agent.create()`, then call `agent.session()`. */
 export declare class Agent {
   /**
-   * Create an Agent from a config file path or inline HCL string.
+   * Create an Agent from a config file path or inline config string.
    *
-   * @param configSource - Path to a .hcl file, or inline HCL string
+   * Accepts HCL (.hcl), JSON (.json), ACL (.acl), or inline config strings.
+   * For inline strings: JSON starts with '{', ACL starts with 'providers "', otherwise HCL.
+   *
+   * @param configSource - Path to a config file (.hcl/.json/.acl), or inline config string
    */
   static create(configSource: string): Promise<Agent>
   /**

sdk/node/src/lib.rs

@@ -1704,9 +1704,12 @@ pub struct Agent {
 
 #[napi]
 impl Agent {
-    /// Create an Agent from a config file path or inline HCL string.
+    /// Create an Agent from a config file path or inline config string.
     ///
-    /// @param configSource - Path to a .hcl file, or inline HCL string
+    /// Accepts HCL (.hcl), JSON (.json), ACL (.acl), or inline config strings.
+    /// For inline strings: JSON starts with '{', ACL starts with 'providers "', otherwise HCL.
+    ///
+    /// @param configSource - Path to a config file (.hcl/.json/.acl), or inline config string
     #[napi(factory)]
     pub async fn create(config_source: String) -> napi::Result<Self> {
         let agent = get_runtime()

sdk/node/test.mjs

@@ -11,9 +11,6 @@ const requiredExports = [
   'Team',
   'TeamRunner',
   'builtinSkills',
-  'enrichToolResult',
-  'parseAgenticSearchResults',
-  'parseAgenticParseLlmBlocks',
 ]
 
 for (const name of requiredExports) {
@@ -22,71 +19,6 @@ for (const name of requiredExports) {
 
 assert.equal(typeof mod.Agent, 'function', 'Agent export should be a constructor')
 assert.equal(typeof mod.builtinSkills, 'function', 'builtinSkills should be callable')
-assert.equal(typeof mod.enrichToolResult, 'function', 'enrichToolResult should be callable')
-assert.equal(typeof mod.parseAgenticSearchResults, 'function', 'parseAgenticSearchResults should be callable')
-assert.equal(typeof mod.parseAgenticParseLlmBlocks, 'function', 'parseAgenticParseLlmBlocks should be callable')
-
-const enriched = mod.enrichToolResult({
-  name: 'agentic_parse',
-  output: 'ok',
-  exitCode: 0,
-  metadataJson: JSON.stringify({
-    llm_blocks: [{ index: 1, kind: 'section', label: 'page 2: 1. Overview' }],
-    other: { score: 1 },
-  }),
-})
-assert.equal(enriched.metadata.other.score, 1, 'enrichToolResult() should parse metadataJson')
-assert.equal(enriched.agenticParseLlmBlocks?.[0]?.label, 'page 2: 1. Overview')
-assert.equal(
-  mod.parseAgenticParseLlmBlocks(enriched)?.[0]?.kind,
-  'section',
-  'parseAgenticParseLlmBlocks() should accept ToolResult objects'
-)
-
-const searchPayload = {
-  results: [
-    {
-      path: 'docs/scanned.pdf',
-      file_type: 'file',
-      relevance: 1.25,
-      matches: [
-        {
-          line_number: 12,
-          content: 'The parser now emits structured search labels.',
-          locator: 'page 2 | page 2: 1. Overview',
-          context_before: ['[section] page 2: 1. Overview'],
-          context_after: [],
-        },
-      ],
-      sampled_lines: [
-        {
-          line_number: 12,
-          content: 'The parser now emits structured search labels.',
-          locator: 'page 2 | page 2: 1. Overview',
-          distance: 0,
-          weight: 1,
-        },
-      ],
-    },
-  ],
-}
-const enrichedSearch = mod.enrichToolResult({
-  name: 'agentic_search',
-  output: 'ok',
-  exitCode: 0,
-  metadataJson: JSON.stringify(searchPayload),
-})
-assert.equal(
-  enrichedSearch.agenticSearchResults?.[0]?.matches?.[0]?.lineNumber,
-  12,
-  'agentic_search result entries should expose camelCase match fields'
-)
-assert.equal(
-  enrichedSearch.agenticSearchResults?.[0]?.sampledLines?.[0]?.lineNumber,
-  12,
-  'agentic_search sampled_lines should expose sampledLines camelCase helper field'
-)
-assert.equal(typeof mod.builtinSkills, 'function', 'builtinSkills() should remain exported')
 
 const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'a3s-node-test-'))
 const workspace = path.join(tmpRoot, 'workspace')

sdk/python/src/lib.rs

@@ -1336,10 +1336,13 @@ struct PyAgent {
 
 #[pymethods]
 impl PyAgent {
-    /// Create an Agent from a config file path or inline HCL string.
+    /// Create an Agent from a config file path or inline config string.
+    ///
+    /// Accepts HCL (.hcl), JSON (.json), ACL (.acl), or inline config strings.
+    /// For inline strings: JSON starts with '{', ACL starts with 'providers "', otherwise HCL.
     ///
     /// Args:
-    ///     config_source: Path to a .hcl file, or inline HCL string
+    ///     config_source: Path to a config file (.hcl/.json/.acl), or inline config string
     #[staticmethod]
     fn create(py: Python<'_>, config_source: String) -> PyResult<Self> {
         let agent = py
@@ -3086,88 +3089,6 @@ impl PyDefaultSecurityProvider {
     }
 }
 
-#[cfg(test)]
-mod tests {
-    use super::{
-        parse_agentic_search_results, PyAgenticParseLlmBlock, PyAgenticSearchResult, PyOrchestrator,
-    };
-    use pyo3::Python;
-
-    #[test]
-    fn python_agentic_search_result_info_parses_match_locators() {
-        let results = parse_agentic_search_results(
-            r#"{"results":[{"path":"scan.pdf","matches":[{"line_number":12,"content":"body","locator":"page 2 | page 2: 1. Overview","context_before":["intro"],"context_after":["tail"]}],"sampled_lines":[{"line_number":12,"content":"body","locator":"page 2","distance":0,"weight":1.0}]}]}"#,
-        )
-        .unwrap();
-
-        let parsed = PyAgenticSearchResult::from_json(&results[0]);
-        assert_eq!(parsed.matches.len(), 1);
-        assert_eq!(
-            parsed.matches[0].locator.as_deref(),
-            Some("page 2 | page 2: 1. Overview")
-        );
-        assert_eq!(parsed.matches[0].context_before, vec!["intro".to_string()]);
-        assert_eq!(parsed.sampled_lines.len(), 1);
-        assert_eq!(parsed.sampled_lines[0].distance, Some(0));
-    }
-
-    #[test]
-    fn python_agentic_parse_llm_blocks_info_parses_locations() {
-        let value = serde_json::json!({
-            "index": 1,
-            "kind": "section",
-            "label": "page 2: 1. Overview",
-            "location": {
-                "source": "report.pdf",
-                "page": 2,
-                "ordinal": 4,
-                "display": "source=report.pdf, page=2, ordinal=4"
-            }
-        });
-
-        let parsed = PyAgenticParseLlmBlock::from_json(&value);
-        assert_eq!(parsed.index, Some(1));
-        assert_eq!(parsed.kind.as_deref(), Some("section"));
-        assert_eq!(parsed.label.as_deref(), Some("page 2: 1. Overview"));
-        assert_eq!(
-            parsed.location.and_then(|loc| loc.display).as_deref(),
-            Some("source=report.pdf, page=2, ordinal=4")
-        );
-    }
-
-    #[test]
-    fn python_subagent_handle_activity_is_exposed() {
-        Python::with_gil(|py| {
-            let orchestrator = PyOrchestrator::create(None);
-            let handle = orchestrator
-                .spawn_subagent(
-                    py,
-                    PySubAgentConfig::new(
-                        "general".to_string(),
-                        "Count from 1 to 3".to_string(),
-                        Some("activity test".to_string()),
-                        true,
-                        None,
-                        Some(5),
-                        Some(5_000),
-                        None,
-                        None,
-                        None,
-                        None,
-                        None,
-                    ),
-                )
-                .expect("spawn should succeed");
-
-            let activity = handle.activity(py).expect("activity should be readable");
-            assert!(matches!(
-                activity.activity_type().as_str(),
-                "idle" | "requesting_llm" | "calling_tool" | "waiting_for_control"
-            ));
-        });
-    }
-}
-
 // ============================================================================
 // Plugin Classes
 // ============================================================================
@@ -5616,6 +5537,55 @@ impl PySubAgentConfig {
     }
 }
 
+#[cfg(test)]
+mod tests {
+    use super::{
+        parse_agentic_search_results, PyAgenticParseLlmBlock, PyAgenticSearchResult,
+    };
+
+    #[test]
+    fn python_agentic_search_result_info_parses_match_locators() {
+        let results = parse_agentic_search_results(
+            r#"{"results":[{"path":"scan.pdf","matches":[{"line_number":12,"content":"body","locator":"page 2 | page 2: 1. Overview","context_before":["intro"],"context_after":["tail"]}],"sampled_lines":[{"line_number":12,"content":"body","locator":"page 2","distance":0,"weight":1.0}]}]}"#,
+        )
+        .unwrap();
+
+        let parsed = PyAgenticSearchResult::from_json(&results[0]);
+        assert_eq!(parsed.matches.len(), 1);
+        assert_eq!(
+            parsed.matches[0].locator.as_deref(),
+            Some("page 2 | page 2: 1. Overview")
+        );
+        assert_eq!(parsed.matches[0].context_before, vec!["intro".to_string()]);
+        assert_eq!(parsed.sampled_lines.len(), 1);
+        assert_eq!(parsed.sampled_lines[0].distance, Some(0));
+    }
+
+    #[test]
+    fn python_agentic_parse_llm_blocks_info_parses_locations() {
+        let value = serde_json::json!({
+            "index": 1,
+            "kind": "section",
+            "label": "page 2: 1. Overview",
+            "location": {
+                "source": "report.pdf",
+                "page": 2,
+                "ordinal": 4,
+                "display": "source=report.pdf, page=2, ordinal=4"
+            }
+        });
+
+        let parsed = PyAgenticParseLlmBlock::from_json(&value);
+        assert_eq!(parsed.index, Some(1));
+        assert_eq!(parsed.kind.as_deref(), Some("section"));
+        assert_eq!(parsed.label.as_deref(), Some("page 2: 1. Overview"));
+        assert_eq!(
+            parsed.location.and_then(|loc| loc.display).as_deref(),
+            Some("source=report.pdf, page=2, ordinal=4")
+        );
+    }
+}
+
 /// Unified agent slot — used for both standalone subagents and team members.
 ///
 /// When `role` is None the slot describes a standalone subagent.