sdk

JavaScript / TypeScript SDK

Use the Klock OS Kernel from Node.js with Native Bindings.

The @klock-protocol/core package provides fully typed TypeScript access to Klock. It uses napi-rs to bind directly to the Rust kernel, bypassing v8 serialization limits for sub-microsecond lease acquisition.

Installation

npm install @klock-protocol/core

Basic Usage

import { KlockClient } from '@klock-protocol/core';

async function runAgent() {
  const klock = new KlockClient();
  
  // Register your agent with a priority (older = higher priority/lower number)
  klock.registerAgent('bot-alpha', 100);
  
  // Attempt to acquire an exclusive lock to mutate auth.ts
  const rawResult = klock.acquireLease(
    'bot-alpha', 
    'session-xyz', 
    'FILE', 
    '/src/auth.ts', 
    'MUTATES', 
    60000 // TTL in ms
  );
  
  const result = JSON.parse(rawResult);
  
  if (result.success) {
    console.log(`Lease acquired! Lease ID: ${result.lease_id}`);
    
    try {
      // Execute your agent's task here
      await rewriteAuthLogic();
      
    } finally {
      // ALWAYS release, even on failures
      klock.releaseLease(result.lease_id);
    }
  } else {
    // Wait-Die logic kicks in
    if (result.reason === 'DIE') {
      console.log(`Aborting. Please wait and retry in ${result.wait_time}ms`);
    } else {
      console.log('Queued for processing. Awaiting lease...');
    }
  }
}

Standalone Client vs Server

By default, initializing new KlockClient() boots an embedded in-memory kernel in your active Node.js thread.

If you want a centralized coordination service, run the separate klock-cli executable and call its REST API from your application. The current JavaScript SDK exposes the embedded client surface only.

const klock = new KlockClient()