@aws/agentcore 1.0.0-preview.23 → 1.0.0-preview.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/agentcore",
-  "version": "1.0.0-preview.23",
+  "version": "1.0.0-preview.24",
   "description": "CLI for Amazon Bedrock AgentCore",
   "license": "Apache-2.0",
   "repository": {
@@ -64,10 +64,13 @@
     "prepare": "husky",
     "test": "vitest run --project unit",
     "test:all": "vitest run",
+    "test:docs": "node --test scripts/*.test.mjs && python3 -m unittest scripts/test_render_adoc.py",
     "test:watch": "vitest --project unit",
     "test:integ": "npm run build && vitest run --project integ",
     "test:unit": "vitest run --project unit --coverage",
     "test:e2e": "vitest run --project e2e",
+    "test-artifacts:sanitize": "tsx scripts/sanitize-test-artifacts.ts --redact",
+    "test-artifacts:check": "tsx scripts/sanitize-test-artifacts.ts --check",
     "test:update-snapshots": "vitest run --project unit --update",
     "test:tui": "npm run build:harness && vitest run --project tui",
     "test:browser": "npx playwright test --config browser-tests/playwright.config.ts",

package/scripts/extract-cli-model.mjs

@@ -19,6 +19,7 @@
 import { execFileSync } from 'node:child_process';
 import { writeFileSync } from 'node:fs';
 import { argv } from 'node:process';
+import { pathToFileURL } from 'node:url';
 
 // Command grouping (arranged properly, per the request). Mirrors the sections
 // in agentcore-cli/docs/commands.md. Any command discovered from the binary but
@@ -84,11 +85,30 @@ function help(args) {
   }
 }
 
+const PARAMETER_DESCRIPTION_OVERRIDES = new Map([
+  ['bedrock, open_ai, or gemini', 'The model provider. Valid values: `bedrock`, `open_ai`, or `gemini`.'],
+  [
+    'Override LiteLLM API base URL (harness only, lite_llm) [non-interactive]',
+    'The LiteLLM API base URL override for harness invocations. ' +
+      'Available only with `lite_llm` in non-interactive mode.',
+  ],
+  [
+    'Override LiteLLM additional params as a JSON object (harness only, lite_llm) [non-interactive]',
+    'The additional LiteLLM parameters, as a JSON object, for harness invocations. ' +
+      'Available only with `lite_llm` in non-interactive mode.',
+  ],
+]);
+
+export function normalizeParameterDescription(description) {
+  return PARAMETER_DESCRIPTION_OVERRIDES.get(description) || description;
+}
+
 // Parse a Commander.js help blob into { summary, signature, params, options }.
-function parseHelp(text, name) {
+export function parseHelp(text) {
   const lines = text.split('\n');
   const out = { summary: '', signature: '', args: [], options: [] };
   let section = 'head';
+  let currentItem = null;
   const descLines = [];
 
   for (const raw of lines) {
@@ -96,18 +116,22 @@ function parseHelp(text, name) {
     if (/^Usage:/.test(line)) {
       out.signature = line.replace(/^Usage:\s*/, '').trim();
       section = 'desc';
+      currentItem = null;
       continue;
     }
     if (/^Arguments:/.test(line)) {
       section = 'args';
+      currentItem = null;
       continue;
     }
     if (/^Options:/.test(line)) {
       section = 'options';
+      currentItem = null;
       continue;
     }
     if (/^Commands:/.test(line)) {
       section = 'commands';
+      currentItem = null;
       continue;
     }
 
@@ -115,10 +139,22 @@ function parseHelp(text, name) {
       if (line.trim()) descLines.push(line.trim());
     } else if (section === 'args') {
       const m = line.match(/^\s+(\S+)\s{2,}(.*)$/);
-      if (m) out.args.push({ name: m[1], type: null, required: true, description: m[2].trim() });
+      if (m) {
+        currentItem = { name: m[1], type: null, required: true, description: m[2].trim() };
+        out.args.push(currentItem);
+      } else if (currentItem && /^\s+\S/.test(line)) {
+        currentItem.description += ` ${line.trim()}`;
+      }
     } else if (section === 'options') {
       const m = line.match(/^\s+(-[^\s].*?)\s{2,}(.*)$/);
-      if (m) out.options.push({ name: m[1].trim(), type: null, required: false, description: m[2].trim() });
+      if (m) {
+        currentItem = { name: m[1].trim(), type: null, required: false, description: m[2].trim() };
+        out.options.push(currentItem);
+      } else if (currentItem && /^\s+\S/.test(line)) {
+        currentItem.description += ` ${line.trim()}`;
+      } else if (line.trim()) {
+        currentItem = null;
+      }
     }
   }
   out.summary = descLines.join(' ');
@@ -138,7 +174,7 @@ function entryForCommand(name) {
         `not a real CLI command (phantom/renamed). Remove it from GROUPS or fix the name.`
     );
   }
-  const parsed = parseHelp(raw, name);
+  const parsed = parseHelp(raw);
   // subcommands (e.g. `add agent`, `remove tool`) show under "Commands:"—
   // we surface the top-level command; nested ones can be expanded later.
   return {
@@ -150,7 +186,10 @@ function entryForCommand(name) {
     // reuse params for both positional args and flags, flagged by required.
     // The renderer already wraps param names in backticks, so don't add our
     // own (that produced double-backticks). Drop the ubiquitous help flag.
-    params: [...parsed.args, ...parsed.options.filter(o => !/^-h,?\s|--help\b/.test(o.name))],
+    params: [...parsed.args, ...parsed.options.filter(o => !/^-h,?\s|--help\b/.test(o.name))].map(param => ({
+      ...param,
+      description: normalizeParameterDescription(param.description),
+    })),
     returns: null,
     raises: [],
     examples: [],
@@ -225,4 +264,6 @@ function main() {
   process.stderr.write(`Wrote doc-model: ${groups.length} groups, version ${version}\n`);
 }
 
-main();
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/scripts/extract-cli-model.test.mjs

@@ -0,0 +1,43 @@
+import { normalizeParameterDescription, parseHelp } from './extract-cli-model.mjs';
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+test('parseHelp preserves wrapped argument and option descriptions', () => {
+  const parsed = parseHelp(`Usage: agentcore invoke [options] [prompt]
+
+Invoke an agent.
+
+Arguments:
+  prompt                 Prompt to send to the agent. Also accepts piped
+                         stdin when no prompt is provided
+
+Options:
+  --prompt-file <path>   Read the prompt from a file (for long or
+                         structured payloads that exceed shell limits)
+
+Output
+  --json                 Output as JSON
+`);
+
+  assert.equal(
+    parsed.args[0].description,
+    'Prompt to send to the agent. Also accepts piped stdin when no prompt is provided'
+  );
+  assert.equal(
+    parsed.options[0].description,
+    'Read the prompt from a file (for long or structured payloads that exceed shell limits)'
+  );
+  assert.equal(parsed.options[1].description, 'Output as JSON');
+});
+
+test('normalizeParameterDescription expands model provider and LiteLLM fragments', () => {
+  assert.equal(
+    normalizeParameterDescription('bedrock, open_ai, or gemini'),
+    'The model provider. Valid values: `bedrock`, `open_ai`, or `gemini`.'
+  );
+  assert.equal(
+    normalizeParameterDescription('Override LiteLLM API base URL (harness only, lite_llm) [non-interactive]'),
+    'The LiteLLM API base URL override for harness invocations. ' +
+      'Available only with `lite_llm` in non-interactive mode.'
+  );
+});

package/scripts/render_adoc.py

@@ -55,15 +55,91 @@ import textwrap
 SCHEMA_VERSION = 1
 
 
+def normalize_style(text):
+    """Apply style-safe substitutions to generated prose."""
+    if not text:
+        return ""
+    text = re.sub(r"\be\.g\.(?:,)?", "for example,", text, flags=re.IGNORECASE)
+    text = re.sub(
+        r"\bAWS (?:Bedrock(?: AgentCore)? )?Code\s*Interpreter\b",
+        "Amazon Bedrock AgentCore Code Interpreter",
+        text,
+        flags=re.IGNORECASE,
+    )
+    text = re.sub(r"\bAWS Bedrock AgentCore\b", "Amazon Bedrock AgentCore", text)
+    text = re.sub(r"\bAWS Bedrock\b", "Amazon Bedrock", text)
+    text = re.sub(
+        r"(?<!Amazon )(?<!AWS )\bBedrock AgentCore\b",
+        "Amazon Bedrock AgentCore",
+        text,
+    )
+    text = re.sub(
+        r"(?<!Amazon Bedrock )\bAgentCore Code Interpreter\b",
+        "Amazon Bedrock AgentCore Code Interpreter",
+        text,
+    )
+    text = re.sub(
+        r"(?<!Amazon Bedrock )\bAgentCore runtime\b",
+        "Amazon Bedrock AgentCore runtime",
+        text,
+    )
+    text = re.sub(
+        r"(?<!Amazon Bedrock )\bAgentCore Identity\b",
+        "Amazon Bedrock AgentCore Identity",
+        text,
+    )
+    text = text.replace(", allowing applications to", " so applications can")
+    text = re.sub(r"\bAWS region\b", "AWS Region", text, flags=re.IGNORECASE)
+    text = re.sub(r"\bAgentCore Memory\b", "AgentCore memory", text)
+    text = re.sub(r"\bAgentCore Runtime\b", "AgentCore runtime", text)
+    text = text.replace(
+        "This feature is in preview and may change in future releases.",
+        "This feature is in preview and might change in future releases.",
+    )
+    text = text.replace("validation will ensure", "validation ensures")
+    return re.sub(r"\bAWS\b", "{aws}", text)
+
+
+def normalize_param_description(text):
+    """Normalize recurring parameter-description style issues."""
+    text = normalize_style(text).strip()
+    exact_substitutions = {
+        "bedrock, open_ai, or gemini": (
+            "The model provider. Valid values: `bedrock`, `open_ai`, or `gemini`."
+        ),
+        "Override LiteLLM API base URL (harness only, lite_llm) [non-interactive]": (
+            "The LiteLLM API base URL override for harness invocations. "
+            "Available only with `lite_llm` in non-interactive mode."
+        ),
+        "Override LiteLLM additional params as a JSON object (harness only, lite_llm) "
+        "[non-interactive]": (
+            "The additional LiteLLM parameters, as a JSON object, for harness invocations. "
+            "Available only with `lite_llm` in non-interactive mode."
+        ),
+    }
+    if text in exact_substitutions:
+        return exact_substitutions[text]
+    substitutions = (
+        (r"^Optional\b", "The optional"),
+        (r"^(?:\{aws\}|AWS)\s+region\b", "The {aws} Region"),
+        (r"^id of\b", "The ID of"),
+        (r"^Behaviour\b", "The behavior"),
+        (r"^Behavior\b", "The behavior"),
+        (r"^Memory resource ID\b", "The memory resource ID"),
+        (r"^Strategy name\b", "The name of the memory strategy"),
+        (r"^Strategy ID\b", "The ID of the memory strategy"),
+    )
+    for pattern, replacement in substitutions:
+        text = re.sub(pattern, replacement, text, count=1, flags=re.IGNORECASE)
+    return text
 def esc(text):
     """Escape AsciiDoc-significant characters in inline text."""
     if not text:
         return ""
     # Guard the couple of chars that start AsciiDoc markup in running prose.
-    return (
-        text.replace("|", "\\|")
-        .replace("{", "\\{")
-    )
+    marker = "\0AWS_ENTITY\0"
+    text = normalize_style(text).replace("{aws}", marker)
+    return text.replace("|", "\\|").replace("{", "\\{").replace(marker, "{aws}")
 
 
 # Match markdown code fences that may be indented (reST/Google docstrings often
@@ -116,7 +192,7 @@ def render_params(params, out):
         req = "" if p.get("required") else " _(optional)_"
         typ = f"`{p['type']}`" if p.get("type") else ""
         out.append(f"`{p['name']}`{req} {typ}::")
-        out.append(esc(p.get("description", "")) or "_No description._")
+        out.append(esc(normalize_param_description(p.get("description", ""))) or "_No description._")
     out.append("")
 
 

package/scripts/safe-junit-reporter.ts

@@ -0,0 +1,7 @@
+import { JUnitReporter } from 'vitest/node';
+
+export default class SafeJUnitReporter extends JUnitReporter {
+  constructor() {
+    super({ includeConsoleOutput: false });
+  }
+}

package/scripts/sanitize-test-artifacts.ts

@@ -0,0 +1,65 @@
+import { redactTestOutput, sensitiveEnvironmentValues } from '../src/test-utils/test-output-redaction';
+import { lstat, readFile, readdir, writeFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+
+type Mode = 'check' | 'redact';
+
+async function collectFiles(inputPath: string): Promise<string[]> {
+  const absolutePath = resolve(inputPath);
+
+  try {
+    const fileStat = await lstat(absolutePath);
+    if (fileStat.isSymbolicLink()) {
+      throw new Error(`Symbolic links are not allowed in test artifacts: ${inputPath}`);
+    }
+    if (fileStat.isFile()) return [absolutePath];
+    if (!fileStat.isDirectory()) return [];
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+
+  const entries = await readdir(absolutePath, { withFileTypes: true });
+  const files = await Promise.all(entries.map(entry => collectFiles(resolve(absolutePath, entry.name))));
+  return files.flat();
+}
+
+async function main(): Promise<void> {
+  const [modeArgument, ...inputPaths] = process.argv.slice(2);
+  if ((modeArgument !== '--redact' && modeArgument !== '--check') || inputPaths.length === 0) {
+    throw new Error('Usage: tsx scripts/sanitize-test-artifacts.ts <--redact|--check> <path...>');
+  }
+
+  const mode = modeArgument.slice(2) as Mode;
+  const files = (await Promise.all(inputPaths.map(collectFiles))).flat();
+  const secretValues = sensitiveEnvironmentValues();
+  const affectedFiles: string[] = [];
+  let redactionCount = 0;
+
+  for (const file of files) {
+    const original = await readFile(file, 'utf8');
+    const result = redactTestOutput(original, secretValues);
+    if (result.redactions === 0) continue;
+
+    affectedFiles.push(relative(process.cwd(), file));
+    redactionCount += result.redactions;
+    if (mode === 'redact') await writeFile(file, result.text, 'utf8');
+  }
+
+  if (mode === 'check' && affectedFiles.length > 0) {
+    console.error(`Sensitive output detected in ${affectedFiles.length} artifact file(s): ${affectedFiles.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (mode === 'redact') {
+    console.log(`Redacted ${redactionCount} sensitive value(s) from ${affectedFiles.length} artifact file(s).`);
+  } else {
+    console.log(`No sensitive output detected in ${files.length} artifact file(s).`);
+  }
+}
+
+void main().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/scripts/test_render_adoc.py

@@ -0,0 +1,38 @@
+import unittest
+
+from scripts.render_adoc import normalize_param_description, normalize_style
+
+
+class NormalizeParamDescriptionTest(unittest.TestCase):
+    def test_optional_descriptions_support_singular_plural_and_mass_nouns(self):
+        cases = {
+            "Optional session name.": "The optional session name.",
+            "Optional tags.": "The optional tags.",
+            "Optional additional task metadata.": "The optional additional task metadata.",
+        }
+
+        for description, expected in cases.items():
+            with self.subTest(description=description):
+                self.assertEqual(normalize_param_description(description), expected)
+
+    def test_service_names_are_fully_qualified(self):
+        self.assertEqual(
+            normalize_style("Client for AgentCore runtime."),
+            "Client for Amazon Bedrock AgentCore runtime.",
+        )
+        self.assertEqual(
+            normalize_style("Client for the AgentCore Code Interpreter sandbox service."),
+            "Client for the Amazon Bedrock AgentCore Code Interpreter sandbox service.",
+        )
+        self.assertEqual(
+            normalize_style("Retrieves an API key from AgentCore Identity."),
+            "Retrieves an API key from Amazon Bedrock AgentCore Identity.",
+        )
+        self.assertEqual(
+            normalize_style("Provides credentials, allowing applications to connect."),
+            "Provides credentials so applications can connect.",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()