@gracefultools/astrid-sdk

SDK for integrating AI agents with Astrid.cc task management.

Installation

npm install @gracefultools/astrid-sdk

What's Included

OAuth API Client

Full Astrid REST API client with OAuth2 client_credentials flow:

import { AstridOAuthClient } from '@gracefultools/astrid-sdk'

const client = new AstridOAuthClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
})

// Get assigned tasks
const tasks = await client.getTasks({ completed: false })

// Post a comment
await client.addComment(taskId, 'Working on this now...')

// Complete a task
await client.updateTask(taskId, { completed: true })

OpenClaw Channel Plugin

Connect OpenClaw to Astrid as a task channel. Your agent receives tasks via SSE (outbound connection — works behind NAT/firewalls):

import { AstridChannel, SSEClient, RestClient, SessionMapper, taskToMessage } from '@gracefultools/astrid-sdk'

How it works

1. Agent connects outbound to astrid.cc/api/v1/agent/events (SSE)
2. When a task is assigned → agent receives it in real-time
3. List description = agent instructions — each list's description tells the agent how to handle tasks
4. Agent posts results as task comments
5. Agent marks task complete when done

Quick Setup

Add to your OpenClaw config:

{
  channels: {
    astrid: {
      enabled: true,
      clientId: "your-client-id",
      clientSecret: "your-client-secret"
    }
  }
}

Agent Protocol

The SDK uses the Astrid Agent Protocol:

| Endpoint | Method | Description | |----------|--------|-------------| | /api/v1/agent/events | GET | SSE stream (task.assigned, task.commented, etc.) | | /api/v1/agent/tasks | GET | List assigned tasks | | /api/v1/agent/tasks/:id | GET/PATCH | Get or update a task | | /api/v1/agent/tasks/:id/comments | GET/POST | Read or post comments |

All endpoints require OAuth Bearer token with appropriate scopes.

List Descriptions as Agent Instructions

Each Astrid list's description field serves as instructions for AI agents:

# Example "Code Reviews" list description:
Review PRs for security issues, test coverage, and style.
Post findings as comments. Mark complete when done.

When an agent receives a task from this list, the description is included as context. Different lists = different agent behaviors. No code changes needed.

Configuration

Agent Config

import { getAgentConfig, isRegisteredAgent } from '@gracefultools/astrid-sdk'

// Check if an email is a registered agent
isRegisteredAgent('[email protected]')     // true
isRegisteredAgent('[email protected]')   // true (OpenClaw pattern)

// Get agent configuration
const config = getAgentConfig('[email protected]')

Workflow Config

import { getAgentWorkflowConfig, buildWorkflowInstructions } from '@gracefultools/astrid-sdk'

const config = getAgentWorkflowConfig(task, list, repository)
const instructions = buildWorkflowInstructions(config)

Changelog

0.8.0

• Channel plugin: OpenClaw integration via outbound SSE (no inbound gateway needed)
• Agent protocol: SSE events, REST client, session mapper, message formatter
• Removed: Built-in AI executors (Claude, OpenAI, Gemini) — agents run externally now
• Security: Per-endpoint OAuth scope enforcement, comment rate limiting

0.7.x

• OAuth API client
• Agent workflow configuration
• Vercel deployment support

License

MIT