mulmoclaude 0.6.2 → 0.6.4

package/src/plugins/encore/defineEncoreDefinition.ts

@@ -0,0 +1,74 @@
+// MCP ToolDefinition for `defineEncore` — the structural tool that
+// composes or modifies an Encore DSL document.
+//
+// Discriminator: `obligationId` presence.
+//   - absent → setup (server generates `id` from `displayName`,
+//     rejects with 409 if the slug collides with an existing
+//     obligation — see `requireUniqueObligationId` in dispatch.ts)
+//   - present → amend the named obligation (shallow-merge top-level)
+//
+// The choice to use parameter PRESENCE as the discriminator (instead
+// of a `kind: "setup" | "amendDefinition"` enum) gives the LLM a
+// natural mental model: "I have an id" / "I don't". The setup vs
+// amend intent IS the parameter shape, no redundant flag.
+//
+// The `dsl` JSON Schema is AUTO-DERIVED from the runtime Zod
+// validator (`z.toJSONSchema(EncoreDslInput)`) — so the LLM sees
+// the same field names, types, and oneOf branches the server
+// enforces, with zero drift risk. The schema lives at
+// `src/types/encore-dsl/` (was `server/encore/dsl/`) so plugin
+// code can import it without crossing the no-server-imports lint
+// boundary.
+
+import { z } from "zod";
+import type { ToolDefinition } from "gui-chat-protocol";
+import { EncoreDslInput } from "../../types/encore-dsl/schema";
+import { META } from "./defineEncoreMeta";
+
+export const TOOL_NAME = META.toolName;
+
+// Strip `$schema` — that's a top-level JSON Schema declaration, not
+// valid as a property subschema. The rest (`oneOf` / `type` /
+// `properties` / ...) is what we want inside `parameters.dsl`.
+const generatedDslSchema = z.toJSONSchema(EncoreDslInput) as Record<string, unknown>;
+const { $schema: __ignored, ...dslJsonSchema } = generatedDslSchema;
+
+const toolDefinition: ToolDefinition = {
+  type: "function",
+  name: TOOL_NAME,
+  prompt:
+    "Use defineEncore to compose a NEW Encore obligation (no `obligationId` argument) or AMEND an existing one (pass its `obligationId`). " +
+    "The `dsl` argument is an OBJECT LITERAL — never a JSON-encoded string. " +
+    "Setup: provide the complete DSL document (version / displayName / type / cadence / targets / steps / formSchema). " +
+    "Amend: provide ONLY the top-level fields you want to change — the server shallow-merges onto the existing DSL. " +
+    "Read `config/helps/encore-dsl.md` for the full grammar, severity rules, and worked examples.",
+  description:
+    "Compose a new Encore obligation, or amend an existing one (pass obligationId). Operational actions (markStepDone, snooze, query, …) live on the sibling manageEncore tool.",
+  parameters: {
+    type: "object",
+    properties: {
+      kind: {
+        type: "string",
+        enum: [TOOL_NAME],
+        description: "Fixed value; the tool's only kind.",
+      },
+      dsl: {
+        ...dslJsonSchema,
+        description:
+          "Encore DSL document (OBJECT LITERAL — do NOT pass a JSON-encoded string). " +
+          "For setup (no obligationId): provide every required field shown in the schema. " +
+          "For amend (with obligationId): provide ONLY the top-level fields you want to change — others are preserved from the existing DSL. " +
+          "See `config/helps/encore-dsl.md` for cross-field rules and worked examples.",
+      },
+      obligationId: {
+        type: "string",
+        description:
+          "Present → amend the named obligation. Absent → setup a new one (server generates the id from displayName). If you intend to amend but forget this, the server rejects with 409 and tells you the id to pass.",
+      },
+    },
+    required: ["kind", "dsl"],
+    additionalProperties: false,
+  },
+};
+
+export default toolDefinition;

package/src/plugins/encore/defineEncoreMeta.ts

@@ -0,0 +1,13 @@
+// Encore plugin — second META (toolName-only sibling to manageEncoreMeta).
+//
+// Same pattern as `scheduler/automationsMeta.ts`: two tools share one
+// apiNamespace, so only ONE meta declares apiNamespace/apiRoutes/
+// workspaceDirs/mcpDispatch (the full one lives in `manageEncoreMeta.ts`).
+// This file exists purely so the host aggregator's `TOOL_NAMES`
+// records the second tool name; everything else is shared.
+
+import { definePluginMeta } from "../meta-types";
+
+export const META = definePluginMeta({
+  toolName: "defineEncore",
+});

package/src/plugins/encore/index.ts

@@ -0,0 +1,93 @@
+// Encore plugin registration — two MCP tools sharing one apiNamespace
+// (same pattern as scheduler/{calendar,automations}):
+//
+//   - `defineEncore` — structural; composes or amends a DSL document.
+//   - `manageEncore` — operational; records progress, queries, etc.
+//
+// Both POST to the same `/api/encore` dispatch endpoint. The server's
+// dispatch.ts routes by the `kind` field in the body (`defineEncore`
+// for the structural tool, `markStepDone` / `snooze` / `query` / ...
+// for the operational one).
+//
+// Vue surface:
+//   - One View at `/encore` (chat-on-mount for bell clicks). Shared
+//     between both tools — the page only handles `resolveNotification`
+//     and that's tool-independent.
+//
+// See plans/feat-encore-as-builtin.md for the original build plan,
+// plans/feat-encore-plugin.md for the DSL spec, and
+// plans/feat-encore-define-tool.md for why the tool was split.
+
+import type { ToolResult } from "gui-chat-protocol";
+import type { PluginEntry, PluginRegistration, ToolPlugin } from "../../tools/types";
+import { pluginEndpoints } from "../api";
+import { wrapWithScope } from "../scope";
+import { apiCall } from "../../utils/api";
+import { makeUuid } from "../../utils/id";
+import View from "./View.vue";
+import manageEncoreDefinition, { TOOL_NAME as MANAGE_ENCORE, type EncoreEndpoints } from "./manageEncoreDefinition";
+import defineEncoreDefinition, { TOOL_NAME as DEFINE_ENCORE } from "./defineEncoreDefinition";
+import { META as MANAGE_META } from "./manageEncoreMeta";
+
+export interface EncoreData {
+  kind?: string;
+  ok?: boolean;
+  message?: string;
+  [key: string]: unknown;
+}
+
+/** Generate an `execute` function bound to a specific toolName so
+ *  the result envelope carries the matching name through to chat
+ *  history and View lookup. Both tools POST to the same dispatch
+ *  endpoint (resolved from `MANAGE_META.apiNamespace`, which both
+ *  tools share). */
+function makeExecute(toolName: typeof MANAGE_ENCORE | typeof DEFINE_ENCORE): ToolPlugin<EncoreData>["execute"] {
+  return async function execute(_context, args) {
+    const endpoints = pluginEndpoints<EncoreEndpoints>(MANAGE_META.apiNamespace);
+    const { method, url } = endpoints.dispatch;
+    const result = await apiCall<ToolResult<EncoreData>>(url, { method, body: args });
+    if (!result.ok) {
+      return {
+        toolName,
+        uuid: makeUuid(),
+        message: result.error,
+      };
+    }
+    return {
+      ...result.data,
+      toolName,
+      uuid: result.data.uuid ?? makeUuid(),
+    };
+  };
+}
+
+export const manageEncorePlugin: ToolPlugin<EncoreData> = {
+  toolDefinition: manageEncoreDefinition,
+  execute: makeExecute(MANAGE_ENCORE),
+  isEnabled: () => true,
+  generatingMessage: "Updating Encore...",
+  viewComponent: wrapWithScope("encore", View),
+};
+
+export const defineEncorePlugin: ToolPlugin<EncoreData> = {
+  toolDefinition: defineEncoreDefinition,
+  execute: makeExecute(DEFINE_ENCORE),
+  isEnabled: () => true,
+  generatingMessage: "Composing Encore obligation...",
+  // Reuse the same View — `defineEncore` doesn't produce its own
+  // bell entries (it produces the obligation; the tick produces the
+  // bells), so there's nothing tool-specific to render. The shared
+  // View handles the chat-on-mount flow for any Encore bell.
+  viewComponent: wrapWithScope("encore", View),
+};
+
+const manageEntry: PluginEntry = manageEncorePlugin as unknown as PluginEntry;
+const defineEntry: PluginEntry = defineEncorePlugin as unknown as PluginEntry;
+
+// One plugin module, two tool registrations — scheduler pattern.
+export const REGISTRATIONS: PluginRegistration[] = [
+  { toolName: MANAGE_ENCORE, entry: manageEntry },
+  { toolName: DEFINE_ENCORE, entry: defineEntry },
+];
+
+export default manageEncorePlugin;

package/src/plugins/encore/manageEncoreDefinition.ts

@@ -0,0 +1,100 @@
+// MCP ToolDefinition for `manageEncore` (operational kinds only).
+//
+// Structural kinds (setup / amendDefinition) moved to the sibling
+// `defineEncoreDefinition.ts`. The server-side dispatcher still
+// accepts them on the wire for backward compat (the new
+// `handleDefineEncore` translates to them internally), but the
+// LLM-facing enum here is narrower so the LLM picks `defineEncore`
+// for DSL composition and `manageEncore` for everything that
+// happens after the obligation exists.
+//
+// Schema details live in the help file (`config/helps/encore-dsl.md`)
+// which the host syncs into the workspace at every startup — keeping
+// this `description` short and letting Claude lazy-read the help file
+// for full grammar is the teaching strategy (see
+// plans/feat-encore-plugin.md "Teaching the DSL to Claude").
+
+import type { ToolDefinition } from "gui-chat-protocol";
+import type { ResolvedRoute } from "../meta-types";
+import { META } from "./manageEncoreMeta";
+
+// Derive TOOL_NAME from META so the schema, MCP-bridge dispatch,
+// and Vue executor can't drift apart. The host aggregators
+// (TOOL_NAMES, API_ROUTES, WORKSPACE_PATHS) read META; everything
+// downstream reads from here.
+export const TOOL_NAME = META.toolName;
+
+/** Resolved-route shape Encore exposes to the browser via
+ *  `pluginEndpoints("encore")`. Derived from META so adding a new
+ *  apiRoutes key flows into the type without manual edits. Shared
+ *  between manageEncore and defineEncore — both POST to the same
+ *  dispatch endpoint. */
+export type EncoreEndpoints = { readonly [K in keyof typeof META.apiRoutes]: ResolvedRoute };
+
+/** Action kinds the LLM is allowed to invoke via the `manageEncore`
+ *  MCP tool. Operational only — structural (setup / amendDefinition)
+ *  lives on the `defineEncore` tool. `resolveNotification` is
+ *  deliberately excluded because it's a browser-only action
+ *  dispatched by the /encore page on mount (calls `startChat`
+ *  server-side; calling it from inside an existing chat would spawn
+ *  a duplicate chat).
+ *
+ *  When adding a new action kind, decide whether it's structural
+ *  (writes/edits a DSL document → add to defineEncore) or
+ *  operational (acts on existing obligation state → add here). */
+export const LLM_ENCORE_KINDS = ["markStepDone", "markTargetSkipped", "recordValues", "query", "appendNote", "snooze", "unsnooze"] as const;
+
+/** Every action kind the server-side dispatch handles, including
+ *  browser-only ones and the structural kinds the server keeps for
+ *  backward compat. NOT the enum exposed to Claude — used by the
+ *  dispatch.ts switch and by tests. */
+export const ALL_ENCORE_KINDS = [...LLM_ENCORE_KINDS, "resolveNotification", "setup", "amendDefinition", "defineEncore"] as const;
+
+const toolDefinition: ToolDefinition = {
+  type: "function",
+  name: TOOL_NAME,
+  prompt:
+    "Once an Encore obligation exists, use manageEncore to record what happened (markStepDone / markTargetSkipped / recordValues / appendNote), to defer reminders (snooze / unsnooze), or to query (query). " +
+    "For composing a NEW obligation or amending an existing one's DSL, use the sibling defineEncore tool. " +
+    "Read `config/helps/encore-dsl.md` before calling — it documents every action's call shape and bell-clearing semantics.",
+  description: "Record progress on existing Encore obligations — close steps, skip targets, snooze, query.",
+  parameters: {
+    type: "object",
+    properties: {
+      kind: {
+        type: "string",
+        enum: [...LLM_ENCORE_KINDS],
+        description: "Which Encore action to perform.",
+      },
+      // Per-field type hints stay sparse — the handler validates the
+      // rest of the args per-kind with Zod (see
+      // server/encore/dispatch.ts), and a strict JSON-schema validator
+      // can't express cross-field rules anyway. We declare ONLY the
+      // fields where the LLM most often produces a structurally wrong
+      // shape (and the resulting Zod error reads as a "schema problem"
+      // that the LLM tends to loop on rather than self-correct).
+      //
+      // `values` (markStepDone / recordValues): the LLM commonly
+      // JSON.stringify's it or wraps a single field-map in an array
+      // (`"[{\"laps\": 0}]"`). Declaring `type: "object"` gives the LLM
+      // a strong "this is an object literal" hint at compose time.
+      values: {
+        type: "object",
+        description:
+          'Flat field-map keyed by field name — e.g. `{"amount": 5000, "paidOn": "2026-05-16"}`. ' +
+          "Do NOT pass a JSON-encoded string. Do NOT wrap in an array. Do NOT nest by targetId. " +
+          "One call per target; the `values` are for that single target.",
+        additionalProperties: true,
+      },
+    },
+    required: ["kind"],
+    // The remaining args (`obligationId` / `cycleId` / `targetId` /
+    // `stepId` / `pendingId` / `body` / `range`) are short strings
+    // or scalars the LLM gets right most of the time; documenting
+    // them in the help file is cheaper than a JSON-schema constraint
+    // that doesn't know which fields apply per kind.
+    additionalProperties: true,
+  },
+};
+
+export default toolDefinition;

package/src/plugins/encore/manageEncoreMeta.ts

@@ -0,0 +1,36 @@
+// Encore plugin META — the central-registry-facing metadata.
+// Imported by host aggregators (`src/config/*` and
+// `server/workspace/paths.ts`) which iterate over every plugin's META
+// and merge automatically. Host code holds zero plugin-specific
+// literals.
+//
+// Browser-safe: no Vue / no Node-only imports.
+//
+// See plans/feat-encore-as-builtin.md for the architecture and
+// plans/feat-encore-plugin.md for the DSL spec the handlers
+// implement.
+
+import { definePluginMeta } from "../meta-types";
+
+export const META = definePluginMeta({
+  toolName: "manageEncore",
+  apiNamespace: "encore",
+  apiRoutes: {
+    /** POST /api/encore — single dispatch with `kind` discriminator
+     *  (setup / amendDefinition / markStepDone / markTargetSkipped /
+     *  recordValues / query / appendNote / snooze / resolveNotification).
+     *  Both the MCP bridge and the chat-on-mount page (`View.vue`,
+     *  which dispatches `resolveNotification` on mount to start
+     *  the chat server-side) POST here; the server splits by
+     *  `kind`. */
+    dispatch: { method: "POST", path: "" },
+  },
+  mcpDispatch: "dispatch",
+  // `data/plugins/encore/` is the plain-name layout chosen for the
+  // built-in (vs. the URL-encoded `%40mulmoclaude%2Fencore-plugin`
+  // path the prior runtime-preset attempt used). See
+  // plans/feat-encore-as-builtin.md "What's intentionally different".
+  workspaceDirs: {
+    encore: "data/plugins/encore",
+  },
+});