@crosshands/contract 0.1.5 → 0.2.0

package/src/errors.ts

@@ -26,41 +26,67 @@ export const ERROR_CATALOG = {
   accessibility_error: { retry: true, remediation: 'check_accessibility_permission' }
 } as const
 
+export const PUBLIC_ERROR_CATALOG = {
+  goal_mismatch: { retry: true, remediation: 'refresh_state' },
+  policy_unavailable: { retry: true, remediation: 'refresh_state' },
+  intent_unavailable: { retry: false, remediation: 'correct_request' }
+} as const
+
+const COMBINED_ERROR_CATALOG = {
+  ...ERROR_CATALOG,
+  ...PUBLIC_ERROR_CATALOG
+} as const
+
 export type ComputerErrorCode = keyof typeof ERROR_CATALOG
-export type ComputerErrorRemediation = (typeof ERROR_CATALOG)[ComputerErrorCode]['remediation']
+export type PublicErrorCode = keyof typeof PUBLIC_ERROR_CATALOG
+export type PublicComputerErrorCode = ComputerErrorCode | PublicErrorCode
+export type ComputerErrorRemediation =
+  (typeof COMBINED_ERROR_CATALOG)[PublicComputerErrorCode]['remediation']
 
-export const ComputerErrorCodeSchema = z.enum(
-  Object.keys(ERROR_CATALOG) as [ComputerErrorCode, ...ComputerErrorCode[]]
-)
+function errorCodeSchema<T extends string>(catalog: Record<T, unknown>): z.ZodEnum<Record<T, T>> {
+  const codes = Object.keys(catalog) as [T, ...T[]]
+  return z.enum(codes)
+}
 
-export const SerializedComputerErrorSchema = z
-  .object({
-    code: ComputerErrorCodeSchema,
-    message: z.string().min(1),
-    retry: z.boolean(),
-    remediation: z.string().min(1),
-    details: z.unknown().optional()
-  })
-  .strict()
+export const ComputerErrorCodeSchema = errorCodeSchema(ERROR_CATALOG)
+export const PublicComputerErrorCodeSchema = errorCodeSchema(COMBINED_ERROR_CATALOG)
+
+function serializedErrorSchema<T extends z.ZodEnum<Record<string, string>>>(code: T) {
+  return z
+    .object({
+      code,
+      message: z.string().min(1),
+      retry: z.boolean(),
+      remediation: z.string().min(1),
+      details: z.unknown().optional()
+    })
+    .strict()
+}
+
+export const SerializedComputerErrorSchema = serializedErrorSchema(ComputerErrorCodeSchema)
+export const PublicSerializedComputerErrorSchema = serializedErrorSchema(
+  PublicComputerErrorCodeSchema
+)
 
 export type SerializedComputerError = z.infer<typeof SerializedComputerErrorSchema>
+export type PublicSerializedComputerError = z.infer<typeof PublicSerializedComputerErrorSchema>
 
 export class ComputerError extends Error {
-  readonly code: ComputerErrorCode
+  readonly code: PublicComputerErrorCode
   readonly retry: boolean
   readonly remediation: ComputerErrorRemediation
   readonly details: unknown
 
-  constructor(code: ComputerErrorCode, message: string, details?: unknown) {
+  constructor(code: PublicComputerErrorCode, message: string, details?: unknown) {
     super(message)
     this.name = 'ComputerError'
     this.code = code
-    this.retry = ERROR_CATALOG[code].retry
-    this.remediation = ERROR_CATALOG[code].remediation
+    this.retry = COMBINED_ERROR_CATALOG[code].retry
+    this.remediation = COMBINED_ERROR_CATALOG[code].remediation
     this.details = details
   }
 
-  toJSON(): SerializedComputerError {
+  toJSON(): PublicSerializedComputerError {
     return this.details === undefined
       ? { code: this.code, message: this.message, retry: this.retry, remediation: this.remediation }
       : {
@@ -71,10 +97,14 @@ export class ComputerError extends Error {
           details: this.details
         }
   }
+
+  toBrokerJSON(): SerializedComputerError {
+    return SerializedComputerErrorSchema.parse(this.toJSON())
+  }
 }
 
 export function createComputerError(
-  code: ComputerErrorCode,
+  code: PublicComputerErrorCode,
   message: string,
   details?: unknown
 ): ComputerError {

package/src/json-schema.ts

@@ -1,11 +1,9 @@
-import { COMPUTER_OPERATIONS } from './operations.js'
+import { COMPUTER_OPERATIONS, PUBLIC_OPERATIONS } from './operations.js'
 import { CONTRACT_VERSIONS } from './versions.js'
 
-export const contractJsonSchemas = {
-  $schema: 'https://json-schema.org/draft/2020-12/schema',
-  versions: CONTRACT_VERSIONS,
-  operations: Object.fromEntries(
-    Object.entries(COMPUTER_OPERATIONS).map(([name, operation]) => [
+function schemaCatalog(operations: typeof COMPUTER_OPERATIONS | typeof PUBLIC_OPERATIONS) {
+  return Object.fromEntries(
+    Object.entries(operations).map(([name, operation]) => [
       name,
       {
         mutation: operation.mutation,
@@ -14,4 +12,11 @@ export const contractJsonSchemas = {
       }
     ])
   )
+}
+
+export const contractJsonSchemas = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  versions: CONTRACT_VERSIONS,
+  operations: schemaCatalog(COMPUTER_OPERATIONS),
+  publicOperations: schemaCatalog(PUBLIC_OPERATIONS)
 } as const

package/src/operations.ts

@@ -1,10 +1,15 @@
 import { z } from 'zod'
 
+import { createComputerError } from './errors.js'
 import {
   AppInfoSchema,
+  GoalSchema,
+  IntentTargetSchema,
   InteractionContextTokenSchema,
   MutationResultSchema,
   ProviderCapabilitiesSchema,
+  PublicMutationResultSchema,
+  PublicSnapshotResultSchema,
   ScreenshotSchema,
   SnapshotResultSchema,
   TargetReferenceSchema,
@@ -116,13 +121,21 @@ export const COMPUTER_OPERATIONS = {
   },
   getAppState: {
     mutation: false,
-    input: z
-      .object({
-        app: AppQuerySchema,
-        window: WindowSelectorSchema.optional(),
-        ...CaptureOptionsShape
-      })
-      .strict(),
+    input: z.union([
+      z
+        .object({
+          app: AppQuerySchema,
+          window: WindowSelectorSchema.optional(),
+          ...CaptureOptionsShape
+        })
+        .strict(),
+      z
+        .object({
+          contextToken: InteractionContextTokenSchema,
+          ...CaptureOptionsShape
+        })
+        .strict()
+    ]),
     output: SnapshotResultSchema
   },
   click: {
@@ -212,13 +225,133 @@ export const COMPUTER_OPERATIONS = {
 } as const
 
 export type ComputerOperationName = keyof typeof COMPUTER_OPERATIONS
+export type BrokerOperationInput<K extends ComputerOperationName> = z.infer<
+  (typeof COMPUTER_OPERATIONS)[K]['input']
+>
+export type PublicOperationInput<K extends ComputerOperationName> = z.infer<
+  (typeof PUBLIC_OPERATIONS)[K]['input']
+>
+
+const PublicActionTargetSchema = z.union([ActionTargetSchema, IntentTargetSchema])
+const PublicElementTargetSchema = z.union([ElementActionTargetSchema, IntentTargetSchema])
+
+function publicMutationInput(brokerInput: z.ZodObject<z.ZodRawShape>, target: z.ZodType) {
+  return brokerInput
+    .omit({ target: true })
+    .extend({
+      target,
+      goal: GoalSchema.optional()
+    })
+    .strict()
+}
+
+function withOptionalGoal(schema: z.ZodObject<z.ZodRawShape>) {
+  return schema.extend({ goal: GoalSchema.optional() }).strict()
+}
+
+const getAppStateArms = COMPUTER_OPERATIONS.getAppState.input.options
+
+export const PUBLIC_OPERATIONS = {
+  ...COMPUTER_OPERATIONS,
+  getAppState: {
+    mutation: false,
+    input: z.union([withOptionalGoal(getAppStateArms[0]), withOptionalGoal(getAppStateArms[1])]),
+    output: PublicSnapshotResultSchema
+  },
+  click: {
+    mutation: true,
+    input: publicMutationInput(COMPUTER_OPERATIONS.click.input, PublicActionTargetSchema),
+    output: PublicMutationResultSchema
+  },
+  performSecondaryAction: {
+    mutation: true,
+    input: publicMutationInput(
+      COMPUTER_OPERATIONS.performSecondaryAction.input,
+      PublicElementTargetSchema
+    ),
+    output: PublicMutationResultSchema
+  },
+  scroll: {
+    mutation: true,
+    input: publicMutationInput(COMPUTER_OPERATIONS.scroll.input, PublicActionTargetSchema),
+    output: PublicMutationResultSchema
+  },
+  setValue: {
+    mutation: true,
+    input: publicMutationInput(COMPUTER_OPERATIONS.setValue.input, PublicElementTargetSchema),
+    output: PublicMutationResultSchema
+  }
+} as const
 
-export function parseOperationInput(operation: ComputerOperationName, input: unknown): unknown {
-  return COMPUTER_OPERATIONS[operation].input.parse(input)
+export function parseOperationInput<K extends ComputerOperationName>(
+  operation: K,
+  input: unknown
+): BrokerOperationInput<K> {
+  return COMPUTER_OPERATIONS[operation].input.parse(input) as BrokerOperationInput<K>
 }
 
 export function parseOperationOutput(operation: ComputerOperationName, output: unknown): unknown {
   return COMPUTER_OPERATIONS[operation].output.parse(output)
 }
 
+export function hasIntentTarget(input: unknown): boolean {
+  if (input === null || typeof input !== 'object' || Array.isArray(input) || !('target' in input)) {
+    return false
+  }
+  const target = input.target
+  return (
+    target !== null &&
+    typeof target === 'object' &&
+    !Array.isArray(target) &&
+    'kind' in target &&
+    target.kind === 'intent'
+  )
+}
+
+function requireGoalForIntent(input: unknown): void {
+  if (!hasIntentTarget(input)) return
+  const goal = (input as { goal?: unknown }).goal
+  if (typeof goal !== 'string' || goal.length === 0) {
+    throw createComputerError('invalid_argument', 'intent targeting requires goal')
+  }
+}
+
+export function parsePublicInput<K extends ComputerOperationName>(
+  operation: K,
+  input: unknown
+): PublicOperationInput<K> {
+  const parsed = PUBLIC_OPERATIONS[operation].input.parse(input) as PublicOperationInput<K>
+  requireGoalForIntent(parsed)
+  return parsed
+}
+
+export function parsePublicOutput(operation: ComputerOperationName, output: unknown): unknown {
+  return PUBLIC_OPERATIONS[operation].output.parse(output)
+}
+
+export function splitPublicInput<T extends object>(
+  input: T
+): { goal: string | undefined; rest: Omit<T, 'goal'> } {
+  if (!('goal' in input)) return { goal: undefined, rest: input as Omit<T, 'goal'> }
+  const { goal, ...rest } = input as T & { goal?: unknown }
+  return {
+    goal: typeof goal === 'string' && goal.length > 0 ? goal : undefined,
+    rest: rest as Omit<T, 'goal'>
+  }
+}
+
+export function toBrokerInput<K extends ComputerOperationName>(
+  operation: K,
+  publicInput: object
+): BrokerOperationInput<K> {
+  const { rest } = splitPublicInput(publicInput)
+  if (hasIntentTarget(rest)) {
+    throw createComputerError(
+      'invalid_argument',
+      'intent targeting must be bound before broker parse'
+    )
+  }
+  return parseOperationInput(operation, rest)
+}
+
 export const ScreenshotOutputSchema = ScreenshotSchema

package/src/schemas.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
 
-import { SerializedComputerErrorSchema } from './errors.js'
+import { PublicSerializedComputerErrorSchema, SerializedComputerErrorSchema } from './errors.js'
 
 const FiniteNumberSchema = z.number().finite()
 const NonNegativeIntegerSchema = z.number().int().nonnegative()
@@ -110,16 +110,19 @@ export const SnapshotSchema = z
   })
   .strict()
 
-export const MutationOutcomeSchema = z.discriminatedUnion('state', [
-  z.object({ state: z.literal('verified'), evidence: z.unknown().optional() }).strict(),
-  z.object({ state: z.literal('indeterminate'), reason: z.string().optional() }).strict(),
-  z
-    .object({ state: z.literal('failed'), error: SerializedComputerErrorSchema.optional() })
-    .strict(),
-  z
-    .object({ state: z.literal('not_attempted'), error: SerializedComputerErrorSchema.optional() })
-    .strict()
-])
+function mutationOutcomeSchema<T extends z.ZodType>(errorSchema: T) {
+  return z.discriminatedUnion('state', [
+    z.object({ state: z.literal('verified'), evidence: z.unknown().optional() }).strict(),
+    z.object({ state: z.literal('indeterminate'), reason: z.string().optional() }).strict(),
+    z.object({ state: z.literal('failed'), error: errorSchema.optional() }).strict(),
+    z.object({ state: z.literal('not_attempted'), error: errorSchema.optional() }).strict()
+  ])
+}
+
+export const MutationOutcomeSchema = mutationOutcomeSchema(SerializedComputerErrorSchema)
+export const PublicMutationOutcomeSchema = mutationOutcomeSchema(
+  PublicSerializedComputerErrorSchema
+)
 
 export type MutationOutcome = z.infer<typeof MutationOutcomeSchema>
 
@@ -132,6 +135,60 @@ export const SnapshotResultSchema = z
   })
   .strict()
 
+export type SnapshotResult = z.infer<typeof SnapshotResultSchema>
+
+export const GoalSchema = z.string().trim().min(1).max(512)
+
+export const IntentTargetSchema = z.object({ kind: z.literal('intent') }).strict()
+
+export const SuggestionMoveSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('click'), elementIndex: NonNegativeIntegerSchema }).strict(),
+  z.object({ kind: z.literal('setValue'), elementIndex: NonNegativeIntegerSchema }).strict(),
+  z
+    .object({
+      kind: z.literal('secondary'),
+      elementIndex: NonNegativeIntegerSchema,
+      action: z.string().min(1).max(256)
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal('scroll'),
+      elementIndex: NonNegativeIntegerSchema,
+      direction: z.enum(['up', 'down', 'left', 'right'])
+    })
+    .strict(),
+  z.object({ kind: z.literal('wait') }).strict(),
+  z.object({ kind: z.literal('done') }).strict(),
+  z.object({ kind: z.literal('blocked'), reason: z.string().min(1).max(256) }).strict()
+])
+
+export const SuggestionSchema = z
+  .object({
+    untrusted: z.literal(true),
+    snapshotId: IdentifierSchema,
+    move: SuggestionMoveSchema,
+    confidence: z.number().min(0).max(1).optional(),
+    label: z.string().optional()
+  })
+  .strict()
+
+export type Suggestion = z.infer<typeof SuggestionSchema>
+
+export const ResolvedTargetSchema = z
+  .object({
+    kind: z.literal('element'),
+    elementIndex: NonNegativeIntegerSchema
+  })
+  .strict()
+
+export const PublicSnapshotResultSchema = SnapshotResultSchema.omit({ issues: true })
+  .extend({
+    issues: z.array(PublicSerializedComputerErrorSchema).default([]),
+    suggestion: SuggestionSchema.optional()
+  })
+  .strict()
+
 export const MutationResultSchema = z
   .object({
     outcome: MutationOutcomeSchema,
@@ -139,13 +196,44 @@ export const MutationResultSchema = z
   })
   .strict()
 
+export type MutationResult = z.infer<typeof MutationResultSchema>
+
+export const PublicMutationResultSchema = z
+  .object({
+    outcome: PublicMutationOutcomeSchema,
+    freshState: SnapshotResultSchema.optional(),
+    resolvedTarget: ResolvedTargetSchema.optional(),
+    suggestion: SuggestionSchema.optional()
+  })
+  .strict()
+
+const BooleanFlagMapSchema = z.record(z.string(), z.boolean())
+
+export const ProviderSupportsSchema = z
+  .object({
+    apps: BooleanFlagMapSchema.optional(),
+    windows: BooleanFlagMapSchema.optional(),
+    surfaces: BooleanFlagMapSchema.optional(),
+    observation: BooleanFlagMapSchema.optional(),
+    actions: BooleanFlagMapSchema.optional()
+  })
+  .strict()
+
+export const ProviderHelperIdentitySchema = z
+  .object({
+    name: z.string().min(1),
+    bundleId: z.string().min(1)
+  })
+  .strict()
+
 export const ProviderCapabilitiesSchema = z
   .object({
     platform: z.enum(['darwin', 'win32', 'linux']),
     provider: IdentifierSchema,
     providerVersion: z.string().min(1),
     operations: z.record(z.string(), z.boolean()),
-    permissions: z.record(z.string(), z.enum(['granted', 'denied', 'unknown', 'not_required']))
+    permissions: z.record(z.string(), z.enum(['granted', 'denied', 'unknown', 'not_required'])),
+    supports: ProviderSupportsSchema.optional()
   })
   .strict()
 
@@ -156,6 +244,7 @@ export const ProviderHandshakeSchema = z
     graphicalSessionId: IdentifierSchema,
     providerProtocol: PositiveIntegerSchema,
     publicContract: z.string().min(1),
-    capabilities: ProviderCapabilitiesSchema
+    capabilities: ProviderCapabilitiesSchema,
+    helper: ProviderHelperIdentitySchema.optional()
   })
   .strict()

package/src/versions.ts

@@ -1,8 +1,8 @@
 import { createComputerError } from './errors.js'
 
 export const CONTRACT_VERSIONS = {
-  product: '0.1.5',
-  publicContract: '1.1.0',
+  product: '0.2.0',
+  publicContract: '1.2.0',
   brokerControl: 1,
   providerProtocol: 1,
   mcpProtocol: '2025-11-25'