@skillerr/protocol 0.6.0

package/dist/extract.js

@@ -0,0 +1,299 @@
+/**
+ * Multi-skill identification → scaffold extraction for agents.
+ *
+ * Segmentation is an agent/adapter responsibility. This module does not invent
+ * skills from free prose: the caller must supply candidate topics. It emits
+ * incomplete SkillContract / SkillSource scaffolds plus completeness reports
+ * so create flows stay coherent with SkillContract 0.5 and refuse incomplete
+ * release compiles.
+ */
+import { createHash } from "node:crypto";
+import { assessSkillContract, scaffoldSkillContract } from "./authoring.js";
+import { PROTOCOL_VERSION } from "./types.js";
+function slugify(title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64);
+    return slug || "skill-candidate";
+}
+function candidateId(title, index) {
+    const digest = createHash("sha256")
+        .update(`${index}:${title}`)
+        .digest("hex")
+        .slice(0, 12);
+    return `cand_${digest}`;
+}
+function normalizeCandidates(input) {
+    const fromCandidates = input.candidates ?? [];
+    const fromTopics = (input.topics ?? []).map((topic) => typeof topic === "string" ? { title: topic } : topic);
+    const merged = [...fromCandidates, ...fromTopics];
+    const seen = new Set();
+    const out = [];
+    for (const item of merged) {
+        const title = typeof item.title === "string" ? item.title.trim() : "";
+        if (!title)
+            continue;
+        const key = title.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ ...item, title });
+    }
+    return out;
+}
+function parseJourney(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw new Error('extract expects JSON object { summary, candidates|topics: [...] }. Run: skill agent-guide');
+    }
+    const obj = raw;
+    const summary = typeof obj.summary === "string"
+        ? obj.summary
+        : typeof obj.journey_summary === "string"
+            ? obj.journey_summary
+            : "";
+    if (!summary.trim()) {
+        throw new Error("extract requires a redacted journey summary string (summary or journey_summary).");
+    }
+    return {
+        kind: "redacted_journey",
+        summary: summary.trim(),
+        redacted: obj.redacted !== false,
+        sensitivity: obj.sensitivity === "private" ||
+            obj.sensitivity === "shareable_redacted" ||
+            obj.sensitivity === "public"
+            ? obj.sensitivity
+            : "shareable_redacted",
+        candidates: Array.isArray(obj.candidates)
+            ? obj.candidates
+            : undefined,
+        topics: Array.isArray(obj.topics)
+            ? obj.topics
+            : undefined,
+    };
+}
+function seedContract(title, intent, skillKind, sensitivity) {
+    const scaffold = scaffoldSkillContract();
+    scaffold.title = title;
+    scaffold.intent =
+        intent?.trim() ||
+            `__required__: state the transferable intent for “${title}” (what an agent must do).`;
+    if (skillKind)
+        scaffold.skill_kind = skillKind;
+    scaffold.sensitivity = sensitivity;
+    return scaffold;
+}
+function sourceScaffold(args) {
+    return {
+        kind: "skill_source",
+        id: args.id,
+        hash: `sha256:${"0".repeat(64)}`,
+        title: args.title,
+        summary: args.summary,
+        intent: args.contract.intent,
+        contract: args.contract,
+        candidates: undefined,
+        sections: [],
+        steering: [],
+        prompts: [],
+        code_refs: [],
+        parents: [],
+        agent: {
+            host: args.host,
+            deployment: "unknown",
+        },
+        journey: {
+            summary: args.summary,
+            redacted: true,
+            sensitivity: args.sensitivity,
+        },
+        inputs_declared: "inferred",
+        sensitivity: args.sensitivity,
+        created_at: new Date(0).toISOString(),
+        actor: { id: "agent" },
+        source_protocol_version: PROTOCOL_VERSION,
+        source_refs: args.evidenceRefs.map((ref, i) => ({
+            product: "extract",
+            kind: "evidence",
+            id: `ev_${i + 1}`,
+            hash: ref,
+        })),
+    };
+}
+const PROTOCOL_RULES = [
+    "Identify distinct transferable skills from the redacted journey; do not collapse unrelated topics into one skill.",
+    "One skill workspace per candidate (skill init in its own directory).",
+    "Fill a SkillContract 0.5 for each skill; section prose alone cannot satisfy release completeness.",
+    "Run skill status / skill contract-check; refuse release compile when incomplete.",
+    "Never invent filler declarations to force a mint; use continuity checkpoint for partial handoff.",
+    "Secrets stay as {{refs}} / env refs; journey text must stay redacted.",
+];
+const CREATE_PATH = [
+    "skill agent-guide",
+    "Identify N candidate skills → write redacted_journey.json with summary + candidates|topics",
+    "skill extract redacted_journey.json -o ./extraction",
+    "For each selected candidate: mkdir workspace && cd workspace && skill init --title \"…\"",
+    "Copy/adapt contract scaffold → complete every declaration (or explicit none/not_applicable)",
+    "skill journey --summary \"…\" && skill propose … (evidence sections)",
+    "skill contract-check .skill/… or contract.json --profile release",
+    "skill status → skill compile -m \"…\" --approve --mint  (or checkpoint if incomplete)",
+];
+/**
+ * Emit incomplete SkillContract/SkillSource scaffolds for agent-identified candidates.
+ * Does not invent topics from free prose when candidates/topics are absent.
+ */
+export function extractSkillCandidates(raw, options = {}) {
+    const journey = parseJourney(raw);
+    const profile = options.profile ?? "release";
+    const host = options.host ?? "__set_SKILL_HOST__";
+    const candidates = normalizeCandidates(journey);
+    if (candidates.length === 0) {
+        throw new Error("No skill candidates supplied. Identify distinct skills from the journey, then pass candidates:[{title,evidence_refs?}] or topics:[\"…\"]. See: skill agent-guide");
+    }
+    const scaffolds = candidates.map((item, index) => {
+        const id = item.id?.trim() || candidateId(item.title, index);
+        const evidence = item.evidence_refs?.filter((r) => typeof r === "string" && r.trim()) ??
+            [];
+        if (evidence.length === 0) {
+            evidence.push(`journey:${slugify(item.title)}`);
+        }
+        const contract = seedContract(item.title, item.intent, item.skill_kind, journey.sensitivity ?? "shareable_redacted");
+        const assessment = assessSkillContract(contract, profile);
+        const candidate = {
+            id,
+            title: item.title,
+            evidence_refs: evidence,
+            assessment,
+            // Incomplete scaffold is intentional; do not claim a complete contract.
+            contract: undefined,
+        };
+        const workspace_slug = slugify(item.title);
+        const missing = assessment.issues.map(({ field, message, fix }) => ({
+            field,
+            message,
+            fix,
+        }));
+        const source = sourceScaffold({
+            id: `src_${id.replace(/^cand_/, "")}`,
+            title: item.title,
+            summary: journey.summary,
+            contract,
+            evidenceRefs: evidence,
+            sensitivity: journey.sensitivity ?? "shareable_redacted",
+            host,
+        });
+        return {
+            candidate,
+            contract_scaffold: contract,
+            source_scaffold: source,
+            workspace_slug,
+            missing,
+            next_steps: [
+                `mkdir -p ${workspace_slug} && cd ${workspace_slug} && export SKILL_HOST=${host === "__set_SKILL_HOST__" ? "cursor" : host} && skill init --title ${JSON.stringify(item.title)}`,
+                "Complete contract_scaffold into a real SkillContract 0.5 (every declaration explicit).",
+                `skill contract-check contract.json --profile ${profile}`,
+                'skill journey --summary "…" && skill propose --json \'[…]\'',
+                "skill status — refuse release compile until complete; use skill checkpoint for handoff.",
+            ],
+        };
+    });
+    return {
+        kind: "skill_extraction",
+        protocol_version: PROTOCOL_VERSION,
+        profile,
+        journey_summary: journey.summary,
+        redacted: journey.redacted !== false,
+        candidate_count: scaffolds.length,
+        scaffolds,
+        protocol: {
+            one_workspace_per_skill: true,
+            refuse_release_if_incomplete: true,
+            rules: PROTOCOL_RULES,
+            create_path: CREATE_PATH,
+        },
+    };
+}
+/** Alias for adapters that prefer "segment" vocabulary. */
+export const segmentJourney = extractSkillCandidates;
+/** Structured agent-facing create / multi-skill protocol (also printed by CLI). */
+export function agentCreateGuide() {
+    return {
+        kind: "skill_agent_guide",
+        protocol_version: PROTOCOL_VERSION,
+        purpose: "Create portable .skill packages with SkillContract 0.5. Identify multiple skills from a conversation when warranted; enforce completeness; never fake a release.",
+        rules: PROTOCOL_RULES,
+        identify_multiple_skills: [
+            "Read the redacted journey / work summary. List distinct transferable skills (separate intents, triggers, or runtimes).",
+            "Do not invent a multi-skill auto-pipeline beyond this protocol. You identify; the CLI scaffolds.",
+            "Write JSON: { \"kind\":\"redacted_journey\", \"summary\":\"…\", \"redacted\":true, \"candidates\":[{ \"title\":\"…\", \"evidence_refs\":[\"…\"], \"intent\":\"…\", \"skill_kind\":\"procedure|knowledge|integration\" }] }",
+            "Run: skill extract journey.json -o ./extraction",
+            "Present candidates + missing[] reports to the human. Only proceed on selected skills.",
+            "One directory / one skill init per selected candidate. Never merge unrelated candidates into one workspace.",
+        ],
+        create_one_skill: [
+            "export SKILL_HOST=<your-host-id>",
+            "skill init --title \"…\"",
+            "skill journey --summary \"Redacted human+AI journey…\"",
+            "Complete SkillContract 0.5 (skill contract-template → edit → skill contract-check).",
+            "skill propose --json '[{\"title\":\"…\",\"body\":\"…\",\"type\":\"decision|integration|…\"}]' for evidence sections",
+            "skill status — inspect completeness / missing",
+            "Partial handoff: skill checkpoint -m \"WIP\"",
+            "Release only when complete: skill compile -m \"…\" --approve --mint",
+            "On compile_refused: list missing fields/fixes; do not pack a fake release.",
+        ],
+        ingest: [
+            "skill inspect ./file.skill",
+            "skill validate ./file.skill",
+            "skill verify-trust ./file.skill",
+            "skill load ./file.skill   # continuity resume",
+            "skill run ./file.skill   # dry-run by default",
+        ],
+        cli: [
+            "skill agent-guide [--json]",
+            "skill extract <journey.json> [-o dir] [--profile release|continuity]",
+            "skill segment …          # alias of extract",
+            "skill contract-template",
+            "skill contract-check <contract-or-source.json> [--profile release|continuity]",
+            "skill status",
+        ],
+        refuse: [
+            "Refuse release compile/mint when contract assessment is incomplete.",
+            "Refuse to invent filler skills or filler contract fields to satisfy gates.",
+            "Refuse to create multiple skills in one workspace.",
+            "Refuse to proceed without SKILL_HOST on create/mint paths.",
+        ],
+    };
+}
+/** Human-readable text form of agentCreateGuide (for terminals / AGENT.md parity). */
+export function formatAgentGuide(guide = agentCreateGuide()) {
+    const lines = [
+        `skill agent-guide — Open .skill Protocol v${guide.protocol_version}`,
+        "",
+        guide.purpose,
+        "",
+        "Rules:",
+        ...guide.rules.map((r) => `  - ${r}`),
+        "",
+        "Identify → propose multiple skills:",
+        ...guide.identify_multiple_skills.map((r, i) => `  ${i + 1}. ${r}`),
+        "",
+        "Create one skill (complete or refuse):",
+        ...guide.create_one_skill.map((r) => `  $ ${r}`),
+        "",
+        "Ingest / load / run:",
+        ...guide.ingest.map((r) => `  $ ${r}`),
+        "",
+        "CLI:",
+        ...guide.cli.map((r) => `  $ ${r}`),
+        "",
+        "Refuse when:",
+        ...guide.refuse.map((r) => `  - ${r}`),
+        "",
+    ];
+    return lines.join("\n");
+}
+/** Type guard helper for partial SkillContract assessments on scaffolds. */
+export function assessExtractionScaffold(scaffold, profile = "release") {
+    return assessSkillContract(scaffold.contract_scaffold, profile);
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/** Open .skill Protocol v0.5 — types, constants, authoring APIs, and schemas. */
+export { PROTOCOL_VERSION, CONTAINER_VERSION, WORKFLOW_DIALECT_VERSION, MEDIA_TYPE, MANIFEST_MEDIA_TYPE, DEFAULT_SKILL_POLICY, } from "./types.js";
+export type { SkillCompileProfile, PackageSensitivity, ProvenanceMode, MintStatus, PermanenceAnchorKind, TrustProfile, TrustState, HostClaimBinding, IssuerClass, InputSource, SensitivityLevel, AskWhen, SideEffectClass, CapabilityFallback, KnowledgeItemType, SteeringEffect, WorkflowStepKind, SkillRunStatus, RuntimeMode, CompletenessPart, GenerationUsage, JourneyProvenance, CompletenessReport, JsonSchema, ContentDigest, ProvenanceRef, InputSlot, OutputContract, CapabilityAdapterHint, CapabilityRequirement, SkillPermission, SkillPolicy, SkillDependency, MintRecord, SealedManifestClaims, CreationAttestation, TrustView, PermanenceAnchor, SkillManifest, KnowledgeItem, SteeringConstraint, WorkflowStepBase, InstructStep, PromptStep, ToolStep, TransformStep, BranchStep, IterateStep, DelegateStep, CheckpointStep, HumanDecisionStep, VerifyStep, EmitStep, SubskillStep, WorkflowStep, Workflow, CompilationIssue, CompilationMapping, CompilationReport, SkillPackageFiles, SkillStepRecord, SkillRun, } from "./types.js";
+export { FORBIDDEN_AGENT_HOSTS, AGENT_RUNTIME_MARKER_ENVS, isValidAgentHost, detectAgentRuntimeMarkers, hasAgentRuntimeEvidence, } from "./source.js";
+export { assessSkillContract, scaffoldSkillContract, explainContractAssessment, } from "./authoring.js";
+export { extractSkillCandidates, segmentJourney, agentCreateGuide, formatAgentGuide, assessExtractionScaffold, } from "./extract.js";
+export type { JourneyCandidateInput, RedactedJourneyInput, ExtractionScaffold, ExtractionReport, AgentGuide, } from "./extract.js";
+export type { SkillKind, DeclarationStatus, ExplicitDeclaration, ContractTrigger, InputApproval, ContractInput, ContractPrecondition, ContractStepKind, ContractStep, ContractBranch, ContractHumanDecision, ContractCapability, ContractPermission, ForbiddenAction, ContractOutput, RecoveryEdge, VerificationAssertion, ContractCorrection, ContractEvidence, ContractProvenance, SkillContract, ContractField, ContractIssue, ContractAssessment, SkillCandidate, } from "./contract.js";
+export type { SectionType, SectionAuthor, CodeRef, Attachment, PersonRef, SkillSection, SteeringEvent, PromptVersion, AgentContext, SkillSource, SteeringVerb, CaptureFidelity, } from "./source.js";
+export { recipeToSkillSource } from "./recipe.js";
+export type { IngredientType, VisibilityIntent, RecipeIngredient, Recipe, Skill, } from "./recipe.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+/** Open .skill Protocol v0.5 — types, constants, authoring APIs, and schemas. */
+export { PROTOCOL_VERSION, CONTAINER_VERSION, WORKFLOW_DIALECT_VERSION, MEDIA_TYPE, MANIFEST_MEDIA_TYPE, DEFAULT_SKILL_POLICY, } from "./types.js";
+export { FORBIDDEN_AGENT_HOSTS, AGENT_RUNTIME_MARKER_ENVS, isValidAgentHost, detectAgentRuntimeMarkers, hasAgentRuntimeEvidence, } from "./source.js";
+export { assessSkillContract, scaffoldSkillContract, explainContractAssessment, } from "./authoring.js";
+export { extractSkillCandidates, segmentJourney, agentCreateGuide, formatAgentGuide, assessExtractionScaffold, } from "./extract.js";
+export { recipeToSkillSource } from "./recipe.js";

package/dist/recipe.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Skillerr-shaped Recipe types — product adapter, not protocol vocabulary.
+ *
+ * Open protocol uses SkillSource / SkillSection (see source.ts).
+ * Skillerr (and similar products) map recipe/ingredient/bake → SkillSource/compile.
+ */
+import type { GenerationUsage, JourneyProvenance } from "./types.js";
+import type { SkillContract } from "./contract.js";
+import type { AgentContext, Attachment, CodeRef, PersonRef, PromptVersion, SectionType, SkillSource, SteeringEvent } from "./source.js";
+/** @deprecated Prefer SectionType from source.ts — kept for Skillerr adapters. */
+export type IngredientType = SectionType;
+export type VisibilityIntent = "private" | "publishable";
+export type { SteeringVerb, CaptureFidelity } from "./source.js";
+export type { CodeRef, Attachment, PersonRef, SteeringEvent, PromptVersion } from "./source.js";
+/** @deprecated Prefer SkillSection — Skillerr ingredient shape. */
+export interface RecipeIngredient {
+    id: string;
+    revision: number;
+    type: IngredientType;
+    title: string;
+    body: string;
+    attachments: Attachment[];
+    code_refs: CodeRef[];
+    sensitivity: VisibilityIntent;
+}
+/**
+ * @deprecated Prefer SkillSource.
+ * Recipe is Skillerr's capture document; adapters convert it before compile.
+ */
+export interface Recipe {
+    kind: "recipe";
+    id: string;
+    hash: string;
+    title: string;
+    summary?: string;
+    ingredients: RecipeIngredient[];
+    steering: SteeringEvent[];
+    prompts: PromptVersion[];
+    code_refs: CodeRef[];
+    parents: string[];
+    provenance: {
+        hosts: string[];
+        models: string[];
+        session_ids: string[];
+    };
+    visibility_intent: VisibilityIntent;
+    baked_at: string;
+    baker: PersonRef;
+    source_protocol_version: string;
+    generation_usage?: GenerationUsage;
+    journey_summary?: string;
+    /** Optional 0.5 protocol-native semantics carried through this lossy product adapter. */
+    contract?: SkillContract;
+}
+/** @deprecated Legacy flat markdown skill export. Prefer SkillManifest / `.skill`. */
+export interface Skill {
+    kind: "skill";
+    id: string;
+    version: string;
+    title: string;
+    body: string;
+    sources: Array<{
+        kind: "ingredient" | "recipe" | "section";
+        id: string;
+        revision?: number;
+        hash?: string;
+    }>;
+    exported_at: string;
+    source_protocol_version: string;
+}
+/** Map a Skillerr Recipe into protocol SkillSource. */
+export declare function recipeToSkillSource(recipe: Recipe, overrides?: {
+    agent?: Partial<AgentContext>;
+    journey?: Partial<JourneyProvenance>;
+}): SkillSource;

package/dist/recipe.js

@@ -0,0 +1,74 @@
+/**
+ * Skillerr-shaped Recipe types — product adapter, not protocol vocabulary.
+ *
+ * Open protocol uses SkillSource / SkillSection (see source.ts).
+ * Skillerr (and similar products) map recipe/ingredient/bake → SkillSource/compile.
+ */
+import { isValidAgentHost } from "./source.js";
+function visibilityToSensitivity(v) {
+    return v === "publishable" ? "public" : "private";
+}
+/** Map a Skillerr Recipe into protocol SkillSource. */
+export function recipeToSkillSource(recipe, overrides = {}) {
+    const host = overrides.agent?.host ?? recipe.provenance.hosts[0];
+    if (!isValidAgentHost(host)) {
+        throw new Error("AI agent host required to adapt Recipe → SkillSource. Set a real host (e.g. cursor, claude), not human/cli.");
+    }
+    const sections = recipe.ingredients.map((ing) => ({
+        id: ing.id,
+        revision: ing.revision,
+        type: ing.type,
+        title: ing.title,
+        body: ing.body,
+        attachments: ing.attachments,
+        code_refs: ing.code_refs,
+        sensitivity: visibilityToSensitivity(ing.sensitivity),
+        authored_by: "agent",
+    }));
+    const journey = {
+        summary: overrides.journey?.summary ??
+            recipe.journey_summary ??
+            recipe.summary ??
+            `Human+AI work captured as recipe ${recipe.id}: ${recipe.title}`,
+        open_questions: overrides.journey?.open_questions,
+        decisions: overrides.journey?.decisions ??
+            recipe.ingredients.filter((i) => i.type === "decision").map((i) => i.title),
+        redacted: overrides.journey?.redacted ?? true,
+        sensitivity: overrides.journey?.sensitivity ??
+            (recipe.visibility_intent === "publishable" ? "public" : "shareable_redacted"),
+    };
+    const declaresInputs = recipe.ingredients.some((ing) => /\{\{[a-zA-Z_][a-zA-Z0-9_]*\}\}|<([A-Z][A-Z0-9_]+)>|\$\{[a-zA-Z_][a-zA-Z0-9_]*\}/.test(ing.body));
+    return {
+        kind: "skill_source",
+        id: recipe.id,
+        hash: recipe.hash,
+        title: recipe.title,
+        summary: recipe.summary,
+        intent: recipe.summary ?? recipe.title,
+        contract: recipe.contract ? structuredClone(recipe.contract) : undefined,
+        sections,
+        steering: recipe.steering,
+        prompts: recipe.prompts,
+        code_refs: recipe.code_refs,
+        parents: recipe.parents,
+        agent: {
+            host: host,
+            provider: overrides.agent?.provider,
+            model: overrides.agent?.model ?? recipe.provenance.models[0],
+            runtime: overrides.agent?.runtime,
+            deployment: overrides.agent?.deployment,
+            endpoint: overrides.agent?.endpoint,
+            session_ids: overrides.agent?.session_ids ?? recipe.provenance.session_ids,
+        },
+        journey,
+        generation_usage: recipe.generation_usage,
+        inputs_declared: declaresInputs ? "inferred" : "none",
+        sensitivity: visibilityToSensitivity(recipe.visibility_intent) === "public"
+            ? "public"
+            : "shareable_redacted",
+        created_at: recipe.baked_at,
+        actor: recipe.baker,
+        source_protocol_version: recipe.source_protocol_version,
+        source_refs: [{ product: "skillerr", kind: "recipe", id: recipe.id, hash: recipe.hash }],
+    };
+}

package/dist/source.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Protocol-native source for the skill compiler.
+ *
+ * Products (Skillerr, etc.) may use their own words (ingredient, recipe, bake).
+ * Adapters map those into SkillSource / SkillSection before compile.
+ */
+import type { SkillContract, SkillCandidate } from "./contract.js";
+import type { GenerationUsage, JourneyProvenance, PackageSensitivity } from "./types.js";
+export type SectionType = "prompt" | "decision" | "architecture" | "diagram" | "integration" | "resource" | "reference" | "lesson" | "requirement" | "tradeoff" | "risk" | "question" | "implementation_note" | "config" | "correction_note" | "doc" | "message" | "handoff" | "code" | "intent" | "workflow_note";
+export type SectionAuthor = "agent" | "human_via_agent";
+export interface CodeRef {
+    forge?: string;
+    repo: string;
+    commit?: string;
+    path?: string;
+    range?: string;
+    pr?: number;
+}
+export interface Attachment {
+    id: string;
+    kind: "diagram" | "image" | "config" | "file" | "other";
+    title?: string;
+    content?: string;
+    uri?: string;
+    mediaType?: string;
+}
+export interface PersonRef {
+    id: string;
+    display_name?: string;
+}
+export type SteeringVerb = "affirm" | "correct" | "reject";
+export type CaptureFidelity = "exact" | "synthesize";
+export interface SkillSection {
+    id: string;
+    revision: number;
+    type: SectionType;
+    title: string;
+    body: string;
+    attachments: Attachment[];
+    code_refs: CodeRef[];
+    /** Never embed secret values — sensitivity guides redaction. */
+    sensitivity: PackageSensitivity;
+    /** Declared authoring path for this section. */
+    authored_by: SectionAuthor;
+}
+export interface SteeringEvent {
+    kind: "steering";
+    id: string;
+    session_id: string;
+    verb: SteeringVerb;
+    target_kind: "section" | "turn" | "other" | "ingredient";
+    target_id: string;
+    note?: string;
+    actor: PersonRef;
+    at: string;
+}
+export interface PromptVersion {
+    kind: "prompt";
+    id: string;
+    lineage_id: string;
+    version: number;
+    body: string;
+    origin: "user" | "ai_generated" | "imported";
+    parent_version?: number;
+    session_id?: string;
+    created_at: string;
+}
+/** Required AI agent identity for any compile path. */
+export interface AgentContext {
+    /** Host/app that ran the agent: cursor | ollama | lmstudio | custom-agent | … */
+    host: string;
+    /** Model provider/runtime family; provider-neutral and local-friendly. */
+    provider?: string;
+    model?: string;
+    runtime?: string;
+    /** Where inference ran. This is provenance, not proof. */
+    deployment?: "local" | "hosted" | "hybrid" | "unknown";
+    /** Optional endpoint identifier. Must not contain credentials. */
+    endpoint?: string;
+    session_ids?: string[];
+}
+/**
+ * Protocol input to the compiler.
+ * Products adapt their capture model into this shape.
+ */
+export interface SkillSource {
+    kind: "skill_source";
+    id: string;
+    hash: string;
+    title: string;
+    summary?: string;
+    intent?: string;
+    /**
+     * 0.5 source of truth for transferable semantics. A missing contract marks
+     * a 0.4-compatible text source and is release-lossy.
+     */
+    contract?: SkillContract;
+    /** Optional extraction candidates. Segmentation belongs to an adapter/AI, not the compiler. */
+    candidates?: SkillCandidate[];
+    sections: SkillSection[];
+    steering: SteeringEvent[];
+    prompts: PromptVersion[];
+    code_refs: CodeRef[];
+    parents: string[];
+    agent: AgentContext;
+    journey: JourneyProvenance;
+    generation_usage?: GenerationUsage;
+    /** Explicitly declare that the source needs no runtime inputs. */
+    inputs_declared?: "inferred" | "none";
+    sensitivity: PackageSensitivity;
+    created_at: string;
+    actor: PersonRef;
+    source_protocol_version: string;
+    /** Optional product-specific source refs (e.g. Skillerr recipe id). */
+    source_refs?: Array<{
+        product: string;
+        kind: string;
+        id: string;
+        hash?: string;
+    }>;
+}
+/**
+ * Hosts that are not valid AI agent runtimes for skill creation / mint.
+ * Humans exporting SKILL_HOST=cli|shell|manual must never mint as an agent.
+ */
+export declare const FORBIDDEN_AGENT_HOSTS: Set<string>;
+export declare function isValidAgentHost(host: string | undefined | null): boolean;
+/**
+ * Process / mint markers that indicate an agent runtime path (not a bare human shell).
+ * These are still spoofable by a determined local process — residual risk remains —
+ * but a human who only exports SKILL_HOST=cursor without any agent context fails this check.
+ */
+export declare const AGENT_RUNTIME_MARKER_ENVS: readonly ["CURSOR_AGENT", "CURSOR_TRACE_ID", "COMPOSER_SESSION_ID", "SKILL_AGENT_INVOCATION", "SKILL_SESSION_ID", "CLAUDE_CODE_ENTRYPOINT", "AIDER_ACTIVE"];
+export declare function detectAgentRuntimeMarkers(env?: Record<string, string | undefined>): string[];
+export declare function hasAgentRuntimeEvidence(evidence?: {
+    markers?: string[];
+    session_id?: string;
+} | null, env?: Record<string, string | undefined>): boolean;

package/dist/source.js

@@ -0,0 +1,69 @@
+/**
+ * Protocol-native source for the skill compiler.
+ *
+ * Products (Skillerr, etc.) may use their own words (ingredient, recipe, bake).
+ * Adapters map those into SkillSource / SkillSection before compile.
+ */
+/**
+ * Hosts that are not valid AI agent runtimes for skill creation / mint.
+ * Humans exporting SKILL_HOST=cli|shell|manual must never mint as an agent.
+ */
+export const FORBIDDEN_AGENT_HOSTS = new Set([
+    "",
+    "human",
+    "manual",
+    "none",
+    "cli",
+    "user",
+    "shell",
+    "bash",
+    "zsh",
+    "sh",
+    "fish",
+    "powershell",
+    "pwsh",
+    "cmd",
+    "terminal",
+    "console",
+    "tty",
+    "stdin",
+    "keyboard",
+    "local-shell",
+    "human-cli",
+    "operator",
+]);
+export function isValidAgentHost(host) {
+    if (!host)
+        return false;
+    return !FORBIDDEN_AGENT_HOSTS.has(host.trim().toLowerCase());
+}
+/**
+ * Process / mint markers that indicate an agent runtime path (not a bare human shell).
+ * These are still spoofable by a determined local process — residual risk remains —
+ * but a human who only exports SKILL_HOST=cursor without any agent context fails this check.
+ */
+export const AGENT_RUNTIME_MARKER_ENVS = [
+    "CURSOR_AGENT",
+    "CURSOR_TRACE_ID",
+    "COMPOSER_SESSION_ID",
+    "SKILL_AGENT_INVOCATION",
+    "SKILL_SESSION_ID",
+    "CLAUDE_CODE_ENTRYPOINT",
+    "AIDER_ACTIVE",
+];
+export function detectAgentRuntimeMarkers(env = process.env) {
+    const found = [];
+    for (const key of AGENT_RUNTIME_MARKER_ENVS) {
+        const v = env[key];
+        if (v !== undefined && String(v).trim() !== "")
+            found.push(key);
+    }
+    return found;
+}
+export function hasAgentRuntimeEvidence(evidence, env = process.env) {
+    if (evidence?.session_id && evidence.session_id.trim())
+        return true;
+    if (evidence?.markers?.some((m) => m.trim()))
+        return true;
+    return detectAgentRuntimeMarkers(env).length > 0;
+}