agentlinkops 0.6.9 → 0.6.10

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.',