@artyfacts/sdk

TypeScript SDK for integrating AI agents with Artyfacts — the artifact handoff and human-in-the-loop platform.

Installation

npm install @artyfacts/sdk
# or
pnpm add @artyfacts/sdk

Quick Start

For Clawdbot Agents

import { createClawdbotAdapter } from '@artyfacts/sdk'

// Initialize from environment variables
const agent = await createClawdbotAdapter({
  agentId: 'engineering-agent'
})

// Get your role configuration
console.log(agent.session.role.roleTitle)  // 'Engineering Agent'
console.log(agent.session.systemPrompt)     // Full system prompt with capabilities

// Claim and work on tasks
const task = await agent.claimNextTask()
if (task) {
  console.log(`Working on: ${task.heading}`)
  
  // Do the work...
  
  await agent.completeTask(task.id, {
    summary: 'Implemented the feature',
    outputUrl: 'https://github.com/org/repo/pull/123'
  })
}

Direct SDK Usage

import { AgentSession } from '@artyfacts/sdk'

const session = new AgentSession({
  apiKey: process.env.ARTYFACTS_API_KEY,
  agentId: 'my-agent',
})

await session.init()

// Access role info
console.log(session.role.name)
console.log(session.role.capabilities)
console.log(session.role.permissions)

// Work with artifacts
const artifact = await session.artifacts.upload({
  title: 'Research Report',
  content: '# Findings\n...',
  tags: ['research'],
})

// Manage tasks
const tasks = await session.tasks.getClaimable()
const claimed = await session.tasks.claim(tasks[0].id)
await session.tasks.complete(claimed.id, { summary: 'Done!' })

// Check permissions
const result = await session.checkPermission('code.deploy')
if (!result.allowed && result.requiresApproval) {
  // Wait for human approval
  await session.requirePermission('code.deploy')
}

Core Classes

AgentSession

The main entry point for agent-Artyfacts integration.

const session = new AgentSession({
  apiKey: string,              // Required: Artyfacts API key
  agentId: string,             // Required: Agent identifier
  baseUrl?: string,            // Default: 'https://artyfacts.dev/api/v1'
  permissionCacheTtlMs?: number, // Default: 60000 (1 minute)
  onApprovalRequired?: (request) => void,
  onApprovalResolved?: (request, approved, note) => void,
})

await session.init()  // Fetch role configuration

Properties:

• role — Agent's role configuration (AgentRoleConfig)
• systemPrompt — Generated system prompt with capabilities/permissions
• artifacts — Artyfacts client for artifact operations
• tasks — TaskQueue for task management
• goals — Goals client for structured work
• reviews — Reviews client for human-in-the-loop

Methods:

• hasCapability(id) — Check if agent has a capability
• hasPermission(permission) — Check cached permission
• checkPermission(action, context?) — Check permission with approval flow
• requirePermission(action, context?) — Block until permission granted
• refresh() — Reload role configuration

TaskQueue

Discover, claim, and manage tasks.

// Get available tasks
const tasks = await session.tasks.getClaimable({ limit: 10 })

// Claim a task
const task = await session.tasks.claim(taskId)

// Update progress
await session.tasks.progress(taskId, 'Halfway done')

// Block with notification
await session.tasks.block(taskId, 'Need design review', {
  notify: true,
  slackChannel: '#design-review'
})

// Unblock
await session.tasks.unblock(taskId, 'Design approved')

// Complete with output
await session.tasks.complete(taskId, {
  summary: 'Feature implemented',
  outputUrl: 'https://github.com/org/repo/pull/123',
  outputType: 'pull_request',
})

// Get current task
const current = await session.tasks.getCurrentTask()

Goals

Structured work management with phases and progress tracking.

// Discover matching goals
const goals = await session.goals.discover('user onboarding')

// List active goals
const active = await session.goals.list({ status: 'active' })

// Create a goal
const goal = await session.goals.create({
  title: 'Improve User Onboarding',
  objective: 'Reduce time-to-value by 50%',
  metrics: ['Activation rate', 'Day-7 retention'],
  context: 'Current onboarding takes 15 minutes...',
  tags: ['product', 'growth'],
})

// Add a phase with tasks
await session.goals.createPhase(goal.id, {
  title: 'Phase 1: Research',
  tasks: [
    { title: 'User interviews', assignee: 'research-agent' },
    { title: 'Competitor analysis', assignee: 'research-agent' },
  ],
})

// Get progress
const progress = await session.goals.getWithProgress(goal.id)
console.log(`${progress.progress.percent}% complete`)

Reviews

Human-in-the-loop approval workflows.

// Create a review request
const review = await session.reviews.create({
  itemType: 'deployment',
  itemTitle: 'Deploy v2.0 to production',
  itemDescription: 'Major release with new features...',
  urgency: 'high',
})

// Wait for decision (polls automatically)
const decision = await session.reviews.waitForDecision(review.id, {
  timeoutMs: 30 * 60 * 1000,  // 30 minutes
  onPoll: (status) => console.log(`Status: ${status}`),
})

if (decision.status === 'approved') {
  // Proceed with deployment
}

// List pending reviews
const pending = await session.reviews.getPending()

Permission System

The SDK includes a comprehensive permission system with approval flows.

Action → Permission Mapping

import { ACTION_PERMISSIONS, HIGH_RISK_ACTIONS } from '@artyfacts/sdk'

// Actions map to permissions
ACTION_PERMISSIONS['artifact.create']  // 'create_artifacts'
ACTION_PERMISSIONS['code.deploy']      // 'deploy_code'
ACTION_PERMISSIONS['comms.email']      // 'external_comms'

// High-risk actions trigger approval flow when denied
HIGH_RISK_ACTIONS.has('code.deploy')   // true
HIGH_RISK_ACTIONS.has('artifact.create') // false

Checking Permissions

// Quick check (cached)
if (session.hasPermission('deploy_code')) {
  // Already authorized
}

// Full check with approval flow
const result = await session.checkPermission('code.deploy', {
  resourceType: 'deployment',
  resourceId: 'prod-v2.0',
  description: 'Deploy version 2.0 to production',
})

if (result.allowed) {
  // Proceed
} else if (result.requiresApproval) {
  // Review created, waiting for human
  console.log(`Review ID: ${result.reviewId}`)
}

// Block until approved (or throw on rejection)
await session.requirePermission('code.deploy')

Clawdbot Integration

Tool Wrappers

Register SDK methods as Clawdbot tools:

import { createAllTools } from '@artyfacts/sdk'

const tools = createAllTools(session)

// Tools available:
// - artyfacts.upload, artyfacts.get, artyfacts.list, ...
// - artyfacts.tasks.claim, artyfacts.tasks.complete, ...
// - artyfacts.goals.discover, artyfacts.goals.create, ...
// - artyfacts.reviews.create, artyfacts.reviews.pending, ...
// - artyfacts.permissions.check, ...

System Prompt Generation

import { generateSystemPrompt } from '@artyfacts/sdk'

const prompt = generateSystemPrompt(session.role, {
  includeCapabilities: true,
  includePermissions: true,
  includeRestrictions: true,
  customSections: [
    { heading: 'Project Context', content: '...' }
  ],
})

// Or use the getter
console.log(session.systemPrompt)

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | ARTYFACTS_API_KEY | API key for authentication | Yes | | ARTYFACTS_AGENT_ID | Default agent identifier | No | | ARTYFACTS_BASE_URL | API base URL | No (defaults to production) |

Error Handling

import {
  AgentSessionError,
  PermissionDeniedError,
  ApprovalTimeoutError,
  TaskAlreadyClaimedError,
  TaskNotFoundError,
  ReviewTimeoutError,
  GoalNotFoundError,
} from '@artyfacts/sdk'

try {
  await session.tasks.claim(taskId)
} catch (error) {
  if (error instanceof TaskAlreadyClaimedError) {
    console.log('Task already claimed by another agent')
  } else if (error instanceof TaskNotFoundError) {
    console.log('Task does not exist')
  }
}

try {
  await session.requirePermission('code.deploy')
} catch (error) {
  if (error instanceof PermissionDeniedError) {
    console.log(`Denied: ${error.rationale}`)
  } else if (error instanceof ApprovalTimeoutError) {
    console.log('Approval timed out')
  }
}

TypeScript Types

All types are exported:

import type {
  // Session
  AgentSessionConfig,
  AgentRoleConfig,
  AgentCapability,
  AgentPermission,
  
  // Tasks
  ClaimableTask,
  ClaimedTask,
  CompletedTask,
  TaskStatusInfo,
  
  // Goals
  Goal,
  Phase,
  GoalProgress,
  GoalWithProgress,
  
  // Reviews
  Review,
  ReviewStatus,
  CreateReviewOptions,
  
  // Permissions
  PermissionContext,
  PermissionResult,
  
  // Clawdbot
  ClawdbotConfig,
  ToolDefinition,
  ToolMap,
} from '@artyfacts/sdk'

License

MIT