Skip to content

fix(markdown): keep a link's parenthesised URL whole outside chat - #15714

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
unstablebrainiac:fix/parenthesised-link-url-sweep
Oct 1, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
unstablebrainiac:fix/parenthesised-link-url-sweep

Conversation

@unstablebrainiac

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A Markdown link whose URL holds a balanced pair of parentheses shows only its label in session previews, artifact snippets and spoken replies and links its whole URL on artifact-deploy pages, and a long run of [ no longer stalls any of the four.

A link such as [Python](https://en.wikipedia.org/wiki/Python_(programming_language)) still comes out broken in four places outside chat. Each reads links with its own pattern, and each pattern ends the URL at its first ).

Where What the reader gets on main
Session preview (sidebar, session list) see Python) now
Artifact snippet (artifact list) See Python) docs
Voice reply the URL's tail is spoken: [docs](https://example.com/a_(b)_c) reads as docsc)
Artifact-deploy page <a href=".../Python_(programming_language">Python</a>), a link to a page that does not exist

The same patterns let a label run on to the next ], so in a long run of [ every opener rescans the rest of the text. 20,000 of them take 2.4 s in the session preview, which strips the last message of every session the list shows.

Why it matters

Agents cite Wikipedia and vendor docs often. Every such message leaves a stray ) in the sidebar preview and the artifact list, a spoken reply reads part of the URL aloud, and a published deploy page sends its readers to a missing page. A reply holding a long run of [ holds up the session list.

Not a goal

  • The prepare-pr skill's local_review.py media filter. It mirrors the review workflow's own perl filter, so it must match that filter rather than CommonMark.
  • The web app's own link regexes.
  • Nesting deeper than one level and backslash-escaped parentheses, which the shared grammar leaves unlinked.

What changed (motivation → approach → change)

Session previews, artifact snippets, spoken replies and artifact-deploy pages read a link with a parenthesised URL whole: the first three show only its label, and the deploy page links the full URL. Each of the four patterns ended the URL at its first ) ([^)]*). Each now builds it from constants.md_link_destination(), the unit every chat channel and the display-safety screen use, which takes one URL character or one balanced (...) group.

File Pattern URL characters
preview_text.py _IMAGE_RE, _LINK_RE any but a parenthesis ([^()])
voice_reply.py _MARKDOWN_LINK_RE [^()]
dashboard/handlers/artifacts.py _MD_LINK_RE [^()]
deploy/render.py _LINK_RE no whitespace either ([^()\s])

Each keeps its own character class apart from the parentheses, so a title, a space or a line break in a destination is handled as before. A destination the shared unit does not read as a link is left as written, which is what the chat channels show for it: an unbalanced (, two levels of nesting, an escaped \), or a [label]( inside the URL. On the deploy page that means plain text rather than a link to a cut URL.

Each label stops at the next [ ([^\[\]]), so a run of [ is read in one pass. A label can still span a line break, as CommonMark link text can, so a hard-wrapped label is stripped as before.

Backwards compatibility

Compatible: no input is refused. A link is stripped or linked as before unless its destination holds a parenthesis or its label holds a [. A balanced pair stays inside the URL, and an unbalanced (, deeper nesting, an escaped \) or a nested [label]( leaves the link as written instead of cutting it at its first ). A label holding a [, as in [a [b](u), starts at its last [ and gives [a b, as on every chat channel and in CommonMark.

Tests

  • test/test_preview_text.py: a Wikipedia link previews as its label alone, an image with a parenthesised URL previews as its alt text or (image), and an unbalanced URL is left as written.
  • test/test_voice_reply.py: a parenthesised URL is not spoken, with and without text after the pair.
  • test/test_artifacts_handlers.py: the ?snippet=1 list snippet of a markdown artifact drops a parenthesised URL whole.
  • test/test_deploy_web_render_scan.py: the deploy page's href carries the whole Wikipedia URL, and an unbalanced URL renders as text with no link.
  • test/test_markdown_link_parentheses.py: the five patterns are timed on 5,000 and 20,000 repeats of [b, ![b, [b with a line break and [b](x, and must stay under 0.5 s and grow linearly. Each still reads a hard-wrapped label as one link. The walker-agreement test's class list names the new callers; both classes they pass were already pinned to the outbound_files walker.
  • The seven behaviour tests fail on main on their assertion. Restoring the old label class fails 13 of the 20 speed cases, restoring [^)]* fails the [b](x case of the preview, voice and snippet link patterns, and excluding the line break from a label fails that pattern's hard-wrap case.

Manual verification

Ran the four call sites on main and on this branch over twelve link shapes: Wikipedia and MSDN URLs, a pair followed by text, a plain URL, unbalanced, two-deep and escaped destinations, a nested link, a titled link, two images and a link in an aside. Only the parenthesised and unlinkable shapes changed, as described above. A label holding [ and a hard-wrapped label were checked separately, with the results stated above.

Timed the four sites at 10,000 and 20,000 characters on both. On a run of [, unclosed [a]( openers, ( runs after openers and [b]( runs inside a URL, main's time grows with the square of the length (up to 2.4 s at 20,000) and this branch's grows linearly (at most 5 ms). One opener followed by 20,000 URL characters takes up to 7 ms here against up to 5 ms on main.

Related Issues

no linked issue: #14314 recorded this follow-up in its Pattern harvest; no issue tracks it.

Pattern harvest

Rule candidate: semgrep
Pattern: a Markdown-link regex whose destination is spelled [^)]… instead of built from constants.md_link_destination. After this change the only such regex under src/ is the prepare-pr filter listed under Not a goal.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable): N/A, no spec describes these four patterns
  • No secrets, credentials, or internal references in the diff

@unstablebrainiac
unstablebrainiac requested a review from a team as a code owner October 1, 2026 04:33
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Oct 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed 2065bdff837bc8cc09452f4484ca12aaa5a7d6b4 via the fork AI-review pipeline; updated in place on each push.

Review details

Advisory only: an unbalanced ( in a link URL now survives the strip at the two surfaces whose output is prose or speech, not a rendering.

FINDING — src/kiro_crew/dashboard/handlers/artifacts.py:582 — a truncated link such as See [Python](https://en.wikipedia.org/wiki/Python_(programming_language) docs no longer matches md_link_destination('[^()]')*\) (the destination consumes https://en.wikipedia.org/wiki/Python_, the balanced (programming_language), then docs, and no backtrack position finds the closing \)), and nothing later in _clean_markdown removes [/]/(/), so the list snippet now shows the raw URL where it read See Python docs and burns the 160-char _SNIPPET_MAX_LEN budget on it; the same hunk in voice_reply.py:373 leaves [label]( in the TTS text → Fix: at these two strip-only sites, follow the link pass with a fallback that still collapses an unbalanced [label](… to its label (the renderer-fidelity rationale the new test_an_unbalanced_link_url_is_left_as_written records applies to the preview and deploy page, not to a prose snippet or a speech stream).

[OPUS-REVIEWED] 2065bdf

@unstablebrainiac
unstablebrainiac force-pushed the fix/parenthesised-link-url-sweep branch from bd80a8f to 47e5871 Compare October 1, 2026 05:08
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in files beside this PR's (apps/routes.py imports one of them; dashboard/handlers/_shared.py, session_cleanup.py and 12 others share their directories) since this head went green (ecdc59a -> 7038f5f); CI re-running. The patch is unchanged.

The re-run also repeats the lanes a GitHub installation rate limit stopped on the previous head: Security Scope Review wrote no candidates, Design and First Principles reported incomplete, and the GPT lane passed without posting its comment.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 2065bdff837bc8cc09452f4484ca12aaa5a7d6b4 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] 2065bdf

Description read

[DESCRIPTION-READ] 11f1ead195123843d0a8776054133d1025cf94a0040d37138c5f0a7b0c28012a

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of 2065bdff837bc8cc09452f4484ca12aaa5a7d6b4 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify the one deliberate divergence: these four labels keep \n (hard-wrapped documents) where every chat-channel caller uses [^\[\]\n] — declared and tested, but it is the only seam.

What this change ships

Inventory (8 items) — 8 justified

Intent: FIX — links whose URLs hold a balanced parenthesis pair render whole in session previews, artifact snippets, voice replies and deploy pages, without quadratic rescans.

  1. Session preview shows only the label for a link/image with a parenthesised URL — justified
  2. Artifact-list snippet drops such a link's URL whole — justified
  3. Voice reply no longer speaks the tail of a parenthesised URL — justified
  4. Artifact-deploy page links the full parenthesised URL instead of a cut one — justified
  5. An unlinkable destination (unbalanced, escaped, nested) is left as written, not cut at its first ) — justified
  6. A long run of [ no longer stalls these four surfaces — justified
  7. A label holding [ now starts at its last [ ([a [b](u) → [a b) — justified
  8. A hard-wrapped label still reads as a link on these four surfaces, unlike chat channels — justified

[FIRST-PRINCIPLES-REVIEWED] 2065bdf

Description read

[DESCRIPTION-READ] 6d2dbc32bd03b42a05666746024146b89a98895ee777ccbcb3d2c534884ec666

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 2065bdff837bc8cc09452f4484ca12aaa5a7d6b4 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2065bdf

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 1, 2026
@unstablebrainiac
unstablebrainiac force-pushed the fix/parenthesised-link-url-sweep branch from 47e5871 to f8587f9 Compare October 1, 2026 05:55
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

Rebased: main moved since this head's CI ran (7038f5f -> 20a9365, 18 commits). The overlap is same-directory and importing files only; none of this PR's files changed, and the patch is identical. The Opus 5 Review lane on 47e5871 ended "review incomplete" because the fork lane hit "API rate limit exceeded for installation" at 05:31 UTC, before the review ran. CI re-running.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 1, 2026
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

self-added: no

  • rebutted: an unbalanced destination is left as written, by design

Measured on this head for see [a](https://example.com/(b) now: preview, snippet and deploy page show the text as written; voice gives see [a]( (link) now. The base (20a9365) gave see a now, and its deploy page linked the cut URL https://example.com/(b.
That input is not a CommonMark link: the ( has no closing pair before the link's own ). The chat renderers already show it as written, so the four outside-chat sites now agree with chat instead of inventing a link.
Voice still never speaks the URL: the bare-URL pass replaces it with (link).
The base's shorter see a now came from the same cut at the first ) that broke every URL holding a balanced pair. Keeping it would need a second pattern for a shape that CommonMark does not treat as a link.

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

self-added: no

  • rebutted: [a [b](u) reads as [a b, by design

Measured on this head for see [a [b](https://example.com/u) now: preview, voice and snippet give see [a b now; the deploy page gives see [a <a href="https://example.com/u">b</a> now. The base (20a9365) gave see a [b now and linked a [b.
This is the CommonMark reading. A ] closes the nearest unmatched [, so the link is [b](...) and [a is plain text, which is what the chat renderers show. The base took the outer [ as the label start, which CommonMark does not do.
The label class [^\[\]] that gives this output is also what keeps a long run of [ linear.

@unstablebrainiac
unstablebrainiac force-pushed the fix/parenthesised-link-url-sweep branch from f8587f9 to 54c298e Compare October 1, 2026 06:52
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 1, 2026
@unstablebrainiac

unstablebrainiac commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor Author

Re-pushed the same commit (identical tree, same base 20a9365) to rerun CI. Backend Tests (Windows) (2) failed on f8587f9 on one timing-dependent test outside this PR: test/test_md_notebook.py::test_a_sync_while_the_temp_is_still_staging_never_commits_it, which waits 10 s for a staged temp file. It did not fail in main's own CI run at d5bdff6, Windows shards included. CI runs this PR merged into main's current tip, so main's own reds (test_fold_catalogue, test_lesson_turn_injection, test_vector_memory_composition_contract, red on main at d5bdff6 and 2db531e) show up here too until main is fixed.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 1, 2026
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

self-added: no

  • rebutted: voice does not speak the unbalanced URL

Measured on this head for see [a](https://example.com/(b) now: voice gives see [a]( (link) now. The bare-URL pass still replaces the URL with (link), so the URL is never read out. What remains is the brackets the author typed.
The base (20a9365) gave see a now only because it cut the destination at the first ) and treated the rest as a link.
CommonMark does not read this input as a link, and the chat renderers show it as written. Stripping it in voice alone would need a second pattern for a shape no renderer treats as a link. Same input as the disposition on f8587f9; this tree is identical.

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

self-added: no

  • rebutted: no published page changes

A deploy page is rendered once, at deploy time. _stage_artifact_html in src/kiro_crew/deploy/handlers.py is the only caller of render_standalone, and it writes a static index.html for the upload. A page already published keeps the HTML it was deployed with. Only a later deploy or re-deploy picks up this change.
For see [a](https://example.com/(b) now the base (20a9365) linked https://example.com/(b, the destination cut at its first ). CommonMark does not read the input as a link, so there was no intended target to keep. On this head the page shows that line as text, the same as the chat renderers, the session preview and the artifact snippet.

The session preview, voice reply, artifact snippet and artifact-deploy
page each read a Markdown link with their own pattern, which ended the
URL at its first ")". A link such as
[Python](https://en.wikipedia.org/wiki/Python_(programming_language))
left a stray ")" after the label in the preview, the snippet and the
spoken reply, and the deploy page linked a URL with its ")" cut off.

All four build the destination from constants.md_link_destination(),
the unit every channel renderer and the display-safety screen use, so a
balanced "(...)" pair stays inside the URL. A destination that unit does
not read as a link (an unbalanced "(", nesting two deep, an escaped ")"
or a nested "[label](") is left as written, as the channel renderers
leave it.

Each label stops at the next "[", so a long run of "[" is read in linear
time. A label that ran on to the next "]" made every opener rescan the
rest of the text, which stalled the dashboard's slot preview on a
bracket-heavy reply.
@unstablebrainiac
unstablebrainiac force-pushed the fix/parenthesised-link-url-sweep branch from 54c298e to 2065bdf Compare October 1, 2026 09:46
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

Rebased onto d8fa6a5, where main's own CI passes again: every Backend Tests shard and Backend Lint & Type Check are green in run 36832900240. Every red on 54c298e came from main (test_fold_catalogue, test_lesson_turn_injection, test_vector_memory_composition_contract, and the flake8 F821 in lessons.py), plus one Windows runner socket error at test setup (WinError 10055). None of this PR's files changed on main, and the patch is identical. CI re-running.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 1, 2026
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

self-added: no

  • rebutted: a link whose destination never closes is left as written at every site, by design

Measured for See [Python](https://en.wikipedia.org/wiki/Python_(programming_language) docs. On 2065bdf the preview and deploy page keep it as written, the snippet gives See [Python](https://en.wikipedia.org/wiki/Python(programminglanguage) docs, and voice gives See [Python]( (link) docs. On base d8fa6a5 the three strip sites gave See Python docs, and the deploy page linked the cut URL https://en.wikipedia.org/wiki/Python_(programming_language.
The snippet's missing _ comes from its emphasis pass, which strips it from any bare URL on base too.
The input is not a link: its ( never closes. The shared md_link_destination grammar the chat renderers use leaves it as written, and CommonMark, which the dashboard's react-markdown view follows, does not parse it as a link. So the snippet and the session preview now show what the rendered artifact or message shows.
Voice never speaks the URL: the bare-URL pass replaces it with (link).
Base's See Python docs came from ending the URL at the first ), the rule that broke every balanced URL. A fallback at the two strip sites would add a second end-of-URL guess for a shape no renderer treats as a link, and the same text would read differently across the four sites.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 1, 2026
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

self-added: no

  • verified: the \n in these labels is deliberate, pinned, and reaches no display-safety screen

CommonMark link text may span a line break, and artifact Markdown, which the snippet and deploy page read, hard-wraps labels. test_a_hard_wrapped_label_is_still_a_link checks all five patterns, and narrowing any one label to [^\[\]\n] fails that site's case.
The chat-channel patterns that exclude \n (display_safety.py, whatsapp/renderer.py, imessage/plaintext.py) turn a chat message into a channel's own link form and must agree with the display-safety screen, which reads link labels within one line.
None of these four sites feeds that screen. The session preview's only redaction runs on the already-stripped text (slot_projection.py:288, redact(strip_markdown_preview(text))), so a label across a line cannot hide text from it.

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed. All five link patterns build the URL from md_link_destination and stop the label at the next '['; deploy/render.py still html.escape()s before the regex and re-escapes the href, the scheme stays a literal https?://, and the stricter URL class leaves a non-matching link as escaped text. artifacts.py only produces a snippet through _STRIP_TAGS_RE. Tests pin each behaviour plus the linear-time bound.

Non-blocking: voice_reply.py:420 now reads an unbalanced-paren URL aloud where main read only the label (no test); no test proves the href stays escaped with a quote inside a parenthesised URL.

@iamwhatever
iamwhatever enabled auto-merge (squash) October 1, 2026 16:04
@iamwhatever
iamwhatever merged commit 2412214 into kirodotdev:main Oct 1, 2026
100 checks passed
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

Both notes measured on 2065bdf against main 996b450.

voice_reply.py:420: an http(s) URL is still not spoken. The link is left as written, and the bare-URL pass after it turns the URL into (link): see [a](https://example.com/(b) now gives see [a]( (link) now, where main gave see a now. A non-http destination is spoken as written: see [guide](docs/setup_(old) now gives see [guide](docs/setup(old) now, where main gave see guide now. No test pins either output.

deploy href: see [a](https://example.com/(b"c)) now renders <a href="https://example.com/(b&quot;c)">a</a>. The html.unescape then html.escape pair round-trips the pre-escaped quote, so (b"onmouseover="x) also stays inside the attribute as &quot;. Main escapes it too, but cuts the URL at (b&quot;c and leaves the ) after the link. No test pins the quote case.

@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 1, 2026
unstablebrainiac added a commit to unstablebrainiac/KiroCrew that referenced this pull request Oct 1, 2026
Two outputs of the parenthesised-URL sweep (kirodotdev#15714) had no test.

A link whose destination holds an unbalanced "(" is not a link, so the
voice reply leaves its text as written. A web address in it is still
replaced by "(link)", but a relative destination is spoken as written.

The artifact-deploy page keeps a quote inside a parenthesised URL
escaped as &quot; in the link's href, so it cannot end the attribute.

Both outputs are pinned now, so a later change to either fails a test.
unstablebrainiac added a commit to unstablebrainiac/KiroCrew that referenced this pull request Oct 2, 2026
Two outputs of the parenthesised-URL sweep (kirodotdev#15714) had no test.

A link whose destination holds an unbalanced "(" is not a link, so the
voice reply leaves its text as written. A web address in it is still
replaced by "(link)", but a relative destination is spoken as written.

The artifact-deploy page keeps a quote inside a parenthesised URL
escaped as &quot; in the link's href, so it cannot end the attribute.

Both outputs are pinned now, so a later change to either fails a test.
unstablebrainiac added a commit to unstablebrainiac/KiroCrew that referenced this pull request Oct 2, 2026
Two outputs of the parenthesised-URL sweep (kirodotdev#15714) had no test.

A link whose destination holds an unbalanced "(" is not a link, so the
voice reply leaves its text as written. A web address in it is still
replaced by "(link)", but a relative destination is spoken as written.

The artifact-deploy page keeps a quote inside a parenthesised URL
escaped as &quot; in the link's href, so it cannot end the attribute.

Both outputs are pinned now, so a later change to either fails a test.
bolichen97 pushed a commit that referenced this pull request Oct 2, 2026
…15951)

Two outputs of the parenthesised-URL sweep (#15714) had no test.

A link whose destination holds an unbalanced "(" is not a link, so the
voice reply leaves its text as written. A web address in it is still
replaced by "(link)", but a relative destination is spoken as written.

The artifact-deploy page keeps a quote inside a parenthesised URL
escaped as &quot; in the link's href, so it cannot end the attribute.

Both outputs are pinned now, so a later change to either fails a test.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants