@earendil-works/pi-coding-agent 패키지에는 Pi를 Node.js 또는 Bun 프로세스에 내장하는 TypeScript API가 있습니다. 대화형 CLI가 쓰는 에이전트, 세션, 도구, 모델, 자원과 동일한 메커니즘에 직접 접근합니다. 언어 독립적이거나 격리된 자식 프로세스 연동이 필요하면 대신 CLI 통합(print/JSON/RPC)을 고려합니다.

최소 예제

import { createAgentSession } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession();

try {
  await session.prompt("What files are in the current directory?");
  console.log(session.getLastAssistantText());
} finally {
  session.dispose();
}

작업 폴더, 발견된 자원, 저장된 설정, 설정된 자격 증명을 그대로 사용하며, prompt()은 실행이 끝날 때 해결됩니다.

스트리밍 이벤트 구독

스트리밍 출력이 필요하면 prompt 전에 구독합니다.

const unsubscribe = session.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

try {
  await session.prompt("Explain this repository");
} finally {
  unsubscribe();
}

세션 이벤트는 메시지 갱신, 도구 실행, 대기열, 압축, 재시도, 실행 라이프사이클을 알립니다. message_end가 확정된 최종 메시지이고, agent_end는 저수준 실행 하나의 끝입니다(자동 복구·대기 작업이 이어질 수 있음). Pi가 자동으로 더 진행하지 않는 것을 확실히 기다려야 한다면 agent_settled를 씁니다.

세션 생명주리와 상태

session.messages, session.model, session.thinkingLevel, session.systemPrompt, session.getActiveToolNames()로 현재 상태를 읽습니다. 프롬프트 중에도 조향과 후속을 구분해 넣을 수 있으며(steer(), followUp()), abort()는 중단 후 유휴까지 대기합니다.

SessionManager가 영속 또는 인메모리 트리와 활성 리프를 소유합니다. 세션 파일을 원치 않으면 SessionManager.inMemory()를 전달합니다. 외부 기록을 복원하려면 해당 항목을 담은 매니저로 세션을 만들면 되고, session.agent.state.messages에 할당하는 것만으로는 영속 컨텍스트가 대체되지 않습니다. AgentSessionRuntime은 newSession(), switchSession(), fork(), importFromJsonl()로 활성 세션을 통째로 교체합니다. 교체 후 구독은 옛 세션에 남아 있으므로 다시 묶어야 합니다.

설정 경계

덮어쓰기 없으면 팩토리는 ModelRuntime, 파일 기반 SettingsManager, 영속 SessionManager, DefaultResourceLoader, 설정된 기본 도구를 만듭니다. 각 경계는 명시적으로 교체할 수 있습니다.

주입	제어 범위
modelRuntime, model, thinkingLevel, scopedModels	모델 접근과 선택
settingsManager	설정(파일 또는 인메모리)
sessionManager	대화 기록
resourceLoader	확장·스킬·템플릿·테마·컨텍스트 파일
tools, noTools, excludeTools, customTools	활성 도구 세트

표준 발견 + 일부 덮어쓰기는 DefaultResourceLoader에 선택적 덮어쓰기를 주고, 호스트가 자원 저장·발견 전체를 소유하면 커스텀 ResourceLoader를 만듭니다. 인라인 확장은 DefaultResourceLoader의 extensionFactories로 줄 수 있습니다. 참고로 CLI가 MCP·codemode·tool_search를 내장 확장으로 로드하는 것과 달리 SDK 세션에는 로드되지 않습니다 — 필요하면 createCodemodeExtension(), createToolSearchExtension(), createMcpExtension()을 직접 추가하고 session.bindExtensions()를 호출해야 합니다.

저장소의 SDK 예제 14종

packages/coding-agent/examples/sdk/의 예제 전부는 저장소와 함께 타입 체크됩니다.

예제	목적
01-minimal.ts	생성, 프롬프트, 관찰, 해제
02-custom-model.ts	모델과 thinking 단계 선택
03-custom-prompt.ts	시스템 프롬프트 교체·추가
04-skills.ts	스킬 발견·필터·추가
05-tools.ts	내장 도구와 작업 폴더 선택
06-extensions.ts	파일·인라인 확장 로드
07-context-files.ts	프로젝트 지침 추가·교체
08-prompt-templates.ts	파일식 프롬프트 템플릿 추가
09-api-keys-and-oauth.ts	자격 증명·모델 저장 설정
10-settings.ts	파일·인메모리 설정 공급
11-sessions.ts	세션 영속성과 복원 제어
12-full-control.ts	기본 발견·상태 서비스 교체
13-session-runtime.ts	활성 세션을 안전하게 교체
14-codemode-mcp.ts	codemode·tool_search·MCP 확장 추가

세션 파일의 JSONL 계약은 Session Format 레퍼런스, 대화 값 타입은 Message Types 레퍼런스가 정의합니다. 정확한 메서드와 시그니처는 export된 TypeScript 선언이 원본입니다.

여기까지가 Pi 주제의 본문 순서입니다. 이 13편이 Pi를 자기 도구처럼 쓰는 출발점이 되길 바랍니다. 전체 글 목록은 Pi 주제 페이지에서 볼 수 있습니다.