@ziggs-ai/contracts 0.23.2 → 0.24.0

package/dist/generated/agreements.d.ts

@@ -112,6 +112,10 @@ export type AgreementRead = {
         primitive?: "context";
         kind?: "access-request" | "author-share";
         holderId?: string;
+        holders?: Array<{
+            kind: "agent" | "user" | "org";
+            id: string;
+        }>;
         scope?: {
             kind: string;
             id: string;

package/dist/inbox.d.ts

@@ -79,6 +79,15 @@ export interface AccessAsk {
      * repeating it here would be a second answer to one question.
      */
     holderDisplayName: string | null;
+    /**
+     * The readers a yes would let read it, when the agent asked for others
+     * rather than (or as well as) itself. One grant per reader. Labels only,
+     * never ids. Absent on an ask for the asking agent alone.
+     */
+    readers?: Array<{
+        kind: 'agent' | 'user' | 'org';
+        displayName: string | null;
+    }>;
     /** Why, in the requester's own words. */
     reason: string | null;
     /**

package/dist/socket.d.ts

@@ -68,22 +68,46 @@ export interface ChatReadFrame {
  * Written as a map so a client can type one listener registry over it and be
  * told when a frame it handles changes shape.
  */
+export interface AgentLivenessFrame {
+    agentId: string;
+    state: 'online' | 'offline' | 'suspended';
+}
+/** The roster of a room changed. Clients re-read parties. */
+export interface ChatParticipantsChangedFrame {
+    chatIds: string[];
+    reason?: string;
+}
+/**
+ * Which messages were read. The client sends this; the server fans the same
+ * shape back out, sometimes with `kind` so a handover is not a human read.
+ */
+export interface ChatMessageReadFrame {
+    chatId: string;
+    messageIds: string[];
+    kind?: 'agent_handover';
+}
 export interface ServerToClientEvents {
     'chat:message:new': ChatMessageNewFrame;
+    'chat:message:read': ChatMessageReadFrame;
     'chat:read': ChatReadFrame;
+    'chat:participants_changed': ChatParticipantsChangedFrame;
+    'agent:liveness': AgentLivenessFrame;
     resource_changed: ResourceChangedFrame;
 }
-/** Every frame a client sends. */
+/** Every frame a client sends. Joining a room is not one of them. */
 export interface ClientToServerEvents {
-    'chat:join': string;
+    'chat:message:read': ChatMessageReadFrame;
 }
 /** Wire names of the frames a client receives. */
 export declare const SERVER_EVENTS: {
     readonly chatMessageNew: "chat:message:new";
+    readonly chatMessageRead: "chat:message:read";
     readonly chatRead: "chat:read";
+    readonly chatParticipantsChanged: "chat:participants_changed";
+    readonly agentLiveness: "agent:liveness";
     readonly resourceChanged: "resource_changed";
 };
 /** Wire names of the frames a client sends. */
 export declare const CLIENT_EVENTS: {
-    readonly chatJoin: "chat:join";
+    readonly chatMessageRead: "chat:message:read";
 };

package/dist/socket.js

@@ -4,10 +4,13 @@ exports.CLIENT_EVENTS = exports.SERVER_EVENTS = void 0;
 /** Wire names of the frames a client receives. */
 exports.SERVER_EVENTS = {
     chatMessageNew: 'chat:message:new',
+    chatMessageRead: 'chat:message:read',
     chatRead: 'chat:read',
+    chatParticipantsChanged: 'chat:participants_changed',
+    agentLiveness: 'agent:liveness',
     resourceChanged: 'resource_changed',
 };
 /** Wire names of the frames a client sends. */
 exports.CLIENT_EVENTS = {
-    chatJoin: 'chat:join',
+    chatMessageRead: 'chat:message:read',
 };

package/dist/vocabulary.d.ts

@@ -63,3 +63,99 @@ export declare const ARTIFACT_FILE_FORMAT: {
 export type ArtifactFileFormat = (typeof ARTIFACT_FILE_FORMAT)[keyof typeof ARTIFACT_FILE_FORMAT];
 /** Every accepted format, in one list. */
 export declare const ARTIFACT_FILE_FORMATS: readonly ArtifactFileFormat[];
+/** The four sides of an agreement, in the order every fan-out walks them. */
+export declare const AGREEMENT_PARTY_SIDES: readonly ["payer", "provider", "proposedTo", "creator"];
+export type AgreementPartySideName = (typeof AGREEMENT_PARTY_SIDES)[number];
+/**
+ * A party slot that is a broadcast, not a person.
+ * `everyone` is public. `org` is the agreement's company only.
+ */
+export declare const OPEN_AGREEMENT_TARGET = "everyone";
+export declare const ORG_AGREEMENT_TARGET = "org";
+export declare const BROADCAST_TARGETS: readonly ["everyone", "org"];
+export type BroadcastAudience = (typeof BROADCAST_TARGETS)[number];
+export declare function isBroadcastTarget(id: string | null | undefined): id is BroadcastAudience;
+/** One side, as ids only. Callers may pass the stored row. */
+export interface PartySideRef {
+    principal?: string | null;
+    actor?: string | null;
+}
+/** Both ids on a side, principal then actor, blanks dropped. */
+export declare function partySideIds(side: PartySideRef | null | undefined): string[];
+/** The agents that acted on any side, deduped. */
+export declare function partyActorIds(parties: Partial<Record<AgreementPartySideName, PartySideRef | null>> | null | undefined): string[];
+/** What kind of agreement this paper is. A link is reach, not a hire. */
+export declare const AGREEMENT_ENGAGEMENT_KIND: {
+    readonly HIRE: "hire";
+    readonly SERVICE: "service";
+    readonly LINK: "link";
+};
+export type AgreementEngagementKind = (typeof AGREEMENT_ENGAGEMENT_KIND)[keyof typeof AGREEMENT_ENGAGEMENT_KIND];
+/**
+ * A seller's standing offer: the payer slot is a broadcast, and the paper
+ * is not a reach link. Any status — a paused listing is still a listing.
+ */
+export declare function isSellerListing(row: {
+    engagementKind?: string | null;
+    parties?: {
+        payer?: {
+            principal?: string | null;
+        } | null;
+    } | null;
+} | null | undefined): boolean;
+/** A task is born active. Negotiation lives on the agreement, not here. */
+export declare const TASK_STATE: {
+    readonly ACTIVE: "active";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+    readonly CANCELLED: "cancelled";
+};
+export type TaskStateValue = (typeof TASK_STATE)[keyof typeof TASK_STATE];
+export declare const TASK_STATES: readonly TaskStateValue[];
+/** Finished: nothing left to run. */
+export declare const TERMINAL_TASK_STATES: readonly TaskStateValue[];
+export declare function isTerminalTaskState(state: string): boolean;
+export declare const AGREEMENT_STATUS: {
+    readonly DRAFT: "draft";
+    readonly OPEN: "open";
+    readonly ACTIVE: "active";
+    readonly FULFILLED: "fulfilled";
+    readonly CANCELLED: "cancelled";
+    readonly REFUNDED: "refunded";
+};
+export type AgreementStatusValue = (typeof AGREEMENT_STATUS)[keyof typeof AGREEMENT_STATUS];
+export declare const AGREEMENT_STATUSES: readonly AgreementStatusValue[];
+export declare const AGREEMENT_TERMINAL_STATES: readonly AgreementStatusValue[];
+/**
+ * Context-rail scopes, then the other rails a grant can name.
+ * Order is the order the grants read and the OpenAPI enum publish.
+ */
+export declare const CONTEXT_GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact", "task"];
+export declare const GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact", "task", "connection", "wallet", "consent", "inbox"];
+export type GrantScopeKind = (typeof GRANT_SCOPE_KINDS)[number];
+export type ContextGrantScopeKind = (typeof CONTEXT_GRANT_SCOPE_KINDS)[number];
+/** What an access request may name. Always one resource. */
+export declare const ACCESS_REQUEST_SCOPE_KINDS: readonly ["artifact", "chat", "agreement", "task"];
+export type AccessRequestScopeKind = (typeof ACCESS_REQUEST_SCOPE_KINDS)[number];
+/**
+ * Who an artifact access request may ask a grant FOR. Each reader is named
+ * with its kind; the kind is never inferred from an id or a display name.
+ */
+export declare const ACCESS_REQUEST_HOLDER_KINDS: readonly ["agent", "user", "org"];
+export type AccessRequestHolderKind = (typeof ACCESS_REQUEST_HOLDER_KINDS)[number];
+/** How many readers one access request may name. */
+export declare const MAX_ACCESS_REQUEST_HOLDERS = 20;
+/** What a chat entry's contentType may be. */
+export declare const MESSAGE_CONTENT_TYPE: {
+    readonly TEXT: "text";
+    readonly OPERATION: "operation";
+    readonly CONTEXT: "context";
+    readonly RESULT: "result";
+    readonly AGREEMENT_UPDATE: "agreement_update";
+    readonly TASK: "task";
+    readonly TASK_PLAN_STEP: "task_plan_step";
+    readonly THOUGHT: "thought";
+    readonly PROPOSAL: "proposal";
+};
+export type MessageContentType = (typeof MESSAGE_CONTENT_TYPE)[keyof typeof MESSAGE_CONTENT_TYPE];
+export declare const MESSAGE_CONTENT_TYPES: readonly MessageContentType[];

package/dist/vocabulary.js

@@ -7,7 +7,12 @@
  * enum, a switch a consumer needs to make exhaustive.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ARTIFACT_FILE_FORMATS = exports.ARTIFACT_FILE_FORMAT = exports.RESOURCE_KINDS = exports.CHAT_ADDRESS_KINDS = exports.GRANT_ACCESS_KINDS = void 0;
+exports.MESSAGE_CONTENT_TYPES = exports.MESSAGE_CONTENT_TYPE = exports.MAX_ACCESS_REQUEST_HOLDERS = exports.ACCESS_REQUEST_HOLDER_KINDS = exports.ACCESS_REQUEST_SCOPE_KINDS = exports.GRANT_SCOPE_KINDS = exports.CONTEXT_GRANT_SCOPE_KINDS = exports.AGREEMENT_TERMINAL_STATES = exports.AGREEMENT_STATUSES = exports.AGREEMENT_STATUS = exports.TERMINAL_TASK_STATES = exports.TASK_STATES = exports.TASK_STATE = exports.AGREEMENT_ENGAGEMENT_KIND = exports.BROADCAST_TARGETS = exports.ORG_AGREEMENT_TARGET = exports.OPEN_AGREEMENT_TARGET = exports.AGREEMENT_PARTY_SIDES = exports.ARTIFACT_FILE_FORMATS = exports.ARTIFACT_FILE_FORMAT = exports.RESOURCE_KINDS = exports.CHAT_ADDRESS_KINDS = exports.GRANT_ACCESS_KINDS = void 0;
+exports.isBroadcastTarget = isBroadcastTarget;
+exports.partySideIds = partySideIds;
+exports.partyActorIds = partyActorIds;
+exports.isSellerListing = isSellerListing;
+exports.isTerminalTaskState = isTerminalTaskState;
 /**
  * What a grant lets its holder do with the scope.
  *
@@ -56,3 +61,124 @@ exports.ARTIFACT_FILE_FORMAT = {
 };
 /** Every accepted format, in one list. */
 exports.ARTIFACT_FILE_FORMATS = Object.values(exports.ARTIFACT_FILE_FORMAT);
+/** The four sides of an agreement, in the order every fan-out walks them. */
+exports.AGREEMENT_PARTY_SIDES = [
+    'payer',
+    'provider',
+    'proposedTo',
+    'creator',
+];
+/**
+ * A party slot that is a broadcast, not a person.
+ * `everyone` is public. `org` is the agreement's company only.
+ */
+exports.OPEN_AGREEMENT_TARGET = 'everyone';
+exports.ORG_AGREEMENT_TARGET = 'org';
+exports.BROADCAST_TARGETS = [
+    exports.OPEN_AGREEMENT_TARGET,
+    exports.ORG_AGREEMENT_TARGET,
+];
+function isBroadcastTarget(id) {
+    return exports.BROADCAST_TARGETS.includes(id ?? '');
+}
+/** Both ids on a side, principal then actor, blanks dropped. */
+function partySideIds(side) {
+    return [side?.principal, side?.actor].filter((id) => typeof id === 'string' && id.length > 0);
+}
+/** The agents that acted on any side, deduped. */
+function partyActorIds(parties) {
+    const p = parties ?? {};
+    return [
+        ...new Set(exports.AGREEMENT_PARTY_SIDES.map((name) => p[name]?.actor).filter((id) => !!id)),
+    ];
+}
+/** What kind of agreement this paper is. A link is reach, not a hire. */
+exports.AGREEMENT_ENGAGEMENT_KIND = {
+    HIRE: 'hire',
+    SERVICE: 'service',
+    LINK: 'link',
+};
+/**
+ * A seller's standing offer: the payer slot is a broadcast, and the paper
+ * is not a reach link. Any status — a paused listing is still a listing.
+ */
+function isSellerListing(row) {
+    return (isBroadcastTarget(row?.parties?.payer?.principal) &&
+        row?.engagementKind !== exports.AGREEMENT_ENGAGEMENT_KIND.LINK);
+}
+/** A task is born active. Negotiation lives on the agreement, not here. */
+exports.TASK_STATE = {
+    ACTIVE: 'active',
+    COMPLETED: 'completed',
+    FAILED: 'failed',
+    CANCELLED: 'cancelled',
+};
+exports.TASK_STATES = Object.values(exports.TASK_STATE);
+/** Finished: nothing left to run. */
+exports.TERMINAL_TASK_STATES = [
+    exports.TASK_STATE.COMPLETED,
+    exports.TASK_STATE.FAILED,
+    exports.TASK_STATE.CANCELLED,
+];
+function isTerminalTaskState(state) {
+    return exports.TERMINAL_TASK_STATES.includes(state);
+}
+exports.AGREEMENT_STATUS = {
+    DRAFT: 'draft',
+    OPEN: 'open',
+    ACTIVE: 'active',
+    FULFILLED: 'fulfilled',
+    CANCELLED: 'cancelled',
+    REFUNDED: 'refunded',
+};
+exports.AGREEMENT_STATUSES = Object.values(exports.AGREEMENT_STATUS);
+exports.AGREEMENT_TERMINAL_STATES = [
+    exports.AGREEMENT_STATUS.FULFILLED,
+    exports.AGREEMENT_STATUS.CANCELLED,
+    exports.AGREEMENT_STATUS.REFUNDED,
+];
+/**
+ * Context-rail scopes, then the other rails a grant can name.
+ * Order is the order the grants read and the OpenAPI enum publish.
+ */
+exports.CONTEXT_GRANT_SCOPE_KINDS = [
+    'chat',
+    'agreement',
+    'org',
+    'artifact',
+    'task',
+];
+exports.GRANT_SCOPE_KINDS = [
+    ...exports.CONTEXT_GRANT_SCOPE_KINDS,
+    'connection',
+    'wallet',
+    'consent',
+    'inbox',
+];
+/** What an access request may name. Always one resource. */
+exports.ACCESS_REQUEST_SCOPE_KINDS = [
+    'artifact',
+    'chat',
+    'agreement',
+    'task',
+];
+/**
+ * Who an artifact access request may ask a grant FOR. Each reader is named
+ * with its kind; the kind is never inferred from an id or a display name.
+ */
+exports.ACCESS_REQUEST_HOLDER_KINDS = ['agent', 'user', 'org'];
+/** How many readers one access request may name. */
+exports.MAX_ACCESS_REQUEST_HOLDERS = 20;
+/** What a chat entry's contentType may be. */
+exports.MESSAGE_CONTENT_TYPE = {
+    TEXT: 'text',
+    OPERATION: 'operation',
+    CONTEXT: 'context',
+    RESULT: 'result',
+    AGREEMENT_UPDATE: 'agreement_update',
+    TASK: 'task',
+    TASK_PLAN_STEP: 'task_plan_step',
+    THOUGHT: 'thought',
+    PROPOSAL: 'proposal',
+};
+exports.MESSAGE_CONTENT_TYPES = Object.values(exports.MESSAGE_CONTENT_TYPE);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/contracts",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "description": "Wire contracts for the Ziggs API — response shapes, error body, and socket events, shared by every client.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",