@executespec/core

Shared TypeScript client library for ExecuteSpec.

It provides the typed REST/SSE client, browser-login and PAT helpers, agent-session primitives, provider/model policy helpers, and the guarded local tool runtime used by ExecuteSpec clients. The backend—not this package—owns the agent loop, prompts, routing, scoring, billing, and run history.

This package does not contain or publish the ExecuteSpec VS Code extension or a VSIX.

Requirements

• Node.js 20 or newer
• ESM

Install

npm install @executespec/core

Usage

import {createClient, resolveConfig} from '@executespec/core';

const config = resolveConfig();
const client = createClient({
  host: config.host,
  token: process.env.EXECUTESPEC_TOKEN,
});

const me = await client.getMe();

The default backend is https://dev.executespec.ai. Consumers can override it with EXECUTESPEC_HOST, stored client configuration, or an explicit host option.

client.getPublicationEligibility(runId) returns the backend's read-only publication decision. getPublicationEligibility, getReport, and getCost accept optional request options so terminal clients can impose bounded evidence-read deadlines without changing their response contracts. Its typed evidence contract keeps deterministic build, tests, workflows, protected contracts, reviewer result and route, correction diff, workspace freshness, and effective execution route separate. Clients must not infer eligibility from task completion or a score. Correction action types retain the server-bounded unified patch, capture/full-byte counts, truncation/redaction markers, and the deterministic before/after validation delta. Validation ledger rows are also typed so clients can display an exact score-zero-cause row without deriving a cause from nearby build, test, or reviewer facts. Run details distinguish the physically observed reviewer model from its configured model, mark whether test counts came from verified execution, and carry workflow plus validation-workspace freshness fields for honest fallback rendering. Terminal run details may include a server-owned terminalOutcome. Consumers should accept it only after parseRunTerminalOutcome validates the exact v1 contract, then prefer its customer copy, impact, next action, support code, and automation exit code to forensic failure fields. The CLI also cross-checks the outcome category against the durable terminal status. Missing, malformed, future, or contradictory outcomes are unverified: terminal clients suppress forensic reasons and fail closed instead of inferring success from the legacy status alone.

Security boundary

The caller owns token storage, workspace selection, user approval, and local tool authority. Do not enable local tools without an explicit approver and a trusted working tree. The backend remains authoritative for authentication, authorization, provider/model admission, plan gates, and run state.

Exact-plan approval helpers hash the persisted plan bytes; consumers must fail closed when those bytes or required confirmation context are absent. Local tool helpers apply path, secret, and command safeguards, but callers must still review effects and handle failures conservatively.

Documentation and support

• CLI and client documentation
• Issue tracker

Responsible use and license

Use only with systems, repositories, and data you are authorized to access. Do not use this package to bypass safeguards, exfiltrate data, violate third-party rights, or cause unlawful harm. Proprietary software. All rights reserved. Use is subject to the included license and applicable ExecuteSpec terms. Provided without warranties to the maximum extent permitted by law.