@ddse/acm-sdk

Core types and abstract classes for the ACM v0.5 Node.js Framework.

Overview

The SDK package provides the foundational types and interfaces that all other ACM packages build upon. It's designed to be minimal, with zero dependencies beyond Node.js built-ins.

Installation

pnpm add @ddse/acm-sdk

What's Included

Abstract Classes

Tool<I, O>: Base class for atomic operations
Task<I, O>: Base class for logical task units
CapabilityRegistry: Interface for task registries
ToolRegistry: Interface for tool registries

Types

Goal: Represents user intent
Context: Immutable facts for planning
Plan: Task graph with edges and guards
TaskSpec: Task configuration
LedgerEntry: Memory ledger entry
PolicyDecision: Authorization result
RunContext: Execution context passed to tasks

Utilities

DefaultStreamSink: Stream multiplexer for real-time updates
PolicyEngine: Interface for policy decision points

Usage

Defining a Tool

import { Tool } from '@ddse/acm-sdk';

export class MyTool extends Tool<{ input: string }, { output: string }> {
  name(): string {
    return 'my-tool';
  }

  async call(input: { input: string }): Promise<{ output: string }> {
    // Your implementation
    return { output: `Processed: ${input.input}` };
  }
}

Defining a Task

import { Task, type RunContext } from '@ddse/acm-sdk';

export class MyTask extends Task<{ query: string }, { result: any }> {
  constructor() {
    super('my-task-id', 'my-capability');
  }

  async execute(ctx: RunContext, input: { query: string }): Promise<{ result: any }> {
    const tool = ctx.getTool('my-tool');
    if (!tool) throw new Error('Tool not found');
    
    const result = await tool.call({ input: input.query });
    return { result };
  }

  // Optional: for idempotency
  idemKey(ctx: RunContext, input: { query: string }): string {
    return `my-task:${input.query}`;
  }

  // Optional: for policy evaluation
  policyInput(ctx: RunContext, input: { query: string }): Record<string, unknown> {
    return { query: input.query, userId: ctx.context.facts.userId };
  }

  // Optional: for verification
  verification(): string[] {
    return ['output.result !== undefined'];
  }
}

Implementing Registries

import { CapabilityRegistry, ToolRegistry, type Capability, type Task, type Tool } from '@ddse/acm-sdk';

export class MyCapabilityRegistry extends CapabilityRegistry {
  private tasks = new Map<string, Task>();
  private capabilities = new Map<string, Capability>();

  register(capability: Capability, task: Task): void {
    this.capabilities.set(capability.name, capability);
    this.tasks.set(capability.name, task);
  }

  list(): Capability[] {
    return Array.from(this.capabilities.values());
  }

  has(name: string): boolean {
    return this.capabilities.has(name);
  }

  resolve(name: string): Task | undefined {
    return this.tasks.get(name);
  }

  inputSchema(name: string): unknown | undefined {
    return this.capabilities.get(name)?.inputSchema;
  }

  outputSchema(name: string): unknown | undefined {
    return this.capabilities.get(name)?.outputSchema;
  }
}

Using Streaming

import { DefaultStreamSink } from '@ddse/acm-sdk';

const stream = new DefaultStreamSink();

// Attach listeners
stream.attach('task', (update) => {
  console.log('Task update:', update);
});

stream.attach('planner', (chunk) => {
  if (chunk.delta) {
    process.stdout.write(chunk.delta);
  }
});

// Emit events
stream.emit('task', { taskId: 't1', status: 'running' });
stream.emit('planner', { delta: 'Generating plan...' });

// Clean up
stream.close('task');

Type Reference

Goal

type Goal = {
  id: string;
  intent: string;
  constraints?: Record<string, any>;
};

Context

type Context = {
  id: string;
  facts: Record<string, any>;
  version?: string;
};

Plan

type Plan = {
  id: string;
  contextRef: string;
  capabilityMapVersion: string;
  tasks: TaskSpec[];
  edges: PlanEdge[];
  join?: 'all' | 'any';
  alternatives?: string[];
  rationale?: string;
};

TaskSpec

type TaskSpec = {
  id: string;
  capability: string;
  input?: any;
  retry?: {
    attempts: number;
    backoff: 'fixed' | 'exp';
    baseMs?: number;
    jitter?: boolean;
  };
  verification?: string[];
};

ACM v0.5 Mapping

This package implements the core abstractions from ACM v0.5:

Goal: Section 2.1
Capability: Section 2.3
Task: Section 2.4
Tool: Section 2.5
Context: Section 4
Plan: Section 5.4

License

Apache-2.0