Personal assistant

​

What this example demonstrates

1. Pair the person in the application, before any Checkfu call. The app sends a single-use, short-lived pairing code into the DM and accepts it only when the same member echoes it back in the same DM. That proves continuity of the conversation; the authenticator is the application, not Checkfu.
2. Provision one Principal and one Agent per person. The person’s Principal is found again by its external subject. The person holds act_as and approve on their own Agent, and the Agent holds use_environment on the Environment.
3. Start one direct Session for the DM with acted_as set to the person and the person’s principal-owned MemoryStore mounted read-write. Admission is refused without act_as, use_environment, or the Agent’s grant on the store. The Session is created with the ordinary Session API.
4. Connect an app with connections.apply. The Connection is owned by the person; connections.apply mints use_connection and use_tool for the person and their Agent and pins the Connection on the Agent as a new AgentVersion. The DM moves to a new Session on that version with the same acted_as and memory mount.
5. Decide ActionApprovals as the person. The app reads the parked approval from the event log, renders the draft only when the logged arguments hash to the frozen digest, and calls actionApprovals.decide with expected_version and acted_as the person. The ledger names the person, with the app’s key as the authenticating caller.
6. Keep reminders app-side. The app serves reminder Custom tools that act only for the platform-frozen actedAs, keeps the schedule in its own state, and drives the person’s current DM Session when a reminder is due. The resulting Run is the person’s Run, bounded like a message they typed.

DM message → app pairing code → Principal + Agent per person
                                      │
                                      ▼
Session (acted_as = person) → Runs → durable event log
  │
  ├── MemoryStore (owned by the person, granted only to their Agent)
  ├── connected tool → person + Agent access → ActionPolicy → ActionApproval → provider effect
  └── Custom tool (reminders) → application handler → result

App-side scheduler → user.message into the person's Session

​

Retention, delivery, and recovery boundaries

​

Pinned source boundary

const readRequiresActionApproval = (
	event: SessionEvent,
): { readonly approvalId: string; readonly toolUseId: string } | null => {
	if (event.type !== "run.requires_action") return null
	const payload = event.payload
	if (!isJsonRecord(payload)) return null
	const record = payload.action
	if (!isJsonRecord(record)) return null
	if (jsonField(record, "kind") !== "action_approval") return null
	const approvalId = jsonField(record, "approval")
	const toolUseId = jsonField(record, "tool_use_id")
	if (typeof approvalId !== "string" || typeof toolUseId !== "string") return null
	return { approvalId, toolUseId }
}

​

What this example omits