Toolshed

Toolshed is the integration and tool management layer for the ShellApps ecosystem. It manages connections between services and provides a tool registry that Norman agents use to discover and execute capabilities.

What Toolshed Does

• Integration management — Connect external services (GitHub, Slack, APIs) to ShellApps
• Tool registry — Register, discover, and version tools that agents can call
• Execution layer — Securely execute tools on behalf of users with proper auth scoping
• Connection lifecycle — Handle OAuth flows, API keys, and token refresh for integrations

Architecture

┌─────────────┐     ┌──────────┐     ┌──────────────────┐
│ Norman Agent │ ──▶ │ Toolshed │ ──▶ │ External Service │
│ (RapidStack) │     │          │     │ (GitHub, Slack)  │
└─────────────┘     │  Registry │     └──────────────────┘
                    │  + Auth   │
                    └──────────┘

1. RapidStack agents request a tool via Toolshed
2. Toolshed resolves the tool, checks permissions, and handles auth
3. The tool executes against the external service
4. Results return to the agent

Tool Types

Quick Example

// Register a tool
await toolshed.register({
  name: 'github.create-issue',
  description: 'Create a GitHub issue',
  parameters: {
    repo: { type: 'string', required: true },
    title: { type: 'string', required: true },
    body: { type: 'string' },
  },
  integration: 'github',
});
 
// Execute a tool (typically called by an agent)
const result = await toolshed.execute('github.create-issue', {
  repo: 'shellapps/experience',
  title: 'Bug: page not loading',
  body: 'Steps to reproduce...',
});

Related

• API Reference — Tool registration and execution endpoints
• RapidStack — Agent orchestration that uses Toolshed
• Auth — Permission scoping for tool execution