@mulmoclaude/core 0.2.0 → 0.2.5

package/assets/helps/collection-skills.md

@@ -49,7 +49,7 @@ data/<name>/items/             ← the records (separate from the skill dir)
   discovery enforces and reports the exact problem, where a hand-edit can
   silently fail validation and make the collection vanish from the UI. It writes
   the canonical `data/skills/<slug>/schema.json` and mirrors it for you — same
-  destination as authoring, just validated. (Creating a *new* collection still
+  destination as authoring, just validated. (Creating a _new_ collection still
   means writing `SKILL.md` + `schema.json` under `data/skills/<slug>/`, since
   there's nothing to `getSchema` yet.)
 - **Do NOT use the `mc-` prefix** for skills you create. `mc-*` is reserved for
@@ -127,7 +127,7 @@ skipped, never crashes the host):
 | `title`                | Human name shown in the sidebar / header. Required.                                                                                                                                                                                                                                                                                                                                                                           |
 | `icon`                 | A **Material Symbols** name (`receipt_long`, `people`, `schedule`, `menu_book`). Required.                                                                                                                                                                                                                                                                                                                                    |
 | `dataPath`             | Workspace-relative records folder, e.g. `data/recipes/items`. Must stay under the workspace. Required.                                                                                                                                                                                                                                                                                                                        |
-| `primaryKey`           | The field name whose value is the filename. That field MUST set `primary: true`. The value must be a valid record id (see the **Records** section's id-charset rule). Required.                                                                                                                                                                                                                                                |
+| `primaryKey`           | The field name whose value is the filename. That field MUST set `primary: true`. The value must be a valid record id (see the **Records** section's id-charset rule). Required.                                                                                                                                                                                                                                               |
 | `singleton`            | Optional. When set, at most one record exists, pinned to this exact id (e.g. `me`). Host pre-fills + locks the create form and hides Add once it exists.                                                                                                                                                                                                                                                                      |
 | `fields`               | Ordered map of field-name → field spec. **Insertion order = column order** in the table. Required.                                                                                                                                                                                                                                                                                                                            |
 | `actions`              | Optional array of per-record buttons (see below).                                                                                                                                                                                                                                                                                                                                                                             |
@@ -492,7 +492,7 @@ month's rent `paid`, and next month's pending record appears on its own.
   - **Field-driven interval** (one list, mixed cadences): instead of a single
     `{ unit, interval }`, `every` may select the interval **per record** from
     an `enum` field. Use `{ "fromField": "<enum field>", "map": { <value>:
-    { unit, interval, … } } }` — the host reads the record's value and
+{ unit, interval, … } } }` — the host reads the record's value and
     advances by the matching entry. This lets one collection carry daily,
     weekly, and monthly obligations together:
 
@@ -513,6 +513,7 @@ month's rent `paid`, and next month's pending record appears on its own.
     by `set`) so the successor keeps its frequency and the chain keeps
     recurring. Each `map` value is a literal `every` (same `unit` / `interval`
     / `dayOfMonth` rules as above).
+
 - **`carry`** — record fields copied verbatim onto the successor (must name
   real fields). Fields not in `carry` / `set` / the trigger+primary keys start
   blank.
@@ -538,6 +539,53 @@ This covers _periodic_ obligations. It does **not** do escalating, multi-stage
 reminders over a long prep window (info → warning → urgent) — that is
 intentionally out of scope for collections.
 
+### Scheduled agent refresh (`ingest.kind: "agent"`)
+
+When a collection's records need to be **refreshed on a schedule by judgment**
+— fetch today's stock quotes for every ticker, re-check each watched URL, pull
+fresh figures that a static feed URL can't express — add an `ingest` block with
+`kind: "agent"`. On schedule (and on the **Refresh** button, which appears on
+any collection with an `ingest` block), the host launches a **hidden background
+worker** in `role`, seeded with your `template` plus the same compact
+all-records summary a collection-level action gets. The worker edits the records
+itself via its collection tools, then finishes silently — nothing shows in the
+chat list. Host stays generic: all the domain logic lives in the template prose.
+
+```json
+"ingest": {
+  "kind": "agent",
+  "schedule": "daily",
+  "atHour": 22,
+  "role": "investor",
+  "template": "templates/refresh.md"
+}
+```
+
+- **`schedule`**: `hourly` | `daily` | `weekly` | `on-demand`. `on-demand` never
+  auto-runs (Refresh button only). Cadence is elapsed-based ("≥24 h since the
+  last run, checked hourly") unless you anchor it (below).
+- **`atHour`** (optional, `daily` only): the hour (0–23) to run around. The host
+  ticks hourly, so the run lands within that hour.
+  **⚠ `atHour` is UTC — NOT the user's local time.** A bare `"atHour": 9` fires
+  at 09:00 UTC (= 18:00 JST, = 04:00 ET), which is almost never what "9am" means
+  to the user. So when the user says a local time, **always convert to UTC
+  first**: 07:00 JST → `"atHour": 22`; 9am ET ≈ `"atHour": 13`; 9am PT ≈
+  `"atHour": 17`. (UTC is used for an unambiguous, DST-free comparison, matching
+  the rest of the scheduler.)
+- **`role`**: the role the worker runs in — it must own the tools the refresh
+  needs (e.g. `investor` for the Yahoo Finance endpoints).
+- **`template`**: a path-safe `templates/…md` file (same rule as action
+  templates) whose prose tells the worker exactly what to do. End it with "edit
+  the records and stop — do not present anything" (no one is watching its
+  canvas).
+- No `url`/`map` — the agent owns retrieval and record shape; its writes are
+  still schema-validated. A failed run raises a single bell ("Collection refresh
+  failed: `<slug>`") that clears on the next success.
+
+Reach for `ingest.kind: "agent"` (not a `manageAutomations` task) whenever the
+schedule belongs to one collection: it travels with the schema, dies with the
+collection, and needs no separate setup.
+
 ### Calendar view
 
 Any collection that has at least one `date` (or `datetime`) field gains a
@@ -713,7 +761,7 @@ single source of truth and the "done" checkbox is a `toggle` field projecting it
   separators, **no** leading/trailing dot, and **no** `..` substring. If your
   natural key contains anything else (a space, `/`, `:`, a leading dot), sanitise
   it first — e.g. replace each illegal run with `_`. Note `manageCollection`
-  enforces this on every targeted read/write, so an id that only *looks* fine in
+  enforces this on every targeted read/write, so an id that only _looks_ fine in
   a full `getItems` listing but violates the rule can't be updated or deleted by
   id — fix the id, don't work around it with raw file I/O.
 - **The file MUST be valid JSON.** A malformed record is **silently skipped** at

package/assets/helps/custom-view.md

@@ -69,19 +69,36 @@ window.__MC_VIEW = {
 
 ### Reading records
 
+> **Always project `fields`.** The host refuses any read of more than 200
+> records that does not pass `?fields=…` or `?ids=…`, because an unscoped
+> fetch wastes work and bandwidth on columns your view never reads. Once a
+> user's collection grows past the threshold an unprojected view starts
+> returning `400` instead of records — write the projection from day one so
+> the same view keeps working forever.
+
 ```js
 const { token, dataUrl } = window.__MC_VIEW;
-const res = await fetch(dataUrl, { headers: { Authorization: "Bearer " + token } });
-if (!res.ok) throw new Error("load failed: " + res.status);
+// List the columns this view actually reads — never send `dataUrl` raw.
+const url = dataUrl + "?fields=" + encodeURIComponent("title,start,end,status");
+const res = await fetch(url, { headers: { Authorization: "Bearer " + token } });
+if (!res.ok) {
+  // Surface the server's reason (the 400 carries `{ error: "<message>" }`),
+  // not just the status code — that text is what tells the user / Claude
+  // how to fix the call (e.g. "pass `fields` to project only the columns").
+  const detail = await res.text();
+  throw new Error("load failed (" + res.status + "): " + detail);
+}
 const { items } = await res.json(); // { collection, count, items: [...] }
 ```
 
 Records come back **with computed fields already resolved** (derived formulas,
 toggles, embeds) — the same numbers the user sees elsewhere.
 
-- Narrow large reads: `dataUrl + "?fields=title,start,end"` or `?ids=a,b,c`
-  (comma-separated). A read of **more than 200 records** without `ids`/`fields`
-  is refused — always project `fields` for big collections.
+- **`?fields=a,b,c`** — only these columns per record (the primary key is always
+  included). Use this on every read; it is mandatory above 200 records.
+- **`?ids=x,y,z`** — only these specific record ids. Use it when the view edits
+  / shows one record at a time. Combinable with `fields`.
+- The primary key is always returned regardless of `fields`.
 
 ### Writing records (only with the `write` capability)
 
@@ -111,9 +128,11 @@ By default a view paints once, on load. To keep it fresh, register a callback
 it runs whenever the collection's data changes on the server:
 
 ```js
+// Same projection rule as the initial read — list the columns this view uses.
+const url = dataUrl + "?fields=" + encodeURIComponent("title,start,end,status");
 async function render() {
-  const res = await fetch(dataUrl, { headers: { Authorization: "Bearer " + token } });
-  if (!res.ok) return; // handle the error per your UI
+  const res = await fetch(url, { headers: { Authorization: "Bearer " + token } });
+  if (!res.ok) return; // surface the body if you want a richer error UI
   const { items } = await res.json();
   // …draw items…
 }
@@ -303,8 +322,9 @@ fields `start` / `end` and a `title`. `capabilities: ["read"]`.
       const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
       async function main() {
         const { token, dataUrl } = window.__MC_VIEW;
-        const res = await fetch(dataUrl, { headers: { Authorization: "Bearer " + token } });
-        if (!res.ok) throw new Error("HTTP " + res.status);
+        const url = dataUrl + "?fields=" + encodeURIComponent("title,start");
+        const res = await fetch(url, { headers: { Authorization: "Bearer " + token } });
+        if (!res.ok) throw new Error("HTTP " + res.status + ": " + (await res.text()));
         const { items } = await res.json();
         const buckets = MONTHS.map(() => []);
         for (const it of items) {
@@ -382,10 +402,11 @@ writes it back. `capabilities: ["read","write"]`.
       const DAYS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
       const { token, dataUrl } = window.__MC_VIEW;
       const auth = { Authorization: "Bearer " + token, "Content-Type": "application/json" };
+      const readUrl = dataUrl + "?fields=" + encodeURIComponent("title,start");
 
       async function read() {
-        const res = await fetch(dataUrl, { headers: { Authorization: "Bearer " + token } });
-        if (!res.ok) throw new Error("HTTP " + res.status);
+        const res = await fetch(readUrl, { headers: { Authorization: "Bearer " + token } });
+        if (!res.ok) throw new Error("HTTP " + res.status + ": " + (await res.text()));
         return (await res.json()).items;
       }
       async function bump(item) {

package/assets/helps/feeds.md

@@ -16,8 +16,8 @@ engine does that automatically: the first time the feed's view is opened, on an
 hourly schedule thereafter, and when the user clicks **Refresh feed**. Records
 render in the standard collection view at `/feeds/<slug>`.
 
-This is the project philosophy: *the workspace is the database; you are the
-intelligent interface.* Adding a feed = **fetch the URL, look at its real
+This is the project philosophy: _the workspace is the database; you are the
+intelligent interface._ Adding a feed = **fetch the URL, look at its real
 fields, and write one `schema.json`.**
 
 ## Workflow to add a feed
@@ -45,11 +45,11 @@ lists all registered feeds, and its delete button does the same.
   "primaryKey": "id",
   "displayField": "headline",
   "fields": {
-    "id":        { "type": "string",   "label": "ID", "primary": true },
-    "headline":  { "type": "string",   "label": "Headline" },
-    "url":       { "type": "string",   "label": "URL" },
-    "published": { "type": "date",     "label": "Published" },
-    "summary":   { "type": "markdown", "label": "Summary" }
+    "id": { "type": "string", "label": "ID", "primary": true },
+    "headline": { "type": "string", "label": "Headline" },
+    "url": { "type": "string", "label": "URL" },
+    "published": { "type": "date", "label": "Published" },
+    "summary": { "type": "markdown", "label": "Summary" }
   },
   "ingest": {
     "kind": "rss",
@@ -87,6 +87,10 @@ lists all registered feeds, and its delete button does the same.
 - `url`: the feed / API endpoint (must be public http/https; the host refuses
   private/loopback addresses).
 - `schedule`: `hourly` | `daily` | `weekly` | `on-demand`.
+- `atHour` (optional, `daily` only): the hour (0–23) to anchor a daily feed to
+  (the host ticks hourly, so the run lands within that hour). **⚠ UTC, NOT local
+  time** — `"atHour": 9` is 09:00 UTC (= 18:00 JST). Always convert the user's
+  local time to UTC before writing.
 - `map`: `{ <yourFieldName>: <sourcePath> }` — a dot/bracket path into each
   fetched item. **Map the fields you actually saw when you inspected the feed.**
   - rss/atom: each item is the parsed XML element. Tags are keys (`title`,
@@ -106,6 +110,11 @@ lists all registered feeds, and its delete button does the same.
 - http-json needs an array of objects. Columnar/parallel-array APIs (e.g.
   Open-Meteo weather: `hourly.time[]` + `hourly.temperature_2m[]`) are not
   supported yet.
+- When a refresh needs **judgment** the declarative `map` can't express — auth
+  headers, per-record requests, picking which symbols to fetch, computing a
+  value — use `ingest.kind: "agent"` instead (a scheduled hidden worker; see
+  `config/helps/collection-skills.md` → "Scheduled agent refresh"). It works on
+  any collection, not just feeds.
 - A malformed `schema.json` is skipped at load time (with a diagnostic on the
   notification bell), so double-check the shape above before writing.
 - A feed can carry **custom views** just like any collection — author the HTML at

package/assets/skills-preset/mc-manage-automations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mc-manage-automations
-description: Schedule, list, edit, or remove a recurring agent task (cron / interval). Use when the user wants the agent to run a prompt on a schedule ("毎朝7時に天気", "every weekday 8am check email", "schedule a weekly cleanup"), list active automations, or stop one. Edits `config/scheduler/tasks.json` (cwd-relative — the agent already runs with cwd = workspace); the auto-refresh hook re-registers tasks on save.
+description: Schedule, list, edit, or remove a recurring agent task (cron / interval) in `config/scheduler/tasks.json`. Use for cross-collection digests, notifications, or any standalone recurring prompt ("毎朝7時に天気", "every weekday 8am check email", "schedule a weekly cleanup"), or to list/stop automations. EXCEPTION — do NOT create a task here to keep ONE collection's records fresh (e.g. "update the stock-quotes daily", "refresh these quotes every morning", "re-poll these URLs"): instead add an `ingest` block with `kind: "agent"` to THAT collection's own `schema.json` (it self-refreshes on schedule and from its Refresh button; syntax in `config/helps/collection-skills.md` → "Scheduled agent refresh"). Read this skill body in full before writing `tasks.json` — the entry format is structured, not free-form.
 ---
 
 # Automations manager
@@ -18,6 +18,40 @@ take effect immediately.
 End with a one-line confirmation ("Scheduled weather-morning, daily 07:00
 UTC." / "Stopped weekly-cleanup.") so the user can verify without scrolling.
 
+## First: is this just refreshing ONE collection?
+
+Before writing a `tasks.json` automation, check what the recurring work
+actually is. If it's **"keep one collection's records up to date"** — refresh
+stock quotes, re-poll a set of watched URLs, pull fresh figures for every row —
+do **NOT** create an automation here. Add an `ingest` block to _that
+collection's own_ `schema.json` instead:
+
+```json
+"ingest": {
+  "kind": "agent",
+  "schedule": "daily",
+  "atHour": 21,
+  "role": "<a role that owns the tools the refresh needs>",
+  "template": "templates/refresh.md"
+}
+```
+
+and write `templates/refresh.md` telling the worker how to refresh the records.
+The full contract is in `config/helps/collection-skills.md` → "Scheduled agent
+refresh". On schedule (and on the collection's **Refresh** button) the host runs
+a hidden background worker that edits the records.
+
+Prefer this over a `tasks.json` automation whenever the work is one collection's
+refresh: the schedule lives **with** the collection — it travels when the skill
+is copied and is deleted when the collection is, instead of leaving an orphan
+task here whose prompt points at records that may no longer exist. (Editing
+`data/stock-quotes/items/*.json` daily? That's `ingest.kind: "agent"` on the
+stock-quotes schema, not an automation.)
+
+Use the `tasks.json` automation below only for work that **isn't** one
+collection's refresh: cross-collection digests, notifications, or an arbitrary
+recurring prompt.
+
 ## Workflow 1: schedule a new automation
 
 **Triggers**: "毎朝 7 時に天気を", "every weekday 8am check email",
@@ -26,7 +60,7 @@ UTC." / "Stopped weekly-cleanup.") so the user can verify without scrolling.
 **Step 1 — convert local time to UTC.** Schedules are stored / compared in
 UTC (the task-manager calls `Date.getUTCHours/Minutes`). When the user gives
 a local time, convert before writing. E.g. "07:00 JST" → `"16:00"` of the
-*previous* UTC day? No — `07:00 JST` is `22:00 UTC` of the *previous* day.
+_previous_ UTC day? No — `07:00 JST` is `22:00 UTC` of the _previous_ day.
 JST is UTC+9, so `07:00 JST = 22:00 UTC (yesterday)`. (Run the math, don't
 trust your reflex — UTC offsets are a classic typo source.)
 

package/dist/collection/core/schema.d.ts

@@ -7,15 +7,39 @@
  *  these three + the presence check. */
 export interface CollectionIngest {
     kind: string;
-    url: string;
     schedule: string;
+    /** Optional time-of-day anchor for `schedule: "daily"` — the hour (0–23) to
+     *  refresh around (the host ticks hourly, so the run lands within that hour).
+     *  Ignored for non-daily schedules. Absent ⇒ elapsed-based daily ("≥24 h since
+     *  the last run"). NOTE: **UTC**, not local — compared via `getUTCHours()` for
+     *  an unambiguous, DST-free check (matching the rest of the scheduler), so
+     *  convert local times before writing (e.g. 07:00 JST → `atHour: 22`). */
+    atHour?: number;
+    /** Declarative retrievers (`rss`/`atom`/`http-json`) only — the host fetches
+     *  this URL on the schedule. Absent for `kind: "agent"`, where the agent owns
+     *  retrieval. */
+    url?: string;
+    /** `kind: "agent"` only: role id the scheduled hidden worker runs in. */
+    role?: string;
+    /** `kind: "agent"` only: skill-relative template path (under `templates/`)
+     *  whose prose tells the worker how to refresh the records. */
+    template?: string;
 }
-/** Retriever kinds a Feed's `ingest.kind` may declare. The host's feeds engine
- *  dispatches on these; they live here (with the schema contract) so the schema
- *  validator can enforce them. The host re-exports these from
+/** Declarative retriever kinds a Feed's `ingest.kind` may declare. The host's
+ *  feeds engine dispatches on these; they live here (with the schema contract)
+ *  so the schema validator can enforce them. The host re-exports these from
  *  `server/workspace/feeds/ingestTypes.ts`. */
 export declare const INGEST_KINDS: readonly ["rss", "atom", "http-json"];
 export type IngestKind = (typeof INGEST_KINDS)[number];
+/** The agent-performed ingest kind. Instead of a declarative fetch, the host
+ *  dispatches a hidden background chat (origin `system`) in `ingest.role`,
+ *  seeded with `ingest.template` + a summary of every record, on the
+ *  `ingest.schedule` cadence; the worker edits records via the collections io
+ *  layer. Kept separate from {@link INGEST_KINDS} (which the declarative
+ *  retriever registry keys on) so the schema validator can model `ingest` as a
+ *  discriminated union without the feeds engine gaining an "agent" retriever. */
+export declare const AGENT_INGEST_KIND: "agent";
+export type AgentIngestKind = typeof AGENT_INGEST_KIND;
 /** Refresh cadences a Feed's `ingest.schedule` may declare. */
 export declare const FEED_SCHEDULES: readonly ["hourly", "daily", "weekly", "on-demand"];
 export type FeedSchedule = (typeof FEED_SCHEDULES)[number];
@@ -335,12 +359,15 @@ export interface CollectionSchema {
      *  notify for every open record (the prior behaviour). `notifyWhen.field`
      *  must name a real top-level field. */
     notifyWhen?: CollectionWhen;
-    /** Optional declarative retrieval config. When present, this collection
-     *  is a "Feed": the host periodically fetches `ingest.url`, maps the
-     *  response into records, and upserts them by `primaryKey`. Only feeds
-     *  discovered from the `<workspace>/feeds/` registry carry this; skill
-     *  collections omit it. The host's feeds subsystem narrows this to its
-     *  richer `IngestSpec` (which `extends CollectionIngest`). */
+    /** Optional scheduled-retrieval config. When present, the host refreshes
+     *  this collection on `ingest.schedule`. Two flavours: a declarative Feed
+     *  (`kind: rss/atom/http-json`) periodically fetches `ingest.url`, maps the
+     *  response into records, and upserts them by `primaryKey` — only feeds
+     *  discovered from the `<workspace>/feeds/` registry carry this. Or
+     *  `kind: "agent"`, valid on any (incl. skill-backed) collection: the host
+     *  dispatches a hidden background worker in `ingest.role` seeded with
+     *  `ingest.template`, and the worker edits the records itself. The host's
+     *  feeds subsystem narrows this to its richer `IngestSpec`. */
     ingest?: CollectionIngest;
 }
 export interface CollectionSummary {

package/dist/collection/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_deriveAll = require("../deriveAll-C15OpM3K.cjs");
+const require_deriveAll = require("../deriveAll-VRWrs3SF.cjs");
 //#region src/collection/core/presentCollection.ts
 var TOOL_NAME = "presentCollection";
 var TOOL_DEFINITION = {
@@ -328,7 +328,7 @@ function firstMissingRequiredField(draft, schema) {
 //#region src/collection/core/sortItems.ts
 var EMPTY = { empty: true };
 /** Field types that render no value text in the table, so offer no sort. */
-var NON_SORTABLE = new Set([
+var NON_SORTABLE = /* @__PURE__ */ new Set([
 	"markdown",
 	"table",
 	"image",
@@ -410,7 +410,7 @@ function sortItems(items, direction, valueOf) {
 }
 //#endregion
 //#region src/collection/core/itemLabel.ts
-var LABEL_FIELD_TYPES = new Set([
+var LABEL_FIELD_TYPES = /* @__PURE__ */ new Set([
 	"string",
 	"text",
 	"markdown",
@@ -736,6 +736,7 @@ function defangForPrompt(value) {
 	return value.replace(/[<>]/g, "").replace(/`/g, "'").replace(/\$\{/g, "$ {").replace(/\s+/g, " ").slice(0, DEFANG_MAX_LEN);
 }
 //#endregion
+exports.AGENT_INGEST_KIND = require_deriveAll.AGENT_INGEST_KIND;
 exports.ENUM_ALERT = ENUM_ALERT;
 exports.ENUM_NEUTRAL = ENUM_NEUTRAL;
 exports.ENUM_NUDGE = ENUM_NUDGE;