stagent 0.9.6 → 0.11.0

package/src/lib/chat/tools/helpers.ts

@@ -2,9 +2,16 @@
  * Shared helpers and types for Stagent chat MCP tools.
  */
 
+import { db } from "@/lib/db";
+import { like } from "drizzle-orm";
+import type { SQLiteTableWithColumns } from "drizzle-orm/sqlite-core";
+import type { SQLiteColumn } from "drizzle-orm/sqlite-core";
+
 /** Context passed to each tool factory — provides project scoping and entity callbacks. */
 export interface ToolContext {
   projectId?: string | null;
+  /** Absolute path to the active project's working directory. Used by profile tools to surface filesystem skills. */
+  projectDir?: string | null;
   onToolResult?: (toolName: string, result: unknown) => void;
 }
 
@@ -22,3 +29,37 @@ export function err(message: string) {
     isError: true as const,
   };
 }
+
+/**
+ * Resolve an entity ID that may be a prefix (8+ chars) to the full UUID.
+ * Uses LIKE 'prefix%' which hits the primary key B-tree index on SQLite.
+ *
+ * Fast path: IDs >=32 chars are returned as-is (already full UUIDs).
+ */
+export async function resolveEntityId(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  table: SQLiteTableWithColumns<any>,
+  idColumn: SQLiteColumn,
+  rawId: string,
+): Promise<{ id: string } | { error: string }> {
+  // Full UUIDs are 36 chars (with hyphens) or 32 (without) — skip prefix search
+  if (rawId.length >= 32) {
+    return { id: rawId };
+  }
+
+  const matches = await db
+    .select({ id: idColumn })
+    .from(table)
+    .where(like(idColumn, `${rawId}%`))
+    .limit(2);
+
+  if (matches.length === 0) {
+    return { error: `No entity found matching ID prefix: ${rawId}` };
+  }
+  if (matches.length > 1) {
+    return {
+      error: `Ambiguous ID prefix "${rawId}" matches multiple entities: ${matches.map((m) => m.id).join(", ")}. Use the full ID.`,
+    };
+  }
+  return { id: matches[0].id as string };
+}

package/src/lib/chat/tools/notification-tools.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { db } from "@/lib/db";
 import { notifications } from "@/lib/db/schema";
 import { eq, isNull, desc } from "drizzle-orm";
-import { ok, err, type ToolContext } from "./helpers";
+import { ok, err, resolveEntityId, type ToolContext } from "./helpers";
 
 export function notificationTools(_ctx: ToolContext) {
   return [
@@ -73,13 +73,17 @@ export function notificationTools(_ctx: ToolContext) {
       },
       async (args) => {
         try {
+          const resolved = await resolveEntityId(notifications, notifications.id, args.notificationId);
+          if ("error" in resolved) return err(resolved.error);
+          const notificationId = resolved.id;
+
           const notification = await db
             .select()
             .from(notifications)
-            .where(eq(notifications.id, args.notificationId))
+            .where(eq(notifications.id, notificationId))
             .get();
 
-          if (!notification) return err(`Notification not found: ${args.notificationId}`);
+          if (!notification) return err(`Notification not found: ${notificationId}`);
           if (notification.response) return err("Already responded to this notification");
 
           const responseData = {
@@ -98,7 +102,7 @@ export function notificationTools(_ctx: ToolContext) {
               respondedAt: new Date(),
               read: true,
             })
-            .where(eq(notifications.id, args.notificationId));
+            .where(eq(notifications.id, notificationId));
 
           // Save permanent permission if requested
           if (args.behavior === "allow" && args.alwaysAllow && notification.toolName && notification.toolInput) {
@@ -115,7 +119,7 @@ export function notificationTools(_ctx: ToolContext) {
 
           return ok({
             message: `Notification ${args.behavior === "allow" ? "approved" : "denied"}`,
-            notificationId: args.notificationId,
+            notificationId,
             alwaysAllow: args.alwaysAllow ?? false,
           });
         } catch (e) {

package/src/lib/chat/tools/profile-tools.ts

@@ -2,30 +2,42 @@ import { defineTool } from "../tool-registry";
 import { z } from "zod";
 import { ok, err, type ToolContext } from "./helpers";
 
-export function profileTools(_ctx: ToolContext) {
-  return [
-    defineTool(
-      "list_profiles",
-      "List all available agent profiles with their capabilities and compatible runtimes.",
-      {},
-      async () => {
-        try {
-          const { listProfiles } = await import("@/lib/agents/profiles/registry");
-          const profiles = listProfiles();
-          return ok(
-            profiles.map((p) => ({
-              id: p.id,
-              name: p.name,
-              description: p.description,
-              domain: p.domain,
-              tags: p.tags,
-            }))
-          );
-        } catch (e) {
-          return err(e instanceof Error ? e.message : "Failed to list profiles");
-        }
+/**
+ * Factory for the list_profiles tool, parameterized by projectDir so it can
+ * surface project filesystem skills alongside registry profiles via
+ * listFusedProfiles. See features/chat-claude-sdk-skills.md.
+ */
+export function getListProfilesTool(projectDir: string | null) {
+  return defineTool(
+    "list_profiles",
+    "List all available agent profiles and filesystem skills with their capabilities and compatible runtimes.",
+    {},
+    async () => {
+      try {
+        const { listFusedProfiles } = await import(
+          "@/lib/agents/profiles/list-fused-profiles"
+        );
+        const profiles = await listFusedProfiles(projectDir);
+        return ok(
+          profiles.map((p) => ({
+            id: p.id,
+            name: p.name,
+            description: p.description,
+            domain: p.domain,
+            tags: p.tags,
+            origin: p.origin ?? "registry",
+          }))
+        );
+      } catch (e) {
+        return err(e instanceof Error ? e.message : "Failed to list profiles");
       }
-    ),
+    }
+  );
+}
+
+export function profileTools(ctx: ToolContext) {
+  return [
+    getListProfilesTool(ctx.projectDir ?? null),
 
     defineTool(
       "get_profile",
@@ -44,5 +56,90 @@ export function profileTools(_ctx: ToolContext) {
         }
       }
     ),
+
+    defineTool(
+      "create_profile",
+      "Create a new agent profile with a configuration and system prompt (SKILL.md). The profile is saved to ~/.claude/skills/ and becomes immediately available. Use get_profile on an existing profile to see the expected config structure.",
+      {
+        config: z.object({
+          id: z.string().min(1).describe("Unique profile ID (kebab-case, e.g. 'my-analyst')"),
+          name: z.string().min(1).describe("Human-readable profile name"),
+          version: z.string().regex(/^\d+\.\d+\.\d+$/).describe("Semver version, e.g. '1.0.0'"),
+          domain: z.enum(["work", "personal"]).describe("Profile domain"),
+          tags: z.array(z.string()).describe("Searchable tags"),
+          maxTurns: z.number().positive().optional().describe("Max agent turns per task"),
+          outputFormat: z.string().optional().describe("Expected output format hint"),
+          author: z.string().optional().describe("Profile author"),
+        }).describe("Profile configuration object"),
+        skillMd: z.string().min(1).describe(
+          "The SKILL.md content — this is the system prompt that defines the agent's behavior, personality, and instructions. Markdown format."
+        ),
+      },
+      async (args) => {
+        try {
+          const { createProfile } = await import("@/lib/agents/profiles/registry");
+          createProfile(args.config, args.skillMd);
+          ctx.onToolResult?.("create_profile", { id: args.config.id, name: args.config.name });
+          return ok({
+            id: args.config.id,
+            name: args.config.name,
+            message: "Profile created successfully",
+          });
+        } catch (e) {
+          return err(e instanceof Error ? e.message : "Failed to create profile");
+        }
+      }
+    ),
+
+    defineTool(
+      "update_profile",
+      "Update an existing agent profile's configuration and/or system prompt. Built-in profiles cannot be modified — duplicate them first with create_profile.",
+      {
+        profileId: z.string().describe("The profile ID to update"),
+        config: z.object({
+          id: z.string().min(1),
+          name: z.string().min(1),
+          version: z.string().regex(/^\d+\.\d+\.\d+$/),
+          domain: z.enum(["work", "personal"]),
+          tags: z.array(z.string()),
+          maxTurns: z.number().positive().optional(),
+          outputFormat: z.string().optional(),
+          author: z.string().optional(),
+        }).describe("Full profile configuration (replaces existing)"),
+        skillMd: z.string().min(1).describe("Updated SKILL.md content"),
+      },
+      async (args) => {
+        try {
+          const { updateProfile } = await import("@/lib/agents/profiles/registry");
+          updateProfile(args.profileId, args.config, args.skillMd);
+          ctx.onToolResult?.("update_profile", { id: args.profileId });
+          return ok({
+            id: args.profileId,
+            message: "Profile updated successfully",
+          });
+        } catch (e) {
+          return err(e instanceof Error ? e.message : "Failed to update profile");
+        }
+      }
+    ),
+
+    defineTool(
+      "delete_profile",
+      "Delete a custom agent profile. Built-in profiles cannot be deleted.",
+      {
+        profileId: z.string().describe("The profile ID to delete"),
+      },
+      async (args) => {
+        try {
+          const { deleteProfile } = await import("@/lib/agents/profiles/registry");
+          deleteProfile(args.profileId);
+          return ok({
+            message: `Profile "${args.profileId}" deleted`,
+          });
+        } catch (e) {
+          return err(e instanceof Error ? e.message : "Failed to delete profile");
+        }
+      }
+    ),
   ];
 }

package/src/lib/chat/tools/project-tools.ts

@@ -85,5 +85,38 @@ export function projectTools(ctx: ToolContext) {
         }
       }
     ),
+
+    defineTool(
+      "delete_project",
+      "Permanently delete a project and all its resources (tasks, tables, schedules, " +
+        "documents, app instances). This is irreversible. Use to clean up orphaned or " +
+        "unwanted projects. Always confirm with the user before calling.",
+      {
+        projectId: z
+          .string()
+          .describe("The ID of the project to delete"),
+      },
+      async (args) => {
+        try {
+          const { deleteProjectCascade } = await import(
+            "@/lib/data/delete-project"
+          );
+
+          const deleted = deleteProjectCascade(args.projectId);
+          if (!deleted) {
+            return err(`Project "${args.projectId}" not found`);
+          }
+
+          return ok({
+            projectId: args.projectId,
+            message: `Project "${args.projectId}" and all its resources have been deleted.`,
+          });
+        } catch (e) {
+          return err(
+            e instanceof Error ? e.message : "Failed to delete project",
+          );
+        }
+      }
+    ),
   ];
 }

package/src/lib/chat/tools/schedule-tools.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { db } from "@/lib/db";
 import { schedules } from "@/lib/db/schema";
 import { eq, and, desc } from "drizzle-orm";
-import { ok, err, type ToolContext } from "./helpers";
+import { ok, err, resolveEntityId, type ToolContext } from "./helpers";
 import { analyzePromptEfficiency } from "@/lib/schedules/prompt-analyzer";
 
 const VALID_SCHEDULE_STATUSES = [
@@ -69,6 +69,13 @@ export function scheduleTools(ctx: ToolContext) {
           .number()
           .optional()
           .describe("Auto-expire after this many hours"),
+        maxTurns: z
+          .number()
+          .int()
+          .min(10)
+          .max(500)
+          .optional()
+          .describe("Hard cap on turns per firing (10-500). Omit to inherit the system default."),
       },
       async (args) => {
         try {
@@ -147,6 +154,8 @@ export function scheduleTools(ctx: ToolContext) {
             recurs: true,
             status: "active",
             maxFirings: args.maxFirings ?? null,
+            maxTurns: args.maxTurns ?? null,
+            maxTurnsSetAt: args.maxTurns !== undefined ? now : null,
             firingCount: 0,
             expiresAt,
             nextFireAt,
@@ -184,13 +193,17 @@ export function scheduleTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
+          const resolved = await resolveEntityId(schedules, schedules.id, args.scheduleId);
+          if ("error" in resolved) return err(resolved.error);
+          const scheduleId = resolved.id;
+
           const schedule = await db
             .select()
             .from(schedules)
-            .where(eq(schedules.id, args.scheduleId))
+            .where(eq(schedules.id, scheduleId))
             .get();
 
-          if (!schedule) return err(`Schedule not found: ${args.scheduleId}`);
+          if (!schedule) return err(`Schedule not found: ${scheduleId}`);
           ctx.onToolResult?.("get_schedule", schedule);
           return ok(schedule);
         } catch (e) {
@@ -216,16 +229,28 @@ export function scheduleTools(ctx: ToolContext) {
           .describe("New status (use 'paused' to pause, 'active' to resume)"),
         assignedAgent: z.string().optional().describe("New runtime ID"),
         agentProfile: z.string().optional().describe("New agent profile"),
+        maxTurns: z
+          .number()
+          .int()
+          .min(10)
+          .max(500)
+          .optional()
+          .nullable()
+          .describe("Hard cap on turns per firing (10-500). Pass null to clear an override back to the system default."),
       },
       async (args) => {
         try {
+          const resolved = await resolveEntityId(schedules, schedules.id, args.scheduleId);
+          if ("error" in resolved) return err(resolved.error);
+          const scheduleId = resolved.id;
+
           const existing = await db
             .select()
             .from(schedules)
-            .where(eq(schedules.id, args.scheduleId))
+            .where(eq(schedules.id, scheduleId))
             .get();
 
-          if (!existing) return err(`Schedule not found: ${args.scheduleId}`);
+          if (!existing) return err(`Schedule not found: ${scheduleId}`);
 
           const updates: Record<string, unknown> = { updatedAt: new Date() };
           if (args.name !== undefined) updates.name = args.name;
@@ -233,6 +258,10 @@ export function scheduleTools(ctx: ToolContext) {
           if (args.status !== undefined) updates.status = args.status;
           if (args.assignedAgent !== undefined) updates.assignedAgent = args.assignedAgent;
           if (args.agentProfile !== undefined) updates.agentProfile = args.agentProfile;
+          if (args.maxTurns !== undefined) {
+            updates.maxTurns = args.maxTurns;
+            updates.maxTurnsSetAt = args.maxTurns === null ? null : new Date();
+          }
 
           if (args.interval) {
             const { parseInterval, computeNextFireTime } = await import(
@@ -267,12 +296,12 @@ export function scheduleTools(ctx: ToolContext) {
           await db
             .update(schedules)
             .set(updates)
-            .where(eq(schedules.id, args.scheduleId));
+            .where(eq(schedules.id, scheduleId));
 
           const [schedule] = await db
             .select()
             .from(schedules)
-            .where(eq(schedules.id, args.scheduleId));
+            .where(eq(schedules.id, scheduleId));
 
           ctx.onToolResult?.("update_schedule", schedule);
           return ok(schedule);
@@ -290,16 +319,20 @@ export function scheduleTools(ctx: ToolContext) {
       },
       async (args) => {
         try {
+          const resolved = await resolveEntityId(schedules, schedules.id, args.scheduleId);
+          if ("error" in resolved) return err(resolved.error);
+          const scheduleId = resolved.id;
+
           const existing = await db
             .select()
             .from(schedules)
-            .where(eq(schedules.id, args.scheduleId))
+            .where(eq(schedules.id, scheduleId))
             .get();
 
-          if (!existing) return err(`Schedule not found: ${args.scheduleId}`);
+          if (!existing) return err(`Schedule not found: ${scheduleId}`);
 
-          await db.delete(schedules).where(eq(schedules.id, args.scheduleId));
-          return ok({ message: "Schedule deleted", scheduleId: args.scheduleId, name: existing.name });
+          await db.delete(schedules).where(eq(schedules.id, scheduleId));
+          return ok({ message: "Schedule deleted", scheduleId, name: existing.name });
         } catch (e) {
           return err(e instanceof Error ? e.message : "Failed to delete schedule");
         }

package/src/lib/chat/tools/skill-tools.ts

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import { defineTool } from "../tool-registry";
+import { ok, err, type ToolContext } from "./helpers";
+
+/**
+ * Stagent MCP tools for conversation-scoped skill management.
+ *
+ * Primary consumer: Ollama — the HTTP chat-completion API has no native
+ * concept of skills, so Stagent takes over: activate a skill (persist to
+ * conversations.active_skill_id) → context builder injects its SKILL.md
+ * into Tier 0 of every subsequent turn.
+ *
+ * Secondary consumer: Claude and Codex runtimes may also call these tools
+ * for a programmatic skill-activation path alongside their native Skill
+ * handling. The tools themselves are runtime-agnostic — they just bind
+ * skill IDs to conversation rows.
+ *
+ * See `features/chat-ollama-native-skills.md`.
+ */
+
+// `mergeActiveSkillIds` lives in `@/lib/chat/active-skills` so client code
+// can import the pure helper without pulling this module's `db` import.
+// Re-exported here for back-compat with existing callers (tests, etc.).
+import { mergeActiveSkillIds } from "@/lib/chat/active-skills";
+export { mergeActiveSkillIds };
+
+export function skillTools(_ctx: ToolContext) {
+  return [
+    defineTool(
+      "list_skills",
+      "List all Stagent-discoverable skills across user (~/.claude, ~/.codex) and project (.claude, .agents) scopes. Returns id, name, tool persona, scope, and a short preview for each. Pass `enriched: true` for additional per-skill metadata (healthScore, syncStatus, linkedProfileId). Read-only.",
+      {
+        enriched: z
+          .boolean()
+          .optional()
+          .describe(
+            "When true, include healthScore ('healthy'|'stale'|'aging'|'unknown'), syncStatus ('synced'|'claude-only'|'codex-only'|'shared'), and linkedProfileId per skill."
+          ),
+      },
+      async (args) => {
+        try {
+          if (args.enriched) {
+            const { listSkillsEnriched } = await import("@/lib/environment/list-skills");
+            const skills = listSkillsEnriched();
+            return ok({
+              count: skills.length,
+              skills: skills.map((s) => ({
+                id: s.id,
+                name: s.name,
+                tool: s.tool,
+                scope: s.scope,
+                preview: s.preview,
+                sizeBytes: s.sizeBytes,
+                healthScore: s.healthScore,
+                syncStatus: s.syncStatus,
+                linkedProfileId: s.linkedProfileId,
+              })),
+            });
+          }
+          const { listSkills } = await import("@/lib/environment/list-skills");
+          const skills = listSkills();
+          return ok({
+            count: skills.length,
+            skills: skills.map((s) => ({
+              id: s.id,
+              name: s.name,
+              tool: s.tool,
+              scope: s.scope,
+              preview: s.preview,
+              sizeBytes: s.sizeBytes,
+            })),
+          });
+        } catch (e) {
+          return err(e instanceof Error ? e.message : "list_skills failed");
+        }
+      }
+    ),
+
+    defineTool(
+      "get_skill",
+      "Return the full SKILL.md content plus metadata for a single skill, identified by the id returned from list_skills. Use this to preview a skill before activating it.",
+      {
+        id: z
+          .string()
+          .describe("Opaque skill ID (from list_skills). Typically the relative path."),
+      },
+      async (args) => {
+        try {
+          const { getSkill } = await import("@/lib/environment/list-skills");
+          const skill = getSkill(args.id);
+          if (!skill) return err(`Skill not found: ${args.id}`);
+          return ok({
+            id: skill.id,
+            name: skill.name,
+            tool: skill.tool,
+            scope: skill.scope,
+            sizeBytes: skill.sizeBytes,
+            content: skill.content,
+          });
+        } catch (e) {
+          return err(e instanceof Error ? e.message : "get_skill failed");
+        }
+      }
+    ),
+
+    defineTool(
+      "activate_skill",
+      "Activate a skill on a conversation. While active, the skill's SKILL.md is injected into the system prompt on every subsequent turn. Default mode 'replace' clears any prior active skills and binds just this one. Pass mode='add' to compose multiple skills (gated by runtime — Ollama refuses; Claude/Codex/direct allow up to 3). Pass force=true to skip conflict warnings on add.",
+      {
+        conversationId: z.string().describe("ID of the conversation to bind the skill to."),
+        skillId: z.string().describe("Opaque skill ID from list_skills (typically the relative path)."),
+        mode: z
+          .enum(["replace", "add"])
+          .optional()
+          .default("replace")
+          .describe("'replace' (default) clears prior active skills; 'add' appends — runtime must support composition."),
+        force: z
+          .boolean()
+          .optional()
+          .default(false)
+          .describe("When mode='add', skip the conflict heuristic check and add anyway."),
+      },
+      async (args) => {
+        const { activateSkill } = await import("@/lib/chat/skill-composition");
+        const result = await activateSkill({
+          conversationId: args.conversationId,
+          skillId: args.skillId,
+          mode: args.mode,
+          force: args.force,
+        });
+
+        if (result.kind === "error") return err(result.message);
+
+        if (result.kind === "conflicts") {
+          return ok({
+            conversationId: args.conversationId,
+            requiresConfirmation: true,
+            conflicts: result.conflicts,
+            hint: "Re-call activate_skill with force=true to add anyway",
+          });
+        }
+
+        // kind === "ok"
+        if (result.note === "skill already active") {
+          return ok({
+            conversationId: args.conversationId,
+            activeSkillIds: result.activeSkillIds,
+            note: result.note,
+          });
+        }
+
+        return ok({
+          conversationId: args.conversationId,
+          activatedSkillId: result.activatedSkillId,
+          activeSkillIds: result.activeSkillIds,
+          skillName: result.skillName,
+        });
+      }
+    ),
+
+    defineTool(
+      "deactivate_skill",
+      "Clear the active skill on a conversation. After this call, subsequent turns will not include any Stagent-injected SKILL.md in the system prompt.",
+      {
+        conversationId: z
+          .string()
+          .describe("ID of the conversation to clear the active skill from."),
+      },
+      async (args) => {
+        const { deactivateSkill } = await import("@/lib/chat/skill-composition");
+        const result = await deactivateSkill({ conversationId: args.conversationId });
+
+        if (result.kind === "error") return err(result.message);
+
+        return ok({
+          conversationId: args.conversationId,
+          previousSkillId: result.previousSkillId,
+          activeSkillId: null,
+        });
+      }
+    ),
+  ];
+}