Open-source, local-first social media research agent for Instagram, TikTok, and LinkedIn. Jev routes read-only steps; socai CLI captures cited browser evidence.
JavaScript agent-skillsai-agentsbrowser-agentbrowser-automationdecision-modeldeep-researchinstagramjevlinkedinlocal-firstopen-sourceosintresearch-agentsocaisocial-listeningsocial-mediasocial-media-researchsocmintsystem-onetiktok
Harden platform routing guardrails (#57)
Asklvcd7158bb4583
diff --git a/src/classifier.js b/src/classifier.jsindex 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.jsindex 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.jsindex 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.jsindex 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",