ACK-Lab SDK Development Assistant

Expert assistant for working with the ACK-Lab SDK codebase - a TypeScript SDK for secure agent-to-agent (A2A) authentication and communication on the ACK-Lab platform.

What This Skill Does

This skill helps you work effectively with the ACK-Lab SDK by:

Instructions

Understanding the Codebase

When asked about the project structure or architecture:

1. Explain that this is an ESM-only TypeScript SDK built with `tsdown`

2. Describe the core structure:

- `src/index.ts` - Main export exposing `AckLabSdk` class

- `src/sdk.ts` - Core SDK implementation with agent caller and request handler factories

- `src/core/` - API client, handshake protocol, and type definitions

- `src/utils/` - Challenge generation and SHA-256 hashing utilities

- `src/demo/` - Example implementations of A2A communication patterns

3. Highlight the key components:

- **AckLabSdk**: Main SDK class providing high-level APIs

- `createAgentCaller(url)`: Creates functions for calling remote agents with automatic authentication

- `createRequestHandler(agentFn)`: Creates handlers for processing authenticated requests

- Automatically handles cryptographic handshake protocol

- **ApiClient**: HTTP client for ACK-Lab platform API with JWT-based authentication

- **HandshakeClient**: Manages multi-step cryptographic handshake protocol

- **Challenge utilities**: Generate and verify random challenges for security

4. Note the key dependencies:

- `agentcommercekit` - Agent commerce and DID resolution

- `jose` - JWT and cryptographic operations

- `valibot` - Schema validation

- `uuid` - Challenge generation

- `safe-stable-stringify` - Deterministic JSON serialization

Development Workflow

When working on features or fixes:

1. **Before making changes**, run checks to understand current state:

```bash

pnpm check:types

pnpm check:lint

pnpm test

```

2. **During development**:

- Use `pnpm format` to format code with Prettier

- Use `pnpm lint:fix` to auto-fix linting issues

- Run `pnpm build` to verify the build works

- Run `pnpm test` frequently to ensure tests pass

3. **Before completing work**, run full checks:

```bash

pnpm check

```

This runs format, lint, types, publint, and tests in one command.

4. **Testing the demo**:

```bash

pnpm demo

```

This showcases agent-to-agent communication patterns.

Building and Testing

When asked to build or test:

1. **Build the SDK**:

```bash

pnpm build

```

- Uses `tsdown` for TypeScript to ESM compilation

- Outputs to `dist/` with separate type definitions

- Single entry point at `src/index.ts`

2. **Run tests**:

```bash

pnpm test

```

- Uses Vitest with pass-through configuration

- For watch mode, run `vitest` directly

3. **Type checking**:

```bash

pnpm check:types

```

Implementing Agent-to-Agent Communication

When helping implement A2A patterns:

1. Direct users to the demo directory (`src/demo/`) for reference implementations

2. Explain the basic pattern:

- Use `sdk.createAgentCaller(url)` to create a caller function

- Use `sdk.createRequestHandler(agentFn)` to handle incoming requests

- The SDK automatically manages the cryptographic handshake

3. Emphasize that authentication and security are handled automatically by the SDK

4. Show how to structure agent functions that can be called remotely

Code Quality

When reviewing or writing code:

1. Ensure TypeScript types are properly defined

2. Use Valibot schemas for runtime validation where appropriate

3. Follow ESM module conventions (`"type": "module"`)

4. Maintain the existing code style (use Prettier and ESLint)

5. Add tests for new functionality using Vitest

6. Keep the single entry point architecture (`src/index.ts`)

Common Tasks

**Adding new features**:

1. Implement in appropriate directory (`src/core/`, `src/utils/`, etc.)

2. Export from `src/index.ts` if public API

3. Add tests in corresponding test file

4. Update types and validation schemas

5. Run `pnpm check` before completing

**Fixing bugs**:

1. Write a failing test that reproduces the issue

2. Implement the fix

3. Verify the test passes

4. Run full check suite

5. Test with demo if applicable

**Updating dependencies**:

1. Check for breaking changes in key dependencies

2. Update code if needed

3. Run full test suite

4. Verify build output

Examples

Running the development workflow

```bash

Check current state

pnpm check:types && pnpm test

Make changes, then format and fix

pnpm format && pnpm lint:fix

Build and test

pnpm build && pnpm test

Run all checks before committing

pnpm check

```

Testing the demo

```bash

Run the addition demo

pnpm demo

```

Important Notes