ContractSpec docs

OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

All-in-one example · Company Intelligence Scout

Build cited company intelligence from eligible public web sources.

The Scout discovers companies, services, products, missions, goals, locations, jobs, professional people, and eligible public contact points while keeping collection and outreach behind explicit policy.

Mission

Concrete mission

Research companies matching a query, normalize their cited facts into Company Intelligence records, surface conflicts and gaps, and prepare policy-eligible recruiting or sales support without making hiring decisions.

Run the deterministic fixture

bun run --cwd packages/examples/agent-application-foundation \
  example:company-intelligence-scout
import {
  runCompanyIntelligenceScoutExample,
} from "@lssm-tech/example.agent-application-foundation/company-intelligence-scout";

const result = await runCompanyIntelligenceScoutExample({
  mode: "fixture",
  query: "European infrastructure companies hiring TypeScript engineers",
  topology: "vercel-railway-supabase",
  policy: {
    purposes: ["recruiting"],
    autonomyMode: "draft-only",
    lawfulBasisRef: "policy://example/research-purpose",
    noticePolicyRef: "policy://example/privacy-notice",
    retentionDays: 30,
    allowedDomains: ["acme.example"],
    maxPagesPerDomain: 20,
    minimumRequestDelayMs: 1_000,
    maxContactsPerRun: 10,
    outboundDailyLimit: 0,
    killSwitchRefs: ["control://tenant/scout"],
  },
});

console.log(result.recordPacket);
console.log(result.readiness.status); // "candidate"

End-to-end workflow

Profile, offering, jobs, people/contact, and independent-verification subagents emit source, evidence, entity, relation, claim, conflict, gap, graph, and edition records.

query + purpose + policy + seed domains
  → discover candidate companies
  → check domain, robots, access, and crawl budget
  → bounded HTTPS fetch or approved dynamic render
  → profile, offering, job, people/contact subagents
  → independent evidence verification
  → Company Intelligence records, conflicts, gaps, and edition
  → policy-controlled research or outreach disposition
  → durable refresh, deletion, and governed improvement

Reuse the Company Intelligence model

The Scout projects into the existing Company Intelligence contracts instead of creating a parallel knowledge model. It deduplicates companies, jobs, people, and contacts while leaving ambiguous identities unresolved for review.

Choose the autonomy boundary

The default is draft-only. Automated hiring decisions, candidate rejection, job applications, protected-trait inference, and sensitive-data enrichment are outside the example.

research-only

Create cited intelligence records without outreach material.

draft-only · default

Prepare recruiting or sales drafts for a person to review and send separately.

approval-bound-send

Send only after recipient-level approval, suppression checks, and an exactly-once receipt.

autonomous-send

Requires explicit high-risk tenant policy, lawful-purpose references, notice policy, provider allowlisting, caps, audit, budgets, and kill switches.

Inject live providers explicitly

Fixture mode never crawls the public internet or sends outreach. Live discovery, rendering, suppression, and outreach remain consumer-supplied ports.

import type {
  CompanyScoutPorts,
} from "@lssm-tech/example.agent-application-foundation/company-intelligence-scout";

const ports: CompanyScoutPorts = {
  discovery: consumerDiscoveryAdapter,
  fetcher: ssrfSafePublicHttpsAdapter,
  renderer: approvedPlaywrightAdapter,
  suppression: consumerSuppressionRegistry,
  outreach: governedOutreachProvider,
};

// Live mode fails closed unless policy and required ports are supplied.
await runCompanyIntelligenceScoutExample({
  mode: "live",
  query,
  seedUrls,
  policy,
  ports,
});
bun run --cwd packages/examples/agent-application-foundation \
  example:company-intelligence-scout:live -- \
  --policy ./company-scout.policy.json \
  --ports-module ./company-scout.ports.ts \
  --seed-url https://allowed-company.example

Web and personal-data safety

Robots and access boundaries

Follow RFC 9309, fail closed on ambiguity, and never bypass authentication, CAPTCHA, paywalls, or access controls.

SSRF-resistant fetching

Allow HTTPS only; reject private, link-local, loopback, and metadata addresses; revalidate every redirect; bound redirects, bodies, pages, and time.

Prompt-injection isolation

Page content is untrusted data and cannot grant identity, authority, approval, tools, capabilities, or policy changes.

Evidence is mandatory

Every retained fact or contact carries a source URL, locator, digest, observation time, confidence, and usage eligibility.

Contact eligibility

Every retained contact needs cited evidence and usage eligibility. Ambiguous or private-context contacts require review and cannot enter autonomous outreach.

Retention and rights

Refresh or delete person and contact records after 30 days and preserve correction, deletion, suppression, revocation, tombstone, and audit workflows.

Telemetry minimization

Exclude sensitive traits, inferred protected attributes, page bodies, contacts, prompts, and credentials from telemetry.

Continuous operation

Continuous operation stays bounded

Leases, crawl and outreach budgets, retries, cancellation, replay, audited dead letters, refresh schedules, and kill switches constrain every loop. The result reports record projections, conflicts, gaps, extraction receipts, and outreach dispositions.

Runtime portability stays explicit

The same compiled contracts target Workflow DevKit or the isolated EVE adapter. EVE remains preview maturity, so inspect its declared capability losses before promotion.

Authoritative policy references

Public visibility does not make personal data unrestricted. Consumers own purpose, lawful basis, transparency, rights handling, and jurisdiction-specific compliance.

Readiness boundary

Candidate, not qualified

Fixture evidence cannot qualify live crawling, identity, retention, suppression, outreach, provider, isolation, or incident controls. Run the complete live suite for the exact deployed plan.