@classic-homes/agent-contracts 0.0.0-stage → 0.1.0

package/dist/chat.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { DocumentContext } from './context.js';
+import { AgentKey, ConversationId, FileId, RequestId } from './ids.js';
+import { LIMITS } from './limits.js';
+import { OperationResult } from './operations.js';
+/** Which client sent a request. Lets the backend shape tool availability and rendering hints. */
+export const ClientKind = z.enum(['office', 'app']);
+/** Body of `POST /api/chat`. */
+export const ChatRequest = z.object({
+    requestId: RequestId,
+    /** Omit to start a new conversation; the `start` event returns the assigned ID. */
+    conversationId: ConversationId.optional(),
+    agent: AgentKey.default('classic-agent'),
+    message: z.string().trim().min(1).max(LIMITS.messageChars),
+    context: DocumentContext.optional(),
+    /** Host-confirmed outcomes of earlier proposals, so the agent can continue accurately. */
+    operationResults: z.array(OperationResult).max(LIMITS.operationResults).optional(),
+    /** Files already uploaded through `POST /api/files` to attach to this turn. */
+    fileIds: z.array(FileId).max(LIMITS.requestFiles).optional(),
+    client: ClientKind.optional(),
+});
+//# sourceMappingURL=chat.js.map

package/dist/chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.js","sourceRoot":"","sources":["../src/chat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,iGAAiG;AACjG,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AAGpD,gCAAgC;AAChC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,SAAS,EAAE,SAAS;IACpB,mFAAmF;IACnF,cAAc,EAAE,cAAc,CAAC,QAAQ,EAAE;IACzC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,eAAe,CAAC;IACxC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC;IAC1D,OAAO,EAAE,eAAe,CAAC,QAAQ,EAAE;IACnC,0FAA0F;IAC1F,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,QAAQ,EAAE;IAClF,+EAA+E;IAC/E,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE;IAC5D,MAAM,EAAE,UAAU,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,245 @@
+import { z } from 'zod';
+/** A single Excel cell value as Office.js reports it. Empty cells are `""`. */
+export declare const CellValue: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+export type CellValue = z.infer<typeof CellValue>;
+export declare const Grid: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+export type Grid = z.infer<typeof Grid>;
+/** Excel sheet names: 1-31 chars, none of `: \ / ? * [ ]`. */
+export declare const SheetName: z.ZodString;
+/** Bounded single-area A1 address without a sheet prefix. */
+export declare const A1Address: z.ZodString;
+export declare function gridShape(grid: readonly (readonly unknown[])[]): [number, number] | null;
+/** True when the grid is rectangular and matches the address dimensions. */
+export declare function gridMatchesAddress(grid: readonly (readonly unknown[])[], address: string): boolean;
+export declare const ExcelSelection: z.ZodObject<{
+    sheet: z.ZodString;
+    address: z.ZodString;
+    values: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    formulas: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+}, z.core.$strip>;
+export type ExcelSelection = z.infer<typeof ExcelSelection>;
+/**
+ * Word target captured by the bridge. `targetId` is an opaque, bridge-issued handle valid
+ * only while the pane stays open; `expectedText` is re-checked before any write.
+ */
+export declare const WordTarget: z.ZodObject<{
+    targetId: z.ZodString;
+    expectedText: z.ZodString;
+}, z.core.$strip>;
+export type WordTarget = z.infer<typeof WordTarget>;
+export declare const WordSelection: z.ZodObject<{
+    text: z.ZodString;
+    isEmpty: z.ZodBoolean;
+    target: z.ZodObject<{
+        targetId: z.ZodString;
+        expectedText: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type WordSelection = z.infer<typeof WordSelection>;
+export declare const ExcelContext: z.ZodObject<{
+    selection: z.ZodObject<{
+        sheet: z.ZodString;
+        address: z.ZodString;
+        values: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+        formulas: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    }, z.core.$strip>;
+    documentId: z.ZodString;
+    capturedAt: z.ZodISODateTime;
+    simulated: z.ZodBoolean;
+    host: z.ZodLiteral<"excel">;
+}, z.core.$strip>;
+export declare const WordContext: z.ZodObject<{
+    selection: z.ZodObject<{
+        text: z.ZodString;
+        isEmpty: z.ZodBoolean;
+        target: z.ZodObject<{
+            targetId: z.ZodString;
+            expectedText: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    documentId: z.ZodString;
+    capturedAt: z.ZodISODateTime;
+    simulated: z.ZodBoolean;
+    host: z.ZodLiteral<"word">;
+}, z.core.$strip>;
+/** Kinds of Classic App records a page can put in front of the agent. */
+export declare const AppRecordKind: z.ZodEnum<{
+    home: "home";
+    lot: "lot";
+    community: "community";
+    filing: "filing";
+    floorplan: "floorplan";
+    elevation: "elevation";
+    district: "district";
+    user: "user";
+    vendor: "vendor";
+    sign: "sign";
+    "slide-deck": "slide-deck";
+    survey: "survey";
+    workspace: "workspace";
+    walk: "walk";
+    permit: "permit";
+    incentive: "incentive";
+}>;
+export type AppRecordKind = z.infer<typeof AppRecordKind>;
+export declare const AppRecordRef: z.ZodObject<{
+    kind: z.ZodEnum<{
+        home: "home";
+        lot: "lot";
+        community: "community";
+        filing: "filing";
+        floorplan: "floorplan";
+        elevation: "elevation";
+        district: "district";
+        user: "user";
+        vendor: "vendor";
+        sign: "sign";
+        "slide-deck": "slide-deck";
+        survey: "survey";
+        workspace: "workspace";
+        walk: "walk";
+        permit: "permit";
+        incentive: "incentive";
+    }>;
+    id: z.ZodString;
+    label: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AppRecordRef = z.infer<typeof AppRecordRef>;
+/**
+ * Scope the backend resolves company agent context for (CHAPI `/v2/agent-context/resolve`).
+ * At most one key, mirroring that endpoint. The app never sends the resolved text itself.
+ */
+export declare const AgentContextTarget: z.ZodObject<{
+    homeRid: z.ZodOptional<z.ZodNumber>;
+    lotRid: z.ZodOptional<z.ZodNumber>;
+    elevationRid: z.ZodOptional<z.ZodNumber>;
+    floorplanRid: z.ZodOptional<z.ZodNumber>;
+    filingRid: z.ZodOptional<z.ZodNumber>;
+    communityRid: z.ZodOptional<z.ZodNumber>;
+    districtId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AgentContextTarget = z.infer<typeof AgentContextTarget>;
+/**
+ * Context a Classic App page attaches to a turn: where the user is and which record they are
+ * looking at. Sent per turn, only when the user keeps the context toggle on. Never the page's
+ * whole data set; `facts` are a page-chosen whitelist.
+ */
+export declare const AppContext: z.ZodObject<{
+    host: z.ZodLiteral<"app">;
+    capturedAt: z.ZodISODateTime;
+    route: z.ZodString;
+    title: z.ZodString;
+    tab: z.ZodOptional<z.ZodString>;
+    record: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            home: "home";
+            lot: "lot";
+            community: "community";
+            filing: "filing";
+            floorplan: "floorplan";
+            elevation: "elevation";
+            district: "district";
+            user: "user";
+            vendor: "vendor";
+            sign: "sign";
+            "slide-deck": "slide-deck";
+            survey: "survey";
+            workspace: "workspace";
+            walk: "walk";
+            permit: "permit";
+            incentive: "incentive";
+        }>;
+        id: z.ZodString;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    target: z.ZodOptional<z.ZodObject<{
+        homeRid: z.ZodOptional<z.ZodNumber>;
+        lotRid: z.ZodOptional<z.ZodNumber>;
+        elevationRid: z.ZodOptional<z.ZodNumber>;
+        floorplanRid: z.ZodOptional<z.ZodNumber>;
+        filingRid: z.ZodOptional<z.ZodNumber>;
+        communityRid: z.ZodOptional<z.ZodNumber>;
+        districtId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    facts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    selection: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AppContext = z.infer<typeof AppContext>;
+/**
+ * Explicitly serialized context for one turn: an Office selection or a Classic App page.
+ * Never the whole workbook, document or data set.
+ */
+export declare const DocumentContext: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    selection: z.ZodObject<{
+        sheet: z.ZodString;
+        address: z.ZodString;
+        values: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+        formulas: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    }, z.core.$strip>;
+    documentId: z.ZodString;
+    capturedAt: z.ZodISODateTime;
+    simulated: z.ZodBoolean;
+    host: z.ZodLiteral<"excel">;
+}, z.core.$strip>, z.ZodObject<{
+    selection: z.ZodObject<{
+        text: z.ZodString;
+        isEmpty: z.ZodBoolean;
+        target: z.ZodObject<{
+            targetId: z.ZodString;
+            expectedText: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    documentId: z.ZodString;
+    capturedAt: z.ZodISODateTime;
+    simulated: z.ZodBoolean;
+    host: z.ZodLiteral<"word">;
+}, z.core.$strip>, z.ZodObject<{
+    host: z.ZodLiteral<"app">;
+    capturedAt: z.ZodISODateTime;
+    route: z.ZodString;
+    title: z.ZodString;
+    tab: z.ZodOptional<z.ZodString>;
+    record: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            home: "home";
+            lot: "lot";
+            community: "community";
+            filing: "filing";
+            floorplan: "floorplan";
+            elevation: "elevation";
+            district: "district";
+            user: "user";
+            vendor: "vendor";
+            sign: "sign";
+            "slide-deck": "slide-deck";
+            survey: "survey";
+            workspace: "workspace";
+            walk: "walk";
+            permit: "permit";
+            incentive: "incentive";
+        }>;
+        id: z.ZodString;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    target: z.ZodOptional<z.ZodObject<{
+        homeRid: z.ZodOptional<z.ZodNumber>;
+        lotRid: z.ZodOptional<z.ZodNumber>;
+        elevationRid: z.ZodOptional<z.ZodNumber>;
+        floorplanRid: z.ZodOptional<z.ZodNumber>;
+        filingRid: z.ZodOptional<z.ZodNumber>;
+        communityRid: z.ZodOptional<z.ZodNumber>;
+        districtId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    facts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    selection: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "host">;
+export type DocumentContext = z.infer<typeof DocumentContext>;
+export type ExcelContext = z.infer<typeof ExcelContext>;
+export type WordContext = z.infer<typeof WordContext>;
+/** A captured Office selection: the only contexts a document edit can be proposed against. */
+export type OfficeContext = ExcelContext | WordContext;
+export declare function isOfficeContext(context: DocumentContext): context is OfficeContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,+EAA+E;AAC/E,eAAO,MAAM,SAAS,0EAKpB,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAElD,eAAO,MAAM,IAAI,kGAA8B,CAAC;AAChD,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;AAExC,8DAA8D;AAC9D,eAAO,MAAM,SAAS,aAIK,CAAC;AAE5B,6DAA6D;AAC7D,eAAO,MAAM,SAAS,aAIyE,CAAC;AAEhG,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAKxF;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,EACrC,OAAO,EAAE,MAAM,GACd,OAAO,CAIT;AAED,eAAO,MAAM,cAAc;;;;;iBAwBvB,CAAC;AACL,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,UAAU;;;iBAGrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,aAAa;;;;;;;iBAIxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAS1D,eAAO,MAAM,YAAY;;;;;;;;;;;iBAIvB,CAAC;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;iBAItB,CAAC;AAEH,yEAAyE;AACzE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;EAiBxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;iBAOvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAGxD;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;iBAY3B,CAAC;AACL,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAIpE;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiBrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAC9D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACxD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,8FAA8F;AAC9F,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,WAAW,CAAC;AACvD,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,IAAI,aAAa,CAElF"}

package/dist/context.js

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+import { parseA1Range } from './a1.js';
+import { DocumentId } from './ids.js';
+import { LIMITS } from './limits.js';
+/** A single Excel cell value as Office.js reports it. Empty cells are `""`. */
+export const CellValue = z.union([
+    z.string().max(LIMITS.excelCellChars),
+    z.number(),
+    z.boolean(),
+    z.null(),
+]);
+export const Grid = z.array(z.array(CellValue));
+/** Excel sheet names: 1-31 chars, none of `: \ / ? * [ ]`. */
+export const SheetName = z
+    .string()
+    .min(1)
+    .max(31)
+    .regex(/^[^:\\/?*[\]]+$/);
+/** Bounded single-area A1 address without a sheet prefix. */
+export const A1Address = z
+    .string()
+    .min(2)
+    .max(32)
+    .refine((value) => parseA1Range(value) !== null, 'Expected a bounded A1 range such as B2:D5');
+export function gridShape(grid) {
+    const rows = grid.length;
+    const cols = grid[0]?.length ?? 0;
+    if (rows === 0 || cols === 0)
+        return null;
+    return grid.every((row) => row.length === cols) ? [rows, cols] : null;
+}
+/** True when the grid is rectangular and matches the address dimensions. */
+export function gridMatchesAddress(grid, address) {
+    const range = parseA1Range(address);
+    const shape = gridShape(grid);
+    return !!range && !!shape && shape[0] === range.rowCount && shape[1] === range.columnCount;
+}
+export const ExcelSelection = z
+    .object({
+    sheet: SheetName,
+    address: A1Address,
+    values: Grid,
+    /** Formulas as Office.js reports them: a formula string, or the constant value. */
+    formulas: Grid,
+})
+    .superRefine((sel, ctx) => {
+    const range = parseA1Range(sel.address);
+    if (range && range.rowCount * range.columnCount > LIMITS.excelCells) {
+        ctx.addIssue({ code: 'custom', message: `Selection exceeds ${LIMITS.excelCells} cells` });
+        return;
+    }
+    if (!gridMatchesAddress(sel.values, sel.address)) {
+        ctx.addIssue({ code: 'custom', path: ['values'], message: 'values do not match address' });
+    }
+    if (!gridMatchesAddress(sel.formulas, sel.address)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['formulas'],
+            message: 'formulas do not match address',
+        });
+    }
+});
+/**
+ * Word target captured by the bridge. `targetId` is an opaque, bridge-issued handle valid
+ * only while the pane stays open; `expectedText` is re-checked before any write.
+ */
+export const WordTarget = z.object({
+    targetId: z.string().min(1).max(128),
+    expectedText: z.string().max(LIMITS.wordChars),
+});
+export const WordSelection = z.object({
+    text: z.string().max(LIMITS.wordChars),
+    isEmpty: z.boolean(),
+    target: WordTarget,
+});
+const contextBase = {
+    documentId: DocumentId,
+    capturedAt: z.iso.datetime(),
+    /** True when produced by the browser simulator rather than a real Office host. */
+    simulated: z.boolean(),
+};
+export const ExcelContext = z.object({
+    host: z.literal('excel'),
+    ...contextBase,
+    selection: ExcelSelection,
+});
+export const WordContext = z.object({
+    host: z.literal('word'),
+    ...contextBase,
+    selection: WordSelection,
+});
+/** Kinds of Classic App records a page can put in front of the agent. */
+export const AppRecordKind = z.enum([
+    'home',
+    'lot',
+    'community',
+    'filing',
+    'floorplan',
+    'elevation',
+    'district',
+    'user',
+    'vendor',
+    'sign',
+    'slide-deck',
+    'survey',
+    'workspace',
+    'walk',
+    'permit',
+    'incentive',
+]);
+export const AppRecordRef = z.object({
+    kind: AppRecordKind,
+    /** The record's own key in CHAPI (homeRid, lotRid, bunitRid, uuid, ...). */
+    id: z.string().min(1).max(64),
+    label: z.string().min(1).max(200),
+    /** App path the agent may link back to. Path only, no origin or query. */
+    path: z.string().startsWith('/').max(500).optional(),
+});
+const rid = z.number().int().positive();
+/**
+ * Scope the backend resolves company agent context for (CHAPI `/v2/agent-context/resolve`).
+ * At most one key, mirroring that endpoint. The app never sends the resolved text itself.
+ */
+export const AgentContextTarget = z
+    .object({
+    homeRid: rid.optional(),
+    lotRid: rid.optional(),
+    elevationRid: rid.optional(),
+    floorplanRid: rid.optional(),
+    filingRid: rid.optional(),
+    communityRid: rid.optional(),
+    districtId: z.string().min(1).max(64).optional(),
+})
+    .refine((t) => Object.values(t).filter((v) => v !== undefined).length <= 1, {
+    message: 'at most one scope key',
+});
+const FactValue = z.union([z.string().max(LIMITS.appFactChars), z.number(), z.boolean(), z.null()]);
+/**
+ * Context a Classic App page attaches to a turn: where the user is and which record they are
+ * looking at. Sent per turn, only when the user keeps the context toggle on. Never the page's
+ * whole data set; `facts` are a page-chosen whitelist.
+ */
+export const AppContext = z.object({
+    host: z.literal('app'),
+    capturedAt: z.iso.datetime(),
+    /** App pathname only, no origin or query. */
+    route: z.string().startsWith('/').max(300),
+    title: z.string().max(200),
+    tab: z.string().max(60).optional(),
+    record: AppRecordRef.optional(),
+    target: AgentContextTarget.optional(),
+    facts: z
+        .record(z.string().min(1).max(40), FactValue)
+        .refine((f) => Object.keys(f).length <= LIMITS.appFacts, {
+        message: `at most ${LIMITS.appFacts} facts`,
+    })
+        .optional(),
+    /** Text the user highlighted on the page, if any. */
+    selection: z.string().max(LIMITS.appSelectionChars).optional(),
+});
+/**
+ * Explicitly serialized context for one turn: an Office selection or a Classic App page.
+ * Never the whole workbook, document or data set.
+ */
+export const DocumentContext = z.discriminatedUnion('host', [
+    ExcelContext,
+    WordContext,
+    AppContext,
+]);
+export function isOfficeContext(context) {
+    return context.host === 'excel' || context.host === 'word';
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

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