@geminixiang/mikan 1.0.0-beta.4 → 1.0.0-beta.41

package/dist/harness/event-format.js

@@ -0,0 +1,160 @@
+import { Type } from "@sinclair/typebox";
+import { parseJsonSchemaValue } from "../utils/file-guards.js";
+/**
+ * Single home for the scheduled-event file format (`events/*.json`, the
+ * workspace scheduling bus). Every reader and writer — the EventsWatcher
+ * scheduler, the agent `event` tool, and the extension schedule API — must go
+ * through this module: one schema, one payload union, one parser, one
+ * builder. Per-type field rules (`at` for one-shot, `schedule` + `timezone`
+ * for periodic) live here and nowhere else.
+ */
+/** Typebox union for the `type` field, shared by the file schema and the event tool's parameters. */
+export const EventTypeSchema = Type.Union([
+    Type.Literal("immediate"),
+    Type.Literal("one-shot"),
+    Type.Literal("periodic"),
+]);
+/**
+ * Lenient file-reading schema: every field optional so shape problems surface
+ * as the specific missing-field messages below rather than typebox noise.
+ * `channelId` is the legacy alias for `conversationId`.
+ */
+const EventFileSchema = Type.Object({
+    type: Type.Optional(EventTypeSchema),
+    platform: Type.Optional(Type.String()),
+    conversationId: Type.Optional(Type.String()),
+    channelId: Type.Optional(Type.String()),
+    conversationKind: Type.Optional(Type.Union([Type.Literal("direct"), Type.Literal("shared")])),
+    userId: Type.Optional(Type.String()),
+    text: Type.Optional(Type.String()),
+    at: Type.Optional(Type.String()),
+    schedule: Type.Optional(Type.String()),
+    timezone: Type.Optional(Type.String()),
+});
+const ISO_TIMESTAMP_WITH_OFFSET = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?(Z|[+-](\d{2}):(\d{2}))$/;
+function daysInMonth(year, month) {
+    if (month === 2) {
+        const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+        return leapYear ? 29 : 28;
+    }
+    return month === 4 || month === 6 || month === 9 || month === 11 ? 30 : 31;
+}
+/** True for a complete ISO 8601 timestamp that carries an explicit UTC offset. */
+export function isValidIsoTimestampWithOffset(value) {
+    const match = ISO_TIMESTAMP_WITH_OFFSET.exec(value);
+    if (!match)
+        return false;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = match[6] === undefined ? 0 : Number(match[6]);
+    const offsetHour = match[8] === undefined ? 0 : Number(match[8]);
+    const offsetMinute = match[9] === undefined ? 0 : Number(match[9]);
+    return (month >= 1 &&
+        month <= 12 &&
+        day >= 1 &&
+        day <= daysInMonth(year, month) &&
+        hour >= 0 &&
+        hour <= 23 &&
+        minute >= 0 &&
+        minute <= 59 &&
+        second >= 0 &&
+        second <= 59 &&
+        offsetHour >= 0 &&
+        offsetHour <= 23 &&
+        offsetMinute >= 0 &&
+        offsetMinute <= 59 &&
+        Number.isFinite(Date.parse(value)));
+}
+/**
+ * Resolve an event file's conversation id, honoring the legacy `channelId`
+ * alias. Alias knowledge is private to the format module: consumers always
+ * see `conversationId` on parsed payloads.
+ */
+function resolveEventConversationId(data) {
+    if (typeof data.conversationId === "string")
+        return data.conversationId;
+    if (typeof data.channelId === "string")
+        return data.channelId;
+    return undefined;
+}
+/**
+ * Parse and validate one event file's content into the canonical payload.
+ * `filename` appears in error messages. Throws on malformed JSON, wrong
+ * field types, and missing required fields (common and per-type).
+ */
+export function parseEventPayload(content, filename) {
+    const data = parseJsonSchemaValue(content, EventFileSchema, (detail) => detail === "unexpected JSON shape"
+        ? `Expected top-level JSON object in ${filename}`
+        : `Malformed event file ${filename}: ${detail}`);
+    const conversationId = resolveEventConversationId(data);
+    const { type, text } = data;
+    if (!type || !conversationId || !text) {
+        throw new Error(`Missing required fields (type, conversationId, text) in ${filename}`);
+    }
+    const base = {
+        ...(data.platform !== undefined ? { platform: data.platform } : {}),
+        conversationId,
+        ...(data.conversationKind !== undefined ? { conversationKind: data.conversationKind } : {}),
+        ...(data.userId !== undefined ? { userId: data.userId } : {}),
+        text,
+    };
+    switch (type) {
+        case "immediate":
+            return { type, ...base };
+        case "one-shot":
+            if (typeof data.at !== "string" || data.at.length === 0) {
+                throw new Error(`Missing 'at' field for one-shot event in ${filename}`);
+            }
+            if (!isValidIsoTimestampWithOffset(data.at)) {
+                throw new Error(`Invalid 'at' field for one-shot event in ${filename}: expected a valid ISO 8601 timestamp with UTC offset`);
+            }
+            return { type, ...base, at: data.at };
+        case "periodic":
+            if (typeof data.schedule !== "string" || data.schedule.length === 0) {
+                throw new Error(`Missing 'schedule' field for periodic event in ${filename}`);
+            }
+            if (typeof data.timezone !== "string" || data.timezone.length === 0) {
+                throw new Error(`Missing 'timezone' field for periodic event in ${filename}`);
+            }
+            return { type, ...base, schedule: data.schedule, timezone: data.timezone };
+    }
+}
+/**
+ * Validate and assemble a new event payload for writing. Owns the per-type
+ * field rules; write-side *policy* beyond the format (e.g. the event tool's
+ * requirement that `at` lies in the future) stays with the writer.
+ */
+export function buildEventPayload(input) {
+    const base = {
+        ...(input.platform !== undefined ? { platform: input.platform } : {}),
+        conversationId: input.conversationId,
+        ...(input.conversationKind !== undefined ? { conversationKind: input.conversationKind } : {}),
+        ...(input.userId !== undefined ? { userId: input.userId } : {}),
+        text: input.text,
+    };
+    switch (input.type) {
+        case "immediate":
+            return { type: "immediate", ...base };
+        case "one-shot": {
+            if (!input.at) {
+                throw new Error("`at` is required for one-shot events");
+            }
+            if (!isValidIsoTimestampWithOffset(input.at)) {
+                throw new Error("`at` must be a valid ISO 8601 timestamp with UTC offset");
+            }
+            return { type: "one-shot", ...base, at: input.at };
+        }
+        case "periodic":
+            if (!input.schedule) {
+                throw new Error("`schedule` is required for periodic events");
+            }
+            if (!input.timezone) {
+                throw new Error("`timezone` is required for periodic events");
+            }
+            return { type: "periodic", ...base, schedule: input.schedule, timezone: input.timezone };
+    }
+}
+//# sourceMappingURL=event-format.js.map

package/dist/harness/event-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-format.js","sourceRoot":"","sources":["../../src/harness/event-format.ts"],"names":[],"mappings":"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","sourcesContent":["import { Type, type Static } from \"@sinclair/typebox\";\nimport { parseJsonSchemaValue } from \"../utils/file-guards.js\";\nimport type { EventFilePayload, EventPayloadInput } from \"./types.js\";\n\nexport type {\n  EventConversationKind,\n  EventFilePayload,\n  EventPayloadInput,\n  EventType,\n  ImmediateEventPayload,\n  OneShotEventPayload,\n  PeriodicEventPayload,\n} from \"./types.js\";\n\n/**\n * Single home for the scheduled-event file format (`events/*.json`, the\n * workspace scheduling bus). Every reader and writer — the EventsWatcher\n * scheduler, the agent `event` tool, and the extension schedule API — must go\n * through this module: one schema, one payload union, one parser, one\n * builder. Per-type field rules (`at` for one-shot, `schedule` + `timezone`\n * for periodic) live here and nowhere else.\n */\n\n/** Typebox union for the `type` field, shared by the file schema and the event tool's parameters. */\nexport const EventTypeSchema = Type.Union([\n  Type.Literal(\"immediate\"),\n  Type.Literal(\"one-shot\"),\n  Type.Literal(\"periodic\"),\n]);\n\n/**\n * Lenient file-reading schema: every field optional so shape problems surface\n * as the specific missing-field messages below rather than typebox noise.\n * `channelId` is the legacy alias for `conversationId`.\n */\nconst EventFileSchema = Type.Object({\n  type: Type.Optional(EventTypeSchema),\n  platform: Type.Optional(Type.String()),\n  conversationId: Type.Optional(Type.String()),\n  channelId: Type.Optional(Type.String()),\n  conversationKind: Type.Optional(Type.Union([Type.Literal(\"direct\"), Type.Literal(\"shared\")])),\n  userId: Type.Optional(Type.String()),\n  text: Type.Optional(Type.String()),\n  at: Type.Optional(Type.String()),\n  schedule: Type.Optional(Type.String()),\n  timezone: Type.Optional(Type.String()),\n});\n\ntype EventFileData = Static<typeof EventFileSchema>;\n\nconst ISO_TIMESTAMP_WITH_OFFSET =\n  /^(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2})(?::(\\d{2})(?:\\.\\d+)?)?(Z|[+-](\\d{2}):(\\d{2}))$/;\n\nfunction daysInMonth(year: number, month: number): number {\n  if (month === 2) {\n    const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);\n    return leapYear ? 29 : 28;\n  }\n  return month === 4 || month === 6 || month === 9 || month === 11 ? 30 : 31;\n}\n\n/** True for a complete ISO 8601 timestamp that carries an explicit UTC offset. */\nexport function isValidIsoTimestampWithOffset(value: string): boolean {\n  const match = ISO_TIMESTAMP_WITH_OFFSET.exec(value);\n  if (!match) return false;\n\n  const year = Number(match[1]);\n  const month = Number(match[2]);\n  const day = Number(match[3]);\n  const hour = Number(match[4]);\n  const minute = Number(match[5]);\n  const second = match[6] === undefined ? 0 : Number(match[6]);\n  const offsetHour = match[8] === undefined ? 0 : Number(match[8]);\n  const offsetMinute = match[9] === undefined ? 0 : Number(match[9]);\n\n  return (\n    month >= 1 &&\n    month <= 12 &&\n    day >= 1 &&\n    day <= daysInMonth(year, month) &&\n    hour >= 0 &&\n    hour <= 23 &&\n    minute >= 0 &&\n    minute <= 59 &&\n    second >= 0 &&\n    second <= 59 &&\n    offsetHour >= 0 &&\n    offsetHour <= 23 &&\n    offsetMinute >= 0 &&\n    offsetMinute <= 59 &&\n    Number.isFinite(Date.parse(value))\n  );\n}\n\n/**\n * Resolve an event file's conversation id, honoring the legacy `channelId`\n * alias. Alias knowledge is private to the format module: consumers always\n * see `conversationId` on parsed payloads.\n */\nfunction resolveEventConversationId(data: {\n  conversationId?: unknown;\n  channelId?: unknown;\n}): string | undefined {\n  if (typeof data.conversationId === \"string\") return data.conversationId;\n  if (typeof data.channelId === \"string\") return data.channelId;\n  return undefined;\n}\n\n/**\n * Parse and validate one event file's content into the canonical payload.\n * `filename` appears in error messages. Throws on malformed JSON, wrong\n * field types, and missing required fields (common and per-type).\n */\nexport function parseEventPayload(content: string, filename: string): EventFilePayload {\n  const data: EventFileData = parseJsonSchemaValue(content, EventFileSchema, (detail) =>\n    detail === \"unexpected JSON shape\"\n      ? `Expected top-level JSON object in ${filename}`\n      : `Malformed event file ${filename}: ${detail}`,\n  );\n  const conversationId = resolveEventConversationId(data);\n  const { type, text } = data;\n\n  if (!type || !conversationId || !text) {\n    throw new Error(`Missing required fields (type, conversationId, text) in ${filename}`);\n  }\n\n  const base = {\n    ...(data.platform !== undefined ? { platform: data.platform } : {}),\n    conversationId,\n    ...(data.conversationKind !== undefined ? { conversationKind: data.conversationKind } : {}),\n    ...(data.userId !== undefined ? { userId: data.userId } : {}),\n    text,\n  };\n\n  switch (type) {\n    case \"immediate\":\n      return { type, ...base };\n\n    case \"one-shot\":\n      if (typeof data.at !== \"string\" || data.at.length === 0) {\n        throw new Error(`Missing 'at' field for one-shot event in ${filename}`);\n      }\n      if (!isValidIsoTimestampWithOffset(data.at)) {\n        throw new Error(\n          `Invalid 'at' field for one-shot event in ${filename}: expected a valid ISO 8601 timestamp with UTC offset`,\n        );\n      }\n      return { type, ...base, at: data.at };\n\n    case \"periodic\":\n      if (typeof data.schedule !== \"string\" || data.schedule.length === 0) {\n        throw new Error(`Missing 'schedule' field for periodic event in ${filename}`);\n      }\n      if (typeof data.timezone !== \"string\" || data.timezone.length === 0) {\n        throw new Error(`Missing 'timezone' field for periodic event in ${filename}`);\n      }\n      return { type, ...base, schedule: data.schedule, timezone: data.timezone };\n  }\n}\n\n/**\n * Validate and assemble a new event payload for writing. Owns the per-type\n * field rules; write-side *policy* beyond the format (e.g. the event tool's\n * requirement that `at` lies in the future) stays with the writer.\n */\nexport function buildEventPayload(input: EventPayloadInput): EventFilePayload {\n  const base = {\n    ...(input.platform !== undefined ? { platform: input.platform } : {}),\n    conversationId: input.conversationId,\n    ...(input.conversationKind !== undefined ? { conversationKind: input.conversationKind } : {}),\n    ...(input.userId !== undefined ? { userId: input.userId } : {}),\n    text: input.text,\n  };\n\n  switch (input.type) {\n    case \"immediate\":\n      return { type: \"immediate\", ...base };\n\n    case \"one-shot\": {\n      if (!input.at) {\n        throw new Error(\"`at` is required for one-shot events\");\n      }\n      if (!isValidIsoTimestampWithOffset(input.at)) {\n        throw new Error(\"`at` must be a valid ISO 8601 timestamp with UTC offset\");\n      }\n      return { type: \"one-shot\", ...base, at: input.at };\n    }\n\n    case \"periodic\":\n      if (!input.schedule) {\n        throw new Error(\"`schedule` is required for periodic events\");\n      }\n      if (!input.timezone) {\n        throw new Error(\"`timezone` is required for periodic events\");\n      }\n      return { type: \"periodic\", ...base, schedule: input.schedule, timezone: input.timezone };\n  }\n}\n"]}

package/dist/harness/extensions/loader.d.ts

@@ -1,62 +1,40 @@
-import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Api, Model } from "@earendil-works/pi-ai";
-import { type MikanSkill } from "../skills.js";
-import { ExtensionRegistry } from "./registry.js";
-import type { ExtensionHostServices, ExtensionLoadError, LoadedExtension } from "./types.js";
+import type { OfficeAddress } from "../../types.js";
+import type { ExtensionValidation, InstalledExtensionInfo, LoadExtensionsOptions, LoadExtensionsResult } from "./types.js";
+export type { ExtensionValidation, InstalledExtensionInfo, LoadExtensionsOptions, LoadExtensionsResult, } from "./types.js";
 /**
- * Canonical host-only extension directories for a conversation:
- * `<stateDir>/extensions/global` (all conversations) and
- * `<stateDir>/extensions/<conversationId>` (that conversation only).
- * `global` is reserved as a scope name; platform conversation ids never
- * take that value.
+ * Canonical host-only extension code directories for a conversation, in load
+ * order: `<stateDir>/global/extensions` (all conversations) then
+ * `<stateDir>/conversations/<office key>/extensions` (that conversation
+ * only). `global` and `conversations` are the two sibling scopes; see
+ * `LAYOUT.md`.
  */
-export declare function defaultExtensionDirs(conversationId: string, stateDir?: string): string[];
-/** Discovery-only view of an installed extension (module is not imported). */
-export interface InstalledExtensionInfo {
-    /** Display name: manifest name, falling back to the slug. */
-    name: string;
-    slug: string;
-    path: string;
-    /** Scan directory the extension was found in. */
-    dir: string;
-    version?: string;
-    description?: string;
-    /** Names of skills shipped in the extension's skills/ directory. */
-    skillNames: string[];
-}
+export declare function defaultExtensionDirs(address: OfficeAddress, stateDir?: string): string[];
 /**
  * List installed extensions without importing or activating them — safe for
  * inventory surfaces (commands, portal). Activation side effects (schedule
  * upserts, tool registration) only happen in {@link loadExtensions}.
  */
 export declare function listInstalledExtensions(dirs: string[]): InstalledExtensionInfo[];
-export interface LoadExtensionsOptions {
-    /** Directories to scan for extensions. Missing directories are skipped. */
-    dirs: string[];
-    context: {
-        conversationId: string;
-        workspaceDir: string;
-        model: Model<Api>;
-        thinkingLevel: ThinkingLevel;
-    };
-    /** Embedder-provided services backing the v2 api surface. */
-    services?: ExtensionHostServices;
-}
-export interface LoadExtensionsResult {
-    registry: ExtensionRegistry;
-    extensions: LoadedExtension[];
-    errors: ExtensionLoadError[];
-    /** Skills contributed by extensions (inline: bodies ride in the prompt). */
-    skills: MikanSkill[];
-}
 /**
- * Filesystem-safe identifier for an extension, derived from its install
- * location (directory name for `<name>/index.mjs`, file basename otherwise).
- * The slug keys the extension's data dir, secrets vault, and schedule
- * ownership — installing the same extension globally and per-conversation
- * shares one slug and therefore one data dir.
+ * Filesystem-safe identifier for an extension, derived from its root (the
+ * install directory, or the file path for a bare-file extension). The slug
+ * keys the extension's data dir, secrets vault, and schedule ownership —
+ * installing the same extension globally and per-conversation shares one
+ * slug and therefore one shared data dir. This is the only slug derivation:
+ * a second one keyed off a different input (e.g. the entrypoint, which for
+ * package.json-form extensions can live under dist/) would silently split an
+ * extension's identity.
  */
-export declare function extensionSlug(entrypoint: string): string;
+export declare function extensionSlug(rootDir: string): string;
 /** Load and activate all extensions found in the given directories. */
 export declare function loadExtensions(options: LoadExtensionsOptions): Promise<LoadExtensionsResult>;
+/**
+ * Validate an extension source path (a directory or a single file) WITHOUT
+ * activating it: resolves the entrypoint (package.json `mikan.extensions`,
+ * index file, or the file itself), imports it, and checks it exports an
+ * `activate` function. Used by `mikan ext install` as a preflight and by
+ * `mikan ext validate`. Importing runs top-level module code but not
+ * `activate`, so there are no schedule/tool side effects.
+ */
+export declare function validateExtension(sourcePath: string): Promise<ExtensionValidation>;
 //# sourceMappingURL=loader.d.ts.map

package/dist/harness/extensions/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/harness/extensions/loader.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAa,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAKlB,eAAe,EAIhB,MAAM,YAAY,CAAC;AAIpB;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,MAAM,EACtB,QAAQ,GAAE,MAAkC,GAC3C,MAAM,EAAE,CAEV;AAED,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,sBAAsB,EAAE,CAkBhF;AAED,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE;QACP,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAClB,aAAa,EAAE,aAAa,CAAC;KAC9B,CAAC;IACF,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,4EAA4E;IAC5E,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AA0CD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAUxD;AAkMD,uEAAuE;AACvE,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAmD/B"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/harness/extensions/loader.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAWV,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EAKrB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAiBpB;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,EACtB,QAAQ,GAAE,MAAkC,GAC3C,MAAM,EAAE,CAKV;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,sBAAsB,EAAE,CAmBhF;AAkJD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIrD;AA4WD,uEAAuE;AACvE,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAoE/B;AA2DD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAuDxF"}