@guuey/hooks 0.26.0 → 0.28.0

package/README.md

@@ -40,6 +40,26 @@ Prebuilt hooks (`use: 'email-reporter'`) and dev-defined ones share this spec.
   `@guuey/config`.
 - `toWireToolName('server.tool')` → `mcp__server__tool` — the one function
   both config names and the runtime's tool extractor call.
+- An agent definition's `tools` is required and exact: `[]` mounts nothing
+  (a summariser that only writes its output); there is no "absent = every
+  declared server" default.
+- An agent definition's optional `output` is a JSON Schema for the run's
+  structured output (the runtime hands it to the model's structured-output
+  mode); a `required` tool the model skipped is called with that output.
+- `PREBUILT_DEFINITIONS` / `prebuiltBinding(name, event)` — the prebuilt
+  catalog, ONE copy for the runtime and the dispatcher, keyed per event.
+  `email-reporter`: on `session.ended` an agent run with `tools: []` writes
+  the report as its `output` and the platform makes the call — the pod never
+  mounts a first-party server for a hook run. On `handoff.requested` it binds
+  nothing (`{ kind: 'skip' }`): the platform's notifier already mails every
+  hand-off whenever the reporter is on, so a declaration there is legal and
+  simply recorded `skipped`.
+- `hookInvokeRequestSchema` / `hookInvokeResultSchema` / `HOOK_DOOR_PATH` —
+  the wire between the dispatcher and the runtime's hook door
+  (`POST <pod origin>/agent/hook`): `{ runId, name, event, timeoutMs }` in,
+  `{ runId, status: ok|failed, output?, effects, error? }` out. The pod
+  resolves the hook by `name` from its own snapshot or the prebuilt catalog,
+  never from the wire.
 
 Everything is optional both ways across a rolling release: a `guuey.json`
 without `hooks` behaves exactly as before.

package/dist/index.d.ts

@@ -61,6 +61,11 @@ export type JsonValue = JsonPrimitive | JsonValue[] | {
 };
 /** A JSON-shaped value — the hook's `output` and a reserved event's `data`. */
 export declare const jsonValueSchema: z.ZodType<JsonValue>;
+/** A JSON object — a tool call's arguments, a hook's structured output when a tool must be called with it. */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export declare const jsonObjectSchema: z.ZodType<JsonObject>;
 /** `"<server>.<tool>"` — the name a config uses for one tool. */
 export declare const toolNameSchema: z.ZodString;
 /** `"<server>.<tool>"` or `"<server>.*"` — an allowlist entry. */
@@ -225,6 +230,29 @@ export declare const hookHandlerRefSchema: z.ZodUnion<readonly [z.ZodObject<{
     definition: z.ZodString;
 }, z.core.$strict>]>;
 export type HookHandlerRef = z.infer<typeof hookHandlerRefSchema>;
+declare const agentDefinitionSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"agent">;
+    on: z.ZodArray<z.ZodEnum<{
+        "session.ended": "session.ended";
+        "handoff.requested": "handoff.requested";
+        "session.idled": "session.idled";
+        "turn.completed": "turn.completed";
+        "session.started": "session.started";
+        "turn.start": "turn.start";
+        "schedule.tick": "schedule.tick";
+    }>>;
+    instruction: z.ZodString;
+    tools: z.ZodArray<z.ZodString>;
+    required: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    model: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        small: "small";
+    }>>;
+    maxTurns: z.ZodOptional<z.ZodNumber>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    output: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
+    actAs: z.ZodOptional<z.ZodLiteral<"hook">>;
+}, z.core.$strict>;
 export declare const hookDefinitionSchema: z.ZodUnion<readonly [z.ZodObject<{
     kind: z.ZodLiteral<"agent">;
     on: z.ZodArray<z.ZodEnum<{
@@ -237,7 +265,7 @@ export declare const hookDefinitionSchema: z.ZodUnion<readonly [z.ZodObject<{
         "schedule.tick": "schedule.tick";
     }>>;
     instruction: z.ZodString;
-    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tools: z.ZodArray<z.ZodString>;
     required: z.ZodOptional<z.ZodArray<z.ZodString>>;
     model: z.ZodOptional<z.ZodEnum<{
         default: "default";
@@ -245,6 +273,7 @@ export declare const hookDefinitionSchema: z.ZodUnion<readonly [z.ZodObject<{
     }>>;
     maxTurns: z.ZodOptional<z.ZodNumber>;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
+    output: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
     actAs: z.ZodOptional<z.ZodLiteral<"hook">>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"tool">;
@@ -260,6 +289,7 @@ export declare const hookDefinitionSchema: z.ZodUnion<readonly [z.ZodObject<{
     tool: z.ZodString;
 }, z.core.$strict>]>;
 export type HookDefinition = z.infer<typeof hookDefinitionSchema>;
+export type AgentHookDefinition = z.infer<typeof agentDefinitionSchema>;
 export declare const hooksSectionSchema: z.ZodObject<{
     'session.ended': z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
         use: z.ZodString;
@@ -343,7 +373,7 @@ export declare const hooksSectionSchema: z.ZodObject<{
             "schedule.tick": "schedule.tick";
         }>>;
         instruction: z.ZodString;
-        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tools: z.ZodArray<z.ZodString>;
         required: z.ZodOptional<z.ZodArray<z.ZodString>>;
         model: z.ZodOptional<z.ZodEnum<{
             default: "default";
@@ -351,6 +381,7 @@ export declare const hooksSectionSchema: z.ZodObject<{
         }>>;
         maxTurns: z.ZodOptional<z.ZodNumber>;
         timeoutMs: z.ZodOptional<z.ZodNumber>;
+        output: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
         actAs: z.ZodOptional<z.ZodLiteral<"hook">>;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"tool">;
@@ -381,4 +412,200 @@ export declare const hooksSectionSchema: z.ZodObject<{
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 export type HooksSection = z.infer<typeof hooksSectionSchema>;
+/** Where a live pod answers hook runs: `POST <pod origin>/agent/hook`. */
+export declare const HOOK_DOOR_PATH = "/agent/hook";
+/**
+ * What the dispatcher POSTs. Minimal by design: the pod resolves the hook's
+ * definition (instruction, tools, required, output, timeout) BY NAME — from
+ * its own snapshot for a dev-defined hook, from {@link PREBUILT_DEFINITIONS}
+ * for a prebuilt — never from the wire, so nothing on the wire can widen a
+ * hook's reach. `timeoutMs` is the dispatcher's wait; the pod caps it by the
+ * definition's own.
+ */
+export declare const hookInvokeRequestSchema: z.ZodObject<{
+    runId: z.ZodString;
+    name: z.ZodString;
+    event: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"session.ended">;
+        data: z.ZodObject<{
+            reason: z.ZodLiteral<"idle">;
+            idleMinutes: z.ZodNumber;
+            lastActivityAt: z.ZodISODateTime;
+            turns: z.ZodNumber;
+            handoff: z.ZodOptional<z.ZodObject<{
+                question: z.ZodString;
+                contactEmail: z.ZodOptional<z.ZodString>;
+                contactName: z.ZodOptional<z.ZodString>;
+                summary: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        threadId: z.ZodString;
+        id: z.ZodString;
+        at: z.ZodISODateTime;
+        appId: z.ZodString;
+        hook: z.ZodObject<{
+            name: z.ZodString;
+            runId: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"handoff.requested">;
+        data: z.ZodObject<{
+            question: z.ZodString;
+            contactEmail: z.ZodOptional<z.ZodString>;
+            contactName: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        threadId: z.ZodString;
+        id: z.ZodString;
+        at: z.ZodISODateTime;
+        appId: z.ZodString;
+        hook: z.ZodObject<{
+            name: z.ZodString;
+            runId: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"schedule.tick">;
+        data: z.ZodObject<{
+            schedule: z.ZodString;
+            scheduledFor: z.ZodISODateTime;
+        }, z.core.$strict>;
+        id: z.ZodString;
+        at: z.ZodISODateTime;
+        appId: z.ZodString;
+        hook: z.ZodObject<{
+            name: z.ZodString;
+            runId: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodEnum<{
+            "session.idled": "session.idled";
+            "turn.completed": "turn.completed";
+            "session.started": "session.started";
+            "turn.start": "turn.start";
+        }>;
+        data: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
+        threadId: z.ZodString;
+        id: z.ZodString;
+        at: z.ZodISODateTime;
+        appId: z.ZodString;
+        hook: z.ZodObject<{
+            name: z.ZodString;
+            runId: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>], "type">;
+    timeoutMs: z.ZodNumber;
+}, z.core.$strict>;
+export type HookInvokeRequest = z.infer<typeof hookInvokeRequestSchema>;
+/** One effect as the POD reports it — `missing` = a `required` tool the model never called (the dispatcher enforces it). */
+export declare const hookDoorEffectSchema: z.ZodObject<{
+    tool: z.ZodString;
+    status: z.ZodEnum<{
+        called: "called";
+        failed: "failed";
+        missing: "missing";
+    }>;
+}, z.core.$strict>;
+export type HookDoorEffect = z.infer<typeof hookDoorEffectSchema>;
+/**
+ * What the pod answers, synchronously, with a 200. `ok` / `failed` only — the
+ * run's terminal state is the dispatcher's to write (one writer); `deferred`,
+ * `parked` and `skipped` are decided on its side. Other faces are HTTP: 503 +
+ * `Retry-After` at capacity, 422 `UNKNOWN_HOOK` for a name the pod cannot
+ * resolve, 401/403 for a principal that is not this app's hook.
+ *
+ * NOT strict on purpose (the rolling-release rule): the pod may add fields
+ * (`stopReason`, `timedOut`, …) the dispatcher does not read yet; a reader
+ * never refuses a key the other side started sending. The REQUEST stays
+ * strict — nothing on it may widen a hook's reach.
+ */
+export declare const hookInvokeResultSchema: z.ZodObject<{
+    runId: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        ok: "ok";
+    }>;
+    output: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
+    effects: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        status: z.ZodEnum<{
+            called: "called";
+            failed: "failed";
+            missing: "missing";
+        }>;
+    }, z.core.$strict>>>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type HookInvokeResult = z.infer<typeof hookInvokeResultSchema>;
+/**
+ * A prebuilt bound to an event as ONE tool call, no model: the dispatcher
+ * calls `tool` on the FIRST-PARTY hosted server `serverId` (a registry id —
+ * never the app's `mcpServers` map; the gateway still requires the app's
+ * grant) with `args(event)`. `undefined` from `args` = this event carries
+ * nothing for the tool → the run is `skipped`, not failed.
+ */
+export interface PrebuiltToolBinding {
+    readonly kind: 'tool';
+    readonly serverId: string;
+    readonly tool: string;
+    args(event: HookEvent): JsonObject | undefined;
+}
+/** An effect the DISPATCHER makes after a prebuilt agent run answers `ok`: `tool` on `serverId` with the run's `output` as the arguments. */
+export interface PrebuiltEffect {
+    readonly serverId: string;
+    readonly tool: string;
+}
+/**
+ * A prebuilt bound to an event as an agent run. "The model writes, the
+ * platform calls": the definition mounts no tools (`tools: []`) — its structured `output`
+ * (shaped by `definition.output`) is what the dispatcher hands to each
+ * {@link PrebuiltEffect}. So the pod never mounts a first-party server for a
+ * hook run, and the app's `mcpServers` need not declare guuey's own tools.
+ */
+export interface PrebuiltAgentBinding {
+    readonly kind: 'agent';
+    readonly definition: AgentHookDefinition;
+    readonly effects: readonly PrebuiltEffect[];
+}
+/**
+ * A prebuilt deliberately bound to NOTHING on an event, with the reason: the
+ * declaration stays legal in the block, the dispatcher records the run
+ * `skipped` (no claim, no call), the door never sees it. The email reporter
+ * on `handoff.requested` is the first: the platform's notifier already mails
+ * every hand-off whenever the reporter is on (guuey#1525), so a hook there
+ * would mail the owner twice (guuey#1561).
+ */
+export interface PrebuiltSkipBinding {
+    readonly kind: 'skip';
+    readonly reason: PrebuiltSkipReason;
+}
+export type PrebuiltSkipReason = 'notifier-mails-handoffs';
+export type PrebuiltBinding = PrebuiltToolBinding | PrebuiltAgentBinding | PrebuiltSkipBinding;
+export declare function isPrebuiltHookName(name: string): name is PrebuiltHookName;
+/** The report the email reporter's tool takes (`report_conversation`'s input): the shape both prebuilt bindings produce. */
+export declare const conversationReportSchema: z.ZodObject<{
+    summary: z.ZodString;
+    wantedHuman: z.ZodOptional<z.ZodBoolean>;
+    contactEmail: z.ZodOptional<z.ZodString>;
+    contactName: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ConversationReport = z.infer<typeof conversationReportSchema>;
+/** `report_conversation`'s input as a JSON Schema — the reporter's `output` contract for the session-end run. */
+export declare const CONVERSATION_REPORT_JSON_SCHEMA: JsonObject;
+/**
+ * The prebuilt catalog, keyed per event (guuey#1537). A prebuilt with no
+ * binding for an event the app declared it on is `prebuilt-not-served` on
+ * the dispatcher's side and `UNKNOWN_HOOK` at the door — never a guess.
+ *
+ * `email-reporter` (guuey#1511): on `session.ended` nothing has summarised
+ * the conversation yet — a tool-less agent run writes the report as its
+ * structured output and the dispatcher makes the call. On
+ * `handoff.requested` it binds NOTHING, on purpose: the platform's notifier
+ * mails every hand-off (with the rep's summary, guuey#1510) whenever the
+ * reporter is on, no hook needed — a binding there mailed twice
+ * (guuey#1561); the declaration stays legal and is recorded `skipped`.
+ */
+export declare const PREBUILT_DEFINITIONS: Readonly<Record<PrebuiltHookName, Partial<Readonly<Record<HookEventName, PrebuiltBinding>>>>>;
+/** The binding a prebuilt has for an event, if any. */
+export declare function prebuiltBinding(name: PrebuiltHookName, event: HookEventName): PrebuiltBinding | undefined;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -58,6 +58,7 @@ export const jsonValueSchema = z.lazy(() => z.union([
     z.array(jsonValueSchema),
     z.record(z.string(), jsonValueSchema),
 ]));
+export const jsonObjectSchema = z.record(z.string(), jsonValueSchema);
 // ── Tool names ────────────────────────────────────────────────────────
 /** `guuey.json` mcpServers keys: the same grammar `@guuey/config` accepts (non-empty, no dots — the dot separates server from tool). */
 const SERVER_KEY = /^[A-Za-z0-9_-]+$/;
@@ -113,15 +114,21 @@ function hookNameSchemaRef() {
     return hookNameSchema;
 }
 // ── The envelope in (§8.2) ────────────────────────────────────────────
+/**
+ * Id caps: an event id is `<threadId>#<event>#<seq | ISO instant>` and a run
+ * id adds `#<hookName>` — with a 128-char threadId, a 24-char instant and a
+ * 64-char name that is ~231 chars, so 320 leaves room; 128 refused valid ids.
+ */
+const ID_MAX = 320;
 const hookRefSchema = z.strictObject({
     /** The hook the platform is dispatching (a prebuilt name or a `definitions` key). */
     name: z.string().min(1).max(64),
     /** The HookRun id — the idempotency key of this delivery. */
-    runId: z.string().min(1).max(128),
+    runId: z.string().min(1).max(ID_MAX),
 });
 const baseEvent = {
     /** The event id — dedupe on it; deliveries are at-least-once and unordered. */
-    id: z.string().min(1).max(128),
+    id: z.string().min(1).max(ID_MAX),
     at: z.iso.datetime({ offset: true }),
     appId: z.string().min(1).max(128),
     hook: hookRefSchema,
@@ -199,18 +206,33 @@ const agentDefinitionSchema = z
     on: z.array(hookEventNameSchema).min(1),
     /** The hook's system instruction — what to do with the conversation and the event. */
     instruction: z.string().min(1).max(8000),
-    /** Tools the run may call (`server.tool` | `server.*`); absent = the app's declared servers. */
-    tools: z.array(toolPatternSchema).max(64).optional(),
+    /**
+     * Tools the run may call (`server.tool` | `server.*`) — REQUIRED, and
+     * exactly what is declared: `[]` = the run mounts nothing (a summariser
+     * that only writes its `output`). There is no "absent = every declared
+     * server" default: that would hand a hook the colocated children too
+     * (`guuey-handoff`'s `request_human`, `guuey-memory`) without anyone
+     * meaning it (infra's #1529 seam review).
+     */
+    tools: z.array(toolPatternSchema).max(64),
     /** Effects that MUST happen; the Router calls them with the structured output if the model did not. */
     required: z.array(toolNameSchema).max(16).optional(),
     model: z.enum(['small', 'default']).optional(),
     maxTurns: z.number().int().min(1).max(16).optional(),
     timeoutMs: z.number().int().min(1_000).max(300_000).optional(),
+    /**
+     * A JSON Schema the run's structured `output` must satisfy — the Router
+     * hands it to the adapter's structured-output mode (Claude
+     * `outputFormat: json_schema`, OpenAI `output_type`, ADK's parsed text).
+     * Absent = free-form output. What a `required` effect is called with when
+     * the model skipped it, and what a prebuilt's platform-made effect takes.
+     */
+    output: jsonValueSchema.optional(),
     /** v1: the hook principal only. The field exists so the enum can widen without a shape change. */
     actAs: z.literal('hook').optional(),
 })
     .superRefine((d, ctx) => {
-    if (!d.tools || !d.required)
+    if (!d.required)
         return;
     for (const [i, req] of d.required.entries()) {
         if (!d.tools.some((p) => toolPatternCovers(p, req))) {
@@ -294,3 +316,113 @@ export const hooksSectionSchema = z
         }
     }
 });
+// ── The runtime's hook door (§8.4 — the wire between the dispatcher and the pod) ──
+/** Where a live pod answers hook runs: `POST <pod origin>/agent/hook`. */
+export const HOOK_DOOR_PATH = '/agent/hook';
+/**
+ * What the dispatcher POSTs. Minimal by design: the pod resolves the hook's
+ * definition (instruction, tools, required, output, timeout) BY NAME — from
+ * its own snapshot for a dev-defined hook, from {@link PREBUILT_DEFINITIONS}
+ * for a prebuilt — never from the wire, so nothing on the wire can widen a
+ * hook's reach. `timeoutMs` is the dispatcher's wait; the pod caps it by the
+ * definition's own.
+ */
+export const hookInvokeRequestSchema = z.strictObject({
+    runId: z.string().min(1).max(ID_MAX),
+    name: hookNameSchema,
+    event: hookEventSchema,
+    timeoutMs: z.number().int().min(1_000).max(300_000),
+});
+/** One effect as the POD reports it — `missing` = a `required` tool the model never called (the dispatcher enforces it). */
+export const hookDoorEffectSchema = z.strictObject({
+    tool: toolNameSchema,
+    status: z.enum(['called', 'failed', 'missing']),
+});
+/**
+ * What the pod answers, synchronously, with a 200. `ok` / `failed` only — the
+ * run's terminal state is the dispatcher's to write (one writer); `deferred`,
+ * `parked` and `skipped` are decided on its side. Other faces are HTTP: 503 +
+ * `Retry-After` at capacity, 422 `UNKNOWN_HOOK` for a name the pod cannot
+ * resolve, 401/403 for a principal that is not this app's hook.
+ *
+ * NOT strict on purpose (the rolling-release rule): the pod may add fields
+ * (`stopReason`, `timedOut`, …) the dispatcher does not read yet; a reader
+ * never refuses a key the other side started sending. The REQUEST stays
+ * strict — nothing on it may widen a hook's reach.
+ */
+export const hookInvokeResultSchema = z.object({
+    runId: z.string().min(1).max(ID_MAX),
+    status: z.enum(['ok', 'failed']),
+    output: jsonValueSchema.optional(),
+    effects: z.array(hookDoorEffectSchema).default([]),
+    error: z.string().max(2000).optional(),
+});
+export function isPrebuiltHookName(name) {
+    return PREBUILT_HOOKS.includes(name);
+}
+/** The report the email reporter's tool takes (`report_conversation`'s input): the shape both prebuilt bindings produce. */
+export const conversationReportSchema = z.strictObject({
+    summary: z.string().min(1).max(1200),
+    wantedHuman: z.boolean().optional(),
+    contactEmail: z.string().max(320).optional(),
+    contactName: z.string().max(200).optional(),
+});
+/** `report_conversation`'s input as a JSON Schema — the reporter's `output` contract for the session-end run. */
+export const CONVERSATION_REPORT_JSON_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['summary', 'wantedHuman'],
+    properties: {
+        summary: {
+            type: 'string',
+            minLength: 1,
+            maxLength: 1200,
+            description: "Two to four sentences for the app's owner: what the visitor wanted, what was answered, and what is still open.",
+        },
+        wantedHuman: { type: 'boolean', description: 'Whether the visitor asked to talk to a person.' },
+        contactEmail: { type: 'string', maxLength: 320, description: "The visitor's email address for a follow-up, if they shared one." },
+        contactName: { type: 'string', maxLength: 200, description: "The visitor's name, if they shared one." },
+    },
+};
+const EMAIL_REPORTER_SERVER_ID = 'email-reporter';
+const EMAIL_REPORTER_TOOL = 'report_conversation';
+/**
+ * The prebuilt catalog, keyed per event (guuey#1537). A prebuilt with no
+ * binding for an event the app declared it on is `prebuilt-not-served` on
+ * the dispatcher's side and `UNKNOWN_HOOK` at the door — never a guess.
+ *
+ * `email-reporter` (guuey#1511): on `session.ended` nothing has summarised
+ * the conversation yet — a tool-less agent run writes the report as its
+ * structured output and the dispatcher makes the call. On
+ * `handoff.requested` it binds NOTHING, on purpose: the platform's notifier
+ * mails every hand-off (with the rep's summary, guuey#1510) whenever the
+ * reporter is on, no hook needed — a binding there mailed twice
+ * (guuey#1561); the declaration stays legal and is recorded `skipped`.
+ */
+export const PREBUILT_DEFINITIONS = {
+    'email-reporter': {
+        'handoff.requested': { kind: 'skip', reason: 'notifier-mails-handoffs' },
+        'session.ended': {
+            kind: 'agent',
+            definition: {
+                kind: 'agent',
+                on: ['session.ended'],
+                instruction: "The conversation has ended. Write the app owner's report of it as the structured output: `summary` — two to four " +
+                    'sentences on what the visitor wanted, what was answered, and what is still open, written from the whole ' +
+                    'conversation; `wantedHuman` — whether the visitor asked to talk to a person; `contactEmail` and `contactName` ' +
+                    'only if the visitor shared them. Report facts from the transcript; never invent contact details.',
+                // Mounts NOTHING: the report is the structured output; the dispatcher makes the one call below.
+                tools: [],
+                output: CONVERSATION_REPORT_JSON_SCHEMA,
+                model: 'small',
+                maxTurns: 2,
+                timeoutMs: 90_000,
+            },
+            effects: [{ serverId: EMAIL_REPORTER_SERVER_ID, tool: EMAIL_REPORTER_TOOL }],
+        },
+    },
+};
+/** The binding a prebuilt has for an event, if any. */
+export function prebuiltBinding(name, event) {
+    return PREBUILT_DEFINITIONS[name][event];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/hooks",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "The guuey hook spec — lifecycle events a hosted agent's platform fires (session.ended, handoff.requested), the JSON envelope in / result out, the two handler kinds (agent | tool), and the hooks block of guuey.json. Types + zod schemas + the per-event class table; no runtime of its own.",
   "license": "MIT",
   "type": "module",