Skip to content

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.

  • 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-note with 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:create and customer-notice:create are ordinary r.crud creates 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.

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.

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/.

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).

Terminal window
bun --env-file=../.env test --config=bunfig.integration.toml samples/recipes/field-service-mobile

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.