agent-sin 0.1.12 → 0.1.15

package/templates/skill-typescript/main.ts

@@ -6,11 +6,30 @@
 //   ctx.log.info(msg) / warn / error    writes to logs/runs/<run-id>.json and events.jsonl
 //   ctx.memory.get(key) / set(key, v)   persists under skill.yaml memory.namespace
 //   ctx.ai.run(step_id, payload)        calls an ai_steps entry declared in skill.yaml
-//   ctx.notify(args)                    notifies Discord/Telegram/macOS/Mail/Slack/stderr (auto recommended)
+//   ctx.notify(args)                    notifies Discord/Telegram/macOS/Mail/Slack/stderr (auto recommended);
+//                                       pass filePath/filePaths to attach local files on Discord/Telegram
+//   ctx.history.append({time?, meta?, content, replace?})  insert/upsert one row in this skill's SQLite log
+//   ctx.history.list({from?, to?, limit?})        read past rows as [{time, meta, content}] (date range filter)
+//   ctx.history.read({from?, to?})                read past rows as one concatenated string (handy for ai_steps)
 //   ctx.now()                           current time as an ISO8601 string
 //
 // See src/skills-sdk/types.ts for SkillInput / SkillResult.
 // Runtime handles saving, notifications, and cron; skills should not touch fs directly.
+//
+// If you need to write a user-visible markdown that the runtime's outputs block
+// doesn't fit (free-form filename, rotating log, accumulating list), write it
+// under input.sources.skillOutputDir:
+//
+//   import { mkdir, appendFile } from "node:fs/promises";
+//   import path from "node:path";
+//   const dir = input.sources.skillOutputDir!;
+//   await appendFile(path.join(dir, "my-log.md"), "...\n");
+//
+// The runtime creates the dir before invoking the skill. Use a plain filename
+// like "marketing-log.md" — DO NOT create date-based subdirectories like
+// 2026/05/2026-05-22.md. Files placed here surface in Obsidian as
+// "06 Skills/<skill-id>/...". For internal state the user shouldn't see, use
+// ctx.memory or ctx.history, not this dir.
 
 interface SkillCtx {
   log: { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void };
@@ -20,15 +39,24 @@ interface SkillCtx {
     set: (key: string, value: unknown) => Promise<boolean>;
   };
   ai: { run: (stepId: string, payload: unknown) => Promise<unknown> };
+  history: {
+    append: (args: { time?: string | Date; meta?: Record<string, unknown>; content: string; replace?: boolean }) => Promise<{ path: string; id: string }>;
+    list: (options?: { from?: string | Date; to?: string | Date; limit?: number }) => Promise<Array<{ time: string; meta: Record<string, unknown>; content: string }>>;
+    read: (options?: { from?: string | Date; to?: string | Date }) => Promise<string>;
+  };
   notify: (args: {
-    title: string;
-    body: string;
+    title?: string;
+    body?: string;
     subtitle?: string;
     sound?: boolean;
-    channel?: "auto" | "macos" | "discord" | "telegram" | "slack" | "mail" | "stderr";
+    channel?: "auto" | "macos" | "discord" | "telegram" | "slack" | "mail" | "g2" | "stderr";
     to?: string;
     discordThreadId?: string;
     telegramThreadId?: string;
+    filePath?: string;
+    filePaths?: string[];
+    imagePath?: string;
+    imagePaths?: string[];
   }) => Promise<{ ok: boolean; channel: string; detail?: string }>;
   now: () => string;
 }
@@ -36,7 +64,14 @@ interface SkillCtx {
 interface SkillInput {
   args: Record<string, unknown>;
   trigger: { type: string; id: string; time: string };
-  sources: Record<string, unknown> & { locale?: string };
+  sources: Record<string, unknown> & {
+    locale?: string;
+    workspace?: string;
+    notes_dir?: string;
+    memory_dir?: string;
+    skill_output_dir?: string;
+    skillOutputDir?: string;
+  };
   memory: Record<string, unknown>;
 }
 

package/templates/skill-typescript/skill.yaml

@@ -36,6 +36,15 @@ memory:
   read: true
   write: true
 
+# Enable history when the skill should accumulate a queryable log (food,
+# weight, training, reviews, etc.). Entries land in ~/.agent-sin/data/<skill-id>.db
+# (SQLite, hidden from the user) and the skill reads them back via
+# ctx.history.list({from, to, limit}). Pair it with an outputs entry below if
+# you also want a human-readable Markdown report under notes/.
+# history:
+#   read: true
+#   write: true
+
 # Optional: set "raw" only when you want to return the summary directly to users.
 # By default, the LLM receives the result and formats a natural-language reply.
 # See https://agent.shingoirie.com/skill-authoring for details.