Durable SDK (실험적 기능)

실험적 기능입니다. 패키지, 해당 API 및 사용하는 통신 방식은 이후 마이너 릴리스에서 변경되거나 기능이 제거될 수 있습니다. 영구 에이전트에서 이것이 무엇을 의미하는지는 버전에 설명되어 있습니다.

@colliepwa/durable-sdk은 영구 에이전트가 Collie를 통해 휴대전화에 자신을 표시하는 데 사용하는 npm 패키지입니다. 이 페이지에서는 해당 패키지의 모든 부분을 나열합니다. Durable agent에는 빠른 시작과 Collie 측 설정이 나와 있으며, durable wire에는 둘 사이에서 전달되는 내용이 설명되어 있습니다.

설치 및 진입점

한 번 설치하면 5개의 진입점이 제공됩니다. 대부분의 영구 에이전트를 위한 루트 import와 특수한 용도의 진입점 4개입니다.

npm install @colliepwa/durable-sdk@experimental
# or
bun add @colliepwa/durable-sdk@experimental

이 패키지에는 Node 22.19 이상 또는 Bun 1.4 이상이 필요하며, 런타임 의존성은 없습니다. ./pi에는 1.1 이상 2 미만의 @earendil-works/pi-durable, @earendil-works/pi-ai, @earendil-works/chord이 필요합니다. 해당 엔트리는 Pi Durable 1.1.0 및 1.2.0에서 테스트되었습니다. 세 가지는 선택적 피어 의존성이므로, ./pi을 전혀 import하지 않는 durable agent는 아무것도 설치하지 않습니다.

런타임은 durable agent가 응답자를 식별할 수 있는지 결정합니다. 하위 프로세스 검사는 durable agent 자체 또는 해당 에이전트가 시작한 프로세스의 동작을 403 caller-refused으로 거부합니다. answer, send, stop, action, rename, close, reopen 및 starter가 여기에 해당합니다. 읽기 작업은 계속 열려 있습니다.

이 검사가 없으면 에이전트가 실행하는 도구를 포함하여 사용자의 모든 프로세스가 카드에 응답할 수 있습니다. 소켓에 접근할 수 없는 샌드박스에서 에이전트 도구를 실행하십시오. 소켓에는 파일 소유자가 있는 시스템이 필요하므로 Windows에서는 시작 시 openCollie이 중단됩니다. Windows 환경의 durable agent는 대신 토큰이 포함된 TLS 뒤에서 ./core을 제공합니다(durable agent에 연결하는 두 가지 방법).

연결 열기

openCollie은 비공개 소켓을 생성하며, 반환된 핸들은 휴대폰에 표시되는 내용을 배치합니다.

import { openCollie } from "@colliepwa/durable-sdk";

const collie = await openCollie({ hostName: "desk" });
const space = collie.workspace("support", { title: "Support" });
const tab = space.tab("main", { title: "Tickets" });
const pane = tab.pane("ticket-1", { title: "Maria Lopez", harness: "desk" });
collie.ready();

socket 옵션이 없으면 Collie도 읽는 변수인 COLLIE_DURABLE_SOCKET에서 경로를 가져옵니다.

openCollie에는 없고 createCore에만 두 가지 옵션이 더 존재합니다: receipts 및 allowAlways(질문 목록).

close()은 의도적으로 열린 ask를 열린 상태로 둡니다. 종료는 응답이 아니며, 응답을 기다리는 작업의 처리 방식은 영속 에이전트가 결정합니다.

tab.pane(id, { title, harness, cwd?, sessionId? })은 해당 ID를 가진 창이 존재할 때 이를 반환하므로 영속 에이전트는 두 번째 창 없이 대화를 두 번 표시할 수 있습니다. 제목은 256바이트로, harness은 64바이트로 잘립니다. cwd은 절대 경로여야 하며 그렇지 않으면 생략됩니다.

모든 ID는 ID 규칙을 따릅니다: 1~128바이트, 제어 문자 없음, 공백 문자 없음, /, ?, # 중 어느 것도 포함하지 않음. 잘못된 ID는 TypeError입니다. 유선 프로토콜이 탭을 <workspace>:<tab>로 지정하므로 워크스페이스 또는 탭 ID에는 :를 포함할 수 없습니다.

창

창은 하나의 대화이며, 창의 메서드는 휴대폰에 표시할 내용을 설정합니다.

창에는 4개의 읽기 전용 필드도 있습니다: id, sessionId, turnId (실행 중인 turn 또는 마지막 turn), openAsks. 액션의 icon은 play, pause, check, x, refresh, archive, flag, star, send, note, search, more 중 하나입니다. 다른 이름은 아이콘을 표시하지 않습니다.

item 이벤트는 id 및 선택적 ts을 가진 항목 하나를 전달합니다. 알려진 id를 가진 항목은 이전 항목을 제자리에서 대체합니다.

reply, thinking, notice 또는 markdown 항목은 텍스트가 늘어나는 동안 partial: true을 전달할 수 있습니다. 창이 working을 벗어나기 전에 텍스트가 늘어남에 따라 동일한 id를 최대 250ms마다 다시 작성하고, 마지막으로 partial 없이 최종 텍스트와 함께 한 번 더 작성하십시오.

제한을 초과한 텍스트는 잘리며, 제어 문자 및 보이지 않는 문자는 제거됩니다. 잘못된 lang, 잘못된 href, 잘못된 배지 또는 잘못된 진행률은 Collie가 버리므로 대신 TypeError 또는 RangeError이 됩니다. durable agent는 ask, ask-closed, state 이벤트를 직접 추가할 수 없습니다. ask() 및 state()이 이를 작성합니다.

질문 목록

pane.ask은 카드를 표시하고 응답으로 리졸브되며, requireApproval은 한 줄로 단일 도구 호출에 대해 묻습니다.

import { requireApproval } from "@colliepwa/durable-sdk";

const args = { order: "5521", amount: 40 };
const approval = await requireApproval("refund", args, {
  pane,
  toolCallId: "call-1",
  timeoutMs: 10 * 60_000,
});
if (!approval.approved) throw new Error(`refund not approved: ${approval.decidedBy}`);

requireApproval(toolName, args, options)은 모델의 설명이 아니라 호출 내용 자체로부터 카드를 구성합니다. 제목은 "refund wants to run"이고 도구 라인은 refund(order: "5521", amount: 40)이며 푸시는 "refund needs a yes"로 표시되고 버튼은 Allow 및 Deny입니다. { approved, decidedBy, decidedAt, askId }을 반환합니다. 거부, 타임아웃, 중지, 중단은 모두 approved: false을 반환합니다.

callSummary(name, args) 및 argumentsView(args)은 사용하는 두 구성 요소입니다. 호출은 한 줄로 표현되고 인수는 각 값이 JSON인 key: value 쌍으로 표현됩니다.

pane.ask(input)은(는) 네 가지 종류 중 하나를 받습니다. 프로미스는 해당 종류의 형태를 가진 응답으로 해결됩니다.

모든 종류는 toolCallId, itemId, title(256바이트)를 받습니다. reason(2 KiB), tool, push: { title?, line? }(60자 및 120자, 알림 문구), expiresAt(시간대가 포함된 Date 또는 ISO 8601 문자열)을 받을 수 있습니다.

id을(를) 생략하십시오. SDK는 askIdFor(paneId, toolCallId)을(를) 통해 이를 도출합니다. 두 id에 대한 SHA-256의 앞자리 16진수 32자입니다. 따라서 재시작 후 다시 발생한 동일한 도구 호출은 동일한 id를 얻게 되며, 재시작 전에 휴대폰에서 전송한 응답이 전달됩니다. 이미 열려 있는 id를 발생시키는 것은 TypeError입니다.

decidedBy은(는) phone, program 또는 timeout입니다. 요청은 expiresAt을(를) 초과하면 timeout에 의해 결정된 상태로 닫힙니다. ask()은(는) decidedBy이(가) timeout인 AskClosed(으)로 거부됩니다. 카드에는 그때까지 남은 시간이 표시됩니다. 시간 초과되었거나 지속형 에이전트에서 결정된 질문은 Chat에 "응답 전에 시간 초과됨: refund 실행을 원함"과 같은 한 줄을 남깁니다.

중단된 signal, pane.close() 및 휴대폰에서의 종료는 요청을 program에 의해 결정된 상태로 닫으며 ask()은(는) AskClosed(으)로 거부됩니다.

주의. allow-always 옵션은 한 번 응답한 후의 모든 후속 호출을 통과시킵니다. https에서는 토큰이 유일한 관문이므로, 그곳의 지속형 에이전트는 허용 및 거부만 제공합니다. allowAlways: false을(를) 포함한 createCore은(는) allow-always 옵션을 TypeError(으)로 만듭니다. 문구가 잘리거나 정제된 요청 또는 도구 이름이 없는 요청에 대해서는 휴대폰에서 allow-always을(를) 제공하지 않습니다.

휴대폰에서 오는 모든 동작에는 요청 id가 포함되며, 코어는 해당 영수증을 보관합니다. 중복 요청은 아무것도 실행하지 않고 replayed: true와 함께 첫 번째 응답을 다시 받습니다. 기본 MemoryReceiptStore는 창별로, 그리고 시작, 이름 변경, 닫기, 다시 열기 그룹별로 최신 RECEIPTS_PER_GROUP개(1000개)를 유지합니다. 폐기된 id가 중복 요청되면 500 receipt-dropped을 받고 아무것도 실행하지 않습니다. 프로세스가 종료되면 저장소도 사라집니다.

재시작 후에도 영수증을 유지하려면 get(requestId) 및 put(requestId, record, group)를 포함하는 ReceiptStore를 작성하고 createCore에 receipts로 전달하십시오. openCollie는 항상 이를 메모리에 보관합니다.

훅 및 기록

hook은 휴대폰이 보내는 동작을 처리하는 단일 지정 위치이며, history provider는 자체 기록을 제공합니다.

hook은 해당 cap이 켜져 있고 요청 id가 새로운 경우에만 실행됩니다. 거부 시에는 아무것도 저장되지 않으므로 동일한 요청 id로 다시 시도할 수 있습니다. 창별 핸들러가 hook보다 우선합니다. 둘 다 없는 창은 전송, 중지 또는 탭에 대해 409 not-supported로 응답합니다.

SDK는 수락된 동작을 직접 적용합니다. 이름 변경은 제목을 설정합니다. 닫기는 대상과 그 내부의 모든 항목을 제거하고, 열려 있는 질문들을 중지됨 상태로 닫습니다. hook 없는 다시 열기는 현재 프로세스가 닫은 창을 복원합니다. 재시작 전에 닫힌 대화는 onReopen가 필요합니다. 레이아웃은 시작할 때마다 다시 생성되므로, 제목이나 닫기 상태가 프로세스 종료 후에도 유지되기를 원하는 durable agent는 이를 hook에 저장합니다.

collie.history(provider)는 durable agent 자체 저장소에서 열려 있거나 닫힌 모든 대화를 제공합니다. caps가 생략되거나 history: true을 지정하면 history cap을 켭니다.

행은 { id, title, subtitle?, workspaceId?, tabId?, startedAt, endedAt?, state, items }이며, state은 open 또는 closed이고 items는 개수입니다. 커서(after, next)는 공백이 없는 1~512바이트의 출력 가능한 ASCII 문자열로 직접 지정합니다. next가 없으면 목록이 끝납니다.

provider가 설정되면 각 창의 sessionId는 해당 창의 id가 되며, 기록은 그 아래에서 창의 대화를 제공합니다. 다른 id를 지정하려면 sessionId를 tab.pane()에 전달하고, 재시작 후 동일하게 유지될 수 없는 경우에는 null를 전달하십시오.

tailLimit는 기록이 아닙니다. Collie의 이벤트 읽기를 위해 각 창이 보관하는 원시 tail이며, 기본값은 500개 이벤트입니다. 이보다 뒤처진 리더는 창의 현재 전체 뷰(최대 최신 2000개 항목)를 대신 받습니다.

기능

cap은 durable agent가 수행할 수 있는 작업을 나타내며, 휴대폰은 durable agent가 선언한 cap에 대해서만 컨트롤을 표시합니다.

생략하면 caps는 SDK가 수행할 수 있는 모든 기능을 활성화하고, history()에 제공자가 생기면 history도 활성화합니다. 지정하면 전체 목록으로 작동합니다. 지정하지 않은 cap은 비활성화되므로 { asks: true }는 ask만 선언합니다. 하나만 비활성화하고 나머지를 유지하려면 ALL_CAPS를 전개하십시오: { ...ALL_CAPS, steer: false }. 비활성화된 cap의 라우트는 409 not-supported로 응답합니다. terminal는 항상 false입니다.

도우미 및 상수

루트 import는 openCollie를 구성하는 요소들과 적용되는 규칙도 함께 내보냅니다.

유선상(wire)의 모든 타입과 모든 훅 페이로드 역시 src/core/types.ts에서 export됩니다.

Pi 헬퍼입니다.

./pi은(는) Pi Durable 대화를 창(pane)으로, 위험한 툴 호출을 카드로, Pi의 저장소를 히스토리로 변환합니다.

카드가 표시하는 단어는 옵션으로 전달되므로, ./pi에는 해당 두 상수를 제외한 예시 텍스트가 포함되지 않습니다. 이는 Pi Durable 1.1.0을 기준으로 작성되었습니다. examples/durable-member/의 지원 데스크가 모든 부분을 결합합니다.

버전

이 패키지는 Collie와는 별개의 자체 버전을 가지며, 지원하는 유선 버전을 지정합니다.

Collie는 하나의 유선 버전을 지원하며, 새 버전이 출시된 후 한 번의 마이너 릴리스 동안은 직전 버전을 허용합니다. Collie가 사용자의 버전 중 어느 것도 지원하지 않는 경우, 코어는 warn을(를) 통해 버전당 한 줄씩 작성합니다(예: collie: Collie speaks wire v2, this durable agent speaks v1. Update the agent's SDK, or Collie.). Phone은 durable agent의 홈에 Collie 자체의 표현으로 불일치를 표시합니다. 더 오래된 쪽을 업데이트하십시오.

패키지는 최신(latest)이 아닌 npm dist-tag experimental로 배포됩니다. durable 유선 버전이 종료에 도달하면 패키지는 지원 중단됩니다(ADR 0105).