@timemachine-sdk/sdk

const tm = new TimeMachine({
  apiKey: 'tm_...',          // required
  baseUrl: 'https://...',   // default: https://api.timemachine.dev
  maxRetries: 3,             // default: 3 (exponential backoff)
  debug: false,              // default: false
});

const execution = await tm.startExecution({
  name: 'my-agent-run',
  metadata: { model: 'gpt-4o', version: '1.2.0' },
});

const step = execution.step('llm_call', {
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello' }],
});

await execution.complete();

await execution.fail(new Error('LLM returned invalid JSON'));
// or
await execution.fail('Rate limited by OpenAI');

const status = execution.getStatus();
// 'running' | 'completed' | 'failed'

await step.complete({
  output: { response: 'Here is the answer...' },
  tokensIn: 150,
  tokensOut: 300,
  cost: 0.0045,
  latencyMs: 1200,   // auto-calculated if omitted
  toolCalls: [
    { name: 'web_search', input: { query: 'news' }, output: { results: [...] } }
  ],
  stateSnapshot: {
    agentState: { memory: [...], plan: [...] },
  },
});

await step.fail(new Error('API timeout'));

step.getStatus(); // 'running' | 'completed' | 'failed'
step.getIndex();  // 0-based index in execution sequence

# npm
npm install @timemachine-sdk/sdk

# bun
bun add @timemachine-sdk/sdk

# pnpm
pnpm add @timemachine-sdk/sdk

export TIMEMACHINE_API_KEY="tm_your-api-key-here"
export TIMEMACHINE_BASE_URL="https://app.timemachinesdk.dev"  # or http://localhost:3000

node --input-type=module -e "
  import { installClaudeCodeHooks } from '@timemachine-sdk/sdk/claude-code-installer';
  const result = await installClaudeCodeHooks({
    projectDir: process.cwd(),
    scope: 'local'
  });
  console.log(result);
"

TIMEMACHINE_API_KEY="tm_your_project_key"
TIMEMACHINE_BASE_URL="https://app.timemachinesdk.dev"

#!/bin/bash
set -a
source "$(dirname "$0")/.env"
set +a
exec node "$(dirname "$0")/timemachine-bridge.mjs" "$@"

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/.claude/hooks/timemachine-bridge.mjs"
          }
        ]
      }
    ]
  }
}

import { runClaudeCodeHookBridge } from '@timemachine-sdk/sdk/claude-code-bridge';

runClaudeCodeHookBridge().catch((error) => {
  console.error('[TimeMachine][ClaudeCodeBridge]', error);
  process.exitCode = 1;
});

# Check hooks are configured
cat .claude/settings.local.json | python3 -m json.tool | grep -c '"hooks"'

# Check environment variables
echo $TIMEMACHINE_API_KEY    # should start with tm_
echo $TIMEMACHINE_BASE_URL   # should be your server URL

# Test the API key
curl -s -H "Authorization: Bearer $TIMEMACHINE_API_KEY" \
  $TIMEMACHINE_BASE_URL/api/v1/executions | head -c 200

# Run a session — then check your dashboard
claude

.claude/settings.local.json    # Hook configuration (11 events)
.claude/hooks/.env             # API key + base URL (gitignored)
.claude/hooks/run-bridge.sh    # Shell wrapper — sources .env, runs node
.claude/hooks/timemachine-bridge.mjs  # Entrypoint — imports SDK bridge

~/.timemachine/claude-code/    # Session state (auto-cleaned on SessionEnd)
  <session-id>.json            # Maps session → executionId

# Install SDK
bun add @timemachine-sdk/sdk

# Set env vars
export TIMEMACHINE_API_KEY="tm_..."
export TIMEMACHINE_BASE_URL="https://app.timemachinesdk.dev"

# Install hooks (automatic)
node --input-type=module -e "
  import { installClaudeCodeHooks } from '@timemachine-sdk/sdk/claude-code-installer';
  await installClaudeCodeHooks({ projectDir: process.cwd(), scope: 'local' });
"

# Verify — run a session, check dashboard
claude

{
  "mcpServers": {
    "timemachine": {
      "command": "npx",
      "args": ["-y", "@timemachine-sdk/mcp"],
      "env": {
        "TIMEMACHINE_API_KEY": "tm_...",
        "TIMEMACHINE_PROJECT_ID": "proj_...",
        "TIMEMACHINE_BASE_URL": "https://app.timemachinesdk.dev"
      }
    }
  }
}

npm install -g @timemachine-sdk/cli
# or run without installing:
npx @timemachine-sdk/cli --help

tm config set --api-key tm_... --project-id proj_...

# Or use environment variables:
export TIMEMACHINE_API_KEY=tm_...
export TIMEMACHINE_PROJECT_ID=proj_...

# 1. See what failed
tm failed

# 2. Inspect the trace
tm view exec_abc123

# 3. Fork at the broken step and replay
tm fork exec_abc123 --at 4 --replay

# 4. Watch the replay live
tm tail exec_def456

import { TimeMachine } from '@timemachine-sdk/sdk';

const tm = new TimeMachine({ apiKey: process.env.TIMEMACHINE_API_KEY! });

const suite = await tm.createEvalSuite({
  name: 'Customer Support Quality',
  description: 'Verify response accuracy, tone, and latency',
  agentEndpoint: 'https://your-api.com/agent',
  tags: ['production', 'support'],
});

// Add test cases
await tm.addEvalCase(suite.id, {
  input: { message: 'How do I reset my password?' },
  expectedOutput: { contains: 'reset link' },
  tags: ['auth'],
});

await tm.addEvalCase(suite.id, {
  input: { message: 'Cancel my subscription' },
  tags: ['billing'],
});

# Run a suite and wait for results
tm eval run suite_abc123 --wait

# Run with a minimum pass threshold (CI use-case)
tm eval run suite_abc123 --wait --threshold 0.9

# Check status of a previous run
tm eval status run_def456

# List recent runs
tm eval list suite_abc123

await tm.addEvalCase(suite.id, {
  input: { query: 'Summarise this article in 3 bullet points.' },
  assertions: [
    // Output must contain bullet points
    { type: 'contains', value: '•' },
    // Graded by LLM on conciseness + accuracy
    {
      type: 'llm_judge',
      rubric: 'Does the response contain exactly 3 concise bullet points that accurately summarise the article?',
      threshold: 0.8,
    },
    // Must complete within 5s and under $0.02
    { type: 'latency_under', maxLatencyMs: 5000 },
    { type: 'cost_under', maxCost: 0.02 },
  ],
});

name: Eval Suite

on:
  pull_request:
    branches: [main]
  workflow_dispatch:

jobs:
  evals:
    name: Run eval suite
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run eval suite (threshold 0.9)
        env:
          TIMEMACHINE_API_KEY: ${{ secrets.TIMEMACHINE_API_KEY }}
        run: |
          npx @timemachine-sdk/cli eval run ${{ vars.EVAL_SUITE_ID }} \
            --wait \
            --threshold 0.9

      # Optional: post score as PR comment
      - name: Post eval score
        if: always()
        env:
          TIMEMACHINE_API_KEY: ${{ secrets.TIMEMACHINE_API_KEY }}
          GH_TOKEN: ${{ github.token }}
        run: |
          SCORE=$(npx @timemachine-sdk/cli eval status --latest --format score)
          gh pr comment ${{ github.event.pull_request.number }} \
            --body "**Eval score:** ${SCORE} / 1.0"

# Trigger a run via API
RUN=$(curl -s -X POST \
  -H "Authorization: Bearer $TIMEMACHINE_API_KEY" \
  -H "Content-Type: application/json" \
  https://app.timemachinesdk.dev/api/v1/eval/suites/$SUITE_ID/runs)

RUN_ID=$(echo $RUN | jq -r '.id')

# Poll until terminal
while true; do
  STATUS=$(curl -s \
    -H "Authorization: Bearer $TIMEMACHINE_API_KEY" \
    https://app.timemachinesdk.dev/api/v1/eval/runs/$RUN_ID/status)

  STATE=$(echo $STATUS | jq -r '.status')
  SCORE=$(echo $STATUS | jq -r '.score')

  [ "$STATE" = "completed" ] && break
  [ "$STATE" = "failed" ] && exit 1
  sleep 5
done

# Fail if below threshold
awk "BEGIN { exit ($SCORE < 0.9) }" || exit 1

import { createLangChainHandler } from '@timemachine-sdk/sdk/adapters';

const { handler, execution } = await createLangChainHandler(tm, {
  name: 'research-agent',
  metadata: { model: 'gpt-4o' },
  debug: false,
  autoCalculateCost: true,
  maxDocumentLength: 500,
});

await agent.invoke(input, { callbacks: [handler] });
await execution.complete();

import { TimeMachine } from '@timemachine-sdk/sdk';

const tm = new TimeMachine({
  apiKey: process.env.TIMEMACHINE_API_KEY!,
  // No changes needed — configure OpenRouter in your LLM client directly
});

// Use OpenRouter as your LLM provider
import OpenAI from 'openai';

const openrouter = new OpenAI({
  apiKey: process.env.OPENROUTER_API_KEY!,
  baseURL: 'https://openrouter.ai/api/v1',
  defaultHeaders: {
    'HTTP-Referer': 'https://your-app.com',   // optional, for rankings
    'X-Title': 'Your App Name',               // optional
  },
});

const execution = await tm.startExecution({
  name: 'openrouter-agent',
  metadata: { router: 'openrouter' },
});

const step = execution.step('llm_call', {
  model: 'anthropic/claude-opus-4',   // OpenRouter model ID
  messages: [{ role: 'user', content: 'Explain quantum entanglement' }],
});

const response = await openrouter.chat.completions.create({
  model: 'anthropic/claude-opus-4',
  messages: [{ role: 'user', content: 'Explain quantum entanglement' }],
});

await step.complete({
  output: { message: response.choices[0].message.content },
  tokensIn: response.usage?.prompt_tokens,
  tokensOut: response.usage?.completion_tokens,
});

await execution.complete();

import { ChatOpenAI } from '@langchain/openai';
import { createLangChainHandler } from '@timemachine-sdk/sdk/adapters';

const model = new ChatOpenAI({
  modelName: 'google/gemini-2.5-pro',   // or any OpenRouter model
  openAIApiKey: process.env.OPENROUTER_API_KEY!,
  configuration: {
    baseURL: 'https://openrouter.ai/api/v1',
  },
});

const { handler, execution } = await createLangChainHandler(tm, {
  name: 'gemini-via-openrouter',
});

// All LLM calls automatically captured
const result = await model.invoke('What is the latest news?', {
  callbacks: [handler],
});

await execution.complete();

import {
  calculateCost,
  hasModelPricing,
  getModelPricing,
  normalizeModelName,
  configureFallbackPricing,
  extractTokensFromLLMResult,
} from '@timemachine-sdk/sdk/utils';

// Calculate cost for known models
const cost = calculateCost('gpt-4o', 1000, 500);
// => 0.00625 (USD)

// Check model pricing availability
hasModelPricing('gpt-4o');          // true
hasModelPricing('my-custom-model'); // false

// Get pricing details
getModelPricing('gpt-4o');
// => { inputPer1k: 0.005, outputPer1k: 0.015 }

// Normalize model names (strips version suffixes)
normalizeModelName('gpt-4-0125-preview');    // 'gpt-4'
normalizeModelName('claude-3-sonnet-20240229'); // 'claude-3-sonnet'

// Configure fallback pricing for unknown models
configureFallbackPricing({
  inputPer1k: 0.002,
  outputPer1k: 0.006,
  enabled: true,
});

// Extract tokens from LLM results (multi-provider)
const { tokensIn, tokensOut } = extractTokensFromLLMResult(llmResult);

import { TimeMachine } from '@timemachine-sdk/sdk';

const tm = new TimeMachine({ apiKey: process.env.TIMEMACHINE_API_KEY! });

async function runAgent(query: string) {
  const execution = await tm.startExecution({
    name: 'research-agent',
    metadata: { query, timestamp: Date.now() },
  });

  try {
    // Step 1: Plan
    const planStep = execution.step('decision', { action: 'plan', query });
    const plan = await generatePlan(query);
    await planStep.complete({ output: { plan } });

    // Step 2: Search
    const searchStep = execution.step('tool_use', {
      tool: 'web_search',
      query: plan.searchQuery,
    });
    const results = await webSearch(plan.searchQuery);
    await searchStep.complete({
      output: { resultCount: results.length, results },
    });

    // Step 3: Synthesize
    const llmStep = execution.step('llm_call', {
      model: 'gpt-4o',
      context: results,
    });
    const answer = await callLLM(query, results);
    await llmStep.complete({
      output: { answer },
      tokensIn: answer.usage.prompt_tokens,
      tokensOut: answer.usage.completion_tokens,
    });

    await execution.complete();
    return answer;
  } catch (error) {
    await execution.fail(error as Error);
    throw error;
  }
}

const execution = await tm.startExecution({ name: 'multi-step-workflow' });

// Step 1: Classify the request
const classifyStep = execution.step('llm_call', { action: 'classify' });
const category = await classifyRequest(userInput);
await classifyStep.complete({ output: { category } });

// Step 2: Route based on classification
const routeStep = execution.step('decision', { category });
const handler = selectHandler(category);
await routeStep.complete({ output: { handler: handler.name } });

// Step 3+: Conditional execution
if (category === 'needs_research') {
  const retrieveStep = execution.step('retrieval', { query: userInput });
  const docs = await vectorStore.similaritySearch(userInput);
  await retrieveStep.complete({ output: { documentCount: docs.length } });

  const answerStep = execution.step('llm_call', { model: 'gpt-4o', context: docs });
  const answer = await generateAnswer(userInput, docs);
  await answerStep.complete({
    output: { answer },
    tokensIn: 2000,
    tokensOut: 500,
  });
}

await execution.complete();

const execution = await tm.startExecution({ name: 'agent-run' });

try {
  const step = execution.step('tool_use', { tool: 'database_query' });
  const result = await queryDatabase(sql);
  await step.complete({ output: { rows: result.length } });

  await execution.complete();
} catch (error) {
  // Records the error in Time Machine for debugging
  await execution.fail(error as Error);
  throw error;
}

// Enable debug mode to see SDK activity in your console
const tm = new TimeMachine({
  apiKey: process.env.TIMEMACHINE_API_KEY!,
  debug: true,  // Logs all SDK requests and errors
});

import express from 'express';
import { TimeMachine } from '@timemachine-sdk/sdk';

const app = express();
const tm = new TimeMachine({ apiKey: process.env.TIMEMACHINE_API_KEY! });

app.post('/api/chat', async (req, res) => {
  const execution = await tm.startExecution({
    name: 'chat-endpoint',
    metadata: {
      userId: req.body.userId,
      sessionId: req.body.sessionId,
    },
  });

  try {
    const step = execution.step('llm_call', {
      model: 'gpt-4o',
      messages: req.body.messages,
    });

    const response = await openai.chat.completions.create({
      model: 'gpt-4o',
      messages: req.body.messages,
    });

    await step.complete({
      output: { message: response.choices[0].message },
      tokensIn: response.usage?.prompt_tokens,
      tokensOut: response.usage?.completion_tokens,
    });

    await execution.complete();
    res.json({ message: response.choices[0].message.content });
  } catch (error) {
    await execution.fail(error as Error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// Client configuration
interface TimeMachineConfig {
  apiKey: string;
  baseUrl?: string;        // default: 'https://api.timemachine.dev'
  maxRetries?: number;     // default: 3
  debug?: boolean;         // default: false
}

// Execution creation
interface CreateExecutionRequest {
  name?: string;
  metadata?: Record<string, unknown>;
}

// Step completion
interface StepCompleteOptions {
  output?: Record<string, unknown>;
  stateSnapshot?: Omit<StateSnapshot, 'stepId' | 'timestamp'>;
  tokensIn?: number;
  tokensOut?: number;
  cost?: number;
  latencyMs?: number;
  toolCalls?: ToolCall[];
  error?: StepError;
}

// Tool call record
interface ToolCall {
  name: string;
  input: Record<string, unknown>;
  output?: Record<string, unknown>;
}

// Error record
interface StepError {
  message: string;
  stack?: string;
}

// Status types
type ExecutionStatus = 'running' | 'completed' | 'failed';
type StepStatus = 'running' | 'completed' | 'failed';
type StepType =
  | 'llm_call' | 'tool_use' | 'decision' | 'retrieval'
  | 'human_input' | 'transform' | 'custom';

// Utility types
interface TokenUsage { tokensIn: number; tokensOut: number; }
interface ModelPricing { inputPer1k: number; outputPer1k: number; }
interface FallbackPricingConfig {
  inputPer1k: number;
  outputPer1k: number;
  enabled: boolean;
}