agentlinkops 0.6.8 → 0.6.10

package/src/citations/browser/shims/utils.js

@@ -4,12 +4,19 @@
 export {
   PROVIDER_NO_OUTPUT_TIMEOUT_MS,
   PROVIDER_FORCE_EXIT_STABLE_MS,
-  PROVIDER_EDITOR_SELECTORS,
   PROVIDER_SUBMIT_BTN_SELECTORS,
   PROVIDER_RESPONSE_GENERATION_SELECTORS,
   RETRYABLE_ERRORS,
 } from '../gen/utils/agent-constants.js';
-import { PROVIDER_MODEL_RESPONSE_SELECTORS as vendoredResponseSelectors } from '../gen/utils/agent-constants.js';
+import { PROVIDER_MODEL_RESPONSE_SELECTORS as vendoredResponseSelectors, PROVIDER_EDITOR_SELECTORS as vendoredEditorSelectors } from '../gen/utils/agent-constants.js';
+
+// Anonymous composer observed 2026-09-25: a plain textarea (#mobile-composer-prompt,
+// name="prompt"). None of the vendored ChatGPT selectors match it; without these the engine
+// reached it only through the broad shadow-DOM fallback.
+export const PROVIDER_EDITOR_SELECTORS = Object.freeze({
+  ...vendoredEditorSelectors,
+  chatgpt: Object.freeze(['textarea#mobile-composer-prompt', 'textarea[name="prompt"]', ...vendoredEditorSelectors.chatgpt]),
+});
 
 // Anonymous surface observed 2026-09-20: conversation LI, distinct from its
 // user sibling, with response actions. Never select the conversation itself.

package/src/citations/login.js

@@ -8,7 +8,9 @@
 // it's never synced to the hosted service, and `citation logout ENGINE`
 // removes it. This is the CLI-own-browser posture — the user's account,
 // their risk, their data.
-import { mkdir, writeFile, rm, chmod } from 'node:fs/promises';
+import * as fs from 'node:fs/promises';
+import { rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
@@ -25,6 +27,44 @@ const ENGINE_URLS = Object.freeze({
   bing: 'https://www.bing.com/',
 });
 
+async function saveSession(sessionDir, engineName, state, { sessionFs = fs, platform = process.platform } = {}) {
+  const fail = () => Object.assign(new Error('Session storage requires a real private directory (0700) and regular private files (0600). Choose private storage and remove symbolic links.'), { code: 'PRIVATE_STORAGE_REQUIRED' });
+  const privateMode = (info, mode) => platform === 'win32' || (info.mode & 0o7777) === mode;
+  await sessionFs.mkdir(sessionDir, { recursive: true, mode: 0o700 });
+  const directory = await sessionFs.lstat(sessionDir);
+  if (!directory.isDirectory() || !privateMode(directory, 0o700)) throw fail();
+  const sessionPath = join(sessionDir, `${engineName}.json`);
+  const inspect = async () => {
+    try {
+      const info = await sessionFs.lstat(sessionPath);
+      if (!info.isFile() || !privateMode(info, 0o600)) throw fail();
+      return info;
+    } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  };
+  const previous = await inspect();
+  const temporary = join(sessionDir, `.${engineName}.${randomUUID()}.tmp`);
+  let handle, owned = false;
+  try {
+    handle = await sessionFs.open(temporary, 'wx', 0o600); owned = true;
+    const info = await handle.stat();
+    if (!info.isFile() || !privateMode(info, 0o600)) throw fail();
+    await handle.writeFile(JSON.stringify(state, null, 2));
+    await handle.sync();
+    await handle.close(); handle = undefined;
+    const currentDirectory = await sessionFs.lstat(sessionDir);
+    if (!currentDirectory.isDirectory() || !privateMode(currentDirectory, 0o700) || currentDirectory.dev !== directory.dev || currentDirectory.ino !== directory.ino) throw fail();
+    const current = await inspect();
+    if (Boolean(current) !== Boolean(previous) || (current && ['dev', 'ino', 'size', 'mtimeMs'].some(key => current[key] !== previous[key]))) {
+      throw Object.assign(new Error('The saved session changed during login. Retry without another session writer.'), { code: 'SESSION_CHANGED' });
+    }
+    await sessionFs.rename(temporary, sessionPath); owned = false;
+    return sessionPath;
+  } finally {
+    await handle?.close().catch(() => {});
+    if (owned) await sessionFs.unlink(temporary).catch(() => {});
+  }
+}
+
 export async function loginEngine({ engineName, timeoutMs = 180_000, runtime = {} }) {
   const url = ENGINE_URLS[engineName];
   if (!url) {
@@ -80,10 +120,7 @@ export async function loginEngine({ engineName, timeoutMs = 180_000, runtime = {
   // (anonymous surfaces don't need login, and the adapter handles both).
   const state = await context.storageState();
   const sessionDir = runtime.sessionDir ?? SESSIONS_DIR;
-  await mkdir(sessionDir, { recursive: true, mode: 0o700 });
-  const sessionPath = join(sessionDir, `${engineName}.json`);
-  await writeFile(sessionPath, JSON.stringify(state, null, 2), { mode: 0o600 });
-  await chmod(sessionPath, 0o600);
+  const sessionPath = await saveSession(sessionDir, engineName, state, runtime);
 
   return {
     engine: engineName,

package/src/discovery/contract.js

@@ -64,7 +64,7 @@ export const DiscoveryQuery = z.strictObject({
   row_limit: count.min(1).max(DISCOVERY_LIMITS.rows),
 }).superRefine((q, ctx) => {
   const url = validatePublicUrl(q.target_kind === 'domain' ? `https://${q.target}/` : q.target);
-  if (!url.valid || (q.target_kind === 'domain' ? url.hostname !== q.target || q.target.startsWith('www.') : url.url !== q.target))
+  if (!url.valid || (q.target_kind === 'domain' ? url.hostname !== q.target : url.url !== q.target))
     ctx.addIssue({ code: 'custom', message: 'Invalid or noncanonical discovery target.', path: ['target'] });
   if (q.target_kind === 'exact_url' && q.include_subdomains)
     ctx.addIssue({ code: 'custom', message: 'Exact URL scope cannot include subdomains.', path: ['include_subdomains'] });

package/src/response-shaping.js

@@ -0,0 +1,58 @@
+// DP-0036-T15: response shaping. A list or report command whose rows carry evidence has a
+// reviewed CONCISE projection: the fields an agent needs to decide and to call next, with the
+// observation facts the unknown-versus-absent rule depends on always kept (state, uncertain,
+// the latest attempt and its reason, the last verified observation). MCP and code mode default
+// to concise; REST and the CLI default to detailed; every caller can ask for either with
+// `format`. Rows only are projected: top-level envelope fields (cursors, coverage, counts,
+// reservations, run and inventory metadata) are never dropped. Rules: AGENT-SURFACE-CONTRACT.md.
+
+export const FORMATS = ['concise','detailed'];
+
+const pick = (row, keys) => Object.fromEntries(keys.filter(key => row[key] !== undefined).map(key => [key, row[key]]));
+// The evidence core of an observation_state or an attempt: never more than these, never less.
+const attempt = value => value && typeof value === 'object' ? pick(value, ['state','reason','checkedAt','httpStatus','occurrenceCount','checkerVersion']) : value;
+export function conciseObservationState(state) {
+  if (!state || typeof state !== 'object') return state ?? {};
+  const out = pick(state, ['state','uncertain','checked_at','reason','confirmedState','lastChangedAt','firstAbsentAt','consecutiveAbsent','nextCheckAt','lastSuccessfulAt','lastHealthyAt','firstUnavailableAt','unavailableCount','retryNotBefore']);
+  if (state.latestAttempt !== undefined) out.latestAttempt = attempt(state.latestAttempt);
+  if (state.lastSuccessfulObservation !== undefined) out.lastSuccessfulObservation = attempt(state.lastSuccessfulObservation);
+  if (state.lastSuccessfulObservationSameAsLatestAttempt !== undefined) out.lastSuccessfulObservationSameAsLatestAttempt = state.lastSuccessfulObservationSameAsLatestAttempt;
+  return out;
+}
+const withState = (row, keys) => ({ ...pick(row, keys), observation_state: conciseObservationState(row.observation_state) });
+// An event snapshot (shared/observation-event.js) minus the occurrence list, expectations and
+// signatures: the state, uncertainty, check state, reason, status and timing stay.
+const conciseSnapshot = snapshot => snapshot && typeof snapshot === 'object'
+  ? pick(snapshot, ['state','uncertain','check_state','reason','checked_at','http_status','occurrence_count','occurrences_truncated','source_url','target_url','url','next_check_at','watch_id','target_id'])
+  : snapshot;
+const observationResult = result => result && typeof result === 'object'
+  ? { ...pick(result, ['state','reason','checkedAt','httpStatus','checkerVersion','evidence','redirects']), occurrenceCount: result.occurrenceCount ?? result.occurrences?.length ?? 0 }
+  : result;
+
+// One entry per shaped command: which array holds the rows and how a row is projected. The
+// `keeps` list is what the docs and the tests read; `row` is the projection itself.
+export const SHAPES = {
+  list_rank_history: { rows: 'items', keeps: ['overview_run_id','slot_at','rank','observed_at','retrieved_at','freshness','outcome','execution','cost'],
+    row: r => pick(r, ['overview_run_id','slot_at','rank','observed_at','retrieved_at','freshness','outcome','execution','cost']) },
+  list_link_watches: { rows: 'items', keeps: ['id','source_url','target_url','status','state','observation_state','next_check_at','local_reference'], row: r => withState(r, ['id','source_url','target_url','status','state','next_check_at','local_reference']) },
+  list_targets: { rows: 'items', keeps: ['id','url','status','state','observation_state','next_check_at'], row: r => withState(r, ['id','url','status','state','next_check_at']) },
+  get_target_placements: { rows: 'items', keeps: ['id','source_url','target_url','target_scope','status','state'], row: r => pick(r, ['id','source_url','target_url','target_scope','status','state']) },
+  list_check_jobs: { rows: 'items', keeps: ['id','state','type','watch_id','target_id','attempt_count','error_code','created_at','completed_at'], row: r => pick(r, ['id','state','type','watch_id','target_id','attempt_count','error_code','created_at','completed_at']) },
+  get_history: { rows: 'items', keeps: ['id','state','reason','checked_at','job_id','evidence_key','result (state, reason, checkedAt, httpStatus, checkerVersion, evidence, redirects, occurrenceCount)'], row: r => ({ ...pick(r, ['id','state','reason','checked_at','job_id','evidence_key']), result: observationResult(r.result) }) },
+  list_events: { rows: 'events', keeps: ['id','type','watch_id','target_id','created_at','cursor','data (before and after snapshots without occurrences, expectations and signatures; observation_id; evidence_key)'], row: r => ({ ...pick(r, ['id','type','watch_id','target_id','created_at','cursor']), data: r.data && typeof r.data === 'object' ? { ...pick(r.data, ['observation_id','evidence_key']), ...(r.data.before !== undefined ? { before: conciseSnapshot(r.data.before) } : {}), ...(r.data.after !== undefined ? { after: conciseSnapshot(r.data.after) } : {}) } : r.data }) },
+  list_discovery_candidates: { rows: 'items', keeps: ['id','source_url','target_url','anchor','dofollow','provider_last_seen','verification_status','verified_at','observation_id'], row: r => pick(r, ['id','source_url','target_url','anchor','dofollow','provider_last_seen','verification_status','verified_at','observation_id']) },
+  list_competitor_inventory_rows: { rows: 'items', keeps: ['id','source_url','target_url','anchor','dofollow','provider_last_seen','verification_status','observation_id','member_role'], row: r => pick(r, ['id','source_url','target_url','anchor','dofollow','provider_last_seen','verification_status','observation_id','member_role']) },
+  get_candidate_verification_batch: { rows: 'items', keeps: ['ordinal','candidate_id','local_reference','job_id','watch_id','state','error_code','observation','usage'], row: r => pick(r, ['ordinal','candidate_id','local_reference','job_id','watch_id','state','error_code','observation','usage']) },
+};
+export const SHAPED_COMMANDS = Object.keys(SHAPES);
+
+// Apply the requested (or defaulted) format. Detailed returns the data untouched apart from
+// `defaults_applied`; concise projects the rows. Both formats say which defaults were applied.
+export function shapeResponse(name, data, { format = null, defaultFormat = 'detailed' } = {}) {
+  const shape = SHAPES[name];
+  if (!shape || !data || typeof data !== 'object' || Array.isArray(data)) return data;
+  const applied = format ?? defaultFormat;
+  const defaults = format ? {} : { format: defaultFormat };
+  if (applied !== 'concise' || !Array.isArray(data[shape.rows])) return { ...data, defaults_applied: defaults };
+  return { ...data, [shape.rows]: data[shape.rows].map(row => row && typeof row === 'object' ? shape.row(row) : row), defaults_applied: defaults };
+}

package/src/tool-views.js

@@ -3,7 +3,7 @@
 // script, the MCP router, the CLI index and the generators all read the same definitions.
 // Rules: docs/technical/AGENT-SURFACE-CONTRACT.md (DP-0036).
 
-export const TOOLSETS = ['monitoring','evidence','discovery','library','competitors','reports','workspace','notifications','webhooks','admission','disavow','lifecycle','digests'];
+export const TOOLSETS = ['monitoring','evidence','rank','discovery','baseline','library','competitors','reports','workspace','notifications','webhooks','admission','disavow','lifecycle','digests'];
 
 // One line per toolset: what the group is for. Printed by the site brief, the REST index and the
 // catalog snapshot so the same wording reaches every client; a toolset without a summary is a
@@ -15,7 +15,9 @@ export const TOOLSET_SUMMARIES = {
   digests: 'Own-address digest preferences, delivery history and exact events.',
   monitoring: 'Watch earned links and destination URLs: create, list, update, import, export, recheck.',
   evidence: 'What a check observed: histories, snapshots, change feeds, check jobs, published contacts.',
+  rank: 'Synthetic DataForSEO rank schedules and dated history; hosted collection disabled.',
   discovery: 'Import candidate rows, read stored runs, verify selected candidates, enroll them.',
+  baseline: 'Scoped backlink baselines; supplier admission disabled.',
   library: 'Read and export the coverage-stated opportunity library.',
   competitors: 'Competitor sets, dated inventories, scheduled refresh, gap and domain-mix reports.',
   reports: 'Profile, anchor and report summaries over the tracked dataset.',
@@ -58,7 +60,7 @@ export function oneLiner(description, max = 60) {
 export function manifestText(entries, { max = 36 } = {}) {
   const groups = new Map(TOOLSETS.map(t => [t, []]));
   for (const entry of entries) (groups.get(entry.toolset) ?? groups.set(entry.toolset, []).get(entry.toolset)).push(entry);
-  const lines = ['Commands by toolset (name: what it does). Use search_tools or describe_tools for the full schema before calling.'];
+  const lines = ['Commands by toolset (name: what it does). On /mcp use exec: `exec search <words>`, `exec describe <name>`, `exec call <name> <json>`; the CLI mirrors the verbs as `agentlinkops tools | describe | call`.'];
   for (const [toolset, members] of groups) {
     if (!members.length) continue;
     lines.push(`\n${toolset}:`);
@@ -94,11 +96,34 @@ export const CODE_TOOLS = [
 ];
 export const CODE_LIMITS = { outputChars:24000, timeoutMs:30000, maxCalls:200 };
 
+// DP-0059: the default view's single exec tool. One definition carries the whole registry: the
+// agent searches, inspects and calls commands through CLI-style strings instead of loading
+// schemas upfront (the pattern PostHog's MCP shipped and we adopted). The definition lives here
+// beside META_TOOLS and CODE_TOOLS so the measurement script counts the real shape the router
+// registers; the four meta tools remain registered on /mcp for direct calls by clients that
+// learned them, unlisted.
+export const EXEC_TOOL = {
+  name: 'exec',
+  description: 'Run any AgentLinkOps command through one CLI-style command string: search finds commands by task, describe shows an exact schema, call runs it (reads and writes, under this connection\'s scopes). Find with search, describe once, then call and reuse the schema; never guess a schema. One command per call; several exec calls can run in parallel.',
+  readOnly: false,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      command: {
+        type: 'string', minLength: 1, maxLength: 8000,
+        description: 'CLI-style command. Verbs: search [--toolset T] [--limit N] <words>; tools [toolset]; describe [--output-schema] [--examples] <name>...; schema <name> [<field.path>]; call [--json] <name> <json_input>. --json returns full rows instead of the concise projection. A schema larger than the context budget is summarized; drill any field carrying a hint with schema <name> <field.path>. Unknown name: run search <words>.',
+      },
+    },
+    required: ['command'],
+    additionalProperties: false,
+  },
+};
+
 // Views. `entries` carry name, toolset, tier, readOnly and (from tool-exposure.js) unavailable.
 // An unavailable command stays a member of its views: it is listed with its marker, never
 // hidden, so a client that calls it gets the stable configuration error rather than not-found.
 export const VIEW_BUDGETS = {
-  default: { definitions:12, tokens:6000 },
+  default: { definitions:1, tokens:3500 },
   toolset: { definitions:22, tokens:8000 },
   code: { definitions:3, tokens:2000 },
   manifest: { tokens:2500 },
@@ -108,7 +133,9 @@ export function viewMembers(entries, view) {
   const core = visible.filter(e => e.tier === 'core');
   if (view === 'all') return visible;
   if (view === 'readonly') return visible.filter(e => e.readOnly);
-  if (view === 'default') return core;
+  // DP-0059: the default view lists exactly one tool, exec. Every command (core tier included)
+  // stays registered and callable there through exec call and by a direct tools/call.
+  if (view === 'default') return [];
   if (view === 'code') return [];
   const m = /^toolset:([a-z]+)(:readonly)?$/.exec(view);
   if (!m) throw new Error(`Unknown view ${view}`);