@positive-skew/headless

Shared adapter-agnostic core for Positive Skew headless clients.

Version 0.4.0 is published on npm and pairs with CLI 0.5.0 and MCP 0.4.0. Requires Node.js 22+; this package is for Node integrations.

Install and read a scoped snapshot

npm install --save-exact @positive-skew/[email protected]

First authorize a separate profile using CLI 0.5.0: pskew profile create agent, then pskew agent signin. Save this example as snapshot.mjs and run it with PSKEW_PROFILE=agent node snapshot.mjs:

import { createAgentClient, HeadlessError } from '@positive-skew/headless';

try {
  const snapshot = await createAgentClient().snapshot();
  console.log(JSON.stringify(snapshot, null, 2));
} catch (error) {
  if (!(error instanceof HeadlessError)) throw error;
  console.error(error.message);
  process.exitCode = 1;
}

The snapshot contains account identifier/mode, selected strategy settings and simulated paper cash/equity. Treat returned account data as private. The profile uses the same OS-backed encrypted storage as the CLI and MCP. An expired, revoked or uncertain-refresh grant requires fresh browser authorization.

API and compatibility

Import named exports from @positive-skew/headless; avoid internal dist/ paths. TypeScript declarations ship with the package.

| Export group | Purpose | | --- | --- | | createAgentClient, AgentSnapshot | Scoped account reads, grant exchange/refresh/revocation | | Profile/session functions | Shared encrypted configuration and profile lifecycle | | authedClient, strategy/account helpers | Full-owner integrations; unavailable to scoped profiles | | HeadlessError | Structured failures for adapters to translate | | Telemetry helpers | Optional owner-client request headers |

This is a pre-1.0 API. Pin an exact version, review release notes, and validate your integration before upgrading. Full-owner helpers can perform account mutations; they are not the restricted agent surface.

Consumed by:

• @positive-skew/cli — terminal CLI
• @positive-skew/mcp — MCP stdio server

What's in here

• Session/config storage (PSKEW_PROFILE, atomic session writes)
• Embedded production Supabase defaults + explicit PSKEW_SUPABASE_* override resolution
• Telemetry header builder
• Secure browser PKCE/state callback and opaque agent capability client
• Separate issuer-bound agent-capability profiles, one-use refresh rotation, and a dedicated snapshot API (never Supabase Auth SDK restoration)
• Web brokerage-connect handoff without email or predictable OAuth state in URLs
• Edge-function invocation + structured error mapping
• Typed error contract (HeadlessError)

What's NOT in here

• process.exit / argv parsing / Commander
• MCP SDK / tool schemas
• Console output / human-readable formatting
• Adapter-specific behavior drift (e.g. pskew pipeline run waiting strategy, --since defensive filters)

Adapters (CLI, MCP) translate HeadlessError instances into their own surface: exit codes for CLI, structured tool results for MCP.

Capability sessions are encrypted with the same OS-backed storage as owner profiles but cannot enter owner SDK paths. They expose only account:read, expire after at most seven days, and stop on owner revocation or logout of the authorizing browser session. Refresh attempts are durably marked pending before the network call; uncertain outcomes require fresh authorization and never silently replay an old refresh token. Profile updates use compare-and-swap under the filesystem lock to prevent concurrent CLI/MCP refreshes losing credentials.

License

MIT — Copyright (c) 2026 Burak Yenigun.