@forge-sdk/comm

ANVIL Communication Contract: message transport, envelopes, and protocol negotiation

Package contract

Field	Value
Language	typescript
Source version	0.1.0
Manifest	`forge-ts/packages/forge-comm/package.json`
Source files	5
Evidence	Source reference; registry publication and runtime conformance are separate checks

Import boundary

import * as api from '@forge-sdk/comm';

Use a source checkout or your verified private registry. Manifest coordinates identify the package; they do not establish that a public registry release exists.

Download package reference JSON. Each original source file and generated declaration artifact has its own SHA-256 digest. Function bodies and constant values are omitted from downloads. These are source declaration inventories, not compiler-resolved rustdoc, TypeDoc, DocC, or Dokka output. Private modules can contain public declarations that are not reachable through the package boundary; consult the entry point before importing.

error.ts

Read declaration text · 3 declaration entries

export const CommErrorCode /* type inferred in source */;

export type CommErrorCodeType =
  (typeof CommErrorCode)[keyof typeof CommErrorCode];

export class CommError extends Error {
  readonly code: CommErrorCodeType;
  static serializationFailed(reason: string): CommError;
  static deserializationFailed(reason: string): CommError;
  static transportFailed(reason: string): CommError;
  static notConnected(): CommError;
  static channelClosed(): CommError;
  static signatureInvalid(sender: string): CommError;
  static protocolNegotiationFailed(offered: string, reason: string): CommError;
  static messageTooLarge(size: number, maxSize: number): CommError;
  static timeout(durationMs: number): CommError;
}

index.ts

Read declaration text · 4 declaration entries

export { AgentMessage } from './message.js';

export { type MessageTransport, NoopTransport } from './transport.js';

export {
  type ProtocolOffer,
  type ProtocolAccept,
  negotiateProtocol,
} from './protocol.js';

export {
  CommErrorCode,
  type CommErrorCodeType,
  CommError,
} from './error.js';

message.ts

Read declaration text · 1 declaration entries

export class AgentMessage {
  readonly id: string;
  readonly correlationId: string | undefined;
  readonly replyTo: string | undefined;
  readonly sender: string;
  readonly recipient: string;
  readonly protocol: string;
  readonly messageType: string;
  readonly payload: unknown;
  readonly signature: string | undefined;
  readonly timestamp: string;
  static create(
    sender: string,
    recipient: string,
    protocol: string,
    messageType: string,
    payload: unknown
  ): AgentMessage;
  kind(): string;
  isSigned(): boolean;
  withCorrelationId(id: string): AgentMessage;
  withReplyTo(id: string): AgentMessage;
  withSignature(sig: string): AgentMessage;
  toJSON(): Record<string, unknown>;
}

protocol.ts

Read declaration text · 3 declaration entries

export interface ProtocolOffer {
  /** The protocol identifier (e.g., "anvil.task"). */
  readonly protocol: string;
  /** The versions the offering agent supports, ordered by preference. */
  readonly versions: readonly string[];
  /** Optional extensions the offering agent supports. */
  readonly extensions: readonly string[];
}

export interface ProtocolAccept {
  /** The agreed-upon protocol identifier. */
  readonly protocol: string;
  /** The agreed-upon version string. */
  readonly version: string;
  /** The extensions active for this protocol session. */
  readonly extensions: readonly string[];
}

export function negotiateProtocol(
  offered: ProtocolOffer,
  supportedVersions: readonly string[]
): ProtocolAccept;

transport.ts

Read declaration text · 2 declaration entries

export interface MessageTransport {
  /**
   * Send a message to the recipient identified in the message envelope.
   *
   * @param message - The agent message envelope to send.
   * @throws {CommError} If the transport fails, channel is closed, or message is too large.
   */
  send(message: AgentMessage): Promise<void>;

  /**
   * Receive the next available message.
   *
   * @returns The next AgentMessage from the transport.
   * @throws {CommError} If the transport is not connected, channel is closed, or transport fails.
   */
  receive(): Promise<AgentMessage>;
}

export class NoopTransport implements MessageTransport {
  async send(_message: AgentMessage): Promise<void>;
  async receive(): Promise<AgentMessage>;
}