@jinn-network/client 0.1.9 → 0.2.0-canary.0b79cd5d

package/dist/vendor/@jinn-network/plugin/dist/plugin.js

@@ -0,0 +1,675 @@
+/**
+ * Host-neutral Stage 1 product workflow. Embedded hosts buffer their session
+ * through `PluginSession`; process hosts pass the already-captured EpisodeV1
+ * to `completeSession`. Both paths persist the same canonical evidence and
+ * contribution contracts.
+ */
+/// <reference types="node" />
+import { createHash, randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { EPISODE_SCHEMA_VERSION, EpisodeV1Schema, EpisodeV1WriteSchema, SessionActivityFactsSchema, } from './schemas/episode.js';
+import { ContributionCandidateV1ProjectionSchema, ContributionCandidateV1Schema, } from './schemas/contribution-candidate.js';
+import { projectKnowledgePacket } from './schemas/knowledge-packet.js';
+import { deriveSearchTerms, discriminatingTerms, rankKnowledgeCandidates, rankScoredKnowledgeHits, scoreKnowledgeRecord, MAX_CONTENT_RESCORE_CANDIDATES, MAX_SELECTED_PACKETS, RELEVANCE_FLOOR, } from './pickup.js';
+import { degraded, ok, unavailable, valueOr } from './outcome.js';
+import { parsePickupConfig } from './schemas/pickup-config.js';
+import { deriveEligibility } from './eligibility.js';
+import { foldExplain, foldHistory } from './history.js';
+async function previewContribution(deps, acknowledge) {
+    let ledger;
+    try {
+        ledger = await deps.contribution.ledger();
+    }
+    catch (error) {
+        return unavailable(`contribution preview failed: ${errorReason(error)}`);
+    }
+    if (ledger.status === 'unavailable')
+        return unavailable(ledger.reason);
+    const rows = ledger.status === 'ok' ? ledger.value : ledger.value ?? [];
+    const row = rows.find((entry) => entry.publicationState === 'preview-required');
+    if (!row) {
+        return ledger.status === 'degraded' ? degraded(ledger.reason, null) : ok(null);
+    }
+    if (!row.repositorySlug || !row.baseCommit) {
+        return unavailable('contribution preview repository facts unavailable');
+    }
+    let publicationState = 'preview-required';
+    if (acknowledge) {
+        let authorization;
+        try {
+            authorization = await deps.contribution.authorize(row.recordId);
+        }
+        catch (error) {
+            return unavailable(`contribution preview acknowledgement failed: ${errorReason(error)}`);
+        }
+        if (authorization.status === 'unavailable')
+            return unavailable(authorization.reason);
+        if (authorization.status === 'degraded') {
+            return degraded(authorization.reason);
+        }
+        publicationState = 'queued';
+    }
+    const value = {
+        recordId: row.recordId,
+        repositorySlug: row.repositorySlug,
+        baseCommit: row.baseCommit,
+        localState: row.localState,
+        publicationState,
+        status: publicationState,
+        acknowledged: acknowledge,
+    };
+    return ledger.status === 'degraded' ? degraded(ledger.reason, value) : ok(value);
+}
+export const JINN_PLUGIN_CONTRACT_VERSION = 1;
+function errorReason(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Titles for `SessionSummary.providedPackets` — the packet's own task summary. */
+function packetTitle(packet) {
+    return { ref: packet.ref, title: packet.task.summary };
+}
+async function completeSession(deps, input, hits = { providedPackets: [] }) {
+    if (input.contractVersion !== JINN_PLUGIN_CONTRACT_VERSION) {
+        throw new Error(`unsupported plugin contract version: ${String(input.contractVersion)}`);
+    }
+    const capturedEpisode = EpisodeV1Schema.parse(input.episode);
+    const activity = SessionActivityFactsSchema.parse(input.activity);
+    const eligibility = deriveEligibility({
+        status: capturedEpisode.outcome.status,
+        verifiabilityTier: capturedEpisode.outcome.verificationStrength,
+        retentionPolicy: capturedEpisode.retention.policy,
+        publicRepo: input.eligibilityInputs.publicRepo,
+        acceptedDiff: input.eligibilityInputs.acceptedDiff,
+    }, capturedEpisode.session.capturedAt);
+    const embeddedCandidateResult = capturedEpisode.contributionCandidate === undefined
+        ? undefined
+        : ContributionCandidateV1ProjectionSchema.safeParse(capturedEpisode.contributionCandidate);
+    const requestCandidateResult = input.contributionCandidate === undefined
+        ? undefined
+        : ContributionCandidateV1Schema.safeParse(input.contributionCandidate);
+    let resolvedCandidate;
+    let contributionUnavailableReason;
+    if ((capturedEpisode.contributionCandidate !== undefined || input.contributionCandidate !== undefined)
+        && capturedEpisode.session.kind === 'host-internal') {
+        contributionUnavailableReason = 'host-internal sessions cannot create contribution candidates';
+    }
+    else if (embeddedCandidateResult && !embeddedCandidateResult.success) {
+        contributionUnavailableReason = 'invalid embedded contribution candidate';
+    }
+    else if (requestCandidateResult && !requestCandidateResult.success) {
+        contributionUnavailableReason = 'invalid contribution candidate';
+    }
+    else {
+        const embeddedCandidate = embeddedCandidateResult?.data;
+        const requestCandidate = requestCandidateResult?.data;
+        if (embeddedCandidate
+            && requestCandidate
+            && !isDeepStrictEqual(embeddedCandidate, requestCandidate)) {
+            contributionUnavailableReason = 'embedded and request contribution candidates must match';
+        }
+        else {
+            resolvedCandidate = requestCandidate ?? embeddedCandidate;
+            if (resolvedCandidate && resolvedCandidate.sourceId !== capturedEpisode.episodeId) {
+                contributionUnavailableReason = 'contribution candidate sourceId must match episodeId';
+                resolvedCandidate = undefined;
+            }
+        }
+    }
+    // A contribution payload must be present before the first immutable evidence
+    // write. Invalid or forbidden payloads are dropped so the session evidence
+    // itself is still retained.
+    const { contributionCandidate: _capturedCandidate, ...capturedWithoutCandidate } = capturedEpisode;
+    const episode = EpisodeV1WriteSchema.parse({
+        ...capturedWithoutCandidate,
+        session: {
+            ...capturedEpisode.session,
+            kind: capturedEpisode.session.kind ?? 'user',
+        },
+        origin: capturedEpisode.origin === 'legacy-unstamped'
+            ? {
+                writer: capturedEpisode.environment.harness.name,
+                build: capturedEpisode.environment.harness.version,
+            }
+            : capturedEpisode.origin,
+        activity,
+        eligibility,
+        ...(resolvedCandidate ? { contributionCandidate: resolvedCandidate } : {}),
+    });
+    let persistence;
+    try {
+        persistence = await deps.evidence.put(episode);
+    }
+    catch (error) {
+        persistence = unavailable(`evidence put failed: ${errorReason(error)}`);
+    }
+    let contribution;
+    if (contributionUnavailableReason) {
+        contribution = unavailable(contributionUnavailableReason);
+    }
+    else if (resolvedCandidate !== undefined) {
+        const persistedEpisodeId = persistence.status === 'unavailable'
+            ? undefined
+            : persistence.value?.episodeId;
+        if (persistedEpisodeId !== episode.episodeId) {
+            contribution = unavailable('contribution reference not recorded because canonical episode persistence was not confirmed');
+        }
+        else {
+            try {
+                contribution = await deps.contribution.recordMineable(resolvedCandidate, input.contributionVetoed ? { publicationState: 'vetoed' } : undefined);
+            }
+            catch (error) {
+                contribution = unavailable(`contribution record failed: ${errorReason(error)}`);
+            }
+            if (contribution.status === 'ok' && input.contributionVetoed === true) {
+                const recordId = contribution.value.recordId;
+                try {
+                    const veto = await deps.contribution.veto(recordId);
+                    contribution = veto.status === 'unavailable'
+                        ? degraded(veto.reason, { recordId })
+                        : veto;
+                }
+                catch (error) {
+                    contribution = degraded(`contribution veto failed: ${errorReason(error)}`, { recordId });
+                }
+            }
+            else if (contribution.status === 'ok') {
+                const recordId = contribution.value.recordId;
+                try {
+                    const snapshot = await deps.contribution.mintStatus(recordId);
+                    if (snapshot.status === 'ok') {
+                        contribution = ok({ recordId, ...snapshot.value });
+                    }
+                    else if (snapshot.status === 'degraded' && snapshot.value !== undefined) {
+                        contribution = degraded(snapshot.reason, { recordId, ...snapshot.value });
+                    }
+                    else {
+                        contribution = degraded(snapshot.reason, { recordId });
+                    }
+                }
+                catch (error) {
+                    contribution = degraded(`contribution status failed: ${errorReason(error)}`, { recordId });
+                }
+            }
+        }
+    }
+    const providedPackets = hits.providedPackets.length > 0
+        ? hits.providedPackets.map(packetTitle)
+        : activity.providedRefs.map((ref) => ({ ref, title: ref }));
+    const summary = {
+        episodeRef: episode.episodeId,
+        searchedTerms: activity.searchedTerms,
+        providedPackets,
+        eligibility,
+        nothingFound: activity.providedRefs.length === 0,
+    };
+    return {
+        episodeRef: episode.episodeId,
+        persistence,
+        ...(contribution !== undefined ? { contribution } : {}),
+        eligibility,
+        summary,
+    };
+}
+export class PluginSession {
+    deps;
+    meta;
+    trajectory = [];
+    searchedTerms = [];
+    providedRefs = [];
+    fetchedRefs = [];
+    packets = [];
+    retrievalFired = false;
+    eligibleRefs = [];
+    deliveryMode = 'disabled';
+    deliveredContentHash;
+    capturedAt = new Date().toISOString();
+    constructor(deps, meta) {
+        this.deps = deps;
+        this.meta = meta;
+    }
+    async firstTurnPickup(firstMessage, options = {}) {
+        const excludedCanonicalEpisodeIds = new Set(options.excludeCanonicalEpisodeIds ?? []);
+        const config = parsePickupConfig(this.meta.pickup);
+        if (!config.enabled) {
+            return {
+                contextBlock: null,
+                packets: [],
+                searchedTerms: [],
+                retrievalFired: false,
+                eligibleRefs: [],
+                deliveredRefs: [],
+                deliveredCanonicalEpisodeIds: [],
+                deliveryMode: 'disabled',
+            };
+        }
+        const terms = deriveSearchTerms(firstMessage, this.meta.repositorySlug);
+        // Search with every term; score with the discriminating ones only — the
+        // repository name tags every record in an in-repo corpus, so counting it
+        // halved the effective relevance floor (#1886).
+        const scoringTerms = discriminatingTerms(terms, this.meta.repositorySlug);
+        this.searchedTerms = terms;
+        this.retrievalFired = true;
+        this.deliveryMode = 'delivered';
+        if (terms.length === 0) {
+            this.deliveryMode = 'withheld';
+            return {
+                contextBlock: null,
+                packets: [],
+                searchedTerms: terms,
+                retrievalFired: true,
+                eligibleRefs: [],
+                deliveredRefs: [],
+                deliveredCanonicalEpisodeIds: [],
+                deliveryMode: this.deliveryMode,
+            };
+        }
+        // Issue all per-term searches concurrently — the searches are
+        // independent (mono #1795: sequential awaits serialized ~1.6s/term of
+        // live indexer round-trips, blowing the 15s host deadline once lexical
+        // v2 widened the term budget to 10). `Promise.all` preserves result
+        // order by term index regardless of resolution order, so the merge
+        // below stays in term order — dedup priority and the first-observed
+        // degraded reason are byte-identical to the old sequential loop. A
+        // rejected promise would violate the PortResult convention (ports
+        // resolve, never throw), but is guarded anyway: it degrades that one
+        // term's contribution rather than the whole pickup (fail-open).
+        const results = await Promise.all(terms.map((term) => this.deps.corpus.search(term).catch((error) => degraded(`corpus search rejected: ${errorReason(error)}`))));
+        // Merge hits in term order (skip non-ok reads → fail open; keep the
+        // first degraded reason observed for an honest, non-crashing report).
+        let degradedReason;
+        const byRef = new Map();
+        for (const result of results) {
+            if (result.status !== 'ok' && degradedReason === undefined)
+                degradedReason = result.reason;
+            for (const hit of valueOr(result, [])) {
+                if (!byRef.has(hit.ref))
+                    byRef.set(hit.ref, hit);
+            }
+        }
+        // Only the production local search adapter exposes this hit-level hint in
+        // this release. Federated search is stable local-then-public, so the first
+        // hit for an identity is the deterministic local form to prefer once a
+        // fetched public record reveals that same identity.
+        const preferredHitByCanonicalEpisodeId = new Map();
+        for (const hit of byRef.values()) {
+            if (hit.canonicalEpisodeId !== undefined
+                && !preferredHitByCanonicalEpisodeId.has(hit.canonicalEpisodeId)) {
+                preferredHitByCanonicalEpisodeId.set(hit.canonicalEpisodeId, hit);
+            }
+        }
+        const candidates = rankKnowledgeCandidates([...byRef.values()].filter((hit) => hit.canonicalEpisodeId === undefined
+            || !excludedCanonicalEpisodeIds.has(hit.canonicalEpisodeId)), scoringTerms);
+        if (candidates.length === 0) {
+            this.deliveryMode = degradedReason === undefined ? 'withheld' : 'degraded';
+            return {
+                contextBlock: null,
+                packets: [],
+                searchedTerms: terms,
+                retrievalFired: true,
+                eligibleRefs: [],
+                deliveredRefs: [],
+                deliveredCanonicalEpisodeIds: [],
+                deliveryMode: this.deliveryMode,
+                ...(degradedReason !== undefined ? { degraded: degradedReason } : {}),
+            };
+        }
+        // Metadata score-1 candidates are plausible enough to inspect but not
+        // relevant enough to inject. Fetch only the deterministic top K and
+        // re-score the original normalized terms against concise authored
+        // content (synthesis + step titles). Gets run concurrently inside the
+        // same host deadline as search; Promise.all preserves candidate order.
+        // Reuse successful fetched records below so escalation never causes a
+        // duplicate corpus/cache read. Any individual failure stays below the
+        // floor and records an honest degraded reason (fail open).
+        const fetchedRefs = [];
+        const prefetchedByRef = new Map();
+        const fetchRecord = (hit) => {
+            const prefetched = prefetchedByRef.get(hit.ref);
+            if (prefetched !== undefined)
+                return prefetched;
+            fetchedRefs.push(hit.ref);
+            const pending = this.deps.corpus.get(hit.ref).catch((error) => degraded(`corpus get rejected for ${hit.ref}: ${errorReason(error)}`));
+            prefetchedByRef.set(hit.ref, pending);
+            return pending;
+        };
+        const resolvePreferredRecord = async (hit, fetchedRecord) => {
+            let selectedHit = hit;
+            let record = fetchedRecord;
+            let preferredFailureReason;
+            const canonicalEpisodeId = record.canonicalEpisodeId;
+            const preferredHit = canonicalEpisodeId === undefined
+                ? undefined
+                : preferredHitByCanonicalEpisodeId.get(canonicalEpisodeId);
+            if (preferredHit !== undefined && preferredHit.ref !== hit.ref) {
+                const preferredResult = await fetchRecord(preferredHit);
+                if (preferredResult.status === 'unavailable') {
+                    preferredFailureReason = preferredResult.reason;
+                }
+                else {
+                    if (preferredResult.status === 'degraded') {
+                        preferredFailureReason = preferredResult.reason;
+                    }
+                    const preferredRecord = valueOr(preferredResult, null);
+                    if (preferredRecord !== null) {
+                        selectedHit = preferredHit;
+                        record = preferredRecord;
+                    }
+                }
+            }
+            return {
+                selectedHit,
+                record,
+                ...(preferredFailureReason !== undefined ? { preferredFailureReason } : {}),
+            };
+        };
+        const directCandidates = candidates.filter((candidate) => candidate.score >= RELEVANCE_FLOOR);
+        const nearMisses = candidates
+            .filter((candidate) => candidate.score < RELEVANCE_FLOOR)
+            .slice(0, MAX_CONTENT_RESCORE_CANDIDATES);
+        const nearMissResults = await Promise.all(nearMisses.map(async ({ hit }) => {
+            const result = await fetchRecord(hit);
+            if (result.status === 'unavailable') {
+                return { result, selectedHit: hit, record: null };
+            }
+            const fetchedRecord = valueOr(result, null);
+            if (fetchedRecord === null)
+                return { result, selectedHit: hit, record: null };
+            if (fetchedRecord.canonicalEpisodeId !== undefined
+                && excludedCanonicalEpisodeIds.has(fetchedRecord.canonicalEpisodeId)) {
+                return { result, selectedHit: hit, record: null };
+            }
+            const preferred = await resolvePreferredRecord(hit, fetchedRecord);
+            return { result, ...preferred };
+        }));
+        const promotedCandidates = [];
+        for (let index = 0; index < nearMisses.length; index += 1) {
+            const candidate = nearMisses[index];
+            const nearMissResult = nearMissResults[index];
+            if (nearMissResult.result.status === 'unavailable') {
+                if (degradedReason === undefined)
+                    degradedReason = nearMissResult.result.reason;
+                continue;
+            }
+            if (nearMissResult.result.status === 'degraded') {
+                degradedReason ??= nearMissResult.result.reason;
+            }
+            degradedReason ??= nearMissResult.preferredFailureReason;
+            const record = nearMissResult.record;
+            if (record === null)
+                continue;
+            if (record.isSkillPayload === true)
+                continue;
+            if (record.retrievalVisible !== true)
+                continue;
+            const score = scoreKnowledgeRecord(candidate.hit, record, scoringTerms);
+            if (score >= RELEVANCE_FLOOR)
+                promotedCandidates.push({ hit: candidate.hit, score });
+        }
+        const ranked = rankScoredKnowledgeHits([
+            ...directCandidates,
+            ...promotedCandidates,
+        ]).map((candidate) => candidate.hit);
+        if (ranked.length === 0) {
+            this.fetchedRefs = fetchedRefs;
+            this.deliveryMode = degradedReason === undefined ? 'withheld' : 'degraded';
+            return {
+                contextBlock: null,
+                packets: [],
+                searchedTerms: terms,
+                retrievalFired: true,
+                eligibleRefs: [],
+                deliveredRefs: [],
+                deliveredCanonicalEpisodeIds: [],
+                deliveryMode: this.deliveryMode,
+                ...(degradedReason !== undefined ? { degraded: degradedReason } : {}),
+            };
+        }
+        // Fetch full content for ranked candidates and project packets, walking
+        // down the ranked list until MAX_SELECTED_PACKETS valid packets are
+        // found or candidates are exhausted (mono #1782). Post-fetch guards can
+        // disqualify a candidate without spending its slot, promoting the
+        // next-ranked one: (1) canonical exclusion/dedup; (2) content-level
+        // skill classification — which excludes a legacy skill-shaped record
+        // (skill.md step attribute) or a jinn.skill.v1-backed record that slipped
+        // the wire kind filter, exactly as a wire kind:'skill' hit is excluded at
+        // selection time; (3) retrieval-visibility content verification (#1824,
+        // W2) — fail-closed where the other guards are fail-open; (4)
+        // empty-packet honesty — a projection with zero excerpts and no synthesis
+        // is not evidence. A projection failure degrades that one ref to
+        // nothing-found rather than throwing into the caller (§3.5).
+        const packets = [];
+        const deliveredCanonicalEpisodeIds = [];
+        const deliveredCanonicalSet = new Set();
+        for (const hit of ranked) {
+            if (packets.length >= MAX_SELECTED_PACKETS)
+                break;
+            const result = await fetchRecord(hit);
+            if (result.status === 'unavailable') {
+                if (degradedReason === undefined)
+                    degradedReason = result.reason;
+                continue;
+            }
+            if (result.status === 'degraded')
+                degradedReason ??= result.reason;
+            const fetchedRecord = valueOr(result, null);
+            if (fetchedRecord === null)
+                continue;
+            const fetchedCanonicalEpisodeId = fetchedRecord.canonicalEpisodeId;
+            if (fetchedCanonicalEpisodeId !== undefined
+                && (excludedCanonicalEpisodeIds.has(fetchedCanonicalEpisodeId)
+                    || deliveredCanonicalSet.has(fetchedCanonicalEpisodeId))) {
+                continue;
+            }
+            const { selectedHit, record, preferredFailureReason, } = await resolvePreferredRecord(hit, fetchedRecord);
+            degradedReason ??= preferredFailureReason;
+            const canonicalEpisodeId = record.canonicalEpisodeId;
+            if (canonicalEpisodeId !== undefined
+                && (excludedCanonicalEpisodeIds.has(canonicalEpisodeId)
+                    || deliveredCanonicalSet.has(canonicalEpisodeId))) {
+                continue;
+            }
+            if (record.isSkillPayload === true)
+                continue;
+            // Post-fetch content guard (#1824, W2): content is the truth, the
+            // search-hit's retrievalVisible was only a hint used to clear ranking.
+            // Fail-closed — undefined excludes, exactly like isSkillPayload's
+            // fail-open is the opposite case.
+            if (record.retrievalVisible !== true)
+                continue;
+            let packet;
+            try {
+                packet = projectKnowledgePacket(record);
+            }
+            catch (error) {
+                degradedReason ??= `packet projection failed for ${selectedHit.ref}: ${errorReason(error)}`;
+                continue;
+            }
+            if (packet.excerpts.length === 0 && packet.synthesis === undefined)
+                continue;
+            packets.push(packet);
+            if (canonicalEpisodeId !== undefined) {
+                deliveredCanonicalSet.add(canonicalEpisodeId);
+                deliveredCanonicalEpisodeIds.push(canonicalEpisodeId);
+            }
+        }
+        this.fetchedRefs = fetchedRefs;
+        this.providedRefs = packets.map((packet) => packet.ref);
+        this.eligibleRefs = [...this.providedRefs];
+        this.packets = packets;
+        if (packets.length === 0) {
+            this.deliveryMode = degradedReason === undefined ? 'withheld' : 'degraded';
+            return {
+                contextBlock: null,
+                packets: [],
+                searchedTerms: terms,
+                retrievalFired: true,
+                eligibleRefs: this.eligibleRefs,
+                deliveredRefs: [],
+                deliveredCanonicalEpisodeIds: [],
+                deliveryMode: this.deliveryMode,
+                ...(degradedReason !== undefined ? { degraded: degradedReason } : {}),
+            };
+        }
+        const contextBlock = renderKnowledgePackets(packets);
+        this.deliveryMode = degradedReason === undefined ? 'delivered' : 'degraded';
+        this.deliveredContentHash = `sha256:${createHash('sha256').update(contextBlock).digest('hex')}`;
+        return {
+            contextBlock,
+            packets,
+            searchedTerms: terms,
+            retrievalFired: true,
+            eligibleRefs: this.eligibleRefs,
+            deliveredRefs: this.providedRefs,
+            deliveredCanonicalEpisodeIds,
+            deliveryMode: this.deliveryMode,
+            deliveredContentHash: this.deliveredContentHash,
+            ...(degradedReason !== undefined ? { degraded: degradedReason } : {}),
+        };
+    }
+    noteUserTurn(content) {
+        this.pushTurn('user', content);
+    }
+    noteAssistantTurn(content) {
+        this.pushTurn('assistant', content);
+    }
+    pushTurn(role, content) {
+        // A turn is a zero-duration point event on the single unix-nano time base.
+        const nowNano = `${Date.now()}000000`;
+        this.trajectory.push({
+            spanId: randomUUID(),
+            parentSpanId: null,
+            kind: 'jinn.agent_turn',
+            name: 'turn',
+            startTimeUnixNano: nowNano,
+            endTimeUnixNano: nowNano,
+            attributes: { role, content },
+            redactedKeys: [],
+        });
+    }
+    noteToolCall(call) {
+        this.trajectory.push({ ...call, kind: 'jinn.tool_call', redactedKeys: call.redactedKeys ?? [] });
+    }
+    async end(outcome) {
+        const episode = EpisodeV1WriteSchema.parse({
+            schemaVersion: EPISODE_SCHEMA_VERSION,
+            episodeId: randomUUID(),
+            session: {
+                sessionId: this.meta.sessionId,
+                capturedAt: this.capturedAt,
+                kind: this.meta.kind ?? 'user',
+                ...(this.meta.parentSessionId ? { parentSessionId: this.meta.parentSessionId } : {}),
+            },
+            origin: {
+                writer: this.meta.harness.name,
+                build: this.meta.harness.version,
+            },
+            task: {
+                summary: this.meta.taskSummary,
+                distributionTags: this.meta.distributionTags ?? [],
+                ...(this.meta.repositorySlug ? { repositorySlug: this.meta.repositorySlug } : {}),
+            },
+            trajectory: this.trajectory,
+            environment: {
+                harness: this.meta.harness,
+                model: this.meta.model,
+                tools: this.meta.tools,
+                skillsLoadout: this.meta.skillsLoadout ?? [],
+            },
+            outcome: {
+                status: outcome.status,
+                verificationStrength: outcome.verifiabilityTier,
+                ...(outcome.summary !== undefined ? { summary: outcome.summary } : {}),
+                ...(outcome.acceptedDiff !== undefined ? { acceptedDiff: outcome.acceptedDiff } : {}),
+                ...(outcome.testRuns !== undefined ? { testRuns: outcome.testRuns } : {}),
+            },
+            cost: {
+                durationMs: outcome.durationMs,
+                ...(outcome.tokens ? { tokens: outcome.tokens } : {}),
+            },
+            retention: { policy: outcome.retentionPolicy },
+            provenance: 'contributed',
+        });
+        return completeSession(this.deps, {
+            contractVersion: JINN_PLUGIN_CONTRACT_VERSION,
+            episode,
+            activity: {
+                searchedTerms: this.searchedTerms,
+                providedRefs: this.providedRefs,
+                retrievalFired: this.retrievalFired,
+                eligibleRefs: this.eligibleRefs,
+                deliveredRefs: this.providedRefs,
+                deliveryMode: this.deliveryMode,
+                ...(this.deliveredContentHash
+                    ? { deliveredContentHash: this.deliveredContentHash }
+                    : {}),
+                surfacedRefs: [],
+                fetchedRefs: this.fetchedRefs,
+                installedSkillRefs: [],
+            },
+            eligibilityInputs: {
+                publicRepo: outcome.publicRepo,
+                acceptedDiff: outcome.acceptedDiff,
+            },
+        }, { providedPackets: this.packets });
+    }
+}
+/**
+ * Composes the block the host injects into the first user message, verbatim
+ * and cache-safe (rescope §3.4).
+ */
+function renderKnowledgePacket(packet) {
+    const lines = [
+        `${packet.task.summary} · ${packet.outcome.status}/${packet.outcome.verifiabilityTier}`,
+    ];
+    if (packet.synthesis)
+        lines.push(packet.synthesis);
+    for (const excerpt of packet.excerpts)
+        lines.push(`- ${excerpt.label}: ${excerpt.text}`);
+    const capturedDate = packet.attribution.capturedAt.slice(0, 10);
+    lines.push(`  source: ${packet.ref} · ${packet.attribution.origin} · captured ${capturedDate}`);
+    return lines.join('\n');
+}
+function renderKnowledgePackets(packets) {
+    return [
+        '[jinn corpus] Prior evidence relevant to this task:',
+        ...packets.map(renderKnowledgePacket),
+    ].join('\n');
+}
+export function createJinnPlugin(deps) {
+    return {
+        session(meta) {
+            return new PluginSession(deps, meta);
+        },
+        completeSession(input) {
+            return completeSession(deps, input);
+        },
+        history() {
+            return foldHistory(deps);
+        },
+        explain(sessionRef) {
+            return foldExplain(sessionRef, deps);
+        },
+        previewContribution(acknowledge = false) {
+            return previewContribution(deps, acknowledge);
+        },
+        async contributionLedger() {
+            try {
+                return await deps.contribution.ledger();
+            }
+            catch (error) {
+                return unavailable(`contribution ledger failed: ${errorReason(error)}`);
+            }
+        },
+        async disableContributionPublication() {
+            if (!deps.contribution.disableUnpublished) {
+                return unavailable('contribution disable is unavailable');
+            }
+            try {
+                return await deps.contribution.disableUnpublished();
+            }
+            catch (error) {
+                return unavailable(`contribution disable failed: ${errorReason(error)}`);
+            }
+        },
+    };
+}