macroclaw 0.34.0 → 0.35.0

package/src/settings.ts

@@ -1,18 +1,20 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { IANAZone } from "luxon";
 import { z } from "zod/v4";
 import { createLogger } from "./logger";
 
 const log = createLogger("settings");
 
 export const settingsSchema = z.object({
-  botToken: z.string(),
-  chatId: z.string().regex(/^-?\d+$/, "Must be a numeric Telegram chat ID"),
-  model: z.enum(["haiku", "sonnet", "opus"]).default("sonnet"),
-  workspace: z.string().default("~/.macroclaw-workspace"),
-  openaiApiKey: z.string().optional(),
-  logLevel: z.enum(["debug", "info", "warn", "error"]).default("info"),
-  pinoramaUrl: z.string().optional(),
+  botToken: z.string().trim(),
+  chatId: z.string().trim().regex(/^-?\d+$/, "Must be a numeric Telegram chat ID"),
+  model: z.string().trim().pipe(z.enum(["haiku", "sonnet", "opus"])).default("sonnet"),
+  workspace: z.string().trim().default("~/.macroclaw-workspace"),
+  timezone: z.string().trim().refine((tz) => IANAZone.isValidZone(tz), "Must be a valid IANA timezone").default("UTC"),
+  openaiApiKey: z.string().trim().optional(),
+  logLevel: z.string().trim().pipe(z.enum(["debug", "info", "warn", "error"])).default("info"),
+  pinoramaUrl: z.string().trim().optional(),
 });
 
 export type Settings = z.infer<typeof settingsSchema>;
@@ -35,6 +37,7 @@ export class SettingsManager {
     chatId: "AUTHORIZED_CHAT_ID",
     model: "MODEL",
     workspace: "WORKSPACE",
+    timezone: "TIMEZONE",
     openaiApiKey: "OPENAI_API_KEY",
     logLevel: "LOG_LEVEL",
     pinoramaUrl: "PINORAMA_URL",
@@ -88,18 +91,24 @@ export class SettingsManager {
   }
 
   applyEnvOverrides(settings: Settings): { settings: Settings; overrides: Set<string> } {
-    const merged = { ...settings };
+    const merged: Record<string, unknown> = { ...settings };
     const overrides = new Set<string>();
 
     for (const [key, envVar] of Object.entries(SettingsManager.envMapping)) {
       const value = process.env[envVar];
       if (value !== undefined) {
-        (merged as Record<string, unknown>)[key] = value;
+        merged[key] = value;
         overrides.add(key);
       }
     }
 
-    return { settings: merged, overrides };
+    const result = settingsSchema.safeParse(merged);
+    if (!result.success) {
+      log.error({ issues: result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`) }, "settings env override validation failed");
+      process.exit(1);
+    }
+
+    return { settings: result.data, overrides };
   }
 
   print(settings: Settings, overrides: Set<string>): void {

package/src/setup.test.ts

@@ -79,7 +79,7 @@ function createMockIO(inputs: string[]): SetupIo & { written: string[] } {
 }
 
 // Save/restore env vars
-const envVars = ["TELEGRAM_BOT_TOKEN", "AUTHORIZED_CHAT_ID", "MODEL", "WORKSPACE", "OPENAI_API_KEY", "LOG_LEVEL"];
+const envVars = ["TELEGRAM_BOT_TOKEN", "AUTHORIZED_CHAT_ID", "MODEL", "WORKSPACE", "TIMEZONE", "OPENAI_API_KEY", "LOG_LEVEL"];
 const savedEnv: Record<string, string | undefined> = {};
 
 beforeEach(() => {
@@ -107,12 +107,13 @@ afterEach(() => {
 describe("SetupWizard", () => {
   it("collects all required fields via prompts", async () => {
     const io = createMockIO([
-      "123:ABC",   // bot token
-      "12345678",  // chat ID
-      "opus",      // model
-      "/my/ws",    // workspace
-      "sk-test",   // openai key
-      "",          // no service install
+      "123:ABC",        // bot token
+      "12345678",       // chat ID
+      "opus",           // model
+      "/my/ws",         // workspace
+      "Europe/Prague",  // timezone
+      "sk-test",        // openai key
+      "",               // no service install
     ]);
 
     const settings = await runSetup(io);
@@ -121,6 +122,7 @@ describe("SetupWizard", () => {
     expect(settings.chatId).toBe("12345678");
     expect(settings.model).toBe("opus");
     expect(settings.workspace).toBe("/my/ws");
+    expect(settings.timezone).toBe("Europe/Prague");
     expect(settings.openaiApiKey).toBe("sk-test");
     expect(settings.logLevel).toBe("info");
   });
@@ -130,6 +132,7 @@ describe("SetupWizard", () => {
     process.env.AUTHORIZED_CHAT_ID = "99887766";
     process.env.MODEL = "haiku";
     process.env.WORKSPACE = "/env/ws";
+    process.env.TIMEZONE = "America/New_York";
     process.env.OPENAI_API_KEY = "sk-env";
 
     const io = createMockIO([
@@ -137,6 +140,7 @@ describe("SetupWizard", () => {
       "",  // accept default chat ID
       "",  // accept default model
       "",  // accept default workspace
+      "",  // accept default timezone
       "",  // accept default openai key
       "",  // no service install
     ]);
@@ -147,6 +151,7 @@ describe("SetupWizard", () => {
     expect(settings.chatId).toBe("99887766");
     expect(settings.model).toBe("haiku");
     expect(settings.workspace).toBe("/env/ws");
+    expect(settings.timezone).toBe("America/New_York");
     expect(settings.openaiApiKey).toBe("sk-env");
   });
 
@@ -156,6 +161,7 @@ describe("SetupWizard", () => {
       "123",
       "",       // press enter for default model
       "",       // press enter for default workspace
+      "",       // press enter for default timezone
       "",       // press enter for no openai key
       "",       // no service install
     ]);
@@ -173,6 +179,7 @@ describe("SetupWizard", () => {
       "123",
       "",
       "",
+      "",  // timezone
       "",
       "",  // no service install
     ]);
@@ -196,6 +203,7 @@ describe("SetupWizard", () => {
       "good-token",  // second attempt — succeeds
       "123",
       "",
+      "",  // timezone
       "",
       "",
       "",  // no service install
@@ -213,6 +221,7 @@ describe("SetupWizard", () => {
       "actual-token",
       "123",
       "",
+      "",  // timezone
       "",
       "",
       "",  // no service install
@@ -229,6 +238,7 @@ describe("SetupWizard", () => {
       "",        // empty — re-prompt
       "456",
       "",
+      "",  // timezone
       "",
       "",
       "",  // no service install
@@ -245,6 +255,7 @@ describe("SetupWizard", () => {
       "not-a-number",  // invalid — re-prompt
       "456",
       "",
+      "",  // timezone
       "",
       "",
       "",  // no service install
@@ -263,6 +274,7 @@ describe("SetupWizard", () => {
       "xxx",     // invalid — re-prompt
       "opus",    // valid
       "",
+      "",  // timezone
       "",
       "",  // no service install
     ]);
@@ -279,6 +291,7 @@ describe("SetupWizard", () => {
       "123",
       "",
       "",
+      "",  // timezone
       "",
       "",  // no service install
     ]);
@@ -297,6 +310,7 @@ describe("SetupWizard", () => {
       "123",
       "",
       "",
+      "",  // timezone
       "",
       "",  // no service install
     ]);
@@ -317,6 +331,7 @@ it("installs service when user answers yes", async () => {
       "123",
       "",
       "",
+      "",  // timezone
       "",
       "y",
       "sk-test-token",  // oauth token (macOS)
@@ -336,6 +351,7 @@ it("installs service when user answers yes", async () => {
       "123",
       "",
       "",
+      "",  // timezone
       "",
       "n",  // no to service install
     ]);
@@ -353,6 +369,7 @@ it("installs service when user answers yes", async () => {
       "123",
       "",
       "",
+      "",  // timezone
       "",
       "y",
       "",  // empty oauth token
@@ -373,6 +390,7 @@ it("installs service when user answers yes", async () => {
       "123",
       "",
       "",
+      "",  // timezone
       "",
       "yes",
       "sk-test-token",  // oauth token (macOS)

package/src/setup.ts

@@ -84,6 +84,13 @@ export class SetupWizard {
       const defaultWorkspace = this.#default("workspace", "~/.macroclaw-workspace");
       const workspace = await this.#askValidated("workspace", `Workspace [${defaultWorkspace}]: `, defaultWorkspace);
 
+      // Timezone
+      this.#io.write("\nLocal timezone for the agent's clock and scheduled events.\n");
+      this.#io.write("Use an IANA timezone name (e.g. Europe/Prague, America/New_York, UTC).\n\n");
+      const detectedTz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+      const defaultTimezone = this.#default("timezone", detectedTz || "UTC");
+      const timezone = await this.#askValidated("timezone", `Timezone [${defaultTimezone}]: `, defaultTimezone);
+
       // OpenAI API key
       this.#io.write("\nMacroclaw uses OpenAI's Whisper API to transcribe voice messages.\n");
       this.#io.write("Without this key, voice messages will be ignored.\n\n");
@@ -99,6 +106,7 @@ export class SetupWizard {
         chatId,
         model,
         workspace,
+        timezone,
         openaiApiKey,
         ...(logLevel && { logLevel }),
       });
@@ -157,7 +165,7 @@ export class SetupWizard {
     let value = await this.#io.ask(prompt) || fallback;
     while (true) {
       const result = schema.safeParse(value);
-      if (result.success) return value;
+      if (result.success) return result.data as string;
       const issue = result.error?.issues?.[0];
       this.#io.write(`Invalid value: ${issue?.message ?? "validation failed"}. Please try again.\n`);
       value = await this.#io.ask(prompt) || fallback;

package/workspace-template/.claude/skills/schedule/SKILL.md

@@ -19,7 +19,7 @@ Schedule a new event by adding it to `data/schedule.json`.
 1. Run `date` to get the current date and time
 2. Read `data/schedule.json` (create with `{"jobs": []}` if missing)
 3. Determine job type:
-   - **Recurring** → convert to a cron expression (UTC). See reference below.
+   - **Recurring** → convert to a cron expression in local time. See reference below.
    - **One-time** → compute an ISO 8601 timestamp with the user's timezone offset for `fireAt`
 4. **Be proactive about timing**: if the user says "next week" or "tomorrow" without a specific time, pick the best time based on what you know (their routine, calendar, context)
 5. Append the new job to the `jobs` array
@@ -30,14 +30,16 @@ Schedule a new event by adding it to `data/schedule.json`.
 
 The user's timezone is in their profile (CLAUDE.md/USER.md).
 
-**One-time events** use `fireAt` with the user's timezone offset:
-- "in 5 minutes" → compute exact time, e.g. `"fireAt": "2026-03-16T10:05:00+01:00"`
-- "tomorrow at 10am" → `"fireAt": "2026-03-14T10:00:00+01:00"`
-- "next Monday" → `"fireAt": "2026-03-17T09:00:00+01:00"` (pick a sensible time)
+**One-time events** use `fireAt` in local time (no offset needed — interpreted in the configured timezone):
+- "in 5 minutes" → compute exact time, e.g. `"fireAt": "2026-03-16T10:05:00"`
+- "tomorrow at 10am" → `"fireAt": "2026-03-14T10:00:00"`
+- "next Monday" → `"fireAt": "2026-03-17T09:00:00"` (pick a sensible time)
 
-**Recurring events** use `cron` in UTC:
-- "every morning" → `"cron": "0 7 * * *"` (adjust for timezone)
-- "every weekday at 9" → `"cron": "0 7 * * 1-5"` (UTC)
+Only add a timezone offset when the event targets a different timezone than the configured one (e.g. the user is traveling or scheduling for another location).
+
+**Recurring events** use `cron` in local time:
+- "every morning" → `"cron": "0 7 * * *"`
+- "every weekday at 9" → `"cron": "0 9 * * 1-5"`
 - "every 30 minutes" → `"cron": "*/30 * * * *"`
 
 ## schedule.json format
@@ -60,7 +62,7 @@ Two job types, discriminated by field:
     },
     {
       "name": "dentist-reminder",
-      "fireAt": "2026-03-15T08:00:00+01:00",
+      "fireAt": "2026-03-15T08:00:00",
       "prompt": "Reminder: call the dentist to reschedule your appointment"
     }
   ]
@@ -72,14 +74,14 @@ Two job types, discriminated by field:
 | Field | Required | Description |
 |-------|----------|-------------|
 | `name` | yes | Short kebab-case identifier (e.g. `dentist-reminder`). Appears in the `[Context: cron/<name>]` prefix when fired. |
-| `cron` | for recurring | Standard cron expression (UTC). See reference below. |
-| `fireAt` | for one-time | ISO 8601 timestamp, preferably with timezone offset (e.g. `2026-03-15T08:00:00+01:00`). Any format parseable by JavaScript `Date` works. |
+| `cron` | for recurring | Standard cron expression (local time). See reference below. |
+| `fireAt` | for one-time | ISO 8601 timestamp (e.g. `2026-03-15T08:00:00`). Can include a timezone offset (e.g. `2026-03-15T08:00:00+01:00`); without one, the time is interpreted in the configured timezone. |
 | `prompt` | yes | The message sent to the agent when the event fires. Write it as a natural instruction. |
 | `model` | no | Override the model. Use `haiku` for cheap checks, `opus` for complex reasoning. Omit for default. |
 
 Each job must have exactly one of `cron` or `fireAt` (not both).
 
-## Cron expression reference (UTC)
+## Cron expression reference (local time)
 
 ```
 ┌───────── minute (0-59)
@@ -92,11 +94,11 @@ Each job must have exactly one of `cron` or `fireAt` (not both).
 ```
 
 Common patterns:
-- `0 9 * * *` — daily at 9:00 UTC
-- `0 7 * * 1-5` — weekdays at 7:00 UTC
+- `0 9 * * *` — daily at 9:00
+- `0 7 * * 1-5` — weekdays at 7:00
 - `*/30 * * * *` — every 30 minutes
 - `0 */2 * * *` — every 2 hours
-- `0 9,18 * * *` — at 9:00 and 18:00 UTC
+- `0 9,18 * * *` — at 9:00 and 18:00
 
 ## Notes