@cutie-crypto/connector-core

Cutie Connector core protocol + connection runtime + PlatformAdapter contract.

Node.js only. Uses node:http / node:https / node:url / Buffer.

What this package gives you

• Protocol envelopes: TaskPush / HelloOk / HeartbeatAck / ServerMessage / RegisterResult / TaskResultMessage
• HTTP client: register(serverUrl, RegisterParams) / fetchStrategyKnowledge(serverUrl, token) / buildFormData / post / get
• Connection runtime: ConnectorConnection class — WS loop / heartbeat / task dispatch / upgrade trigger
• Adapter contract: CorePlatformAdapter<C> — 6 methods you implement to plug a new platform

How to write a new adapter

import type {
  CorePlatformAdapter,
  AgentResult,
  SafetyTemplates,
} from '@cutie-crypto/connector-core';

interface MyConfig {
  endpoint: string;
}

export class EchoAdapter implements CorePlatformAdapter<MyConfig> {
  readonly id = 'echo';
  private config: MyConfig | null = null;

  attachConfig(config: MyConfig): void {
    this.config = config;
  }

  async callAgent(message: string, _model: string): Promise<AgentResult> {
    return { answer: `echo: ${message}`, latency_ms: 1 };
  }

  async selfUpgrade(_targetVersion: string): Promise<void> {
    // No-op. Real adapter would: download new version, replace binary,
    // process.exit(0) to let supervisor (systemd / PM2 / Zylos) restart.
  }

  augmentHeartbeat(envelope: Record<string, unknown>): Record<string, unknown> {
    return envelope;
  }

  getCapabilities(): string[] {
    return [];
  }

  applySafetyTemplates(_templates: SafetyTemplates): void {
    // OpenClaw / Hermes write to workspace files.
    // CLI-style adapters (Claude / Codex) cache here, splice into prompt later.
  }
}

The 8 design constraints (Phase 0.2)

These are the contracts connector-core upholds so any adapter (OpenClaw, Hermes, future Claude / Codex CLI integration) plugs in without touching core:

1. AI call abstraction: adapter.callAgent(message, model) → {answer, latency_ms}. Core does not assume HTTP / CLI.
2. Config layering: top-level holds shared fields; platform-specific config is the generic C parameter on CorePlatformAdapter<C>. Each adapter sees only its own config type.
3. Safety template dispatch: adapter.applySafetyTemplates({agents_md, soul_md, canary_token?}) — core delivers what server's register returns; adapter decides how to land it (file vs cache). Called only after pairing/setup succeeds.
4. Self-upgrade: adapter.selfUpgrade(targetVersion) — adapter chooses install method. Core does not hardcode npm install.
5. Process management: core does not assume systemd / PM2 / launchd. Adapter's selfUpgrade typically process.exit(0) to let supervisor restart.
6. Unified agent_status: core builds heartbeat with agent_status; adapter's augmentHeartbeat adds backward-compat fields (e.g. openclaw_status mirroring agent_status).
7. README + dummy adapter: see the compilable EchoAdapter example above in How to write a new adapter.
8. Capability flags: register form / heartbeat envelope carry optional capabilities: string[]. Adapter returns [] today; future adapters declare e.g. ['sandbox=srt', 'runtime=claude'].

When to call applySafetyTemplates

Only after register HTTP response returns templates. Never during install / post-install hooks — there's no pair_token yet, so the templates haven't been generated by Cutie Server.

Runtime requirements

Node.js >= 18.