Migrate Honcho Ts

Honcho TypeScript SDK Migration (v1.6.0 → v2.1.1)

Overview

This skill migrates code from @honcho-ai/sdk v1.6.0 to v2.1.1 (required for Honcho 3.0.0+).

Key breaking changes:

• @honcho-ai/core dependency removed
• "Observation" → "Conclusion" terminology
• "Deriver" → "Queue" terminology
• getConfig/setConfig → getConfiguration/setConfiguration
• snake_case → camelCase throughout
• Streaming via chatStream() instead of chat({ stream: true })
• Representation class removed (returns string now)

Quick Migration

1. Update dependencies

Remove @honcho-ai/core from package.json. The SDK now has its own HTTP client.

2. Replace .core with .http

// Before
const workspace = await client.core.workspaces.getOrCreate({ id: 'my-workspace' })

// After
const response = await client.http.post('/v3/workspaces', { body: { id: 'my-workspace' } })

3. Rename configuration methods

// Before
await honcho.getConfig()
await honcho.setConfig({ key: 'value' })
await peer.getConfig()
await session.getConfig()

// After
await honcho.getConfiguration()
await honcho.setConfiguration({ reasoning: { enabled: true } })
await peer.getConfiguration()
await session.getConfiguration()

4. Rename listing methods

// Before
const peers = await honcho.getPeers()
const sessions = await honcho.getSessions()
const workspaces = await honcho.getWorkspaces()  // string[]

// After
const peers = await honcho.peers()
const sessions = await honcho.sessions()
const workspaces = await honcho.workspaces()  // Page<string>

5. Update streaming

// Before
const stream = await peer.chat('Hello', { stream: true })

// After
const stream = await peer.chatStream('Hello')

6. Update observations → conclusions

// Before
peer.observations
peer.observationsOf('bob')
maxObservations: 50
includeMostDerived: true

// After
peer.conclusions
peer.conclusionsOf('bob')
maxConclusions: 50
includeMostFrequent: true

7. Update queue status methods

// Before
await honcho.getDeriverStatus({ observer: peer })
await honcho.pollDeriverStatus({ timeoutMs: 60000 })  // REMOVE - see note below

// After
await honcho.queueStatus({ observer: peer })
// pollDeriverStatus() has no replacement - see note below

Important: pollDeriverStatus() and its polling pattern have been removed entirely. Do not rely on the queue ever being empty. The queue is a continuous processing system—new messages may arrive at any time, and waiting for "completion" is not a valid pattern. If your code previously polled for queue completion, redesign it to work without that assumption.

8. Convert snake_case to camelCase

// Before
message.peer_id
message.session_id
message.created_at
message.token_count
{ observe_me: true, observe_others: false }
{ created_at: '2024-01-01' }

// After
message.peerId
message.sessionId
message.createdAt
message.tokenCount
{ observeMe: true, observeOthers: false }
{ createdAt: '2024-01-01' }

9. Update representation calls

// Before
const rep = await peer.workingRep(session, target, options)
console.log(rep.explicit)  // ExplicitObservation[]
console.log(rep.deductive) // DeductiveObservation[]

// After
const rep = await peer.representation({ session, target, ...options })
console.log(rep)  // string

10. Move updateMessage to session

// Before
await honcho.updateMessage(message, metadata, session)

// After
await session.updateMessage(message, metadata)

11. Update card() to getCard() (v2.0.1+)

// Before
const card = await peer.card(target)

// After (v2.0.1+)
const card = await peer.getCard(target)  // Returns string[] | null

// peer.card() still works but is deprecated — use getCard()

// New: setPeerCard / setCard
await peer.setCard(['Prefers dark mode', 'Located in US'])

12. Strict input validation (v2.0.2+)

Client constructor and all input schemas now reject unknown options via .strict() Zod validation.

// Before (v2.0.1 and earlier) — silently ignored
const honcho = new Honcho({ baseUrl: 'http://...' })  // typo: baseUrl vs baseURL — silently fell back to default

// After (v2.0.2+) — throws ZodError
const honcho = new Honcho({ baseUrl: 'http://...' })  // ZodError! Use baseURL

13. peer() and session() always make API calls (v2.1.0+)

Breaking: peer() and session() now always make a get-or-create API call. Previously, calling without metadata/configuration returned a lazy object with no API call.

// Before (v2.0.x) — no API call without options
const session = honcho.session('my-session')  // Lazy, no network request

// After (v2.1.0+) — always hits the API
const session = await honcho.session('my-session')  // Makes POST to /sessions (get-or-create)

14. New properties and methods (v2.1.0+)

// createdAt on Peer and Session
const peer = await honcho.peer('user-123')
console.log(peer.createdAt)  // string | undefined

const session = await honcho.session('sess-1')
console.log(session.createdAt)  // string | undefined

// isActive on Session
console.log(session.isActive)  // boolean | undefined

// getMessage() on Session
const msg = await session.getMessage('msg-id')

15. Pagination parameters on list methods (v2.1.0+)

All list methods now accept page, size, and reverse parameters:

// Before (v2.0.x) — only filters
const peers = await honcho.peers({ metadata: { role: 'admin' } })

// After (v2.1.0+) — pagination controls via options object
const peers = await honcho.peers({
  filters: { metadata: { role: 'admin' } },
  page: 2,
  size: 25,
  reverse: true
})

// Legacy raw-filter form still works:
const peers = await honcho.peers({ metadata: { role: 'admin' } })

// Works on: honcho.peers(), honcho.sessions(), honcho.workspaces(),
// peer.sessions(), session.messages(), scope.list()

16. searchQuery moved in context() (v2.1.0+)

Breaking: searchQuery removed from top-level context() options. Use representationOptions.searchQuery instead.

// Before (v2.0.x)
await session.context({ searchQuery: '...' })

// After (v2.1.0+)
await session.context({ representationOptions: { searchQuery: '...' } })

17. Broader fetch retry logic (v2.1.1+)

The SDK now retries on all TypeError network failures (connection resets, DNS errors, etc.) instead of only those with 'fetch' in the message. No code changes needed — this is transparent.

Quick Reference Table

Detailed Reference

For comprehensive details on each change, see:

• DETAILED-CHANGES.md - Full API change documentation
• MIGRATION-CHECKLIST.md - Step-by-step checklist

New Error Types

import {
  HonchoError,
  AuthenticationError,
  BadRequestError,
  NotFoundError,
  PermissionDeniedError,
  RateLimitError,
  ConflictError,
  UnprocessableEntityError,
  ServerError,
  ConnectionError,
  TimeoutError
} from '@honcho-ai/sdk'

New Configuration Types

Configurations are now strongly typed:

await honcho.setConfiguration({
  reasoning: {
    enabled: true,
    customInstructions: 'Be concise'
  },
  peerCard: { use: true, create: true },
  summary: {
    enabled: true,
    messagesPerShortSummary: 20,
    messagesPerLongSummary: 60
  },
  dream: { enabled: true }
})

Detailed API Changes

Client Changes

.core Property Removed

The .core property (which exposed the raw @honcho-ai/core client) has been removed. Use .http for advanced HTTP access.

// Before
const workspace = await client.core.workspaces.getOrCreate({ id: 'my-workspace' })

// After - SDK handles workspace creation automatically
// For advanced usage:
const response = await client.http.post('/v3/workspaces', { body: { id: 'my-workspace' } })

Listing Methods Return Type Changes

• workspaces() now returns Page<string> instead of string[]
• session.peers() now returns Peer[] instead of Page<Peer>

const workspacePage = await honcho.workspaces()
for (const id of workspacePage.items) {
  console.log(id)
}

updateMessage() Moved to Session

// Before
await honcho.updateMessage(message, { key: 'value' }, session)

// After
await session.updateMessage(message, { key: 'value' })

config Option Renamed to configuration

// Before
const peer = await honcho.peer('user-id', { config: { observe_me: true } })
const session = await honcho.session('session-id', { config: { ... } })

// After
const peer = await honcho.peer('user-id', { configuration: { observeMe: true } })
const session = await honcho.session('session-id', { configuration: { reasoning: { enabled: true } } })

---

Peer Changes

Streaming API

The stream option on chat() has been removed. Use chatStream() instead.

// Before
const stream = await peer.chat('Hello', { stream: true })
for await (const chunk of stream) {
  process.stdout.write(chunk)
}

// After
const stream = await peer.chatStream('Hello')
for await (const chunk of stream) {
  process.stdout.write(chunk)
}

Non-streaming chat() now only returns string | null:

const response = await peer.chat('Hello')  // Returns string | null

New reasoningLevel Option

const response = await peer.chat('Complex question', {
  reasoningLevel: 'high'  // 'minimal' | 'low' | 'medium' | 'high' | 'max'
})

workingRep() Renamed to representation()

// Before
const rep = await peer.workingRep(session, target, options)
console.log(rep.toString())
console.log(rep.explicit)
console.log(rep.deductive)

// After
const rep = await peer.representation({
  session,
  target,
  searchQuery: options?.searchQuery,
  maxConclusions: options?.maxObservations,
  includeMostFrequent: options?.includeMostDerived,
})
console.log(rep)  // Returns string directly

getContext() Renamed to context()

Options are now passed as a single object:

// Before
const ctx = await peer.getContext(target, options)

// After
const ctx = await peer.context({ target, ...options })

card() Return Type Changed

// Before
const card = await peer.card(target)  // Returns string

// After
const card = await peer.card(target)  // Returns string[] | null

message() Options Changed

// Before
const msg = peer.message('Hello', {
  metadata: { key: 'value' },
  configuration: { deriver: { enabled: true } },
  created_at: '2024-01-01T00:00:00Z'
})
// Returns ValidatedMessageCreate with peer_id, created_at

// After
const msg = peer.message('Hello', {
  metadata: { key: 'value' },
  configuration: { reasoning: { enabled: true } },
  createdAt: '2024-01-01T00:00:00Z'
})
// Returns MessageInput with peerId, createdAt

PeerContext.representation Type Changed

// Before
const ctx = await peer.getContext()
if (ctx.representation) {
  console.log(ctx.representation.explicit)  // Representation object
  console.log(ctx.representation.deductive)
}

// After
const ctx = await peer.context()
if (ctx.representation) {
  console.log(ctx.representation)  // Now a string
}

---

Session Changes

getPeers() Return Type Changed

// Before
const peers = await session.getPeers()  // Returns Page<Peer>

// After
const peers = await session.peers()  // Returns Peer[]

getContext() Renamed to context()

// Before
const ctx = await session.getContext({
  summary: true,
  peerTarget: user,
  peerPerspective: assistant,
  lastUserMessage: "What are my preferences?",
  representationOptions: {
    maxObservations: 50,
    includeMostDerived: true
  }
})

// After
const ctx = await session.context({
  summary: true,
  peerTarget: user,
  peerPerspective: assistant,
  searchQuery: "What are my preferences?",
  representationOptions: {
    maxConclusions: 50,
    includeMostFrequent: true
  }
})

SessionPeerConfig Uses camelCase and Methods Renamed

// Before
await session.setPeerConfig(peer, {
  observe_me: true,
  observe_others: false
})
const config = await session.peerConfig(peer)

// After
await session.setPeerConfiguration(peer, {
  observeMe: true,
  observeOthers: false
})
const config = await session.getPeerConfiguration(peer)

---

Message Changes

Message Properties Use camelCase

// Before (from @honcho-ai/core)
message.peer_id
message.session_id
message.workspace_id
message.created_at
message.token_count

// After
message.peerId
message.sessionId
message.workspaceId
message.createdAt
message.tokenCount

MessageInput Type

// Before
interface ValidatedMessageCreate {
  peer_id: string
  content: string
  metadata?: Record<string, unknown>
  configuration?: Record<string, unknown>
  created_at?: string
}

// After
interface MessageInput {
  peerId: string
  content: string
  metadata?: Record<string, unknown>
  configuration?: MessageConfiguration
  createdAt?: string
}

---

Streaming Changes

DialecticStreamDelta Removed

// Before
import { DialecticStreamDelta, DialecticStreamChunk } from '@honcho-ai/sdk'

// After
import { DialecticStreamChunk, DialecticStreamResponse } from '@honcho-ai/sdk'

---

Configuration Changes

Workspace Configuration

Configurations are now strongly typed objects instead of Record<string, unknown>.

// Before
await honcho.setConfig({
  deriver: { enabled: true },
  some_custom_key: 'value'
})

// After
await honcho.setConfiguration({
  reasoning: {
    enabled: true,
    customInstructions: 'Be concise'
  },
  peerCard: {
    use: true,
    create: true
  },
  summary: {
    enabled: true,
    messagesPerShortSummary: 20,
    messagesPerLongSummary: 60
  },
  dream: {
    enabled: true
  }
})

Peer Configuration

// Before
await peer.setConfig({ observe_me: false })

// After
await peer.setConfiguration({ observeMe: false })

Message Configuration

// Before
peer.message('Hello', {
  configuration: {
    deriver: { enabled: true }
  }
})

// After
peer.message('Hello', {
  configuration: {
    reasoning: {
      enabled: true,
      customInstructions: 'Focus on emotions'
    }
  }
})

---

Type Changes

Removed Exports

• Observation (use Conclusion)
• ObservationScope (use ConclusionScope)
• ObservationData, ObservationCreateParam, ObservationQueryParams
• Representation, RepresentationData, RepresentationOptions (class removed)
• ExplicitObservation, DeductiveObservation
• DialecticStreamDelta
• DeriverStatusOptions (use QueueStatusOptions)
• MessageCreate (use MessageInput)
• WorkingRepParams

New Exports

import {
  // Domain classes
  Conclusion,
  ConclusionScope,
  ConclusionCreateParams,

  // Error types
  HonchoError,
  AuthenticationError,
  BadRequestError,
  NotFoundError,
  PermissionDeniedError,
  RateLimitError,
  ConflictError,
  UnprocessableEntityError,
  ServerError,
  ConnectionError,
  TimeoutError,

  // Message types
  Message,
  MessageInput,

  // Configuration types
  WorkspaceConfig,
  SessionConfig,
  PeerConfig,
  SessionPeerConfig,
  MessageConfiguration,
  ReasoningConfig,
  PeerCardConfig,
  SummaryConfig,
  DreamConfig,

  // API response types
  QueueStatus,
  QueueStatusOptions,
  RepresentationOptions,
  ConclusionQueryParams,
  ConclusionResponse,
} from '@honcho-ai/sdk'

SummaryData Type Changed

// Before
interface SummaryData {
  content: string
  message_id: string
  summary_type: string
  created_at: string
  token_count: number
}

// After
interface SummaryData {
  content: string
  messageId: string
  summaryType: string
  createdAt: string
  tokenCount: number
}

---

Post-v2.0.0 Changes

---

Card Method Deprecation and setCard (v2.0.1)

Before (v2.0.0)

const card = await peer.card(target)  // string[] | null

After (v2.0.1+)

// getCard() is the preferred method
const card = await peer.getCard(target)  // string[] | null

// card() still works but is deprecated
const card = await peer.card(target)  // Deprecated

// New: setCard()
const updated = await peer.setCard(['Fact 1', 'Fact 2'])
const updated = await peer.setCard(['Fact 1'], targetPeer)

---

Strict Input Validation (v2.0.2)

Client constructor and all input schemas now use .strict() Zod validation.

// Before (v2.0.1) — silently ignored
const honcho = new Honcho({ baseUrl: 'http://...' })  // typo fell back to default

// After (v2.0.2+) — ZodError thrown
const honcho = new Honcho({ baseUrl: 'http://...' })  // ZodError: Unrecognized key "baseUrl"

---

peer() and session() Always Make API Calls (v2.1.0)

Before (v2.0.x)

// Without options: lazy object, no API call
const peer = honcho.peer('user-123')

// With options: made API call
const peer = await honcho.peer('user-123', { metadata: { key: 'value' } })

After (v2.1.0+)

// Always makes a get-or-create API call
const peer = await honcho.peer('user-123')
// peer.createdAt is now always populated

---

New Properties: createdAt, isActive (v2.1.0)

// Peer
const peer = await honcho.peer('user-123')
console.log(peer.createdAt)   // string | undefined

// Session
const session = await honcho.session('sess-1')
console.log(session.createdAt) // string | undefined
console.log(session.isActive)  // boolean | undefined

// Refreshed by getMetadata(), getConfiguration(), and refresh()
await session.refresh()

---

getMessage() on Session (v2.1.0)

// Fetch a single message by ID
const msg = await session.getMessage('msg-abc123')
console.log(msg.content, msg.createdAt)

---

Pagination Parameters (v2.1.0)

All list methods now accept page, size, and reverse:

// Defaults: page=1, size=50, reverse=false
const peersPage = await honcho.peers({
  filters: { metadata: { role: 'admin' } },
  page: 2,
  size: 25,
  reverse: true
})

// Page<T> properties:
console.log(peersPage.total)      // Total items
console.log(peersPage.pages)      // Total pages
console.log(peersPage.hasNextPage) // boolean

// Works on:
// honcho.peers(), honcho.sessions(), honcho.workspaces()
// peer.sessions()
// session.messages()
// scope.list()

---

searchQuery Moved in context() (v2.1.0)

Before (v2.0.x)

const ctx = await session.context({
  searchQuery: 'What are my preferences?',
  representationOptions: { maxConclusions: 50 }
})

After (v2.1.0+)

const ctx = await session.context({
  representationOptions: {
    searchQuery: 'What are my preferences?',
    maxConclusions: 50
  }
})

---

Broader Fetch Retry Logic (v2.1.1)

The SDK now retries on all TypeError network failures (connection resets, DNS errors, etc.) instead of only those containing 'fetch' in the error message. This is transparent — no code changes needed.

Migration Checklist

Use this checklist to track migration progress. Copy into your working notes and check off items as completed.

Dependencies

• [ ] Remove @honcho-ai/core from dependencies
• [ ] Update @honcho-ai/sdk to v2.1.1

Client-Level Changes

• [ ] Replace all .core usages with .http or remove
• [ ] Rename getConfig() → getConfiguration()
• [ ] Rename setConfig() → setConfiguration()
• [ ] Rename getPeers() → peers()
• [ ] Rename getSessions() → sessions()
• [ ] Rename getWorkspaces() → workspaces() (returns Page<string> now)
• [ ] Rename getDeriverStatus() → queueStatus()
• [ ] Remove pollDeriverStatus() calls entirely (no replacement—do not rely on queue being empty)
• [ ] Move updateMessage() calls from client to session

Peer-Level Changes

• [ ] Replace peer.chat(q, { stream: true }) with peer.chatStream(q)
• [ ] Rename getSessions() → sessions()
• [ ] Rename getConfig() → getConfiguration()
• [ ] Rename setConfig() → setConfiguration()
• [ ] Rename peerConfig() → getPeerConfiguration()
• [ ] Rename setPeerConfig() → setPeerConfiguration()
• [ ] Rename workingRep() → representation() (returns string now)
• [ ] Rename getContext() → context()
• [ ] Replace observations → conclusions
• [ ] Replace observationsOf() → conclusionsOf()
• [ ] Handle card() returning string[] | null instead of string

Session-Level Changes

• [ ] Rename getPeers() → peers() (returns Peer[] now, not Page<Peer>)
• [ ] Rename getMessages() → messages()
• [ ] Rename getConfig() → getConfiguration()
• [ ] Rename setConfig() → setConfiguration()
• [ ] Rename getContext() → context()
• [ ] Rename getSummaries() → summaries()
• [ ] Rename getDeriverStatus() → queueStatus()
• [ ] Remove pollDeriverStatus() calls entirely (no replacement—do not rely on queue being empty)
• [ ] Rename workingRep() → representation() (returns string now)

Terminology Changes

• [ ] Rename maxObservations → maxConclusions
• [ ] Rename includeMostDerived → includeMostFrequent
• [ ] Rename lastUserMessage → searchQuery
• [ ] Rename Observation type → Conclusion
• [ ] Rename ObservationScope type → ConclusionScope

snake_case → camelCase

• [ ] Update all { config: ... } to { configuration: ... }
• [ ] Update observe_me → observeMe
• [ ] Update observe_others → observeOthers
• [ ] Update created_at → createdAt
• [ ] Update message property access:
• [ ] peer_id → peerId
• [ ] session_id → sessionId
• [ ] workspace_id → workspaceId
• [ ] created_at → createdAt
• [ ] token_count → tokenCount
• [ ] Update summary property access:
• [ ] message_id → messageId
• [ ] summary_type → summaryType

Configuration Objects

• [ ] Update workspace configuration to typed structure
• [ ] Update session configuration to typed structure
• [ ] Update peer configuration to typed structure
• [ ] Replace deriver config with reasoning config

Error Handling

• [ ] Update error handling to use new error types if needed

Type Imports

• [ ] Remove imports of deleted types:
• Observation, ObservationScope, ObservationData
• Representation, RepresentationData
• ExplicitObservation, DeductiveObservation
• DialecticStreamDelta
• DeriverStatusOptions
• MessageCreate, ValidatedMessageCreate
• WorkingRepParams
• [ ] Add imports of new types as needed:
• Conclusion, ConclusionScope
• MessageInput
• QueueStatusOptions
• Error types

Representation Handling

• [ ] Remove usage of Representation class methods (.explicit, .deductive, .isEmpty(), .diff())
• [ ] Handle representation as plain string

Card Method Updates (v2.0.1)

• [ ] Replace peer.card() with peer.getCard() (card() is deprecated)
• [ ] Use peer.setCard(string[]) if setting peer cards

Strict Validation (v2.0.2)

• [ ] Verify no constructor options or input schemas pass unknown/misspelled fields (now throws ZodError)
• [ ] Check for baseUrl vs baseURL typo in Honcho constructor

peer() / session() API Call Change (v2.1.0)

• [ ] Update code that relied on lazy peer() / session() — they now always make API calls
• [ ] Ensure all peer() and session() calls are awaited

New Properties (v2.1.0)

• [ ] Use peer.createdAt / session.createdAt where creation time is needed
• [ ] Use session.isActive where session active status is needed

New Methods (v2.1.0)

• [ ] Use session.getMessage(messageId) to fetch single messages by ID

Pagination Parameters (v2.1.0)

• [ ] Add page, size, reverse parameters to list calls where needed:
• [ ] honcho.peers()
• [ ] honcho.sessions()
• [ ] honcho.workspaces()
• [ ] peer.sessions()
• [ ] session.messages()
• [ ] scope.list()

searchQuery Location Change (v2.1.0)

• [ ] Move searchQuery from top-level context() options to representationOptions.searchQuery

Final Verification

• [ ] Run TypeScript compiler with no errors
• [ ] Run tests
• [ ] Verify streaming functionality works
• [ ] Verify configuration changes take effect