{"_id":"@agent-ruler/agent-sdk","name":"@agent-ruler/agent-sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agent-ruler/agent-sdk","version":"0.1.0","description":"AgentRuler SDK — AgentLoop core with Node.js backend adapter, permission system, and full toolbar settings API.","keywords":["agent","mcp","llm","ai","agent-loop","tools","permissions"],"homepage":"https://github.com/agent-ruler/agent-sdk","bugs":{"url":"https://github.com/agent-ruler/agent-sdk/issues"},"license":"MIT","author":{"name":"AgentRuler Team"},"main":"./dist/index.cjs","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.mjs"},"require":{"types":"./dist/index.d.ts","default":"./dist/index.cjs"}}},"engines":{"node":">=18.0.0"},"scripts":{"build":"tsup","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit","prepublishOnly":"npm run lint && npm run test && npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.26.0"},"devDependencies":{"@types/node":"^22.0.0","tsup":"^8.0.0","typescript":"^5.7.0","vitest":"^3.0.0"},"_id":"@agent-ruler/agent-sdk@0.1.0","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-wUCT78W6o2QNpNkFE/7fQFptcuH9CAMzPluRF+GnDn2zcvTqLUcXBylqxCj9X96iCrOivXYr7jj5qSdlk0QMcA==","shasum":"9324b12b38a169247c4d83ec80fe5776387b1e63","tarball":"https://registry.npmjs.org/@agent-ruler/agent-sdk/-/agent-sdk-0.1.0.tgz","fileCount":8,"unpackedSize":736721,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDxLDz2Zj9ETVD3dwNN78JMaLZqGFQFIiZ4y5o7vnbKowIhAK633EBpoIQl7esCzpIBS84sehp8fTGKsYCP9ts9ZOSH"}]},"_npmUser":{"name":"kirigaya","email":"1193466151@qq.com"},"directories":{},"maintainers":[{"name":"peacesheep","email":"peacesheep@qq.com"},{"name":"kirigaya","email":"1193466151@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-sdk_0.1.0_1778148832127_0.45091279637222415"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-07T10:13:51.740Z","0.1.0":"2026-05-07T10:13:52.327Z","modified":"2026-05-07T10:13:52.505Z"},"maintainers":[{"name":"peacesheep","email":"peacesheep@qq.com"},{"name":"kirigaya","email":"1193466151@qq.com"}],"description":"AgentRuler SDK — AgentLoop core with Node.js backend adapter, permission system, and full toolbar settings API.","homepage":"https://github.com/agent-ruler/agent-sdk","keywords":["agent","mcp","llm","ai","agent-loop","tools","permissions"],"author":{"name":"AgentRuler Team"},"bugs":{"url":"https://github.com/agent-ruler/agent-sdk/issues"},"license":"MIT","readme":"# @agent-ruler/agent-sdk\n\nAgentRuler SDK — A production-grade agent loop with Node.js backend, permission system, and full toolbar settings API.\n\n## Features\n\n- **AgentLoop** — Platform-agnostic ReAct loop with streaming and callback APIs\n- **NodeBackendAdapter** — Full Node.js backend: MCP clients, LLM streaming, bash, file I/O, web tools\n- **Permission Engine** — Identity-based access control with presets (Admin / Maintainer / Reader / Guest)\n- **Toolbar Settings API** — Programmatic control of all chat settings: mode, thinking, temperature, tools, skills, permissions\n- **MCP Support** — STDIO, SSE, and Streamable HTTP transports\n- **Dual Module** — ESM + CJS with TypeScript declarations\n\n## Installation\n\n```bash\nnpm install @agent-ruler/agent-sdk\n```\n\n## Quick Start\n\n```typescript\nimport { AgentSDK } from '@agent-ruler/agent-sdk';\n\nconst sdk = new AgentSDK();\n\n// Configure LLM\nsdk.setDefaultLLM({\n  baseURL: 'https://api.openai.com/v1',\n  apiToken: process.env.OPENAI_API_KEY!,\n  model: 'gpt-4o',\n});\n\n// Configure MCP servers\nsdk.loadMcpConfig({\n  mcpServers: {\n    filesystem: {\n      command: 'npx',\n      args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],\n    },\n  },\n  defaultLLM: {\n    baseURL: 'https://api.openai.com/v1',\n    apiToken: process.env.OPENAI_API_KEY!,\n    model: 'gpt-4o',\n  },\n});\n\n// Simple invocation\nconst answer = await sdk.ainvoke({ messages: 'List files in /tmp' });\nconsole.log(answer);\n```\n\n## Toolbar Settings API\n\nAll chat toolbar settings are fully configurable via the SDK:\n\n### Agent Loop Mode\n```typescript\nsdk.setAgentLoopMode('chat');   // Pure conversation\nsdk.setAgentLoopMode('agent');  // Tool-enhanced (default)\nsdk.setAgentLoopMode('plan');   // Planning mode (reserved)\n```\n\n### Thinking Mode\n```typescript\nsdk.setThinking(true, 'high');  // Enable with effort level\nsdk.setThinking(false);         // Disable\n// effort: 'low' | 'medium' | 'high' | 'max'\n```\n\n### Temperature\n```typescript\nsdk.setTemperature(0.7);  // 0.0 – 2.0, defaults to 0.6\n```\n\n### Parallel Tool Calls\n```typescript\nsdk.setParallelToolCalls(true);   // Default\nsdk.setParallelToolCalls(false);\n```\n\n### XML Wrapper\n```typescript\nsdk.setXmlWrapper(true);\n```\n\n### System Prompt\n```typescript\nsdk.setSystemPrompt('You are a senior TypeScript engineer.');\n```\n\n### Tool Management\n```typescript\nsdk.setToolEnabled('Bash', true);\nsdk.setToolEnabled('WebSearch', false);\nsdk.setAllToolsEnabled(true);\n```\n\n### Skill Management\n```typescript\nsdk.setSkillEntries([\n  { id: 'my-skill', enabled: true },\n]);\nsdk.enableSkill('my-skill', false);\n```\n\n### Defer Loading\n```typescript\nsdk.setDeferLoading(true);   // MCP tools deferred by default\nsdk.setDeferLoading(false);\n```\n\n## Permission System\n\n### Preset Identities\n```typescript\nsdk.setPresetIdentity('admin');       // Full access\nsdk.setPresetIdentity('maintainer');  // Elevated with restrictions\nsdk.setPresetIdentity('reader');      // Read-only\nsdk.setPresetIdentity('guest');       // Minimal access\n```\n\n### Custom Permissions\n```typescript\nsdk.setPermissionProfile({\n  presetId: 'maintainer',\n  toolOverrides: {\n    Bash: { enabled: true },\n    Agent: { enabled: false },\n  },\n  resourceOverrides: [\n    { resourceType: 'file', pathPattern: '/secrets/**', actions: ['read'], effect: 'deny' },\n  ],\n  workingDirectory: '/project',\n  allowSandboxEscapeWithConsent: true,\n});\n\nsdk.overrideToolPermission('Bash', false);\nsdk.setWorkingDirectory('/project');\nsdk.setSandboxEscapeConsent(true);\n```\n\n## Streaming\n\n```typescript\nconst stream = sdk.stream({ messages: 'Explain quantum computing' });\n\nfor await (const event of stream) {\n  switch (event.type) {\n    case 'stream_event':\n      process.stdout.write(event.event.choices[0]?.delta.content ?? '');\n      break;\n    case 'tool_call':\n      console.log('Tool:', event.toolCall.function?.name);\n      break;\n    case 'tool_result':\n      console.log('Result:', event.result.content);\n      break;\n    case 'done':\n      console.log('\\nTokens:', event.consumption);\n      break;\n  }\n}\n```\n\n## Sub-Agents\n\n```typescript\nconst result = await sdk.runSubAgent(\n  'Explore codebase',\n  'Find all uses of the deprecated API',\n  {\n    model: 'gpt-4o-mini',\n    onProgress: (progress) => {\n      console.log(`Steps: ${progress.stepCount}, Tools: ${progress.toolUseCount}`);\n    },\n  }\n);\nconsole.log(result.output);\n```\n\n## Low-Level AgentLoop\n\nFor advanced use cases, use `AgentLoop` directly:\n\n```typescript\nimport { AgentLoop, NodeBackendAdapter } from '@agent-ruler/agent-sdk';\n\nconst adapter = new NodeBackendAdapter();\nconst loop = new AgentLoop(adapter);\n\nloop.setLlmConfig({\n  baseUrl: 'https://api.openai.com/v1',\n  userToken: 'sk-...',\n  userModel: 'gpt-4o',\n});\n\nconst storage = await loop.createStorage();\n\nloop.registerOnChunk((chunk) => {\n  console.log(chunk.choices[0]?.delta.content);\n});\n\nawait loop.start(storage, 'Hello');\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-1c73bc5f46e0d8ccb7d4e3a31e941b0c"}