Core サーバー API
`@sna-sdk/core/server` から export されるサーバー側エントリーポイントです。
Core サーバー API
独自サーバープロセス内で SNA をホストする場合に使います。Server package は HTTP app、WebSocket attachment、session manager、local port discovery route、direct one-shot/completion helper を公開します。
| サーフェス | 目的 |
|---|---|
createSnaApp(options?) | SNA HTTP application を作成します。 |
attachWebSocket(server, sessionManager, options?) | 既存 HTTP server に SNA WebSocket protocol を接続します。 |
generateSnaAuthToken() | Protected HTTP / WebSocket route 用の bearer token を生成します。 |
SessionManager | Server-side agent session と lifecycle event を管理します。 |
snaPortRoute | ブラウザ自動検出のため現在の SNA port を公開します。 |
runOnce, completion | この entry point からも re-export される direct server-side helper です。 |
@sna-sdk/core/server/routes/* 配下の deprecated compatibility route module は引き続き export されますが、新しい統合では server entry point と生成済みの API リファレンス を優先してください。
最小 host 例
import { serve } from "@hono/node-server";
import { createSnaApp, attachWebSocket, generateSnaAuthToken, SessionManager } from "@sna-sdk/core/server";
const sessionManager = new SessionManager({ maxSessions: 10 });
const authToken = generateSnaAuthToken();
const app = await createSnaApp({ sessionManager, authToken });
const server = serve({ fetch: app.fetch, port: 3099, hostname: "127.0.0.1" }) as unknown as import("node:http").Server;
attachWebSocket(server, sessionManager, { authToken });サーバー entry point は agent lifecycle を所有する process の近くに置いてください。Browser client は server module を直接 import せず、@sna-sdk/client または @sna-sdk/react 経由で接続する方が安全です。
createSnaApp(options?)
declare function createSnaApp(options?: {
sessionManager?: SessionManager;
authToken?: string;
allowedOrigins?: string[];
unsafeDisableAuth?: boolean;
}): Promise<Hono>;SNA route を公開する Hono HTTP application を作成します。OpenAPI app factory へ委譲するため、返された app には generated OpenAPI metadata と /docs の Swagger UI が含まれます。
sessionManager を省略すると server が 1 つ作成します。HTTP route と WebSocket client が同じ session state を共有する必要がある場合、または host が lifecycle event に直接アクセスする必要がある場合は、manager を作成して渡してください。
認証はデフォルトで有効です。authToken を渡すか SNA_AUTH_TOKEN を設定し、
GET /health だけが公開状態に残ります。unsafeDisableAuth は隔離された
test や docs generation にだけ使い、host app では使いません。
allowedOrigins は token 検証の前に browser Origin 値を filter し、
Origin を送らない native client は許可されます。
attachWebSocket(server, sessionManager, options?)
const wss = attachWebSocket(httpServer, sessionManager, { authToken, allowedOrigins });既存 Node HTTP server の /ws upgrade path に WebSocket server を接続します。createSnaApp に渡したものと同じ SessionManager を使ってください。そうしないと、HTTP command と WebSocket subscription が別々の session state を見ることになります。
createSnaApp で使ったものと同じ authToken と allowedOrigins を渡します。
TypeScript client は browser upgrade を ?token=... で認証します。Native
client は Authorization: Bearer ... または X-SNA-Token も送れます。
WebSocket server が push する message:
| Push | 送信タイミング |
|---|---|
sessions.snapshot | 接続直後、lifecycle/state/metadata 変更後。 |
session.lifecycle | Agent が開始、終了、crash、kill されたとき。 |
session.state-changed | Session が idle、busy、waiting、permission state の間を移動したとき。 |
session.config-changed | Model、permission mode、関連 runtime config が変わったとき。 |
agent.event | Client が session を subscribe したあと。 |
permission.request | Client が permission prompt を subscribe したあと。 |
SessionManager
SessionManager は server-side session record、runtime、event buffer、persisted history、lifecycle callback を調整します。
const sessionManager = new SessionManager({ maxSessions: 10 });重要な概念:
| Concept | 意味 |
|---|---|
| Session record | Durable SNA session metadata: id、label、cwd、meta、config、message count、timestamp。 |
| Runtime session | Session に現在接続されている runtime process または runtime handle。Config 変更で respawn が必要な場合は runtime chain ができます。 |
SessionInfo | Client に返される public snapshot shape。alive、state、agentStatus、cwd、config、count、last message、optional runtime chain を含みます。 |
SessionState | idle、processing、waiting、permission などの server state。 |
AgentStatus | UI-oriented state: idle、busy、disconnected。 |
ほとんどの host では createSnaApp と attachWebSocket が manager を使う形で十分です。Custom lifecycle policy、diagnostics、killAll() による coordinated shutdown が必要な場合に直接扱ってください。
snaPortRoute
snaPortRoute はブラウザ側の自動検出用の小さな handler です。
import { snaPortRoute } from "@sna-sdk/core/server";
app.get("/api/sna-port", snaPortRoute);現在の working directory の .sna/sna-api.port を読み、{ port } を返します。File がない場合は HTTP 503 と { port: null, error: "SNA API not running" } を返します。
SnaProvider が明示的な snaUrl なしで mount された場合、React integration がこの route を使います。