@mndrk/agx 2.0.0-next.8 → 2.0.0

package/cloud-runtime/standalone/Projects/Agents/agx-cloud/lib/storage/thread-adapter.ts

@@ -1,33 +1,33 @@
 import type { GroupMessage } from "../types";
 
 /**
- * Arbitrary metadata that can be stored alongside a thread for sorting/filtering.
+ * Arbitrary metadata that can be stored alongside a workspace for sorting/filtering.
  */
-export type ThreadMetadata = Record<string, unknown>;
+export type WorkspaceMetadata = Record<string, unknown>;
 
 /**
- * The canonical representation of a conversation thread in agx-chat.
+ * The canonical representation of a workspace in agx-chat.
  */
-export interface Thread {
-  /** Unique identifier for the thread. */
+export interface Workspace {
+  /** Unique identifier for the workspace. */
   id: string;
   /** Human-friendly title (optional). */
   title?: string;
-  /** Ordered messages that belong to the thread. */
+  /** Ordered messages that belong to the workspace. */
   messages: GroupMessage[];
-  /** Denotes when the thread was created (epoch ms). */
+  /** Denotes when the workspace was created (epoch ms). */
   createdAt: number;
-  /** Denotes the last time the thread was updated (epoch ms). */
+  /** Denotes the last time the workspace was updated (epoch ms). */
   updatedAt: number;
   /** Optional metadata bucket adapters can use for sorting/filtering. */
-  metadata?: ThreadMetadata;
+  metadata?: WorkspaceMetadata;
 }
 
 /**
- * Input data that is required when creating or updating a thread.
+ * Input data that is required when creating or updating a workspace.
  * Adapters may enrich this input with timestamps or derived metadata before persistence.
  */
-export interface SaveThreadInput extends Omit<Thread, "createdAt" | "updatedAt"> {
+export interface SaveWorkspaceInput extends Omit<Workspace, "createdAt" | "updatedAt"> {
   /** Allow callers to override the created timestamp when reconstructing archives. */
   createdAt?: number;
   /** Allow callers to override the updated timestamp when reconstructing archives. */
@@ -35,48 +35,48 @@ export interface SaveThreadInput extends Omit<Thread, "createdAt" | "updatedAt">
 }
 
 /**
- * Pagination and sort hints that adapters should honor when listing threads.
+ * Pagination and sort hints that adapters should honor when listing workspaces.
  */
-export interface ThreadListOptions {
-  /** Maximum number of threads to return. Defaults to all available threads. */
+export interface WorkspaceListOptions {
+  /** Maximum number of workspaces to return. Defaults to all available workspaces. */
   limit?: number;
-  /** Number of threads to skip before collecting results (offset-style cursor). */
+  /** Number of workspaces to skip before collecting results (offset-style cursor). */
   offset?: number;
-  /** Sort order for the threads based on `updatedAt`. Defaults to "desc" (newest first). */
+  /** Sort order for the workspaces based on `updatedAt`. Defaults to "desc" (newest first). */
   order?: "asc" | "desc";
 }
 
 /**
- * Result payload for `listThreads` that includes the requested subset and the total size.
+ * Result payload for `listWorkspaces` that includes the requested subset and the total size.
  */
-export interface ListThreadsResult {
-  /** Threads for the current page. */
-  threads: Thread[];
-  /** Total number of available threads (before paging). */
+export interface ListWorkspacesResult {
+  /** Workspaces for the current page. */
+  workspaces: Workspace[];
+  /** Total number of available workspaces (before paging). */
   total: number;
 }
 
 /**
- * Abstraction over storage mechanisms that persist conversation threads.
+ * Abstraction over storage mechanisms that persist workspaces.
  */
-export interface ThreadAdapter {
+export interface WorkspaceAdapter {
   /**
-   * Persist a thread. Implementations should update timestamps and return the stored result.
+   * Persist a workspace. Implementations should update timestamps and return the stored result.
    */
-  saveThread(input: SaveThreadInput): Promise<Thread>;
+  saveWorkspace(input: SaveWorkspaceInput): Promise<Workspace>;
 
   /**
-   * Load a thread by its `id`. Return `null` when the thread does not exist.
+   * Load a workspace by its `id`. Return `null` when the workspace does not exist.
    */
-  loadThread(threadId: string): Promise<Thread | null>;
+  loadWorkspace(workspaceId: string): Promise<Workspace | null>;
 
   /**
-   * List persisted threads with optional pagination/sorting hints.
+   * List persisted workspaces with optional pagination/sorting hints.
    */
-  listThreads(options?: ThreadListOptions): Promise<ListThreadsResult>;
+  listWorkspaces(options?: WorkspaceListOptions): Promise<ListWorkspacesResult>;
 
   /**
-   * Remove a persisted thread. The method should be idempotent.
+   * Remove a persisted workspace. The method should be idempotent.
    */
-  deleteThread(threadId: string): Promise<void>;
+  deleteWorkspace(workspaceId: string): Promise<void>;
 }

package/cloud-runtime/standalone/Projects/Agents/agx-cloud/lib/stream-multiplexer.ts

@@ -323,7 +323,8 @@ function buildContext(
   transcript: Array<{ name: string; content: string }>,
   recentHistory: Array<{ id: string; name: string; content: string }>,
   exchangeMessages: Array<{ id: string; name: string; content: string }>,
-  currentUserMessageId: string | null
+  currentUserMessageId: string | null,
+  invitedBy: string | null
 ): string {
   const otherActive = active.filter((p) => p.id !== self.id);
   const otherNames = otherActive.map((p) => p.name).join(", ");
@@ -337,6 +338,9 @@ You are "${self.name}" in a group chat. All agents: ${allNames}.`;
   if (otherNames) {
     context += ` Currently active in this exchange: ${otherNames}.`;
   }
+  if (invitedBy) {
+    context += `\nYou were invited into this conversation by ${invitedBy}. The user's message was directed at ${invitedBy}, not at you. Your job is to contribute your own perspective, feedback, or expertise — not to re-ask others to do the same thing.`;
+  }
   context += `
 Respond as ${self.name} only. Keep responses conversational and concise.
 IMPORTANT: Always respond to the user's actual question. Do not reference unrelated technical context, previous threads, or system internals unless directly asked.
@@ -349,6 +353,8 @@ Mentions:
 - To run agents in parallel, use @@ (double-at): @@${exampleName} — e.g. "@@Alice @@Bob" runs both concurrently.
 - You only get another turn if someone @mentions you. If you need to continue working (e.g. writing code), @mention yourself: @${self.name}.
 - If your work is complete, do NOT @mention yourself — just deliver your final response.
+- NEVER just forward or re-delegate a request. If someone asks you to review, give your actual review. If asked to help, do the work. Simply @mentioning others to do what you were asked to do is not a valid response.
+- Only @mention others when you genuinely need their specific input on something new — not to pass along the same request you received.
 
 Reactions (machine-readable status channel):
 - Emit status with tags: [reaction target=<messageId> type=ack|working|done|clarify|blocked reason="..." blockerCode=<optional>]
@@ -412,7 +418,8 @@ async function runAgent(
   currentUserMessageId: string | null,
   signal: AbortSignal | undefined,
   write: (event: ChatEvent) => void,
-  rootMessageId?: string | null
+  rootMessageId?: string | null,
+  invitedBy?: string | null
 ): Promise<{
   skipped: boolean;
   response: string;
@@ -444,13 +451,19 @@ async function runAgent(
     selfContent = `[Self — who you've become through experience]\n${agentSelf.content}`;
   }
 
-  // Resolve skills: read each file and concatenate
+  // Resolve skills: read each file and concatenate with conditions
   let skillsContent: string | undefined;
   if (p.skills && p.skills.length > 0) {
     const parts = await Promise.all(
-      p.skills.map(async (reference) => {
+      p.skills.map(async (skill) => {
+        // Support both new {file,condition} format and legacy string format
+        const reference = typeof skill === "string" ? skill : skill.file;
+        const condition = typeof skill === "string" ? "" : skill.condition;
         const resolved = await readReferenceContent(reference);
-        return `--- ${resolved.label} ---\n${resolved.content}`;
+        const header = condition
+          ? `--- ${resolved.label} ---\nUse when: ${condition}`
+          : `--- ${resolved.label} ---`;
+        return `${header}\n${resolved.content}`;
       })
     );
     skillsContent = `[Skills]\n${parts.join("\n\n")}`;
@@ -464,7 +477,8 @@ async function runAgent(
     transcript,
     recentHistory,
     exchangeMessages,
-    currentUserMessageId
+    currentUserMessageId,
+    invitedBy ?? null
   );
   write({
     type: "log",
@@ -707,6 +721,8 @@ export function createMultiplexedStream({
 
       const transcript: Array<{ name: string; content: string }> = [];
       const exchangeMessages: Array<{ id: string; name: string; content: string }> = [];
+      // Track who invited each agent so they know their role (contributor vs. lead)
+      const invitedByMap = new Map<string, string>();
       // Prior messages for dedup — includes recent DB history so we catch
       // repetitions across separate user sends, not just within one exchange
       const priorMessages: Array<{ name: string; content: string }> = recentHistory
@@ -761,7 +777,8 @@ export function createMultiplexedStream({
                 currentUserMessageId || null,
                 signal,
                 write,
-                rootMessageId
+                rootMessageId,
+                invitedByMap.get(agent.id) || null
               );
               return { agent, result };
             });
@@ -792,6 +809,10 @@ export function createMultiplexedStream({
               }
 
               for (const id of result.mentions) {
+                if (id === agent.id) continue;
+                if (!invitedByMap.has(id)) {
+                  invitedByMap.set(id, agent.name);
+                }
                 activeIds.add(id);
                 const mentionedIdx = activeList.findIndex((a) => a.id === id);
                 const isPendingInThisRound =
@@ -824,7 +845,8 @@ export function createMultiplexedStream({
             currentUserMessageId || null,
             signal,
             write,
-            rootMessageId
+            rootMessageId,
+            invitedByMap.get(p.id) || null
           );
 
           if (result.skipped) continue;
@@ -853,6 +875,14 @@ export function createMultiplexedStream({
 
           // Mark mentioned agents as addressed for next round
           for (const id of result.mentions) {
+            // Skip self-mentions — agents shouldn't invite themselves
+            if (id === p.id) continue;
+
+            // Track who invited this agent (first inviter wins)
+            if (!invitedByMap.has(id)) {
+              invitedByMap.set(id, p.name);
+            }
+
             // Optimization: if the mentioned agent is yet to run in THIS round (and is addressed),
             // they will see this message and respond immediately. No need to queue them for next round.
             const mentionedIdx = activeList.findIndex((a) => a.id === id);
@@ -868,6 +898,7 @@ export function createMultiplexedStream({
           // Collect newly invited agents
           const newlyInvited = new Set<string>();
           for (const id of result.mentions) {
+            if (id === p.id) continue; // ignore self-mentions
             if (!activeIds.has(id)) {
               activeIds.add(id);
               newlyInvited.add(id);
@@ -893,7 +924,8 @@ export function createMultiplexedStream({
                 currentUserMessageId || null,
                 signal,
                 write,
-                rootMessageId
+                rootMessageId,
+                invitedByMap.get(a.id) || null
               );
               return { agent: a, result: r };
             });
@@ -917,6 +949,10 @@ export function createMultiplexedStream({
                 transcript.push({ name: agent.name, content: r.response });
               }
               for (const id of r.mentions) {
+                if (id === agent.id) continue;
+                if (!invitedByMap.has(id)) {
+                  invitedByMap.set(id, agent.name);
+                }
                 activeIds.add(id);
                 addressedNextRound.add(id);
               }

package/cloud-runtime/standalone/Projects/Agents/agx-cloud/lib/types.ts

@@ -15,9 +15,15 @@ export interface Participant {
   color: string;
   identity?: string;
   identityFile?: string;
-  skills?: string[];
+  skills?: Skill[];
 }
 
+export interface Skill {
+  file: string;
+  condition: string;
+}
+
+
 export type ReactionType = "ack" | "working" | "done" | "clarify" | "blocked";
 
 export interface MessageReaction {

package/cloud-runtime/standalone/Projects/Agents/agx-cloud/migrations/sqlite_schema.sql

@@ -480,3 +480,48 @@ CREATE TRIGGER IF NOT EXISTS execution_graphs_auto_update
             graph_version = OLD.graph_version + 1
         WHERE rowid = NEW.rowid;
     END;
+
+-- ---------------------------------------------------------------------------
+-- Notifications read-model (projector output)
+-- ---------------------------------------------------------------------------
+
+CREATE TABLE IF NOT EXISTS notifications (
+    id          TEXT NOT NULL PRIMARY KEY DEFAULT (lower(hex(randomblob(4)) || '-' || hex(randomblob(2)) || '-4' || substr(hex(randomblob(2)),2) || '-' || substr('89ab',abs(random()) % 4 + 1, 1) || substr(hex(randomblob(2)),2) || '-' || hex(randomblob(6)))),
+    user_id     TEXT NOT NULL,
+    task_id     TEXT NOT NULL,
+    event_id    TEXT NOT NULL,
+    type        TEXT NOT NULL,
+    tier        TEXT NOT NULL DEFAULT 'info' CHECK(tier IN ('info', 'warning', 'error', 'success')),
+    title       TEXT NOT NULL,
+    body        TEXT,
+    created_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    read_at     TEXT,
+    UNIQUE (event_id, user_id, type)
+);
+
+CREATE INDEX IF NOT EXISTS idx_notifications_user_unread ON notifications(user_id, read_at);
+CREATE INDEX IF NOT EXISTS idx_notifications_task ON notifications(task_id);
+
+-- ---------------------------------------------------------------------------
+-- Notification outbox
+-- ---------------------------------------------------------------------------
+
+CREATE TABLE IF NOT EXISTS notification_outbox (
+    id              TEXT NOT NULL PRIMARY KEY DEFAULT (lower(hex(randomblob(4)) || '-' || hex(randomblob(2)) || '-4' || substr(hex(randomblob(2)),2) || '-' || substr('89ab',abs(random()) % 4 + 1, 1) || substr(hex(randomblob(2)),2) || '-' || hex(randomblob(6)))),
+    notification_id TEXT NOT NULL REFERENCES notifications(id) ON DELETE CASCADE,
+    payload         JSON NOT NULL CHECK(json_valid(payload)),
+    created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    delivered_at    TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_notification_outbox_pending ON notification_outbox(delivered_at, created_at);
+
+-- ---------------------------------------------------------------------------
+-- Projector checkpoint cursors
+-- ---------------------------------------------------------------------------
+
+CREATE TABLE IF NOT EXISTS projector_cursors (
+    consumer_id     TEXT NOT NULL PRIMARY KEY,
+    last_event_id   TEXT NOT NULL,
+    updated_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+);

package/cloud-runtime/standalone/Projects/Agents/agx-cloud/script.txt

@@ -0,0 +1,111 @@
+AGX — THINK FIRST, BUILD FAST
+==============================
+
+PART 1: THE PROBLEM
+-------------------
+
+When I want to build something, I usually start by brainstorming ideas, then come up with a plan, before writing any code.
+
+To refine the idea into plan before execution I used to jump between:
+ - different models Claude, GPT
+ - and tools: claude code, codex, cursor, antigravity
+
+Now, all of that happens in one place.
+
+PART 2: WHAT CHANGED
+---------------------
+
+Let's say I want to add a notification system to AGX.
+
+Let's start with something vague:
+
+  "Add a notification system to AGX."
+
+
+
+
+PART 3: HOW IT WORKS — A LIVE EXAMPLE
+--------------------------------------
+
+Let me show you what this looks like in practice.
+
+Say I want to add a notification system to AGX. I'll start with something
+intentionally vague:
+
+  "Add a notification system to AGX."
+
+I keep it vague on purpose. I don't want to jump to implementation. I want
+my agents to help me figure out what I actually want.
+
+[DEMO: Type the vague prompt into AGX chat]
+
+The agents don't just start coding. They start asking questions:
+
+  — What types of notifications? Errors? Status updates? Mentions?
+  — In-app? Email? Both?
+  — Real-time push, or periodic digests?
+  — Per-user preferences, or system-wide defaults?
+  — Event-driven, or polling?
+
+This is the diverge phase. We're expanding the problem space, not narrowing
+it. I'm not answering a spec — I'm discovering what I care about.
+
+[DEMO: Show the back-and-forth conversation in AGX]
+
+And here's the key: some of the best questions are ones I wouldn't have
+thought to ask myself. The agents surface tradeoffs I hadn't considered.
+They make me think harder.
+
+Through this conversation, I start to see the shape of what I actually want:
+
+  — Event-driven architecture
+  — Multiple notification channels
+  — Users control their own frequency and preferences
+  — Start with in-app, design for email later
+
+We diverged first. Explored. Now we converge on a clear direction.
+
+[DEMO: Show the refined plan that emerges from the conversation]
+
+
+PART 4: FROM PLAN TO EXECUTION
+-------------------------------
+
+Now — and only now — do we start building.
+
+But the transition is seamless. The agents already have full context from
+the thinking phase. There's no handoff. No "let me re-explain what I want
+to a different tool." The same environment that helped me think now helps
+me build.
+
+[DEMO: Show AGX generating tasks from the plan]
+
+The plan becomes tasks. The tasks become code. The code gets tested. All
+in the same place, with the same context, by the same agents who helped me
+think through the design.
+
+[DEMO: Show code being generated and tested]
+
+
+PART 5: WHY THIS MATTERS
+--------------------------
+
+The old way:
+
+  Idea → Tool A → Tool B → Tool C → Tool D → Maybe the right thing
+
+The AGX way:
+
+  Vague idea → Thinking → Clear plan → Execution → The right thing
+
+The difference isn't speed. It's accuracy. When you think clearly first,
+you build the right thing the first time. You don't waste cycles building
+something, realizing it's wrong, and starting over.
+
+AGX doesn't just make me faster. It makes me more intentional.
+
+I don't start by coding. I start by thinking.
+And AGX makes sure the thinking is as rigorous as the code.
+
+
+=== END ===

package/cloud-runtime/standalone/Projects/Agents/agx-cloud/services/threadService.ts

@@ -1,21 +1,21 @@
-import { LocalThreadAdapter } from "@/lib/storage";
-import type { SaveThreadInput, Thread } from "@/lib/storage";
+import { LocalWorkspaceAdapter } from "@/lib/storage";
+import type { SaveWorkspaceInput, Workspace } from "@/lib/storage";
 import type { GroupMessage } from "@/lib/types";
 
-const adapter = new LocalThreadAdapter();
+const adapter = new LocalWorkspaceAdapter();
 
-const createThreadId = (): string => {
+const createWorkspaceId = (): string => {
   if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
     return crypto.randomUUID();
   }
-  return `thread-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  return `workspace-${Date.now()}-${Math.random().toString(16).slice(2)}`;
 };
 
-const sortByUpdatedAt = (threads: Thread[]) =>
-  [...threads].sort((a, b) => b.updatedAt - a.updatedAt);
+const sortByUpdatedAt = (workspaces: Workspace[]) =>
+  [...workspaces].sort((a, b) => b.updatedAt - a.updatedAt);
 
-function isArchivedThread(thread: Thread): boolean {
-  const archived = (thread.metadata as { archived?: unknown } | undefined)?.archived;
+function isArchivedWorkspace(workspace: Workspace): boolean {
+  const archived = (workspace.metadata as { archived?: unknown } | undefined)?.archived;
   return archived === true;
 }
 
@@ -44,19 +44,19 @@ function areMessagesEqual(a: GroupMessage[], b: GroupMessage[]): boolean {
   return true;
 }
 
-export const threadService = {
-  async listThreads(): Promise<Thread[]> {
-    const result = await adapter.listThreads({ order: "desc" });
-    return sortByUpdatedAt(result.threads.filter((thread) => !isArchivedThread(thread)));
+export const workspaceService = {
+  async listWorkspaces(): Promise<Workspace[]> {
+    const result = await adapter.listWorkspaces({ order: "desc" });
+    return sortByUpdatedAt(result.workspaces.filter((workspace) => !isArchivedWorkspace(workspace)));
   },
 
-  async createThread(
-    input?: Partial<Pick<SaveThreadInput, "id" | "title" | "messages" | "metadata">>
-  ): Promise<Thread> {
+  async createWorkspace(
+    input?: Partial<Pick<SaveWorkspaceInput, "id" | "title" | "messages" | "metadata">>
+  ): Promise<Workspace> {
     const requestedId = typeof input?.id === "string" ? input.id.trim() : "";
 
     if (requestedId) {
-      const existing = await adapter.loadThread(requestedId);
+      const existing = await adapter.loadWorkspace(requestedId);
       if (existing) {
         const metadata = {
           ...(existing.metadata ?? {}),
@@ -64,7 +64,7 @@ export const threadService = {
           archived: false,
           archivedAt: null,
         };
-        return adapter.saveThread({
+        return adapter.saveWorkspace({
           id: existing.id,
           title: input?.title ?? existing.title,
           messages: input?.messages?.length ? input.messages : existing.messages,
@@ -74,20 +74,20 @@ export const threadService = {
       }
     }
 
-    const payload: SaveThreadInput = {
-      id: requestedId || createThreadId(),
+    const payload: SaveWorkspaceInput = {
+      id: requestedId || createWorkspaceId(),
       messages: input?.messages?.length ? input.messages : [],
       title: input?.title,
       metadata: input?.metadata,
     };
-    return adapter.saveThread(payload);
+    return adapter.saveWorkspace(payload);
   },
 
-  async deleteThread(threadId: string) {
-    const id = threadId.trim();
+  async deleteWorkspace(workspaceId: string) {
+    const id = workspaceId.trim();
     if (!id) return;
 
-    const existing = await adapter.loadThread(id);
+    const existing = await adapter.loadWorkspace(id);
     if (!existing) return;
 
     const metadata = {
@@ -96,7 +96,7 @@ export const threadService = {
       archivedAt: Date.now(),
     };
 
-    await adapter.saveThread({
+    await adapter.saveWorkspace({
       id: existing.id,
       title: existing.title,
       messages: existing.messages,
@@ -105,19 +105,19 @@ export const threadService = {
     });
   },
 
-  async renameThread(threadId: string, title: string) {
-    const id = threadId.trim();
+  async renameWorkspace(workspaceId: string, title: string) {
+    const id = workspaceId.trim();
     const nextTitle = title.trim();
     if (!id || !nextTitle) return null;
 
-    const existing = await adapter.loadThread(id);
+    const existing = await adapter.loadWorkspace(id);
     if (!existing) return null;
 
     if ((existing.title?.trim() ?? "") === nextTitle) {
       return existing;
     }
 
-    return adapter.saveThread({
+    return adapter.saveWorkspace({
       id: existing.id,
       title: nextTitle,
       messages: existing.messages,
@@ -126,8 +126,8 @@ export const threadService = {
     });
   },
 
-  async saveThreadMessages(threadId: string, messages: GroupMessage[]): Promise<Thread | null> {
-    const existing = await adapter.loadThread(threadId);
+  async saveWorkspaceMessages(workspaceId: string, messages: GroupMessage[]): Promise<Workspace | null> {
+    const existing = await adapter.loadWorkspace(workspaceId);
     if (!existing) return null;
 
     const title = existing.title?.trim() || deriveTitleFromMessages(messages);
@@ -135,7 +135,7 @@ export const threadService = {
       return existing;
     }
 
-    return adapter.saveThread({
+    return adapter.saveWorkspace({
       id: existing.id,
       title,
       messages,