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

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 - present Bas Milius
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @adecore/agent-contracts
+
+[![npm](https://img.shields.io/npm/v/@adecore/agent-contracts)](https://www.npmjs.com/package/@adecore/agent-contracts)
+[![Docs](https://img.shields.io/badge/docs-adecore.dev-blue)](https://adecore.dev/agent-contracts/)
+
+The Zod schemas and TypeScript types an agent chat host and its clients share: the frames on the wire, the requests and events, a chat and its items, providers, models, accounts, tasks, worktrees and usage. It opens no connection and starts no process, so a browser, a preload and a backend can all import it.
+
+## Install
+
+```sh
+bun add @adecore/agent-contracts
+```
+
+## Use
+
+```ts
+import { AGENT_REQUEST_SCHEMAS, parseRequest } from '@adecore/agent-contracts';
+
+const frame = parseRequest(incoming);
+if (frame.ok && frame.value.type === 'chat.send') {
+    const payload = AGENT_REQUEST_SCHEMAS['chat.send'].payload.parse(frame.value.payload);
+}
+```
+
+The root exports everything. Each group also has a subpath of its own: `agent`, `chat`, `envelope`, `ids`, `model`, `port`, `protocol`, `provider-accounts`, `task`, `text`, `usage` and `worktree`.
+
+## Documentation
+
+| Page | What it covers |
+|---|---|
+| [Overview](https://adecore.dev/agent-contracts/) | Install, a first check and the entry points |
+| [Protocol](https://adecore.dev/agent-contracts/protocol) | Frames, the request and event tables, replay and adding requests |
+| [Conversation](https://adecore.dev/agent-contracts/conversation) | A chat's info and items, attachments, approvals, bookmarks and forks |
+| [Providers and accounts](https://adecore.dev/agent-contracts/providers-and-accounts) | Agent kinds, model catalogs, capabilities, runtime modes and accounts |
+| [Tasks and usage](https://adecore.dev/agent-contracts/tasks-and-usage) | Tasks, worktrees, token totals, summaries and plan limits |
+
+## License
+
+FSL-1.1-MIT. See [LICENSE](./LICENSE).

package/dist/agent.d.ts

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+export declare const AgentKindSchema: z.ZodEnum<{
+    apple: "apple";
+    claude: "claude";
+    codex: "codex";
+    copilot: "copilot";
+    gemini: "gemini";
+}>;
+export type AgentKind = z.infer<typeof AgentKindSchema>;
+export declare const AgentStatusSchema: z.ZodEnum<{
+    error: "error";
+    exited: "exited";
+    idle: "idle";
+    "needs-you": "needs-you";
+    running: "running";
+}>;
+export type AgentStatus = z.infer<typeof AgentStatusSchema>;
+export declare const SUGGESTED_TITLE_LIMIT = 80;
+export declare const SuggestedTitleSchema: z.ZodString;
+export declare const AgentInfoSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        apple: "apple";
+        claude: "claude";
+        codex: "codex";
+        copilot: "copilot";
+        gemini: "gemini";
+    }>;
+    agentSessionId: z.ZodString;
+    transcriptPath: z.ZodNullable<z.ZodString>;
+    suggestedTitle: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        error: "error";
+        exited: "exited";
+        idle: "idle";
+        "needs-you": "needs-you";
+        running: "running";
+    }>;
+    live: z.ZodBoolean;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type AgentInfo = z.infer<typeof AgentInfoSchema>;
+export declare const SessionStatusEventSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    agent: z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            apple: "apple";
+            claude: "claude";
+            codex: "codex";
+            copilot: "copilot";
+            gemini: "gemini";
+        }>;
+        agentSessionId: z.ZodString;
+        transcriptPath: z.ZodNullable<z.ZodString>;
+        suggestedTitle: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            error: "error";
+            exited: "exited";
+            idle: "idle";
+            "needs-you": "needs-you";
+            running: "running";
+        }>;
+        live: z.ZodBoolean;
+        updatedAt: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SessionStatusEvent = z.infer<typeof SessionStatusEventSchema>;
+export declare const AgentResumePayloadSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export type AgentResumePayload = z.infer<typeof AgentResumePayloadSchema>;
+export declare const ApprovalChoiceSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+        remember: "remember";
+    }>;
+    label: z.ZodString;
+}, z.core.$strip>;
+export type ApprovalChoice = z.infer<typeof ApprovalChoiceSchema>;
+export declare const ApprovalRequestSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    sessionId: z.ZodString;
+    toolName: z.ZodString;
+    summary: z.ZodString;
+    choices: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+            remember: "remember";
+        }>;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+    createdAt: z.ZodNumber;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>;
+export type ApprovalRequest = z.infer<typeof ApprovalRequestSchema>;
+export declare const SessionApprovalsEventSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    approvals: z.ZodArray<z.ZodObject<{
+        requestId: z.ZodString;
+        sessionId: z.ZodString;
+        toolName: z.ZodString;
+        summary: z.ZodString;
+        choices: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                allow: "allow";
+                deny: "deny";
+                remember: "remember";
+            }>;
+            label: z.ZodString;
+        }, z.core.$strip>>;
+        createdAt: z.ZodNumber;
+        expiresAt: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SessionApprovalsEvent = z.infer<typeof SessionApprovalsEventSchema>;
+export declare const ApprovalAnswerPayloadSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    requestId: z.ZodString;
+    choiceId: z.ZodString;
+}, z.core.$strip>;
+export type ApprovalAnswerPayload = z.infer<typeof ApprovalAnswerPayloadSchema>;
+export declare const ApprovalAnswerResultSchema: z.ZodObject<{
+    accepted: z.ZodBoolean;
+}, z.core.$strip>;
+export type ApprovalAnswerResult = z.infer<typeof ApprovalAnswerResultSchema>;
+export declare const ApprovalPreferencePayloadSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+}, z.core.$strip>;
+export type ApprovalPreferencePayload = z.infer<typeof ApprovalPreferencePayloadSchema>;

package/dist/agent.js

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { SessionIdSchema } from './ids.js';
+// 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']);
+// `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']);
+// 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 const SessionStatusEventSchema = z.object({
+    sessionId: SessionIdSchema,
+    agent: AgentInfoSchema.nullable()
+});
+export const AgentResumePayloadSchema = z.object({
+    sessionId: SessionIdSchema
+});
+/*
+ * 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)
+});
+/*
+ * 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()
+});
+// 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 const ApprovalAnswerPayloadSchema = z.object({
+    sessionId: SessionIdSchema,
+    requestId: z.string().min(1),
+    choiceId: z.string().min(1)
+});
+// 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()
+});
+/*
+ * 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()
+});