stagent 0.1.0

package/src/lib/utils/crypto.ts

@@ -0,0 +1,90 @@
+import { randomBytes, createCipheriv, createDecipheriv } from "crypto";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const ALGORITHM = "aes-256-gcm";
+const IV_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+const KEY_LENGTH = 32;
+
+function getKeyfilePath(): string {
+  return join(
+    process.env.STAGENT_DATA_DIR || join(homedir(), ".stagent"),
+    ".keyfile"
+  );
+}
+
+/**
+ * Read or create the encryption keyfile at ~/.stagent/.keyfile.
+ * File is 32 random bytes with chmod 0600 (owner-only read/write).
+ */
+export function getOrCreateKeyfile(): Buffer {
+  const keyfilePath = getKeyfilePath();
+
+  if (existsSync(keyfilePath)) {
+    const key = readFileSync(keyfilePath);
+    if (key.length !== KEY_LENGTH) {
+      throw new Error(`Invalid keyfile: expected ${KEY_LENGTH} bytes, got ${key.length}`);
+    }
+    return key;
+  }
+
+  // Create parent directory if needed
+  const dir = join(keyfilePath, "..");
+  mkdirSync(dir, { recursive: true });
+
+  const key = randomBytes(KEY_LENGTH);
+  writeFileSync(keyfilePath, key, { mode: 0o600 });
+  chmodSync(keyfilePath, 0o600);
+  return key;
+}
+
+/**
+ * Encrypt plaintext using AES-256-GCM.
+ * Returns base64 string in format: iv:authTag:ciphertext
+ */
+export function encrypt(plaintext: string): string {
+  const key = getOrCreateKeyfile();
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext, "utf8"),
+    cipher.final(),
+  ]);
+  const authTag = cipher.getAuthTag();
+
+  return [
+    iv.toString("base64"),
+    authTag.toString("base64"),
+    encrypted.toString("base64"),
+  ].join(":");
+}
+
+/**
+ * Decrypt a string previously encrypted with encrypt().
+ * Expects base64 format: iv:authTag:ciphertext
+ */
+export function decrypt(encrypted: string): string {
+  const parts = encrypted.split(":");
+  if (parts.length !== 3) {
+    throw new Error("Invalid encrypted format: expected iv:authTag:ciphertext");
+  }
+
+  const [ivB64, authTagB64, ciphertextB64] = parts;
+  const key = getOrCreateKeyfile();
+  const iv = Buffer.from(ivB64, "base64");
+  const authTag = Buffer.from(authTagB64, "base64");
+  const ciphertext = Buffer.from(ciphertextB64, "base64");
+
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(authTag);
+
+  const decrypted = Buffer.concat([
+    decipher.update(ciphertext),
+    decipher.final(),
+  ]);
+
+  return decrypted.toString("utf8");
+}

package/src/lib/utils/format-timestamp.ts

@@ -0,0 +1,46 @@
+const MINUTE = 60_000;
+const HOUR = 3_600_000;
+const DAY = 86_400_000;
+
+/**
+ * Formats a timestamp with relative time for recent items
+ * and a full date for older ones.
+ */
+export function formatTimestamp(date: string | Date): string {
+  const d = typeof date === "string" ? new Date(date) : date;
+  const now = Date.now();
+  const diff = now - d.getTime();
+
+  if (diff < MINUTE) return "just now";
+  if (diff < HOUR) {
+    const mins = Math.floor(diff / MINUTE);
+    return `${mins}m ago`;
+  }
+  if (diff < DAY) {
+    const hours = Math.floor(diff / HOUR);
+    return `${hours}h ago`;
+  }
+  if (diff < 7 * DAY) {
+    const days = Math.floor(diff / DAY);
+    return `${days}d ago`;
+  }
+
+  return d.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: d.getFullYear() !== new Date().getFullYear() ? "numeric" : undefined,
+  });
+}
+
+/**
+ * Formats a timestamp as HH:MM:SS for log entries.
+ */
+export function formatTime(date: string | Date): string {
+  const d = typeof date === "string" ? new Date(date) : date;
+  return d.toLocaleTimeString("en-US", {
+    hour12: false,
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  });
+}

package/src/lib/utils/session-cleanup.ts

@@ -0,0 +1,26 @@
+import { db } from "@/lib/db";
+import { tasks } from "@/lib/db/schema";
+import { eq, and, lt, isNotNull, inArray } from "drizzle-orm";
+
+/**
+ * Nullify sessionId on completed/failed tasks older than retention period.
+ * Manual utility — not auto-scheduled.
+ */
+export function cleanupOldSessions(retentionDays = 7): number {
+  const cutoff = new Date(Date.now() - retentionDays * 24 * 60 * 60 * 1000);
+
+  const result = db
+    .update(tasks)
+    .set({ sessionId: null })
+    .where(
+      and(
+        isNotNull(tasks.sessionId),
+        inArray(tasks.status, ["completed", "failed"]),
+        lt(tasks.updatedAt, cutoff)
+      )
+    )
+    .returning()
+    .all();
+
+  return result.length;
+}

package/src/lib/utils/stagent-paths.ts

@@ -0,0 +1,18 @@
+import { homedir } from "os";
+import { join } from "path";
+
+export function getStagentDataDir(): string {
+  return process.env.STAGENT_DATA_DIR || join(homedir(), ".stagent");
+}
+
+export function getStagentDbPath(): string {
+  return join(getStagentDataDir(), "stagent.db");
+}
+
+export function getStagentUploadsDir(): string {
+  return join(getStagentDataDir(), "uploads");
+}
+
+export function getStagentBlueprintsDir(): string {
+  return join(getStagentDataDir(), "blueprints");
+}

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/lib/validators/blueprint.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+
+export const BlueprintVariableSchema = z.object({
+  id: z.string(),
+  type: z.enum(["text", "textarea", "select", "number", "boolean", "file"]),
+  label: z.string(),
+  description: z.string().optional(),
+  required: z.boolean(),
+  default: z.unknown().optional(),
+  placeholder: z.string().optional(),
+  options: z
+    .array(z.object({ value: z.string(), label: z.string() }))
+    .optional(),
+  min: z.number().optional(),
+  max: z.number().optional(),
+});
+
+export const BlueprintStepSchema = z.object({
+  name: z.string(),
+  profileId: z.string(),
+  promptTemplate: z.string(),
+  requiresApproval: z.boolean(),
+  expectedOutput: z.string().optional(),
+  condition: z.string().optional(),
+});
+
+export const BlueprintSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  version: z.string().regex(/^\d+\.\d+\.\d+$/),
+  domain: z.enum(["work", "personal"]),
+  tags: z.array(z.string()),
+  pattern: z.enum(["sequence", "planner-executor", "checkpoint"]),
+  variables: z.array(BlueprintVariableSchema),
+  steps: z.array(BlueprintStepSchema).min(1),
+  author: z.string().optional(),
+  source: z.string().url().optional(),
+  estimatedDuration: z.string().optional(),
+  difficulty: z.enum(["beginner", "intermediate", "advanced"]).optional(),
+});
+
+export type BlueprintConfig = z.infer<typeof BlueprintSchema>;

package/src/lib/validators/profile.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { SUPPORTED_AGENT_RUNTIMES } from "@/lib/agents/runtime/catalog";
+
+const runtimeIdSchema = z.enum(SUPPORTED_AGENT_RUNTIMES);
+
+const profileTestsSchema = z.array(
+  z.object({
+    task: z.string(),
+    expectedKeywords: z.array(z.string()),
+  })
+);
+
+const canUseToolPolicySchema = z.object({
+  autoApprove: z.array(z.string()).optional(),
+  autoDeny: z.array(z.string()).optional(),
+});
+
+const profileRuntimeOverrideSchema = z.object({
+  instructions: z.string().min(1).optional(),
+  allowedTools: z.array(z.string()).optional(),
+  mcpServers: z.record(z.string(), z.unknown()).optional(),
+  canUseToolPolicy: canUseToolPolicySchema.optional(),
+  tests: profileTestsSchema.optional(),
+});
+
+export const ProfileConfigSchema = 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()),
+  allowedTools: z.array(z.string()).optional(),
+  mcpServers: z.record(z.string(), z.unknown()).optional(),
+  canUseToolPolicy: canUseToolPolicySchema.optional(),
+  hooks: z
+    .object({
+      preToolCall: z.array(z.string()).optional(),
+      postToolCall: z.array(z.string()).optional(),
+    })
+    .optional(),
+  temperature: z.number().min(0).max(1).optional(),
+  maxTurns: z.number().positive().optional(),
+  outputFormat: z.string().optional(),
+  author: z.string().optional(),
+  source: z.string().url().optional(),
+  tests: profileTestsSchema.optional(),
+  supportedRuntimes: z.array(runtimeIdSchema).optional(),
+  runtimeOverrides: z
+    .object(
+      Object.fromEntries(
+        SUPPORTED_AGENT_RUNTIMES.map((runtimeId) => [
+          runtimeId,
+          profileRuntimeOverrideSchema.optional(),
+        ])
+      ) as Record<
+        (typeof SUPPORTED_AGENT_RUNTIMES)[number],
+        z.ZodOptional<typeof profileRuntimeOverrideSchema>
+      >
+    )
+    .partial()
+    .optional(),
+});
+
+export type ProfileConfig = z.infer<typeof ProfileConfigSchema>;

package/src/lib/validators/project.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+export const createProjectSchema = z.object({
+  name: z.string().min(1, "Name is required").max(100),
+  description: z.string().max(500).optional(),
+  workingDirectory: z.string().max(500).optional(),
+});
+
+export const updateProjectSchema = z.object({
+  name: z.string().min(1).max(100).optional(),
+  description: z.string().max(500).optional(),
+  workingDirectory: z.string().max(500).optional(),
+  status: z.enum(["active", "paused", "completed"]).optional(),
+});
+
+export type CreateProjectInput = z.infer<typeof createProjectSchema>;
+export type UpdateProjectInput = z.infer<typeof updateProjectSchema>;

package/src/lib/validators/settings.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { SUPPORTED_AGENT_RUNTIMES } from "@/lib/agents/runtime/catalog";
+
+export const updateAuthSettingsSchema = z.object({
+  method: z.enum(["api_key", "oauth"]),
+  apiKey: z
+    .string()
+    .startsWith("sk-ant-", "API key must start with sk-ant-")
+    .optional(),
+});
+
+export type UpdateAuthSettingsInput = z.infer<typeof updateAuthSettingsSchema>;
+
+export const updateOpenAISettingsSchema = z.object({
+  apiKey: z
+    .string()
+    .startsWith("sk-", "API key must start with sk-"),
+});
+
+export type UpdateOpenAISettingsInput = z.infer<typeof updateOpenAISettingsSchema>;
+
+const nullablePositiveNumber = z.preprocess((value) => {
+  if (value === "" || value == null) return null;
+  if (typeof value === "string") return Number(value);
+  return value;
+}, z.number().finite().positive().nullable());
+
+const nullablePositiveInteger = z.preprocess((value) => {
+  if (value === "" || value == null) return null;
+  if (typeof value === "string") return Number(value);
+  return value;
+}, z.number().int().positive().nullable());
+
+export const runtimeBudgetPolicySchema = z.object({
+  dailySpendCapUsd: nullablePositiveNumber,
+  monthlySpendCapUsd: nullablePositiveNumber,
+  dailyTokenCap: nullablePositiveInteger,
+  monthlyTokenCap: nullablePositiveInteger,
+});
+
+export const budgetPolicySchema = z.object({
+  overall: z.object({
+    dailySpendCapUsd: nullablePositiveNumber,
+    monthlySpendCapUsd: nullablePositiveNumber,
+  }),
+  runtimes: z.object(
+    Object.fromEntries(
+      SUPPORTED_AGENT_RUNTIMES.map((runtimeId) => [runtimeId, runtimeBudgetPolicySchema])
+    ) as Record<(typeof SUPPORTED_AGENT_RUNTIMES)[number], typeof runtimeBudgetPolicySchema>
+  ),
+});
+
+export const updateBudgetPolicySchema = budgetPolicySchema;
+
+export type RuntimeBudgetPolicy = z.infer<typeof runtimeBudgetPolicySchema>;
+export type BudgetPolicy = z.infer<typeof budgetPolicySchema>;
+export type UpdateBudgetPolicyInput = z.infer<typeof updateBudgetPolicySchema>;

package/src/lib/validators/task.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { SUPPORTED_AGENT_RUNTIMES } from "@/lib/agents/runtime/catalog";
+
+const assignedAgentSchema = z.enum(SUPPORTED_AGENT_RUNTIMES);
+
+export const createTaskSchema = z.object({
+  title: z.string().min(1, "Title is required").max(200),
+  description: z.string().max(2000).optional(),
+  projectId: z.string().optional(),
+  priority: z.number().min(0).max(3).default(2),
+  assignedAgent: assignedAgentSchema.optional(),
+  agentProfile: z.string().optional(),
+  fileIds: z.array(z.string()).optional(),
+});
+
+export const updateTaskSchema = z.object({
+  title: z.string().min(1).max(200).optional(),
+  description: z.string().max(2000).optional(),
+  status: z
+    .enum(["planned", "queued", "running", "completed", "failed", "cancelled"])
+    .optional(),
+  priority: z.number().min(0).max(3).optional(),
+  assignedAgent: assignedAgentSchema.optional(),
+  agentProfile: z.string().optional(),
+  result: z.string().optional(),
+  sessionId: z.string().optional(),
+});
+
+export type CreateTaskInput = z.infer<typeof createTaskSchema>;
+export type UpdateTaskInput = z.infer<typeof updateTaskSchema>;

package/src/lib/workflows/blueprints/builtins/code-review-pipeline.yaml

@@ -0,0 +1,72 @@
+id: code-review-pipeline
+name: Code Review Pipeline
+description: Security scan, quality analysis, and summary report for code changes
+version: "1.0.0"
+domain: work
+tags: [code-review, security, quality, owasp]
+pattern: checkpoint
+estimatedDuration: "10-20 min"
+difficulty: intermediate
+author: stagent
+
+variables:
+  - id: target
+    type: text
+    label: Review Target
+    description: What to review — file path, PR number, or description of changes
+    required: true
+    placeholder: "e.g., src/lib/auth/ or PR #42"
+  - id: focus
+    type: select
+    label: Review Focus
+    description: Primary focus area for the review
+    required: true
+    default: balanced
+    options:
+      - { value: security, label: "Security-focused (OWASP, injection, auth)" }
+      - { value: quality, label: "Quality-focused (patterns, duplication, naming)" }
+      - { value: balanced, label: "Balanced (security + quality)" }
+  - id: context
+    type: textarea
+    label: Additional Context
+    description: Any relevant context about the changes being reviewed
+    required: false
+    placeholder: "e.g., This is a new authentication module..."
+
+steps:
+  - name: Security Scan
+    profileId: code-reviewer
+    promptTemplate: |
+      Perform a security-focused code review of: {{target}}
+
+      Focus: {{focus}}
+      {{#if context}}Context: {{context}}{{/if}}
+
+      Check for OWASP Top 10 vulnerabilities, injection flaws, authentication bypasses,
+      and sensitive data exposure. Report each finding with severity, location, and fix.
+    requiresApproval: true
+    expectedOutput: structured-findings
+
+  - name: Quality Analysis
+    profileId: code-reviewer
+    promptTemplate: |
+      Perform a code quality analysis of: {{target}}
+
+      Focus: {{focus}}
+      {{#if context}}Context: {{context}}{{/if}}
+
+      Check for code duplication, naming conventions, error handling patterns,
+      test coverage gaps, and performance issues. Report each finding with
+      severity (CRITICAL/WARNING/SUGGESTION), location, and recommended fix.
+    requiresApproval: false
+    expectedOutput: structured-findings
+
+  - name: Review Summary
+    profileId: document-writer
+    promptTemplate: |
+      Write a concise code review summary for: {{target}}
+
+      Synthesize the security scan and quality analysis findings from previous steps.
+      Structure as: Overview, Critical Issues, Warnings, Suggestions, Verdict (approve/request changes).
+    requiresApproval: true
+    expectedOutput: markdown-report

package/src/lib/workflows/blueprints/builtins/documentation-generation.yaml

@@ -0,0 +1,62 @@
+id: documentation-generation
+name: Documentation Generation
+description: Analyze code, draft documentation, and review for accuracy
+version: "1.0.0"
+domain: work
+tags: [documentation, api-docs, technical-writing, readme]
+pattern: sequence
+estimatedDuration: "10-15 min"
+difficulty: beginner
+author: stagent
+
+variables:
+  - id: target
+    type: text
+    label: Documentation Target
+    description: What to document — module path, API, or component
+    required: true
+    placeholder: "e.g., src/lib/agents/ or the REST API endpoints"
+  - id: docType
+    type: select
+    label: Documentation Type
+    description: What kind of documentation to produce
+    required: true
+    default: api-docs
+    options:
+      - { value: api-docs, label: "API Documentation" }
+      - { value: readme, label: "README" }
+      - { value: adr, label: "Architecture Decision Record" }
+      - { value: guide, label: "User Guide" }
+
+steps:
+  - name: Code Analysis
+    profileId: technical-writer
+    promptTemplate: |
+      Analyze the codebase at: {{target}}
+
+      Documentation type: {{docType}}
+
+      Map the public API surface, key abstractions, data flow, and usage patterns.
+      Identify what needs to be documented and the logical structure for the docs.
+    requiresApproval: false
+    expectedOutput: analysis-notes
+
+  - name: Draft Documentation
+    profileId: technical-writer
+    promptTemplate: |
+      Write {{docType}} documentation for: {{target}}
+
+      Use the code analysis from the previous step. Follow standard {{docType}} conventions.
+      Include code examples, parameter descriptions, return types, and edge cases.
+    requiresApproval: false
+    expectedOutput: markdown-report
+
+  - name: Technical Review
+    profileId: code-reviewer
+    promptTemplate: |
+      Review the drafted {{docType}} documentation for: {{target}}
+
+      Check for: technical accuracy, completeness, code example correctness,
+      missing edge cases, and clarity. Suggest specific improvements.
+    requiresApproval: true
+    expectedOutput: review-feedback

package/src/lib/workflows/blueprints/builtins/investment-research.yaml

@@ -0,0 +1,81 @@
+id: investment-research
+name: Investment Research
+description: Gather market data, analyze risk, and produce an investment report with disclaimers
+version: "1.0.0"
+domain: personal
+tags: [finance, investing, research, risk-assessment]
+pattern: checkpoint
+estimatedDuration: "15-30 min"
+difficulty: advanced
+author: stagent
+
+variables:
+  - id: asset
+    type: text
+    label: Asset or Topic
+    description: What to research — stock, sector, strategy, or investment question
+    required: true
+    placeholder: "e.g., NVIDIA stock, index fund vs. active management"
+  - id: horizon
+    type: select
+    label: Investment Horizon
+    description: Time frame for the investment
+    required: true
+    default: medium
+    options:
+      - { value: short, label: "Short-term (< 1 year)" }
+      - { value: medium, label: "Medium-term (1-5 years)" }
+      - { value: long, label: "Long-term (5+ years)" }
+  - id: riskTolerance
+    type: select
+    label: Risk Tolerance
+    description: Your risk comfort level
+    required: true
+    default: moderate
+    options:
+      - { value: conservative, label: "Conservative" }
+      - { value: moderate, label: "Moderate" }
+      - { value: aggressive, label: "Aggressive" }
+
+steps:
+  - name: Data Gathering
+    profileId: researcher
+    promptTemplate: |
+      Research the following investment topic: {{asset}}
+
+      Investment horizon: {{horizon}}
+      Risk tolerance: {{riskTolerance}}
+
+      Gather recent financial data, market trends, analyst opinions, and relevant
+      news. Focus on fundamentals, competitive position, and macro factors.
+    requiresApproval: false
+    expectedOutput: research-data
+
+  - name: Risk Analysis
+    profileId: wealth-manager
+    promptTemplate: |
+      Analyze the investment risks for: {{asset}}
+
+      Horizon: {{horizon}}
+      Risk tolerance: {{riskTolerance}}
+
+      Evaluate: market risk, liquidity risk, concentration risk, regulatory risk.
+      Provide risk-adjusted return expectations and portfolio fit assessment.
+      Include appropriate disclaimers about investment advice.
+    requiresApproval: true
+    expectedOutput: risk-report
+
+  - name: Investment Report
+    profileId: document-writer
+    promptTemplate: |
+      Write a comprehensive investment research report on: {{asset}}
+
+      Horizon: {{horizon}}, Risk tolerance: {{riskTolerance}}
+
+      Synthesize research and risk analysis from previous steps.
+      Structure: Executive Summary, Market Analysis, Risk Assessment,
+      Recommendation, Key Risks to Monitor.
+
+      IMPORTANT: Include standard disclaimers that this is not financial advice.
+    requiresApproval: true
+    expectedOutput: markdown-report