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

Overview

This skill migrates code from @honcho-ai/sdk v1.6.0 to v2.0.0 (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)

Quick Reference Table

v1.6.0 v2.0.0

client.core

client.http

getConfig()

getConfiguration()

setConfig()

setConfiguration()

getPeers()

peers()

getSessions()

sessions()

getWorkspaces()

workspaces()

getDeriverStatus()

queueStatus()

pollDeriverStatus()

Removed - do not poll

peer.chat(q, { stream: true })

peer.chatStream(q)

peer.workingRep()

peer.representation()

peer.getContext()

peer.context()

peer.observations

peer.conclusions

peer.observationsOf()

peer.conclusionsOf()

session.getPeers()

session.peers()

session.getMessages()

session.messages()

session.getSummaries()

session.summaries()

session.getContext()

session.context()

session.workingRep()

session.representation()

session.peerConfig()

session.getPeerConfiguration()

session.setPeerConfig()

session.setPeerConfiguration()

{ timeoutMs: 60000 }

{ timeout: 60 }

{ maxObservations: 50 }

{ maxConclusions: 50 }

{ includeMostDerived }

{ includeMostFrequent }

{ lastUserMessage }

{ searchQuery }

{ config: ... }

{ configuration: ... }

message.peer_id

message.peerId

message.created_at

message.createdAt

Observation

Conclusion

ObservationScope

ConclusionScope

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 } })