TuringPulse TypeScript SDK

Decorator-driven instrumentation for Node/TypeScript runtimes. Drop it into any service to publish telemetry to the Agent Observability Service, raise governance workflows (HITL/HATL/HOTL) inside the Agent PM Service, and register hidden entrypoints that can be triggered without an HTTP surface.

Framework Compatibility

| Framework | Version | Node 18 | Node 20 | Node 22 | |---|---| --- | --- | --- | | Mistral | 1.15.1 | pass | pass | pass |

Highlights

• init(config) bootstraps SDK defaults (base URLs, tenant headers, tracing, governance fallbacks, fetch implementation).
• @instrument(...) works on class methods (NestJS, controllers, workers) while withInstrumentation(fn, opts) wraps standalone functions.
• Decorator options control tracing, custom labels/metadata, manual trigger keys, governance policies, KPI definitions, and hidden entrypoints.
• Automatic OpenTelemetry spans + rich metadata; emits AgentEvent payloads that match the shared @turingpulse/interfaces schema.
• Trigger registry lets you invoke hidden agents via getInstance().triggerAgent('hidden:sync_rag', args) even when no endpoint exists.

Install

pnpm add @turingpulse/sdk @turingpulse/interfaces
# or npm/yarn equivalent

Local workspace dev:

cd packages/turingpulse-sdk
pnpm install
pnpm build

Quickstart

import { init, instrument, GovernanceDirective, KPIConfig } from '@turingpulse/sdk';

init({
  apiKey: process.env.TP_API_KEY!,
  workflowName: 'My Workflow',
  redactFields: ['password', 'apiKey', 'secret'],
});

const governance = new GovernanceDirective({ hitl: true, reviewers: ['[email protected]'] });
const throughputKpi = { kpiId: 'items_processed', fromResultPath: 'count', comparator: 'lt', alertThreshold: 1 };

class MarketScanner {
  @instrument({
    agentId: 'agent-research',
    operation: 'market_scan',
    labels: { surface: 'slack' },
    governance,
    kpis: [throughputKpi],
    triggerKey: 'hidden.market_scan',
    hiddenEntrypoint: true,
  })
  async run(query: string) {
    // ... do work ...
    return { count: 3, items: [] };
  }
}

Manual trigger:

import { getInstance } from '@turingpulse/sdk';

await getInstance().triggerAgent('hidden.market_scan', 'pricing updates');

Wrap standalone functions:

import { withInstrumentation } from '@turingpulse/sdk';

const handler = withInstrumentation(
  async (payload: Payload) => {
    return service.process(payload);
  },
  { agentId: 'agent-worker', operation: 'ingest_payload' },
);

Decorator Options

| Option | Description | | --- | --- | | agentId | Required Agent identifier | | operation | Logical name; defaults to method name | | labels / metadata | Merged with global defaults and sent to traces + AgentEvent metadata | | trace | Enable/disable tracing at the decorator level | | triggerKey | Registers the method for manual invocation | | hiddenEntrypoint | Marks calls as UI-hidden; metadata includes agent.hidden_entrypoint | | governance | GovernanceDirective describing HITL/HATL/HOTL behaviour | | kpis | Array of KPIConfig to emit metrics + alert metadata |

Governance

GovernanceDirective controls reviewer queues, escalation channels, severity, and auto-escalation timers. When enabled, the plugin creates tasks in the Agent PM Service per mode (HITL/HATL/HOTL) and attaches KPI metadata for downstream auditors.

KPI Mapping & Alerts

• useDuration derives KPI values from observed runtime (ms).
• fromResultPath pulls nested properties from the returned payload.
• value can be a literal number or (ctx) => number.
• When alertThreshold + comparator trip, metadata includes metric.alert.<id>=true.

Security

The SDK includes built-in protections to ensure safe operation in customer environments:

Endpoint Validation

• SSRF protection: Private/internal IP ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, localhost, [::1]) are blocked as endpoints.
• CRLF injection prevention: Newline and null characters are stripped from API keys and endpoint URLs.
• TLS enforcement: The SDK emits a warning if an http:// endpoint is used instead of https://.

Data Protection

• Sensitive field redaction: Use redactFields in config to mask sensitive keys before telemetry leaves your environment.
• Error sanitization: Error messages in telemetry do not leak stack traces or internal paths.
• No content truncation: The SDK does not truncate or limit content size — backend handles that.

init({
  apiKey: 'sk_...',
  workflowName: 'My Workflow',
  redactFields: ['password', 'apiKey', 'secret', 'token', 'authorization'],
});

Network Safety

• Retry-After compliance: The SDK respects Retry-After headers from 429 responses.
• No retry on terminal errors: 401, 402, 403, 404 responses stop retries immediately.
• Timeout cap: HTTP timeout is capped at 120 seconds.

UUID Generation

• Uses crypto.randomUUID() when available, falls back to crypto.getRandomValues() for better entropy than Math.random().

Fingerprinting & Change Detection

The SDK automatically captures workflow fingerprints to enable root cause analysis when anomalies or drifts are detected. This works out-of-the-box with zero configuration.

How It Works

1. The SDK automatically detects LLM calls (OpenAI, Anthropic, LangChain, etc.)
2. Prompts and configurations are hashed for change detection
3. Workflow structure (nodes and edges) is tracked
4. Fingerprints are sent to the backend after each run
5. When anomalies occur, changes are correlated for root cause attribution

Configuration

import { init } from '@turingpulse/sdk';

init({
  apiKey: 'sk_...',
  workflowName: 'My Workflow',
  fingerprint: {
    enabled: true,              // Master switch (default: true)
    capturePrompts: true,       // Hash prompts for change detection
    captureConfigs: true,       // Hash configs for change detection
    captureStructure: true,     // Track DAG structure
    sensitiveConfigKeys: [      // Keys to redact before hashing
      'apiKey', 'password', 'secret', 'token'
    ],
    sendAsync: true,            // Send fingerprints asynchronously
    sendOnFailure: true,        // Send even if run fails
  },
});

Deploy Tracking

Register deployments to correlate anomalies with code changes:

import { registerDeploy } from '@turingpulse/sdk';

// Auto-detect from CI/CD environment (GitHub Actions, GitLab CI, etc.)
await registerDeploy({
  workflowId: 'chat-assistant',
  autoDetect: true,
});

// Or provide explicit values
await registerDeploy({
  workflowId: 'chat-assistant',
  version: 'v1.2.3',
  gitSha: process.env.GIT_SHA,
  commitMessage: process.env.GIT_COMMIT_MSG,
});

Supported CI/CD environments for auto-detection:

• GitHub Actions
• GitLab CI
• CircleCI
• Jenkins
• Azure DevOps
• Bitbucket Pipelines
• Travis CI

Roadmap

• Browser-friendly fetch adapter
• Extended decorators for parameter injection + custom trace attributes
• CLI helper for listing/triggering hidden entrypoints