aimeat 1.34.0 → 1.35.0

package/dist/src/cli/connect/onboarding-prompt.js

@@ -7,6 +7,9 @@
  *   them here -- not in the consumers.
  * @version-history
  *   v1.0.0 -- 2026-05-28 -- Initial extraction from auth.ts/skill-bundle.ts duplication.
+ *   v1.1.0 -- 2026-06-30 -- Add anti-fabrication rule (only five aimeat_onboarding_* tools exist;
+ *                            drive other steps via each step's howTo.tool from aimeat_onboarding_status;
+ *                            stop at summary.completable).
  */
 /** Canonical Hello Integration MCP tool sequence, in execution order. */
 export const HELLO_INTEGRATION_TOOL_SEQUENCE = [
@@ -34,9 +37,13 @@ export const HELLO_INTEGRATION_TOOL_SEQUENCE = [
 export function buildAgentOnboardingInstruction() {
     return `You are connected to AIMEAT through MCP in this runtime.
 
-Use the available AIMEAT tools now. Hello Integration is AIMEAT's required first-run onboarding handshake for every newly connected agent. The names below are MCP tools shown by your AI runtime; do not type them as terminal commands. Complete Hello Integration in this order:
+Use the available AIMEAT tools now. Hello Integration is AIMEAT's required first-run onboarding handshake for every newly connected agent. The names below are MCP tools shown by your AI runtime; do not type them as terminal commands.
+
+There are ONLY five aimeat_onboarding_* tools: aimeat_onboarding_status, aimeat_onboarding_identify_platform, aimeat_onboarding_confirm_skill_installed, aimeat_onboarding_confirm_directives_read, aimeat_onboarding_declare_services. There is NO aimeat_onboarding_<stepId> tool for any other step -- never construct one. aimeat_onboarding_status returns a step_guide (and a howTo on each step): for any pending step, call the tool named in its howTo.tool with howTo.args. Skip steps whose howTo.tool is null -- the server passes those automatically once you are active. Stop as soon as summary.completable is true (all required steps passed); the optional offers-ladder steps never block completion.
+
+Complete Hello Integration in this order:
 1. Call aimeat_handbook_get and read the operating handbook.
-2. Call aimeat_onboarding_status and follow its next-step hints.
+2. Call aimeat_onboarding_status and follow its step_guide / per-step howTo and next-step hints.
 3. Call aimeat_onboarding_identify_platform with your runtime/platform name.
 4. Call aimeat_onboarding_confirm_skill_installed after confirming the local skill bundle is available.
 5. Call aimeat_agent_capabilities_report with your useful capabilities.
@@ -46,7 +53,7 @@ Use the available AIMEAT tools now. Hello Integration is AIMEAT's required first
 9. Call aimeat_task_list and find the task named "Onboarding verification".
 10. Call aimeat_task_propose_todos with a short TODO plan for that task.
 11. Call aimeat_onboarding_status again. If the test task is active, use aimeat_task_event, aimeat_task_todo, and aimeat_task_complete to finish it.
-12. Call aimeat_onboarding_status one final time and report any remaining pending step.
+12. Call aimeat_onboarding_status one final time. When summary.completable is true you are done; otherwise complete summary.next_required_step via its howTo.tool and re-check.
 13. After Hello Integration is complete, publish post-onboarding setup from SKILL.md:
   - Register your actual owner-facing slash commands at the memory key agents.{your-agent-name}.commands. Use a flat array of { name, description, category }. Include only commands you can really handle from AIMEAT Messages; do not copy examples or list internal MCP tools as message commands.
   - Publish actual runtime/config artifacts under agents.config.*. If this runtime only uses aimeat connect serve, describe that connector accurately; do not invent a watchdog file.

package/dist/src/cli/connect/onboarding-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"onboarding-prompt.js","sourceRoot":"","sources":["../../../../src/cli/connect/onboarding-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,yEAAyE;AACzE,MAAM,CAAC,MAAM,+BAA+B,GAA0B;IACpE,qBAAqB;IACrB,0BAA0B;IAC1B,qCAAqC;IACrC,2CAA2C;IAC3C,kCAAkC;IAClC,2CAA2C;IAC3C,qBAAqB;IACrB,+BAA+B;IAC/B,kBAAkB;IAClB,2BAA2B;IAC3B,0BAA0B;IAC1B,mBAAmB;IACnB,kBAAkB;IAClB,sBAAsB;IACtB,0BAA0B;CAC3B,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,+BAA+B;IAC7C,OAAO;;;;;;;;;;;;;;;;;;;;;+FAqBsF,CAAC;AAChG,CAAC"}
+{"version":3,"file":"onboarding-prompt.js","sourceRoot":"","sources":["../../../../src/cli/connect/onboarding-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,yEAAyE;AACzE,MAAM,CAAC,MAAM,+BAA+B,GAA0B;IACpE,qBAAqB;IACrB,0BAA0B;IAC1B,qCAAqC;IACrC,2CAA2C;IAC3C,kCAAkC;IAClC,2CAA2C;IAC3C,qBAAqB;IACrB,+BAA+B;IAC/B,kBAAkB;IAClB,2BAA2B;IAC3B,0BAA0B;IAC1B,mBAAmB;IACnB,kBAAkB;IAClB,sBAAsB;IACtB,0BAA0B;CAC3B,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,+BAA+B;IAC7C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;+FAyBsF,CAAC;AAChG,CAAC"}

package/dist/src/generated/api-types.d.ts

@@ -994,6 +994,86 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/secretary/brief": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Propose grounded Work Briefs for the active context's structural gaps
+         * @description The light-vs-heavy seam. The cheap node-local Secretary no longer authors content one-shot (that hallucinated). It detects STRUCTURAL gaps (empty/thin workspaces, stale content, off-target KPIs) and assembles a grounded Work Brief — Current picture + real Discovery sources + exact record schemas + the appdev MCP playbook — that a Builder (a connected big AI via the MCP tools) executes. Deterministic (no paid AI call), idempotent (deduped against open briefs by gap), additive (never touches content). Optional `ws` scopes to one workspace. Owner-only.
+         */
+        post: operations["secretaryBrief"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/secretary/briefs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List the open Work Briefs (proposed/dispatched) for the brief tray
+         * @description Owner-scoped private memory; includes the full brief markdown + MCP hints so the view renders without a second fetch. Owner-only.
+         */
+        get: operations["secretaryBriefsList"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/secretary/brief/{id}/dispatch": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Dispatch a Work Brief to a connected Builder (queue a task it runs via MCP)
+         * @description Queues the brief as an agent task a connected Builder picks up and runs via the appdev MCP tools (lane b). The target must be one of THIS owner's connected agents and not the Secretary or a node-local specialist. Marks the brief 'dispatched'. Owner-only.
+         */
+        post: operations["secretaryBriefDispatch"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/secretary/brief/{id}/done": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Resolve a Work Brief (handled or no longer relevant)
+         * @description Marks the brief 'done' so it leaves the tray and the tick won't re-propose the same gap. Owner-only.
+         */
+        post: operations["secretaryBriefDone"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/agents/device-authorize": {
         parameters: {
             query?: never;
@@ -13936,7 +14016,15 @@ export interface components {
             id?: string;
             order?: number;
             title?: string;
+            /** @description Raw i18n key (agentOnboarding.stepDescriptions.{id}); see descriptionText for the resolved string. */
             description?: string;
+            /**
+             * @description Localised, human-readable resolution of `description`. Present on the GET /onboarding
+             *     and aimeat_onboarding_status payloads (REST resolves via Accept-Language; MCP uses the
+             *     node default locale). Added so connector/agent consumers without the i18n bundle never
+             *     see a raw key.
+             */
+            descriptionText?: string;
             /** @enum {string} */
             status?: "pending" | "passed" | "failed" | "skipped";
             required?: boolean;
@@ -13945,6 +14033,58 @@ export interface components {
             /** @enum {string} */
             validationMethod?: "automatic" | "api_call" | "owner_confirm";
             failureReason?: string;
+            /** @description Machine-readable how-to-complete descriptor (null when the step id has no mapping). */
+            howTo?: components["schemas"]["OnboardingStepHowTo"] | null;
+        };
+        /**
+         * @description Authoritative machine-readable "how to complete this step" descriptor. A connector drives
+         *     each pending step from this (call `tool` with `args`) instead of fabricating a non-existent
+         *     `aimeat_onboarding_<stepId>` tool. The only onboarding-prefixed tools that exist are the five
+         *     aimeat_onboarding_* tools; every other step is completed by calling its mapped real tool.
+         */
+        OnboardingStepHowTo: {
+            /**
+             * @description Who performs the action -- the agent calls a tool, or the server validates passively.
+             * @enum {string}
+             */
+            actor?: "agent" | "server";
+            /** @description true when the server auto-ticks the step by reading real state (no dedicated confirm call). */
+            automatic?: boolean;
+            /** @description Mirrors `required` -- true when this step gates onboarding completion. */
+            gatesCompletion?: boolean;
+            /** @enum {string} */
+            validationMethod?: "automatic" | "api_call" | "owner_confirm";
+            /** @description Exact MCP tool to call, or null for passive/server steps. */
+            tool?: string | null;
+            /** @description Optional local-connector convenience tool with the same effect (e.g. aimeat_offers_publish). */
+            toolAlias?: string;
+            /** @description Underlying REST route for non-MCP clients; null for passive steps. */
+            restEndpoint?: {
+                /** @enum {string} */
+                method?: "GET" | "POST" | "PUT" | "PATCH";
+                path?: string;
+            } | null;
+            /** @description Copyable argument template. `{name}` is substituted server-side; `{test_task_id}` is filled from hints.test_task_id. */
+            args?: {
+                [key: string]: unknown;
+            };
+            /** @description For tool === null steps, the condition under which the server auto-passes the step. */
+            passiveNote?: string;
+        };
+        /** @description Reachability summary. Completion gates only on required steps; optional steps never block. */
+        OnboardingSummary: {
+            required_total?: number;
+            required_passed?: number;
+            required_remaining?: number;
+            optional_total?: number;
+            optional_passed?: number;
+            optional_remaining?: number;
+            /** @description true once every required step has passed -- the agent can stop here. */
+            completable?: boolean;
+            /** @description First not-yet-passed required step id, or null when none remain. */
+            next_required_step?: string | null;
+            /** @description Ids of pending optional steps (never block completion). */
+            optional_pending?: string[];
         };
         /** @description An opt-in budget/run guard on a schedule. type 'max_runs' or 'daily_limit' in v1. */
         ScheduleConstraint: {
@@ -16060,6 +16200,164 @@ export interface operations {
             };
         };
     };
+    secretaryBrief: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description Optional workspace id to scope the brief to. */
+                    ws?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Work briefs proposed (0 when no new gaps) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AimeatEnvelope"] & {
+                        data?: {
+                            proposed?: number;
+                            workspaces?: number;
+                            briefs?: {
+                                id?: string;
+                                objective?: string;
+                                ws?: string;
+                                wsName?: string;
+                                gaps?: number;
+                                /** @example proposed */
+                                status?: string;
+                            }[];
+                        };
+                    };
+                };
+            };
+            /** @description No active Secretary context with an organism to brief (NO_CONTEXT) */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: components["responses"]["Unauthorized"];
+        };
+    };
+    secretaryBriefsList: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Open Work Briefs, newest first */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AimeatEnvelope"] & {
+                        data?: {
+                            briefs?: Record<string, never>[];
+                        };
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+        };
+    };
+    secretaryBriefDispatch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description The Builder agent GAII (or name) to dispatch to. */
+                    targetAgent: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Brief dispatched; task queued */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AimeatEnvelope"] & {
+                        data?: {
+                            dispatched?: boolean;
+                            taskId?: string;
+                            to?: string;
+                        };
+                    };
+                };
+            };
+            /** @description Missing targetAgent, or the target is not a valid Builder (INVALID_TARGET) */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: components["responses"]["Unauthorized"];
+            /** @description Work brief not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    secretaryBriefDone: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Brief resolved */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AimeatEnvelope"] & {
+                        data?: {
+                            done?: boolean;
+                        };
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            /** @description Work brief not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     deviceAuthorize: {
         parameters: {
             query?: never;
@@ -33532,10 +33830,19 @@ export interface operations {
                     "application/json": components["schemas"]["AimeatEnvelope"] & {
                         data?: {
                             onboarding: components["schemas"]["AgentOnboardingRecord"];
+                            /**
+                             * @description Flow-scoped map of stepId -> OnboardingStepHowTo for the steps in this
+                             *     agent's onboarding flow. The authoritative how-to-complete contract a
+                             *     connector drives from (call howTo.tool with howTo.args per pending step).
+                             */
+                            step_guide?: {
+                                [key: string]: components["schemas"]["OnboardingStepHowTo"];
+                            };
+                            summary?: components["schemas"]["OnboardingSummary"];
                             /**
                              * @description Next-step guidance for the agent. May include
-                             *     `next_step` (step id), `message` (human-readable),
-                             *     `test_task_id`, `test_task_active`.
+                             *     `next_step` (step id; now prefers the next required step),
+                             *     `message` (human-readable), `test_task_id`, `test_task_active`.
                              */
                             hints?: {
                                 [key: string]: unknown;