charness 0.0.0-stage → 3.0.0

package/dist/connectors/jira/answerSink.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jiraReadBackDelayMs = exports.jiraReadBackClockSkewMs = exports.jiraReadBackCommentCount = void 0;
+exports.buildJiraAlertText = buildJiraAlertText;
+exports.buildJiraParkText = buildJiraParkText;
+exports.createJiraAnswerSink = createJiraAnswerSink;
+const requestGroup_1 = require("../../requests/requestGroup");
+const adf_1 = require("./adf");
+const promptText_1 = require("./promptText");
+const unconfirmedPosts_1 = require("./unconfirmedPosts");
+/**
+ * @description The Jira connector's answer sink (plan J6, D20, R18): an answer
+ * becomes one or more comments by the AI account, in order; a `question` or a
+ * `final` answer to an open request hands the issue back to the requester — but
+ * ONLY while it is still assigned to the AI account (someone who took it
+ * meanwhile keeps it). Comment first, then the hand-back: a hand-back that fails
+ * leaves the answer delivered (a warning, never a retry that would post it twice).
+ * A comment post whose outcome is unknown (R18) is never re-posted blindly: the
+ * issue's newest comments are read once, after a short wait, and a matching
+ * comment by the AI account counts as delivered. A post left unconfirmed is
+ * remembered on disk (R29): when the same text is sent again for the same
+ * request, the issue is read first and a comment that did land is not posted
+ * twice. The agent cannot look at the issue itself, so every failure tells it
+ * what to send again. Bot texts on the issue are English (D20).
+ */
+/** How many of the issue's newest comments R18's read-back looks through. */
+exports.jiraReadBackCommentCount = 20;
+/**
+ * A comment Jira dated this much before the post started still counts as the post
+ * (clock skew) — short (R30), so an earlier identical comment, such as a repeated
+ * park notice, is not taken for the new one.
+ */
+exports.jiraReadBackClockSkewMs = 60 * 1000;
+/**
+ * How long the read-back waits after a post of unknown outcome: a post that timed
+ * out or met a 5xx may still be committing on Jira's side, and reading at once
+ * would call it "not posted" and invite the agent to post it twice.
+ */
+exports.jiraReadBackDelayMs = 10_000;
+/** How much of the first unposted part a partial delivery quotes, so the agent can tell where to resend from. */
+const missingPartPreviewChars = 80;
+const alertTexts = {
+    silentTurns: 'the agent ended its turns without answering, and the reminders gave up',
+    wakeCap: 'the agent was reminded as many times as allowed without answering',
+    wakeFailed: "the agent's session could not be reached to remind it",
+};
+/** @description The alert comment: which request, why, and that a person is needed (D20). */
+function buildJiraAlertText(requestId, reason) {
+    return `⚠️ The AI could not finish request ${requestId}: ${alertTexts[reason]}. A person needs to look at this issue.`;
+}
+/** @description The park notice (D12): over the run budget, handed back without a new request. */
+function buildJiraParkText(runBudgetPer24h) {
+    return `⏸ This issue was handed to the AI ${runBudgetPer24h} times in the last 24 hours, its limit, so no new request was opened. ` +
+        'Assign it to the AI again later, or ask the operator to raise the limit.';
+}
+/** A comment's text as the read-back compares it: its plain text, whitespace collapsed. */
+function getComparableText(body) {
+    return (0, promptText_1.getSingleLineText)((0, adf_1.getAdfText)(body));
+}
+/** The start of a comment's text, for the agent to find in its own answer. */
+function getTextPreview(body) {
+    const characters = [...getComparableText(body)];
+    return characters.length > missingPartPreviewChars ? `${characters.slice(0, missingPartPreviewChars).join('')}…` : characters.join('');
+}
+function createJiraAnswerSink(deps) {
+    const { client } = deps;
+    /** Is the comment on the issue, by the AI account, dated from the post's start on? `null` — the issue could not be read. */
+    async function checkIsCommentOnIssue(issueKey, comparableText, postStartedAt) {
+        try {
+            const comments = await client.getRecentComments(issueKey, exports.jiraReadBackCommentCount);
+            return comments.some((comment) => comment.author?.accountId === deps.aiAccountId
+                && Date.parse(comment.created) >= postStartedAt - exports.jiraReadBackClockSkewMs
+                && getComparableText(comment.body) === comparableText);
+        }
+        catch (error) {
+            console.warn(`[jira] ${issueKey}: read-back failed: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+    /**
+     * Post one comment. With a `requestId`, a post left unconfirmed is remembered,
+     * and a resend of a remembered one reads the issue first (R29).
+     */
+    async function postComment(issueKey, body, requestId) {
+        const comparableText = getComparableText(body);
+        const bodyHash = (0, unconfirmedPosts_1.getCommentBodyHash)(comparableText);
+        const earlierPostedAt = requestId === null ? null : deps.unconfirmedPosts.getPostedAt(requestId, bodyHash);
+        if (requestId !== null && earlierPostedAt !== null) {
+            const isEarlierOnIssue = await checkIsCommentOnIssue(issueKey, comparableText, earlierPostedAt);
+            if (isEarlierOnIssue === null) {
+                return { kind: 'unchecked', detail: 'the issue could not be read to check whether the earlier attempt landed' };
+            }
+            deps.unconfirmedPosts.settle(requestId, bodyHash);
+            if (isEarlierOnIssue)
+                return 'posted';
+        }
+        const postStartedAt = deps.now();
+        let result;
+        try {
+            result = await client.addComment(issueKey, body);
+        }
+        catch (error) {
+            return { kind: 'refused', detail: error instanceof Error ? error.message : String(error) };
+        }
+        if (result.outcome === 'created')
+            return 'posted';
+        // R18: a post that timed out or met a 5xx may still be committing on Jira's side.
+        await deps.wait(exports.jiraReadBackDelayMs);
+        const isOnIssue = await checkIsCommentOnIssue(issueKey, comparableText, postStartedAt);
+        if (isOnIssue === true)
+            return 'posted';
+        if (requestId !== null)
+            deps.unconfirmedPosts.recordUnconfirmed(requestId, bodyHash, postStartedAt);
+        return isOnIssue === false
+            ? { kind: 'notPosted', detail: `${result.reason}; it was not on the issue ${exports.jiraReadBackDelayMs / 1000} s later` }
+            : { kind: 'unknown', detail: result.reason };
+    }
+    async function postComments(issueKey, bodies, requestId) {
+        let postedCount = 0;
+        for (const body of bodies) {
+            const outcome = await postComment(issueKey, body, requestId);
+            if (outcome !== 'posted')
+                return { postedCount, failure: outcome };
+            postedCount += 1;
+        }
+        return { postedCount, failure: null };
+    }
+    /** Hand the issue back to the requester while it is still the AI's; a warning when that could not happen. */
+    async function handBack(issueKey, requesterAccountId) {
+        if (requesterAccountId === requestGroup_1.emptyRequester)
+            return 'no requester is known, so the issue stays assigned to the AI account';
+        try {
+            const issue = await client.getIssue(issueKey, ['assignee']);
+            // Someone took it meanwhile: they keep it.
+            if (issue.fields.assignee?.accountId !== deps.aiAccountId)
+                return null;
+            await client.assignIssue(issueKey, requesterAccountId);
+            return null;
+        }
+        catch (error) {
+            return `the issue could not be handed back to the requester (${error instanceof Error ? error.message : String(error)}); it stays assigned to the AI account`;
+        }
+    }
+    /**
+     * A failure before the first comment landed. The agent has no way to look at the
+     * issue itself, so the text says what to do: send again — and, when the issue
+     * could not be read, to send the same text unchanged, since only an identical
+     * resend is checked against the issue first (R29).
+     */
+    function getNothingPostedError(failure) {
+        switch (failure.kind) {
+            case 'refused':
+                return `Jira did not take the comment: ${failure.detail}`;
+            case 'notPosted':
+                return `Jira did not confirm the comment (${failure.detail}), so it was most likely not posted; send the answer again`;
+            case 'unknown':
+                return `Jira did not confirm the comment and the issue could not be read to check it (${failure.detail}); it may already be there. ` +
+                    'Send the answer again, unchanged: before the same text is posted again, the issue is read, so a comment that did land is not posted twice';
+            case 'unchecked':
+                return `Nothing was posted: ${failure.detail}. Send the answer again in a few minutes`;
+        }
+    }
+    /** A failure after some comments landed: where the unposted rest starts, so only that rest is sent again. */
+    function getMissingPartsWarning(bodies, posted, failure) {
+        const restStart = `"${getTextPreview(bodies[posted.postedCount])}"`;
+        const postedPart = `the first ${posted.postedCount} of the answer's ${bodies.length} comments reached the issue`;
+        if (failure.kind === 'unknown') {
+            return `${postedPart}; the next one, starting at ${restStart}, may or may not have (${failure.detail}; the issue could not be read to check), ` +
+                `and nothing after it was posted. Send the rest again, unchanged, starting at ${restStart} — the same text is checked against the issue first, so a comment that did land is not posted twice`;
+        }
+        if (failure.kind === 'unchecked') {
+            return `${postedPart}; nothing after them was posted (${failure.detail}). Send the rest again in a few minutes, starting at ${restStart}`;
+        }
+        return `${postedPart}, the rest did not (${failure.detail}). Send the rest again, starting at ${restStart} — not the comments already posted`;
+    }
+    return {
+        async deliverAnswer(key, delivery) {
+            const issueKey = key.thread;
+            const bodies = (0, adf_1.createCommentBodies)(delivery.body);
+            if (bodies.length === 0)
+                return { ok: false, error: 'the answer is empty' };
+            const posted = await postComments(issueKey, bodies, delivery.requestId);
+            if (posted.postedCount === 0 && posted.failure)
+                return { ok: false, error: getNothingPostedError(posted.failure) };
+            const warnings = [];
+            if (posted.failure)
+                warnings.push(getMissingPartsWarning(bodies, posted, posted.failure));
+            // An answer to a request that is no longer open (superseded by a newer one) must not take the issue from it.
+            if (delivery.isRequestOpen && (delivery.kind === 'question' || delivery.kind === 'final')) {
+                const handBackWarning = await handBack(issueKey, (0, requestGroup_1.getRequestRequester)(delivery.origin));
+                if (handBackWarning)
+                    warnings.push(handBackWarning);
+            }
+            return warnings.length > 0 ? { ok: true, warning: warnings.join('; ') } : { ok: true };
+        },
+        async deliverAlert(key, alert) {
+            const issueKey = key.thread;
+            const posted = await postComments(issueKey, [(0, adf_1.convertMarkdownToAdf)(buildJiraAlertText(alert.requestId, alert.reason))], alert.requestId);
+            if (posted.postedCount === 0 && posted.failure)
+                return { ok: false, error: getNothingPostedError(posted.failure) };
+            const handBackWarning = await handBack(issueKey, (0, requestGroup_1.getRequestRequester)(alert.origin));
+            if (handBackWarning)
+                console.warn(`[jira] ${issueKey}: alert for ${alert.requestId}: ${handBackWarning}`);
+            // A comment needs no release: nothing is pinned.
+            return { ok: true };
+        },
+        async releaseAlert() { },
+        async parkIssue(issueKey, requester) {
+            const posted = await postComments(issueKey, [(0, adf_1.convertMarkdownToAdf)(buildJiraParkText(deps.runBudgetPer24h))], null);
+            if (posted.postedCount === 0 && posted.failure) {
+                console.warn(`[jira] ${issueKey}: park notice not posted: ${getNothingPostedError(posted.failure)}`);
+                return;
+            }
+            const handBackWarning = await handBack(issueKey, requester?.accountId ?? requestGroup_1.emptyRequester);
+            if (handBackWarning)
+                console.warn(`[jira] ${issueKey}: park: ${handBackWarning}`);
+        },
+    };
+}
+//# sourceMappingURL=answerSink.js.map

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * @description Stream one Jira attachment's content to a file (prompt context
+ * C10). No size limit: the body is written chunk by chunk, never held whole, so
+ * a file of any size works. The only rules are technical necessities:
+ *
+ *  - a STALL timeout — a connection that stops delivering never ends by itself
+ *    and would hold the agent's tool call for ever, so no bytes for
+ *    {@link jiraDownloadStallTimeoutMs} (headers included) aborts the download;
+ *  - the credentials go only to the site (its origin — scheme, host and port):
+ *    `redirect=false` makes Jira answer with the content itself, but a 3xx to
+ *    another host (Atlassian's media CDN, whose URL carries its own token) or to
+ *    plain http is followed WITHOUT the Authorization header, so the token is
+ *    never handed to a host that did not ask for it, nor sent unencrypted;
+ *  - the file is created exclusively (`wx`) at the path it is given — a caller
+ *    hands it a fresh temporary name and renames it into place.
+ */
+export declare const jiraDownloadStallTimeoutMs: number;
+/** A redirect chain longer than this is a loop, not a download. */
+export declare const jiraDownloadMaxRedirects = 5;
+export interface JiraDownloadOptions {
+    /** `https://<site>`, no trailing slash. */
+    baseUrl: string;
+    authorization: string;
+    fetchImpl: typeof fetch;
+    stallTimeoutMs: number;
+}
+export type JiraDownloadResult = {
+    ok: true;
+    bytes: number;
+} | {
+    ok: false;
+    status: number;
+    detail: string;
+};
+/**
+ * @description Download attachment `attachmentId` into the new file `destinationPath`.
+ * Resolves a failure instead of throwing for every outcome the caller reports
+ * (a refusal, a stall, a broken connection); the file, if any was begun, is removed.
+ */
+export declare function downloadJiraAttachment(options: JiraDownloadOptions, attachmentId: string, destinationPath: string): Promise<JiraDownloadResult>;
+//# sourceMappingURL=attachmentDownload.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"attachmentDownload.d.ts","sourceRoot":"","sources":["../../../src/connectors/jira/attachmentDownload.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,0BAA0B,QAAgB,CAAC;AACxD,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAK1C,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,OAAO,KAAK,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,mBAAmB,EAC5B,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAoD7B"}

package/dist/connectors/jira/attachmentDownload.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jiraDownloadMaxRedirects = exports.jiraDownloadStallTimeoutMs = void 0;
+exports.downloadJiraAttachment = downloadJiraAttachment;
+const fs_1 = require("fs");
+/**
+ * @description Stream one Jira attachment's content to a file (prompt context
+ * C10). No size limit: the body is written chunk by chunk, never held whole, so
+ * a file of any size works. The only rules are technical necessities:
+ *
+ *  - a STALL timeout — a connection that stops delivering never ends by itself
+ *    and would hold the agent's tool call for ever, so no bytes for
+ *    {@link jiraDownloadStallTimeoutMs} (headers included) aborts the download;
+ *  - the credentials go only to the site (its origin — scheme, host and port):
+ *    `redirect=false` makes Jira answer with the content itself, but a 3xx to
+ *    another host (Atlassian's media CDN, whose URL carries its own token) or to
+ *    plain http is followed WITHOUT the Authorization header, so the token is
+ *    never handed to a host that did not ask for it, nor sent unencrypted;
+ *  - the file is created exclusively (`wx`) at the path it is given — a caller
+ *    hands it a fresh temporary name and renames it into place.
+ */
+exports.jiraDownloadStallTimeoutMs = 2 * 60 * 1000;
+/** A redirect chain longer than this is a loop, not a download. */
+exports.jiraDownloadMaxRedirects = 5;
+const attachmentFileMode = 0o600;
+const redirectStatusMin = 300;
+const redirectStatusMax = 399;
+/**
+ * @description Download attachment `attachmentId` into the new file `destinationPath`.
+ * Resolves a failure instead of throwing for every outcome the caller reports
+ * (a refusal, a stall, a broken connection); the file, if any was begun, is removed.
+ */
+async function downloadJiraAttachment(options, attachmentId, destinationPath) {
+    const siteOrigin = new URL(options.baseUrl).origin;
+    const controller = new AbortController();
+    let stallTimer = null;
+    const armStallTimer = () => {
+        if (stallTimer)
+            clearTimeout(stallTimer);
+        stallTimer = setTimeout(() => controller.abort(new Error(`no data for ${Math.round(options.stallTimeoutMs / 1000)} s`)), options.stallTimeoutMs);
+    };
+    let file = null;
+    try {
+        armStallTimer();
+        let url = `${options.baseUrl}/rest/api/3/attachment/content/${encodeURIComponent(attachmentId)}?redirect=false`;
+        for (let hop = 0;; hop += 1) {
+            const response = await options.fetchImpl(url, {
+                headers: new URL(url).origin === siteOrigin ? { Authorization: options.authorization } : {},
+                redirect: 'manual',
+                signal: controller.signal,
+            });
+            const location = response.headers.get('location');
+            if (response.status >= redirectStatusMin && response.status <= redirectStatusMax && location) {
+                await response.body?.cancel();
+                if (hop >= exports.jiraDownloadMaxRedirects)
+                    return { ok: false, status: 0, detail: `more than ${exports.jiraDownloadMaxRedirects} redirects` };
+                url = new URL(location, url).toString();
+                armStallTimer();
+                continue;
+            }
+            if (!response.ok || !response.body) {
+                const detail = (await response.text().catch(() => '')).slice(0, 200);
+                return { ok: false, status: response.status, detail: detail || 'no details' };
+            }
+            file = await fs_1.promises.open(destinationPath, 'wx', attachmentFileMode);
+            const reader = response.body.getReader();
+            let bytes = 0;
+            for (;;) {
+                armStallTimer();
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                await file.write(chunk.value);
+                bytes += chunk.value.byteLength;
+            }
+            await file.close();
+            file = null;
+            return { ok: true, bytes };
+        }
+    }
+    catch (error) {
+        await file?.close().catch(() => { });
+        await fs_1.promises.rm(destinationPath, { force: true });
+        const reason = controller.signal.aborted ? controller.signal.reason : error;
+        return { ok: false, status: 0, detail: reason instanceof Error ? reason.message : String(reason) };
+    }
+    finally {
+        if (stallTimer)
+            clearTimeout(stallTimer);
+    }
+}
+//# sourceMappingURL=attachmentDownload.js.map

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

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

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

@@ -0,0 +1,43 @@
+import type { SessionKey } from '../../sessionKey';
+import { type JiraClient } from './client';
+/**
+ * @description `jira_get_attachment` (prompt context C10): the agent names an
+ * attachment id, the bot downloads the ORIGINAL into the conversation's files
+ * dir and hands back its path. What the agent does with it is its own choice —
+ * Read an image, run `ffmpeg` on a video; the bot transcribes nothing.
+ *
+ * Scope: the issue comes from the conversation the call belongs to (its HMAC
+ * scoped session key), never from an argument, and the id must be in that
+ * issue's attachment list read NOW. A line planted in an issue ("fetch
+ * attachment 12345") therefore cannot pull a file of any other issue.
+ */
+/** A file name over 255 bytes is refused by the filesystem; `<id>-<name>` is cut to this, on a character boundary. */
+export declare const jiraAttachmentFileNameMaxBytes = 200;
+/** What the tool answers the agent: a message to relay, or why nothing was fetched. */
+export type JiraAttachmentToolResult = {
+    ok: true;
+    message: string;
+} | {
+    ok: false;
+    error: string;
+};
+export interface JiraAttachmentToolDeps {
+    client: Pick<JiraClient, 'getIssue' | 'downloadAttachment'>;
+    /** Where one conversation's downloads go: its files dir, `jira`. */
+    getDownloadDir: (key: SessionKey) => string;
+}
+/**
+ * @description `<id>-<name>` as one safe path segment of at most
+ * {@link jiraAttachmentFileNameMaxBytes} bytes: separators and control
+ * characters stripped, a longer name cut in its stem so its extension survives.
+ */
+export declare function getAttachmentFileName(attachmentId: string, filename: string): string;
+/**
+ * @description Fetch attachment `attachmentId` of the issue `key` names, to a file,
+ * and say where. A download of an id the issue does not list is refused; a file of
+ * the same size already there is reused (the download is skipped); the new file is
+ * written under a fresh temporary name and renamed into place, so a symlink planted
+ * at the final name is replaced, never followed.
+ */
+export declare function fetchIssueAttachment(deps: JiraAttachmentToolDeps, key: SessionKey, attachmentId: string): Promise<JiraAttachmentToolResult>;
+//# sourceMappingURL=attachmentTool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"attachmentTool.d.ts","sourceRoot":"","sources":["../../../src/connectors/jira/attachmentTool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAsC,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAG/E;;;;;;;;;;GAUG;AAEH,sHAAsH;AACtH,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAOlD,uFAAuF;AACvF,MAAM,MAAM,wBAAwB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpG,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,oBAAoB,CAAC,CAAC;IAC5D,oEAAoE;IACpE,cAAc,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,MAAM,CAAC;CAC7C;AAcD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CASpF;AAwBD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,sBAAsB,EAAE,GAAG,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CA2BjJ"}

package/dist/connectors/jira/attachmentTool.js

@@ -0,0 +1,150 @@
+"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.jiraAttachmentFileNameMaxBytes = void 0;
+exports.getAttachmentFileName = getAttachmentFileName;
+exports.fetchIssueAttachment = fetchIssueAttachment;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const client_1 = require("./client");
+const promptText_1 = require("./promptText");
+/**
+ * @description `jira_get_attachment` (prompt context C10): the agent names an
+ * attachment id, the bot downloads the ORIGINAL into the conversation's files
+ * dir and hands back its path. What the agent does with it is its own choice —
+ * Read an image, run `ffmpeg` on a video; the bot transcribes nothing.
+ *
+ * Scope: the issue comes from the conversation the call belongs to (its HMAC
+ * scoped session key), never from an argument, and the id must be in that
+ * issue's attachment list read NOW. A line planted in an issue ("fetch
+ * attachment 12345") therefore cannot pull a file of any other issue.
+ */
+/** A file name over 255 bytes is refused by the filesystem; `<id>-<name>` is cut to this, on a character boundary. */
+exports.jiraAttachmentFileNameMaxBytes = 200;
+/** The longest extension kept when a long name is cut (so `.png` / `.mp4` still tell the type). */
+const extensionMaxBytes = 16;
+/** Path separators and control characters: a name must stay ONE path segment. */
+const unsafeFileNameCharsRe = /[\/\\\u0000-\u001f\u007f]/g;
+const mimeTypeUnknown = 'unknown type';
+/** The longest prefix of `text` of at most `maxBytes` UTF-8 bytes, cut between characters. */
+function getPrefixWithinBytes(text, maxBytes) {
+    let bytes = 0;
+    let prefix = '';
+    for (const character of text) {
+        bytes += Buffer.byteLength(character);
+        if (bytes > maxBytes)
+            break;
+        prefix += character;
+    }
+    return prefix;
+}
+/**
+ * @description `<id>-<name>` as one safe path segment of at most
+ * {@link jiraAttachmentFileNameMaxBytes} bytes: separators and control
+ * characters stripped, a longer name cut in its stem so its extension survives.
+ */
+function getAttachmentFileName(attachmentId, filename) {
+    const prefix = `${attachmentId.replace(unsafeFileNameCharsRe, '')}-`;
+    const name = filename.replace(unsafeFileNameCharsRe, '');
+    const budget = exports.jiraAttachmentFileNameMaxBytes - Buffer.byteLength(prefix);
+    if (Buffer.byteLength(name) <= budget)
+        return `${prefix}${name}`;
+    const extension = path.extname(name);
+    const keptExtension = Buffer.byteLength(extension) <= extensionMaxBytes ? extension : '';
+    const stem = name.slice(0, name.length - keptExtension.length);
+    return `${prefix}${getPrefixWithinBytes(stem, budget - Buffer.byteLength(keptExtension))}${keptExtension}`;
+}
+/** Is a regular file (never a symlink: `lstat` does not follow one) of exactly `size` bytes already there? */
+async function checkHasRegularFileOfSize(filePath, size) {
+    if (size === undefined)
+        return false;
+    try {
+        const stat = await fs_1.promises.lstat(filePath);
+        return stat.isFile() && stat.size === size;
+    }
+    catch {
+        return false;
+    }
+}
+function describeSavedAttachment(attachment, filePath, bytes) {
+    // Written by whoever attached the file: kept on one line, like every other piece of issue text.
+    const mimeType = (0, promptText_1.getSingleLineText)(attachment.mimeType ?? '') || mimeTypeUnknown;
+    const hint = mimeType.startsWith('image/')
+        ? ' View it with your file-reading tool.'
+        : mimeType.startsWith('video/')
+            ? ' It is a video: if ffmpeg is on your PATH, take frames or the audio track from it.'
+            : '';
+    return `Attachment ${attachment.id} (${(0, promptText_1.getSingleLineText)(attachment.filename)}, ${mimeType}, ${bytes} bytes) is saved at ${filePath}.${hint}`;
+}
+/**
+ * @description Fetch attachment `attachmentId` of the issue `key` names, to a file,
+ * and say where. A download of an id the issue does not list is refused; a file of
+ * the same size already there is reused (the download is skipped); the new file is
+ * written under a fresh temporary name and renamed into place, so a symlink planted
+ * at the final name is replaced, never followed.
+ */
+async function fetchIssueAttachment(deps, key, attachmentId) {
+    const issueKey = key.thread;
+    try {
+        const issue = await deps.client.getIssue(issueKey, ['attachment']);
+        const attachment = (issue.fields.attachment ?? []).find((candidate) => candidate.id === attachmentId);
+        if (!attachment) {
+            const listed = (issue.fields.attachment ?? []).map((candidate) => candidate.id).join(', ') || 'none';
+            return { ok: false, error: `Attachment ${attachmentId} is not an attachment of ${issueKey}. Its attachments: ${listed}.` };
+        }
+        const downloadDir = deps.getDownloadDir(key);
+        const filePath = path.join(downloadDir, getAttachmentFileName(attachment.id, attachment.filename));
+        if (await checkHasRegularFileOfSize(filePath, attachment.size)) {
+            return { ok: true, message: describeSavedAttachment(attachment, filePath, attachment.size ?? 0) };
+        }
+        await fs_1.promises.mkdir(downloadDir, { recursive: true, mode: 0o700 });
+        const tmpPath = `${filePath}.${(0, crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+        try {
+            const bytes = await deps.client.downloadAttachment(attachment.id, tmpPath);
+            await fs_1.promises.rename(tmpPath, filePath);
+            return { ok: true, message: describeSavedAttachment(attachment, filePath, bytes) };
+        }
+        finally {
+            await fs_1.promises.rm(tmpPath, { force: true });
+        }
+    }
+    catch (error) {
+        if (error instanceof client_1.JiraAuthError)
+            return { ok: false, error: `Jira refused the download of attachment ${attachmentId} (${error.status}).` };
+        return { ok: false, error: `Attachment ${attachmentId} could not be fetched: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+//# sourceMappingURL=attachmentTool.js.map

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

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