charness 0.0.0-stage → 3.1.0

package/dist/connectors/jira/connector.js

@@ -0,0 +1,312 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jiraPollJqlLogPrefix = exports.jiraNoTrustedGroupLogLine = exports.jiraSpillDirName = exports.jiraFilesDirName = exports.JiraConnectorStartError = void 0;
+exports.checkIsTransientJiraFailure = checkIsTransientJiraFailure;
+exports.prepareJiraConnector = prepareJiraConnector;
+const path = __importStar(require("path"));
+const botFileStorage_1 = require("../../botFileStorage");
+const client_1 = require("./client");
+const answerSink_1 = require("./answerSink");
+const config_1 = require("./config");
+const inbound_1 = require("./inbound");
+const triggerLog_1 = require("./triggerLog");
+const contextLedger_1 = require("./contextLedger");
+const trustedGroup_1 = require("./trustedGroup");
+const attachmentTool_1 = require("./attachmentTool");
+const agentBinaries_1 = require("./agentBinaries");
+const agentEnvironment_1 = require("../../utils/agentEnvironment");
+const unconfirmedPosts_1 = require("./unconfirmedPosts");
+const utils_1 = require("../../utils");
+/**
+ * @description The Jira connector's entry point, loaded by `bot.ts` through a
+ * dynamic `import()` only when `CONNECTORS` lists `jira` (R20). Preparing it
+ * reads and checks everything a poll depends on BEFORE the boot goes on — the
+ * config, that the API token belongs to the configured AI account, each
+ * project's trigger status ids, the trigger log — so a broken setup stops the
+ * start with every reason at once instead of failing on the first poll.
+ */
+class JiraConnectorStartError extends Error {
+    reasons;
+    constructor(reasons) {
+        super(`the Jira connector cannot start: ${reasons.join('; ')}`);
+        this.reasons = reasons;
+        this.name = 'JiraConnectorStartError';
+    }
+}
+exports.JiraConnectorStartError = JiraConnectorStartError;
+/**
+ * @description R22: a failure that says nothing about the setup — no answer, a
+ * 5xx, a 429 after the client's own retries. A refused token (401/403) or any
+ * other 4xx (an unknown project) is the setup's fault.
+ */
+function checkIsTransientJiraFailure(error) {
+    if (error instanceof client_1.JiraAuthError)
+        return false;
+    if (error instanceof client_1.JiraHttpError)
+        return error.status === 0 || error.status === 429 || error.status >= 500;
+    return true;
+}
+/** A lookup's result or its failure, so independent lookups can run together and all be reported. */
+async function settle(lookup) {
+    try {
+        return { ok: true, value: await lookup };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
+    }
+}
+/** The status Jira answers with when the account lacks the permission a call needs. */
+const permissionRefusedStatus = 403;
+/**
+ * What the setup check reads from Jira: the token's account, every project's statuses, the site's fields when
+ * any project names extra ones, and the trusted group with its members when the config names one.
+ */
+async function checkJiraSetup(client, config, now) {
+    const projectEntries = [...config.projects];
+    const hasExtraFields = projectEntries.some(([, project]) => project.extraFieldIds.length > 0);
+    const { trustedGroupName } = config;
+    // Independent lookups, made together; one project's failure does not hide the others' problems.
+    const [myself, statusLookups, fieldsLookup, groupLookup] = await Promise.all([
+        settle(client.getMyself()),
+        Promise.all(projectEntries.map(([projectKey]) => settle(client.getProjectStatuses(projectKey)))),
+        hasExtraFields ? settle(client.getFields()) : null,
+        trustedGroupName === null ? null : settle((0, trustedGroup_1.readJiraTrustedGroup)(client, trustedGroupName, now)),
+    ]);
+    const reasons = [];
+    const transientDetails = [];
+    const noteFailure = (error) => {
+        (checkIsTransientJiraFailure(error) ? transientDetails : reasons).push(error.message);
+    };
+    if (!myself.ok)
+        noteFailure(myself.error);
+    else if (myself.value.accountId !== config.accountId)
+        reasons.push('jira.json accountId is not the account its apiToken belongs to');
+    if (fieldsLookup && !fieldsLookup.ok)
+        noteFailure(fieldsLookup.error);
+    const fieldDefinitions = fieldsLookup?.ok ? fieldsLookup.value : [];
+    if (groupLookup && !groupLookup.ok) {
+        const { error } = groupLookup;
+        if (error instanceof client_1.JiraAuthError && error.status === permissionRefusedStatus) {
+            reasons.push('jira.json trustedGroup: the AI account needs the Browse users and groups global permission to read the trusted group');
+        }
+        else {
+            noteFailure(error);
+        }
+    }
+    else if (groupLookup && groupLookup.value === null) {
+        reasons.push(`jira.json trustedGroup: the site has no group named "${trustedGroupName}"`);
+    }
+    const trustedGroup = groupLookup?.ok ? groupLookup.value : null;
+    const projects = new Map();
+    const unknownExtraFieldIds = new Map();
+    projectEntries.forEach(([projectKey, project], index) => {
+        const lookup = statusLookups[index];
+        if (!lookup.ok) {
+            noteFailure(lookup.error);
+            return;
+        }
+        const resolved = (0, config_1.resolveTriggerStatusIds)(projectKey, project.triggerStatusNames, lookup.value);
+        if (!resolved.ok) {
+            reasons.push(resolved.error);
+            return;
+        }
+        const { extraFields, unknownFieldIds } = (0, config_1.resolveExtraFields)(project.extraFieldIds, fieldDefinitions);
+        if (unknownFieldIds.length > 0)
+            unknownExtraFieldIds.set(projectKey, unknownFieldIds);
+        projects.set(projectKey, { folder: project.folder, triggerStatusIds: new Set(resolved.statusIds), extraFields });
+    });
+    if (reasons.length > 0)
+        return { kind: 'refused', reasons };
+    if (transientDetails.length > 0)
+        return { kind: 'unreachable', detail: transientDetails.join('; ') };
+    return { kind: 'ready', projects, unknownExtraFieldIds, trustedGroup };
+}
+/** The connector's own folders inside a conversation's files dir: its downloads, and under them the text too long for a prompt. */
+exports.jiraFilesDirName = 'jira';
+exports.jiraSpillDirName = 'text';
+/** Logged at boot when `jira.json` has no `trustedGroup`: nothing filters whose text reaches the agents. */
+exports.jiraNoTrustedGroupLogLine = '[jira] no trustedGroup: the text of everyone who can edit or comment reaches the agents';
+/** The start-of-polling log line that carries the poll's JQL. */
+exports.jiraPollJqlLogPrefix = '[jira] poll JQL: ';
+async function prepareJiraConnector(context) {
+    const loaded = (0, config_1.loadJiraConfig)(context);
+    if (!loaded.ok)
+        throw new JiraConnectorStartError(loaded.errors);
+    const { config } = loaded;
+    const client = (0, client_1.createJiraClient)({
+        baseUrl: config.baseUrl,
+        email: config.email,
+        apiToken: config.apiToken,
+        ...(context.testTiming ? { sleepImpl: context.testTiming.sleep } : {}),
+    });
+    const now = () => Date.now();
+    // R22: a wrong setup refuses the start; a Jira that does not answer does not —
+    // the connector starts and checks again before its first poll.
+    const firstCheck = await checkJiraSetup(client, config, now);
+    if (firstCheck.kind === 'refused')
+        throw new JiraConnectorStartError(firstCheck.reasons);
+    if (firstCheck.kind === 'unreachable')
+        console.warn(`[jira] Jira unreachable at start (${firstCheck.detail}); polling starts once it answers`);
+    if (config.trustedGroupName === null)
+        console.log(exports.jiraNoTrustedGroupLogLine);
+    const triggerLog = triggerLog_1.JiraTriggerLog.createForDataDir(path.join(context.dataDir, triggerLog_1.jiraTriggerLogFileName));
+    await triggerLog.load();
+    const unconfirmedPosts = unconfirmedPosts_1.JiraUnconfirmedPosts.createForDataDir(path.join(context.dataDir, unconfirmedPosts_1.jiraUnconfirmedPostsFileName), now);
+    await unconfirmedPosts.load();
+    /** The connector's own folder inside a conversation's files dir. */
+    const getJiraFilesDir = (key) => path.join((0, botFileStorage_1.resolveThreadFilesDir)(context.dataDir, key), exports.jiraFilesDirName);
+    const contextLedger = contextLedger_1.JiraContextLedger.createForDataDir(context.dataDir);
+    // C11: the tools the agents should find on their PATH, linked once per boot; a name dropped from the config is unlinked.
+    (0, agentEnvironment_1.registerAgentBinDir)((0, agentBinaries_1.linkAgentBinaries)(context.dataDir, config.agentBinaries));
+    const answerSink = (0, answerSink_1.createJiraAnswerSink)({
+        client,
+        aiAccountId: config.accountId,
+        runBudgetPer24h: config.runBudgetPer24h,
+        now,
+        wait: utils_1.sleep,
+        unconfirmedPosts,
+    });
+    let inbound = null;
+    /** Built from the first setup check that came out ready; `null` before that, and for good without `trustedGroup`. */
+    let trust = null;
+    const adoptTrustedGroup = (ready) => {
+        const { trustedGroup } = ready;
+        trust = trustedGroup ? (0, trustedGroup_1.createJiraTrust)({ client, snapshot: trustedGroup, aiAccountId: config.accountId, now }) : null;
+    };
+    if (firstCheck.kind === 'ready')
+        adoptTrustedGroup(firstCheck);
+    /** Why the setup check that retried after an unreachable start came out refused — polling never began; `null` while none did. */
+    let lateSetupRefusalReasons = null;
+    let setupRetryTimer = null;
+    let isStarted = false;
+    const startPolling = (deps, ready) => {
+        const { projects, unknownExtraFieldIds, trustedGroup } = ready;
+        // Once per start: this runs only for the check that came out ready.
+        for (const [projectKey, fieldIds] of unknownExtraFieldIds) {
+            console.warn(`[jira] ${projectKey}: extraFields the site does not list are left out of every prompt: ${fieldIds.join(', ')}`);
+        }
+        if (trustedGroup && trustedGroup.memberAccountIds.size === 0) {
+            console.warn(`[jira] the trusted group "${trustedGroup.groupName}" has no members: only apps and automations can hand the AI work`);
+        }
+        inbound = new inbound_1.JiraInbound({
+            ...deps,
+            client,
+            aiAccountId: config.accountId,
+            siteUrl: config.baseUrl,
+            projects,
+            runBudgetPer24h: config.runBudgetPer24h,
+            pollIntervalMs: config.pollIntervalMs,
+            contextLedger,
+            getSpillDir: (key) => path.join(getJiraFilesDir(key), exports.jiraSpillDirName),
+            triggerLog,
+            trust,
+            now,
+            parkIssue: (issueKey, requester) => answerSink.parkIssue(issueKey, requester),
+            refuseUntrusted: (issueKey, requester, groupName) => answerSink.refuseUntrusted(issueKey, requester, groupName),
+        });
+        inbound.start();
+        console.log(`[jira] polling ${[...projects.keys()].join(', ')} every ${config.pollIntervalMs / 1000} s`);
+        // The allowlist as Jira receives it — what an operator reads to see which projects the AI account may act in.
+        console.log(`${exports.jiraPollJqlLogPrefix}${(0, inbound_1.buildJiraTriggerJql)(projects)}`);
+    };
+    /** Check the setup again, with backoff, until Jira answers; then poll — or, if the setup turns out wrong, stop loudly (the process stays up). */
+    const retrySetupCheck = (deps, failureCount) => {
+        // Not unref'd: in a Jira-only instance this timer keeps the process alive (D9).
+        setupRetryTimer = setTimeout(() => {
+            void checkJiraSetup(client, config, now).then((check) => {
+                if (!isStarted)
+                    return;
+                if (check.kind === 'refused') {
+                    lateSetupRefusalReasons = check.reasons;
+                    for (const reason of check.reasons)
+                        console.error(`[jira] polling NOT started: ${reason}`);
+                }
+                else if (check.kind === 'unreachable') {
+                    retrySetupCheck(deps, failureCount + 1);
+                }
+                else {
+                    adoptTrustedGroup(check);
+                    startPolling(deps, check);
+                }
+            });
+        }, (0, inbound_1.getJiraRetryDelayMs)(context.testTiming?.setupRetryBaseMs ?? config.pollIntervalMs, failureCount));
+    };
+    return {
+        adapterName: config.adapter,
+        launchDefaults: { model: config.model, effort: config.effort },
+        answerSink,
+        onPromptSettled: (key, requestId, outcome) => {
+            // A Jira conversation's thread IS its issue key.
+            if (outcome === 'takenIn')
+                contextLedger.commit(key.thread, requestId);
+            else
+                contextLedger.drop(key.thread, requestId);
+        },
+        fetchAttachment: async (key, attachmentId) => {
+            // A group is configured but was never read: who uploaded what is unknown, so nothing is served. Either Jira did
+            // not answer yet (its check is retried), or the retried check was refused and polling never began.
+            if (config.trustedGroupName !== null && trust === null) {
+                const reason = lateSetupRefusalReasons === null
+                    ? 'the trusted group has not been read yet; try again shortly'
+                    : `the setup was refused after the start (${lateSetupRefusalReasons.join('; ')}), so the trusted group is not read and polling never began; an operator has to fix the setup`;
+                return { ok: false, error: `Attachment ${attachmentId} could not be fetched: ${reason}` };
+            }
+            return (0, attachmentTool_1.fetchIssueAttachment)({ client, getDownloadDir: getJiraFilesDir, trust }, key, attachmentId);
+        },
+        onContextReset: (key, reason) => {
+            contextLedger.reset(key.thread);
+            console.log(`[jira] ${key.thread}: its context was reset (${reason}); the next prompt carries the whole issue`);
+        },
+        start: (deps) => {
+            if (isStarted)
+                return;
+            isStarted = true;
+            if (firstCheck.kind === 'ready')
+                startPolling(deps, firstCheck);
+            else
+                retrySetupCheck(deps, 0);
+        },
+        stop: () => {
+            isStarted = false;
+            if (setupRetryTimer)
+                clearTimeout(setupRetryTimer);
+            setupRetryTimer = null;
+            inbound?.stop();
+            inbound = null;
+        },
+    };
+}
+//# sourceMappingURL=connector.js.map

package/dist/connectors/jira/connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.js","sourceRoot":"","sources":["../../../src/connectors/jira/connector.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkEA,kEAIC;AAqGD,oDAgJC;AA3TD,2CAA6B;AAC7B,yDAA6D;AAC7D,qCAAqH;AACrH,6CAAyE;AACzE,qCAAwG;AACxG,uCAAiI;AACjI,6CAAsE;AACtE,mDAAoD;AACpD,iDAAsH;AACtH,qDAAuF;AACvF,mDAAoD;AACpD,mEAAmE;AAGnE,yDAAwF;AACxF,uCAAoC;AAEpC;;;;;;;GAOG;AAEH,MAAa,uBAAwB,SAAQ,KAAK;IAC3B;IAArB,YAAqB,OAAiB;QACpC,KAAK,CAAC,oCAAoC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAD7C,YAAO,GAAP,OAAO,CAAU;QAEpC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AALD,0DAKC;AA8BD;;;;GAIG;AACH,SAAgB,2BAA2B,CAAC,KAAY;IACtD,IAAI,KAAK,YAAY,sBAAa;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,KAAK,YAAY,sBAAa;QAAE,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG,CAAC;IAC7G,OAAO,IAAI,CAAC;AACd,CAAC;AAsBD,qGAAqG;AACrG,KAAK,UAAU,MAAM,CAAI,MAAkB;IACzC,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,MAAM,EAAE,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;IACzF,CAAC;AACH,CAAC;AAED,uFAAuF;AACvF,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC;;;GAGG;AACH,KAAK,UAAU,cAAc,CAAC,MAAkB,EAAE,MAAkB,EAAE,GAAiB;IACrF,MAAM,cAAc,GAAG,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,cAAc,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC9F,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAAC;IACpC,gGAAgG;IAChG,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC3E,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QAC1B,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAChG,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI;QAClD,gBAAgB,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAA,mCAAoB,EAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,CAAC,CAAC;KAC/F,CAAC,CAAC;IACH,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,gBAAgB,GAAa,EAAE,CAAC;IACtC,MAAM,WAAW,GAAG,CAAC,KAAY,EAAQ,EAAE;QACzC,CAAC,2BAA2B,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACxF,CAAC,CAAC;IACF,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;SACrC,IAAI,MAAM,CAAC,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,SAAS;QAAE,OAAO,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;IACrI,IAAI,YAAY,IAAI,CAAC,YAAY,CAAC,EAAE;QAAE,WAAW,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IACtE,MAAM,gBAAgB,GAAmC,YAAY,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACpG,IAAI,WAAW,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC;QACnC,MAAM,EAAE,KAAK,EAAE,GAAG,WAAW,CAAC;QAC9B,IAAI,KAAK,YAAY,sBAAa,IAAI,KAAK,CAAC,MAAM,KAAK,uBAAuB,EAAE,CAAC;YAC/E,OAAO,CAAC,IAAI,CAAC,sHAAsH,CAAC,CAAC;QACvI,CAAC;aAAM,CAAC;YACN,WAAW,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;SAAM,IAAI,WAAW,IAAI,WAAW,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QACrD,OAAO,CAAC,IAAI,CAAC,wDAAwD,gBAAgB,GAAG,CAAC,CAAC;IAC5F,CAAC;IACD,MAAM,YAAY,GAAG,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAChE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA8B,CAAC;IACvD,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAAoB,CAAC;IACzD,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE;QACtD,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC1B,OAAO;QACT,CAAC;QACD,MAAM,QAAQ,GAAG,IAAA,gCAAuB,EAAC,UAAU,EAAE,OAAO,CAAC,kBAAkB,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/F,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC7B,OAAO;QACT,CAAC;QACD,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,IAAA,2BAAkB,EAAC,OAAO,CAAC,aAAa,EAAE,gBAAgB,CAAC,CAAC;QACrG,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC;YAAE,oBAAoB,CAAC,GAAG,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;QACtF,QAAQ,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;IACnH,CAAC,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAC5D,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IACrG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,YAAY,EAAE,CAAC;AACzE,CAAC;AAED,mIAAmI;AACtH,QAAA,gBAAgB,GAAG,MAAM,CAAC;AAC1B,QAAA,gBAAgB,GAAG,MAAM,CAAC;AAEvC,4GAA4G;AAC/F,QAAA,yBAAyB,GAAG,yFAAyF,CAAC;AAEnI,iEAAiE;AACpD,QAAA,oBAAoB,GAAG,mBAAmB,CAAC;AAEjD,KAAK,UAAU,oBAAoB,CAAC,OAM1C;IACC,MAAM,MAAM,GAAG,IAAA,uBAAc,EAAC,OAAO,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACjE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAC1B,MAAM,MAAM,GAAG,IAAA,yBAAgB,EAAC;QAC9B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IACrC,+EAA+E;IAC/E,+DAA+D;IAC/D,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7D,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS;QAAE,MAAM,IAAI,uBAAuB,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACzF,IAAI,UAAU,CAAC,IAAI,KAAK,aAAa;QAAE,OAAO,CAAC,IAAI,CAAC,qCAAqC,UAAU,CAAC,MAAM,mCAAmC,CAAC,CAAC;IAC/I,IAAI,MAAM,CAAC,gBAAgB,KAAK,IAAI;QAAE,OAAO,CAAC,GAAG,CAAC,iCAAyB,CAAC,CAAC;IAE7E,MAAM,UAAU,GAAG,2BAAc,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,mCAAsB,CAAC,CAAC,CAAC;IACvG,MAAM,UAAU,CAAC,IAAI,EAAE,CAAC;IACxB,MAAM,gBAAgB,GAAG,uCAAoB,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,+CAA4B,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9H,MAAM,gBAAgB,CAAC,IAAI,EAAE,CAAC;IAE9B,oEAAoE;IACpE,MAAM,eAAe,GAAG,CAAC,GAAe,EAAU,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAA,sCAAqB,EAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,wBAAgB,CAAC,CAAC;IAC9H,MAAM,aAAa,GAAG,iCAAiB,CAAC,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1E,yHAAyH;IACzH,IAAA,sCAAmB,EAAC,IAAA,iCAAiB,EAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;IAC9E,MAAM,UAAU,GAAG,IAAA,iCAAoB,EAAC;QACtC,MAAM;QACN,WAAW,EAAE,MAAM,CAAC,SAAS;QAC7B,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,GAAG;QACH,IAAI,EAAE,aAAK;QACX,gBAAgB;KACjB,CAAC,CAAC;IACH,IAAI,OAAO,GAAuB,IAAI,CAAC;IACvC,qHAAqH;IACrH,IAAI,KAAK,GAAqB,IAAI,CAAC;IACnC,MAAM,iBAAiB,GAAG,CAAC,KAAiD,EAAQ,EAAE;QACpF,MAAM,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC;QAC/B,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,IAAA,8BAAe,EAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxH,CAAC,CAAC;IACF,IAAI,UAAU,CAAC,IAAI,KAAK,OAAO;QAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAC/D,iIAAiI;IACjI,IAAI,uBAAuB,GAA6B,IAAI,CAAC;IAC7D,IAAI,eAAe,GAA0B,IAAI,CAAC;IAClD,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,MAAM,YAAY,GAAG,CAAC,IAA8B,EAAE,KAAiD,EAAQ,EAAE;QAC/G,MAAM,EAAE,QAAQ,EAAE,oBAAoB,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC;QAC/D,oEAAoE;QACpE,KAAK,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,oBAAoB,EAAE,CAAC;YAC1D,OAAO,CAAC,IAAI,CAAC,UAAU,UAAU,sEAAsE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChI,CAAC;QACD,IAAI,YAAY,IAAI,YAAY,CAAC,gBAAgB,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAC7D,OAAO,CAAC,IAAI,CAAC,6BAA6B,YAAY,CAAC,SAAS,kEAAkE,CAAC,CAAC;QACtI,CAAC;QACD,OAAO,GAAG,IAAI,qBAAW,CAAC;YACxB,GAAG,IAAI;YACP,MAAM;YACN,WAAW,EAAE,MAAM,CAAC,SAAS;YAC7B,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,QAAQ;YACR,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,aAAa;YACb,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,wBAAgB,CAAC;YACvE,UAAU;YACV,KAAK;YACL,GAAG;YACH,SAAS,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,QAAQ,EAAE,SAAS,CAAC;YAC7E,eAAe,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC;SAChH,CAAC,CAAC;QACH,OAAO,CAAC,KAAK,EAAE,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,MAAM,CAAC,cAAc,GAAG,IAAI,IAAI,CAAC,CAAC;QACzG,8GAA8G;QAC9G,OAAO,CAAC,GAAG,CAAC,GAAG,4BAAoB,GAAG,IAAA,6BAAmB,EAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC,CAAC;IAEF,iJAAiJ;IACjJ,MAAM,eAAe,GAAG,CAAC,IAA8B,EAAE,YAAoB,EAAQ,EAAE;QACrF,gFAAgF;QAChF,eAAe,GAAG,UAAU,CAAC,GAAG,EAAE;YAChC,KAAK,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;gBACtD,IAAI,CAAC,SAAS;oBAAE,OAAO;gBACvB,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;oBAC7B,uBAAuB,GAAG,KAAK,CAAC,OAAO,CAAC;oBACxC,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,OAAO;wBAAE,OAAO,CAAC,KAAK,CAAC,+BAA+B,MAAM,EAAE,CAAC,CAAC;gBAC7F,CAAC;qBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;oBACxC,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,CAAC,CAAC,CAAC;gBAC1C,CAAC;qBAAM,CAAC;oBACN,iBAAiB,CAAC,KAAK,CAAC,CAAC;oBACzB,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,EAAE,IAAA,6BAAmB,EAAC,OAAO,CAAC,UAAU,EAAE,gBAAgB,IAAI,MAAM,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC,CAAC;IACvG,CAAC,CAAC;IAEF,OAAO;QACL,WAAW,EAAE,MAAM,CAAC,OAAO;QAC3B,cAAc,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAC9D,UAAU;QACV,eAAe,EAAE,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE;YAC3C,iDAAiD;YACjD,IAAI,OAAO,KAAK,SAAS;gBAAE,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;;gBAClE,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QACjD,CAAC;QACD,eAAe,EAAE,KAAK,EAAE,GAAG,EAAE,YAAY,EAAE,EAAE;YAC3C,gHAAgH;YAChH,mGAAmG;YACnG,IAAI,MAAM,CAAC,gBAAgB,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACvD,MAAM,MAAM,GAAG,uBAAuB,KAAK,IAAI;oBAC7C,CAAC,CAAC,4DAA4D;oBAC9D,CAAC,CAAC,0CAA0C,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,+FAA+F,CAAC;gBAChL,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,YAAY,0BAA0B,MAAM,EAAE,EAAE,CAAC;YAC5F,CAAC;YACD,OAAO,IAAA,qCAAoB,EAAC,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC;QACrG,CAAC;QACD,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE;YAC9B,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAChC,OAAO,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,MAAM,4BAA4B,MAAM,4CAA4C,CAAC,CAAC;QAClH,CAAC;QACD,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE;YACd,IAAI,SAAS;gBAAE,OAAO;YACtB,SAAS,GAAG,IAAI,CAAC;YACjB,IAAI,UAAU,CAAC,IAAI,KAAK,OAAO;gBAAE,YAAY,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;;gBAC3D,eAAe,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAChC,CAAC;QACD,IAAI,EAAE,GAAG,EAAE;YACT,SAAS,GAAG,KAAK,CAAC;YAClB,IAAI,eAAe;gBAAE,YAAY,CAAC,eAAe,CAAC,CAAC;YACnD,eAAe,GAAG,IAAI,CAAC;YACvB,OAAO,EAAE,IAAI,EAAE,CAAC;YAChB,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/connectors/jira/contextLedger.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+/**
+ * @description What each issue's conversation was already told (prompt context
+ * C4, C6): per issue, the hash of every block its agent has taken in (the
+ * sent-set), and per request the sent-set its prompt WOULD make once taken in.
+ *
+ *   build  → `recordBuild`: pending[request] = {generation, buildSeq, sent}
+ *   taken in (the ledger's flag, or a close by its own answer) → `commit`
+ *   superseded / cancelled → `drop`
+ *   fresh session / completed compaction → `reset` (S5): generation + 1, nothing sent, nothing pending
+ *
+ * A commit is dropped whole when its build belongs to an older generation (the
+ * agent lost that context since) or was built before the last committed one
+ * (the newer prompt already carried everything the older one did). When in
+ * doubt a block is sent twice, never lost. Persisted per issue in
+ * `DATA_DIR/jira-context/<ISSUE-KEY>.json`, written atomically, so a restart or
+ * a hot reload keeps it.
+ */
+export declare const jiraContextDirName = "jira-context";
+/** Builds kept waiting for their take-in; older ones are forgotten (their request closed without a word to the ledger). */
+export declare const jiraPendingBuildsMaxCount = 20;
+declare const sentBlockSchema: z.ZodObject<{
+    hash: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    isWithheld: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type JiraSentBlock = z.infer<typeof sentBlockSchema>;
+/** Block key → what was sent of it. */
+export type JiraSentBlocks = Record<string, JiraSentBlock>;
+/** What a build reads: the sent-set and the generation it belongs to. */
+export interface JiraContextSnapshot {
+    generation: number;
+    sent: Readonly<JiraSentBlocks>;
+}
+export declare class JiraContextLedger {
+    private readonly dir;
+    private readonly states;
+    constructor(dir: string);
+    static createForDataDir(dataDir: string): JiraContextLedger;
+    /** @description The issue's sent-set and generation, as a build reads them. */
+    getSnapshot(issueKey: string): JiraContextSnapshot;
+    /** @description A request's prompt was built from the snapshot of `generation`; `sent` is what it makes the sent-set once taken in. */
+    recordBuild(issueKey: string, requestId: string, generation: number, sent: JiraSentBlocks): void;
+    /** @description The agent took the request's prompt in: what it carried counts as sent — unless it is stale. */
+    commit(issueKey: string, requestId: string): void;
+    /** @description The request closed before its prompt was taken in: what it carried was never seen. */
+    drop(issueKey: string, requestId: string): void;
+    /**
+     * @description The conversation's agent lost its context (a fresh session, a completed compaction, C6): nothing
+     * counts as sent any more, and a build made before is dropped at its commit — its generation is gone.
+     */
+    reset(issueKey: string): void;
+    private getState;
+    /** A missing file is a conversation told nothing yet; an unreadable one is treated the same — the next prompt is whole. */
+    private load;
+    /** Atomic (a temp file renamed into place). A failed write is logged: at worst a block is sent again after a restart. */
+    private save;
+}
+export {};
+//# sourceMappingURL=contextLedger.d.ts.map

package/dist/connectors/jira/contextLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextLedger.d.ts","sourceRoot":"","sources":["../../../src/connectors/jira/contextLedger.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AACjD,2HAA2H;AAC3H,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAI5C,QAAA,MAAM,eAAe;;;;iBAMnB,CAAC;AAeH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAC5D,uCAAuC;AACvC,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAG3D,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;CAChC;AAWD,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;gBAE7B,GAAG,EAAE,MAAM;IAExC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB;IAI3D,+EAA+E;IAC/E,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB;IAKlD,uIAAuI;IACvI,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAWhG,gHAAgH;IAChH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAYjD,sGAAsG;IACtG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAO/C;;;OAGG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQ7B,OAAO,CAAC,QAAQ;IAQhB,2HAA2H;IAC3H,OAAO,CAAC,IAAI;IAoBZ,yHAAyH;IACzH,OAAO,CAAC,IAAI;CAYb"}

package/dist/connectors/jira/contextLedger.js

@@ -0,0 +1,196 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JiraContextLedger = exports.jiraPendingBuildsMaxCount = exports.jiraContextDirName = void 0;
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const zod_1 = require("zod");
+/**
+ * @description What each issue's conversation was already told (prompt context
+ * C4, C6): per issue, the hash of every block its agent has taken in (the
+ * sent-set), and per request the sent-set its prompt WOULD make once taken in.
+ *
+ *   build  → `recordBuild`: pending[request] = {generation, buildSeq, sent}
+ *   taken in (the ledger's flag, or a close by its own answer) → `commit`
+ *   superseded / cancelled → `drop`
+ *   fresh session / completed compaction → `reset` (S5): generation + 1, nothing sent, nothing pending
+ *
+ * A commit is dropped whole when its build belongs to an older generation (the
+ * agent lost that context since) or was built before the last committed one
+ * (the newer prompt already carried everything the older one did). When in
+ * doubt a block is sent twice, never lost. Persisted per issue in
+ * `DATA_DIR/jira-context/<ISSUE-KEY>.json`, written atomically, so a restart or
+ * a hot reload keeps it.
+ */
+exports.jiraContextDirName = 'jira-context';
+/** Builds kept waiting for their take-in; older ones are forgotten (their request closed without a word to the ledger). */
+exports.jiraPendingBuildsMaxCount = 20;
+const fileMode = 0o600;
+const dirMode = 0o700;
+const sentBlockSchema = zod_1.z.object({
+    hash: zod_1.z.string(),
+    /** A comment's `comment <id> by <name> from <date>`, for the line that says it was deleted. */
+    label: zod_1.z.string().optional(),
+    /** What was sent was a marker for text outside the trusted group; absent = the block was readable (a ledger from before the group). */
+    isWithheld: zod_1.z.boolean().optional(),
+});
+const sentBlocksSchema = zod_1.z.record(zod_1.z.string(), sentBlockSchema);
+const pendingBuildSchema = zod_1.z.object({
+    generation: zod_1.z.number().int(),
+    buildSeq: zod_1.z.number().int(),
+    sent: sentBlocksSchema,
+});
+const contextStateSchema = zod_1.z.object({
+    generation: zod_1.z.number().int(),
+    lastBuildSeq: zod_1.z.number().int(),
+    committedBuildSeq: zod_1.z.number().int(),
+    sent: sentBlocksSchema,
+    pending: zod_1.z.record(zod_1.z.string(), pendingBuildSchema),
+});
+function createEmptyState() {
+    return { generation: 0, lastBuildSeq: 0, committedBuildSeq: 0, sent: {}, pending: {} };
+}
+/** An issue key as a file name: Jira's keys are letters, digits, `_` and one `-`; anything else is replaced. */
+function getStateFileName(issueKey) {
+    return `${issueKey.replace(/[^A-Za-z0-9_-]/g, '_')}.json`;
+}
+class JiraContextLedger {
+    dir;
+    states = new Map();
+    constructor(dir) {
+        this.dir = dir;
+    }
+    static createForDataDir(dataDir) {
+        return new JiraContextLedger(path.join(dataDir, exports.jiraContextDirName));
+    }
+    /** @description The issue's sent-set and generation, as a build reads them. */
+    getSnapshot(issueKey) {
+        const state = this.getState(issueKey);
+        return { generation: state.generation, sent: state.sent };
+    }
+    /** @description A request's prompt was built from the snapshot of `generation`; `sent` is what it makes the sent-set once taken in. */
+    recordBuild(issueKey, requestId, generation, sent) {
+        const state = this.getState(issueKey);
+        state.lastBuildSeq += 1;
+        state.pending[requestId] = { generation, buildSeq: state.lastBuildSeq, sent };
+        const overflow = Object.entries(state.pending)
+            .sort(([, left], [, right]) => left.buildSeq - right.buildSeq)
+            .slice(0, Math.max(0, Object.keys(state.pending).length - exports.jiraPendingBuildsMaxCount));
+        for (const [staleRequestId] of overflow)
+            delete state.pending[staleRequestId];
+        this.save(issueKey, state);
+    }
+    /** @description The agent took the request's prompt in: what it carried counts as sent — unless it is stale. */
+    commit(issueKey, requestId) {
+        const state = this.getState(issueKey);
+        const build = state.pending[requestId];
+        if (!build)
+            return;
+        delete state.pending[requestId];
+        if (build.generation === state.generation && build.buildSeq > state.committedBuildSeq) {
+            state.sent = build.sent;
+            state.committedBuildSeq = build.buildSeq;
+        }
+        this.save(issueKey, state);
+    }
+    /** @description The request closed before its prompt was taken in: what it carried was never seen. */
+    drop(issueKey, requestId) {
+        const state = this.getState(issueKey);
+        if (!state.pending[requestId])
+            return;
+        delete state.pending[requestId];
+        this.save(issueKey, state);
+    }
+    /**
+     * @description The conversation's agent lost its context (a fresh session, a completed compaction, C6): nothing
+     * counts as sent any more, and a build made before is dropped at its commit — its generation is gone.
+     */
+    reset(issueKey) {
+        const state = this.getState(issueKey);
+        state.generation += 1;
+        state.sent = {};
+        state.pending = {};
+        this.save(issueKey, state);
+    }
+    getState(issueKey) {
+        const cached = this.states.get(issueKey);
+        if (cached)
+            return cached;
+        const loaded = this.load(issueKey);
+        this.states.set(issueKey, loaded);
+        return loaded;
+    }
+    /** A missing file is a conversation told nothing yet; an unreadable one is treated the same — the next prompt is whole. */
+    load(issueKey) {
+        const filePath = path.join(this.dir, getStateFileName(issueKey));
+        let text;
+        try {
+            text = fs.readFileSync(filePath, 'utf8');
+        }
+        catch (error) {
+            const isMissing = error instanceof Error && 'code' in error && error.code === 'ENOENT';
+            if (!isMissing)
+                console.warn(`[jira] ${issueKey}: cannot read its sent-state, the next prompt is whole: ${error instanceof Error ? error.message : String(error)}`);
+            return createEmptyState();
+        }
+        try {
+            const parsed = contextStateSchema.safeParse(JSON.parse(text));
+            if (parsed.success)
+                return parsed.data;
+        }
+        catch {
+            // Not JSON: same as a wrong shape.
+        }
+        console.warn(`[jira] ${issueKey}: its sent-state file is unreadable, the next prompt is whole`);
+        return createEmptyState();
+    }
+    /** Atomic (a temp file renamed into place). A failed write is logged: at worst a block is sent again after a restart. */
+    save(issueKey, state) {
+        const filePath = path.join(this.dir, getStateFileName(issueKey));
+        const tmpPath = `${filePath}.${(0, crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+        try {
+            fs.mkdirSync(this.dir, { recursive: true, mode: dirMode });
+            fs.writeFileSync(tmpPath, JSON.stringify(state), { mode: fileMode, flag: 'wx' });
+            fs.renameSync(tmpPath, filePath);
+        }
+        catch (error) {
+            fs.rmSync(tmpPath, { force: true });
+            console.warn(`[jira] ${issueKey}: its sent-state could not be saved (kept in memory): ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+exports.JiraContextLedger = JiraContextLedger;
+//# sourceMappingURL=contextLedger.js.map

package/dist/connectors/jira/contextLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextLedger.js","sourceRoot":"","sources":["../../../src/connectors/jira/contextLedger.ts"],"names":[],"mappings":"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"}

package/dist/connectors/jira/contextPreamble.d.ts

@@ -0,0 +1,18 @@
+import type { SessionKey } from '../../sessionKey';
+/**
+ * @description The Jira issue's context preamble (Jira connector plan J5, R5):
+ * what `[Telegram thread context]` is for a topic — where the agent works and
+ * for whom — glued ahead of a prompt by the bot's one choke point, re-sent only
+ * when it changes. Agent-facing, so English. Kept free of the connector's
+ * heavier modules: `bot.ts` imports it statically (R20).
+ */
+export declare const jiraContextPreambleHeader = "[Jira issue context]";
+export interface JiraContextPreambleInput {
+    /** A Jira conversation key: `space` is the project, `thread` the issue key. */
+    key: SessionKey;
+    /** The project's working folder under `WORK_ROOT`. */
+    subdir: string;
+    timezone?: string;
+}
+export declare function buildJiraContextPreamble(input: JiraContextPreambleInput): string;
+//# sourceMappingURL=contextPreamble.d.ts.map

package/dist/connectors/jira/contextPreamble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextPreamble.d.ts","sourceRoot":"","sources":["../../../src/connectors/jira/contextPreamble.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;GAMG;AAEH,eAAO,MAAM,yBAAyB,yBAAyB,CAAC;AAEhE,MAAM,WAAW,wBAAwB;IACvC,+EAA+E;IAC/E,GAAG,EAAE,UAAU,CAAC;IAChB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,CAgBhF"}