@electric-ax/agents 0.4.18 → 0.4.19

package/dist/entrypoint.js

@@ -5,7 +5,7 @@ import fs from "node:fs";
 import pino from "pino";
 import { fileURLToPath } from "node:url";
 import { GOAL_SLASH_COMMAND, MOONSHOT_API_BASE_URL, MOONSHOT_PROVIDER, appendPathToUrl, buildSkillSlashCommands, commentsCollection, completeWithLowCostModel, createContextSkillLoader, createEntityRegistry, createPullWakeRunner, createRuntimeHandler, createSkillsRegistry, db, detectAvailableProviders, dispatchGoalCommand, formatTokenCount, getMoonshotApiKey, getMoonshotModel, getMoonshotModels, isGoalCommandText, parseGoalCommand, pgSync, readCodexAccessToken, registerToolProvider, unregisterToolProvider } from "@electric-ax/agents-runtime";
-import { braveSearchTool, createBashTool, createEditTool, createEventSourceTools, createFetchUrlTool, createMarkGoalCompleteTool, createReadFileTool, createScheduleTools, createSendTool, createWriteTool } from "@electric-ax/agents-runtime/tools";
+import { braveSearchTool, createBashTool, createEditTool, createFetchUrlTool, createMarkGoalCompleteTool, createReadFileTool, createScheduleTools, createSendTool, createWebhookSourceTools, createWriteTool } from "@electric-ax/agents-runtime/tools";
 import { chooseDefaultSandbox, isE2BAvailable, lazySandbox, remoteSandbox } from "@electric-ax/agents-runtime/sandbox";
 import { z } from "zod";
 import { createHash } from "node:crypto";
@@ -814,7 +814,7 @@ function createSpawnWorkerTool(ctx, modelConfig) {
 
 //#endregion
 //#region src/tools/observe-pg-sync.ts
-function asToolResult(value) {
+function asToolResult$1(value) {
 	return {
 		content: [{
 			type: `text`,
@@ -832,9 +832,9 @@ function createObservePgSyncTool(ctx) {
 	return {
 		name: `observe_pg_sync`,
 		label: `Observe Postgres Sync`,
-		description: `Observe an Electric Postgres shape stream and wake this agent when matching row changes arrive.`,
+		description: `Observe an Electric Postgres shape stream and wake this agent when matching row changes arrive. Requires the HTTP(S) URL of an Electric shape endpoint — ask the user for it if you don't know it. Registration validates the endpoint up front and fails with Electric's error if the shape can't be fetched.`,
 		parameters: Type.Object({
-			url: Type.Optional(Type.String({ description: `Optional Electric shape endpoint URL. Defaults to the server-configured pg-sync URL.` })),
+			url: Type.String({ description: `HTTP(S) URL of the Electric shape endpoint, e.g. http://localhost:3000/v1/shape. Not a postgres:// connection string. Never guess this — ask the user if it hasn't been provided.` }),
 			table: Type.String({
 				minLength: 1,
 				pattern: `\\S`,
@@ -851,6 +851,7 @@ function createObservePgSyncTool(ctx) {
 		}),
 		execute: async (_toolCallId, params) => {
 			const args = params;
+			if (typeof args.url !== `string` || args.url.trim().length === 0) throw new Error(`url is required`);
 			if (typeof args.table !== `string` || args.table.trim().length === 0) throw new Error(`table is required`);
 			const source = pgSync({
 				url: args.url,
@@ -865,16 +866,79 @@ function createObservePgSyncTool(ctx) {
 				...args.wake?.ops ? { ops: args.wake.ops } : {},
 				...args.wake?.debounceMs !== void 0 ? { debounceMs: args.wake.debounceMs } : {}
 			};
-			await ctx.observe(source, { wake });
-			return asToolResult({
-				sourceRef: source.sourceRef,
-				streamUrl: source.streamUrl,
+			const handle = await ctx.observe(source, { wake });
+			if (!handle.streamUrl) throw new Error(`pg-sync observation did not return a stream URL for ${handle.sourceRef}`);
+			return asToolResult$1({
+				sourceRef: handle.sourceRef,
+				streamUrl: handle.streamUrl,
 				wake
 			});
 		}
 	};
 }
 
+//#endregion
+//#region src/tools/unobserve-pg-sync.ts
+function asToolResult(value) {
+	return {
+		content: [{
+			type: `text`,
+			text: typeof value === `string` ? value : JSON.stringify(value, null, 2)
+		}],
+		details: {}
+	};
+}
+function isRecord$1(value) {
+	return typeof value === `object` && value !== null && !Array.isArray(value);
+}
+function listPgSyncObservations(ctx) {
+	const manifests = ctx.db.collections.manifests?.toArray;
+	if (!Array.isArray(manifests)) return [];
+	const observations = [];
+	for (const entry of manifests) {
+		if (!isRecord$1(entry) || entry.kind !== `source` || entry.sourceType !== `pgSync` || typeof entry.sourceRef !== `string`) continue;
+		const config = isRecord$1(entry.config) ? entry.config : {};
+		observations.push({
+			sourceRef: entry.sourceRef,
+			...typeof config.table === `string` ? { table: config.table } : {},
+			...typeof config.url === `string` ? { url: config.url } : {},
+			...typeof entry.streamUrl === `string` ? { streamUrl: entry.streamUrl } : {}
+		});
+	}
+	return observations.sort((left, right) => left.sourceRef.localeCompare(right.sourceRef));
+}
+function createUnobservePgSyncTool(ctx) {
+	return {
+		name: `unobserve_pg_sync`,
+		label: `Stop Observing Postgres Sync`,
+		description: `Stop being woken by a Postgres shape stream you previously observed with observe_pg_sync. Identify the observation by its sourceRef (preferred) or table. Call with no arguments to list your active pg-sync observations. This only removes your own subscription; any other agents observing the same shape keep their stream.`,
+		parameters: Type.Object({
+			sourceRef: Type.Optional(Type.String({ description: `The sourceRef returned by observe_pg_sync. Preferred — unambiguous.` })),
+			table: Type.Optional(Type.String({ description: `The observed table name. Used only when sourceRef is not given; fails if more than one observation matches.` }))
+		}),
+		execute: async (_toolCallId, params) => {
+			const args = params;
+			const observations = listPgSyncObservations(ctx);
+			if (!args.sourceRef && !args.table) return asToolResult(observations.length > 0 ? { observations } : `You have no active pg-sync observations.`);
+			let sourceRef = args.sourceRef;
+			if (!sourceRef) {
+				const matches = observations.filter((o) => o.table === args.table);
+				if (matches.length === 0) return asToolResult(`No active pg-sync observation found for table "${args.table}".`);
+				if (matches.length > 1) return asToolResult({
+					error: `Multiple pg-sync observations match table "${args.table}"; pass a sourceRef instead.`,
+					matches
+				});
+				sourceRef = matches[0].sourceRef;
+			} else if (!observations.some((o) => o.sourceRef === sourceRef)) return asToolResult(`No active pg-sync observation found for sourceRef "${sourceRef}".`);
+			await ctx.unobserve(sourceRef);
+			return asToolResult({
+				unobserved: true,
+				sourceRef
+			});
+		}
+	};
+}
+
 //#endregion
 //#region src/tools/fork.ts
 function createForkTool(ctx) {
@@ -1306,7 +1370,7 @@ async function generateTitle(userMessage, llmCall, onFallback) {
 }
 function buildHortonSystemPrompt(workingDirectory, opts = {}) {
 	const docsTools = opts.hasDocsSupport ? `\n- search_electric_agents_docs: hybrid search over the built-in Electric Agents docs index` : ``;
-	const eventSourceTools = opts.hasEventSourceTools ? `\n- list_event_sources: list external webhook/event feeds you can subscribe to, including available buckets and parameters\n- subscribe_event_source: subscribe yourself to one of those feeds or buckets so matching future events wake you\n- list_event_source_subscriptions: list your active event source subscriptions\n- unsubscribe_event_source: remove one of your event source subscriptions by id` : ``;
+	const webhookSourceTools = opts.hasWebhookSourceTools ? `\n- list_webhook_sources: list external webhook feeds you can subscribe to, including available buckets and parameters\n- subscribe_webhook_source: subscribe yourself to one of those feeds or buckets so matching future webhooks wake you\n- list_webhook_source_subscriptions: list your active webhook source subscriptions\n- unsubscribe_webhook_source: remove one of your webhook source subscriptions by id` : ``;
 	const titleTool = `\n- set_title: set or rename this chat session's UI title`;
 	const scheduleTools = opts.hasScheduleTools ? `\n- upsert_cron_schedule: create or update a recurring cron wake for yourself. Always include payload with the concrete instruction/message you should receive when the cron fires.\n- delete_schedule: delete one of your cron or future-send schedules by stable id\n- list_schedules: list your manifest-backed cron and future-send schedules` : ``;
 	const skillsTools = opts.hasSkills ? `\n- use_skill: load a skill (knowledge, instructions, or a tutorial) into your context to help with the user's request\n- remove_skill: unload a skill from context when you're done with it` : ``;
@@ -1363,9 +1427,10 @@ When a user opens with a greeting ("hi", "hello", "hey", etc.) or a broad statem
 - fetch_url: fetch and convert a URL to markdown
 - spawn_worker: dispatch a subagent for an isolated task
 - fork: spawn a child session that inherits this conversation's history up to the latest completed response. Same parent-ownership model as spawn_worker — when the fork's next run finishes, you'll wake with its response.
-- observe_pg_sync: observe an Electric Postgres sync stream and wake on matching changes
+- observe_pg_sync: observe an Electric Postgres sync stream and wake on matching changes (see "Observing Postgres tables")
+- unobserve_pg_sync: stop being woken by a pg-sync stream you previously observed (see "Observing Postgres tables")
 - send: send a message to an Electric Agent/entity. To schedule future work for yourself, call send with self: true and afterMs.
-${eventSourceTools}${titleTool}${scheduleTools}${docsTools}${skillsTools}
+${webhookSourceTools}${titleTool}${scheduleTools}${docsTools}${skillsTools}
 
 # Working with files
 - Prefer edit over write when modifying existing files.
@@ -1373,6 +1438,14 @@ ${eventSourceTools}${titleTool}${scheduleTools}${docsTools}${skillsTools}
 - Use absolute paths or paths relative to the current working directory.
 ${modelGuidance}${docsGuidance}${skillsGuidance}${onboardingGuidance}${docsUrlGuidance}
 
+# Observing Postgres tables
+observe_pg_sync subscribes you to row changes in a Postgres table via an Electric shape stream:
+- The \`url\` parameter is the HTTP(S) URL of an Electric shape endpoint (e.g. \`http://localhost:3000/v1/shape\`). It is NOT a \`postgres://\` connection string and there is no default — if the user hasn't given you the endpoint URL, ask for it. Never guess or invent one.
+- Registration validates the endpoint by fetching the shape log first. If it fails, the error includes Electric's response or the failure reason — use it to correct the table name, where clause, or URL, or relay it to the user.
+- Use \`where\` and \`columns\` to narrow the shape so you only wake on changes you care about; use \`wake.ops\` to filter by operation and \`wake.debounceMs\` to batch bursts.
+- The observation persists across wakes — register it once, don't re-register on every wake.
+- To stop, call unobserve_pg_sync with the sourceRef from observe_pg_sync (or the table name). Call it with no arguments to list your active observations. This only ends your own subscription.
+
 # Risky actions
 Pause and confirm with the user before:
 - Destructive operations (deleting files, rm -rf, dropping data, force-pushing)
@@ -1444,6 +1517,7 @@ function createHortonTools(sandbox, ctx, readSet, opts = {}) {
 		createSpawnWorkerTool(ctx, opts.modelConfig),
 		createForkTool(ctx),
 		createObservePgSyncTool(ctx),
+		createUnobservePgSyncTool(ctx),
 		createSetTitleTool(ctx),
 		createSendTool(ctx.send, { selfEntityUrl: ctx.entityUrl }),
 		...ctx.getGoal()?.status === `active` ? [createMarkGoalCompleteTool(ctx)] : [],
@@ -1584,7 +1658,7 @@ function createAssistantHandler(options) {
 			...loadedSkills.tools,
 			...mcp.tools()
 		];
-		const hasEventSourceTools = tools.some((tool) => getToolName(tool) === `list_event_sources`);
+		const hasWebhookSourceTools = tools.some((tool) => getToolName(tool) === `list_webhook_sources`);
 		const hasScheduleTools = tools.some((tool) => getToolName(tool) === `upsert_cron_schedule`);
 		const titlePromise = !ctx.tags.title ? (async () => {
 			const firstUserMessage = await extractFirstUserMessage(ctx);
@@ -1686,7 +1760,7 @@ function createAssistantHandler(options) {
 				docsUrl,
 				modelProvider: modelConfig.provider,
 				modelId: String(modelConfig.model),
-				hasEventSourceTools,
+				hasWebhookSourceTools,
 				hasScheduleTools,
 				...activeGoalPromptInfo && { activeGoal: activeGoalPromptInfo }
 			}),
@@ -1974,7 +2048,7 @@ function dedupeToolsByName(tools) {
 }
 function createBuiltinElectricTools(custom) {
 	return async (context) => {
-		const builtinTools = [...createEventSourceTools(context), ...createScheduleTools({
+		const builtinTools = [...createWebhookSourceTools(context), ...createScheduleTools({
 			...context,
 			db: context.db
 		})];

package/dist/index.cjs

@@ -820,7 +820,7 @@ function createSpawnWorkerTool(ctx, modelConfig) {
 
 //#endregion
 //#region src/tools/observe-pg-sync.ts
-function asToolResult(value) {
+function asToolResult$1(value) {
 	return {
 		content: [{
 			type: `text`,
@@ -838,9 +838,9 @@ function createObservePgSyncTool(ctx) {
 	return {
 		name: `observe_pg_sync`,
 		label: `Observe Postgres Sync`,
-		description: `Observe an Electric Postgres shape stream and wake this agent when matching row changes arrive.`,
+		description: `Observe an Electric Postgres shape stream and wake this agent when matching row changes arrive. Requires the HTTP(S) URL of an Electric shape endpoint — ask the user for it if you don't know it. Registration validates the endpoint up front and fails with Electric's error if the shape can't be fetched.`,
 		parameters: __sinclair_typebox.Type.Object({
-			url: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String({ description: `Optional Electric shape endpoint URL. Defaults to the server-configured pg-sync URL.` })),
+			url: __sinclair_typebox.Type.String({ description: `HTTP(S) URL of the Electric shape endpoint, e.g. http://localhost:3000/v1/shape. Not a postgres:// connection string. Never guess this — ask the user if it hasn't been provided.` }),
 			table: __sinclair_typebox.Type.String({
 				minLength: 1,
 				pattern: `\\S`,
@@ -857,6 +857,7 @@ function createObservePgSyncTool(ctx) {
 		}),
 		execute: async (_toolCallId, params) => {
 			const args = params;
+			if (typeof args.url !== `string` || args.url.trim().length === 0) throw new Error(`url is required`);
 			if (typeof args.table !== `string` || args.table.trim().length === 0) throw new Error(`table is required`);
 			const source = (0, __electric_ax_agents_runtime.pgSync)({
 				url: args.url,
@@ -871,16 +872,79 @@ function createObservePgSyncTool(ctx) {
 				...args.wake?.ops ? { ops: args.wake.ops } : {},
 				...args.wake?.debounceMs !== void 0 ? { debounceMs: args.wake.debounceMs } : {}
 			};
-			await ctx.observe(source, { wake });
-			return asToolResult({
-				sourceRef: source.sourceRef,
-				streamUrl: source.streamUrl,
+			const handle = await ctx.observe(source, { wake });
+			if (!handle.streamUrl) throw new Error(`pg-sync observation did not return a stream URL for ${handle.sourceRef}`);
+			return asToolResult$1({
+				sourceRef: handle.sourceRef,
+				streamUrl: handle.streamUrl,
 				wake
 			});
 		}
 	};
 }
 
+//#endregion
+//#region src/tools/unobserve-pg-sync.ts
+function asToolResult(value) {
+	return {
+		content: [{
+			type: `text`,
+			text: typeof value === `string` ? value : JSON.stringify(value, null, 2)
+		}],
+		details: {}
+	};
+}
+function isRecord$1(value) {
+	return typeof value === `object` && value !== null && !Array.isArray(value);
+}
+function listPgSyncObservations(ctx) {
+	const manifests = ctx.db.collections.manifests?.toArray;
+	if (!Array.isArray(manifests)) return [];
+	const observations = [];
+	for (const entry of manifests) {
+		if (!isRecord$1(entry) || entry.kind !== `source` || entry.sourceType !== `pgSync` || typeof entry.sourceRef !== `string`) continue;
+		const config = isRecord$1(entry.config) ? entry.config : {};
+		observations.push({
+			sourceRef: entry.sourceRef,
+			...typeof config.table === `string` ? { table: config.table } : {},
+			...typeof config.url === `string` ? { url: config.url } : {},
+			...typeof entry.streamUrl === `string` ? { streamUrl: entry.streamUrl } : {}
+		});
+	}
+	return observations.sort((left, right) => left.sourceRef.localeCompare(right.sourceRef));
+}
+function createUnobservePgSyncTool(ctx) {
+	return {
+		name: `unobserve_pg_sync`,
+		label: `Stop Observing Postgres Sync`,
+		description: `Stop being woken by a Postgres shape stream you previously observed with observe_pg_sync. Identify the observation by its sourceRef (preferred) or table. Call with no arguments to list your active pg-sync observations. This only removes your own subscription; any other agents observing the same shape keep their stream.`,
+		parameters: __sinclair_typebox.Type.Object({
+			sourceRef: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String({ description: `The sourceRef returned by observe_pg_sync. Preferred — unambiguous.` })),
+			table: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String({ description: `The observed table name. Used only when sourceRef is not given; fails if more than one observation matches.` }))
+		}),
+		execute: async (_toolCallId, params) => {
+			const args = params;
+			const observations = listPgSyncObservations(ctx);
+			if (!args.sourceRef && !args.table) return asToolResult(observations.length > 0 ? { observations } : `You have no active pg-sync observations.`);
+			let sourceRef = args.sourceRef;
+			if (!sourceRef) {
+				const matches = observations.filter((o) => o.table === args.table);
+				if (matches.length === 0) return asToolResult(`No active pg-sync observation found for table "${args.table}".`);
+				if (matches.length > 1) return asToolResult({
+					error: `Multiple pg-sync observations match table "${args.table}"; pass a sourceRef instead.`,
+					matches
+				});
+				sourceRef = matches[0].sourceRef;
+			} else if (!observations.some((o) => o.sourceRef === sourceRef)) return asToolResult(`No active pg-sync observation found for sourceRef "${sourceRef}".`);
+			await ctx.unobserve(sourceRef);
+			return asToolResult({
+				unobserved: true,
+				sourceRef
+			});
+		}
+	};
+}
+
 //#endregion
 //#region src/tools/fork.ts
 function createForkTool(ctx) {
@@ -1313,7 +1377,7 @@ async function generateTitle(userMessage, llmCall, onFallback) {
 }
 function buildHortonSystemPrompt(workingDirectory, opts = {}) {
 	const docsTools = opts.hasDocsSupport ? `\n- search_electric_agents_docs: hybrid search over the built-in Electric Agents docs index` : ``;
-	const eventSourceTools = opts.hasEventSourceTools ? `\n- list_event_sources: list external webhook/event feeds you can subscribe to, including available buckets and parameters\n- subscribe_event_source: subscribe yourself to one of those feeds or buckets so matching future events wake you\n- list_event_source_subscriptions: list your active event source subscriptions\n- unsubscribe_event_source: remove one of your event source subscriptions by id` : ``;
+	const webhookSourceTools = opts.hasWebhookSourceTools ? `\n- list_webhook_sources: list external webhook feeds you can subscribe to, including available buckets and parameters\n- subscribe_webhook_source: subscribe yourself to one of those feeds or buckets so matching future webhooks wake you\n- list_webhook_source_subscriptions: list your active webhook source subscriptions\n- unsubscribe_webhook_source: remove one of your webhook source subscriptions by id` : ``;
 	const titleTool = `\n- set_title: set or rename this chat session's UI title`;
 	const scheduleTools = opts.hasScheduleTools ? `\n- upsert_cron_schedule: create or update a recurring cron wake for yourself. Always include payload with the concrete instruction/message you should receive when the cron fires.\n- delete_schedule: delete one of your cron or future-send schedules by stable id\n- list_schedules: list your manifest-backed cron and future-send schedules` : ``;
 	const skillsTools = opts.hasSkills ? `\n- use_skill: load a skill (knowledge, instructions, or a tutorial) into your context to help with the user's request\n- remove_skill: unload a skill from context when you're done with it` : ``;
@@ -1370,9 +1434,10 @@ When a user opens with a greeting ("hi", "hello", "hey", etc.) or a broad statem
 - fetch_url: fetch and convert a URL to markdown
 - spawn_worker: dispatch a subagent for an isolated task
 - fork: spawn a child session that inherits this conversation's history up to the latest completed response. Same parent-ownership model as spawn_worker — when the fork's next run finishes, you'll wake with its response.
-- observe_pg_sync: observe an Electric Postgres sync stream and wake on matching changes
+- observe_pg_sync: observe an Electric Postgres sync stream and wake on matching changes (see "Observing Postgres tables")
+- unobserve_pg_sync: stop being woken by a pg-sync stream you previously observed (see "Observing Postgres tables")
 - send: send a message to an Electric Agent/entity. To schedule future work for yourself, call send with self: true and afterMs.
-${eventSourceTools}${titleTool}${scheduleTools}${docsTools}${skillsTools}
+${webhookSourceTools}${titleTool}${scheduleTools}${docsTools}${skillsTools}
 
 # Working with files
 - Prefer edit over write when modifying existing files.
@@ -1380,6 +1445,14 @@ ${eventSourceTools}${titleTool}${scheduleTools}${docsTools}${skillsTools}
 - Use absolute paths or paths relative to the current working directory.
 ${modelGuidance}${docsGuidance}${skillsGuidance}${onboardingGuidance}${docsUrlGuidance}
 
+# Observing Postgres tables
+observe_pg_sync subscribes you to row changes in a Postgres table via an Electric shape stream:
+- The \`url\` parameter is the HTTP(S) URL of an Electric shape endpoint (e.g. \`http://localhost:3000/v1/shape\`). It is NOT a \`postgres://\` connection string and there is no default — if the user hasn't given you the endpoint URL, ask for it. Never guess or invent one.
+- Registration validates the endpoint by fetching the shape log first. If it fails, the error includes Electric's response or the failure reason — use it to correct the table name, where clause, or URL, or relay it to the user.
+- Use \`where\` and \`columns\` to narrow the shape so you only wake on changes you care about; use \`wake.ops\` to filter by operation and \`wake.debounceMs\` to batch bursts.
+- The observation persists across wakes — register it once, don't re-register on every wake.
+- To stop, call unobserve_pg_sync with the sourceRef from observe_pg_sync (or the table name). Call it with no arguments to list your active observations. This only ends your own subscription.
+
 # Risky actions
 Pause and confirm with the user before:
 - Destructive operations (deleting files, rm -rf, dropping data, force-pushing)
@@ -1451,6 +1524,7 @@ function createHortonTools(sandbox, ctx, readSet, opts = {}) {
 		createSpawnWorkerTool(ctx, opts.modelConfig),
 		createForkTool(ctx),
 		createObservePgSyncTool(ctx),
+		createUnobservePgSyncTool(ctx),
 		createSetTitleTool(ctx),
 		(0, __electric_ax_agents_runtime_tools.createSendTool)(ctx.send, { selfEntityUrl: ctx.entityUrl }),
 		...ctx.getGoal()?.status === `active` ? [(0, __electric_ax_agents_runtime_tools.createMarkGoalCompleteTool)(ctx)] : [],
@@ -1591,7 +1665,7 @@ function createAssistantHandler(options) {
 			...loadedSkills.tools,
 			...__electric_ax_agents_mcp.mcp.tools()
 		];
-		const hasEventSourceTools = tools.some((tool) => getToolName(tool) === `list_event_sources`);
+		const hasWebhookSourceTools = tools.some((tool) => getToolName(tool) === `list_webhook_sources`);
 		const hasScheduleTools = tools.some((tool) => getToolName(tool) === `upsert_cron_schedule`);
 		const titlePromise = !ctx.tags.title ? (async () => {
 			const firstUserMessage = await extractFirstUserMessage(ctx);
@@ -1693,7 +1767,7 @@ function createAssistantHandler(options) {
 				docsUrl,
 				modelProvider: modelConfig.provider,
 				modelId: String(modelConfig.model),
-				hasEventSourceTools,
+				hasWebhookSourceTools,
 				hasScheduleTools,
 				...activeGoalPromptInfo && { activeGoal: activeGoalPromptInfo }
 			}),
@@ -1982,7 +2056,7 @@ function dedupeToolsByName(tools) {
 }
 function createBuiltinElectricTools(custom) {
 	return async (context) => {
-		const builtinTools = [...(0, __electric_ax_agents_runtime_tools.createEventSourceTools)(context), ...(0, __electric_ax_agents_runtime_tools.createScheduleTools)({
+		const builtinTools = [...(0, __electric_ax_agents_runtime_tools.createWebhookSourceTools)(context), ...(0, __electric_ax_agents_runtime_tools.createScheduleTools)({
 			...context,
 			db: context.db
 		})];

package/dist/index.d.cts

@@ -239,7 +239,7 @@ interface ActiveGoalPromptInfo {
 }
 declare function buildHortonSystemPrompt(workingDirectory: string, opts?: {
   hasDocsSupport?: boolean;
-  hasEventSourceTools?: boolean;
+  hasWebhookSourceTools?: boolean;
   hasScheduleTools?: boolean;
   hasSkills?: boolean;
   docsUrl?: string;

package/dist/index.d.ts

@@ -239,7 +239,7 @@ interface ActiveGoalPromptInfo {
 }
 declare function buildHortonSystemPrompt(workingDirectory: string, opts?: {
   hasDocsSupport?: boolean;
-  hasEventSourceTools?: boolean;
+  hasWebhookSourceTools?: boolean;
   hasScheduleTools?: boolean;
   hasSkills?: boolean;
   docsUrl?: string;

package/dist/index.js

@@ -2,7 +2,7 @@ import { mergeElectricPrincipalHeader } from "./server-headers-KD5yHFYT.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { GOAL_SLASH_COMMAND, MOONSHOT_API_BASE_URL, MOONSHOT_PROVIDER, appendPathToUrl, buildSkillSlashCommands, commentsCollection, completeWithLowCostModel, createContextSkillLoader, createEntityRegistry, createPullWakeRunner, createRuntimeHandler, createSkillsRegistry, db, detectAvailableProviders, dispatchGoalCommand, formatTokenCount, getMoonshotApiKey, getMoonshotModel, getMoonshotModels, isGoalCommandText, parseGoalCommand, pgSync, readCodexAccessToken, registerToolProvider, unregisterToolProvider } from "@electric-ax/agents-runtime";
-import { braveSearchTool, braveSearchTool as braveSearchTool$1, createBashTool, createEditTool, createEventSourceTools, createFetchUrlTool, createMarkGoalCompleteTool, createReadFileTool, createScheduleTools, createSendTool, createWriteTool } from "@electric-ax/agents-runtime/tools";
+import { braveSearchTool, braveSearchTool as braveSearchTool$1, createBashTool, createEditTool, createFetchUrlTool, createMarkGoalCompleteTool, createReadFileTool, createScheduleTools, createSendTool, createWebhookSourceTools, createWriteTool } from "@electric-ax/agents-runtime/tools";
 import { chooseDefaultSandbox, isE2BAvailable, lazySandbox, remoteSandbox } from "@electric-ax/agents-runtime/sandbox";
 import fsSync from "node:fs";
 import pino from "pino";
@@ -796,7 +796,7 @@ function createSpawnWorkerTool(ctx, modelConfig) {
 
 //#endregion
 //#region src/tools/observe-pg-sync.ts
-function asToolResult(value) {
+function asToolResult$1(value) {
 	return {
 		content: [{
 			type: `text`,
@@ -814,9 +814,9 @@ function createObservePgSyncTool(ctx) {
 	return {
 		name: `observe_pg_sync`,
 		label: `Observe Postgres Sync`,
-		description: `Observe an Electric Postgres shape stream and wake this agent when matching row changes arrive.`,
+		description: `Observe an Electric Postgres shape stream and wake this agent when matching row changes arrive. Requires the HTTP(S) URL of an Electric shape endpoint — ask the user for it if you don't know it. Registration validates the endpoint up front and fails with Electric's error if the shape can't be fetched.`,
 		parameters: Type.Object({
-			url: Type.Optional(Type.String({ description: `Optional Electric shape endpoint URL. Defaults to the server-configured pg-sync URL.` })),
+			url: Type.String({ description: `HTTP(S) URL of the Electric shape endpoint, e.g. http://localhost:3000/v1/shape. Not a postgres:// connection string. Never guess this — ask the user if it hasn't been provided.` }),
 			table: Type.String({
 				minLength: 1,
 				pattern: `\\S`,
@@ -833,6 +833,7 @@ function createObservePgSyncTool(ctx) {
 		}),
 		execute: async (_toolCallId, params) => {
 			const args = params;
+			if (typeof args.url !== `string` || args.url.trim().length === 0) throw new Error(`url is required`);
 			if (typeof args.table !== `string` || args.table.trim().length === 0) throw new Error(`table is required`);
 			const source = pgSync({
 				url: args.url,
@@ -847,16 +848,79 @@ function createObservePgSyncTool(ctx) {
 				...args.wake?.ops ? { ops: args.wake.ops } : {},
 				...args.wake?.debounceMs !== void 0 ? { debounceMs: args.wake.debounceMs } : {}
 			};
-			await ctx.observe(source, { wake });
-			return asToolResult({
-				sourceRef: source.sourceRef,
-				streamUrl: source.streamUrl,
+			const handle = await ctx.observe(source, { wake });
+			if (!handle.streamUrl) throw new Error(`pg-sync observation did not return a stream URL for ${handle.sourceRef}`);
+			return asToolResult$1({
+				sourceRef: handle.sourceRef,
+				streamUrl: handle.streamUrl,
 				wake
 			});
 		}
 	};
 }
 
+//#endregion
+//#region src/tools/unobserve-pg-sync.ts
+function asToolResult(value) {
+	return {
+		content: [{
+			type: `text`,
+			text: typeof value === `string` ? value : JSON.stringify(value, null, 2)
+		}],
+		details: {}
+	};
+}
+function isRecord$1(value) {
+	return typeof value === `object` && value !== null && !Array.isArray(value);
+}
+function listPgSyncObservations(ctx) {
+	const manifests = ctx.db.collections.manifests?.toArray;
+	if (!Array.isArray(manifests)) return [];
+	const observations = [];
+	for (const entry of manifests) {
+		if (!isRecord$1(entry) || entry.kind !== `source` || entry.sourceType !== `pgSync` || typeof entry.sourceRef !== `string`) continue;
+		const config = isRecord$1(entry.config) ? entry.config : {};
+		observations.push({
+			sourceRef: entry.sourceRef,
+			...typeof config.table === `string` ? { table: config.table } : {},
+			...typeof config.url === `string` ? { url: config.url } : {},
+			...typeof entry.streamUrl === `string` ? { streamUrl: entry.streamUrl } : {}
+		});
+	}
+	return observations.sort((left, right) => left.sourceRef.localeCompare(right.sourceRef));
+}
+function createUnobservePgSyncTool(ctx) {
+	return {
+		name: `unobserve_pg_sync`,
+		label: `Stop Observing Postgres Sync`,
+		description: `Stop being woken by a Postgres shape stream you previously observed with observe_pg_sync. Identify the observation by its sourceRef (preferred) or table. Call with no arguments to list your active pg-sync observations. This only removes your own subscription; any other agents observing the same shape keep their stream.`,
+		parameters: Type.Object({
+			sourceRef: Type.Optional(Type.String({ description: `The sourceRef returned by observe_pg_sync. Preferred — unambiguous.` })),
+			table: Type.Optional(Type.String({ description: `The observed table name. Used only when sourceRef is not given; fails if more than one observation matches.` }))
+		}),
+		execute: async (_toolCallId, params) => {
+			const args = params;
+			const observations = listPgSyncObservations(ctx);
+			if (!args.sourceRef && !args.table) return asToolResult(observations.length > 0 ? { observations } : `You have no active pg-sync observations.`);
+			let sourceRef = args.sourceRef;
+			if (!sourceRef) {
+				const matches = observations.filter((o) => o.table === args.table);
+				if (matches.length === 0) return asToolResult(`No active pg-sync observation found for table "${args.table}".`);
+				if (matches.length > 1) return asToolResult({
+					error: `Multiple pg-sync observations match table "${args.table}"; pass a sourceRef instead.`,
+					matches
+				});
+				sourceRef = matches[0].sourceRef;
+			} else if (!observations.some((o) => o.sourceRef === sourceRef)) return asToolResult(`No active pg-sync observation found for sourceRef "${sourceRef}".`);
+			await ctx.unobserve(sourceRef);
+			return asToolResult({
+				unobserved: true,
+				sourceRef
+			});
+		}
+	};
+}
+
 //#endregion
 //#region src/tools/fork.ts
 function createForkTool(ctx) {
@@ -1289,7 +1353,7 @@ async function generateTitle(userMessage, llmCall, onFallback) {
 }
 function buildHortonSystemPrompt(workingDirectory, opts = {}) {
 	const docsTools = opts.hasDocsSupport ? `\n- search_electric_agents_docs: hybrid search over the built-in Electric Agents docs index` : ``;
-	const eventSourceTools = opts.hasEventSourceTools ? `\n- list_event_sources: list external webhook/event feeds you can subscribe to, including available buckets and parameters\n- subscribe_event_source: subscribe yourself to one of those feeds or buckets so matching future events wake you\n- list_event_source_subscriptions: list your active event source subscriptions\n- unsubscribe_event_source: remove one of your event source subscriptions by id` : ``;
+	const webhookSourceTools = opts.hasWebhookSourceTools ? `\n- list_webhook_sources: list external webhook feeds you can subscribe to, including available buckets and parameters\n- subscribe_webhook_source: subscribe yourself to one of those feeds or buckets so matching future webhooks wake you\n- list_webhook_source_subscriptions: list your active webhook source subscriptions\n- unsubscribe_webhook_source: remove one of your webhook source subscriptions by id` : ``;
 	const titleTool = `\n- set_title: set or rename this chat session's UI title`;
 	const scheduleTools = opts.hasScheduleTools ? `\n- upsert_cron_schedule: create or update a recurring cron wake for yourself. Always include payload with the concrete instruction/message you should receive when the cron fires.\n- delete_schedule: delete one of your cron or future-send schedules by stable id\n- list_schedules: list your manifest-backed cron and future-send schedules` : ``;
 	const skillsTools = opts.hasSkills ? `\n- use_skill: load a skill (knowledge, instructions, or a tutorial) into your context to help with the user's request\n- remove_skill: unload a skill from context when you're done with it` : ``;
@@ -1346,9 +1410,10 @@ When a user opens with a greeting ("hi", "hello", "hey", etc.) or a broad statem
 - fetch_url: fetch and convert a URL to markdown
 - spawn_worker: dispatch a subagent for an isolated task
 - fork: spawn a child session that inherits this conversation's history up to the latest completed response. Same parent-ownership model as spawn_worker — when the fork's next run finishes, you'll wake with its response.
-- observe_pg_sync: observe an Electric Postgres sync stream and wake on matching changes
+- observe_pg_sync: observe an Electric Postgres sync stream and wake on matching changes (see "Observing Postgres tables")
+- unobserve_pg_sync: stop being woken by a pg-sync stream you previously observed (see "Observing Postgres tables")
 - send: send a message to an Electric Agent/entity. To schedule future work for yourself, call send with self: true and afterMs.
-${eventSourceTools}${titleTool}${scheduleTools}${docsTools}${skillsTools}
+${webhookSourceTools}${titleTool}${scheduleTools}${docsTools}${skillsTools}
 
 # Working with files
 - Prefer edit over write when modifying existing files.
@@ -1356,6 +1421,14 @@ ${eventSourceTools}${titleTool}${scheduleTools}${docsTools}${skillsTools}
 - Use absolute paths or paths relative to the current working directory.
 ${modelGuidance}${docsGuidance}${skillsGuidance}${onboardingGuidance}${docsUrlGuidance}
 
+# Observing Postgres tables
+observe_pg_sync subscribes you to row changes in a Postgres table via an Electric shape stream:
+- The \`url\` parameter is the HTTP(S) URL of an Electric shape endpoint (e.g. \`http://localhost:3000/v1/shape\`). It is NOT a \`postgres://\` connection string and there is no default — if the user hasn't given you the endpoint URL, ask for it. Never guess or invent one.
+- Registration validates the endpoint by fetching the shape log first. If it fails, the error includes Electric's response or the failure reason — use it to correct the table name, where clause, or URL, or relay it to the user.
+- Use \`where\` and \`columns\` to narrow the shape so you only wake on changes you care about; use \`wake.ops\` to filter by operation and \`wake.debounceMs\` to batch bursts.
+- The observation persists across wakes — register it once, don't re-register on every wake.
+- To stop, call unobserve_pg_sync with the sourceRef from observe_pg_sync (or the table name). Call it with no arguments to list your active observations. This only ends your own subscription.
+
 # Risky actions
 Pause and confirm with the user before:
 - Destructive operations (deleting files, rm -rf, dropping data, force-pushing)
@@ -1427,6 +1500,7 @@ function createHortonTools(sandbox, ctx, readSet, opts = {}) {
 		createSpawnWorkerTool(ctx, opts.modelConfig),
 		createForkTool(ctx),
 		createObservePgSyncTool(ctx),
+		createUnobservePgSyncTool(ctx),
 		createSetTitleTool(ctx),
 		createSendTool(ctx.send, { selfEntityUrl: ctx.entityUrl }),
 		...ctx.getGoal()?.status === `active` ? [createMarkGoalCompleteTool(ctx)] : [],
@@ -1567,7 +1641,7 @@ function createAssistantHandler(options) {
 			...loadedSkills.tools,
 			...mcp.tools()
 		];
-		const hasEventSourceTools = tools.some((tool) => getToolName(tool) === `list_event_sources`);
+		const hasWebhookSourceTools = tools.some((tool) => getToolName(tool) === `list_webhook_sources`);
 		const hasScheduleTools = tools.some((tool) => getToolName(tool) === `upsert_cron_schedule`);
 		const titlePromise = !ctx.tags.title ? (async () => {
 			const firstUserMessage = await extractFirstUserMessage(ctx);
@@ -1669,7 +1743,7 @@ function createAssistantHandler(options) {
 				docsUrl,
 				modelProvider: modelConfig.provider,
 				modelId: String(modelConfig.model),
-				hasEventSourceTools,
+				hasWebhookSourceTools,
 				hasScheduleTools,
 				...activeGoalPromptInfo && { activeGoal: activeGoalPromptInfo }
 			}),
@@ -1958,7 +2032,7 @@ function dedupeToolsByName(tools) {
 }
 function createBuiltinElectricTools(custom) {
 	return async (context) => {
-		const builtinTools = [...createEventSourceTools(context), ...createScheduleTools({
+		const builtinTools = [...createWebhookSourceTools(context), ...createScheduleTools({
 			...context,
 			db: context.db
 		})];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents",
-  "version": "0.4.18",
+  "version": "0.4.19",
   "description": "Built-in Electric Agents runtimes such as Horton and worker",
   "repository": {
     "type": "git",
@@ -49,8 +49,8 @@
     "sqlite-vec": "^0.1.9",
     "undici": "^7.24.7",
     "zod": "^4.3.6",
-    "@electric-ax/agents-mcp": "0.2.3",
-    "@electric-ax/agents-runtime": "0.4.0"
+    "@electric-ax/agents-runtime": "0.4.1",
+    "@electric-ax/agents-mcp": "0.2.3"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",