@audienti/cli 0.1.145 → 0.2.0-exora.2

package/skills/audienti/references/helpers.md

@@ -0,0 +1,149 @@
+# Helpers and installation
+
+Read the installed package version with `skills show audienti --json`. Node 24.22.1 is the repository's supported runtime. The helper
+scripts use only Node built-ins and need no network, login or provider credentials.
+The CLI/MCP adapter uses the dependencies shipped with the CLI distribution.
+
+Use the complete versioned skills/audienti directory included in the CLI archive. For Codex, place this
+directory under your configured `.agents/skills/audienti` directory. For Claude
+Code, use its `.claude/skills/audienti` location. Installation is an explicit local
+action; no command here installs a plugin, grants access or modifies credentials.
+For another Node-capable agent, retain the directory structure and invoke
+`scripts/run.mjs`. To use local MCP, run `node cli/audienti.mjs mcp` from the extracted CLI directory
+through the host's stdio configuration. The server exposes `skills_list`,
+`skills_show`, `skills_profile_queries`, `skills_profile_candidates`,
+`skills_profile_completeness` and `skills_profile_evidence` without
+account authentication; existing CRM/tools still check their own credentials.
+
+`skills show audienti --json` publishes each helper's input/output JSON schema and
+a digest of this package. Inputs have a 1 MiB cap. Unknown fields and helper names
+are rejected. Use `--file -` to read bounded JSON from standard input. JSON errors
+never echo supplied values. Outputs go to stdout; choose private output storage
+if retaining personal data. No automatic transcript or credential store is created.
+
+## profile-queries
+
+Input: `{ "kind": "social", "profile": { "displayName": "Avery Example",
+"companyName": "Example Studio", "companyDomain": "example.org",
+"title": "Founder", "handles": ["avery.example"] } }`.
+
+`kind` is `social`, `email` or `website`; optional `mode` is `broad` (default) or
+`attachable`, reflecting V10's query network gates, not a promise that every
+network has a supported enrichment adapter. Facts are supplied by the agent;
+the helper never fetches a company or canonicalizes an identity.
+
+Output has `version`, `queries` and `missing`. An empty query list means there is
+not enough usable context; it is not a research result. Optional name fallback
+uses `prospectName` for social queries only. Email/website queries and candidate
+name scoring require `displayName`. Social handle permutations are search terms, not profile IDs.
+
+## profile-candidates
+
+Input: `{ "profile": { "displayName": "Avery Example" }, "candidates": [
+{ "url": "https://example.org/team", "title": "Avery Example", "snippet": "Founder",
+"domain": "example.org" } ], "limit": 12 }`.
+
+At most 80 results, at most 12 returned candidates. Supply optional `profileId`
+only from an actual CRM response for that exact candidate URL; never reuse the
+anchor Profile ID for unconfirmed candidates. Canonical-reference dedup uses that ID; otherwise
+dedup is exact URL string equality. The helper does not infer identity from URLs.
+`saved_reference` means the input supplied an ID, not independently verified access.
+
+V10 advisory weights are name .4, company-domain .3, known-source .2, social-domain
+.1, text overlap .15. Its legacy substring domain feature is preserved for ranking;
+it is not a trust or matching check. Scores below .4 suggest skipping, above .7
+suggest inspecting the page; otherwise inspect available snippets. You choose and
+invoke any subsequent tool yourself. Dedup keeps the first supplied item, ranking
+ties preserve input order. `duplicatesRemoved` and `omitted` explain truncation.
+
+Port reference: V10 commit 915cae248a4e8698e5ef773f9624249481f1a0ce,
+`profiles/expansion/query_builder.rb`, `result_scorer.rb`,
+`profiles/social_query_planner.rb` and `config/web_search_queries.yml`.
+Database selections in V10 are supplied input facts here. No V10 production data,
+Rails callbacks, paid-provider orchestration or final identity matcher is bundled.
+
+## Supplying facts
+
+Map the saved Prospect's projection name to displayName, title to title, and bio
+or description to the matching helper field. Profiles expose canonicalUrl and
+providerId; a known LinkedIn URL can be supplied as linkedinReference, its known
+vanity segment as linkedinSlug. Supply handles only when observed; do not derive
+identity from guessed handles. Choose companyName/companyDomain from the CRM's
+selected employment relationship and its company projection. companyDomain must
+be a bare hostname such as example.org, not a URL. Missing facts stay omitted.
+
+The ranking helper uses each candidate's supplied domain for all domain signals;
+it does not extract a hostname from url. Supply the observed hostname explicitly
+when available. These signals only prioritize inspection and confer no trust.
+
+HTTP clients can read the public catalog at GET /api/v1/skills and the complete
+artifact at GET /api/v1/skills/audienti. Check the version and digest before saving
+the returned files locally. Reading the artifact does not execute a helper.
+Agents need a local Node environment or the local stdio MCP server to execute
+these helpers; an HTTP-only client cannot execute them through this API.
+
+To check the file digest, iterate artifact.files in its supplied order. Feed SHA-256
+UTF-8 bytes for path, a NUL byte, the decimal UTF-8 content byte length, another
+NUL byte, then the content, for each file. Compare the lowercase hex result with
+digest. This detects changed contents; it is not an authenticity signature. Get
+artifacts from your trusted installation or the expected HTTPS API origin.
+
+## profile-completeness
+
+Input: `{ "requiredFields": ["name", "websites"], "fields": [
+{ "name": "name", "state": "available" },
+{ "name": "websites", "state": "absent" } ] }`.
+
+`fields` is required; use `[]` when the saved read did not report states.
+Map `profiles.enrich.operation.result.fieldStates` (or the legacy
+`profiles.fetch.result.fieldStates`) to the helper's `fields` array of
+`{name,state}` entries using the actual provider field names (`about`,
+`websites`, not projection names `bio` or a made-up `website`); do not manufacture an
+`available` state because a name or URL seems plausible. Required field names are
+selected by the agent for the task. The output preserves `available` and known
+`absent` separately. `needsEvidence` reports unavailable, truncated, unreported
+or conflicting supplied states, in requested order with duplicate names removed.
+Contradictory reports never get resolved by input order.
+
+`allFieldsKnown` means every required field has one supplied available/absent
+state. It does not establish freshness, fit, identity, cache eligibility or cost.
+An absent field is not a reason to automatically purchase another lookup. The
+server alone owns the 30-day cache and paid admission. A truncated requested field
+can cause `profile_fields_truncated`: omit that requirement or explicitly choose
+a paid refresh; never refresh automatically. Saved Profile list/get results do
+not report these states. Missing reports remain `not_reported`. This helper applies the
+accepted Exora field-state contract to V10's required-field planning pattern; it
+does not port CompanyCitationEnricher's hidden company calls or employer selection.
+
+## profile-evidence
+
+Input: `{ "profileId": "<optional saved Profile UUID>",
+"observationId": "<optional observation UUID>", "platform": "twitter",
+"bio": "Founder. See https://example.org and @colleague",
+"websiteUrl": "https://example.org" }`.
+
+Returns exact observed URL candidates and lowercase mention handles with their
+input fields. Exact duplicate URLs combine their field references. The source IDs
+are merely supplied references: they do not prove access or trusted provenance.
+The explicit website link is considered first so a long bio cannot crowd it out.
+Every output is `caller_supplied`, even when the caller claims a verified source.
+A mention is not a resolved Profile URL. No links are fetched or canonicalized,
+no provider IDs guessed, and no citations or identity attachments are written.
+
+V10 source: `profiles/writer.rb#extract_citations_from_bio` and
+`#extract_citations_from_website_url`, and `utils/text_scanner.rb` at the pinned
+commit above. Portable tests reuse its URL and Twitter/Reddit/Instagram fixtures.
+This package stops before V10's URL parser/citation writer: use explicit CRM
+normalization and evidence operations after inspecting the actual target. It
+accepts absolute HTTP(S) links only; other website values remain unresolved.
+Email addresses and URL text are excluded from mention extraction so they do not
+become invented social identities. URLs with userinfo or recognized credential parameter names (including OAuth
+fragments and signed-URL keys) are omitted, with `rejectedLinks` reported. This
+is not a guarantee that arbitrary secrets hidden in URLs can be detected; never
+put secrets in any helper input.
+
+Each result caps links and mentions at 50, with omitted counts. Bio input is at
+most 10,000 characters; URLs at most 2,048. Oversize mention handles are counted
+as omitted. Empty text returns empty candidates, not a research success. Relevant
+source text and its observation time stay in the original evidence record; these
+candidates are preparation for the agent's next explicit step.

package/skills/audienti/references/profile-workflows.md

@@ -0,0 +1,212 @@
+# Agent-owned profile workflows
+
+The agent runs these recipes. Each search, retrieval, AI judgment and contact
+purchase is an explicit agent action. The helper scripts do not chain tools and
+the CRM does not run a hidden research job. Read the installed schemas and selected
+workspace permissions; do not invent flags from prose. Keep an
+[agent research receipt](workflow-receipt.md), including incomplete work.
+
+First read saved records with `prospect_list`/`prospect_get` and
+`profile_list`/`profile_get` (CLI `prospects list|get`, `profiles list|get`).
+These search the selected workspace's saved records. External search is a separate
+explicit call to `profiles.discover`; legacy `profiles.search` has those same paid
+external semantics. Query builders and candidate scores are planning aids.
+
+## Enrich a known Profile
+
+1. Resolve a supplied URL or saved Profile ID against saved records. Use the
+   current Prospect ID returned by the server; do not infer identity from a name.
+2. Decide which fields the task needs. Pass prior supplier `fieldStates` to
+   `profile-completeness`; saved list/get projections do not report them, so use
+   `fields:[]` when no such report exists. Use actual field names such as `about`
+   and `websites`. Known absence is not an automatic refresh request.
+3. For supported LinkedIn person/company URLs or authorized saved Profile IDs,
+   call `profiles.enrich` explicitly with stable request ID and required fields.
+   This finds/creates the source Profile, saves its facts, resolves existing
+   canonical identity and returns its Prospect and visible Profile page. The
+   server reuses complete workspace data for 30 days; `refresh:true` deliberately
+   buys a new lookup and is subject to current paid admission.
+4. Inspect `operation` for status and billing. `prospect`, `profilesPage`,
+   `projectionStatus` and `projectionReadAt` are a separate current authorized CRM
+   read. The `prospect` value is a detail object: its canonical ID is
+   `prospect.prospect.id`; `matchedProfileId` identifies the enriched source
+   Profile. Page with `prospect_get` if more profiles are needed. Do not treat a
+   historical paid result's Prospect ID as current ownership after correction.
+5. On interrupted/running work, inspect the operation and retry with the exact
+   original ID/input/principal. If projection is unavailable, retry free saved
+   reads. Never buy another lookup to recover a response. Expired evidence,
+   truncated fields and unsupported networks remain explicit gaps.
+
+`profiles.fetch` remains the legacy flat paid-operation result. Its admission is
+shared with `profiles.enrich`, which wraps that operation with the current CRM
+read; changing names never buys a second attempt. Likewise `profiles.discover`
+and legacy `profiles.search` share admission. A new completed-cache call and a
+same-request replay are different events even when both are free.
+
+## Find people through an audience or question
+
+1. Read the caller's scope: selected workspace, audience/role criteria, company
+   filters, questions, time window, requested count and tool/budget limits. Use
+   saved audience definitions when supplied. Missing evidence remains unknown;
+   do not pool different people or companies to satisfy a conjunction.
+2. Search saved records first. Choose an available research mechanism explicitly:
+   compatible agent search/browsing, `web.search`, or `profiles.discover` using its
+   actual supported input schema. Unsupported audience filters must be evaluated
+   separately from retained evidence, not invented as provider arguments.
+3. Inspect primary sources and dates. A current official source may establish a
+   present state; a retrieved historical event is not automatically current. A
+   failed retrieval, search miss or JavaScript shell is not evidence of absence.
+4. Select relevant identities, then use the enrichment recipe or submit attributed
+   externally acquired Profile facts through `prospect_record_observation`.
+   Preserve producing skill version, source URL/time and actual response IDs.
+   Contact lookup, optional `decide`, classification and further retrieval require
+   their own deliberate agent calls. No automatic email/mobile finding or send.
+5. Compare sourced company/role/question judgments to the brief, preserving
+   counterevidence. Record observations/interpretations with the shared evidence
+   owner. The server's exact qualification operation, when requested, owns
+   admission to an experiment; a helper score or this receipt is not admission.
+6. Continue until requested scope/count, agreed budget/time limit or documented
+   source exhaustion. Return supported findings plus pending/rejected/unknown
+   records and next actions; one completed search batch is not completion.
+
+This adapts the existing signal-prospect-research method's separation of scope,
+primary-source evidence, current state, unknown answers and unfinished work. It
+adds no parallel CRM rule engine or automatic research executor.
+
+## Find people through a topic, post and its participants
+
+1. Reuse a saved topic with `topics_list`/`topics_get`, or deliberately create one
+   with `topics_create`. A topic is saved context, not proof of a person's intent.
+2. Explicitly search/fetch a relevant post with `posts.search`/`posts.fetch`,
+   supplying the selected topic ID when supported. Keep the returned topic/post
+   IDs and immutable evidence references; local report references are not CRM IDs.
+3. Explicitly retrieve `posts.comments` or `posts.reactions` and follow requested
+   pages. These time-scoped pages retrieve fresh data; they do not use the
+   30-day Profile cache. Same-request replay remains safe. A valid empty page is
+   distinct from malformed data and can still have verified supplier expense and
+   a customer charge. Report partial pages and unknown observation times.
+4. Read the observed author/participant references and evidence. Choose whom to
+   inspect as the agent; a reaction alone does not prove pain, fit, buying intent
+   or consent. Incoming interactions do not establish outgoing engagement history.
+5. Enrich the selected participant with an explicit call, or record compatible
+   external research as attributed evidence. Preserve post/topic/interaction
+   provenance using supported citation/evidence operations and actual stored IDs.
+6. Read back the current Prospect and visible Profiles before reporting saved
+   results. Keep observation and interpretation separate. Do not silently buy
+   contacts, invoke AI, send outreach or install another research tool.
+
+## Expand an identity into additional Profiles
+
+1. Read the anchor and visible Profiles. Take selected employer/title from the
+   CRM relationship projection; do not silently choose an employer from scraped
+   text. Read required field states rather than assuming a saved name is complete.
+2. Run `profile-queries` on supplied context, then explicitly execute selected
+   searches within scope. `social` uses V10 network gates; `website` and `email`
+   prepare query text only. The queries themselves do not buy contact data.
+3. Pass supplied results to `profile-candidates` to prioritize inspection. Scores,
+   inferred domains, handles and legacy `trusted_source` weights are advisory.
+   Inspect promising sources explicitly. `profile-evidence` extracts supplied
+   links/mentions without fetching, canonicalizing or certifying them.
+4. Search saved workspace Profiles for a candidate's actual URL/ID. Keep an
+   unconfirmed candidate separate from the anchor. Record an independently
+   observed candidate only with its own actual source identity; omit the anchor
+   `prospectId` from observation intake. That intake is not a speculative
+   candidate inbox and must not be used to force an attachment.
+5. Explicitly enrich if needed and supported. Hosted profile retrieval supports
+   LinkedIn people and companies. Other networks can have attributed externally
+   obtained facts; a query mentioning a network does not imply a hosted adapter.
+6. If the server exposes `profile_match_evaluate`, evaluate the saved anchor and
+   candidate IDs. CLI: `profiles match evaluate SOURCE_ID CANDIDATE_ID`. This is a
+   free deterministic check, not a provider call. The first supported cross-network
+   rule requires a forward link from SOURCE to CANDIDATE. SOURCE must be a
+   supported LinkedIn Profile with a provider ID and a succeeded supplier
+   snapshot in this workspace. Its payload must be unexpired, its retrieval
+   under 30 days old, and its `websites` state `available` with the candidate's
+   current canonical URL listed. The newest snapshot for that source identity
+   controls the result; an older positive link cannot override newer evidence.
+   Reversing the two arguments does not reverse the evidence. A GitHub-to-LinkedIn
+   link or a caller-reported bio/image link cannot satisfy this release's rule.
+   `insufficient_evidence` / `no_current_verified_direct_link` means the proof is
+   missing, stale or unsupported; it does not mean different people. If current
+   retrieval is justified, explicitly choose a supported paid enrichment/refresh
+   within the user's budget, then reevaluate. Otherwise keep the candidate
+   unconfirmed and record the missing evidence. Never refresh automatically.
+   `identity_kind_conflict`, `contradictory_provider_id` and `staff_separation`
+   are conflicts, not a reason to force an attachment or bypass the guard.
+   Caller citations,
+   text, images, scores and a shared name do not make that evidence trusted.
+7. On `match`, explicitly call `profile_match_apply` with the exact evaluation
+   digest and new stable request ID. CLI: `profiles match apply SOURCE_ID
+   CANDIDATE_ID --evaluation-digest HASH --request-id UUID`. The server rechecks
+   current evidence/authority, chooses the compatible canonical owner and records
+   lineage. `already_associated` needs no new merge. Keep returned IDs.
+8. On changed state, reread and reevaluate; a new reviewed input needs a new
+   request ID. On uncertain apply completion, retry the exact original ID/input
+   first, never silently change its digest. `insufficient_evidence` and `conflict`
+   are not attachments. Decide whether further explicit research can resolve them.
+   Active staff separation cannot be overridden by a workspace agent. Mistaken
+   global associations require a verified global administrator's reviewed browser
+   resolution; this skill grants no such authority and cannot call that path.
+9. Read the Prospect and its visible Profiles. `profile_identity_history` (CLI
+   `profiles history RESOLUTION_ID`) returns only this workspace's movement
+   history, oldest first, at most 100 rows with an explicit truncation flag.
+   When truncated, newer movements may be unavailable in that response. Use the
+   apply response's `resolutionId`; `already_associated` may return null because
+   no new movement was recorded. It does not reveal
+   global staff notes or other workspaces. A historical apply receipt is distinct
+   from current identity state after a later correction.
+
+Inspect installed client descriptors and server capability before using match
+operations. An older server/client may not implement them; report the capability
+gap and retain the research rather than forcing an observation association.
+A person and company remain separate typed Prospects linked by citations.
+
+## Evidence, cost and safe resumption
+
+Use shared observation/citation/evidence/qualification owners and their live
+schemas. Other research tools are welcome; their submissions remain attributed
+to the caller, never forged supplier receipts or verified identity flags.
+Preserve unknown fields, contrary sources, producing version and coverage limits.
+Every CRM identifier comes from a server result, not a URL or local helper ref.
+
+For `prospect_record_evidence` with `kind:interpretation`, `data` accepts
+`conclusion`, optional `reason`, and optional `evidenceIds` only. Use actual saved
+observation IDs; a citation ID or local receipt reference is not an observation.
+Keep topic/post context in the existing saved graph, the reason and the local
+receipt, rather than inventing extra `data` keys. For example, replace every
+bracketed value with the selected workspace or a returned server ID:
+
+```json
+{
+  "workspaceId": "<selected workspace UUID>",
+  "requestId": "<new stable request UUID>",
+  "subject": { "kind": "person", "prospectId": "<current canonical Prospect UUID>" },
+  "kind": "interpretation",
+  "data": {
+    "conclusion": "Investigate; engagement alone does not establish fit.",
+    "reason": "State the retained source context and any missing page coverage.",
+    "evidenceIds": ["<retained observation UUID>"]
+  },
+  "sourceUrl": "https://example.org/observed-source",
+  "observedAt": null,
+  "skill": { "id": "audienti", "version": "1.3.0" }
+}
+```
+
+`observedAt:null` means unknown, not now. Signal evidence has its own live
+`signalId`/`result`/`details` contract; an interpretation is not a qualification
+or experiment admission.
+
+For operation recovery, use CLI `tools runs get OPERATION_ID` / `tools runs list`
+or MCP `tools_runs_get` / `tools_runs_list`. Paid primitive MCP names use `tools_`
+plus dots replaced by underscores, for example `tools_profiles_enrich` and
+`tools_posts_comments`; saved-record and identity operation names are the explicit
+names shown above, not this prefix rule.
+
+Keep exact paid request IDs, inputs, operation IDs, status, usage and reported
+charge/retrieval provenance. Read current balance through the existing tools.
+New paid tasks stop at zero or below; admitted small work can overdraw. The agent
+must not recreate tariffs or reserve balances. Core reads/evidence remain free
+under normal workspace authorization, even when using compatible external tools
+at zero hosted credits. No request, credential or billing information belongs in
+an unprotected public report. Never include bearer/proxy/provider secrets.

package/skills/audienti/references/workflow-receipt.md

@@ -0,0 +1,49 @@
+# Agent research receipt
+
+Keep a local research receipt as the agent performs explicit steps. This is a
+reporting convention, not a new CRM object or permission. Never include bearer
+tokens, proxy credentials or raw provider secrets. Use the installed tool schemas
+for requests; this receipt does not define replacement API payloads.
+
+Record the producing skill ID/version, selected workspace ID and requested scope.
+For each finding keep:
+
+- Its local reference, distinct from server-issued Prospect, Profile, observation,
+  topic and post IDs. Do not manufacture a CRM ID from a URL or local reference.
+- The observed fact, source URL and observation time (or explicitly unknown time).
+  Keep the agent's interpretation separate. A reaction is not evidence of a buyer
+  problem, intent or consent to contact.
+- Acquisition provenance: which explicit tool returned it, its operation/request
+  ID when available, and the evidence reference actually stored in the CRM.
+  An alternative research tool's result remains caller-attributed evidence.
+- Current identity status comes from a fresh authorized `profile_get` /
+  `prospect_get`: saved independently, currently associated, or unconfirmed.
+  Record that read's time and returned canonical ID. A match/apply receipt is a
+  historical mutation event; replay can return it after a staff correction and
+  cannot confirm present ownership. A helper score or mention never confirms
+  identity. If the installed server lacks the guarded operations, preserve the
+  candidate and report the capability gap.
+- Coverage limits, missing fields, pagination not retrieved, truncated content and
+  time uncertainty. Incoming comments/reactions on a post do not establish an
+  author's outgoing engagement history.
+
+For paid calls retain the exact request ID and normalized input you sent, plus the
+returned operation ID, terminal status and billing result. If the response is lost,
+read that operation or replay the same request; do not invent a new ID. Do not count
+an alias or request replay as an additional purchase. A cached result is distinct
+from replaying an operation. Current CRM projection is distinct from paid history.
+
+When resuming with a new skill version, retain the original producing version on
+existing evidence and assessments. New interpretations get new evidence and their
+actual producing version. Report an unavailable tool or exhausted scope as a gap;
+do not silently install software, buy contact data, invoke AI or send outreach.
+
+Read back the selected workspace's Prospect, visible profiles and saved evidence
+before reporting persistence. Unconfirmed candidate URLs remain in this report;
+never use observation intake with the anchor Prospect ID to force an association.
+
+This convention follows the distinction between local references, CRM identities,
+interaction evidence and incomplete coverage in the separately maintained
+Audienti profile-audience-targeting and profile-engagement-targeting marketplace
+skills. Those packages have separate publication ownership and are not installed
+or executed by this package.

package/skills/audienti/scripts/contracts.mjs

@@ -0,0 +1,72 @@
+export const SKILL_VERSION = '1.3.0';
+export const MAX_INPUT_BYTES = 1024 * 1024;
+const text = maxLength => ({ type: 'string', maxLength });
+const object = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+const array = (items, maxItems) => ({ type: 'array', items, maxItems });
+const uuid = { type: 'string', pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' };
+const profile = object({
+  displayName: text(300), prospectName: text(300), companyName: text(300),
+  companyDomain: text(253), title: text(500), bio: text(10000), headline: text(1000),
+  description: text(10000), linkedinReference: text(1024), linkedinSlug: text(200),
+  handles: array(text(200), 12),
+});
+const candidate = object({
+  url: { ...text(2048), minLength: 1 }, title: text(1000), snippet: text(10000),
+  domain: text(253), profileId: uuid, prospectId: uuid,
+}, ['url']);
+const query = object({ query: text(16000), kind: { enum: ['email', 'website', 'social'] } }, ['query', 'kind']);
+const ranked = object({
+  ...candidate.properties, score: { type: 'number' }, signals: array(text(40), 5),
+  identityStatus: { enum: ['saved_reference', 'unresolved'] },
+  suggestedAction: { enum: ['inspect_page', 'inspect_snippet', 'skip_low_score'] },
+}, ['url', 'score', 'signals', 'identityStatus', 'suggestedAction']);
+export const helperContracts = {
+  'profile-completeness': {
+    description: 'Summarize supplied field states for research planning. Known absence stays distinct from missing evidence. Does not determine cache eligibility, billing or authority.',
+    inputSchema: object({ requiredFields: array({ ...text(80), minLength: 1 }, 40), fields: array(object({ name: { ...text(80), minLength: 1 }, state: { enum: ['available', 'absent', 'unavailable', 'truncated'] } }, ['name', 'state']), 80) }, ['requiredFields', 'fields']),
+    outputSchema: object({ version: { const: SKILL_VERSION }, authority: { const: 'planning_only' }, allFieldsKnown: { type: 'boolean' }, available: array(text(80), 40), absent: array(text(80), 40), needsEvidence: array(object({ field: text(80), state: { enum: ['unavailable', 'truncated', 'not_reported', 'conflicting'] } }, ['field', 'state']), 40) }, ['version', 'authority', 'allFieldsKnown', 'available', 'absent', 'needsEvidence']),
+  },
+  'profile-evidence': {
+    description: 'Extract bounded observed URL and mention candidates from supplied profile text using V10 text rules. Caller-attributed evidence only; no fetch, canonicalization, attachment or identity decision.',
+    inputSchema: object({ profileId: uuid, observationId: uuid, platform: { enum: ['twitter', 'x', 'reddit', 'instagram', 'facebook', 'linkedin', 'tiktok', 'youtube', 'threads', 'github', 'medium'] }, bio: text(10000), websiteUrl: text(2048) }),
+    outputSchema: object({ version: { const: SKILL_VERSION }, authority: { const: 'caller_supplied' }, profileId: uuid, observationId: uuid, links: array(object({ url: text(2048), fields: array({ enum: ['bio', 'websiteUrl'] }, 2) }, ['url', 'fields']), 50), mentions: array(object({ platform: text(40), handle: text(200), field: { const: 'bio' } }, ['platform', 'handle', 'field']), 50), rejectedLinks: { type: 'integer', minimum: 0 }, omittedLinks: { type: 'integer', minimum: 0 }, omittedMentions: { type: 'integer', minimum: 0 } }, ['version', 'authority', 'links', 'mentions', 'rejectedLinks', 'omittedLinks', 'omittedMentions']),
+  },
+  'profile-queries': {
+    description: 'Prepare bounded V10-derived profile search queries from supplied facts. Does not search or call the CRM.',
+    inputSchema: object({ profile, kind: { enum: ['social', 'email', 'website'] }, mode: { enum: ['broad', 'attachable'] } }, ['profile', 'kind']),
+    outputSchema: object({ version: { const: SKILL_VERSION }, queries: array(query, 5), missing: array(text(80), 2) }, ['version', 'queries', 'missing']),
+  },
+  'profile-candidates': {
+    description: 'Rank at most 80 supplied results using V10 advisory weights; deduplicate references without claiming an identity match.',
+    inputSchema: object({ profile, candidates: array(candidate, 80), limit: { type: 'integer', minimum: 1, maximum: 12 } }, ['profile', 'candidates']),
+    outputSchema: object({ version: { const: SKILL_VERSION }, candidates: array(ranked, 12), duplicatesRemoved: { type: 'integer', minimum: 0 }, omitted: { type: 'integer', minimum: 0 } }, ['version', 'candidates', 'duplicatesRemoved', 'omitted']),
+  },
+};
+
+// This validator serves only the closed, bundled schemas above. It accepts no
+// caller-provided schema, references, regular expressions or executable code.
+export function validateInput(name, value) {
+  const contract = Object.hasOwn(helperContracts, name) && helperContracts[name];
+  if (!contract) throw new Error('Unknown bundled helper.');
+  function visit(schema, item) {
+    const invalid = () => { throw new Error('Invalid helper input; inspect the bundled input schema.'); };
+    if (schema.enum && !schema.enum.includes(item)) invalid();
+    if (schema.type === 'object') {
+      if (!item || typeof item !== 'object' || Array.isArray(item)) invalid();
+      if (Object.keys(item).some(key => !Object.hasOwn(schema.properties, key))) invalid();
+      if (schema.required.some(key => !Object.hasOwn(item, key))) invalid();
+      for (const [key, child] of Object.entries(item)) visit(schema.properties[key], child);
+    } else if (schema.type === 'array') {
+      if (!Array.isArray(item) || item.length > schema.maxItems) invalid();
+      for (const child of item) visit(schema.items, child);
+    } else if (schema.type === 'string') {
+      if (typeof item !== 'string' || item.length > (schema.maxLength ?? Infinity) || item.length < (schema.minLength ?? 0)) invalid();
+      if (schema.pattern && !new RegExp(schema.pattern).test(item)) invalid();
+    } else if (schema.type === 'integer') {
+      if (!Number.isInteger(item) || item < schema.minimum || item > schema.maximum) invalid();
+    }
+  }
+  visit(contract.inputSchema, value);
+  if (Buffer.byteLength(JSON.stringify(value), 'utf8') > MAX_INPUT_BYTES) throw new Error('Helper input exceeds 1 MiB.');
+  return value;
+}

package/skills/audienti/scripts/profile-helpers.mjs

@@ -0,0 +1,138 @@
+import { SKILL_VERSION, validateInput } from './contracts.mjs';
+
+const broadNetworks = ['x.com', 'twitter.com', 'linkedin.com/in', 'instagram.com', 'facebook.com', 'github.com', 'medium.com', 'youtube.com', 'tiktok.com', 'threads.net', 'reddit.com'];
+const attachableNetworks = ['x.com', 'twitter.com', 'linkedin.com/in', 'instagram.com', 'facebook.com', 'tiktok.com', 'reddit.com', 'youtube.com'];
+const stopwords = new Set('a an and are as at be but by for if in into is it no not of on or such that the their then there these they this to was will with from via over under'.split(' '));
+const trustedSources = ['rocketreach.co', 'apollo.io', 'hunter.io', 'clearbit.com', 'zoominfo.com', 'lusha.com'];
+const socialSources = ['twitter.com', 'instagram.com', 'facebook.com', 'linkedin.com', 'github.com', 'medium.com', 'youtube.com', 'tiktok.com', 'threads.net', 'reddit.com'];
+const term = value => (value ?? '').replaceAll('"', ' ').replace(/\s+/g, ' ').trim();
+const unique = values => [...new Set(values.filter(Boolean))];
+const quoted = value => `"${term(value)}"`;
+const personName = value => {
+  const name = term(value), tokens = name.split(' ');
+  return /^[\p{L}\s'.-]+$/u.test(name) && tokens.length >= 2 && tokens.every(token => token.length >= 2) ? name : '';
+};
+
+// Inputs are already selected facts. Employer selection, canonical URL parsing,
+// identity validation and database reads belong to the CRM and the calling agent.
+function queries({ profile, kind, mode = 'broad' }) {
+  const displayName = term(profile.displayName), company = term(profile.companyName), domain = term(profile.companyDomain);
+  let values = [];
+  if (kind === 'social') {
+    const name = personName(displayName) || personName(profile.prospectName);
+    const evidence = unique([company, domain, company && profile.title ? `${term(profile.title)} at ${company}` : '', term(profile.linkedinReference), term(profile.linkedinSlug)]);
+    const gate = (mode === 'broad' ? broadNetworks : attachableNetworks).map(host => `site:${host}`).join(' OR ');
+    if (name) values.push(`${quoted(name)}${evidence.length ? ` (${evidence.map(quoted).join(' OR ')})` : ''} (${gate})`);
+    const handles = unique([...(profile.handles ?? []), profile.linkedinSlug].map(value => term(value).replace(/^@/, '')).filter(value => value.length >= 3 && !/\s|@|:\/\//.test(value) && !/^(seed-|unknown$|profile$)/i.test(value)));
+    const single = [], groups = [];
+    for (const handle of handles) {
+      // V10 keeps LinkedIn opaque IDs case-sensitive; it does not manufacture
+      // permutations of them. Other observed handles supply query variants only.
+      if (/^ACo[A-Za-z0-9_-]+$/.test(handle)) { single.push(handle); continue; }
+      const tokens = handle.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+      if (tokens.length === 1) single.push(tokens[0]);
+      else if (tokens.length) groups.push(tokens);
+    }
+    const variants = unique([...single.sort(), ...['', '-', '_'].flatMap(separator => [...groups].sort((a, b) => a.join(separator) < b.join(separator) ? -1 : a.join(separator) > b.join(separator) ? 1 : 0).map(tokens => tokens.join(separator)))]);
+    const fallback = unique([company, domain, name]);
+    if (variants.length >= 2 && fallback.length) values.push(`(${variants.map(quoted).join(' OR ')}) (${fallback.map(quoted).join(' OR ')}) (${gate})`);
+  } else if (displayName) {
+    if (kind === 'email') {
+      // V10 templates requiring missing values are skipped, not filled with
+      // guessed company identity or fabricated contact details.
+      if (company) values.push(`${displayName} ${company} email`);
+      if (domain) values.push(`${displayName} "@${domain}" email`);
+    } else {
+      values = [`${displayName} website`, `${displayName} about`];
+      if (company) values.push(`${displayName} ${company} contact`);
+    }
+  }
+  values = unique(values).slice(0, 5);
+  return { version: SKILL_VERSION, queries: values.map(query => ({ query, kind })), missing: values.length ? [] : ['usable_profile_search_context'] };
+}
+
+const normalizeName = value => value.toLowerCase().replace(/[-_.]/g, ' ').replace(/ +/g, ' ').trim();
+const tokens = value => new Set(value.toLowerCase().replace(/[^a-z0-9\s]/g, ' ').split(/\s+/).filter(token => token.length >= 3 && !stopwords.has(token)));
+function score(profile, candidate) {
+  const name = normalizeName(profile.displayName ?? ''), parts = name.split(/\s+/);
+  const title = (candidate.title ?? '').toLowerCase(), snippet = (candidate.snippet ?? '').toLowerCase(), domain = (candidate.domain ?? '').toLowerCase();
+  const nameIn = value => name && (normalizeName(value).includes(name) || (parts.length >= 2 && normalizeName(value).includes(parts[0]) && normalizeName(value).includes(parts.at(-1))));
+  let amount = 0; const signals = [];
+  if (nameIn(title) || nameIn(snippet)) { amount += 0.4; signals.push('name_match'); }
+  const companyDomain = (profile.companyDomain ?? '').toLowerCase().replace(/^www\./, '').split('/')[0];
+  // Preserve V10's advisory substring weights, not an authorization predicate.
+  if (companyDomain && domain && (domain.replace(/^www\./, '').split('/')[0] === companyDomain || domain.includes(companyDomain))) { amount += 0.3; signals.push('company_domain'); }
+  if (trustedSources.some(value => domain.includes(value))) { amount += 0.2; signals.push('trusted_source'); }
+  if (socialSources.some(value => domain.includes(value))) { amount += 0.1; signals.push('social_platform'); }
+  const a = tokens([profile.displayName, profile.bio, profile.headline, profile.description].filter(Boolean).join(' ')), b = tokens(`${title} ${snippet}`);
+  const union = new Set([...a, ...b]).size, intersection = [...a].filter(value => b.has(value)).length;
+  if (union && intersection / union >= 0.2) { amount += 0.15; signals.push('text_overlap'); }
+  return { score: Math.round(amount * 100) / 100, signals };
+}
+
+function candidates({ profile, candidates: rows, limit = 12 }) {
+  const seen = new Set(), ranked = []; let duplicatesRemoved = 0;
+  for (const row of rows) {
+    const key = row.profileId ? `profile:${row.profileId}` : `raw:${row.url}`;
+    if (seen.has(key)) { duplicatesRemoved++; continue; }
+    seen.add(key);
+    const result = score(profile, row);
+    ranked.push({ ...row, ...result, identityStatus: row.profileId ? 'saved_reference' : 'unresolved', suggestedAction: result.score < 0.4 ? 'skip_low_score' : result.score > 0.7 ? 'inspect_page' : 'inspect_snippet' });
+  }
+  ranked.sort((a, b) => b.score - a.score);
+  return { version: SKILL_VERSION, candidates: ranked.slice(0, limit), duplicatesRemoved, omitted: Math.max(0, ranked.length - limit) };
+}
+
+function completeness({ requiredFields, fields }) {
+  const available = [], absent = [], needsEvidence = [];
+  for (const field of unique(requiredFields)) {
+    const states = unique(fields.filter(row => row.name === field).map(row => row.state));
+    const state = states.length > 1 ? 'conflicting' : states[0] ?? 'not_reported';
+    if (state === 'available') available.push(field);
+    else if (state === 'absent') absent.push(field);
+    else needsEvidence.push({ field, state });
+  }
+  return { version: SKILL_VERSION, authority: 'planning_only', allFieldsKnown: needsEvidence.length === 0, available, absent, needsEvidence };
+}
+
+// V10 Utils::TextScanner and Profiles::Writer prepare observations. URL identity
+// normalization and authoritative citation/identity writes remain server-owned.
+const observedUrlPattern = /https?:\/\/[^\s<>"')]+/g;
+const sensitiveUrlKey = value => /token$|secret|password|signature|credential|accesskey|^(auth|authorization|key|code|sig|apikey|sas)$/.test(value.replace(/[^a-z0-9]/gi, '').toLowerCase());
+function evidence({ profileId, observationId, platform, bio = '', websiteUrl = '' }) {
+  const links = new Map(); let rejectedLinks = 0;
+  const add = (raw, field) => {
+    const url = raw.trim().replace(/\.$/, '').replace(/,$/, '').replace(/!$/, '');
+    try {
+      const parsed = new URL(url);
+      if (url.length > 2048 || /\s/.test(url) || !['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password || [...parsed.searchParams.keys(), ...new URLSearchParams(parsed.hash.slice(1)).keys()].some(sensitiveUrlKey)) throw new Error();
+    } catch { rejectedLinks++; return; }
+    const fields = links.get(url) ?? [];
+    if (!fields.includes(field)) fields.push(field);
+    links.set(url, fields);
+  };
+  if (websiteUrl.trim()) add(websiteUrl, 'websiteUrl');
+  for (const match of bio.matchAll(observedUrlPattern)) add(match[0], 'bio');
+  let handles = [];
+  if (platform) {
+    // Unlike V10's unbounded @ regex, require a token boundary so an email
+    // address cannot become a proposed social identity. A mention is never a URL.
+    const pattern = platform === 'reddit' ? /\bu\/([A-Za-z0-9_-]+)/g
+      : ['twitter', 'x'].includes(platform) ? /(?<![\p{L}\p{N}_@./])@([A-Za-z0-9_]{1,15})(?![A-Za-z0-9_])/gu
+      : /(?<![\p{L}\p{N}_@./])@([A-Za-z0-9_.]+[A-Za-z0-9_])/gu;
+    const mentionText = bio.replace(observedUrlPattern, ' ');
+    handles = unique([...mentionText.matchAll(pattern)].map(match => match[1].toLowerCase()));
+  }
+  const selectedHandles = handles.filter(handle => handle.length <= 200).slice(0, 50);
+  return { version: SKILL_VERSION, authority: 'caller_supplied', ...(profileId ? { profileId } : {}), ...(observationId ? { observationId } : {}),
+    links: [...links].slice(0, 50).map(([url, fields]) => ({ url, fields })), mentions: selectedHandles.map(handle => ({ platform, handle, field: 'bio' })),
+    rejectedLinks, omittedLinks: Math.max(0, links.size - 50), omittedMentions: handles.length - selectedHandles.length };
+}
+
+export function runHelper(name, input) {
+  validateInput(name, input);
+  if (name === 'profile-queries') return queries(input);
+  if (name === 'profile-candidates') return candidates(input);
+  if (name === 'profile-completeness') return completeness(input);
+  return evidence(input);
+}