@anhlp/alp-protocol 0.0.0-beta.1

package/src/connection.ts

@@ -0,0 +1,9 @@
+import type { Envelope } from './events.js';
+export type DaemonConnection = {
+  request<T = any>(method: string, params?: unknown): Promise<T>;
+  onEvent(listener: (envelope: Envelope) => void): () => void;
+  onClose(listener: (error: Error) => void): () => void;
+  close(): void;
+  /** True once the connection is gone; socket clients report it, in-process ones may not. */
+  readonly closed?: boolean;
+};

package/src/contract-v1.js

@@ -0,0 +1,2 @@
+// Generated by scripts/generate.mjs from schema/methods-v1.json; do not edit.
+export const METHODS_V1 = {"$schema":"http://json-schema.org/draft-07/schema#","$id":"https://alp.dev/schemas/methods-v1.json","protocolVersion":1,"errors":{"parseError":-32700,"invalidRequest":-32600,"methodNotFound":-32601,"invalidParams":-32602,"failed":1000,"notFound":1001,"forbidden":1003,"conflict":1004,"unavailable":1005,"protocol":1006},"capabilities":{"attach.after":"session.attach accepts `after` and answers `cursor`/`reset`; envelopes kept in a tree timeline carry `cursor`.","prompt.receipts":"session.prompt is answered at most once per (sessionId, clientMessageId) from a durable receipt; repeats answer the first outcome or outcome_unknown.","extension.methods":"extension.register/unregister, and the daemon sends extension.invoke requests to the owning connection.","team":"team.list: the teams a project can use, from the daemon host's built-ins, library and project.","task":"task.list, task.create, task.update and task.gate.resolve on a project's .alp/tasks, written by the daemon under the task lock.","library":"library.list/get/save/delete/duplicate/rename, library.skills.set and library.models on the daemon user's library and a project's .alp overrides; secrets are redacted on read.","settings.language":"settings.language.get/set: the language the daemon user reads, in the daemon's ALP_HOME/settings.json."},"methods":{"assignment.recall":{"x-alp":{"effect":"mutation","scope":{"kind":"project","param":"projectRoot","required":false,"alternatives":["assignmentId","taskId"]},"idempotent":false,"risks":["model call"]},"params":{"type":"object","properties":{"assignmentId":{"type":"string"},"taskId":{"type":"string"},"projectRoot":{"type":"string"},"question":{"type":"string"}},"required":["question"],"additionalProperties":true},"result":{"type":"object","properties":{"assignmentId":{"type":"string"},"agent":{"type":"string"},"taskId":{"type":"string"},"finishedAt":{"type":"string"},"answer":{"type":"string"}},"required":["assignmentId","agent","finishedAt","answer"],"additionalProperties":true}},"board.list":{"x-alp":{"effect":"query","scope":{"kind":"project","param":"projectRoot","required":true},"idempotent":true},"params":{"type":"object","properties":{"projectRoot":{"type":"string"}},"required":["projectRoot"],"additionalProperties":true},"result":{"type":"object","properties":{"pins":{"type":"array","items":{"$ref":"#/$defs/pin"}}},"required":["pins"],"additionalProperties":true}},"catalog.get":{"x-alp":{"effect":"query","scope":{"kind":"host"},"idempotent":true},"params":{"type":"object","properties":{},"required":[],"additionalProperties":true},"result":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object"}},"modes":{"type":"array","items":{"type":"object"}},"thinkingOptions":{},"defaultModel":{"type":"string"}},"required":["models","modes","defaultModel"],"additionalProperties":true}},"daemon.hello":{"x-alp":{"effect":"query","scope":{"kind":"connection"},"idempotent":true},"params":{"type":"object","properties":{"protocolVersion":{"const":1},"client":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}},"required":["name","version"],"additionalProperties":true},"capabilities":{"type":"array","items":{"type":"string"}}},"required":["protocolVersion"],"additionalProperties":true},"result":{"type":"object","properties":{"protocolVersion":{"const":1},"daemonVersion":{"type":"string"},"pid":{"type":"integer"},"capabilities":{"type":"array","items":{"type":"string"}}},"required":["protocolVersion"],"additionalProperties":true}},"daemon.pause":{"x-alp":{"effect":"mutation","scope":{"kind":"host"},"idempotent":true,"risks":["admin"]},"params":{"type":"object","properties":{"runtime":{"enum":["codex","claude","acp","antigravity"]},"now":{"type":"boolean"},"reason":{"type":"string"}},"required":[],"additionalProperties":true},"result":{"$ref":"#/$defs/pauseState"}},"daemon.pauses":{"x-alp":{"effect":"query","scope":{"kind":"host"},"idempotent":true},"params":{"type":"object","properties":{},"required":[],"additionalProperties":true},"result":{"$ref":"#/$defs/pauseState"}},"daemon.resume":{"x-alp":{"effect":"mutation","scope":{"kind":"host"},"idempotent":true,"risks":["admin"]},"params":{"type":"object","properties":{"runtime":{"enum":["codex","claude","acp","antigravity"]}},"required":[],"additionalProperties":true},"result":{"$ref":"#/$defs/pauseState"}},"daemon.shutdown":{"x-alp":{"effect":"mutation","scope":{"kind":"host"},"idempotent":true,"risks":["admin"]},"params":{"type":"object","properties":{},"required":[],"additionalProperties":true},"result":{"type":"object","properties":{},"required":[],"additionalProperties":true}},"daemon.status":{"x-alp":{"effect":"query","scope":{"kind":"host"},"idempotent":true},"params":{"type":"object","properties":{},"required":[],"additionalProperties":true},"result":{"type":"object","properties":{"pid":{"type":"integer"},"startedAt":{"type":"string"},"version":{"type":"string"},"protocolVersion":{"type":"integer"},"sessions":{"type":"integer"},"questions":{"type":"integer"},"previousExit":{"type":"object","properties":{"kind":{"enum":["clean","crash"]},"at":{"type":"string"}},"required":["kind"],"additionalProperties":true},"persistence":{"type":"object"},"health":{"$ref":"#/$defs/health"}},"required":["pid","startedAt","version","protocolVersion","sessions","questions","health"],"additionalProperties":true}},"daemon.usage":{"x-alp":{"effect":"query","scope":{"kind":"host"},"idempotent":true,"risks":["refresh asks every provider (spawns on the daemon host)"]},"params":{"type":"object","properties":{"refresh":{"type":"boolean"}},"required":[],"additionalProperties":true},"result":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object"}}},"required":["providers"],"additionalProperties":true}},"extension.register":{"x-alp":{"effect":"mutation","scope":{"kind":"connection"},"idempotent":false,"risks":["admin"]},"params":{"type":"object","properties":{"method":{"type":"string"}},"required":["method"],"additionalProperties":true},"result":{"type":"object","properties":{"registered":{"type":"string"}},"required":["registered"],"additionalProperties":true}},"extension.unregister":{"x-alp":{"effect":"mutation","scope":{"kind":"connection"},"idempotent":false,"risks":["admin"]},"params":{"type":"object","properties":{"method":{"type":"string"}},"required":["method"],"additionalProperties":true},"result":{"type":"object","properties":{"unregistered":{"type":"string"}},"required":["unregistered"],"additionalProperties":true}},"library.delete":{"x-alp":{"effect":"mutation","capability":"library","scope":{"kind":"library-or-project","param":"projectRoot","selector":"scope"},"idempotent":false},"params":{"type":"object","properties":{"kind":{"$ref":"#/$defs/libraryKind"},"name":{"$ref":"#/$defs/entryName"},"scope":{"$ref":"#/$defs/libraryScope"},"projectRoot":{"$ref":"#/$defs/projectRoot"},"revision":{"type":"string"}},"required":["kind","name","scope"],"additionalProperties":true},"result":{"type":"object","properties":{"removed":{"const":true},"now":{"enum":["builtin","library"]}},"required":["removed"],"additionalProperties":true}},"library.duplicate":{"x-alp":{"effect":"mutation","capability":"library","scope":{"kind":"library-or-project","param":"projectRoot","selector":"scope","reads":["builtin","library"]},"idempotent":false,"risks":["exec-config when kind is mcp, hooks or providers"]},"params":{"type":"object","properties":{"kind":{"$ref":"#/$defs/libraryKind"},"from":{"$ref":"#/$defs/entryName"},"to":{"$ref":"#/$defs/entryName"},"scope":{"$ref":"#/$defs/libraryScope"},"projectRoot":{"$ref":"#/$defs/projectRoot"}},"required":["kind","from","to","scope"],"additionalProperties":true},"result":{"type":"object","properties":{"revision":{"$ref":"#/$defs/libraryRevision"}},"required":["revision"],"additionalProperties":true}},"library.get":{"x-alp":{"effect":"query","capability":"library","scope":{"kind":"project","param":"projectRoot","required":false,"reads":["builtin","library"]},"idempotent":true,"redacts":["mcp /server/env/*","mcp /server/headers/*","providers /provider/env/*"]},"params":{"type":"object","properties":{"kind":{"$ref":"#/$defs/libraryKind"},"name":{"$ref":"#/$defs/entryName"},"projectRoot":{"$ref":"#/$defs/projectRoot"},"scope":{"$ref":"#/$defs/libraryScope"}},"required":["kind","name"],"additionalProperties":true},"result":{"type":"object","properties":{"kind":{"$ref":"#/$defs/libraryKind"},"name":{"type":"string"},"source":{"$ref":"#/$defs/librarySource"},"overrides":{"$ref":"#/$defs/librarySource"},"content":{"type":"object"},"revision":{"$ref":"#/$defs/libraryRevision"},"usedBy":{"type":"array","items":{"type":"string"}},"librarySkills":{"type":"array","items":{"type":"string"}},"secrets":{"type":"array","items":{"type":"string"}}},"required":["kind","name","source","content","revision","usedBy"],"additionalProperties":true}},"library.list":{"x-alp":{"effect":"query","capability":"library","scope":{"kind":"project","param":"projectRoot","required":false,"reads":["builtin","library"]},"idempotent":true},"params":{"type":"object","properties":{"kind":{"$ref":"#/$defs/libraryKind"},"projectRoot":{"$ref":"#/$defs/projectRoot"}},"required":["kind"],"additionalProperties":true},"result":{"type":"object","properties":{"projectRoot":{"type":["string","null"]},"entries":{"type":"array","items":{"$ref":"#/$defs/libraryEntryRow"}}},"required":["projectRoot","entries"],"additionalProperties":true}},"library.models":{"x-alp":{"effect":"query","capability":"library","scope":{"kind":"host"},"idempotent":true},"params":{"type":"object","properties":{},"required":[],"additionalProperties":true},"result":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"efforts":{"type":"array","items":{"type":"string"}},"effort":{"type":"string"}},"required":["id","label","efforts"],"additionalProperties":true}}},"required":["models"],"additionalProperties":true}},"library.rename":{"x-alp":{"effect":"mutation","capability":"library","scope":{"kind":"library-or-project","param":"projectRoot","selector":"scope"},"idempotent":false,"risks":["exec-config when kind is mcp, hooks or providers"]},"params":{"type":"object","properties":{"kind":{"$ref":"#/$defs/libraryKind"},"from":{"$ref":"#/$defs/entryName"},"to":{"$ref":"#/$defs/entryName"},"scope":{"$ref":"#/$defs/libraryScope"},"projectRoot":{"$ref":"#/$defs/projectRoot"}},"required":["kind","from","to","scope"],"additionalProperties":true},"result":{"type":"object","properties":{"revision":{"$ref":"#/$defs/libraryRevision"}},"required":["revision"],"additionalProperties":true}},"library.save":{"x-alp":{"effect":"mutation","capability":"library","scope":{"kind":"library-or-project","param":"projectRoot","selector":"scope"},"idempotent":"with revision (a repeat fails revision_conflict)","risks":["exec-config when kind is mcp, hooks or providers, or agents naming mcp/hooks/provider","writes every known project's .alp/settings.json when kind is teams and sync is known-projects"]},"params":{"type":"object","properties":{"kind":{"$ref":"#/$defs/libraryKind"},"name":{"$ref":"#/$defs/entryName"},"scope":{"$ref":"#/$defs/libraryScope"},"projectRoot":{"$ref":"#/$defs/projectRoot"},"content":{"type":"object"},"revision":{"$ref":"#/$defs/libraryRevision"},"sync":{"enum":["none","known-projects"]}},"required":["kind","name","scope","content"],"additionalProperties":true},"result":{"type":"object","properties":{"revision":{"$ref":"#/$defs/libraryRevision"},"syncedProjects":{"type":"integer","minimum":0},"syncErrors":{"type":"array","items":{"type":"string"}}},"required":["revision"],"additionalProperties":true}},"library.skills.set":{"x-alp":{"effect":"mutation","capability":"library","scope":{"kind":"host"},"writes":["ALP_HOME/role-skills.json"],"idempotent":true},"params":{"type":"object","properties":{"agent":{"$ref":"#/$defs/entryName"},"skills":{"type":"array","items":{"$ref":"#/$defs/entryName"},"maxItems":100}},"required":["agent","skills"],"additionalProperties":true},"result":{"type":"object","properties":{"skills":{"type":"array","items":{"type":"string"}}},"required":["skills"],"additionalProperties":true}},"question.answer":{"x-alp":{"effect":"mutation","scope":{"kind":"question","param":"questionId","prefix":true},"idempotent":false},"params":{"type":"object","properties":{"questionId":{"type":"string"},"text":{"type":"string"},"dismiss":{"type":"boolean"},"reason":{"type":"string"}},"required":["questionId"],"additionalProperties":true},"result":{"type":"object","properties":{"questionId":{"type":"string"}},"required":["questionId"],"additionalProperties":true}},"question.list":{"x-alp":{"effect":"query","scope":{"kind":"project","param":"projectRoot","required":false},"idempotent":true},"params":{"type":"object","properties":{"projectRoot":{"type":"string"}},"required":[],"additionalProperties":true},"result":{"type":"object","properties":{"questions":{"type":"array","items":{"$ref":"#/$defs/question"}}},"required":["questions"],"additionalProperties":true}},"session.archive":{"x-alp":{"effect":"mutation","scope":{"kind":"session","param":"sessionId"},"idempotent":true},"params":{"type":"object","properties":{"sessionId":{"type":"string"},"archived":{"type":"boolean"}},"required":["sessionId"],"additionalProperties":true},"result":{"type":"object","properties":{"session":{"$ref":"#/$defs/sessionSummary"}},"required":["session"],"additionalProperties":true}},"session.attach":{"x-alp":{"effect":"query","scope":{"kind":"session","param":"sessionId"},"idempotent":true},"params":{"type":"object","properties":{"sessionId":{"type":"string"},"replay":{"type":"boolean"},"after":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["sessionId"],"additionalProperties":true},"result":{"type":"object","properties":{"session":{"$ref":"#/$defs/sessionSummary"},"cursor":{"type":"integer","minimum":0,"maximum":9007199254740991},"reset":{"const":true}},"required":["session","cursor"],"additionalProperties":true}},"session.close":{"x-alp":{"effect":"mutation","scope":{"kind":"session","param":"sessionId"},"idempotent":false},"params":{"type":"object","properties":{"sessionId":{"type":"string"}},"required":["sessionId"],"additionalProperties":true},"result":{"type":"object","properties":{},"required":[],"additionalProperties":true}},"session.configure":{"x-alp":{"effect":"mutation","scope":{"kind":"session","param":"sessionId"},"idempotent":true},"params":{"type":"object","properties":{"sessionId":{"type":"string"},"mode":{"type":"string"}},"required":["sessionId"],"additionalProperties":true},"result":{"type":"object","properties":{"session":{"$ref":"#/$defs/session"}},"required":["session"],"additionalProperties":true}},"session.create":{"x-alp":{"effect":"mutation","scope":{"kind":"project","param":"spec.cwd"},"idempotent":false,"risks":["exec: spec.env and stdio spec.mcpServers run on the daemon host","spec.workdir/writeRoot/copy*/restore/keepThread are internal"]},"params":{"type":"object","properties":{"sessionId":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"},"spec":{"$ref":"#/$defs/spec"},"history":{"enum":["skip","replay"]},"delegation":{"type":"boolean"},"resume":{"type":"boolean"}},"required":["spec"],"additionalProperties":true},"result":{"type":"object","properties":{"session":{"$ref":"#/$defs/session"},"attached":{"type":"boolean"},"resumed":{"const":true},"durable":{"type":"boolean"}},"required":["session","attached"],"additionalProperties":true}},"session.get":{"x-alp":{"effect":"query","scope":{"kind":"session","param":"sessionId"},"idempotent":true},"params":{"type":"object","properties":{"sessionId":{"type":"string"}},"required":["sessionId"],"additionalProperties":true},"result":{"type":"object","properties":{"session":{"$ref":"#/$defs/sessionSummary"}},"required":["session"],"additionalProperties":true}},"session.interrupt":{"x-alp":{"effect":"mutation","scope":{"kind":"session","param":"sessionId"},"idempotent":true},"params":{"type":"object","properties":{"sessionId":{"type":"string"}},"required":["sessionId"],"additionalProperties":true},"result":{"type":"object","properties":{},"required":[],"additionalProperties":true}},"session.list":{"x-alp":{"effect":"query","scope":{"kind":"project","param":"projectRoot","required":false},"idempotent":true},"params":{"type":"object","properties":{"projectRoot":{"type":"string"},"rootsOnly":{"type":"boolean"},"includeClosed":{"type":"boolean"},"includeArchived":{"type":"boolean"}},"required":[],"additionalProperties":true},"result":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/$defs/sessionSummary"}}},"required":["sessions"],"additionalProperties":true}},"session.log":{"x-alp":{"effect":"query","scope":{"kind":"session","param":"sessionId"},"idempotent":true},"params":{"type":"object","properties":{"sessionId":{"type":"string"}},"required":["sessionId"],"additionalProperties":true},"result":{"type":"object","properties":{"rootId":{"type":"string"},"entries":{"type":"array","items":{"type":"object"}}},"required":["rootId","entries"],"additionalProperties":true}},"session.message":{"x-alp":{"effect":"mutation","scope":{"kind":"session","param":"sessionId"},"idempotent":false},"params":{"type":"object","properties":{"sessionId":{"type":"string"},"text":{"type":"string"}},"required":["sessionId","text"],"additionalProperties":true},"result":{"type":"object","properties":{},"required":[],"additionalProperties":true}},"session.preview":{"x-alp":{"effect":"query","scope":{"kind":"project","param":"spec.cwd"},"idempotent":true},"params":{"type":"object","properties":{"spec":{"$ref":"#/$defs/spec"}},"required":["spec"],"additionalProperties":true},"result":{"type":"object","properties":{"preview":{"$ref":"#/$defs/preview"}},"required":["preview"],"additionalProperties":true}},"session.prompt":{"x-alp":{"effect":"mutation","scope":{"kind":"session","param":"sessionId"},"idempotent":"with prompt.receipts"},"params":{"type":"object","properties":{"sessionId":{"type":"string"},"clientMessageId":{"type":"string"},"delivery":{"enum":["auto","steer"]},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}},"required":["type"],"additionalProperties":true}}},"required":["sessionId","clientMessageId","content"],"additionalProperties":true},"result":{"type":"object","properties":{"outcome":{"enum":["accepted","failed"]},"error":{"$ref":"#/$defs/alpError"},"duplicate":{"type":"boolean"},"durable":{"type":"boolean"}},"required":[],"additionalProperties":true}},"session.release":{"x-alp":{"effect":"mutation","scope":{"kind":"session","param":"sessionId"},"idempotent":true},"params":{"type":"object","properties":{"sessionId":{"type":"string"}},"required":["sessionId"],"additionalProperties":true},"result":{"type":"object","properties":{"closed":{"type":"boolean"}},"required":["closed"],"additionalProperties":true}},"session.rename":{"x-alp":{"effect":"mutation","scope":{"kind":"session","param":"sessionId"},"idempotent":true},"params":{"type":"object","properties":{"sessionId":{"type":"string"},"title":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"}},"required":["sessionId","title"],"additionalProperties":true},"result":{"type":"object","properties":{"session":{"$ref":"#/$defs/sessionSummary"}},"required":["session"],"additionalProperties":true}},"session.status":{"x-alp":{"effect":"query","scope":{"kind":"session","param":"sessionId"},"idempotent":true},"params":{"type":"object","properties":{"sessionId":{"type":"string"}},"required":["sessionId"],"additionalProperties":true},"result":{"type":"object","properties":{"status":{"$ref":"#/$defs/treeStatus"}},"required":["status"],"additionalProperties":true}},"settings.language.get":{"x-alp":{"effect":"query","capability":"settings.language","scope":{"kind":"host"},"idempotent":true},"params":{"type":"object","properties":{},"required":[],"additionalProperties":true},"result":{"$ref":"#/$defs/languageSetting"}},"settings.language.set":{"x-alp":{"effect":"mutation","capability":"settings.language","scope":{"kind":"host"},"writes":["ALP_HOME/settings.json"],"idempotent":true},"params":{"type":"object","properties":{"language":{"anyOf":[{"type":"string","minLength":1,"maxLength":40,"pattern":"\\S"},{"type":"null"}]}},"required":["language"],"additionalProperties":true},"result":{"$ref":"#/$defs/languageSetting"}},"task.create":{"x-alp":{"effect":"mutation","capability":"task","scope":{"kind":"project","param":"projectRoot","required":true},"writes":["<projectRoot>/.alp/tasks"],"idempotent":"per requestId within one alpd process (10 minutes)"},"params":{"type":"object","properties":{"projectRoot":{"$ref":"#/$defs/projectRoot"},"title":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},"priority":{"type":"integer","minimum":0,"maximum":4},"requestId":{"type":"string","minLength":1,"maxLength":128}},"required":["projectRoot","title"],"additionalProperties":true},"result":{"type":"object","properties":{"id":{"$ref":"#/$defs/taskId"},"duplicate":{"const":true}},"required":["id"],"additionalProperties":true}},"task.gate.resolve":{"x-alp":{"effect":"mutation","capability":"task","scope":{"kind":"project","param":"projectRoot","required":true},"writes":["<projectRoot>/.alp/tasks"],"idempotent":false},"params":{"type":"object","properties":{"projectRoot":{"$ref":"#/$defs/projectRoot"},"id":{"$ref":"#/$defs/taskId"},"gate":{"type":"string","minLength":1,"maxLength":128},"note":{"type":"string","maxLength":2000},"ifRev":{"type":"integer","minimum":0}},"required":["projectRoot","id","gate"],"additionalProperties":true},"result":{"type":"object","properties":{"id":{"$ref":"#/$defs/taskId"},"status":{"type":"string"},"rev":{"type":"integer","minimum":0}},"required":["id","status","rev"],"additionalProperties":true}},"task.list":{"x-alp":{"effect":"query","capability":"task","scope":{"kind":"project","param":"projectRoot","required":true},"idempotent":true},"params":{"type":"object","properties":{"projectRoot":{"$ref":"#/$defs/projectRoot"}},"required":["projectRoot"],"additionalProperties":true},"result":{"type":"object","properties":{"projectRoot":{"type":"string"},"tasks":{"type":"array","items":{"$ref":"#/$defs/taskRow"}},"unreadable":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"error":{"type":"string"}},"required":["file","error"],"additionalProperties":true}},"revision":{"type":"string"}},"required":["projectRoot","tasks","unreadable","revision"],"additionalProperties":true}},"task.update":{"x-alp":{"effect":"mutation","capability":"task","scope":{"kind":"project","param":"projectRoot","required":true},"writes":["<projectRoot>/.alp/tasks"],"idempotent":false},"params":{"type":"object","properties":{"projectRoot":{"$ref":"#/$defs/projectRoot"},"id":{"$ref":"#/$defs/taskId"},"action":{"enum":["close","reopen"]},"note":{"type":"string","maxLength":2000},"ifRev":{"type":"integer","minimum":0}},"required":["projectRoot","id","action"],"additionalProperties":true},"result":{"type":"object","properties":{"id":{"$ref":"#/$defs/taskId"},"status":{"type":"string"},"rev":{"type":"integer","minimum":0},"landed":{"type":"string"}},"required":["id","status","rev"],"additionalProperties":true}},"team.list":{"x-alp":{"effect":"query","capability":"team","scope":{"kind":"project","param":"projectRoot","required":false,"reads":["builtin","library"]},"idempotent":true},"params":{"type":"object","properties":{"projectRoot":{"$ref":"#/$defs/projectRoot"}},"required":[],"additionalProperties":true},"result":{"type":"object","properties":{"projectRoot":{"type":["string","null"]},"teams":{"type":"array","items":{"$ref":"#/$defs/teamRow"}}},"required":["projectRoot","teams"],"additionalProperties":true}}},"$defs":{"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{}},"required":["code","message"],"additionalProperties":true},"session":{"type":"object","properties":{"id":{"type":"string"},"projectRoot":{"type":"string"},"agent":{"type":"string"},"runtime":{"enum":["claude","codex","acp","antigravity"]},"model":{"type":"string"},"mode":{"type":"string"},"thinking":{"type":"string"},"workflow":{"type":"object","properties":{"mode":{"type":"string"},"maxPeers":{"type":"integer"},"supervisor":{"type":"boolean"}},"required":["mode","maxPeers","supervisor"],"additionalProperties":true},"threadId":{"type":"string"},"persistent":{"type":"boolean"},"busy":{"type":"boolean"},"parentId":{"type":"string"},"toolCallId":{"type":"string"},"activeTurnId":{"type":"string"},"parked":{"type":"string"},"instructionsSha":{"type":"string"},"teamLabel":{"type":"string"}},"required":["id","projectRoot","agent","runtime","model","mode","thinking","workflow","threadId","persistent","busy"],"additionalProperties":true},"assignment":{"type":"object","properties":{"id":{"type":"string"},"agent":{"type":"string"},"mode":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":"string"},"worktree":{"type":"object","properties":{"branch":{"type":"string"},"path":{"type":"string"}},"required":["branch","path"],"additionalProperties":true}},"required":["id","agent","mode","status","startedAt"],"additionalProperties":true},"mail":{"type":"object","properties":{"id":{"type":"string"},"kind":{"enum":["question","answer","note","steer","result","stalled","board","checkin"]},"from":{"type":"string"},"assignment":{"type":"string"},"body":{"type":"string"},"replyTo":{"type":"string"},"result":{"type":"object"},"redelivered":{"type":"boolean"}},"required":["id","kind","from","assignment"],"additionalProperties":true},"pin":{"type":"object","properties":{"id":{"type":"string"},"project":{"type":"string"},"kind":{"enum":["claim","decision","finding"]},"body":{"type":"string"},"paths":{"type":"array","items":{"type":"string"}},"agent":{"type":"string"},"sessionId":{"type":"string"},"rootId":{"type":"string"},"at":{"type":"string"},"released":{"type":"string"},"task":{"type":"string"}},"required":["id","project","kind","body","agent","sessionId","rootId","at"],"additionalProperties":true},"question":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"rootId":{"type":"string"},"agent":{"type":"string"},"body":{"type":"string"},"options":{"type":"array","items":{"type":"string"}},"askedAt":{"type":"string"}},"required":["id","sessionId","rootId","agent","body","askedAt"],"additionalProperties":true},"spec":{"type":"object","properties":{"cwd":{"type":"string"},"agent":{"type":"string"},"model":{"type":"string"},"mode":{"type":"string"},"thinking":{"type":"string"},"persist":{"type":"boolean"},"restore":{"type":"object"}},"required":["cwd"],"additionalProperties":true},"item":{"anyOf":[{"$ref":"#/$defs/knownItem"},{"$ref":"#/$defs/unknownItem"}]},"event":{"anyOf":[{"$ref":"#/$defs/knownEvent"},{"$ref":"#/$defs/unknownEvent"}]},"envelope":{"type":"object","properties":{"sessionId":{"type":"string"},"epoch":{"type":"string"},"seq":{"type":"integer","minimum":0,"maximum":9007199254740991},"ts":{"type":"string"},"event":{"$ref":"#/$defs/event"},"cursor":{"type":"integer","minimum":1,"maximum":9007199254740991}},"required":["sessionId","epoch","seq","ts","event"],"additionalProperties":true},"request":{"type":"object","properties":{"jsonrpc":{"const":"2.0"},"id":{"anyOf":[{"type":"string","maxLength":128},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"method":{"type":"string"},"params":{"type":"object"}},"required":["jsonrpc","method","id"],"additionalProperties":true},"response":{"oneOf":[{"type":"object","properties":{"jsonrpc":{"const":"2.0"},"id":{"anyOf":[{"type":"string","maxLength":128},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"result":{}},"required":["jsonrpc","id","result"],"additionalProperties":true},{"type":"object","properties":{"jsonrpc":{"const":"2.0"},"id":{"anyOf":[{"type":"string","maxLength":128},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"error":{"$ref":"#/$defs/error"}},"required":["jsonrpc","id","error"],"additionalProperties":true}]},"notification":{"type":"object","properties":{"jsonrpc":{"const":"2.0"},"method":{"const":"event"},"params":{"$ref":"#/$defs/envelope"}},"required":["jsonrpc","method","params"],"additionalProperties":true},"knownEvent":{"oneOf":[{"type":"object","properties":{"type":{"const":"session.opened"},"session":{"$ref":"#/$defs/session"},"cwd":{"type":"string"},"effective":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string"}},"required":["model","thinking"],"additionalProperties":true}},"required":["type","session","cwd","effective"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"session.ready"}},"required":["type"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"session.updated"},"session":{"$ref":"#/$defs/session"}},"required":["type","session"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"session.closed"}},"required":["type"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"session.failed"},"error":{"$ref":"#/$defs/alpError"}},"required":["type","error"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"prompt.accepted"},"clientMessageId":{"type":"string"},"result":{"enum":["turn","steer"]},"turnId":{"type":"string"}},"required":["type","clientMessageId","result","turnId"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"prompt.failed"},"clientMessageId":{"type":"string"},"error":{"$ref":"#/$defs/alpError"}},"required":["type","clientMessageId","error"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"turn.started"},"turnId":{"type":"string"},"origin":{"enum":["user","wake","assignment","runtime"]}},"required":["type","turnId","origin"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"turn.ended"},"turnId":{"type":"string"},"state":{"enum":["completed","failed","canceled"]},"error":{"$ref":"#/$defs/alpError"}},"required":["type","turnId","state"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"item"},"item":{"$ref":"#/$defs/item"}},"required":["type","item"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"mail"},"mail":{"$ref":"#/$defs/mail"}},"required":["type","mail"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"assignment"},"assignment":{"$ref":"#/$defs/assignment"}},"required":["type","assignment"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"question"},"question":{"$ref":"#/$defs/question"}},"required":["type","question"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"question.resolved"},"questionId":{"type":"string"},"outcome":{"enum":["answered","dismissed","timeout","canceled"]},"answer":{"type":"string"}},"required":["type","questionId","outcome"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"pin"},"pin":{"$ref":"#/$defs/pin"}},"required":["type","pin"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"unpin"},"pinId":{"type":"string"},"reason":{"enum":["unpinned","session_ended"]}},"required":["type","pinId","reason"],"additionalProperties":true}]},"unknownEvent":{"type":"object","properties":{"type":{"type":"string","not":{"enum":["session.opened","session.ready","session.updated","session.closed","session.failed","prompt.accepted","prompt.failed","turn.started","turn.ended","item","mail","assignment","question","question.resolved","pin","unpin"]}}},"required":["type"],"additionalProperties":true},"knownItem":{"oneOf":[{"type":"object","properties":{"kind":{"const":"user_message"},"id":{"type":"string"},"text":{"type":"string"},"clientMessageId":{"type":"string"}},"required":["kind","id","text"],"additionalProperties":true},{"type":"object","properties":{"kind":{"const":"assistant_message"},"id":{"type":"string"},"text":{"type":"string"}},"required":["kind","id","text"],"additionalProperties":true},{"type":"object","properties":{"kind":{"const":"notice"},"id":{"type":"string"},"level":{"enum":["info","warning","error"]},"text":{"type":"string"}},"required":["kind","id","level","text"],"additionalProperties":true},{"type":"object","properties":{"kind":{"const":"compaction"},"id":{"type":"string"},"status":{"enum":["running","completed","failed"]},"trigger":{"type":"string"},"preTokens":{"type":"integer"},"postTokens":{"type":"integer"}},"required":["kind","id","status"],"additionalProperties":true},{"type":"object","properties":{"kind":{"const":"todo"},"id":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"status":{"enum":["pending","in_progress","completed"]}},"required":["id","text","status"],"additionalProperties":true}}},"required":["kind","id","items"],"additionalProperties":true},{"type":"object","properties":{"kind":{"const":"tool_call"},"id":{"type":"string"},"callId":{"type":"string"},"name":{"type":"string"},"status":{"enum":["running","completed","failed"]},"error":{"type":"string"},"detail":{"oneOf":[{"type":"object","properties":{"type":{"const":"shell"},"command":{"type":"string"},"cwd":{"type":"string"},"output":{"type":"string"},"exitCode":{"type":["integer","null"]}},"required":["type","command","output"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"unknown"},"input":{},"output":{}},"required":["type","input","output"],"additionalProperties":true}]}},"required":["kind","id","callId","name","status","detail"],"additionalProperties":true}]},"unknownItem":{"type":"object","properties":{"kind":{"type":"string","not":{"enum":["user_message","assistant_message","notice","compaction","todo","tool_call"]}},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":true},"alpError":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"],"additionalProperties":true},"sessionSummary":{"type":"object","properties":{"id":{"type":"string"},"projectRoot":{"type":"string"},"agent":{"type":"string"},"runtime":{"enum":["claude","codex","acp","antigravity"]},"model":{"type":"string"},"mode":{"type":"string"},"thinking":{"type":"string"},"workflow":{"type":"object","properties":{"mode":{"type":"string"},"maxPeers":{"type":"integer"},"supervisor":{"type":"boolean"}},"required":["mode","maxPeers","supervisor"],"additionalProperties":true},"threadId":{"type":"string"},"persistent":{"type":"boolean"},"busy":{"type":"boolean"},"parentId":{"type":"string"},"toolCallId":{"type":"string"},"activeTurnId":{"type":"string"},"parked":{"type":"string"},"instructionsSha":{"type":"string"},"teamLabel":{"type":"string"},"status":{"enum":["initializing","idle","running","error","closed"]},"title":{"type":"string"},"archived":{"type":"boolean"},"lastError":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","projectRoot","agent","runtime","model","mode","thinking","workflow","threadId","persistent","busy","status"],"additionalProperties":true},"pause":{"type":"object","properties":{"since":{"type":"string"},"by":{"type":"string"},"reason":{"type":"string"},"resetsAt":{"type":"string"},"checkedAt":{"type":"string"}},"required":["since","by","reason"],"additionalProperties":true},"pauseState":{"type":"object","properties":{"all":{"$ref":"#/$defs/pause"},"runtimes":{"type":"object","additionalProperties":{"$ref":"#/$defs/pause"}},"parked":{"type":"array","items":{"type":"object","properties":{"assignmentId":{"type":"string"},"agent":{"type":"string"},"runtime":{"type":"string"},"rootId":{"type":"string"},"reason":{"type":"string"},"since":{"type":"string"}},"required":["assignmentId","agent","runtime","rootId","reason","since"],"additionalProperties":true}}},"required":["runtimes","parked"],"additionalProperties":true},"preview":{"type":"object","properties":{"teams":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["id","label"],"additionalProperties":true}},"team":{"type":"string"},"teamLabel":{"type":"string"},"agent":{"type":"string"},"runtime":{"enum":["claude","codex","acp","antigravity"]},"model":{"type":"string"},"mode":{"type":"string"},"thinking":{"type":"string"}},"required":["teams","team","agent","runtime","model","mode","thinking"],"additionalProperties":true},"treeStatus":{"type":"object","properties":{"rootId":{"type":"string"},"sessions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"projectRoot":{"type":"string"},"agent":{"type":"string"},"runtime":{"enum":["claude","codex","acp","antigravity"]},"model":{"type":"string"},"mode":{"type":"string"},"thinking":{"type":"string"},"workflow":{"type":"object","properties":{"mode":{"type":"string"},"maxPeers":{"type":"integer"},"supervisor":{"type":"boolean"}},"required":["mode","maxPeers","supervisor"],"additionalProperties":true},"threadId":{"type":"string"},"persistent":{"type":"boolean"},"busy":{"type":"boolean"},"parentId":{"type":"string"},"toolCallId":{"type":"string"},"activeTurnId":{"type":"string"},"parked":{"type":"string"},"instructionsSha":{"type":"string"},"teamLabel":{"type":"string"},"state":{"enum":["running","waiting","waiting_parent","waiting_user","idle"]},"idleMs":{"type":"number"},"workdir":{"type":"string"},"unreadMail":{"type":"integer","minimum":0}},"required":["id","projectRoot","agent","runtime","model","mode","thinking","workflow","threadId","persistent","busy","state","idleMs","workdir","unreadMail"],"additionalProperties":true}},"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"requester":{"type":"string"},"isolation":{"enum":["shared","worktree"]},"idleMs":{"type":"number"}},"required":["id","requester","isolation","idleMs"],"additionalProperties":true}},"questions":{"type":"array","items":{"$ref":"#/$defs/question"}},"worktrees":{"type":"array","items":{"type":"object","properties":{"assignmentId":{"type":"string"},"requester":{"type":"string"},"agent":{"type":"string"},"branch":{"type":"string"},"files":{"type":"array","items":{"type":"string"}},"stat":{"type":"string"}},"required":["assignmentId","requester","agent","branch","files","stat"],"additionalProperties":true}},"leases":{"type":"array","items":{"type":"object","properties":{"checkout":{"type":"string"},"assignmentId":{"type":"string"},"agent":{"type":"string"}},"required":["checkout","assignmentId","agent"],"additionalProperties":true}},"claims":{"type":"array","items":{"$ref":"#/$defs/pin"}}},"required":["rootId","sessions","assignments","questions","worktrees","leases","claims"],"additionalProperties":true},"health":{"type":"object","properties":{"live":{"type":"boolean"},"ready":{"type":"boolean"},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"ok":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["id","ok"],"additionalProperties":true}}},"required":["live","ready","checks"],"additionalProperties":true},"projectRoot":{"type":"string","minLength":1,"maxLength":4096,"description":"An absolute, normalized path on the daemon host to a directory holding .alp/. Compared as is: the daemon never walks up to a parent."},"taskId":{"type":"string","pattern":"^t-[0-9a-f]{4,12}(?:\\.\\d+)*$"},"taskRow":{"type":"object","properties":{"id":{"$ref":"#/$defs/taskId"},"title":{"type":"string"},"type":{"type":"string"},"priority":{"type":"integer"},"status":{"enum":["open","in_progress","review","closed"]},"rev":{"type":"integer","minimum":0},"parent":{"type":"string"},"assignee":{"type":"string"},"ready":{"type":"boolean"},"blockedBy":{"type":"array","items":{"type":"string"}},"waits":{"type":"array","items":{"type":"string"}},"approvals":{"type":"array","items":{"type":"object","properties":{"gate":{"type":"string"},"note":{"type":"string"}},"required":["gate","note"],"additionalProperties":true}},"handoff":{"type":"object","properties":{"outcome":{"type":"string"},"summary":{"type":"string"},"agent":{"type":"string"}},"required":["outcome","summary"],"additionalProperties":true},"closed":{"type":"object","properties":{"reason":{"type":"string"},"summary":{"type":"string"},"at":{"type":"string"}},"required":["reason","at"],"additionalProperties":true},"description":{"type":"string"},"labels":{"type":"array","items":{"type":"string"}},"paths":{"type":"array","items":{"type":"string"}},"progress":{"type":"object","properties":{"done":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0}},"required":["done","total"],"additionalProperties":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","type","priority","status","rev","ready","updatedAt"],"additionalProperties":true},"libraryKind":{"enum":["agents","skills","mcp","hooks","teams","providers"]},"libraryScope":{"enum":["library","project"]},"librarySource":{"enum":["builtin","library","project"]},"entryName":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_.-]+$","not":{"enum":[".",".."]}},"libraryRevision":{"type":["string","null"]},"libraryEntryRow":{"type":"object","properties":{"name":{"type":"string"},"source":{"$ref":"#/$defs/librarySource"},"overrides":{"$ref":"#/$defs/librarySource"},"description":{"type":"string"},"usedBy":{"type":"array","items":{"type":"string"}}},"required":["name","source"],"additionalProperties":true},"secretMarker":{"type":"object","properties":{"$secret":{"const":"keep"}},"required":["$secret"],"additionalProperties":false,"description":"Stands for a stored secret value: read results carry it in place of the value; a save that sends it back keeps the stored value."},"languageSetting":{"type":"object","properties":{"language":{"type":["string","null"]},"applies":{"type":"string"},"default":{"type":"string"}},"required":["language","applies","default"],"additionalProperties":true},"teamRow":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"source":{"$ref":"#/$defs/librarySource"},"overrides":{"$ref":"#/$defs/librarySource"},"error":{"type":"string"}},"required":["id","source"],"additionalProperties":true}}};

package/src/contract.js

@@ -0,0 +1,44 @@
+// The normative v1 contract (schema/methods-v1.json) as data, with checks over it.
+// Pure JavaScript with no Node or runtime imports: daemons, clients and conformance runners share it.
+import { METHODS_V1 } from './contract-v1.js';
+import { validateSchema } from './validate.js';
+
+export { METHODS_V1, validateSchema };
+
+/** Capabilities a v1 daemon may list in its daemon.hello result; the schema documents each. */
+export const CAPABILITIES = Object.freeze(Object.keys(METHODS_V1.capabilities));
+
+/** @param {string} method */
+const methodOf = method => Object.hasOwn(METHODS_V1.methods, method) ? /** @type {any} */ (METHODS_V1.methods)[method] : undefined;
+
+/**
+ * Checks the params of a v1 method. Absent params count as `{}`.
+ * @param {string} method
+ * @param {unknown} params
+ * @returns {import('./validate.js').SchemaIssue[] | undefined} undefined for a method v1 does not define
+ */
+export function validateParams(method, params) {
+  const entry = methodOf(method);
+  return entry && validateSchema(entry.params, params === undefined ? {} : params, METHODS_V1);
+}
+
+/**
+ * Checks the result of a v1 method.
+ * @param {string} method
+ * @param {unknown} result
+ * @returns {import('./validate.js').SchemaIssue[] | undefined} undefined for a method v1 does not define
+ */
+export function validateResult(method, result) {
+  const entry = methodOf(method);
+  return entry && validateSchema(entry.result, result, METHODS_V1);
+}
+
+/**
+ * Checks one shared definition, such as `envelope`, `error` or `request`.
+ * @param {string} name
+ * @param {unknown} value
+ */
+export function validateDefinition(name, value) {
+  if (!Object.hasOwn(METHODS_V1.$defs, name)) throw new Error(`No definition ${name}`);
+  return validateSchema({ $ref: `#/$defs/${name}` }, value, METHODS_V1);
+}

package/src/dto.ts

@@ -0,0 +1,78 @@
+export type RuntimeKind = 'codex' | 'claude' | 'acp' | 'antigravity';
+
+export type MailKind = 'question' | 'answer' | 'note' | 'steer' | 'result' | 'stalled' | 'board' | 'checkin';
+
+export type MailEvent = {
+  id: string;
+  kind: MailKind;
+  from: string;
+  assignment: string;
+  body?: string;
+  replyTo?: string;
+  result?: Record<string, unknown>;
+  redelivered?: boolean;
+  /** Informational; never steers or wakes a session by itself. */
+  passive?: boolean;
+  /** Delivered between turns, never steered into a running one or taken by alp_wait. */
+  defer?: boolean;
+  /** Turn that received the event; acknowledged when that turn completes. */
+  deliveredTurn?: string;
+};
+
+
+export type PinKind = 'claim' | 'decision' | 'finding';
+
+export type Pin = {
+  id: string;
+  /** The project root the board belongs to. */
+  project: string;
+  kind: PinKind;
+  body: string;
+  /** Project-relative files or directories, or absolute paths in an external write root; required for claims. */
+  paths?: string[];
+  agent: string;
+  sessionId: string;
+  rootId: string;
+  at: string;
+  /** When a claim ended, or any pin was taken down. */
+  released?: string;
+  /** The task the claiming assignment works on. */
+  task?: string;
+};
+
+/** A project's task as task screens show it (schema/methods-v1.json `taskRow`). */
+export type TaskRow = {
+  id: string;
+  title: string;
+  type: string;
+  priority: number;
+  status: 'open' | 'in_progress' | 'review' | 'closed';
+  /** Changes with every write; task.update and task.gate.resolve refuse an older one given as `ifRev`. */
+  rev: number;
+  parent?: string;
+  assignee?: string;
+  ready: boolean;
+  blockedBy?: string[];
+  waits?: string[];
+  approvals?: Array<{ gate: string; note: string }>;
+  handoff?: { outcome: string; summary: string; agent?: string };
+  closed?: { reason: string; summary?: string; at: string };
+  description?: string;
+  labels?: string[];
+  paths?: string[];
+  progress?: { done: number; total: number };
+  createdAt?: string;
+  updatedAt: string;
+};
+
+export type LibraryKind = 'agents' | 'skills' | 'mcp' | 'hooks' | 'teams' | 'providers';
+export type LibraryScope = 'library' | 'project';
+export type LibrarySource = 'builtin' | 'library' | 'project';
+/** Letters, digits, '.', '_' or '-', not '.' or '..'. */
+export type EntryName = string;
+export type LibraryEntryRow = { name: string; source: LibrarySource; overrides?: LibrarySource; description?: string; usedBy?: string[] };
+export type TeamRow = { id: string; label?: string; description?: string; source: LibrarySource; overrides?: LibrarySource; error?: string };
+/** language null: unset, so `default` applies. */
+export type LanguageSetting = { language: string | null; applies: string; default: string };
+/** Stands for a stored secret in library.get content; sent back in library.save it keeps the stored value. */
+export type SecretMarker = { $secret: 'keep' };

package/src/events.ts

@@ -0,0 +1,127 @@
+import type { RuntimeKind, MailEvent, Pin } from './dto.js';
+
+/** Provider-neutral session events (plans/reference/ALPD.md §4). Viewers project them; the runtime never imports a viewer. */
+
+/** `code: 'outcome_unknown'` when the provider may or may not have received the request (ALPD §66). */
+export type AlpError = { message: string; code?: string };
+
+export type TimelineItem =
+  | { kind: 'user_message'; id: string; text: string; clientMessageId?: string }
+  | { kind: 'assistant_message'; id: string; text: string }
+  /** Something about ALP as a whole the user should see, such as a usage limit or a pause (ALPD §29). */
+  | { kind: 'notice'; id: string; level: 'info' | 'warning' | 'error'; text: string }
+  /** The runtime compacting the session's context (ALPD §57). */
+  | { kind: 'compaction'; id: string; status: 'running' | 'completed' | 'failed'; trigger?: 'auto' | 'manual'; preTokens?: number; postTokens?: number }
+  /** The tasks a root's tree created or worked on (plans/reference/ALPD.md §21). */
+  | { kind: 'todo'; id: string; items: Array<{ id: string; text: string; status: 'pending' | 'in_progress' | 'completed' }> }
+  | {
+      kind: 'tool_call';
+      id: string;
+      callId: string;
+      name: string;
+      status: 'running' | 'completed' | 'failed';
+      error?: string;
+      detail:
+        | { type: 'shell'; command: string; cwd?: string; output: string; exitCode?: number | null }
+        | { type: 'unknown'; input: unknown; output: unknown };
+    };
+
+export type SessionSnapshot = {
+  id: string;
+  projectRoot: string;
+  agent: string;
+  runtime: RuntimeKind;
+  model: string;
+  mode: string;
+  thinking: string;
+  workflow: { mode: string; maxPeers: number; supervisor: boolean };
+  /** The label of the session's team, such as Phở (ALPD §42); absent for a custom graph. */
+  teamLabel?: string;
+  threadId: string;
+  /** The native thread is kept and the session can be resumed. */
+  persistent: boolean;
+  parentId?: string;
+  /** The requester's tool call that started this assignment. */
+  toolCallId?: string;
+  activeTurnId?: string;
+  /** A turn, an assignment, a child, or undelivered mail keeps the session working. */
+  busy: boolean;
+  /** Why a usage limit or a pause parked this assignment (ALPD §29). */
+  parked?: string;
+  /** A digest of the instructions the session runs with (ALPD §34). */
+  instructionsSha?: string;
+};
+
+export type AssignmentSnapshot = {
+  id: string;
+  agent: string;
+  mode: string;
+  status: string;
+  startedAt: string;
+  /** An isolated assignment's branch and working directory. */
+  worktree?: { branch: string; path: string };
+};
+
+/** runtime: a turn the native runtime started by itself, such as Claude after a background task ended. */
+export type TurnOrigin = 'user' | 'wake' | 'assignment' | 'runtime';
+
+/** A question an agent asked the user with alp_ask to: "user". */
+export type UserQuestion = {
+  id: string;
+  sessionId: string;
+  rootId: string;
+  agent: string;
+  body: string;
+  options?: string[];
+  askedAt: string;
+};
+
+export type SessionState = 'running' | 'waiting' | 'waiting_parent' | 'waiting_user' | 'idle';
+
+/** A live tree at one moment, for dashboards (plans/reference/ALPD.md §17). */
+export type TreeStatus = {
+  rootId: string;
+  sessions: Array<SessionSnapshot & { state: SessionState; idleMs: number; workdir: string; unreadMail: number }>;
+  assignments: Array<AssignmentSnapshot & { requester: string; isolation: 'shared' | 'worktree'; idleMs: number }>;
+  questions: UserQuestion[];
+  /** Finished worktree assignments waiting for alp_merge or alp_discard. */
+  worktrees: Array<{ assignmentId: string; requester: string; agent: string; branch: string; files: string[]; stat: string }>;
+  leases: Array<{ checkout: string; assignmentId: string; agent: string }>;
+  /** Live claims on the project board held by this tree's sessions. */
+  claims: Pin[];
+};
+
+export type AlpEvent =
+  | { type: 'session.opened'; session: SessionSnapshot; cwd: string; effective: { model: string; thinking: string } }
+  | { type: 'session.ready' }
+  | { type: 'session.updated'; session: SessionSnapshot }
+  | { type: 'session.closed' }
+  | { type: 'session.failed'; error: AlpError }
+  | { type: 'prompt.accepted'; clientMessageId: string; result: 'turn' | 'steer'; turnId: string }
+  | { type: 'prompt.failed'; clientMessageId: string; error: AlpError }
+  | { type: 'turn.started'; turnId: string; origin: TurnOrigin }
+  | { type: 'turn.ended'; turnId: string; state: 'completed' | 'failed' | 'canceled'; error?: AlpError }
+  | { type: 'item'; item: TimelineItem }
+  | { type: 'mail'; mail: Omit<MailEvent, 'passive' | 'deliveredTurn'> }
+  | { type: 'assignment'; assignment: AssignmentSnapshot }
+  | { type: 'question'; question: UserQuestion }
+  | { type: 'question.resolved'; questionId: string; outcome: 'answered' | 'dismissed' | 'timeout' | 'canceled'; answer?: string }
+  /** Emitted on the session that pinned it (plans/reference/ALPD.md §18). */
+  | { type: 'pin'; pin: Pin }
+  | { type: 'unpin'; pinId: string; reason: 'unpinned' | 'session_ended' };
+
+export type Envelope = {
+  sessionId: string;
+  /** Random per runtime instance; a cursor from another epoch is stale. */
+  epoch: string;
+  /** Strictly increasing per session. */
+  seq: number;
+  /**
+   * Position in its tree's stored timeline, set by alpd on the events it keeps: strictly
+   * increasing per root across restarts, so `session.attach { after }` replays only what
+   * a reconnecting client missed (ALPD §66).
+   */
+  cursor?: number;
+  ts: string;
+  event: AlpEvent;
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './wire.js';
+export type * from './dto.js';
+export type * from './events.js';
+export type * from './connection.js';
+export type * from './session.js';
+export type * from './rpc.js';

package/src/public.js

@@ -0,0 +1,2 @@
+// Runtime API is plain ESM so source clients also work before the first build.
+export * from './wire.js';

package/src/rpc.ts

@@ -0,0 +1,102 @@
+/** Portable JSON-RPC structures; implementations and provider SDKs stay outside protocol. */
+import type { RuntimeKind, Pin } from './dto.js';
+import type { AlpError, Envelope, SessionSnapshot, TreeStatus, UserQuestion } from './events.js';
+import type { PauseState, PromptContent, RecallAnswer, SessionPreview, SessionSpec, SessionSummary } from './session.js';
+import type { EntryName, LanguageSetting, LibraryEntryRow, LibraryKind, LibraryScope, LibrarySource, TaskRow, TeamRow } from './dto.js';
+
+export type RpcId = string | number | null;
+export type RpcErrorData = { code: number; message: string; data?: unknown };
+export type RpcRequest = { jsonrpc: '2.0'; id?: RpcId; method: string; params?: Record<string, unknown> };
+export type RpcResponse = { jsonrpc: '2.0'; id: RpcId } & ({ result: unknown; error?: never } | { error: RpcErrorData; result?: never });
+export type EventNotification = { jsonrpc: '2.0'; method: 'event'; params: Envelope };
+
+/** Names a daemon may list in its daemon.hello result (schema/methods-v1.json `capabilities`). */
+export type Capability = 'attach.after' | 'prompt.receipts' | 'extension.methods' | 'team' | 'task' | 'library' | 'settings.language';
+
+/** `data.reason` values alpd sets on errors (docs/protocol/alp-json-rpc-v1.md §5.3). */
+export type ErrorReason =
+  | 'hello_required' | 'protocol_version' | 'invalid_params' | 'invalid_id' | 'batch_unsupported' | 'frame_too_large'
+  | 'response_too_large' | 'persistence_failed' | 'outcome_unknown' | 'key_conflict'
+  // Project, task and library methods (docs/protocol/alp-json-rpc-v1.md §5.3).
+  | 'invalid_path' | 'invalid_scope' | 'invalid_entry' | 'secret_marker' | 'not_alp_project' | 'unknown_task' | 'not_found'
+  | 'unsafe_path' | 'revision_conflict' | 'task_state' | 'in_use' | 'busy' | 'unreadable';
+
+type Empty = Record<string, never>;
+
+/**
+ * Params and result of every v1 method, as schema/methods-v1.json defines them; the protocol tests
+ * type-check the golden fixtures against this map, so the two cannot drift. Results may carry
+ * properties this map does not name: clients ignore them.
+ */
+export type RpcMethodMap = {
+  'daemon.hello': { params: { protocolVersion: 1; client?: { name: string; version: string }; capabilities?: string[] }; result: { protocolVersion: 1; daemonVersion?: string; pid?: number; capabilities?: string[] } };
+  'daemon.status': {
+    params: Empty;
+    result: {
+      pid: number; startedAt: string; version: string; protocolVersion: number; sessions: number; questions: number;
+      previousExit?: { kind: 'clean' | 'crash'; at?: string };
+      persistence?: Record<string, unknown>;
+      health: { live: boolean; ready: boolean; checks: Array<{ id: string; ok: boolean; code?: string; message?: string }> };
+    };
+  };
+  'daemon.shutdown': { params: Empty; result: Empty };
+  'daemon.pause': { params: { runtime?: RuntimeKind; now?: boolean; reason?: string }; result: PauseState };
+  'daemon.resume': { params: { runtime?: RuntimeKind }; result: PauseState };
+  'daemon.pauses': { params: Empty; result: PauseState };
+  'daemon.usage': { params: { refresh?: boolean }; result: { providers: Array<Record<string, unknown>> } };
+  'catalog.get': { params: Empty; result: { models: Array<Record<string, unknown>>; modes: Array<Record<string, unknown>>; thinkingOptions?: unknown; defaultModel: string } };
+  'assignment.recall': { params: { assignmentId?: string; taskId?: string; projectRoot?: string; question: string }; result: RecallAnswer };
+  'board.list': { params: { projectRoot: string }; result: { pins: Pin[] } };
+  'question.list': { params: { projectRoot?: string }; result: { questions: UserQuestion[] } };
+  'question.answer': { params: { questionId: string; text?: string; dismiss?: boolean; reason?: string }; result: { questionId: string } };
+  'session.create': {
+    params: { sessionId?: string; spec: SessionSpec; history?: 'skip' | 'replay'; delegation?: boolean; resume?: boolean };
+    result: { session: SessionSnapshot; attached: boolean; resumed?: true; durable?: boolean };
+  };
+  'session.preview': { params: { spec: SessionSpec }; result: { preview: SessionPreview } };
+  'session.attach': { params: { sessionId: string; replay?: boolean; after?: number }; result: { session: SessionSummary; cursor: number; reset?: true } };
+  'session.release': { params: { sessionId: string }; result: { closed: boolean } };
+  'session.prompt': {
+    params: { sessionId: string; clientMessageId: string; delivery?: 'auto' | 'steer'; content: PromptContent };
+    /** `{}` from a daemon without prompt.receipts. */
+    result: { outcome?: 'accepted' | 'failed'; error?: AlpError; duplicate?: boolean; durable?: boolean };
+  };
+  'session.interrupt': { params: { sessionId: string }; result: Empty };
+  'session.configure': { params: { sessionId: string; mode?: string }; result: { session: SessionSnapshot } };
+  'session.close': { params: { sessionId: string }; result: Empty };
+  'session.rename': { params: { sessionId: string; title: string }; result: { session: SessionSummary } };
+  'session.archive': { params: { sessionId: string; archived?: boolean }; result: { session: SessionSummary } };
+  'session.get': { params: { sessionId: string }; result: { session: SessionSummary } };
+  'session.list': { params: { projectRoot?: string; rootsOnly?: boolean; includeClosed?: boolean; includeArchived?: boolean }; result: { sessions: SessionSummary[] } };
+  'session.status': { params: { sessionId: string }; result: { status: TreeStatus } };
+  'session.message': { params: { sessionId: string; text: string }; result: Empty };
+  'session.log': { params: { sessionId: string }; result: { rootId: string; entries: Array<Record<string, unknown>> } };
+  'extension.register': { params: { method: string }; result: { registered: string } };
+  'extension.unregister': { params: { method: string }; result: { unregistered: string } };
+  'team.list': { params: { projectRoot?: string }; result: { projectRoot: string | null; teams: TeamRow[] } };
+  'task.list': { params: { projectRoot: string }; result: { projectRoot: string; tasks: TaskRow[]; unreadable: Array<{ file: string; error: string }>; revision: string } };
+  'task.create': { params: { projectRoot: string; title: string; priority?: number; requestId?: string }; result: { id: string; duplicate?: true } };
+  'task.update': { params: { projectRoot: string; id: string; action: 'close' | 'reopen'; note?: string; ifRev?: number }; result: { id: string; status: string; rev: number; landed?: string } };
+  'task.gate.resolve': { params: { projectRoot: string; id: string; gate: string; note?: string; ifRev?: number }; result: { id: string; status: string; rev: number } };
+  'library.list': { params: { kind: LibraryKind; projectRoot?: string }; result: { projectRoot: string | null; entries: LibraryEntryRow[] } };
+  'library.get': {
+    params: { kind: LibraryKind; name: EntryName; projectRoot?: string; scope?: LibraryScope };
+    /** `content` carries `{ $secret: 'keep' }` in place of each secret value; `secrets` lists their JSON Pointers. */
+    result: { kind: LibraryKind; name: string; source: LibrarySource; overrides?: LibrarySource; content: Record<string, unknown>; revision: string | null; usedBy: string[]; librarySkills?: string[]; secrets?: string[] };
+  };
+  'library.save': {
+    params: { kind: LibraryKind; name: EntryName; scope: LibraryScope; projectRoot?: string; content: Record<string, unknown>; revision?: string | null; sync?: 'none' | 'known-projects' };
+    result: { revision: string | null; syncedProjects?: number; syncErrors?: string[] };
+  };
+  'library.delete': { params: { kind: LibraryKind; name: EntryName; scope: LibraryScope; projectRoot?: string; revision?: string }; result: { removed: true; now?: 'builtin' | 'library' } };
+  'library.duplicate': { params: { kind: LibraryKind; from: EntryName; to: EntryName; scope: LibraryScope; projectRoot?: string }; result: { revision: string | null } };
+  'library.rename': { params: { kind: LibraryKind; from: EntryName; to: EntryName; scope: LibraryScope; projectRoot?: string }; result: { revision: string | null } };
+  'library.skills.set': { params: { agent: EntryName; skills: EntryName[] }; result: { skills: string[] } };
+  'library.models': { params: Empty; result: { models: Array<{ id: string; label: string; efforts: string[]; effort?: string }> } };
+  'settings.language.get': { params: Empty; result: LanguageSetting };
+  'settings.language.set': { params: { language: string | null }; result: LanguageSetting };
+};
+
+export type RpcMethod = keyof RpcMethodMap;
+export type RpcParams<M extends RpcMethod> = RpcMethodMap[M]['params'];
+export type RpcResult<M extends RpcMethod> = RpcMethodMap[M]['result'];