Core 서버 API

자체 서버 프로세스 안에서 SNA를 호스팅하려면 이 API를 사용합니다. 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가 하나를 생성합니다. HTTP route와 WebSocket client가 같은 session state를 공유해야 하거나 host가 lifecycle event에 직접 접근해야 한다면 manager를 직접 만들어 전달하십시오.

인증은 기본으로 켜져 있습니다. authToken을 전달하거나 SNA_AUTH_TOKEN을 설정해야 하며, GET /health만 공개 상태로 남습니다. unsafeDisableAuth는 격리된 테스트나 문서 생성에만 사용하고 host app에서는 쓰지 않습니다. allowedOrigins는 token 검증 전에 browser Origin 값을 필터링하며, 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를 사용합니다.

Core 서버 API

Core 서버 API

최소 host 예시

createSnaApp(options?)

attachWebSocket(server, sessionManager, options?)

SessionManager

snaPortRoute

목차

`createSnaApp(options?)`

`attachWebSocket(server, sessionManager, options?)`

`SessionManager`

`snaPortRoute`