Wake your agent

Kody runs jobs, subscriptions, and webhooks while your agent is closed. To pull the agent back in when one of them needs it, pick the path the agent's host actually supports. A laptop agent with no wake path cannot be woken. Say so, and offer to build the Kody half now.

Pick a path

Check before you choose. If server/discover on /mcp shows an events capability, the client can use MCP Events. Kody only advertises events while the mcp-events-extension flag is on, so if the capability is missing and the client supports events, ask the user to turn the flag on before you fall back. If you do not know whether the host has a wake URL, ask the user rather than guessing.

MCP Events

MCP Events let the client subscribe to topics your packages emit. Kody POSTs a signed event to the client's callback, and the client wakes the agent. Nothing to host and no URL to store.

• The surface is behind the mcp-events-extension feature flag. The user turns it on from the MCP Events guide page on the website, or joins experiments.
• Supported clients: ChatGPT (Work chats on web, desktop Work + Cloud, dots) on protocol 2026-07-28. Other hosts work only if they advertise events support and implement webhook subscribe and delivery. Cursor and Claude do not today.
• Opt a topic in with "mcp": true on its package.json#kody.emits entry, and events.dispatch it from the package. To surface a Kody topic such as run.error.recorded, subscribe a small package to it and re-emit an opted-in topic.

POST to the webhook

For hosts that expose a wake URL, a package does the POST. Trigger it with a subscription (run.error.recorded, a package-emitted topic, email.message.received), an inbound webhook from an outside system (see Triggers), or a job on a schedule.

Store the full wake URL as a URL credential so the package never holds it. Code passes an empty path to POST to the stored URL itself. If the host also wants a bearer token, declare it as a separate Key need. Example: wake the agent when a run fails.

{
	"name": "@you/wake-on-error",
	"exports": { ".": "./src/index.ts" },
	"kody": {
		"description": "Wake my agent when a run fails.",
		"credentials": {
			"agent-wake": {
				"kind": "url",
				"description": "My agent's wake URL"
			}
		},
		"subscriptions": {
			"run.error.recorded": {
				"handler": "./src/on-run-error.ts",
				"description": "POST failed runs to my agent."
			}
		}
	}
}

import { credential } from 'kody:runtime'

export default async function onRunError(event: {
	run: { name: string | null; error_message: string | null }
	activity_url: string
}) {
	const wake = await credential('agent-wake')
	const response = await wake.fetch('', {
		method: 'POST',
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify({
			text: `Kody run ${event.run.name ?? ''} failed: ${event.run.error_message ?? ''}`,
			link: event.activity_url,
		}),
	})
	if (!response.ok) throw new Error(`Wake POST failed: ${response.status}`)
	return { handled: true }
}

run.error.recorded is best-effort, and failed subscription handlers (this one included) never emit it, so treat the wake as a nudge, not a guarantee. Send the agent the activity_url and a one-line reason, not logs. The agent can call runGet when it wakes. Payload fields are in Package subscriptions.

Email wake

Every account has an inbox ({username}@inbox.kody.codes) and plus-tags route on it. A subscription on email.message.received can wake the agent from a tagged message, or mail a host that wakes on email. See Agent inbox for the plus-tag pattern and a live example.

Where to go next

• MCP Events: flag, topic opt-in, delivery.
• Package subscriptions: every Kody topic.
• Credentials: URL and Key credentials.
• Agent inbox: email triggers.