@multiplayer-app/ai-agent-types 0.0.1-beta.2 → 0.0.1

package/README.md

@@ -2,6 +2,198 @@
 
 Shared TypeScript contracts for Multiplayer AI agent clients, transports, and services.
 
+## Context attachments (`AgentAttachmentType.Context`)
+
+This package supports attaching **structured context** to a user message as attachments. These attachments are:
+
+- **Small**: meant to be _snippets_, not full-page dumps.
+- **Typed + versioned**: `metadata.schemaVersion` is required (currently `1`).
+- **Safe by default**: web snippets are treated as _untrusted_ content by the server prompt renderer.
+- **Extensible**: library consumers can introduce **custom `kind`s** without forking.
+
+### Where it lives
+
+A context attachment is a normal `AgentAttachment` with:
+
+- `type: AgentAttachmentType.Context`
+- `metadata: ContextAttachmentMetadataV1`
+
+### `security.containsPII` and `security.redactionsApplied`
+
+Context attachments may include sensitive information (emails, names, phone numbers, addresses, account IDs, access tokens, etc.). The optional `metadata.security` block is **declarative metadata** to help the host app/service apply correct privacy and retention policies:
+
+- **`containsPII: true`**: “This attachment may contain PII / sensitive data.” This does **not** automatically protect anything; it is a signal for logging/storage/prompt policy decisions.
+- **`redactionsApplied: string[]`**: An audit trail of what sanitization you already applied before attaching it. Example values: `['email', 'phone', 'credit_card', 'access_token']`.
+
+If you set `containsPII: true` with `redactionsApplied: []`, you are explicitly saying: **“this may contain sensitive data and we did not redact it.”**
+
+### Built-in kinds (v1)
+
+Built-ins have strict validation and well-known shapes:
+
+- `webSnippet`: selected text from a webpage (plus optional title/source)
+- `formSnapshot`: a set of form fields at a point in time
+- `formField`: a single field value
+
+### Custom kinds (v1)
+
+If `metadata.kind` is **not** one of the built-ins, it is treated as a **custom kind** with a bounded generic shape:
+
+- `title?: string`
+- `summary?: string`
+- `data?: Record<string, unknown>` (budgeted; rejected if too large)
+
+Custom kinds must **not** collide with built-in kind names.
+
+### Validating attachments (Zod)
+
+This package exports shared schemas you can use in services/clients:
+
+- `ContextAttachmentMetadataSchemaV1`
+- `AgentAttachmentSchema`
+- `SendMessagePayloadSchema`
+
+Example:
+
+```ts
+import { AgentAttachmentSchema, SendMessagePayloadSchema, AgentAttachmentType } from '@multiplayer-app/ai-agent-types'
+
+const payload = SendMessagePayloadSchema.parse({
+  content: 'Can you summarize this?',
+  contextKey: 'support',
+  attachments: [
+    {
+      id: 'att-1',
+      type: AgentAttachmentType.Context,
+      name: 'Selection: Billing policy',
+      url: 'https://example.com/policy',
+      metadata: {
+        schemaVersion: 1,
+        kind: 'webSnippet',
+        capturedAt: new Date().toISOString(),
+        title: 'Billing policy',
+        selectedText: 'Customers may request a refund within 30 days...',
+        source: { app: 'browser', url: 'https://example.com/policy' },
+        security: { containsPII: true, redactionsApplied: [] }
+      }
+    }
+  ]
+})
+
+// You can also validate just one attachment:
+AgentAttachmentSchema.parse(payload.attachments?.[0])
+```
+
+### Built-in examples
+
+#### `webSnippet`
+
+```ts
+{
+  id: 'att-1',
+  type: AgentAttachmentType.Context,
+  name: 'Selection: Checkout page',
+  url: 'https://app.example.com/checkout',
+  metadata: {
+    schemaVersion: 1,
+    kind: 'webSnippet',
+    capturedAt: '2026-01-09T08:00:00.000Z',
+    title: 'Checkout',
+    selectedText: 'Error: card declined (code 54)',
+    source: { app: 'browser', url: 'https://app.example.com/checkout' },
+    security: { containsPII: true, redactionsApplied: [] }
+  }
+}
+```
+
+#### `formSnapshot`
+
+```ts
+{
+  id: 'att-2',
+  type: AgentAttachmentType.Context,
+  name: 'Form snapshot: Lead',
+  metadata: {
+    schemaVersion: 1,
+    kind: 'formSnapshot',
+    capturedAt: '2026-01-09T08:00:00.000Z',
+    formId: 'leadForm',
+    formName: 'Lead',
+    fields: [
+      { name: 'company', label: 'Company', value: 'Acme Inc.' },
+      { name: 'plan', label: 'Plan', value: 'Enterprise' }
+    ],
+    security: { containsPII: true, redactionsApplied: [] }
+  }
+}
+```
+
+#### `formField`
+
+```ts
+{
+  id: 'att-3',
+  type: AgentAttachmentType.Context,
+  name: 'Field: Budget',
+  metadata: {
+    schemaVersion: 1,
+    kind: 'formField',
+    capturedAt: '2026-01-09T08:00:00.000Z',
+    formId: 'leadForm',
+    fieldName: 'budget',
+    fieldLabel: 'Budget',
+    value: '$25k',
+    security: { containsPII: true, redactionsApplied: [] }
+  }
+}
+```
+
+### Custom kind example
+
+```ts
+{
+  id: 'att-5',
+  type: AgentAttachmentType.Context,
+  name: 'CRM context',
+  metadata: {
+    schemaVersion: 1,
+    kind: 'crmRecord', // custom kind
+    capturedAt: '2026-01-09T08:00:00.000Z',
+    title: 'Account: Acme Inc.',
+    summary: 'Renewal in 14 days. Open escalation on billing.',
+    data: {
+      accountId: 'acc_123',
+      renewalDate: '2026-01-23',
+      health: 'yellow'
+    },
+    security: { containsPII: true, redactionsApplied: ['email'] }
+  }
+}
+```
+
+### Custom objection example (recommended)
+
+`objection` is intentionally **not** a built-in kind. Represent objections as a **custom kind** using `summary`/`data`:
+
+```ts
+{
+  id: 'att-4',
+  type: AgentAttachmentType.Context,
+  name: 'Objection: Pricing',
+  metadata: {
+    schemaVersion: 1,
+    kind: 'objection', // custom kind
+    capturedAt: '2026-01-09T08:00:00.000Z',
+    summary: 'It’s too expensive compared to Vendor X.',
+    data: {
+      label: 'Price',
+      evidence: 'Vendor X quoted $18k/year for similar seats.'
+    },
+    security: { containsPII: false, redactionsApplied: [] }
+  }
+}
+```
+
 ## Scripts
 
 ```bash

package/dist/attachments/context.d.ts

@@ -0,0 +1,112 @@
+import type { AgentAttachment } from '../models.js';
+import { AgentAttachmentType } from '../enums.js';
+export declare const BuiltinContextAttachmentKinds: readonly ["webSnippet", "formSnapshot", "formField"];
+export type BuiltinContextAttachmentKind = (typeof BuiltinContextAttachmentKinds)[number];
+/**
+ * Allow library consumers to introduce custom kinds without forking.
+ *
+ * Built-in kinds get strict typing + validation; unknown kinds fall back to a bounded generic schema.
+ */
+export type ContextAttachmentKind = BuiltinContextAttachmentKind | (string & {});
+export type FormInputType = 'text' | 'textarea' | 'number' | 'select' | 'radio' | 'checkbox' | 'date' | 'email' | 'tel';
+export interface FormSelectOption {
+    value: string;
+    label: string;
+}
+export interface ContextAttachmentSourceV1 {
+    app?: string;
+    url?: string;
+    route?: string;
+    domPath?: string;
+}
+export interface ContextAttachmentSecurityV1 {
+    /**
+     * Treat as PII-bearing unless explicitly false.
+     */
+    containsPII?: boolean;
+    redactionsApplied?: string[];
+}
+export interface ContextTextSelectionTargetV1 {
+    /**
+     * Text quote selector (robust across minor DOM changes).
+     */
+    type: 'text';
+    exact: string;
+    prefix?: string;
+    suffix?: string;
+    /**
+     * Optional container selector where selection was taken.
+     */
+    domPath?: string;
+    /**
+     * Optional offsets relative to container text. Helpful but not reliable across rerenders.
+     */
+    startOffset?: number;
+    endOffset?: number;
+}
+export interface ContextDomTargetV1 {
+    type: 'dom';
+    domPath: string;
+}
+export interface ContextFormTargetV1 {
+    type: 'form';
+    formId?: string;
+    fieldName?: string;
+    domPath?: string;
+}
+export type ContextAttachmentTargetV1 = ContextTextSelectionTargetV1 | ContextDomTargetV1 | ContextFormTargetV1;
+export interface ContextAttachmentMetadataBaseV1 {
+    schemaVersion: 1;
+    kind: ContextAttachmentKind;
+    capturedAt: string;
+    source?: ContextAttachmentSourceV1;
+    security?: ContextAttachmentSecurityV1;
+    /**
+     * Optional locator/selector to re-find or highlight the originating UI element later.
+     */
+    target?: ContextAttachmentTargetV1;
+}
+export interface WebSnippetContextV1 extends ContextAttachmentMetadataBaseV1 {
+    kind: 'webSnippet';
+    title?: string;
+    selectedText: string;
+}
+export interface FormSnapshotContextV1 extends ContextAttachmentMetadataBaseV1 {
+    kind: 'formSnapshot';
+    formId?: string;
+    formName?: string;
+    fields: Array<{
+        name: string;
+        label?: string;
+        value: string;
+        inputType?: FormInputType;
+        options?: FormSelectOption[];
+        domPath?: string;
+    }>;
+}
+export interface FormFieldContextV1 extends ContextAttachmentMetadataBaseV1 {
+    kind: 'formField';
+    formId?: string;
+    fieldName: string;
+    fieldLabel?: string;
+    value: string;
+    inputType?: FormInputType;
+    options?: FormSelectOption[];
+    domPath?: string;
+}
+/**
+ * Generic, bounded context metadata for custom kinds. Consumers should define their
+ * own schemas on top of `data` if they need stronger validation.
+ */
+export interface CustomContextMetadataV1 extends ContextAttachmentMetadataBaseV1 {
+    kind: Exclude<string, BuiltinContextAttachmentKind>;
+    title?: string;
+    summary?: string;
+    data?: Record<string, unknown>;
+}
+export type ContextAttachmentMetadataV1 = WebSnippetContextV1 | FormSnapshotContextV1 | FormFieldContextV1 | CustomContextMetadataV1;
+export type ContextAgentAttachment = Omit<AgentAttachment, 'type' | 'metadata'> & {
+    type: AgentAttachmentType.Context;
+    metadata: ContextAttachmentMetadataV1;
+};
+//# sourceMappingURL=context.d.ts.map

package/dist/attachments/context.d.ts.map

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

package/dist/attachments/context.js

@@ -0,0 +1,6 @@
+export const BuiltinContextAttachmentKinds = [
+    'webSnippet',
+    'formSnapshot',
+    'formField',
+];
+//# sourceMappingURL=context.js.map

package/dist/attachments/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/attachments/context.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,YAAY;IACZ,cAAc;IACd,WAAW;CACH,CAAC"}