add asta literature interactive: stateful multi-turn paper-finder via A2A (#52)

Author: Grishezz

plugins/asta-preview/skills/find-literature/SKILL.md

@@ -5,6 +5,7 @@ metadata:
   internal: true
 allowed-tools:
   - Bash(asta literature find *)
+  - Bash(asta literature interactive *)
   - Bash(asta papers *)
   - TaskOutput
   - Bash(jq *)
@@ -17,6 +18,65 @@ Search academic literature for papers relevant to a query. The search will retur
 This is an advanced search, so the query can be long and complex. You may ask the user
 questions to clarify the topic and refine the query before running the search.
 
+## Choosing `find` vs `interactive`
+
+Two entry points are available. Both run the same retrieval pipeline (criteria extraction,
+candidate retrieval, re-ranking). The significant difference is what happens around that
+pipeline — and the right choice is mostly driven by **what the session as a whole is about**,
+not by the complexity of any single query:
+
+- **`asta literature interactive`** — default for literature-focused sessions. Use it when the
+  **first interaction** in the session is about literature search or exploration, or when the
+  **entire session** is focused on literature. It runs the full Asta paper-finder agent: better
+  planning for complex or multi-faceted queries (decomposition, iterative search strategies) and
+  a reasoning / results-verification loop that can re-run or refine the search when the initial
+  results don't satisfy the criteria. It also maintains conversation state via a `thread_id`, so
+  follow-ups can build on prior results: filtering ("now narrow to surveys from 2023+"),
+  aggregating ("group by venue"), following relations ("expand on the third paper's citations"),
+  or iterative refinement.
+
+- **`asta literature find`** — one attempt, no agent loop. Use it primarily when literature
+  search is **a sub-step inside some other multi-step flow** (data analysis, code generation,
+  a broader research workflow, etc.) where the same flow may issue many unrelated searches and
+  the latency of the full agent loop is not worth it for each one. Lower quality, much faster.
+  Don't reach for `find` just because a single query "looks simple" — if the session is
+  literature-centered, prefer `interactive`.
+
+**Continuing a conversation — recommended pattern (`--thread-dir`):** for any
+multi-turn search session, pick a directory named `.asta/literature/threads/<YYYY-MM-DD>-<slug>/`
+(date-prefixed slug, matching the convention used by other agents) and pass it
+on every turn. The CLI auto-resumes the conversation, writes one artifact per
+turn with a `.NNN` index suffix, and maintains a `DIR/index.json` that records
+turn order, queries, narratives, paper counts, and the `thread_id`. Use a
+meaningful `-o` basename per turn — the CLI inserts the turn index for you.
+
+```bash
+# Turn 1 — picks a thread dir; CLI creates DIR/index.json and DIR/transformer-survey.001.json
+asta literature interactive "transformer architecture survey" \
+  --thread-dir .asta/literature/threads/2026-05-04-transformer-architectures \
+  -o transformer-survey.json
+
+# Turn 2 — same dir; thread_id auto-resumes from index.json.
+# Writes DIR/narrow-2023.002.json and appends a turn entry to DIR/index.json.
+asta literature interactive "narrow to 2023+ long-context surveys" \
+  --thread-dir .asta/literature/threads/2026-05-04-transformer-architectures \
+  -o narrow-2023.json
+```
+
+Start a fresh conversation when the topic shifts substantially: pick a new
+`--thread-dir`. Reading the conversation back is straightforward — `jq` over
+`DIR/index.json` for the turn list, then open the per-turn JSON files referenced
+by `turns[].file`.
+
+Without `--thread-dir`, an invocation is a one-shot turn that doesn't continue
+any prior conversation. Use that for ad-hoc single queries; for any multi-turn
+session, always pass `--thread-dir`.
+
+Output deltas vs `find`: the `interactive` JSON adds `thread_id` and `narrative`
+(the agent's terminal response text). It does not currently populate
+`citationContexts` or `publicationDate` per paper; for those, use `find` or the
+`asta papers` commands.
+
 ## Installation
 
 This skill requires the `asta` CLI:

plugins/asta-preview/skills/semantic-scholar/SKILL.md

@@ -20,6 +20,43 @@ allowed-tools:
 
 **Not for comprehensive reports** - use the Literature Report Generation skill for that.
 
+## Related: Find Literature skill
+
+`asta papers ...` (this skill) is for **mechanical, targeted lookups** against the Semantic
+Scholar API: fetch a known paper, list citations, search by keyword across titles / abstracts /
+bodies, look up an author. There is no agent-mediated reasoning beyond S2's own keyword ranking.
+
+The **Find Literature skill** (`asta literature find` / `asta literature interactive`) is for
+**topic-driven, criterion-based search**, where the system extracts relevance criteria from the
+query, retrieves candidates, and ranks them against those criteria with per-paper relevance
+summaries — closer to "literature search as a graded judgement" than to a keyword match.
+
+Use **this** skill (`asta papers`) when:
+
+- The user names a specific paper, author, ID, or exact phrase to look up
+- You need raw metadata (citations, venue, fields of study, openAccessInfo)
+- You're navigating a citation graph (who cites what, who an author has cited)
+- You want to grep for a specific string in paper bodies (`snippet-search`)
+- You need a fast result and exhaustive coverage isn't required
+
+Use the **Find Literature** skill instead when:
+
+- The user asks "find papers on X", "what does the literature say about Y", "papers that argue Z"
+- The query is a research topic, not a string match — and ranked relevance with explanations matters
+- The work session is exploratory: filtering prior results, aggregating, following relations across
+  multiple turns (use `asta literature interactive --thread-dir <dir>`)
+- A `find`-style one-shot or `interactive`-style multi-turn agent loop with verification will
+  produce a better-ranked result than raw keyword search
+
+The two are complementary. A common flow: use Find Literature to discover relevant papers on a
+topic, then `asta papers get` / `asta papers citations` to drill into specific ones.
+
+**Session-level rule of thumb:** if the session as a whole is about literature
+search/exploration (e.g. the first user turn is "find papers on X"), default to
+`asta literature interactive` for the discovery work, even when individual queries look simple.
+Reach for `asta papers` when the session is about something else and a quick metadata or
+citation lookup is just one step inside it.
+
 ## Installation
 
 This skill requires the `asta` CLI:

plugins/asta/skills/semantic-scholar/SKILL.md

@@ -20,6 +20,43 @@ allowed-tools:
 
 **Not for comprehensive reports** - use the Literature Report Generation skill for that.
 
+## Related: Find Literature skill
+
+`asta papers ...` (this skill) is for **mechanical, targeted lookups** against the Semantic
+Scholar API: fetch a known paper, list citations, search by keyword across titles / abstracts /
+bodies, look up an author. There is no agent-mediated reasoning beyond S2's own keyword ranking.
+
+The **Find Literature skill** (`asta literature find` / `asta literature interactive`) is for
+**topic-driven, criterion-based search**, where the system extracts relevance criteria from the
+query, retrieves candidates, and ranks them against those criteria with per-paper relevance
+summaries — closer to "literature search as a graded judgement" than to a keyword match.
+
+Use **this** skill (`asta papers`) when:
+
+- The user names a specific paper, author, ID, or exact phrase to look up
+- You need raw metadata (citations, venue, fields of study, openAccessInfo)
+- You're navigating a citation graph (who cites what, who an author has cited)
+- You want to grep for a specific string in paper bodies (`snippet-search`)
+- You need a fast result and exhaustive coverage isn't required
+
+Use the **Find Literature** skill instead when:
+
+- The user asks "find papers on X", "what does the literature say about Y", "papers that argue Z"
+- The query is a research topic, not a string match — and ranked relevance with explanations matters
+- The work session is exploratory: filtering prior results, aggregating, following relations across
+  multiple turns (use `asta literature interactive --thread-dir <dir>`)
+- A `find`-style one-shot or `interactive`-style multi-turn agent loop with verification will
+  produce a better-ranked result than raw keyword search
+
+The two are complementary. A common flow: use Find Literature to discover relevant papers on a
+topic, then `asta papers get` / `asta papers citations` to drill into specific ones.
+
+**Session-level rule of thumb:** if the session as a whole is about literature
+search/exploration (e.g. the first user turn is "find papers on X"), default to
+`asta literature interactive` for the discovery work, even when individual queries look simple.
+Reach for `asta papers` when the session is about something else and a quick metadata or
+citation lookup is just one step inside it.
+
 ## Installation
 
 This skill requires the `asta` CLI:

skills/find-literature/SKILL.md

@@ -5,6 +5,7 @@ metadata:
   internal: true
 allowed-tools:
   - Bash(asta literature find *)
+  - Bash(asta literature interactive *)
   - Bash(asta papers *)
   - TaskOutput
   - Bash(jq *)
@@ -17,6 +18,65 @@ Search academic literature for papers relevant to a query. The search will retur
 This is an advanced search, so the query can be long and complex. You may ask the user
 questions to clarify the topic and refine the query before running the search.
 
+## Choosing `find` vs `interactive`
+
+Two entry points are available. Both run the same retrieval pipeline (criteria extraction,
+candidate retrieval, re-ranking). The significant difference is what happens around that
+pipeline — and the right choice is mostly driven by **what the session as a whole is about**,
+not by the complexity of any single query:
+
+- **`asta literature interactive`** — default for literature-focused sessions. Use it when the
+  **first interaction** in the session is about literature search or exploration, or when the
+  **entire session** is focused on literature. It runs the full Asta paper-finder agent: better
+  planning for complex or multi-faceted queries (decomposition, iterative search strategies) and
+  a reasoning / results-verification loop that can re-run or refine the search when the initial
+  results don't satisfy the criteria. It also maintains conversation state via a `thread_id`, so
+  follow-ups can build on prior results: filtering ("now narrow to surveys from 2023+"),
+  aggregating ("group by venue"), following relations ("expand on the third paper's citations"),
+  or iterative refinement.
+
+- **`asta literature find`** — one attempt, no agent loop. Use it primarily when literature
+  search is **a sub-step inside some other multi-step flow** (data analysis, code generation,
+  a broader research workflow, etc.) where the same flow may issue many unrelated searches and
+  the latency of the full agent loop is not worth it for each one. Lower quality, much faster.
+  Don't reach for `find` just because a single query "looks simple" — if the session is
+  literature-centered, prefer `interactive`.
+
+**Continuing a conversation — recommended pattern (`--thread-dir`):** for any
+multi-turn search session, pick a directory named `.asta/literature/threads/<YYYY-MM-DD>-<slug>/`
+(date-prefixed slug, matching the convention used by other agents) and pass it
+on every turn. The CLI auto-resumes the conversation, writes one artifact per
+turn with a `.NNN` index suffix, and maintains a `DIR/index.json` that records
+turn order, queries, narratives, paper counts, and the `thread_id`. Use a
+meaningful `-o` basename per turn — the CLI inserts the turn index for you.
+
+```bash
+# Turn 1 — picks a thread dir; CLI creates DIR/index.json and DIR/transformer-survey.001.json
+asta literature interactive "transformer architecture survey" \
+  --thread-dir .asta/literature/threads/2026-05-04-transformer-architectures \
+  -o transformer-survey.json
+
+# Turn 2 — same dir; thread_id auto-resumes from index.json.
+# Writes DIR/narrow-2023.002.json and appends a turn entry to DIR/index.json.
+asta literature interactive "narrow to 2023+ long-context surveys" \
+  --thread-dir .asta/literature/threads/2026-05-04-transformer-architectures \
+  -o narrow-2023.json
+```
+
+Start a fresh conversation when the topic shifts substantially: pick a new
+`--thread-dir`. Reading the conversation back is straightforward — `jq` over
+`DIR/index.json` for the turn list, then open the per-turn JSON files referenced
+by `turns[].file`.
+
+Without `--thread-dir`, an invocation is a one-shot turn that doesn't continue
+any prior conversation. Use that for ad-hoc single queries; for any multi-turn
+session, always pass `--thread-dir`.
+
+Output deltas vs `find`: the `interactive` JSON adds `thread_id` and `narrative`
+(the agent's terminal response text). It does not currently populate
+`citationContexts` or `publicationDate` per paper; for those, use `find` or the
+`asta papers` commands.
+
 ## Installation
 
 This skill requires the `asta` CLI:

skills/semantic-scholar/SKILL.md

@@ -20,6 +20,43 @@ allowed-tools:
 
 **Not for comprehensive reports** - use the Literature Report Generation skill for that.
 
+## Related: Find Literature skill
+
+`asta papers ...` (this skill) is for **mechanical, targeted lookups** against the Semantic
+Scholar API: fetch a known paper, list citations, search by keyword across titles / abstracts /
+bodies, look up an author. There is no agent-mediated reasoning beyond S2's own keyword ranking.
+
+The **Find Literature skill** (`asta literature find` / `asta literature interactive`) is for
+**topic-driven, criterion-based search**, where the system extracts relevance criteria from the
+query, retrieves candidates, and ranks them against those criteria with per-paper relevance
+summaries — closer to "literature search as a graded judgement" than to a keyword match.
+
+Use **this** skill (`asta papers`) when:
+
+- The user names a specific paper, author, ID, or exact phrase to look up
+- You need raw metadata (citations, venue, fields of study, openAccessInfo)
+- You're navigating a citation graph (who cites what, who an author has cited)
+- You want to grep for a specific string in paper bodies (`snippet-search`)
+- You need a fast result and exhaustive coverage isn't required
+
+Use the **Find Literature** skill instead when:
+
+- The user asks "find papers on X", "what does the literature say about Y", "papers that argue Z"
+- The query is a research topic, not a string match — and ranked relevance with explanations matters
+- The work session is exploratory: filtering prior results, aggregating, following relations across
+  multiple turns (use `asta literature interactive --thread-dir <dir>`)
+- A `find`-style one-shot or `interactive`-style multi-turn agent loop with verification will
+  produce a better-ranked result than raw keyword search
+
+The two are complementary. A common flow: use Find Literature to discover relevant papers on a
+topic, then `asta papers get` / `asta papers citations` to drill into specific ones.
+
+**Session-level rule of thumb:** if the session as a whole is about literature
+search/exploration (e.g. the first user turn is "find papers on X"), default to
+`asta literature interactive` for the discovery work, even when individual queries look simple.
+Reach for `asta papers` when the session is about something else and a quick metadata or
+citation lookup is just one step inside it.
+
 ## Installation
 
 This skill requires the `asta` CLI:

src/asta/cli.py

@@ -10,6 +10,7 @@
 from asta.documents import documents
 from asta.experiment import experiment
 from asta.literature.find import find
+from asta.literature.interactive import interactive
 from asta.papers.author import author
 from asta.papers.citations import citations
 from asta.papers.get import get
@@ -61,6 +62,7 @@ def papers():
 
 # Register literature subcommands
 literature.add_command(find)
+literature.add_command(interactive)
 
 # Register papers subcommands
 papers.add_command(get)