AI agent app reference

schema: 1
project: prj_template_ai_agent
baseline: main27
access:
  roles:
    support: [orders.*]
    member: [orders.read]
agents:
  support-bot:
    budget: { spend: $5/day, calls: 500/day }
    approve: { risk: destructive, spend-over: $1 }
mcp:
  confirm: { write: false, destructive: true }
ai:
  models: ['fake/*']
logging:
  audit: true
  retention: 12m
  redact: [personal, sensitive]
network:
  allow: []
  default: deny
  mode: observe

// The AI agent reference architecture: app actions become MCP tools, an agent acts under its own identity and budget,
// a destructive call waits for a person, and every audit record names the agent. Models are called through `ai`, never
// a model SDK directly, and the answer carries the AI disclosure text.
import { action, app, s } from 'mainsdk'

/** The line every agent answer carries: the person knows they talk to an AI (EU AI Act, article 50). */
export const DISCLOSURE = 'You are talking to an AI assistant.'

const orderId = s.object({ orderId: s.string() })

/** Read one order: allowed for a member, no confirmation. */
export const readOrder = action({
  name: 'orders.read',
  intent: 'Read one order',
  input: orderId,
  risk: 'read',
  mcp: true,
  resource: (i) => ({ type: 'orders', id: i.orderId, owner: i.orderId.split(':')[0] ?? '' }),
  run: ({ input }) => ({ order: input.orderId, status: 'shipped' }),
})

/** Refund one order: destructive, so an agent or an MCP client waits for a person's yes. */
export const refundOrder = action({
  name: 'orders.refund',
  intent: 'Refund one order',
  input: orderId,
  risk: 'destructive',
  mcp: true,
  spend: () => '$0.50',
  run: ({ input }) => ({ refunded: input.orderId }),
})

/** The MCP endpoint of the running app: tools are the actions marked `mcp: true`. */
export function mcpHandler(
  identify: Parameters<ReturnType<typeof app>['mcpServer']>[0]['identify'],
) {
  const a = app()
  return a.mcpServer({
    actions: [readOrder, refundOrder] as never,
    ...(identify ? { identify } : {}),
    // The person's answer to "may the agent do this?"; without a person present the answer is no.
    elicit: (c) => Promise.resolve((c.user as { confirm?: boolean } | undefined)?.confirm === true),
    log: a.log,
  })
}

/** Add the disclosure to an answer the agent gives a person. */
export function disclose(text: string): string {
  return `${text}\n\n${DISCLOSURE}`
}