@sourcegraph/amp-sdk 0.1.0-20251022202704-gd85048a → 0.1.0-20251126160117-g66ad0bc

package/LICENSE.md

@@ -1 +1 @@
-© Sourcegraph Inc. All rights reserved. Use of Amp is subject to Amp's [Terms of Service](https://ampcode.com/terms).
+© Sourcegraph Inc. All rights reserved. Use of Amp is subject to Amp's [Terms of Service](https://ampcode.com/terms), or separate Amp terms that you have signed with Sourcegraph Inc.

package/README.md

@@ -36,13 +36,11 @@ The Amp SDK enables a wide range of AI-powered applications:
 
 ### Installation
 
-Install the Amp SDK using `npm` or `yarn`:
-
 ```bash
-# npm
+# Install the Amp SDK using npm
 npm install @sourcegraph/amp-sdk
 
-# yarn
+# or yarn
 yarn add @sourcegraph/amp-sdk
 ```
 
@@ -397,3 +395,520 @@ for await (const message of execute({
 ```
 
 To find out more about Amp Toolboxes, see the [Toolboxes](https://ampcode.com/manual#toolboxes) section of the Amp documentation.
+
+## Functions
+
+### execute()
+
+The main function for executing Amp CLI commands programmatically.
+
+```typescript
+function execute(options: ExecuteOptions): AsyncIterable<StreamMessage>
+```
+
+#### Parameters
+
+- `options` ([`ExecuteOptions`](#executeoptions)) - Configuration for the execution
+
+#### Returns
+
+- `AsyncIterable<StreamMessage>` - Stream of messages from the Amp CLI
+
+#### Example
+
+```typescript
+import { execute } from '@sourcegraph/amp-sdk'
+
+for await (const message of execute({
+	prompt: 'Analyze this codebase',
+	options: {
+		cwd: './my-project',
+		dangerouslyAllowAll: true,
+	},
+})) {
+	if (message.type === 'assistant') {
+		console.log('Assistant:', message.message.content)
+	} else if (message.type === 'result') {
+		console.log('Final result:', message.result)
+		break
+	}
+}
+```
+
+### createUserMessage()
+
+Helper function to create properly formatted user input messages for streaming conversations.
+
+```typescript
+function createUserMessage(text: string): UserInputMessage
+```
+
+#### Parameters
+
+- `text` (`string`) - The text content for the user message
+
+#### Returns
+
+- [`UserInputMessage`](#userinputmessage) - A formatted user input message
+
+#### Example
+
+```typescript
+import { createUserMessage } from '@sourcegraph/amp-sdk'
+
+const message = createUserMessage('Analyze this code')
+console.log(message)
+// Output: { type: 'user', message: { role: 'user', content: [{ type: 'text', text: 'Analyze this code' }] } }
+```
+
+### createPermission()
+
+Helper function to create permission objects for controlling tool usage.
+
+```typescript
+function createPermission(
+	tool: string,
+	action: 'allow' | 'reject' | 'ask' | 'delegate',
+	options?: {
+		matches?: Record<string, PermissionMatchCondition>
+		context?: 'thread' | 'subagent'
+		to?: string
+	},
+): Permission
+```
+
+#### Parameters
+
+- `tool` (`string`) - The name of the tool to which this permission applies (supports glob patterns)
+- `action` (`'allow' | 'reject' | 'ask' | 'delegate'`) - How Amp should proceed when matched
+- `options` (`object`, optional) - Additional configuration for the permission
+  - `matches` ([`Record<string, PermissionMatchCondition>`](#permissionmatchcondition)) - Match conditions for tool arguments
+  - `context` (`'thread' | 'subagent'`) - Only apply this rule in specific context
+  - `to` (`string`) - Command to delegate to (required when action is `'delegate'`)
+
+#### Returns
+
+- [`Permission`](#permission) - A permission object that can be used in the permissions array
+
+#### Examples
+
+```typescript
+import { createPermission } from '@sourcegraph/amp-sdk'
+
+// Allow all Bash commands
+createPermission('Bash', 'allow')
+
+// Allow specific git commands
+createPermission('Bash', 'allow', {
+	matches: { cmd: 'git *' },
+})
+
+// Ask before allowing Read operations on sensitive paths
+createPermission('Read', 'ask', {
+	matches: { path: '/etc/*' },
+})
+
+// Delegate web browsing to a custom command
+createPermission('mcp__playwright__*', 'delegate', {
+	to: 'node browse.js',
+})
+
+// Only apply in subagent context
+createPermission('Bash', 'reject', {
+	context: 'subagent',
+})
+```
+
+## Types
+
+### ExecuteOptions
+
+Configuration options for the `execute()` function.
+
+```typescript
+interface ExecuteOptions {
+	prompt: string | AsyncIterable<UserInputMessage>
+	options?: AmpOptions
+	signal?: AbortSignal
+}
+```
+
+#### Properties
+
+| Property  | Type                                        | Required | Description                                                                                  |
+| --------- | ------------------------------------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `prompt`  | `string \| AsyncIterable<UserInputMessage>` | Yes      | The input prompt as a string or async iterable of user messages for multi-turn conversations |
+| `options` | [`AmpOptions`](#ampoptions)                 | No       | CLI configuration options                                                                    |
+| `signal`  | `AbortSignal`                               | No       | Signal for cancellation support                                                              |
+
+### AmpOptions
+
+Configuration options that map to Amp CLI flags.
+
+```typescript
+interface AmpOptions {
+	cwd?: string
+	dangerouslyAllowAll?: boolean
+	visibility?: 'public' | 'private' | 'workspace' | 'group'
+	settingsFile?: string
+	logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'audit'
+	logFile?: string
+	mcpConfig?: string | MCPConfig
+	env?: Record<string, string>
+	continue?: boolean | string
+	toolbox?: string
+	permissions?: Permission[]
+}
+```
+
+#### Properties
+
+| Property              | Type                                                | Default         | Description                                                              |
+| --------------------- | --------------------------------------------------- | --------------- | ------------------------------------------------------------------------ |
+| `cwd`                 | `string`                                            | `process.cwd()` | Current working directory for execution                                  |
+| `dangerouslyAllowAll` | `boolean`                                           | `false`         | Allow all tool usage without permission prompts                          |
+| `visibility`          | `'public' \| 'private' \| 'workspace' \| 'group'`   | `'workspace'`   | Thread visibility level                                                  |
+| `settingsFile`        | `string`                                            | -               | Path to custom settings file                                             |
+| `logLevel`            | `'debug' \| 'info' \| 'warn' \| 'error' \| 'audit'` | `'info'`        | Logging verbosity level                                                  |
+| `logFile`             | `string`                                            | -               | Path to write logs                                                       |
+| `continue`            | `boolean \| string`                                 | `false`         | Continue most recent thread (`true`) or specific thread by ID (`string`) |
+| `mcpConfig`           | `string \| MCPConfig`                               | -               | MCP server configuration as JSON string, or config object                |
+| `env`                 | `Record<string, string>`                            | -               | Additional environment variables                                         |
+| `toolbox`             | `string`                                            | -               | Folder path with toolbox scripts                                         |
+| `permissions`         | [`Permission[]`](#permission)                       | -               | Permission rules for tool usage                                          |
+
+## Message Types
+
+The SDK streams various message types during execution. All messages implement the base `StreamMessage` type.
+
+### SystemMessage
+
+Initial message containing session information and available tools.
+
+```typescript
+interface SystemMessage {
+	type: 'system'
+	subtype: 'init'
+	session_id: string
+	cwd: string
+	tools: string[]
+	mcp_servers: Array<{
+		name: string
+		status: 'connected' | 'connecting' | 'connection-failed' | 'disabled'
+	}>
+}
+```
+
+#### Properties
+
+| Property      | Type                                    | Description                                  |
+| ------------- | --------------------------------------- | -------------------------------------------- |
+| `session_id`  | `string`                                | Unique identifier for this execution session |
+| `cwd`         | `string`                                | Current working directory                    |
+| `tools`       | `string[]`                              | List of available tool names                 |
+| `mcp_servers` | `Array<{name: string, status: string}>` | Status of MCP servers                        |
+
+### AssistantMessage
+
+AI assistant responses with text content and tool usage.
+
+```typescript
+interface AssistantMessage {
+	type: 'assistant'
+	session_id: string
+	message: {
+		id: string
+		type: 'message'
+		role: 'assistant'
+		model: string
+		content: Array<TextContent | ToolUseContent>
+		stop_reason: 'end_turn' | 'tool_use' | 'max_tokens' | null
+		stop_sequence: string | null
+		usage?: Usage
+	}
+	parent_tool_use_id: string | null
+}
+```
+
+#### Properties
+
+| Property             | Type             | Description                                      |
+| -------------------- | ---------------- | ------------------------------------------------ |
+| `session_id`         | `string`         | Unique identifier for this execution session     |
+| `message`            | `object`         | The assistant's message content                  |
+| `parent_tool_use_id` | `string \| null` | ID of parent tool use if this is a tool response |
+
+### UserMessage
+
+User input and tool results.
+
+```typescript
+interface UserMessage {
+	type: 'user'
+	session_id: string
+	message: {
+		role: 'user'
+		content: Array<TextContent | ToolResultContent>
+	}
+	parent_tool_use_id: string | null
+}
+```
+
+#### Properties
+
+| Property             | Type             | Description                                      |
+| -------------------- | ---------------- | ------------------------------------------------ |
+| `session_id`         | `string`         | Unique identifier for this execution session     |
+| `message`            | `object`         | The user's message content                       |
+| `parent_tool_use_id` | `string \| null` | ID of parent tool use if this is a tool response |
+
+### ResultMessage
+
+Final successful execution result.
+
+```typescript
+interface ResultMessage {
+	type: 'result'
+	subtype: 'success'
+	session_id: string
+	is_error: false
+	result: string
+	duration_ms: number
+	num_turns: number
+	usage?: Usage
+	permission_denials?: string[]
+}
+```
+
+#### Properties
+
+| Property             | Type              | Description                                  |
+| -------------------- | ----------------- | -------------------------------------------- |
+| `session_id`         | `string`          | Unique identifier for this execution session |
+| `result`             | `string`          | The final result from the assistant          |
+| `duration_ms`        | `number`          | Total execution time in milliseconds         |
+| `num_turns`          | `number`          | Number of conversation turns                 |
+| `usage`              | [`Usage`](#usage) | Token usage information                      |
+| `permission_denials` | `string[]`        | List of permissions that were denied         |
+
+### ErrorResultMessage
+
+Final error result indicating execution failure.
+
+```typescript
+interface ErrorResultMessage {
+	type: 'result'
+	subtype: 'error_during_execution' | 'error_max_turns'
+	session_id: string
+	is_error: true
+	error: string
+	duration_ms: number
+	num_turns: number
+	usage?: Usage
+	permission_denials?: string[]
+}
+```
+
+#### Properties
+
+| Property             | Type              | Description                                  |
+| -------------------- | ----------------- | -------------------------------------------- |
+| `session_id`         | `string`          | Unique identifier for this execution session |
+| `error`              | `string`          | Error message describing what went wrong     |
+| `duration_ms`        | `number`          | Total execution time in milliseconds         |
+| `num_turns`          | `number`          | Number of conversation turns                 |
+| `usage`              | [`Usage`](#usage) | Token usage information                      |
+| `permission_denials` | `string[]`        | List of permissions that were denied         |
+
+### TextContent
+
+Plain text content block.
+
+```typescript
+interface TextContent {
+	type: 'text'
+	text: string
+}
+```
+
+### ToolUseContent
+
+Tool execution request.
+
+```typescript
+interface ToolUseContent {
+	type: 'tool_use'
+	id: string
+	name: string
+	input: Record<string, unknown>
+}
+```
+
+### ToolResultContent
+
+Result from tool execution.
+
+```typescript
+interface ToolResultContent {
+	type: 'tool_result'
+	tool_use_id: string
+	content: string
+	is_error: boolean
+}
+```
+
+### Usage
+
+Token usage and billing information from API calls.
+
+```typescript
+interface Usage {
+	input_tokens: number
+	cache_creation_input_tokens?: number
+	cache_read_input_tokens?: number
+	output_tokens: number
+	service_tier?: string
+}
+```
+
+#### Properties
+
+| Property                      | Type     | Description                        |
+| ----------------------------- | -------- | ---------------------------------- |
+| `input_tokens`                | `number` | Number of input tokens used        |
+| `cache_creation_input_tokens` | `number` | Tokens used for cache creation     |
+| `cache_read_input_tokens`     | `number` | Tokens read from cache             |
+| `output_tokens`               | `number` | Number of output tokens generated  |
+| `service_tier`                | `string` | Service tier used for this request |
+
+## Input Types
+
+### UserInputMessage
+
+Formatted user input message for streaming conversations.
+
+```typescript
+interface UserInputMessage {
+	type: 'user'
+	message: {
+		role: 'user'
+		content: Array<{
+			type: 'text'
+			text: string
+		}>
+	}
+}
+```
+
+### MCPConfig
+
+Configuration for MCP (Model Context Protocol) servers.
+
+```typescript
+type MCPConfig = Record<string, MCPServer>
+
+interface MCPServer {
+	command: string
+	args?: string[]
+	env?: Record<string, string>
+	disabled?: boolean
+}
+```
+
+#### Properties
+
+| Property   | Type                     | Required | Description                          |
+| ---------- | ------------------------ | -------- | ------------------------------------ |
+| `command`  | `string`                 | Yes      | Command to start the MCP server      |
+| `args`     | `string[]`               | No       | Command line arguments               |
+| `env`      | `Record<string, string>` | No       | Environment variables for the server |
+| `disabled` | `boolean`                | No       | Whether this server is disabled      |
+
+### Permission
+
+Individual permission rule for controlling tool usage.
+
+```typescript
+interface Permission {
+	tool: string
+	matches?: Record<string, PermissionMatchCondition>
+	action: 'allow' | 'reject' | 'ask' | 'delegate'
+	context?: 'thread' | 'subagent'
+	to?: string
+}
+```
+
+#### Properties
+
+| Property  | Type                                         | Required | Description                                                 |
+| --------- | -------------------------------------------- | -------- | ----------------------------------------------------------- |
+| `tool`    | `string`                                     | Yes      | Tool name (supports glob patterns like `Bash` or `mcp__*`)  |
+| `matches` | `Record<string, PermissionMatchCondition>`   | No       | Match conditions for tool arguments                         |
+| `action`  | `'allow' \| 'reject' \| 'ask' \| 'delegate'` | Yes      | How Amp should proceed when the rule matches                |
+| `context` | `'thread' \| 'subagent'`                     | No       | Apply rule only in main thread or sub-agents                |
+| `to`      | `string`                                     | No       | Command to delegate to (required when action is `delegate`) |
+
+#### Example
+
+```typescript
+import { execute, createPermission } from '@sourcegraph/amp-sdk'
+
+for await (const message of execute({
+	prompt: 'Deploy the application',
+	options: {
+		permissions: [
+			// Allow git commands
+			createPermission('Bash', 'allow', { matches: { cmd: 'git *' } }),
+			// Allow reading files
+			createPermission('Read', 'allow'),
+		],
+	},
+})) {
+	// Handle messages
+}
+```
+
+### PermissionMatchCondition
+
+Match condition for tool arguments. Supports strings (with glob patterns or regex), arrays (OR logic), booleans, numbers, null, undefined, and nested objects.
+
+```typescript
+type PermissionMatchCondition =
+	| string
+	| PermissionMatchCondition[]
+	| { [key: string]: PermissionMatchCondition }
+	| boolean
+	| number
+	| null
+	| undefined
+```
+
+#### Examples
+
+```typescript
+// String pattern with wildcard
+{
+	cmd: 'npm *'
+}
+
+// Array for OR logic
+{
+	cmd: ['npm install', 'npm test', 'npm run build']
+}
+
+// Regex pattern
+{
+	cmd: '/^git (status|log|diff)$/'
+}
+
+// Nested object matching
+{
+	env: {
+		NODE_ENV: 'production'
+	}
+}
+```
+
+## Requirements
+
+- Node.js 18 or higher

package/dist/index.js

@@ -4154,7 +4154,7 @@ function buildEnvironmentVariables(options) {
   if (options.env) {
     Object.assign(env, options.env);
   }
-  env.AMP_SDK_VERSION = "0.1.0-20251022202704-gd85048a";
+  env.AMP_SDK_VERSION = "0.1.0-20251126160117-g66ad0bc";
   return env;
 }
 function spawnAmpCli(args, options) {
@@ -4355,4 +4355,4 @@ export {
   AmpOptionsSchema
 };
 
-//# debugId=55BAB45A56267D2564756E2164756E21
+//# debugId=B95AEF07534E4E7264756E2164756E21

package/package.json

@@ -34,7 +34,7 @@
     "sdk",
     "automation"
   ],
-  "license": "SEE LICENSE IN LICENSE.md",
+  "license": "Sourcegraph Commercial License",
   "main": "dist/index.js",
   "name": "@sourcegraph/amp-sdk",
   "repository": {
@@ -44,7 +44,7 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.1.0-20251022202704-gd85048a",
+  "version": "0.1.0-20251126160117-g66ad0bc",
   "scripts": {
     "build": "bun run scripts/build.ts",
     "dev": "pnpm exec tsc -b --watch",
@@ -52,6 +52,7 @@
     "examples:basic": "pnpm run build && bun run examples/basic.ts",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:integration": "vitest run --config vitest.integration.config.js",
     "pin-cli-version": "bun run scripts/pin-cli-version.ts"
   }
 }