fix(ssm): address cubic review findings

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LJV2dCcAYvf1JuxquCMZAd

Author: waleedlatif1

apps/docs/content/docs/integrations/ssm.mdx

@@ -24,7 +24,9 @@ With AWS Systems Manager, you can:
 
 In Sim, the Systems Manager integration is what lets an agent act on infrastructure rather than only report on it. Paired with CloudWatch or CloudTrail for detection, a workflow can investigate an alert, run a diagnostic command against the affected nodes, read the configuration behind the failure from Parameter Store, and kick off an Automation runbook to remediate — end to end, with every step logged in your run history.
 
-Parameter Store decryption is opt-in: `Get Parameter` and `Get Parameters` leave `WithDecryption` off unless you explicitly enable it, so a SecureString stays encrypted by default. Written and decrypted values are masked in the block and are kept out of logs, traces, and error envelopes.
+Parameter Store decryption is opt-in: `Get Parameter`, `Get Parameters`, and `Get Parameters By Path` leave `WithDecryption` off unless you explicitly enable it, so a SecureString stays encrypted by default.
+
+Be precise about what that protects. The value you supply to `Put Parameter` is masked in the block, is never echoed back in the result, and no parameter value ever appears in an error message. A value you read is different: once you enable decryption, the plaintext is ordinary block output. It flows to downstream blocks as intended, and it is also written to the run log and the execution trace like any other output. Enable decryption only on the steps that genuinely need the plaintext, and treat those run logs as secret material.
 {/* MANUAL-CONTENT-END */}
 
 
@@ -48,7 +50,7 @@ Run an SSM document on managed nodes with AWS Systems Manager Run Command
 | `accessKeyId` | string | Yes | AWS access key ID |
 | `secretAccessKey` | string | Yes | AWS secret access key |
 | `documentName` | string | Yes | Name of the SSM document to run \(e.g., AWS-RunShellScript\) |
-| `instanceIds` | json | No | Managed node IDs to target, as an array of strings \(e.g., \["i-0abc123"\]\). Provide instanceIds or targets |
+| `instanceIds` | json | No | Managed node IDs to target, as an array of strings \(e.g., \["i-0123456789abcdef0"\]\). Provide instanceIds or targets |
 | `targets` | json | No | Tag or resource-group targets, as an array of \{Key, Values\} objects. Provide instanceIds or targets |
 | `documentVersion` | string | No | Document version to run \($LATEST, $DEFAULT, or a version number\) |
 | `parameters` | json | No | Document parameters, as an object mapping each parameter name to an array of string values |
@@ -149,7 +151,7 @@ Read the output and status of a Run Command execution on one managed node
 | `accessKeyId` | string | Yes | AWS access key ID |
 | `secretAccessKey` | string | Yes | AWS secret access key |
 | `commandId` | string | Yes | ID of the command, as returned by ssm_send_command |
-| `instanceId` | string | Yes | Managed node the command ran on \(e.g., i-0abc123\) |
+| `instanceId` | string | Yes | Managed node the command ran on \(e.g., i-0123456789abcdef0\) |
 | `pluginName` | string | No | Name of the document plugin to read output for; required for documents with more than one plugin |
 
 #### Output
@@ -185,7 +187,7 @@ Cancel an in-flight Run Command execution
 | `accessKeyId` | string | Yes | AWS access key ID |
 | `secretAccessKey` | string | Yes | AWS secret access key |
 | `commandId` | string | Yes | ID of the command to cancel, as returned by ssm_send_command |
-| `instanceIds` | json | No | Managed node IDs to cancel on, as an array of strings; omit to cancel on every targeted node |
+| `instanceIds` | array | No | Managed node IDs to cancel on \(e.g., \["i-0123456789abcdef0"\]\); omit to cancel on every targeted node |
 
 #### Output
 
@@ -379,7 +381,7 @@ List the patches reported for one managed node
 | `region` | string | Yes | AWS region \(e.g., us-east-1\) |
 | `accessKeyId` | string | Yes | AWS access key ID |
 | `secretAccessKey` | string | Yes | AWS secret access key |
-| `instanceId` | string | Yes | Managed node to report patches for \(e.g., i-0abc123\) |
+| `instanceId` | string | Yes | Managed node to report patches for \(e.g., i-0123456789abcdef0\) |
 | `filters` | json | No | Filters, as an array of \{Key, Values\} objects. Valid keys: Classification, KBId, Severity, State |
 | `maxResults` | number | No | Maximum number of patches to return \(10-100\) |
 | `nextToken` | string | No | Pagination token from a previous request |

apps/sim/lib/api/contracts/tools/aws/ssm-get-parameters-by-path.ts

@@ -34,7 +34,11 @@ const RequestSchema = z.object({
     }),
   accessKeyId: z.string().min(1, 'AWS access key ID is required'),
   secretAccessKey: z.string().min(1, 'AWS secret access key is required'),
-  path: z.string().min(1, 'Parameter path is required').max(2048),
+  path: z
+    .string()
+    .min(1, 'Parameter path is required')
+    .max(2048)
+    .startsWith('/', 'path must start with a forward slash (e.g., /prod/app)'),
   recursive: z.boolean().nullish(),
   withDecryption: z.boolean().nullish(),
   parameterFilters: z.array(ParameterStringFilterSchema).nullish(),

apps/sim/lib/internal/ssm/execute-tool.test.ts

@@ -214,6 +214,39 @@ describe('executeSsmTool', () => {
     expect(mockOperations.executeSsmGetCommandInvocation).not.toHaveBeenCalled()
   })
 
+  it('rejects a hierarchy path without the leading slash AWS requires', async () => {
+    const response = await executeSsmTool(
+      createRequest({
+        toolId: 'ssm_get_parameters_by_path',
+        input: { ...CONNECTION, path: 'prod/app' },
+      })
+    )
+
+    expect(response.status).toBe(400)
+    await expect(response.json()).resolves.toMatchObject({
+      details: expect.arrayContaining([
+        expect.objectContaining({
+          message: 'path must start with a forward slash (e.g., /prod/app)',
+        }),
+      ]),
+    })
+    expect(mockOperations.executeSsmGetParametersByPath).not.toHaveBeenCalled()
+  })
+
+  it('accepts a hierarchy path that starts with a slash', async () => {
+    mockOperations.executeSsmGetParametersByPath.mockResolvedValue({ parameters: [] })
+
+    const response = await executeSsmTool(
+      createRequest({
+        toolId: 'ssm_get_parameters_by_path',
+        input: { ...CONNECTION, path: '/prod/app' },
+      })
+    )
+
+    expect(response.status).toBe(200)
+    expect(mockOperations.executeSsmGetParametersByPath).toHaveBeenCalled()
+  })
+
   it('rejects an unsupported tool id', async () => {
     const response = await executeSsmTool(createRequest({ toolId: 'ssm_not_a_tool' }))
 

apps/sim/tools/generated/tool-metadata.ts

@@ -0,0 +1,38 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { awsSsmCancelCommandContract } from '@/lib/api/contracts/tools/aws/ssm-cancel-command'
+import { createUserToolSchema } from '@/tools/params'
+import { cancelCommandTool } from '@/tools/ssm/cancel_command'
+
+const COMMAND_ID = '11111111-2222-3333-4444-555555555555'
+const INSTANCE_ID = 'i-0123456789abcdef0'
+
+const CONNECTION = {
+  region: 'us-east-1',
+  accessKeyId: 'access-key',
+  secretAccessKey: 'secret-key',
+}
+
+describe('ssm_cancel_command published schema', () => {
+  const schema = createUserToolSchema(cancelCommandTool)
+
+  it('advertises instanceIds as an array of strings, not an object', () => {
+    expect(schema.properties.instanceIds).toMatchObject({
+      type: 'array',
+      items: { type: 'string' },
+      maxItems: 50,
+    })
+  })
+
+  it('accepts a request shaped the way the published schema advertises', () => {
+    const parsed = awsSsmCancelCommandContract.body?.safeParse({
+      ...CONNECTION,
+      commandId: COMMAND_ID,
+      instanceIds: [INSTANCE_ID],
+    })
+
+    expect(parsed?.success).toBe(true)
+  })
+})

apps/sim/tools/ssm/cancel_command.test.ts

@@ -36,11 +36,13 @@ export const cancelCommandTool: InternalToolConfig<
       description: 'ID of the command to cancel, as returned by ssm_send_command',
     },
     instanceIds: {
-      type: 'json',
+      type: 'array',
       required: false,
       visibility: 'user-or-llm',
+      maxItems: 50,
+      items: { type: 'string' },
       description:
-        'Managed node IDs to cancel on, as an array of strings; omit to cancel on every targeted node',
+        'Managed node IDs to cancel on (e.g., ["i-0123456789abcdef0"]); omit to cancel on every targeted node',
     },
   },
 

apps/sim/tools/ssm/cancel_command.ts

@@ -36,7 +36,7 @@ export const describeInstancePatchesTool: InternalToolConfig<
       type: 'string',
       required: true,
       visibility: 'user-or-llm',
-      description: 'Managed node to report patches for (e.g., i-0abc123)',
+      description: 'Managed node to report patches for (e.g., i-0123456789abcdef0)',
     },
     filters: {
       type: 'json',

apps/sim/tools/ssm/describe_instance_patches.ts

@@ -42,7 +42,7 @@ export const getCommandInvocationTool: InternalToolConfig<
       type: 'string',
       required: true,
       visibility: 'user-or-llm',
-      description: 'Managed node the command ran on (e.g., i-0abc123)',
+      description: 'Managed node the command ran on (e.g., i-0123456789abcdef0)',
     },
     pluginName: {
       type: 'string',

apps/sim/tools/ssm/get_command_invocation.ts

@@ -37,7 +37,7 @@ export const sendCommandTool: InternalToolConfig<SsmSendCommandParams, SsmSendCo
       required: false,
       visibility: 'user-or-llm',
       description:
-        'Managed node IDs to target, as an array of strings (e.g., ["i-0abc123"]). Provide instanceIds or targets',
+        'Managed node IDs to target, as an array of strings (e.g., ["i-0123456789abcdef0"]). Provide instanceIds or targets',
     },
     targets: {
       type: 'json',