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 exposes two surfaces:

  • KlockClient for embedded, in-process coordination
  • KlockHttpClient for a local or remote Klock server

Installation

npm install @klock-protocol/core

Embedded Client

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...');
    }
  }
}

HTTP Client

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

const klock = new KlockHttpClient({ baseUrl: 'http://localhost:3100' });
await klock.registerAgent('bot-alpha', 100);

For localhost workflows, KlockHttpClient can auto-start the local server when it can find a launch command.

Disable auto-start with:

  • KLOCK_DISABLE_AUTOSTART=1
  • new KlockHttpClient({ autoStart: false })

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 or use KlockHttpClient to talk to it.

const klock = new KlockClient()