TypeScript SDK

npm install @protolabsai/sdk

import { query } from '@protolabsai/sdk';
 
const session = query({
  prompt: 'What files are in the current directory?',
  options: { cwd: '/path/to/project' },
});
 
for await (const message of session) {
  if (message.type === 'assistant') {
    console.log('Assistant:', message.message.content);
  } else if (message.type === 'result') {
    console.log('Done:', message.result);
    break;
  }
}

async function* conversation() {
  yield { type: 'human', content: 'Analyse the project structure' };
  yield { type: 'human', content: 'Write a summary to README.md' };
}
 
const session = query({ prompt: conversation() });
for await (const msg of session) { ... }

const session = query({
  prompt: 'Fix all failing tests',
  options: { permissionMode: 'auto-edit' },
});

const session = query({
  prompt: '...',
  options: {
    canUseTool: async (toolName, toolInput) => {
      if (toolName === 'run_shell_command') {
        return { behavior: 'ask' }; // always prompt for shell
      }
      return { behavior: 'allow' };
    },
  },
});

import { query, type SubagentConfig } from '@protolabsai/sdk';
 
const reviewer: SubagentConfig = {
  name: 'code-reviewer',
  description: 'Reviews code for bugs and security issues',
  systemPrompt: 'You are a code reviewer...',
  level: 'session',
  tools: ['read_file', 'glob', 'grep_search'],
  modelConfig: { model: 'claude-sonnet-4-6' },
};
 
const session = query({
  prompt: 'Review the changes in the current branch',
  options: { agents: [reviewer] },
});

import { query, type HookCallback } from '@protolabsai/sdk';
 
const securityGate: HookCallback = async (input) => {
  const data = input as {
    tool_name?: string;
    tool_input?: Record<string, unknown>;
  };
  if (data.tool_name === 'Bash') {
    const cmd = String(data.tool_input?.command ?? '');
    if (cmd.includes('rm -rf')) {
      return { shouldSkip: true, message: 'Blocked' };
    }
  }
  return {};
};
 
const session = query({
  prompt: '...',
  options: { hookCallbacks: { PreToolUse: [securityGate] } },
});

const controller = new AbortController();
const session = query({
  prompt: '...',
  options: { abortController: controller },
});
 
setTimeout(() => controller.abort(), 30_000);
for await (const msg of session) { ... }

const session = query({
  prompt: 'Fix all type errors in src/',
  options: { lsp: true, permissionMode: 'auto-edit' },
});

const session = query({
  prompt: 'Query the database for recent errors',
  options: {
    mcpServers: {
      db: {
        command: 'python',
        args: ['-m', 'db_mcp_server'],
        env: { DB_URL: process.env.DB_URL },
      },
    },
  },
});