@agent-relay/sdk 7.1.0 → 8.0.1

package/dist/delivery/runner.js

@@ -0,0 +1,177 @@
+import { RelayCapabilityError } from '../capabilities.js';
+export class DeliveryRunner {
+    options;
+    stopped = false;
+    running;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        if (!this.options.messaging.capabilities.serverDeliveryState) {
+            throw new RelayCapabilityError('messaging.capabilities.serverDeliveryState', 'DeliveryRunner requires server-backed delivery state for ack/fail/defer.');
+        }
+        this.running ??= this.run();
+        return this.running;
+    }
+    stop() {
+        this.stopped = true;
+    }
+    async run() {
+        await deliveryAdapter(this.options.delivery).connect?.();
+        try {
+            for await (const item of this.options.messaging.inbox.subscribe({
+                agentName: this.options.agentName,
+            })) {
+                if (this.stopped)
+                    return;
+                await this.deliver(item);
+            }
+        }
+        finally {
+            await deliveryAdapter(this.options.delivery).disconnect?.();
+        }
+    }
+    async deliver(item) {
+        try {
+            const result = await deliverToTarget(this.options.delivery, item, this.options.context);
+            await Promise.resolve(this.options.onResult?.(item, result));
+            if (result.status === 'deferred') {
+                await this.options.messaging.inbox.defer({
+                    inboxItemId: item.id,
+                    availableAt: result.availableAt ?? new Date(Date.now() + 30_000).toISOString(),
+                    reason: result.reason,
+                    metadata: result.metadata,
+                });
+                return;
+            }
+            if (result.status === 'failed') {
+                await this.options.messaging.inbox.fail({
+                    inboxItemId: item.id,
+                    error: result.reason ?? 'delivery adapter reported failure',
+                    retry: false,
+                    metadata: result.metadata,
+                });
+                return;
+            }
+            await this.options.messaging.inbox.ack({
+                inboxItemId: item.id,
+                state: result.status === 'delivered' ? 'delivered' : undefined,
+                metadata: result.metadata,
+            });
+        }
+        catch (error) {
+            await Promise.resolve(this.options.onError?.(item, error));
+            await this.options.messaging.inbox.fail({
+                inboxItemId: item.id,
+                error: error instanceof Error ? error.message : String(error),
+                retry: true,
+            });
+        }
+    }
+}
+async function deliverToTarget(target, item, context) {
+    if (typeof target.receiveMessage === 'function') {
+        return receiptToInjectionResult(await target.receiveMessage(item.message, {
+            id: context?.id ?? item.id,
+            mode: toMessageMode(context?.mode),
+            reason: toMessageReason(context?.reason),
+            priority: context?.priority,
+            deadline: context?.deadline,
+            idempotencyKey: context?.idempotencyKey,
+            metadata: context?.metadata,
+        }));
+    }
+    const adapter = deliveryAdapter(target);
+    if (typeof adapter.inject !== 'function') {
+        throw new Error('Delivery target must implement receiveMessage(...) or inject(...).');
+    }
+    return adapter.inject(item.message, {
+        reason: toInjectionReason(context?.reason),
+        priority: context?.priority,
+        mode: toInjectionMode(context?.mode),
+    });
+}
+function deliveryAdapter(target) {
+    return target;
+}
+function receiptToInjectionResult(receipt) {
+    return {
+        status: receipt.status,
+        ...('deliveryId' in receipt && receipt.deliveryId ? { injectionId: receipt.deliveryId } : {}),
+        ...('availableAt' in receipt ? { availableAt: dateToString(receipt.availableAt) } : {}),
+        ...('reason' in receipt && receipt.reason ? { reason: receipt.reason } : {}),
+        ...('metadata' in receipt && receipt.metadata ? { metadata: receipt.metadata } : {}),
+    };
+}
+function toMessageMode(mode) {
+    switch (mode) {
+        case 'append':
+            return 'next-message';
+        case 'interrupt':
+            return 'immediate';
+        case 'wait_until_idle':
+            return 'on-idle';
+        case 'next-message':
+        case 'next-tool-call':
+        case 'on-idle':
+        case 'manual':
+        case 'immediate':
+            return mode;
+        default:
+            return 'immediate';
+    }
+}
+function toMessageReason(reason) {
+    switch (reason) {
+        case 'thread_reply':
+            return 'thread-reply';
+        case 'action_result':
+            return 'action-result';
+        case 'dm':
+        case 'mention':
+        case 'message':
+            return reason;
+        default:
+            return 'message';
+    }
+}
+function toInjectionReason(reason) {
+    switch (reason) {
+        case 'thread-reply':
+            return 'thread_reply';
+        case 'action-result':
+            return 'action_result';
+        case 'notification':
+            return 'message';
+        case 'dm':
+        case 'mention':
+        case 'message':
+        case 'channel':
+        case 'thread_reply':
+        case 'action_result':
+            return reason;
+        default:
+            return 'message';
+    }
+}
+function toInjectionMode(mode) {
+    switch (mode) {
+        case 'immediate':
+            return 'interrupt';
+        case 'next-message':
+        case 'manual':
+            return 'append';
+        case 'on-idle':
+            return 'wait_until_idle';
+        case 'append':
+        case 'interrupt':
+        case 'wait_until_idle':
+            return mode;
+        default:
+            return undefined;
+    }
+}
+function dateToString(input) {
+    return input instanceof Date ? input.toISOString() : input;
+}
+//# sourceMappingURL=runner.js.map

package/dist/delivery/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/delivery/runner.ts"],"names":[],"mappings":"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"}

package/dist/delivery/types.d.ts

@@ -0,0 +1,45 @@
+import type { RelayMessage } from '../messaging/index.js';
+import type { Unsubscribe } from '../capabilities.js';
+import type { AgentSession, AgentSessionDeliveryMode, MessageContext, MessageReceipt } from '../session/index.js';
+export type AgentRuntimeStatus = 'idle' | 'busy' | 'offline' | 'unknown';
+export type DeliveryMode = AgentSessionDeliveryMode;
+export type DeliveryContext = MessageContext;
+export type DeliveryResult = MessageReceipt;
+export interface DeliveryCapabilities {
+    push: boolean;
+    interrupt: boolean;
+    detectIdle: boolean;
+    threads: boolean;
+    attachments: boolean;
+}
+export interface InjectionContext {
+    reason: 'dm' | 'channel' | 'mention' | 'thread_reply' | 'action_result' | 'message';
+    priority?: 'normal' | 'urgent';
+    mode?: 'append' | 'interrupt' | 'wait_until_idle';
+}
+export interface InjectionResult {
+    status: 'accepted' | 'delivered' | 'deferred' | 'failed';
+    injectionId?: string;
+    availableAt?: string;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentActivityEvent {
+    status: AgentRuntimeStatus;
+    at: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentDeliveryAdapter {
+    readonly id: string;
+    readonly kind?: string;
+    readonly capabilities: DeliveryCapabilities;
+    connect?(): Promise<void>;
+    disconnect?(): Promise<void>;
+    inject?(message: RelayMessage, context: InjectionContext): Promise<InjectionResult>;
+    receiveMessage?(message: RelayMessage, context: MessageContext): Promise<MessageReceipt>;
+    getStatus?(): Promise<AgentRuntimeStatus>;
+    interrupt?(): Promise<void>;
+    onActivity?(handler: (event: AgentActivityEvent) => void): Unsubscribe;
+}
+export type MessageDeliveryTarget = AgentDeliveryAdapter | AgentSession;
+//# sourceMappingURL=types.d.ts.map

package/dist/delivery/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/delivery/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EACV,YAAY,EACZ,wBAAwB,EACxB,cAAc,EACd,cAAc,EACf,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AACzE,MAAM,MAAM,YAAY,GAAG,wBAAwB,CAAC;AACpD,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC;AAC7C,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC;AAE5C,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,GAAG,eAAe,GAAG,SAAS,CAAC;IACpF,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,IAAI,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,iBAAiB,CAAC;CACnD;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,CAAC;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAC5C,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACpF,cAAc,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACzF,SAAS,CAAC,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC1C,SAAS,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,WAAW,CAAC;CACxE;AAED,MAAM,MAAM,qBAAqB,GAAG,oBAAoB,GAAG,YAAY,CAAC"}

package/dist/delivery/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/delivery/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/delivery/types.ts"],"names":[],"mappings":""}

package/dist/facade.d.ts

@@ -0,0 +1,151 @@
+import type { RelayMessaging, RelayMessage, RelayMessageReaction, RelayAgentRegistration, RelayAgentType, RelayMessageAttachmentInput, RelayMessageBlock, RelayMessageMode, RelaySendChannelMessageInput, RelayWorkspaceInfo } from './messaging/index.js';
+import { type AgentRelayActions, type ActionContext, type ActionHandle, type ActionPolicy, type ActionSchema } from './actions/index.js';
+import type { DeliveryMode } from './delivery/index.js';
+import type { RelayAgentHandle } from './listeners.js';
+/**
+ * A reference to an agent accepted by the high-level facade APIs. Agents may be
+ * passed as a bare name/handle string, or as an object carrying any of
+ * `name`, `handle`, `id`, and (for acting-as sends) `token`.
+ */
+export interface AgentRef {
+    name?: string;
+    handle?: string;
+    id?: string;
+    token?: string;
+    type?: RelayAgentType;
+    persona?: string;
+    metadata?: Record<string, unknown>;
+}
+export type AgentLike = string | AgentRef;
+/** Resolve an agent reference to its bare name (sigils such as `@`/`#` stripped). */
+export declare function resolveAgentName(ref: AgentLike): string;
+/** Resolve an agent reference to its auth token, when one is available (for acting-as sends). */
+export declare function resolveAgentToken(ref: AgentLike | undefined): string | undefined;
+export interface RelaySendMessageInput {
+    /** `#channel`, `@handle` (DM), or an array of `@handle`s (group DM). */
+    to: string | string[];
+    from?: AgentLike;
+    text?: string;
+    /** README shorthand for `text`. */
+    msg?: string;
+    mentions?: AgentLike[];
+    mode?: RelayMessageMode;
+    attachments?: RelayMessageAttachmentInput[];
+    blocks?: RelayMessageBlock[];
+    idempotencyKey?: string;
+}
+export interface RelayReplyInput {
+    messageId?: string;
+    thread?: string | {
+        id?: string;
+        threadId?: string;
+    };
+    from?: AgentLike;
+    text: string;
+    blocks?: RelayMessageBlock[];
+    idempotencyKey?: string;
+}
+export interface RelayReactInput {
+    message: string | {
+        id: string;
+    };
+    agent?: AgentLike;
+    emoji: string;
+}
+export interface RelayDirectInput {
+    to: string;
+    from?: AgentLike;
+    text?: string;
+    msg?: string;
+    attachments?: RelayMessageAttachmentInput[];
+    mode?: RelayMessageMode;
+    idempotencyKey?: string;
+}
+/** Messaging surface plus the high-level overloads documented in the README. */
+export type EnrichedMessages = RelayMessaging['messages'] & {
+    send(input: RelaySendChannelMessageInput | RelaySendMessageInput): Promise<RelayMessage>;
+    reply(input: RelayReplyInput): Promise<RelayMessage>;
+    react(input: RelayReactInput): Promise<RelayMessageReaction>;
+    react(messageId: string, emoji: string): Promise<RelayMessageReaction>;
+    dm(input: RelayDirectInput): Promise<RelayMessage>;
+};
+/** Emoji reaction input on the live agent client. */
+export interface RelayClientReactInput {
+    messageId: string;
+    emoji: string;
+}
+/**
+ * A live, registered agent. Returned by `relay.workspace.register(...)` /
+ * `reconnect(...)` and by harness `create(...)`. Carries the agent's identity
+ * and status/tool predicate builders alongside a messaging surface scoped to
+ * that agent.
+ */
+export interface RelayAgentClient extends RelayAgentHandle {
+    readonly agents: RelayMessaging['agents'];
+    readonly channels: RelayMessaging['channels'];
+    readonly messages: EnrichedMessages;
+    readonly threads: RelayMessaging['threads'];
+    readonly inbox: RelayMessaging['inbox'];
+    sendMessage(input: RelaySendMessageInput): Promise<RelayMessage>;
+    reply(input: RelayReplyInput): Promise<RelayMessage>;
+    react(input: RelayClientReactInput): Promise<RelayMessageReaction>;
+}
+/** Dependencies that let the workspace facade mint live agent clients. */
+export interface WorkspaceFacadeDeps {
+    buildAgentClient(registration: RelayAgentRegistration): RelayAgentClient;
+    reconnectAgent(apiToken: string): Promise<RelayAgentClient>;
+}
+export interface RelayWorkspace {
+    register<T extends AgentLike | AgentLike[]>(agents: T): Promise<T extends AgentLike[] ? RelayAgentClient[] : RelayAgentClient>;
+    reconnect(input: {
+        apiToken: string;
+    }): Promise<RelayAgentClient>;
+    info(): Promise<RelayWorkspaceInfo>;
+}
+export interface NotifyOptions {
+    type?: string;
+    action?: string;
+    subject?: AgentLike;
+    delivery?: DeliveryMode;
+    text?: string;
+}
+export type NotifyHandler = (event?: unknown) => Promise<void>;
+export interface RegisterActionInput<TInput = unknown, TOutput = unknown> {
+    name: string;
+    description?: string;
+    input?: ActionSchema<TInput>;
+    inputSchema?: ActionSchema<TInput>;
+    output?: ActionSchema<TOutput>;
+    outputSchema?: ActionSchema<TOutput>;
+    visibility?: 'agent' | 'human' | 'internal';
+    /** Restrict which agents may invoke this action. Omit to allow everyone. */
+    availableTo?: AgentLike[];
+    policy?: ActionPolicy;
+    handler(args: {
+        input: TInput;
+        agent: ActionContext['caller'];
+        ctx: ActionContext;
+    }): Promise<TOutput> | TOutput;
+}
+/**
+ * Resolves the messaging client to act through for a given `from` agent. When
+ * the agent carries a token, sends are attributed to that agent; otherwise the
+ * default (workspace) messaging client is used.
+ */
+export type MessagingResolver = (from: AgentLike | undefined) => RelayMessaging['messages'];
+export declare function createEnrichedMessages(base: RelayMessaging['messages'], resolveFrom: MessagingResolver): EnrichedMessages;
+export declare function createWorkspaceFacade(messaging: RelayMessaging, deps?: WorkspaceFacadeDeps): RelayWorkspace;
+/**
+ * Optional relay wiring for {@link registerFacadeAction}. When present and the
+ * messaging client carries an agent-scoped action surface, `registerAction`
+ * additionally registers the descriptor on the relay and subscribes the handler
+ * agent to `action.invoked` so it can run the handler and post the result back.
+ */
+export interface ActionRelayWiring {
+    messaging: RelayMessaging;
+    /** The agent that owns and runs the handler (descriptor `handler_agent`). */
+    handlerAgent?: string;
+}
+export declare function registerFacadeAction<TInput, TOutput>(actions: AgentRelayActions, def: RegisterActionInput<TInput, TOutput>, wiring?: ActionRelayWiring): ActionHandle;
+export declare function createNotifyHandler(messages: EnrichedMessages, target: AgentLike, options: NotifyOptions): NotifyHandler;
+//# sourceMappingURL=facade.d.ts.map

package/dist/facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facade.d.ts","sourceRoot":"","sources":["../src/facade.ts"],"names":[],"mappings":"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"}