@anhlp/alp-protocol 0.0.0-stage → 0.0.1-beta.3

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.","session.list.page":"session.list accepts `limit`, `cursor` and `query` and answers `nextCursor` while more sessions follow; without them it answers every session as before.","question.watch":"question.watch: the connection is told of `question` and `question.resolved` in every tree (of a projectRoot when given), attached or not.","question.watch.turns":"question.watch accepts `turns`: the connection is also told of `turn.ended` of every root in the trees it watches.","workspace.files":"workspace.files.search: files under a directory whose relative path matches a query; read-only, names only, links never followed.","workspace.files.read":"workspace.files.list and workspace.files.read: the entries of a directory and the content of a UTF-8 text file (at most 1 MiB) under a directory; read-only, links never followed, .git, .env* and key or credential files refused, .gitignore'd paths hidden unless asked.","prompt.images":"session.prompt takes inline image parts { type: \"image\", mimeType, data } (base64, no paths or URLs) within the image limits; a session snapshot says whether its runtime takes them in promptImages.","library.project.write":"library save/delete/duplicate/rename accept policy project-data: only project-only pure-data agents and skills, no executable configuration, sidecars or library/built-in collisions."},"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"},"hostname":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"promptImageLimits":{"type":"object","description":"Optional effective inline image limits for this connection, when prompt.images is advertised. Missing on older peers. Byte limits count decoded bytes.","properties":{"maxCount":{"type":"integer","minimum":0},"maxBytes":{"type":"integer","minimum":0},"maxTotalBytes":{"type":"integer","minimum":0}},"required":["maxCount","maxBytes","maxTotalBytes"],"additionalProperties":false}},"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"},"policy":{"enum":["project-data"],"description":"Opt-in strict project-only non-executable mutation policy; requires library.project.write capability."}},"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"},"policy":{"enum":["project-data"],"description":"Opt-in strict project-only non-executable mutation policy; requires library.project.write capability."}},"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"},"policy":{"enum":["project-data"],"description":"Opt-in strict project-only non-executable mutation policy; requires library.project.write capability."}},"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"]},"policy":{"enum":["project-data"],"description":"Opt-in strict project-only non-executable mutation policy; requires library.project.write capability."}},"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}},"question.watch":{"x-alp":{"effect":"query","scope":{"kind":"project","param":"projectRoot","required":false},"idempotent":true,"capability":"question.watch"},"params":{"type":"object","properties":{"projectRoot":{"type":"string"},"turns":{"type":"boolean"}},"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"},"limit":{"type":"integer","minimum":1,"maximum":1000},"cursor":{"type":"string","minLength":1,"maxLength":1024},"query":{"type":"string","maxLength":200},"projectRoots":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":1024}},"required":[],"additionalProperties":true},"result":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/$defs/sessionSummary"}},"nextCursor":{"type":"string","minLength":1}},"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":{"anyOf":[{"type":"object","properties":{"type":{"const":"text"},"text":{"type":"string"}},"required":["type"],"additionalProperties":true},{"$ref":"#/$defs/promptImage"},{"type":"object","properties":{"type":{"type":"string","not":{"enum":["text","image"]}}},"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}},"workspace.files.search":{"x-alp":{"effect":"query","scope":{"kind":"project","param":"projectRoot","required":true},"idempotent":true,"capability":"workspace.files","risks":["lists file names of the directory (not contents)"]},"params":{"type":"object","properties":{"projectRoot":{"type":"string"},"query":{"type":"string","maxLength":200},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["projectRoot"],"additionalProperties":true},"result":{"type":"object","properties":{"files":{"type":"array","maxItems":100,"items":{"type":"object","properties":{"path":{"type":"string","minLength":1}},"required":["path"],"additionalProperties":true}},"truncated":{"type":"boolean"}},"required":["files"],"additionalProperties":true}},"workspace.files.list":{"x-alp":{"effect":"query","scope":{"kind":"project","param":"projectRoot","required":true},"idempotent":true,"capability":"workspace.files.read","risks":["lists names, kinds, sizes and times of a directory's entries (not contents)"]},"params":{"type":"object","properties":{"projectRoot":{"type":"string"},"path":{"type":"string","minLength":1,"maxLength":4096},"includeIgnored":{"type":"boolean"}},"required":["projectRoot"],"additionalProperties":true},"result":{"type":"object","properties":{"entries":{"type":"array","maxItems":1000,"items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"path":{"type":"string","minLength":1},"kind":{"enum":["file","directory"]},"size":{"type":"integer","minimum":0},"modifiedAt":{"type":"string"}},"required":["name","path","kind"],"additionalProperties":true}},"truncated":{"type":"boolean"}},"required":["entries"],"additionalProperties":true}},"workspace.files.read":{"x-alp":{"effect":"query","scope":{"kind":"project","param":"projectRoot","required":true},"idempotent":true,"capability":"workspace.files.read","risks":["returns the content of a text file under the directory"]},"params":{"type":"object","properties":{"projectRoot":{"type":"string"},"path":{"type":"string","minLength":1,"maxLength":4096},"includeIgnored":{"type":"boolean"}},"required":["projectRoot","path"],"additionalProperties":true},"result":{"type":"object","properties":{"path":{"type":"string","minLength":1},"content":{"type":"string"},"size":{"type":"integer","minimum":0,"maximum":1048576},"modifiedAt":{"type":"string"}},"required":["path","content","size"],"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"},"promptImages":{"type":"boolean"},"usage":{"$ref":"#/$defs/usage"}},"required":["id","projectRoot","agent","runtime","model","mode","thinking","workflow","threadId","persistent","busy"],"additionalProperties":true},"usage":{"type":"object","properties":{"contextWindowUsedTokens":{"type":"integer","minimum":0},"contextWindowMaxTokens":{"type":"integer","minimum":1},"inputTokens":{"type":"integer","minimum":0},"cachedInputTokens":{"type":"integer","minimum":0},"outputTokens":{"type":"integer","minimum":0},"totalCostUsd":{"type":"number","minimum":0}},"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":"usage"},"usage":{"$ref":"#/$defs/usage"}},"required":["type","usage"],"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","usage","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"},"images":{"type":"integer","minimum":1}},"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":{"$ref":"#/$defs/toolCallDetail"}},"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},"toolCallDetail":{"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":"read"},"filePath":{"type":"string"},"content":{"type":"string"},"offset":{"type":"integer"},"limit":{"type":"integer"}},"required":["type","filePath"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"edit"},"filePath":{"type":"string"},"oldString":{"type":"string"},"newString":{"type":"string"},"unifiedDiff":{"type":"string"}},"required":["type","filePath"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"write"},"filePath":{"type":"string"},"content":{"type":"string"}},"required":["type","filePath"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"search"},"query":{"type":"string"},"toolName":{"enum":["search","grep","glob","web_search"]},"content":{"type":"string"},"filePaths":{"type":"array","items":{"type":"string"}},"webResults":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"}},"required":["title","url"],"additionalProperties":true}},"numFiles":{"type":"integer"},"numMatches":{"type":"integer"},"truncated":{"type":"boolean"}},"required":["type","query"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"fetch"},"url":{"type":"string"},"prompt":{"type":"string"},"result":{"type":"string"},"code":{"type":"integer"}},"required":["type","url"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"sub_agent"},"subAgentType":{"type":"string"},"description":{"type":"string"},"log":{"type":"string"}},"required":["type"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"plan"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"plain_text"},"label":{"type":"string"},"text":{"type":"string"}},"required":["type"],"additionalProperties":true},{"type":"object","properties":{"type":{"const":"unknown"},"input":{},"output":{}},"required":["type","input","output"],"additionalProperties":true},{"type":"object","properties":{"type":{"type":"string","not":{"enum":["shell","read","edit","write","search","fetch","sub_agent","plan","plain_text","unknown"]}}},"required":["type"],"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},"promptImage":{"type":"object","properties":{"type":{"const":"image"},"mimeType":{"enum":["image/png","image/jpeg","image/gif","image/webp"]},"data":{"type":"string","minLength":4,"maxLength":6990508,"pattern":"^[A-Za-z0-9+/]+={0,2}$"},"name":{"type":"string","maxLength":255}},"required":["type","mimeType","data"],"additionalProperties":false}}};

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,181 @@
+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; /** How many images the message carried; their data is not replayed. */ images?: number }
+  | { 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: ToolCallDetail;
+    };
+
+/**
+ * What a tool call did, typed by kind (ALPD §4.2), in the shapes of Paseo's ToolCallDetail.
+ * `shell` is a command; `unknown` the fallback with the tool's raw input and output. The typed
+ * kinds between come from the runtime's own tools; filePath is the path the runtime reported.
+ * The runtime clips each string field of a typed detail (not shell, not unknown) to 65,536
+ * characters, filePaths to 200 entries and webResults to 50. A receiver shows a detail whose
+ * type it does not know as unknown: new types may be added within v1.
+ */
+export type ToolCallDetail =
+  | { type: 'shell'; command: string; cwd?: string; output: string; exitCode?: number | null }
+  | { type: 'read'; filePath: string; content?: string; offset?: number; limit?: number }
+  | { type: 'edit'; filePath: string; oldString?: string; newString?: string; unifiedDiff?: string }
+  | { type: 'write'; filePath: string; content?: string }
+  | {
+      type: 'search';
+      query: string;
+      toolName?: 'search' | 'grep' | 'glob' | 'web_search';
+      content?: string;
+      filePaths?: string[];
+      webResults?: Array<{ title: string; url: string }>;
+      numFiles?: number;
+      numMatches?: number;
+      truncated?: boolean;
+    }
+  | { type: 'fetch'; url: string; prompt?: string; result?: string; code?: number }
+  | { type: 'sub_agent'; subAgentType?: string; description?: string; log?: string }
+  | { type: 'plan'; text: string }
+  | { type: 'plain_text'; label?: string; text?: string }
+  | { type: 'unknown'; input: unknown; output: unknown };
+
+/**
+ * How much a session has used, from its runtime's latest token report (ALPD §57), as Paseo's
+ * AgentUsage: the context window's fill, the latest model response's tokens, and the session's
+ * cost when the runtime says it. A field the runtime does not report is absent; a later report
+ * replaces the fields it carries and keeps the others.
+ */
+export type SessionUsage = {
+  /** Tokens the context holds now: the latest model call's input and output. */
+  contextWindowUsedTokens?: number;
+  /** The context window, once the runtime has said what it is. */
+  contextWindowMaxTokens?: number;
+  /** The latest model response's input tokens, of which cachedInputTokens came from cache, and output tokens. */
+  inputTokens?: number;
+  cachedInputTokens?: number;
+  outputTokens?: number;
+  /** The session's cost in US dollars so far, as the runtime counts it (Claude, or ACP in USD). */
+  totalCostUsd?: number;
+};
+
+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;
+  /** The session's runtime takes images in session.prompt (capability `prompt.images`); absent means it does not. */
+  promptImages?: boolean;
+  /** The latest usage the session's runtime reported (ALPD §57); absent before its first report. */
+  usage?: SessionUsage;
+};
+
+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' }
+  /** `title` comes with alpd's announcement of a root's name (its first prompt, or `session.rename`). */
+  | { type: 'session.updated'; session: SessionSnapshot & { title?: string } }
+  | { 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 }
+  /** The session's usage changed: the whole latest SessionUsage, not a delta (ALPD §57). */
+  | { type: 'usage'; usage: SessionUsage }
+  | { 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';