migrate-honcho-ts

Honcho TypeScript SDK の移行（v1.6.0 → v2.1.1）

概要

このスキルでは、コードを @honcho-ai/sdk v1.6.0 から v2.1.1 に移行します（Honcho 3.0.0 以降で必要です）。

主な破壊的変更：

• @honcho-ai/core の依存関係を削除
• 用語を「Observation」から「Conclusion」に変更
• 用語を「Deriver」から「Queue」に変更
• getConfig／setConfig から getConfiguration／setConfiguration に変更
• 全体で snake_case から camelCase に変更
• chat({ stream: true }) ではなく chatStream() でストリーミング
• Representation クラスを削除（現在は文字列を返します）

クイック移行ガイド

1. 依存関係を更新する

package.json から @honcho-ai/core を削除します。SDK に独自の HTTP クライアントが追加されました。

2. .core を .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. 設定メソッドの名前を変更する

// 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. 一覧表示メソッドの名前を変更する

// 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. ストリーミングを更新する

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

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

6. observations を conclusions に更新する

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

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

7. キューのステータスメソッドを更新する

// 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

重要： pollDeriverStatus() とそのポーリングパターンは完全に削除されました。キューが空になることを前提にしないでください。キューは継続的な処理システムです。新しいメッセージはいつでも届く可能性があるため、「完了」を待つのは有効なパターンではありません。以前、キューの処理完了をポーリングしていたコードがある場合は、その前提に依存しないよう再設計してください。

8. snake_case を 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. representation の呼び出しを更新する

// 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. updateMessage を session に移動する

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

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

11. card() を 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. 入力の厳密な検証（v2.0.2 以降）

クライアントコンストラクターとすべての入力スキーマでは、.strict() による Zod 検証を使って、不明なオプションを拒否するようになりました。

// 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() と session() は常に API 呼び出しを行います（v2.1.0 以降）

破壊的変更： peer() と session() は常に get-or-create API 呼び出しを行うようになりました。以前は、メタデータや設定を指定せずに呼び出すと、API 呼び出しを行わない遅延オブジェクトが返されていました。

// 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. 新しいプロパティとメソッド（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. list メソッドのページネーションパラメーター（v2.1.0 以降）

すべての list メソッドで、page、size、reverse パラメーターを指定できるようになりました。

// 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. context() 内での searchQuery の移動（v2.1.0 以降）

破壊的変更： searchQuery が context() のトップレベルオプションから削除されました。代わりに representationOptions.searchQuery を使用してください。

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

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

17. fetch の再試行ロジックを拡張（v2.1.1 以降）

SDK は、メッセージに 'fetch' が含まれるエラーだけでなく、すべての TypeError のネットワーク障害（接続リセット、DNS エラーなど）で再試行するようになりました。コードの変更は不要です。これは透過的に適用されます。

クイックリファレンステーブル

v1.6.0	v2.0.0
client.core	client.http
getConfig()	getConfiguration()
setConfig()	setConfiguration()
getPeers()	peers()
getSessions()	sessions()
getWorkspaces()	workspaces()
getDeriverStatus()	queueStatus()
pollDeriverStatus()	削除済み - ポーリングしないでください
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: 60000 }
{ maxObservations: 50 }	{ maxConclusions: 50 }
{ includeMostDerived }	{ includeMostFrequent }
{ lastUserMessage }	{ searchQuery }
{ config: ... }	{ configuration: ... }
message.peer_id	message.peerId
message.created_at	message.createdAt
peer.card()	peer.getCard() (card() は非推奨)
(新規)	peer.setCard(string[])
Observation	Conclusion
ObservationScope	ConclusionScope
(v2.1.0 で新規)	peer.createdAt / session.createdAt
(v2.1.0 で新規)	session.isActive
(v2.1.0 で新規)	session.getMessage(id)
(v2.1.0 で新規)	リストメソッドの page、size、reverse
context({ searchQuery })	context({ representationOptions: { searchQuery } })

詳細リファレンス

各変更の詳細については、以下を参照してください。

• DETAILED-CHANGES.md - API の変更に関する詳細ドキュメント
• MIGRATION-CHECKLIST.md - 手順ごとのチェックリスト

新しいエラータイプ

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

新しい設定タイプ

設定が厳密に型付けされるようになりました。

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