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

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 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,20 @@
+# @adecore/agent-contracts
+
+Zod schemas and TypeScript contracts shared by agent chat hosts and clients. The package covers conversations, attachments, approvals, providers, model selections, accounts, tasks, worktrees, and usage. It is browser safe and contains no process or transport implementation.
+
+```ts
+import { AGENT_REQUEST_SCHEMAS, parseRequest } from '@adecore/agent-contracts';
+import type { FramePort } from '@adecore/agent-contracts/port';
+
+const payload = AGENT_REQUEST_SCHEMAS['chat.send'].payload.parse({ chatId: 'chat-1', text: 'Hello' });
+```
+
+Envelope parsing checks frame structure. Persisted and wire discriminants, including the historical host-owned subagent origin, remain unchanged during the package migration. Validate payloads and correlated results against the selected table schema too. A consumer supplies transport ownership, authorization, and any larger host protocol.
+
+The [documentation](https://adecore.dev/agent-contracts/) covers [setup](https://adecore.dev/agent-contracts/getting-started), [frames and replay](https://adecore.dev/agent-contracts/frames-and-events), [conversation content](https://adecore.dev/agent-contracts/conversation), [providers/accounts](https://adecore.dev/agent-contracts/providers-and-accounts), [tasks/usage](https://adecore.dev/agent-contracts/tasks-and-usage), and [entrypoints/compatibility](https://adecore.dev/agent-contracts/validation-and-compatibility).
+
+The root reexports all groups. Supported subpaths are `agent`, `chat`, `envelope`, `ids`, `model`, `port`, `protocol`, `provider-accounts`, `task`, `text`, `usage`, and `worktree`.
+
+This package is private at `0.0.0`, pending publication setup. In the local workspace, build it with `bun run --cwd packages/agent-contracts build`, then run its `typecheck` and `test` scripts. Default exports use compiled JavaScript/declarations; the `source` condition uses TypeScript. Build it before the backend and React packages.
+
+Transferred code retains 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()
+});