Skip to content

Open-source, local-first social media research agent for Instagram, TikTok, and LinkedIn. Jev routes read-only steps; socai CLI captures cited browser evidence.

Harden platform routing guardrails (#57)

Asklvcd7158bb4583
diff --git a/src/classifier.js b/src/classifier.js
index 14a81e5..d851d25 100644
--- a/src/classifier.js
+++ b/src/classifier.js
@@ -8,6 +8,37 @@ const ROUTE_TO_PLATFORM = {
tiktok_search: "tiktok",
linkedin_search: "linkedin",
};
+const PLATFORM_PATTERN_SOURCE = "(?:instagram|insta|tiktok|tik[\\s-]?tok|linked[\\s-]?in)";
+const DIRECT_PLATFORM_ROUTE = new RegExp(
+ `\\b(?:search|research|explore|browse|scan|monitor|track|investigate|analy[sz]e|review|find|discover|look\\s+up)\\s+(?:on\\s+|in\\s+|from\\s+|via\\s+|using\\s+)?(?<platform>${PLATFORM_PATTERN_SOURCE})\\b`,
+ "giu",
+);
+const PREPOSITION_PLATFORM_ROUTE = new RegExp(
+ `\\b(?:search|research|explore|browse|scan|monitor|track|investigate|analy[sz]e|review|find|discover|look\\s+up)\\b[^.;!?\\n]{0,100}?\\b(?:on|in|from|via|using)\\s+(?<platform>${PLATFORM_PATTERN_SOURCE})\\b`,
+ "giu",
+);
+const COORDINATED_PLATFORM_ROUTE = new RegExp(
+ `\\b(?:on|in|from|via|using)\\s+${PLATFORM_PATTERN_SOURCE}\\s*(?:,|and|or|/)\\s*${PLATFORM_PATTERN_SOURCE}\\b`,
+ "iu",
+);
+const MUTATION_ACTIONS = [
+ /^(?:post|publish|upload)\b(?!\s+(?:performance|reach|impressions?|analytics?|metrics?|engagement|sentiment|data|statistics?|trends?|frequency|rates?|activity|history|volume|cadence|timing|topics?|formats?|length|quality|distribution|demographics?)\b)/iu,
+ /^create\s+(?:(?:a|an|the|this|that|new)\s+)?(?:posts?|comments?|repl(?:y|ies)|stories|reels?|messages?|dms?|content)\b/iu,
+ /^(?:delete|remove|edit|update|repost|reshare|share)\s+(?:(?:a|an|the|this|that|my|our|their|his|her|new)\s+)?(?:(?:instagram|insta|tiktok|tik[\s-]?tok|linked[\s-]?in)\s+)?(?:posts?|photos?|videos?|comments?|repl(?:y|ies)|messages?|stories|reels?|content|updates?|bios?|profiles?|captions?|accounts?|it|them)\b/iu,
+ /^(?:follow|unfollow)\s+(?:@[\w.-]+|(?:(?:a|an|the|this|that|my|our|their|his|her)\s+)?(?:(?:instagram|insta|tiktok|tik[\s-]?tok|linked[\s-]?in)\s+)?(?:creators?|users?|accounts?|profiles?|people|persons?|influencers?|brands?|companies?|him|her|them|me))\b/iu,
+ /^(?:like|unlike|react\s+to)\s+(?:@[\w.-]+|(?:(?:a|an|the|this|that|my|our|their|his|her)\s+)?(?:(?:instagram|insta|tiktok|tik[\s-]?tok|linked[\s-]?in)\s+)?(?:posts?|photos?|videos?|comments?|reels?|stories|content|updates?|accounts?|it|them))\b/iu,
+ /^(?:message|dm)\s+(?:@[\w.-]+|(?:(?:a|an|the|this|that|my|our|their|his|her)\s+)?(?:(?:instagram|insta|tiktok|tik[\s-]?tok|linked[\s-]?in)\s+)?(?:creators?|users?|accounts?|profiles?|people|persons?|influencers?|him|her|them|me))\b/iu,
+ /^send\s+(?:(?:a|an|the|this|that|my|our|their)\s+)?(?:messages?|dms?|repl(?:y|ies)|comments?|invites?)\b/iu,
+ /^send\s+(?:@[\w.-]+|them|him|her|me|(?:(?:the|this|that)\s+)?(?:creators?|users?|people|persons?))\s+(?:(?:a|an|the)\s+)?(?:messages?|dms?|repl(?:y|ies)|comments?|invites?)\b/iu,
+ /^comment\s+(?:on|under)\b/iu,
+ /^comment\s+(?:this|that|something|text|content|an?\s+emoji)\s+(?:on|under)\b/iu,
+ /^(?:leave|write)\s+(?:(?:a|an|the|this|that)\s+)?(?:comments?|repl(?:y|ies)|messages?|dms?)\b/iu,
+ /^give\s+(?:(?:a|an|the|this|that|their|his|her)\s+)?(?:posts?|photos?|videos?|comments?|reels?|stories|content)\s+(?:(?:a|an|the)\s+)?(?:like|reaction)\b/iu,
+ /^reply\s+(?:to|on|under)\b/iu,
+ /^(?:connect\s+with|invite|subscribe\s+to|block|unblock|mute|unmute)\b/iu,
+];
+const CHINESE_MUTATION_ACTION = /^(?:(?:请|麻烦|帮我|请帮我|可以帮我|我想|我要|我需要你|能否|可以)\s*)?(?:发布|发帖|上传|删除|转发|点赞|关注|取消关注|评论|回复|私信|发消息|拉黑|屏蔽|修改(?:我的)?(?:简介|个人资料))/u;
+const READ_ONLY_ANALYTICS_ACTION = /^follow\b[^.;!?]{0,80}\b(?:posting\s+frequency|activity|trends?|metrics?|performance|growth|changes?|updates?)\b/iu;
const WORKFLOW_DEFINITIONS = {
instagram: {
@@ -27,6 +58,65 @@ const WORKFLOW_DEFINITIONS = {
},
};
+function normalizePlatformMention(value) {
+ const normalized = value.toLowerCase().replace(/[\s-]/gu, "");
+ if (normalized === "instagram" || normalized === "insta") return "instagram";
+ if (normalized === "tiktok") return "tiktok";
+ if (normalized === "linkedin") return "linkedin";
+ return null;
+}
+
+function isNegatedRouteMatch(goal, match) {
+ const before = goal.slice(Math.max(0, match.index - 80), match.index);
+ const matchedPrefix = match[0].slice(0, match[0].lastIndexOf(match.groups.platform));
+ return /\b(?:do\s+not|don't|never|avoid|exclude|without|not)\b[^,;.!?\n]{0,60}$/iu.test(before)
+ || /\b(?:not|never|avoid|exclude|without)\b[^.;!?\n]*$/iu.test(matchedPrefix);
+}
+
+function routeMatches(goal, pattern) {
+ pattern.lastIndex = 0;
+ return [...goal.matchAll(pattern)]
+ .filter((match) => !isNegatedRouteMatch(goal, match))
+ .map((match) => normalizePlatformMention(match.groups.platform))
+ .filter(Boolean);
+}
+
+function inferGoalPlatform(goal) {
+ if (COORDINATED_PLATFORM_ROUTE.test(goal)) return null;
+
+ const preposition = [...new Set(routeMatches(goal, PREPOSITION_PLATFORM_ROUTE))];
+ if (preposition.length === 1) return preposition[0];
+ if (preposition.length > 1) return null;
+
+ const direct = [...new Set(routeMatches(goal, DIRECT_PLATFORM_ROUTE))];
+ return direct.length === 1 ? direct[0] : null;
+}
+
+function mutationClauses(goal) {
+ const clauses = [goal.trim()];
+ const suffixes = /(?:[.;!?]\s*|\b(?:then|and\s+then|after\s+that)\s+|(?:然后|再))([^.;!?]+)/giu;
+ for (const match of goal.matchAll(suffixes)) clauses.push(match[1].trim());
+ const conjunctions = /\band\s+((?:please\s+)?(?:post|publish|upload|create|delete|remove|edit|update|repost|reshare|share|follow|unfollow|like|unlike|react|message|dm|send|comment|reply|leave|write|give|connect|invite|subscribe|block|unblock|mute|unmute)\b[^.;!?]*)/giu;
+ for (const match of goal.matchAll(conjunctions)) clauses.push(match[1].trim());
+ return clauses;
+}
+
+function stripRequestPrefix(value) {
+ return value.replace(
+ /^(?:(?:please|kindly)\s+|(?:(?:can|could|would|will)\s+you\s+(?:please\s+)?)|(?:i\s+(?:want|need|would\s+like)\s+(?:you\s+)?to\s+))+/iu,
+ "",
+ );
+}
+
+function hasClearMutationRequest(goal) {
+ return mutationClauses(goal).some((clause) => {
+ const command = stripRequestPrefix(clause.trim());
+ if (READ_ONLY_ANALYTICS_ACTION.test(command)) return false;
+ return CHINESE_MUTATION_ACTION.test(command)
+ || MUTATION_ACTIONS.some((pattern) => pattern.test(command));
+ });
+}
+
export async function classifySearch({
goal,
requestedPlatform = "auto",
@@ -48,8 +138,14 @@ export async function classifySearch({
if (!goal?.trim()) {
throw new AppError("Search query cannot be empty.", { code: "EMPTY_QUERY" });
}
+ if (hasClearMutationRequest(goal)) {
+ throw new AppError("This request is not a supported read-only social task.", {
+ code: "UNSUPPORTED_TASK",
+ });
+ }
const activePlatforms = [...SUPPORTED_PLATFORMS].filter((p) => capabilities?.[p] !== false);
+ const goalPlatform = inferGoalPlatform(goal);
if (normalizedPlatform !== "auto" && !activePlatforms.includes(normalizedPlatform)) {
throw new AppError(`The installed socai CLI does not support ${normalizedPlatform} search.`, {
@@ -57,6 +153,15 @@ export async function classifySearch({
details: { platform: normalizedPlatform },
});
}
+ if (normalizedPlatform === "auto" && goalPlatform && !activePlatforms.includes(goalPlatform)) {
+ throw new AppError(`The installed socai CLI does not support ${goalPlatform} search.`, {
+ code: "SOCAI_CAPABILITY_MISSING",
+ details: { platform: goalPlatform },
+ });
+ }
+ const effectivePlatform = normalizedPlatform === "auto"
+ ? goalPlatform || "auto"
+ : normalizedPlatform;
const supportedWorkflows = activePlatforms.map((p) => WORKFLOW_DEFINITIONS[p].workflow);
const routeCriteria = {};
@@ -69,7 +174,7 @@ export async function classifySearch({
model: decisionModel,
state: {
request: goal.trim(),
- requested_platform: normalizedPlatform,
+ requested_platform: effectivePlatform,
supported_workflows: supportedWorkflows,
},
questions: {
@@ -90,13 +195,13 @@ export async function classifySearch({
const decision = await requestChoice({ request, key: "route", apiKey, provider, client, fetchImpl, signal });
const selected = decision.choice;
const platform = ROUTE_TO_PLATFORM[selected] || null;
- if (normalizedPlatform !== "auto" && platform !== normalizedPlatform) {
+ if (selected !== "unsupported" && effectivePlatform !== "auto" && platform !== effectivePlatform) {
throw new AppError(
- `Jev route '${selected}' conflicts with the explicitly selected ${normalizedPlatform} platform.`,
+ `Jev route '${selected}' conflicts with the ${effectivePlatform} platform constraint.`,
{
code: "JEV_ROUTE_MISMATCH",
details: {
- requestedPlatform: normalizedPlatform,
+ requestedPlatform: effectivePlatform,
selectedRoute: selected,
elapsedMs: decision.elapsedMs,
model: decision.model,
diff --git a/test/app.test.js b/test/app.test.js
index a7e5116..8999d86 100644
--- a/test/app.test.js
+++ b/test/app.test.js
@@ -144,6 +144,62 @@ test("runSearch can use a loopback Kev endpoint without an OpenRouter key", asyn
}
});
+test("a named platform does not bypass a low-confidence supported-vs-unsupported decision", async () => {
+ const { directory, env } = await fixture();
+ const client = {
+ async systemOne(request) {
+ if (request.questions.route) {
+ assert.equal(request.state.requested_platform, "tiktok");
+ return {
+ model: "laya:en",
+ answers: {
+ route: { type: "choice", choice: "tiktok_search", confidence: 0.2 },
+ },
+ };
+ }
+ throw new Error("action selection must not run");
+ },
+ };
+
+ try {
+ await assert.rejects(
+ runSearch(
+ { query: "Research viral camera reviews on TikTok", platform: "auto", limit: 1 },
+ { env, client, reportChunkDelayMs: 0 },
+ ),
+ (error) => error.code === "LOW_CLASSIFICATION_CONFIDENCE",
+ );
+ } finally {
+ await rm(directory, { recursive: true, force: true });
+ }
+});
+
+test("an unconstrained low-confidence platform decision still fails closed", async () => {
+ const { directory, env } = await fixture();
+ try {
+ await assert.rejects(
+ runSearch(
+ { query: "Find emerging creators", platform: "auto" },
+ {
+ env,
+ client: {
+ async systemOne() {
+ return {
+ answers: {
+ route: { type: "choice", choice: "instagram_search", confidence: 0.2 },
+ },
+ };
+ },
+ },
+ },
+ ),
+ (error) => error.code === "LOW_CLASSIFICATION_CONFIDENCE",
+ );
+ } finally {
+ await rm(directory, { recursive: true, force: true });
+ }
+});
+
test("Jev opens a profile then selects a newly observed post", async () => {
const {directory,env} = await fixture();
const client = choices('instagram',(criteria,step) => {
diff --git a/test/classifier.test.js b/test/classifier.test.js
index 920d468..afb4772 100644
--- a/test/classifier.test.js
+++ b/test/classifier.test.js
@@ -106,11 +106,187 @@ test("classifySearch preserves Jev unsupported decisions", async () => {
};
},
};
- const result = await classifySearch({ goal: "send a message", client });
+ const result = await classifySearch({ goal: "write a poem about social media", client });
assert.equal(result.platform, null);
assert.equal(result.route, "unsupported");
});
+test("classifySearch constrains auto routing when the goal names one available platform", async () => {
+ let request;
+ const client = {
+ async systemOne(value) {
+ request = value;
+ return {
+ model: "laya:en",
+ answers: {
+ route: {
+ type: "choice",
+ choice: "tiktok_search",
+ confidence: 0.61,
+ },
+ },
+ };
+ },
+ };
+
+ const result = await classifySearch({
+ goal: "Research viral camera reviews on TikTok",
+ requestedPlatform: "auto",
+ client,
+ });
+
+ assert.equal(request.state.requested_platform, "tiktok");
+ assert.equal(result.platform, "tiktok");
+});
+
+test("classifySearch leaves ambiguous, topical, and negated platform mentions for the decision provider", async () => {
+ const goals = [
+ "Compare creator reactions on TikTok and Instagram",
+ "Search LinkedIn for posts about TikTok",
+ "Do not use TikTok; find emerging creators",
+ "I do not want you to search TikTok; find emerging creators",
+ "Do not ever research LinkedIn; find founders",
+ "Research TikTok trends on Instagram",
+ ];
+ const expectedRequestedPlatforms = ["auto", "linkedin", "auto", "auto", "auto", "instagram"];
+
+ for (const [index, goal] of goals.entries()) {
+ let request;
+ const client = {
+ async systemOne(value) {
+ request = value;
+ return {
+ answers: {
+ route: {
+ type: "choice",
+ choice: "unsupported",
+ confidence: 0.82,
+ },
+ },
+ };
+ },
+ };
+
+ const result = await classifySearch({
+ goal,
+ requestedPlatform: "auto",
+ client,
+ });
+
+ assert.equal(request.state.requested_platform, expectedRequestedPlatforms[index], goal);
+ assert.equal(result.platform, null);
+ }
+});
+
+test("a named but unavailable platform fails before any model call", async () => {
+ let called = false;
+ await assert.rejects(
+ classifySearch({
+ goal: "Find AI founders on LinkedIn",
+ requestedPlatform: "auto",
+ capabilities: { instagram: true, tiktok: true, linkedin: false },
+ client: {
+ async systemOne() {
+ called = true;
+ throw new Error("must not run");
+ },
+ },
+ }),
+ (error) => error.code === "SOCAI_CAPABILITY_MISSING" && error.details?.platform === "linkedin",
+ );
+ assert.equal(called, false);
+});
+
+test("classifySearch rejects clear account-changing requests before any model call", async () => {
+ for (const goal of [
+ "Post a promotional comment on Instagram",
+ "Post photos on Instagram",
+ "Publish to Instagram",
+ "Please like this TikTok video",
+ "Follow creators on TikTok",
+ "Find the creator, then follow their account",
+ "I want you to message this LinkedIn user",
+ "Delete my Instagram post",
+ "Repost this TikTok video",
+ "Connect with this person on LinkedIn",
+ "Update my Instagram bio",
+ "Find the creator, then send them a DM",
+ "Find the creator and leave a comment on their latest post",
+ "Could you give this post a like?",
+ "Please create a post on Instagram",
+ "请帮我关注这个 Instagram 创作者",
+ ]) {
+ let called = false;
+ await assert.rejects(
+ classifySearch({
+ goal,
+ client: {
+ async systemOne() {
+ called = true;
+ throw new Error("must not run");
+ },
+ },
+ }),
+ (error) => error.code === "UNSUPPORTED_TASK",
+ goal,
+ );
+ assert.equal(called, false, goal);
+ }
+});
+
+test("read-only post and comment nouns do not trigger the mutation guard", async () => {
+ for (const goal of [
+ "Find posts and comments about AI creators on Instagram",
+ "Post performance and comment sentiment on Instagram",
+ "Follow the discussion about AI creators on Instagram",
+ "Follow creators' posting frequency on Instagram",
+ "Research posts about how to publish on Instagram",
+ "Like analytics reports, research creators on Instagram",
+ "Post reach and engagement metrics on Instagram",
+ "Post impressions by creator on Instagram",
+ ]) {
+ let called = false;
+ const result = await classifySearch({
+ goal,
+ client: {
+ async systemOne() {
+ called = true;
+ return {
+ answers: {
+ route: {
+ type: "choice",
+ choice: "instagram_search",
+ confidence: 0.9,
+ },
+ },
+ };
+ },
+ },
+ });
+
+ assert.equal(called, true, goal);
+ assert.equal(result.platform, "instagram");
+ }
+});
+
+test("an unsupported decision is preserved even when a positive platform hint exists", async () => {
+ const result = await classifySearch({
+ goal: "Research Instagram in a way the provider cannot support",
+ client: {
+ async systemOne() {
+ return {
+ answers: {
+ route: { type: "choice", choice: "unsupported", confidence: 0.91 },
+ },
+ };
+ },
+ },
+ });
+
+ assert.equal(result.route, "unsupported");
+ assert.equal(result.platform, null);
+});
+
test("classifySearch never lets Jev override an explicit platform", async () => {
const client = {
async systemOne() {
diff --git a/test/decision-provider.test.js b/test/decision-provider.test.js
index 4f56ab8..d31710e 100644
--- a/test/decision-provider.test.js
+++ b/test/decision-provider.test.js
@@ -78,6 +78,38 @@ test("classifySearch defaults to the resolved local provider model", async () =>
assert.equal(result.model, "kev-local-test");
});
+test("a local router may report the canonical model that answered", async () => {
+ const provider = resolveDecisionProvider({
+ JEV_SOCIAL_SYSTEM_ONE_URL: "http://127.0.0.1:11435/v1/systemone",
+ JEV_SOCIAL_SYSTEM_ONE_MODEL: "laya",
+ });
+ let sent;
+ const result = await classifySearch({
+ goal: "find design creators on Instagram",
+ provider,
+ fetchImpl: async (_url, options) => {
+ sent = JSON.parse(options.body);
+ return Response.json({
+ model: "laya:en",
+ answers: {
+ route: {
+ type: "choice",
+ choice: "instagram_search",
+ confidence: 0.91,
+ probabilities: { instagram_search: 0.91, unsupported: 0.09 },
+ },
+ },
+ usage: { input_tokens: 180, output_tokens: 0 },
+ });
+ },
+ });
+
+ assert.equal(sent.model, "laya");
+ assert.equal(result.model, "laya:en");
+ assert.equal(result.modelVerified, true);
+ assert.deepEqual(result.usage, { input_tokens: 180, output_tokens: 0 });
+});
+
test("local System One requests never forward OpenRouter credentials", async () => {
const provider = resolveDecisionProvider({
JEV_SOCIAL_SYSTEM_ONE_URL: "http://localhost:8009/v1/systemone",