@sourcegraph/amp-sdk 0.1.0-20251014155204-ge7f0f28 → 0.1.0-20251020161918-gf8ab86d

package/README.md

@@ -191,6 +191,38 @@ for await (const message of execute({
 }
 ```
 
+### Tool Permissions
+
+Control which tools Amp can use with fine-grained permissions:
+
+```typescript
+import { execute, createPermission } from '@sourcegraph/amp-sdk'
+
+for await (const message of execute({
+	prompt: 'List files and run tests',
+	options: {
+		permissions: [
+			// Allow listing files
+			createPermission('Bash', 'allow', { matches: { cmd: 'ls *' } }),
+			// Allow running tests
+			createPermission('Bash', 'allow', { matches: { cmd: 'npm test' } }),
+			// Ask before reading sensitive files
+			createPermission('Read', 'ask', { matches: { path: '/etc/*' } }),
+		],
+	},
+})) {
+	// Process messages
+}
+```
+
+Permission rules support:
+
+- **Pattern matching**: Use `*` wildcards and regex patterns
+- **Context control**: Restrict rules to main thread or sub-agents
+- **Delegation**: Delegate permission decisions to external programs
+
+Learn more about permissions in the [manual](https://ampcode.com/manual#permissions) and the [appendix](https://ampcode.com/manual/appendix#permissions-reference).
+
 ## Advanced Usage
 
 ### Interactive Progress Tracking

package/dist/index.d.ts

@@ -5,17 +5,16 @@
  * run Amp programmatically in Node.js applications. It wraps the Amp CLI
  * with the --stream-json flag to provide structured output.
  */
-import { type ExecuteOptions, type StreamMessage, type UserInputMessage } from './types.js';
-/**
- * Execute a command with Amp CLI and return an async iterator of messages
- *
- * @param options Execute configuration including prompt and options
- * @returns Async iterator of stream messages from Amp CLI
- */
+import { type ExecuteOptions, type Permission, type PermissionMatchCondition, type StreamMessage, type UserInputMessage } from './types.js';
+/** Execute a command with Amp CLI and return an async iterator of messages */
 export declare function execute(options: ExecuteOptions): AsyncIterable<StreamMessage>;
-/**
- * Helper function to create streaming input messages
- */
+/** Create a user input message for streaming conversations */
 export declare function createUserMessage(text: string): UserInputMessage;
+/** Create a permission object for controlling tool usage */
+export declare function createPermission(tool: string, action: 'allow' | 'reject' | 'ask' | 'delegate', options?: {
+    matches?: Record<string, PermissionMatchCondition>;
+    context?: 'thread' | 'subagent';
+    to?: string;
+}): Permission;
 export * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -7,6 +7,7 @@
  */
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
@@ -16,31 +17,33 @@ const isWindows = process.platform === 'win32';
 // ============================================================================
 // Main Execute Function
 // ============================================================================
-/**
- * Execute a command with Amp CLI and return an async iterator of messages
- *
- * @param options Execute configuration including prompt and options
- * @returns Async iterator of stream messages from Amp CLI
- */
+/** Execute a command with Amp CLI and return an async iterator of messages */
 export async function* execute(options) {
     const { prompt, options: ampOptions = {}, signal } = options;
     // Validate options
-    const validatedOptions = AmpOptionsSchema.parse(ampOptions);
-    // Handle different prompt types
-    const isStreamingInput = typeof prompt !== 'string' && Symbol.asyncIterator in prompt;
+    let validatedOptions = AmpOptionsSchema.parse(ampOptions);
+    // Build settings file (create temp file if needed)
+    const { settingsFilePath, cleanupTempFile } = await buildSettingsFile(validatedOptions, generateSessionId());
+    // Update options with temp settings file path if created
+    validatedOptions = {
+        ...validatedOptions,
+        ...(settingsFilePath && { settingsFile: settingsFilePath }),
+    };
     // Build CLI arguments
     const args = buildCliArgs(validatedOptions);
+    // Handle different prompt types
+    const isStreamingInput = typeof prompt !== 'string' && Symbol.asyncIterator in prompt;
     // Add flag for streaming input if needed
     if (isStreamingInput) {
         args.push('--stream-json-input');
     }
+    // Build environment variables
+    const env = buildEnvironmentVariables(validatedOptions);
     // Log the full CLI command for debugging (only in debug mode)
     if (process.env.AMP_DEBUG || validatedOptions.logLevel === 'debug') {
         const ampCommand = findAmpCommand();
         console.debug(`Executing Amp CLI: ${ampCommand.command} ${[...ampCommand.args, ...args].join(' ')}`);
     }
-    // Build environment variables
-    const env = buildEnvironmentVariables(validatedOptions);
     // Spawn Amp CLI process
     const ampProcess = spawnAmpCli(args, {
         env,
@@ -88,14 +91,71 @@ export async function* execute(options) {
         }
         throw error;
     }
+    finally {
+        // Clean up temp settings file
+        await cleanupTempFile();
+    }
+}
+// ============================================================================
+// Settings File Management
+// ============================================================================
+/** Generate a unique session ID for organizing temp files */
+function generateSessionId() {
+    const randomHex = Math.random().toString(36).substring(2, 10);
+    return `sdk-${Date.now()}-${randomHex}`;
+}
+/** Build settings file for CLI execution, creating a temp file if permissions need to be passed */
+async function buildSettingsFile(options, sessionId) {
+    // Check if we need to create a temp settings file
+    if (!options.permissions) {
+        // No temp file needed
+        return {
+            settingsFilePath: null,
+            cleanupTempFile: async () => { },
+        };
+    }
+    // Determine working directory
+    const cwd = options.cwd || process.cwd();
+    // Create temp directory path: {cwd}/.tmp/{sessionId}/
+    const tempDir = path.join(cwd, '.tmp', sessionId);
+    const tempSettingsPath = path.join(tempDir, 'settings.json');
+    // Read existing settings file if provided
+    let mergedSettings = {};
+    if (options.settingsFile) {
+        try {
+            const settingsContent = await readFile(options.settingsFile, 'utf-8');
+            mergedSettings = JSON.parse(settingsContent);
+        }
+        catch (error) {
+            // If file doesn't exist or can't be read, start with empty settings
+            if (error.code !== 'ENOENT') {
+                throw new Error(`Failed to read settings file ${options.settingsFile}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    // Add permissions to settings with amp. prefix
+    mergedSettings['amp.permissions'] = options.permissions;
+    // Create temp directory
+    await mkdir(tempDir, { recursive: true });
+    // Write merged settings to temp file
+    await writeFile(tempSettingsPath, JSON.stringify(mergedSettings, null, 2), 'utf-8');
+    // Return temp file path and cleanup function
+    return {
+        settingsFilePath: tempSettingsPath,
+        cleanupTempFile: async () => {
+            try {
+                await rm(tempDir, { recursive: true, force: true });
+            }
+            catch (error) {
+                // Ignore cleanup errors
+            }
+        },
+    };
 }
 // ============================================================================
 // Environment Variable Management
 // ============================================================================
-/**
- * Build environment variables for the Amp CLI process
- * Combines system environment variables with user-provided options
- */
+/** Build environment variables for the Amp CLI process */
 function buildEnvironmentVariables(options) {
     const env = {
         ...process.env,
@@ -113,6 +173,7 @@ function buildEnvironmentVariables(options) {
 // ============================================================================
 // CLI Process Management
 // ============================================================================
+/** Spawn the Amp CLI process with the given arguments */
 function spawnAmpCli(args, options) {
     const { env, cwd, signal } = options;
     // Find amp executable
@@ -129,6 +190,7 @@ function spawnAmpCli(args, options) {
     });
     return childProcess;
 }
+/** Find the Amp CLI executable in the local node_modules */
 function findAmpCommand() {
     // Try to find the local CLI (npm already resolved the correct version)
     try {
@@ -152,6 +214,7 @@ function findAmpCommand() {
         throw new Error('Could not find local @sourcegraph/amp package. Make sure it is installed.');
     }
 }
+/** Build CLI arguments from options */
 function buildCliArgs(options) {
     const args = [];
     // Handle continue option first as it changes the base command structure
@@ -190,6 +253,7 @@ function buildCliArgs(options) {
 // ============================================================================
 // Stream Processing
 // ============================================================================
+/** Process the stdout stream from Amp CLI and yield parsed messages */
 async function* processOutputStream(stdout) {
     if (!stdout) {
         throw new Error('No stdout stream available from Amp CLI process');
@@ -215,6 +279,7 @@ async function* processOutputStream(stdout) {
         readline.close();
     }
 }
+/** Handle streaming input by writing user messages to the process stdin */
 async function handleStreamingInput(process, prompt, signal) {
     if (!process.stdin) {
         throw new Error('No stdin stream available for Amp CLI process');
@@ -248,6 +313,7 @@ async function handleStreamingInput(process, prompt, signal) {
         process.stdin.end();
     }
 }
+/** Handle string input by writing the prompt to process stdin */
 function handleStringInput(process, prompt) {
     if (!process.stdin) {
         throw new Error('No stdin stream available for Amp CLI process');
@@ -256,6 +322,7 @@ function handleStringInput(process, prompt) {
     process.stdin.write(prompt + '\n');
     process.stdin.end();
 }
+/** Wait for the process to exit and capture exit code, stderr, and signal */
 function waitForProcess(process, signal) {
     return new Promise((resolve, reject) => {
         let resolved = false;
@@ -306,9 +373,7 @@ function waitForProcess(process, signal) {
 // ============================================================================
 // Utility Functions
 // ============================================================================
-/**
- * Helper function to create streaming input messages
- */
+/** Create a user input message for streaming conversations */
 export function createUserMessage(text) {
     return {
         type: 'user',
@@ -318,6 +383,23 @@ export function createUserMessage(text) {
         },
     };
 }
+/** Create a permission object for controlling tool usage */
+export function createPermission(tool, action, options) {
+    const permission = {
+        tool,
+        action,
+        ...(options?.matches && { matches: options.matches }),
+        ...(options?.context && { context: options.context }),
+    };
+    // delegate requires "to"
+    if (action === 'delegate') {
+        if (!options?.to) {
+            throw new Error('delegate action requires "to" option');
+        }
+        permission.to = options.to;
+    }
+    return permission;
+}
 // ============================================================================
 // Re-export types for convenience
 // ============================================================================

package/dist/types.d.ts

@@ -91,7 +91,9 @@ export interface ErrorResultMessage extends BaseResultMessage {
     is_error: true;
     error: string;
 }
+/** Union of all possible stream messages */
 export type StreamMessage = SystemMessage | AssistantMessage | UserMessage | ResultMessage | ErrorResultMessage;
+/** User input message schema */
 export declare const UserInputMessageSchema: z.ZodObject<{
     type: z.ZodLiteral<"user">;
     message: z.ZodObject<{
@@ -138,6 +140,51 @@ export declare const UserInputMessageSchema: z.ZodObject<{
     };
     type: "user";
 }>;
+/** User input message for streaming conversations */
+export type UserInputMessage = z.infer<typeof UserInputMessageSchema>;
+/** Recursive type for permission match conditions */
+export type PermissionMatchCondition = string | PermissionMatchCondition[] | {
+    [key in string]: PermissionMatchCondition;
+} | boolean | number | null | undefined;
+/** Permission match condition for tool arguments schema */
+export declare const PermissionMatchConditionSchema: z.ZodType<PermissionMatchCondition>;
+/** Individual permission schema */
+export declare const PermissionSchema: z.ZodEffects<z.ZodObject<{
+    tool: z.ZodString;
+    matches: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<PermissionMatchCondition, z.ZodTypeDef, PermissionMatchCondition>>>;
+    action: z.ZodEnum<["allow", "reject", "ask", "delegate"]>;
+    context: z.ZodOptional<z.ZodEnum<["thread", "subagent"]>>;
+    to: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    tool: string;
+    action: "allow" | "reject" | "ask" | "delegate";
+    matches?: Record<string, PermissionMatchCondition> | undefined;
+    context?: "thread" | "subagent" | undefined;
+    to?: string | undefined;
+}, {
+    tool: string;
+    action: "allow" | "reject" | "ask" | "delegate";
+    matches?: Record<string, PermissionMatchCondition> | undefined;
+    context?: "thread" | "subagent" | undefined;
+    to?: string | undefined;
+}>, {
+    tool: string;
+    action: "allow" | "reject" | "ask" | "delegate";
+    matches?: Record<string, PermissionMatchCondition> | undefined;
+    context?: "thread" | "subagent" | undefined;
+    to?: string | undefined;
+}, {
+    tool: string;
+    action: "allow" | "reject" | "ask" | "delegate";
+    matches?: Record<string, PermissionMatchCondition> | undefined;
+    context?: "thread" | "subagent" | undefined;
+    to?: string | undefined;
+}>;
+/** Permission */
+export type Permission = z.infer<typeof PermissionSchema>;
+/** Permissions list */
+export type PermissionsList = Permission[];
+/** MCP server configuration schema */
 export declare const MCPServerSchema: z.ZodObject<{
     command: z.ZodString;
     args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -151,6 +198,7 @@ export declare const MCPServerSchema: z.ZodObject<{
     args?: string[] | undefined;
     env?: Record<string, string> | undefined;
 }>;
+/** MCP configuration schema */
 export declare const MCPConfigSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
     command: z.ZodString;
     args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -164,6 +212,11 @@ export declare const MCPConfigSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
     args?: string[] | undefined;
     env?: Record<string, string> | undefined;
 }>>;
+/** MCP server configuration */
+export type MCPServer = z.infer<typeof MCPServerSchema>;
+/** MCP configuration object */
+export type MCPConfig = z.infer<typeof MCPConfigSchema>;
+/** Configuration options for Amp execution schema */
 export declare const AmpOptionsSchema: z.ZodObject<{
     cwd: z.ZodOptional<z.ZodString>;
     dangerouslyAllowAll: z.ZodOptional<z.ZodBoolean>;
@@ -187,6 +240,37 @@ export declare const AmpOptionsSchema: z.ZodObject<{
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     continue: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>;
     toolbox: z.ZodOptional<z.ZodString>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
+        tool: z.ZodString;
+        matches: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<PermissionMatchCondition, z.ZodTypeDef, PermissionMatchCondition>>>;
+        action: z.ZodEnum<["allow", "reject", "ask", "delegate"]>;
+        context: z.ZodOptional<z.ZodEnum<["thread", "subagent"]>>;
+        to: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tool: string;
+        action: "allow" | "reject" | "ask" | "delegate";
+        matches?: Record<string, PermissionMatchCondition> | undefined;
+        context?: "thread" | "subagent" | undefined;
+        to?: string | undefined;
+    }, {
+        tool: string;
+        action: "allow" | "reject" | "ask" | "delegate";
+        matches?: Record<string, PermissionMatchCondition> | undefined;
+        context?: "thread" | "subagent" | undefined;
+        to?: string | undefined;
+    }>, {
+        tool: string;
+        action: "allow" | "reject" | "ask" | "delegate";
+        matches?: Record<string, PermissionMatchCondition> | undefined;
+        context?: "thread" | "subagent" | undefined;
+        to?: string | undefined;
+    }, {
+        tool: string;
+        action: "allow" | "reject" | "ask" | "delegate";
+        matches?: Record<string, PermissionMatchCondition> | undefined;
+        context?: "thread" | "subagent" | undefined;
+        to?: string | undefined;
+    }>, "many">>;
 }, "strict", z.ZodTypeAny, {
     env?: Record<string, string> | undefined;
     cwd?: string | undefined;
@@ -202,6 +286,13 @@ export declare const AmpOptionsSchema: z.ZodObject<{
     }> | undefined;
     continue?: string | boolean | undefined;
     toolbox?: string | undefined;
+    permissions?: {
+        tool: string;
+        action: "allow" | "reject" | "ask" | "delegate";
+        matches?: Record<string, PermissionMatchCondition> | undefined;
+        context?: "thread" | "subagent" | undefined;
+        to?: string | undefined;
+    }[] | undefined;
 }, {
     env?: Record<string, string> | undefined;
     cwd?: string | undefined;
@@ -217,18 +308,19 @@ export declare const AmpOptionsSchema: z.ZodObject<{
     }> | undefined;
     continue?: string | boolean | undefined;
     toolbox?: string | undefined;
+    permissions?: {
+        tool: string;
+        action: "allow" | "reject" | "ask" | "delegate";
+        matches?: Record<string, PermissionMatchCondition> | undefined;
+        context?: "thread" | "subagent" | undefined;
+        to?: string | undefined;
+    }[] | undefined;
 }>;
-/** User input message for streaming conversations */
-export type UserInputMessage = z.infer<typeof UserInputMessageSchema>;
-/** MCP server configuration */
-export type MCPServer = z.infer<typeof MCPServerSchema>;
-/** MCP configuration object */
-export type MCPConfig = z.infer<typeof MCPConfigSchema>;
-/** Configuration options for Amp CLI execution */
+/** Configuration options for Amp execution */
 export type AmpOptions = z.infer<typeof AmpOptionsSchema>;
 /** Input type for prompts - either a string or streaming user messages */
 type PromptInput = string | AsyncIterable<UserInputMessage>;
-/** Options for executing Amp CLI commands */
+/** Options for executing Amp commands */
 export interface ExecuteOptions {
     prompt: PromptInput;
     options?: AmpOptions;

package/dist/types.js

@@ -5,8 +5,9 @@
  */
 import { z } from 'zod';
 // ============================================================================
-// Validation Schemas (defined to derive interfaces from)
+// User Message Schemas & Types
 // ============================================================================
+/** User input message schema */
 export const UserInputMessageSchema = z.object({
     type: z.literal('user'),
     message: z.object({
@@ -17,6 +18,59 @@ export const UserInputMessageSchema = z.object({
         })),
     }),
 });
+/** Permission match condition for tool arguments schema */
+export const PermissionMatchConditionSchema = z.lazy(() => z.union([
+    z.string().describe('Pattern match where "*" matches any number of any characters'),
+    z.array(PermissionMatchConditionSchema).min(1).describe('OR match of each entry'),
+    z.boolean().describe('A literal boolean match'),
+    z.number().describe('A literal number match'),
+    z.null().describe('A literal null match'),
+    z.undefined().describe('A literal undefined match'),
+    z
+        .record(z.string(), PermissionMatchConditionSchema)
+        .describe('Matching individual keys of an object'),
+]));
+/** Individual permission schema */
+export const PermissionSchema = z
+    .object({
+    tool: z.string().min(1).describe('The name of the tool to which this entry applies'),
+    matches: z
+        .record(z.string(), PermissionMatchConditionSchema)
+        .optional()
+        .describe('Maps tool inputs to conditions'),
+    action: z
+        .enum(['allow', 'reject', 'ask', 'delegate'])
+        .describe('How Amp should proceed in case of a match'),
+    context: z
+        .enum(['thread', 'subagent'])
+        .optional()
+        .describe('Only apply this entry in this context'),
+    to: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Command to delegate to when action is "delegate"'),
+})
+    .superRefine((data, ctx) => {
+    if (data.action === 'delegate' && !data.to) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'delegate action requires "to" field',
+            path: ['to'],
+        });
+    }
+    if (data.action !== 'delegate' && data.to) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: '"to" field only allowed with delegate action',
+            path: ['to'],
+        });
+    }
+});
+// ============================================================================
+// MCP Schemas & Types
+// ============================================================================
+/** MCP server configuration schema */
 export const MCPServerSchema = z.object({
     command: z.string().describe('Command to run the MCP server'),
     args: z.array(z.string()).describe('Arguments for the MCP server command').optional(),
@@ -25,9 +79,14 @@ export const MCPServerSchema = z.object({
         .describe('Environment variables for the server')
         .optional(),
 });
+/** MCP configuration schema */
 export const MCPConfigSchema = z
     .record(z.string(), MCPServerSchema)
     .describe('MCP server configurations keyed by server name');
+// ============================================================================
+// Execute Schemas & Types
+// ============================================================================
+/** Configuration options for Amp execution schema */
 export const AmpOptionsSchema = z
     .object({
     cwd: z.string().describe('Current working directory').optional(),
@@ -59,6 +118,10 @@ export const AmpOptionsSchema = z
         .describe('Continue the most recent thread (true) or a specific thread by ID (string)')
         .optional(),
     toolbox: z.string().describe('Folder path with toolbox scripts').optional(),
+    permissions: z
+        .array(PermissionSchema)
+        .describe('Permission rules for tool usage')
+        .optional(),
 })
     .strict();
 //# sourceMappingURL=types.js.map

package/package.json

@@ -4,7 +4,7 @@
     "email": "amp-devs@sourcegraph.com"
   },
   "dependencies": {
-    "@sourcegraph/amp": "0.0.1760450761-g0908c3",
+    "@sourcegraph/amp": "latest",
     "zod": "^3.23.8"
   },
   "description": "TypeScript SDK for Amp CLI - Build custom AI agents with Amp's capabilities",
@@ -44,12 +44,12 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.1.0-20251014155204-ge7f0f28",
+  "version": "0.1.0-20251020161918-gf8ab86d",
   "scripts": {
     "build": "pnpm exec tsc -b",
     "dev": "pnpm exec tsc -b --watch",
     "clean": "rm -rf dist tsconfig.tsbuildinfo",
-    "examples:basic": "pnpm run build && bun run examples/basic-usage.ts",
+    "examples:basic": "pnpm run build && bun run examples/basic.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "pin-cli-version": "bun run scripts/pin-cli-version.ts"