@cdmbase/cdecli-agent-client

TypeScript client for the cdecli-agent Go HTTP server.

Ships in the same repo as the agent server (src/serve/cdecli_exec.go) so the wire protocol and client move together — every protocol change lands as one PR.

Install

yarn add @cdmbase/cdecli-agent-client
# optional: enable HTTP keep-alive on Node
yarn add undici

Why

A thin, dependency-light wrapper around the cdecli-agent wire protocol (POST /v1/cdecli/exec). Owns the sentinel parser, auth header logic, and credential-key picker so callers don't re-implement them.

Layers

CdecliAgentClient       ← transport (fetch + headers + JSON)
    │
    ├─ CdecliConnectorClient    ← cdecli connector run/install/list/actions
    ├─ CdecliAgentRunnerClient  ← cdecli agent -m … (CDE-Agent)
    └─ CdecliSearchClient       ← cdecli connector search …

Usage

import {
    CdecliAgentClient,
    CdecliConnectorClient,
} from '@cdmbase/cdecli-agent-client';

const transport = new CdecliAgentClient({
    endpoint: process.env.CDECLI_AGENT_ENDPOINT ?? 'https://your-cdecli-agent.example.com',
});
const connectors = new CdecliConnectorClient(transport);

const result = await connectors.runAction({
    userToken: userJwt,            // bearer for per-user $HOME isolation
    connector: 'github',
    action: 'GITHUB_LIST_ISSUES',
    params: { repo: 'owner/repo' },
    credentialId: 'fb-cred-id',    // optional vault lookup
});

if (result.successful) {
    console.log(result.data);
} else {
    console.error(result.error);
}

Wire contract

Matches src/serve/cdecli_exec.go::ExecRequest in this repo. Accepts either args (argv) or shell_command (POSIX line). Response shape is { stdout, stderr, exit_code, error? }.

Drift policy: every change to the Go ExecRequest / ExecResponse struct in src/serve/cdecli_exec.go must update src/types.ts in the same PR.

HTTP keep-alive

On Node, the default fetchImpl uses a process-wide undici.Agent (connections: 128, keepAliveTimeout: 30s) shared across all tenants. JWTs and session ids live in per-request headers, so pooling is safe.

Disable with CDECLI_AGENT_KEEPALIVE=0.

Development

cd packages/cdecli-agent-client
yarn install
yarn build
yarn test

This package is standalone — not part of any workspace. It pulls its own node_modules and is published independently of the Go binary.