A field-service app for the phone (ai-agent)
A maintenance technician’s app built for a 390 px screen: a start page that says what needs doing now, jobs as cards, a focused job file, and a “New” button that takes a note by voice, camera or keyboard. The assistant knows the open job, offers suggestions derived from it and proposes writes that the technician approves.
What it shows
Section titled “What it shows”- Focus shell. One top bar, the content below, “New” as a floating button. Lists become cards, the job file is a focus screen with banner, next steps, key figures and tabs, all declared as ordinary Kumiko screens.
- The “New” sheet. A bottom drawer titled “New” with three large entries: Speak, Take a photo, Write. Taking a photo stores a
field-notewith the image on the open job. Speaking opens a full-screen capture; speaking and writing send their text to the assistant with the open job as focus, and the answer is a plan card with three steps: write the note, order the spare part, queue a message to the customer. Each step can be switched off before “Apply”, and only the chosen steps run. Without a text provider writing stores a plain note, so the path without AI is complete. Speaking appears only once a tenant has a transcription provider. - Real handlers behind the plan.
field-note:create,part-order:createandcustomer-notice:createare ordinaryr.crudcreates with an agent description and risk. The e2e server scripts the mock provider to answer with all three in one response. - Assistant with context. Suggestion chips come from the open record (start, complete, check the parts). Slash commands (
/today,/jobs,/note) open a screen or a form. - Proposing is not doing. The assistant proposes “complete this job” on an approval card; only “Apply” runs the handler.
- Installable. The app ships a manifest and icons and offers an install hint on the start page.
When to reach for it
Section titled “When to reach for it”Any app whose users work away from a desk: technicians, caretakers, inspectors. Start here when the phone is the main screen and notes, photos and short questions matter more than forms.
Working sample
Section titled “Working sample”This recipe includes a runnable app under src/app/. Start it with FILE_STORAGE_PROVIDER=inmemory bun run src/app/server.ts, open http://localhost:4190 in a phone-sized window and sign in as tech@field-service.example / field-service-demo. The browser suite under e2e/ drives the same app with a scripted mock provider and renders the documented screenshots as a theme and locale matrix.
The mock provider is a deterministic demo backend. Replace it with ai-provider-anthropic or ai-provider-openai-compat when you connect the recipe to a real tenant provider.
The recipe is also the working sample used by the public documentation: /en/enterprise/samples/field-service-mobile/.
Wiring
Section titled “Wiring”src/mount.ts mounts the domain feature next to createAiAgentFeature() on the server, src/client.ts contributes the web half. src/app/new-entry-launcher.tsx and src/app/new-entry-sheet.tsx hold the “New” button and the sheet; they use Drawer with side="bottom" from @cosmicdrift/kumiko-renderer/web, the camera capture from @cosmicdriftgamestudio/kumiko-ai-agent/web and the field-note:create handler. All texts are translations of the recipe (src/i18n.ts).
bun --env-file=../.env test --config=bunfig.integration.toml samples/recipes/field-service-mobileSource code
Section titled “Source code”The feature entry point — embedded straight from the source file, so the code here is exactly what runs. Multi-file samples keep their remaining files next to it on GitHub (link below):
// Field-service sample: a technician's day on a phone. Shows focus screens, list cards, the// assistant with suggestion chips and slash commands, and voice/photo notes on an open job.// The "needs action" text is computed by the queries from the record and never stored.
import { createEntityExecutor, defineFeature } from "@cosmicdrift/kumiko-framework/engine";import { failNotFound, failTransition } from "@cosmicdrift/kumiko-framework/errors";import { z } from "zod";import { ACCESS_ROLES, FEATURE_NAME, type WorkOrderStatus } from "./constants.ts";import { customerNoticeEntity, fieldNoteEntity, partOrderEntity, workOrderEntity,} from "./entities.ts";import { fieldServiceTranslations } from "./i18n.ts";import { fieldNoteCreateScreen, todayScreen, workOrderFileScreen, workOrdersScreen,} from "./screens.ts";import { boardSchema, emptySchema, idSchema, workOrderBoard, workOrderBriefing, workOrderFile, workOrderNow,} from "./work-order-queries.ts";
const access = { roles: ACCESS_ROLES };const transitionSchema = z.object({ id: z.uuid(), version: z.number() });
export const fieldServiceFeature = defineFeature(FEATURE_NAME, (r) => { r.translations({ keys: fieldServiceTranslations });
r.crud(workOrderEntity, { write: { access }, read: { access }, verbs: { create: true, update: false, delete: false, restore: false, list: true, detail: true, }, descriptions: { create: "Plan a new maintenance job for a customer site.", list: "Search maintenance jobs by number, title, customer or asset.", detail: "Read one maintenance job by id.", }, agents: { create: { risk: "low" } }, });
r.crud(fieldNoteEntity, { write: { access }, read: { access }, verbs: { create: true, update: false, delete: false, restore: false, list: true, detail: true, }, descriptions: { create: "Leave a note on the road, optionally tied to one maintenance job.", list: "Search field notes by text, or list the notes of one job.", detail: "Read one field note by id.", }, agents: { create: { risk: "low" } }, });
r.crud(partOrderEntity, { write: { access }, read: { access }, verbs: { create: true, update: false, delete: false, restore: false, list: true, detail: true, }, descriptions: { create: "Order a spare part for one maintenance job.", list: "List the spare parts ordered for a job.", detail: "Read one spare part order by id.", }, agents: { create: { risk: "mid" } }, });
r.crud(customerNoticeEntity, { write: { access }, read: { access }, verbs: { create: true, update: false, delete: false, restore: false, list: true, detail: true, }, descriptions: { create: "Queue a short message to the customer of one maintenance job; the office sends it.", list: "List the messages queued for the customer of a job.", detail: "Read one customer message by id.", }, agents: { create: { risk: "mid" } }, });
const { table, executor } = createEntityExecutor(workOrderEntity);
const transition = async ( payload: z.infer<typeof transitionSchema>, to: WorkOrderStatus, allowedFrom: readonly WorkOrderStatus[], user: Parameters<typeof executor.update>[1], db: Parameters<typeof executor.update>[2], ) => { const [current] = await db.selectMany(table, { id: payload.id }, { limit: 1 }); if (!current) return failNotFound("work-order", payload.id); const from = String(current["status"]); if (!allowedFrom.some((allowed) => allowed === from)) { return failTransition(from, to, allowedFrom); } return executor.update( { id: payload.id, version: payload.version, changes: { status: to } }, user, db, ); };
r.writeHandler({ name: "work-order:start", schema: transitionSchema, handler: async (event, ctx) => transition( event.payload, "in-progress", ["scheduled", "waiting-for-parts"], event.user, ctx.db, ), access, description: "Start a maintenance job by id once the technician is on site.", agent: { risk: "low" }, });
r.writeHandler({ name: "work-order:complete", schema: transitionSchema, handler: async (event, ctx) => transition(event.payload, "done", ["in-progress"], event.user, ctx.db), access, description: "Mark a maintenance job as done by id after the work and the report are finished.", agent: { risk: "mid" }, });
r.queryHandler({ name: "work-order:board", schema: boardSchema, handler: async (query, ctx) => workOrderBoard(ctx, query.user, query.payload), access, }); r.queryHandler({ name: "work-order:now", schema: emptySchema, handler: async (query, ctx) => workOrderNow(ctx, query.user), access, }); r.queryHandler({ name: "work-order:briefing", schema: emptySchema, handler: async (query, ctx) => workOrderBriefing(ctx, query.user), access, }); r.queryHandler({ name: "work-order:file", schema: idSchema, handler: async (query, ctx) => workOrderFile(ctx, query.user, query.payload.id), access, });
r.screen(todayScreen); r.screen(workOrdersScreen); r.screen(workOrderFileScreen); r.screen(fieldNoteCreateScreen);
r.nav({ id: "today", label: `${FEATURE_NAME}:nav.today`, icon: "home", screen: `${FEATURE_NAME}:screen:today`, order: 10, }); r.nav({ id: "work-orders", label: `${FEATURE_NAME}:nav.work-orders`, icon: "list", screen: `${FEATURE_NAME}:screen:work-orders`, order: 20, }); r.workspace({ id: "main", label: `${FEATURE_NAME}:workspace.main`, icon: "briefcase", default: true, access, nav: [`${FEATURE_NAME}:nav:today`, `${FEATURE_NAME}:nav:work-orders`], });});Enterprise recipe source is included in the generated docs mirror; the commercial workspace is not publicly browsable.