basic-block

apps/x/packages/core/src/agents/runtime.ts

@@ -11,6 +11,7 @@ import { execTool } from "../application/lib/exec-tool.js";
 import { AskHumanRequestEvent, RunEvent, ToolPermissionRequestEvent } from "@x/shared/dist/runs.js";
 import { BuiltinTools } from "../application/lib/builtin-tools.js";
 import { buildCopilotAgent } from "../application/assistant/agent.js";
+import { buildTrackRunAgent } from "../knowledge/track/run-agent.js";
 import { isBlocked, extractCommandNames } from "../application/lib/command-executor.js";
 import container from "../di/container.js";
 import { IModelConfigRepo } from "../models/repo.js";
@@ -372,6 +373,10 @@ export async function loadAgent(id: string): Promise<z.infer<typeof Agent>> {
         return buildCopilotAgent();
     }
 
+    if (id === "track-run") {
+        return buildTrackRunAgent();
+    }
+
     if (id === 'note_creation') {
         const raw = getNoteCreationRaw();
         let agent: z.infer<typeof Agent> = {

apps/x/packages/core/src/application/lib/builtin-tools.ts

@@ -25,6 +25,7 @@ import { isSignedIn } from "../../account/account.js";
 import { getGatewayProvider } from "../../models/gateway.js";
 import { getAccessToken } from "../../auth/tokens.js";
 import { API_URL } from "../../config/env.js";
+import { updateContent, updateTrackBlock } from "../../knowledge/track/fileops.js";
 // Parser libraries are loaded dynamically inside parseFile.execute()
 // to avoid pulling pdfjs-dist's DOM polyfills into the main bundle.
 // Import paths are computed so esbuild cannot statically resolve them.
@@ -1431,4 +1432,22 @@ export const BuiltinTools: z.infer<typeof BuiltinToolsSchema> = {
         },
         isAvailable: async () => isComposioConfigured(),
     },
+    'update-track-content': {
+        description: "Update the output content of a track block in a knowledge note. This replaces the content inside the track's target region (between <!--track-target:ID--> markers), or creates the target region if it doesn't exist. Also updates the track's lastRunAt timestamp.",
+        inputSchema: z.object({
+            filePath: z.string().describe("Workspace-relative path to the note file (e.g., 'knowledge/Notes/my-note.md')"),
+            trackId: z.string().describe("The track block's trackId"),
+            content: z.string().describe("The new content to place inside the track's target region"),
+        }),
+        execute: async ({ filePath, trackId, content }: { filePath: string; trackId: string; content: string }) => {
+            try {
+                await updateContent(filePath, trackId, content);
+                await updateTrackBlock(filePath, trackId, { lastRunAt: new Date().toISOString() });
+                return { success: true, message: `Updated track ${trackId} in ${filePath}` };
+            } catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { success: false, error: msg };
+            }
+        },
+    },
 };

apps/x/packages/core/src/knowledge/track/bus.ts

@@ -0,0 +1,23 @@
+import type { TrackEventType } from '@x/shared/dist/track-block.js';
+
+type Handler = (event: TrackEventType) => void;
+
+class TrackBus {
+    private subs: Handler[] = [];
+
+    publish(event: TrackEventType): void {
+        for (const handler of this.subs) {
+            handler(event);
+        }
+    }
+
+    subscribe(handler: Handler): () => void {
+        this.subs.push(handler);
+        return () => {
+            const idx = this.subs.indexOf(handler);
+            if (idx >= 0) this.subs.splice(idx, 1);
+        };
+    }
+}
+
+export const trackBus = new TrackBus();

apps/x/packages/core/src/knowledge/track/fileops.ts

@@ -0,0 +1,109 @@
+import z from 'zod';
+import fs from 'fs/promises';
+import path from 'path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { WorkDir } from '../../config/config.js';
+import { TrackBlockSchema } from '@x/shared/dist/track-block.js';
+import { TrackStateSchema } from './types.js';
+
+const KNOWLEDGE_DIR = path.join(WorkDir, 'knowledge');
+
+function absPath(filePath: string): string {
+    return path.join(KNOWLEDGE_DIR, filePath);
+}
+
+export async function fetchAll(filePath: string): Promise<z.infer<typeof TrackStateSchema>[]> {
+    let content: string;
+    try {
+        content = await fs.readFile(absPath(filePath), 'utf-8');
+    } catch {
+        return [];
+    }
+
+    const lines = content.split('\n');
+    const blocks: z.infer<typeof TrackStateSchema>[] = [];
+    let i = 0;
+    const contentFenceStartMatcher = /<!--track-target:(\w+)-->/;
+    const contentFenceEndMatcher = /<!--\/track-target:(\w+)-->/;
+    while (i < lines.length) {
+        if (lines[i].trim() === '```track') {
+            const fenceStart = i;
+            i++;
+            const blockLines: string[] = [];
+            while (i < lines.length && lines[i].trim() !== '```') {
+                blockLines.push(lines[i]);
+                i++;
+            }
+            try {
+                const data = parseYaml(blockLines.join('\n'));
+                const result = TrackBlockSchema.safeParse(data);
+                if (result.success) {
+                    blocks.push({ track: result.data, fenceStart, fenceEnd: i, content: '' });
+                }
+            } catch { /* skip */ }
+        } else if (contentFenceStartMatcher.test(lines[i])) {
+            const match = contentFenceStartMatcher.exec(lines[i]);
+            if (match) {
+                const trackId = match[1];
+                // have we already collected this track block?
+                const existingBlock = blocks.find(b => b.track.trackId === trackId);
+                if (!existingBlock) {
+                    i++;
+                    continue;
+                }
+                const contentStart = i + 1;
+                while (i < lines.length && !contentFenceEndMatcher.test(lines[i])) {
+                    i++;
+                }
+                const contentEnd = i;
+                existingBlock.content = lines.slice(contentStart, contentEnd).join('\n');
+            }
+        }
+        i++;
+    }
+    return blocks;
+}
+
+export async function fetch(filePath: string, trackId: string): Promise<z.infer<typeof TrackStateSchema> | null> {
+    const blocks = await fetchAll(filePath);
+    return blocks.find(b => b.track.trackId === trackId) ?? null;
+}
+
+export async function updateContent(filePath: string, trackId: string, newContent: string): Promise<void> {
+    let content = await fs.readFile(absPath(filePath), 'utf-8');
+    const openTag = `<!--track-target:${trackId}-->`;
+    const closeTag = `<!--/track-target:${trackId}-->`;
+    const openIdx = content.indexOf(openTag);
+    const closeIdx = content.indexOf(closeTag);
+    if (openIdx !== -1 && closeIdx !== -1 && closeIdx > openIdx) {
+        content = content.slice(0, openIdx + openTag.length) + '\n' + newContent + '\n' + content.slice(closeIdx);
+    } else {
+        const block = await fetch(filePath, trackId);
+        if (!block) {
+            throw new Error(`Track ${trackId} not found in ${filePath}`);
+        }
+        const lines = content.split('\n');
+        const insertAt = Math.min(block.fenceEnd + 1, lines.length);
+        const contentFence = [openTag, newContent, closeTag];
+        lines.splice(insertAt, 0, ...contentFence);
+        content = lines.join('\n');
+    }
+    await fs.writeFile(absPath(filePath), content, 'utf-8');
+}
+
+export async function updateTrackBlock(filepath: string, trackId: string, updates: Partial<z.infer<typeof TrackBlockSchema>>): Promise<void> {
+    const block = await fetch(filepath, trackId);
+    if (!block) {
+        throw new Error(`Track ${trackId} not found in ${filepath}`);
+    }
+    block.track = { ...block.track, ...updates };
+
+    // read file contents
+    let content = await fs.readFile(absPath(filepath), 'utf-8');
+    const lines = content.split('\n');
+    const yaml = stringifyYaml(block.track).trimEnd();
+    const yamlLines = yaml ? yaml.split('\n') : [];
+    lines.splice(block.fenceStart, block.fenceEnd - block.fenceStart + 1, '```track', ...yamlLines, '```');
+    content = lines.join('\n');
+    await fs.writeFile(absPath(filepath), content, 'utf-8');
+}

apps/x/packages/core/src/knowledge/track/run-agent.ts

@@ -0,0 +1,65 @@
+import z from 'zod';
+import { Agent, ToolAttachment } from '@x/shared/dist/agent.js';
+import { BuiltinTools } from '../../application/lib/builtin-tools.js';
+import { WorkDir } from '../../config/config.js';
+
+const TRACK_RUN_INSTRUCTIONS = `You are a track block runner — a background agent that updates a specific section of a knowledge note.
+
+You will receive a message containing a track instruction, the current content of the target region, and optionally some context. Your job is to follow the instruction and produce updated content.
+
+# Background Mode
+
+You are running as a background task — there is no user present.
+- Do NOT ask clarifying questions — make reasonable assumptions
+- Be concise and action-oriented — just do the work
+
+# The Knowledge Graph
+
+The knowledge graph is stored as plain markdown in \`${WorkDir}/knowledge/\` (inside the workspace). It's organized into:
+- **People/** — Notes on individuals
+- **Organizations/** — Notes on companies
+- **Projects/** — Notes on initiatives
+- **Topics/** — Notes on recurring themes
+
+Use workspace tools to search and read the knowledge graph for context.
+
+# How to Access the Knowledge Graph
+
+**CRITICAL:** Always include \`knowledge/\` in paths.
+- \`workspace-grep({ pattern: "Acme", path: "knowledge/" })\`
+- \`workspace-readFile("knowledge/People/Sarah Chen.md")\`
+- \`workspace-readdir("knowledge/People")\`
+
+**NEVER** use an empty path or root path.
+
+# How to Write Your Result
+
+Use the \`update-track-content\` tool to write your result. The message will tell you the file path and track ID.
+
+- Produce the COMPLETE replacement content (not a diff)
+- Preserve existing content that's still relevant
+- Write in a clear, concise style appropriate for personal notes
+
+# Web Search
+
+You have access to \`web-search\` for tracks that need external information (news, trends, current events). Use it when the track instruction requires information beyond the knowledge graph.
+
+# After You're Done
+
+End your response with a brief summary of what you did (1-2 sentences).
+`;
+
+export function buildTrackRunAgent(): z.infer<typeof Agent> {
+    const tools: Record<string, z.infer<typeof ToolAttachment>> = {};
+    for (const name of Object.keys(BuiltinTools)) {
+        if (name === 'executeCommand') continue;
+        tools[name] = { type: 'builtin', name };
+    }
+
+    return {
+        name: 'track-run',
+        description: 'Background agent that updates track block content',
+        instructions: TRACK_RUN_INSTRUCTIONS,
+        tools,
+    };
+}

apps/x/packages/core/src/knowledge/track/runner.ts

@@ -0,0 +1,122 @@
+import z from 'zod';
+import { fetchAll, updateTrackBlock } from './fileops.js';
+import { createRun, createMessage } from '../../runs/runs.js';
+import { extractAgentResponse, waitForRunCompletion } from '../../agents/utils.js';
+import { trackBus } from './bus.js';
+import type { TrackStateSchema } from './types.js';
+
+export interface TrackUpdateResult {
+    trackId: string;
+    action: 'replace' | 'no_update';
+    contentBefore: string | null;
+    contentAfter: string | null;
+    summary: string | null;
+    error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Agent run
+// ---------------------------------------------------------------------------
+
+function buildMessage(filePath: string, track: z.infer<typeof TrackStateSchema>, context?: string): string {
+    const now = new Date();
+    const localNow = now.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long' });
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+
+    let msg = `Update track **${track.track.trackId}** in \`${filePath}\`.
+
+**Time:** ${localNow} (${tz})
+
+**Instruction:**
+${track.track.instruction}
+
+**Current content:**
+${track.content || '(empty — first run)'}
+
+Use \`update-track-content\` with filePath=\`${filePath}\` and trackId=\`${track.track.trackId}\`.`;
+
+    if (context) {
+        msg += `\n\n**Context:**\n${context}`;
+    }
+
+    return msg;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Trigger an update for a specific track block.
+ * Can be called by any trigger system (manual, cron, event matching).
+ */
+export async function triggerTrackUpdate(
+    trackId: string,
+    filePath: string,
+    context?: string,
+): Promise<TrackUpdateResult> {
+    console.log('triggerTrackUpdate', trackId, filePath, context);
+    const tracks = await fetchAll(filePath);
+    const track = tracks.find(t => t.track.trackId === trackId);
+    if (!track) {
+        return { trackId, action: 'no_update', contentBefore: null, contentAfter: null, summary: null, error: 'Track not found' };
+    }
+
+    const contentBefore = track.content;
+
+    // Emit start event — runId is set after agent run is created
+    const agentRun = await createRun({ agentId: 'track-run' });
+
+    await trackBus.publish({
+        type: 'track_run_start',
+        trackId,
+        filePath,
+        trigger: 'manual',
+        runId: agentRun.id,
+    });
+
+    try {
+        await createMessage(agentRun.id, buildMessage(filePath, track, context));
+        await waitForRunCompletion(agentRun.id);
+        const summary = await extractAgentResponse(agentRun.id);
+
+        const updatedTracks = await fetchAll(filePath);
+        const contentAfter = updatedTracks.find(t => t.track.trackId === trackId)?.content;
+        const didUpdate = contentAfter !== contentBefore;
+
+        // Update track block metadata
+        await updateTrackBlock(filePath, trackId, {
+            lastRunAt: new Date().toISOString(),
+            lastRunId: agentRun.id,
+            lastRunSummary: summary ?? undefined,
+        });
+
+        await trackBus.publish({
+            type: 'track_run_complete',
+            trackId,
+            filePath,
+            runId: agentRun.id,
+            summary: summary ?? undefined,
+        });
+
+        return {
+            trackId,
+            action: didUpdate ? 'replace' : 'no_update',
+            contentBefore: contentBefore ?? null,
+            contentAfter: contentAfter ?? null,
+            summary,
+        };
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+
+        await trackBus.publish({
+            type: 'track_run_complete',
+            trackId,
+            filePath,
+            runId: agentRun.id,
+            error: msg,
+        });
+
+        return { trackId, action: 'no_update', contentBefore: contentBefore ?? null, contentAfter: null, summary: null, error: msg };
+    }
+}

apps/x/packages/core/src/knowledge/track/types.ts

@@ -0,0 +1,9 @@
+import z from "zod";
+import { TrackBlockSchema } from "@x/shared/dist/track-block.js";
+
+export const TrackStateSchema = z.object({
+    track: TrackBlockSchema,
+    fenceStart: z.number(),
+    fenceEnd: z.number(),
+    content: z.string(),
+});

apps/x/packages/shared/src/index.ts

@@ -9,6 +9,7 @@ export * as agentScheduleState from './agent-schedule-state.js';
 export * as serviceEvents from './service-events.js'
 export * as inlineTask from './inline-task.js';
 export * as blocks from './blocks.js';
+export * as trackBlock from './track-block.js';
 export * as frontmatter from './frontmatter.js';
 export * as bases from './bases.js';
 export { PrefixLogger };

apps/x/packages/shared/src/ipc.ts

@@ -6,6 +6,7 @@ import { LlmModelConfig } from './models.js';
 import { AgentScheduleConfig, AgentScheduleEntry } from './agent-schedule.js';
 import { AgentScheduleState } from './agent-schedule-state.js';
 import { ServiceEvent } from './service-events.js';
+import { TrackEvent } from './track-block.js';
 import { UserMessageContent } from './message.js';
 import { RowboatApiConfig } from './rowboat-account.js';
 import { ZListToolkitsResponse } from './composio.js';
@@ -193,6 +194,10 @@ const ipcSchemas = {
     req: ServiceEvent,
     res: z.null(),
   },
+  'tracks:events': {
+    req: TrackEvent,
+    res: z.null(),
+  },
   'models:list': {
     req: z.null(),
     res: z.object({
@@ -560,6 +565,18 @@ const ipcSchemas = {
       response: z.string().nullable(),
     }),
   },
+  // Track channels
+  'track:run': {
+    req: z.object({
+      trackId: z.string(),
+      filePath: z.string(),
+    }),
+    res: z.object({
+      success: z.boolean(),
+      summary: z.string().optional(),
+      error: z.string().optional(),
+    }),
+  },
   // Billing channels
   'billing:getInfo': {
     req: z.null(),

apps/x/packages/shared/src/track-block.ts

@@ -0,0 +1,35 @@
+import z from 'zod';
+
+export const TrackBlockSchema = z.object({
+    trackId: z.string(),
+    instruction: z.string(),
+    matchCriteria: z.string().optional(),
+    active: z.boolean().default(true),
+    lastRunAt: z.string().optional(),
+    lastRunId: z.string().optional(),
+    lastRunSummary: z.string().optional(),
+});
+
+// Track bus events
+export const TrackRunStartEvent = z.object({
+    type: z.literal('track_run_start'),
+    trackId: z.string(),
+    filePath: z.string(),
+    trigger: z.enum(['timed', 'manual', 'event']),
+    runId: z.string(),
+});
+
+export const TrackRunCompleteEvent = z.object({
+    type: z.literal('track_run_complete'),
+    trackId: z.string(),
+    filePath: z.string(),
+    runId: z.string(),
+    error: z.string().optional(),
+    summary: z.string().optional(),
+});
+
+export const TrackEvent = z.union([TrackRunStartEvent, TrackRunCompleteEvent]);
+
+export type TrackBlock = z.infer<typeof TrackBlockSchema>;
+export type TrackResult = z.infer<typeof TrackResultSchema>;
+export type TrackEventType = z.infer<typeof TrackEvent>;