@adecore/agent-contracts 0.0.1 → 0.17.0-beta.2

package/package.json

@@ -1,11 +1,104 @@
 {
   "name": "@adecore/agent-contracts",
-  "version": "0.0.1",
-  "description": "Placeholder for the first release.",
+  "version": "0.17.0-beta.2",
+  "description": "Schemas and port contracts for agent chats, provider accounts, models and usage.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./agent": {
+      "source": "./src/agent.ts",
+      "types": "./dist/agent.d.ts",
+      "default": "./dist/agent.js"
+    },
+    "./chat": {
+      "source": "./src/chat.ts",
+      "types": "./dist/chat.d.ts",
+      "default": "./dist/chat.js"
+    },
+    "./envelope": {
+      "source": "./src/envelope.ts",
+      "types": "./dist/envelope.d.ts",
+      "default": "./dist/envelope.js"
+    },
+    "./ids": {
+      "source": "./src/ids.ts",
+      "types": "./dist/ids.d.ts",
+      "default": "./dist/ids.js"
+    },
+    "./model": {
+      "source": "./src/model.ts",
+      "types": "./dist/model.d.ts",
+      "default": "./dist/model.js"
+    },
+    "./port": {
+      "source": "./src/port.ts",
+      "types": "./dist/port.d.ts",
+      "default": "./dist/port.js"
+    },
+    "./protocol": {
+      "source": "./src/protocol.ts",
+      "types": "./dist/protocol.d.ts",
+      "default": "./dist/protocol.js"
+    },
+    "./provider-accounts": {
+      "source": "./src/provider-accounts.ts",
+      "types": "./dist/provider-accounts.d.ts",
+      "default": "./dist/provider-accounts.js"
+    },
+    "./task": {
+      "source": "./src/task.ts",
+      "types": "./dist/task.d.ts",
+      "default": "./dist/task.js"
+    },
+    "./text": {
+      "source": "./src/text.ts",
+      "types": "./dist/text.d.ts",
+      "default": "./dist/text.js"
+    },
+    "./usage": {
+      "source": "./src/usage.ts",
+      "types": "./dist/usage.d.ts",
+      "default": "./dist/usage.js"
+    },
+    "./worktree": {
+      "source": "./src/worktree.ts",
+      "types": "./dist/worktree.d.ts",
+      "default": "./dist/worktree.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "bun scripts/build.ts",
+    "test": "bun --conditions=source test"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  },
   "license": "FSL-1.1-MIT",
+  "author": "Bas Milius",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/basmilius/adecore.git",
     "directory": "packages/agent-contracts"
-  }
+  },
+  "bugs": {
+    "url": "https://github.com/basmilius/adecore/issues"
+  },
+  "homepage": "https://adecore.dev/agent-contracts/",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__snapshots__"
+  ],
+  "sideEffects": false
 }

package/src/agent.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { SessionIdSchema } from './ids.ts';
+
+// The supported agent CLIs. Whether one has a chat backend or a hook normalizer is a capability
+// on its provider, not a second list: a CLI without hooks still opens as a terminal agent.
+export const AgentKindSchema = z.enum(['claude', 'codex', 'gemini', 'copilot', 'apple']);
+export type AgentKind = z.infer<typeof AgentKindSchema>;
+
+// `exited` is the daemon's own reading, not a hook's: the CLI went down with its shell without
+// ever reporting an end, so the node offers a resume instead of a status that stays on running.
+export const AgentStatusSchema = z.enum(['running', 'needs-you', 'idle', 'error', 'exited']);
+export type AgentStatus = z.infer<typeof AgentStatusSchema>;
+
+// Past this a model's name for a session is a summary, not a title.
+export const SUGGESTED_TITLE_LIMIT = 80;
+
+// Written by a model, so a node shows it as plain text and nothing reads it as an instruction.
+export const SuggestedTitleSchema = z.string().min(1).max(SUGGESTED_TITLE_LIMIT);
+
+export const AgentInfoSchema = z.object({
+    kind: AgentKindSchema,
+    // The CLI's own session id, what `--resume` takes.
+    agentSessionId: z.string().min(1),
+    transcriptPath: z.string().nullable(),
+    // The name the CLI wrote down for the session; Claude Code and the Codex TUI write one.
+    suggestedTitle: SuggestedTitleSchema.optional(),
+    status: AgentStatusSchema,
+    // False once the daemon came back after a restart: the CLI is gone but its session can be resumed.
+    live: z.boolean(),
+    updatedAt: z.number()
+});
+export type AgentInfo = z.infer<typeof AgentInfoSchema>;
+
+export const SessionStatusEventSchema = z.object({
+    sessionId: SessionIdSchema,
+    agent: AgentInfoSchema.nullable()
+});
+export type SessionStatusEvent = z.infer<typeof SessionStatusEventSchema>;
+
+export const AgentResumePayloadSchema = z.object({
+    sessionId: SessionIdSchema
+});
+export type AgentResumePayload = z.infer<typeof AgentResumePayloadSchema>;
+
+/*
+ * One button under a permission request. `allow` and `deny` are always there; a `remember` choice
+ * only exists when the CLI offered a rule to widen, and the daemon holds that rule rather than the
+ * client, so a client never has to know a CLI's permission vocabulary.
+ */
+export const ApprovalChoiceSchema = z.object({
+    id: z.string().min(1),
+    kind: z.enum(['allow', 'remember', 'deny']),
+    label: z.string().min(1)
+});
+export type ApprovalChoice = z.infer<typeof ApprovalChoiceSchema>;
+
+/*
+ * A permission the agent in a terminal is waiting on. The CLI is asking in its own TUI at the same
+ * moment, so this is a second way to answer the same question, never the only one: whoever is first
+ * wins and `expiresAt` is when the daemon stops holding and leaves the TUI to it.
+ */
+export const ApprovalRequestSchema = z.object({
+    requestId: z.string().min(1),
+    sessionId: SessionIdSchema,
+    toolName: z.string().min(1),
+    // The one line a person reads: the command for a shell call, the path for a file tool.
+    summary: z.string(),
+    choices: z.array(ApprovalChoiceSchema).min(1),
+    createdAt: z.number(),
+    expiresAt: z.number()
+});
+export type ApprovalRequest = z.infer<typeof ApprovalRequestSchema>;
+
+// The whole pending list of one session, so a client that arrives late and one that missed a settle agree.
+export const SessionApprovalsEventSchema = z.object({
+    sessionId: SessionIdSchema,
+    approvals: z.array(ApprovalRequestSchema)
+});
+export type SessionApprovalsEvent = z.infer<typeof SessionApprovalsEventSchema>;
+
+export const ApprovalAnswerPayloadSchema = z.object({
+    sessionId: SessionIdSchema,
+    requestId: z.string().min(1),
+    choiceId: z.string().min(1)
+});
+export type ApprovalAnswerPayload = z.infer<typeof ApprovalAnswerPayloadSchema>;
+
+// False when the request was already settled: another client was first, the person used the TUI, or it expired.
+export const ApprovalAnswerResultSchema = z.object({
+    accepted: z.boolean()
+});
+export type ApprovalAnswerResult = z.infer<typeof ApprovalAnswerResultSchema>;
+
+/*
+ * Whether this client offers permission requests to a person at all. One socket's answer, not the
+ * daemon's: with it off the daemon holds nothing for this client, while a second client that still
+ * wants them is asked as before. A client that never sends this wants them, which is what every
+ * client written before the switch existed meant.
+ */
+export const ApprovalPreferencePayloadSchema = z.object({
+    enabled: z.boolean()
+});
+export type ApprovalPreferencePayload = z.infer<typeof ApprovalPreferencePayloadSchema>;