@yahyahammad/venastine 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
@@ -0,0 +1,63 @@
1
+ ---
2
+ name: cybersecurity-research
3
+ description: Conventions for researching vulnerabilities, exploits and defensive posture
4
+ additional_tools: [web_search, fetch_url, arxiv_search]
5
+ ---
6
+
7
+ ## Cybersecurity research methodology
8
+
9
+ ### Establish the authorization context first
10
+
11
+ Before analysing any specific system, state what kind of work this is:
12
+ defensive analysis, an authorized assessment, CTF, or study of published
13
+ research. If the request implies acting against a system the user has not
14
+ established authorization for, say so in one sentence and continue with
15
+ the defensive or educational framing rather than refusing outright.
16
+
17
+ ### Name versions, not products
18
+
19
+ "Log4j is vulnerable" is not a finding. A finding names the affected
20
+ versions, the fixed version, and the condition required to reach the
21
+ vulnerable code path. A claim that omits the version range is unverified
22
+ by construction — treat it as a lead, not a result.
23
+
24
+ ### Prefer primary sources, in this order
25
+
26
+ 1. The vendor advisory or the maintainer's own commit and release notes.
27
+ 2. The CVE record, and the NVD entry for the CVSS vector.
28
+ 3. The original researcher's write-up.
29
+ 4. Aggregators and news coverage — useful for discovering that something
30
+ exists, never sufficient for asserting what it does.
31
+
32
+ When two sources disagree about a version range or a severity, report the
33
+ disagreement rather than picking. Disagreement between an advisory and NVD
34
+ is common and is itself a finding.
35
+
36
+ ### Separate what is proven from what is plausible
37
+
38
+ Three distinct claims that get conflated constantly:
39
+
40
+ - **Exploitable** — a working technique exists and its preconditions are
41
+ documented.
42
+ - **Vulnerable** — the flawed code is present and reachable.
43
+ - **Affected** — the component is present somewhere in the dependency
44
+ tree, possibly on a path nothing calls.
45
+
46
+ State which one you mean. Escalating "affected" to "exploitable" in a
47
+ summary line is the most common failure in this domain.
48
+
49
+ ### Score honestly
50
+
51
+ If you cite a CVSS score, cite the vector string with it, and say whose
52
+ score it is — vendor and NVD scores for the same CVE routinely differ.
53
+ Environmental factors (is it internet-facing, is authentication required
54
+ in this deployment) usually matter more than the base score, and you
55
+ generally do not know them; say so instead of implying the base score is
56
+ the risk.
57
+
58
+ ### Writing up
59
+
60
+ Lead with what an operator should do, then the evidence for it. Include
61
+ the "how do I know I am affected" check — a version query, a config
62
+ inspection, a log signature — because a report that cannot be acted on is
63
+ a summary of someone else's work.
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: code-review
3
+ description: Reading a change for defects rather than for style, and reporting each one with the failure it produces
4
+ additional_tools: [read, shell, read_project_doc]
5
+ ---
6
+
7
+ ## Code review methodology
8
+
9
+ ### Establish what the change claims before reading it
10
+
11
+ A diff on its own can only be read as itself. Read the commit message, the
12
+ issue or the docstring first, then read the change as an answer to that
13
+ claim. The most common real defect is a disagreement between the two — the
14
+ message says one thing was fixed, the diff does that and one other thing
15
+ nobody mentioned — and it is invisible to a reader who starts at line one
16
+ of the diff.
17
+
18
+ ### Read the call graph, not the changed lines
19
+
20
+ A diff shows what moved. It does not show the caller three files away that
21
+ passes the argument the new code no longer tolerates, the subclass that
22
+ overrides the method whose contract just changed, or the second call site
23
+ of the helper that was fixed in one place. Find the callers before you
24
+ approve the change.
25
+
26
+ ### A finding needs a failure, not a preference
27
+
28
+ For each item, name the input, state or sequence that produces the wrong
29
+ result. If you cannot construct one, say so and label the item a concern
30
+ rather than a defect. Both are worth reporting; reporting them in the same
31
+ voice makes the serious ones unfindable.
32
+
33
+ Rank by consequence: wrong answers first, then silently wrong answers
34
+ (worse than a crash, because nothing reports them), then security and data
35
+ loss, then anything that makes the next change harder. Style last, if at
36
+ all.
37
+
38
+ ### Look hardest at what is absent
39
+
40
+ Most surviving defects are omissions rather than errors:
41
+
42
+ - The error path nobody wrote, or one that swallows the cause.
43
+ - The caller that was not updated.
44
+ - The invariant that used to hold and now holds only by accident.
45
+ - The case the new tests cannot distinguish from the old behaviour.
46
+
47
+ Ask what would have to be added for the change to be complete, not only
48
+ whether what is present is correct.
49
+
50
+ ### Judge the tests by whether they could fail
51
+
52
+ A test that passes against the unfixed code is not testing the fix. When a
53
+ change ships with tests, check at least one against the behaviour it
54
+ claims to pin: would it go red if the fix were reverted? If the answer is
55
+ no, that is a finding about the test, and it is often the most valuable
56
+ thing in the review.
57
+
58
+ ### Say when it is fine
59
+
60
+ If the change is sound, say so and stop. Manufacturing findings to justify
61
+ the time spent teaches the author to skim your reviews.
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: debugging
3
+ description: Locating a defect by narrowing rather than guessing, and fixing it where the wrong value is produced
4
+ additional_tools: [read, shell]
5
+ ---
6
+
7
+ ## Debugging methodology
8
+
9
+ ### Reproduce it before theorising about it
10
+
11
+ A defect you cannot reproduce is one you cannot confirm you fixed. Get to
12
+ a command, an input or a sequence that fails reliably, and write it down.
13
+ If it fails intermittently, say how often — one in two and one in a
14
+ thousand are different problems with different causes.
15
+
16
+ Where reproduction is genuinely impossible, say so explicitly and treat
17
+ everything downstream as a hypothesis, the fix included.
18
+
19
+ ### Shrink the case until nothing can be removed
20
+
21
+ Cut the input, the configuration and the code path until removing anything
22
+ else makes the failure disappear. What remains is usually close to the
23
+ cause, and it is what makes a regression test that discriminates. Most of
24
+ the value of debugging comes from this step, and most of the time is spent
25
+ avoiding it.
26
+
27
+ ### Read the whole error
28
+
29
+ The first line of a traceback names the symptom; the cause is usually
30
+ further down, or in the frame above. An exception arriving three layers
31
+ from where it was created has already told you something about the
32
+ boundary it crossed. Do not start editing until you can say which line
33
+ produced the wrong value, as opposed to which line noticed it.
34
+
35
+ ### Bisect in whichever dimension is cheapest
36
+
37
+ Time (which commit), space (which module), input (which field), or
38
+ configuration (which setting). Each halving is worth more than an hour of
39
+ staring, and `git bisect` is only the most familiar instance of the move.
40
+
41
+ ### Confirm the mechanism; correlation is not a diagnosis
42
+
43
+ "It works when I change this" does not identify a cause. Before fixing, be
44
+ able to say why the broken version produced the wrong result, in a
45
+ sentence with a subject and a verb. Without one you cannot tell a fix from
46
+ a coincidence that reorders something, and the defect returns later under
47
+ a different symptom.
48
+
49
+ ### Fix at the producer
50
+
51
+ Correct the place that creates the bad value, not each place that copes
52
+ with it. A guard at the consumer leaves the wrong value in the system,
53
+ moves the failure somewhere less obvious, and has to be repeated at every
54
+ future consumer. When you deliberately fix at the consumer instead —
55
+ because the producer is out of reach — say that you did, and why.
56
+
57
+ ### Leave the test behind, and check that it discriminates
58
+
59
+ The regression test should fail against the code as it was. Verify that
60
+ rather than assuming it: a test written after the fix, from the fixed
61
+ code, frequently passes both ways and pins nothing.
@@ -0,0 +1,67 @@
1
+ ---
2
+ name: test-design
3
+ description: Writing tests that can actually fail — choosing what to pin, and checking that the assertion discriminates
4
+ additional_tools: [read, shell]
5
+ ---
6
+
7
+ ## Test design methodology
8
+
9
+ ### A test's value is entirely in what makes it fail
10
+
11
+ Before writing an assertion, name the change to the production code that
12
+ this test would catch. If you cannot name one, the test is decoration: it
13
+ adds runtime, it adds the appearance of coverage, and it will later be
14
+ cited as evidence that the behaviour is protected.
15
+
16
+ The cheapest check is to break the code on purpose — revert the fix,
17
+ invert the condition, delete the line — and confirm the test goes red. Do
18
+ this once for every non-obvious test. It finds more than rereading does.
19
+
20
+ ### Watch for the assertion that cannot discriminate
21
+
22
+ An assertion is vacuous when the environment guarantees it regardless of
23
+ the code. Sorting is the classic case: if the input already arrives in
24
+ sorted order, a test of the sort cannot tell it from a no-op. Construct
25
+ inputs that would come back wrong if the behaviour were absent —
26
+ reversed, out of range, colliding, duplicated.
27
+
28
+ Watch equally for a check whose passing condition is "found nothing".
29
+ Such a test cannot detect that it looked in fewer places, so pin the
30
+ domain in both directions: something that must be seen, and something
31
+ that must not.
32
+
33
+ ### Test the boundary, not the middle
34
+
35
+ Off by one, empty, exactly one, exactly the limit, one over the limit, the
36
+ duplicate, the null. The interior of a range is where the code is already
37
+ correct.
38
+
39
+ ### One reason to fail per test
40
+
41
+ When a test asserts five things, its failure names one and you learn
42
+ nothing about the other four. Split by the reason it would go red, not by
43
+ the function it calls.
44
+
45
+ ### Name the test after the behaviour
46
+
47
+ `test_a_rejected_payment_leaves_the_cart_untouched` survives a rename and
48
+ tells a reader what broke. `test_process_payment_2` does neither. The name
49
+ is the first thing anyone reads when the suite goes red at an
50
+ inconvenient moment.
51
+
52
+ ### Assert on the observable, not the implementation
53
+
54
+ Prefer the value a caller sees over the internal call that produced it: a
55
+ test asserting that a helper was called still passes when the helper is
56
+ called and its result thrown away. There is a real exception — sometimes
57
+ the arguments a decision was made with are exactly what needs pinning,
58
+ because an outcome check would pass for an implementation that read the
59
+ wrong field and happened to agree — but take it deliberately and say so in
60
+ the docstring.
61
+
62
+ ### Hold the environment still
63
+
64
+ A test whose result depends on filesystem ordering, wall-clock time,
65
+ locale, network reachability, or which test ran before it is a source of
66
+ noise that eventually gets labelled flaky and ignored. Inject the clock,
67
+ pin the ordering, isolate the state.
@@ -0,0 +1,138 @@
1
+ """
2
+ skills/manager.py
3
+
4
+ ROADMAP_v2 §19. SkillManager exposes lookup over the loader's discovered
5
+ skills plus the activation semantics §19 owns.
6
+
7
+ Thin for the same reason agents/manager.py is thin: discovery, frontmatter
8
+ parsing, category derivation and tier precedence all live in
9
+ core/config_loader.py and run at initialize() time. This file adds only:
10
+
11
+ * activate() / deactivate() -- the §19 D7 slash-command semantics.
12
+ * missing_tools() -- K2's precondition check.
13
+ * prompt_fragment() -- K1's pinned bodies, assembled in ONE place.
14
+
15
+ HOLDS NO STATE (K3). Every function takes the active list and returns a
16
+ new one; the shell owns it, exactly as tui/app.py owns `active_agent`.
17
+ §25 demonstrated what "TUI-only" costs when a capability turns out to be
18
+ needed elsewhere -- a manager holding session state is precisely what
19
+ would make wiring a second shell a redesign rather than a call site.
20
+
21
+ WHAT ACTIVATION IS FOR (K1). load_skill already returns any skill's body
22
+ on request, so activation cannot be about *reading* one. It pins the body
23
+ into every subsequent turn's system prompt: a tool result is a single
24
+ message that scrolls away and is subject to §21 compaction, while an
25
+ activated skill governs the session.
26
+ """
27
+
28
+ from typing import Optional
29
+
30
+ from core import config_loader
31
+ from core.config_loader import SkillDef
32
+
33
+
34
+ class SkillManager:
35
+ """Lookup + activation semantics over the loader's discovered skills."""
36
+
37
+ def get(self, name: str) -> Optional[SkillDef]:
38
+ return config_loader.get_skill(name)
39
+
40
+ def names(self) -> list:
41
+ return sorted(config_loader.get_skills())
42
+
43
+ def all(self) -> dict:
44
+ return config_loader.get_skills()
45
+
46
+ def by_category(self) -> dict:
47
+ """{category: [SkillDef, ...]} with names sorted inside each.
48
+
49
+ Same grouping the catalog uses, so `/skill`'s listing and the
50
+ system prompt's catalog cannot present different structures for
51
+ the same set of files.
52
+ """
53
+ # One snapshot: get_skills() builds a fresh copy per call, so the
54
+ # old N+1 pattern copied the dict once per skill and read two
55
+ # independent snapshots where the intent is one (review f23).
56
+ skills = config_loader.get_skills()
57
+ out: dict = {}
58
+ for name in sorted(skills):
59
+ out.setdefault(skills[name].category, []).append(skills[name])
60
+ return out
61
+
62
+ @staticmethod
63
+ def missing_tools(skill: SkillDef, context=None) -> list:
64
+ """Tools this skill declares that the current context cannot
65
+ provide (K2).
66
+
67
+ `additional_tools` is a DECLARATION OF NEED, not a grant, and it
68
+ cannot be anything else. ToolContext.allowed_tools is a whitelist
69
+ that NARROWS -- None means "no opinion", a set restricts to that
70
+ set -- so there is no configuration in which this field widens
71
+ anything: with no active agent everything globally allowed is
72
+ already available, with one §19 AC1 forbids widening, and a
73
+ globally disabled tool is unreachable by D14 unconditionally.
74
+
75
+ Checked through registry.is_allowed so the answer comes from the
76
+ same policy function that would refuse the call later. Reporting
77
+ one thing at activation and enforcing another mid-turn is the
78
+ divergence this routes around.
79
+
80
+ Registration is checked too (review §19-20 f12): policy alone says
81
+ "allowed" for an mcp__ name whose server was never connected, and
82
+ the activation note would then silently miss exactly the tools
83
+ that will fail mid-turn.
84
+ """
85
+ from tools.registry import registry
86
+
87
+ return [
88
+ name for name in (skill.additional_tools or [])
89
+ if not registry.is_allowed(name, context)
90
+ or not registry.is_registered(name)
91
+ ]
92
+
93
+ @staticmethod
94
+ def activate(name: str, active: list) -> list:
95
+ """Return `active` with `name` appended, or unchanged if already
96
+ present. Activation ORDER is preserved rather than sorted: it is
97
+ the order the bodies are pinned in, and a user activating a
98
+ general skill then a specific one is expressing a precedence the
99
+ prompt should reflect.
100
+
101
+ Does NOT validate that the skill exists -- the caller has already
102
+ looked it up to report a good error, and re-deriving that here
103
+ would mean two places deciding what an unknown skill is.
104
+ """
105
+ if name in active:
106
+ return list(active)
107
+ return [*active, name]
108
+
109
+ @staticmethod
110
+ def deactivate(name: str, active: list) -> list:
111
+ return [n for n in active if n != name]
112
+
113
+ def prompt_fragment(self, active: list) -> str:
114
+ """The `## Active skill:` blocks for the current session, or "".
115
+
116
+ ONE assembly point, mirroring core.loop.with_goal, so every shell
117
+ that ever pins a skill produces the same text.
118
+
119
+ MUST be appended OUTSIDE prompts.system_prompts.with_catalogs()
120
+ (K6). That function feeds pass_prompt(), so pinning inside it
121
+ would inject skill bodies into all ten research passes -- a shell
122
+ the user activated nothing from.
123
+
124
+ A name with no matching skill is skipped silently: skills are
125
+ rediscovered on initialize(), so an active name can legitimately
126
+ stop resolving mid-session (a project's trust was revoked, a file
127
+ was deleted), and that is not worth failing a turn over.
128
+ """
129
+ blocks = []
130
+ for name in active or ():
131
+ skill = self.get(name)
132
+ if skill is None:
133
+ continue
134
+ blocks.append(f"## Active skill: {skill.name}\n\n{skill.body}")
135
+ return "\n\n".join(blocks)
136
+
137
+
138
+ manager = SkillManager()
@@ -0,0 +1,111 @@
1
+ """
2
+ skills/tui_commands.py
3
+
4
+ ROADMAP_v2 §19, D7: `/skill` registers into §16's slash registry. The
5
+ shell hosts the command; this section owns it -- the same
6
+ mechanism-vs-policy split tools/registry.py uses for tools and
7
+ agents/tui_commands.py uses for /agent.
8
+
9
+ Handlers receive the app object from tui.commands.dispatch(); this module
10
+ deliberately does NOT import tui.app, so app.py can import it without a
11
+ cycle.
12
+
13
+ The app owns `active_skills` (K5: session-scoped, unpersisted, matching
14
+ /agent rather than /goal). This module reads and replaces it through the
15
+ manager, which holds no state of its own (K3).
16
+ """
17
+
18
+ from agents.manager import manager as agents
19
+ from skills.manager import manager as skills
20
+ from tui.commands import SlashCommand, registry as commands
21
+
22
+
23
+ def _current_context(app):
24
+ """The ToolContext the NEXT turn will actually run under.
25
+
26
+ The precondition check has to use the same context the loop will, or
27
+ /skill reports one thing and the turn enforces another -- which is the
28
+ divergence the check exists to prevent in the first place.
29
+ """
30
+ if app.active_agent is None:
31
+ return None
32
+ return agents.active_context(app.active_agent)
33
+
34
+
35
+ def _list(app) -> None:
36
+ grouped = skills.by_category()
37
+ if not grouped:
38
+ app._transcript.write_system("No skills discovered.")
39
+ return
40
+ lines = []
41
+ for category in sorted(grouped):
42
+ if category:
43
+ lines.append(f" [{category}]")
44
+ for skill in grouped[category]:
45
+ mark = "*" if skill.name in app.active_skills else "-"
46
+ lines.append(f" {mark} {skill.name}: {skill.description}")
47
+ active = ", ".join(app.active_skills) or "none"
48
+ app._transcript.write_system(
49
+ "Skills (* = active):\n" + "\n".join(lines)
50
+ + f"\nActive: {active}."
51
+ + "\n/skill <name> to activate, /skill off <name>, /skill clear."
52
+ )
53
+
54
+
55
+ def _cmd_skill(app, args: str) -> None:
56
+ """Activate a skill for this session: its full body is pinned into
57
+ every subsequent turn's system prompt until deactivated (K1)."""
58
+ args = (args or "").strip()
59
+ if not args:
60
+ _list(app)
61
+ return
62
+
63
+ if args == "clear":
64
+ app.active_skills = []
65
+ app._transcript.write_system("All skills deactivated.")
66
+ return
67
+
68
+ if args.startswith("off "):
69
+ name = args[4:].strip()
70
+ if name not in app.active_skills:
71
+ app._transcript.write_error(f"{name!r} is not active.")
72
+ return
73
+ app.active_skills = skills.deactivate(name, app.active_skills)
74
+ app._transcript.write_system(f"Deactivated {name}.")
75
+ return
76
+
77
+ skill = skills.get(args)
78
+ if skill is None:
79
+ app._transcript.write_error(
80
+ f"Unknown skill {args!r}. "
81
+ f"Available: {', '.join(skills.names()) or 'none'}.")
82
+ return
83
+
84
+ already = args in app.active_skills
85
+ app.active_skills = skills.activate(args, app.active_skills)
86
+ if already:
87
+ app._transcript.write_system(f"{skill.name} is already active.")
88
+ return
89
+
90
+ app._transcript.write_system(
91
+ f"Activated {skill.name} — {skill.description}. "
92
+ "Its full instructions now apply to every turn until /skill off.")
93
+
94
+ # K2: report, do not refuse. A skill is often useful without an
95
+ # optional tool, and a hard failure here would make a restrictive agent
96
+ # silently un-pairable with half the catalog. Saying it now beats the
97
+ # model discovering it mid-turn as a denied call.
98
+ missing = skills.missing_tools(skill, _current_context(app))
99
+ if missing:
100
+ app._transcript.write_system(
101
+ f"Note: {skill.name} expects {', '.join(missing)}, which "
102
+ f"{'is' if len(missing) == 1 else 'are'} not available in this "
103
+ "session. The skill is active; those steps will not be.")
104
+
105
+
106
+ def register_skill_commands() -> None:
107
+ """Idempotent -- registering by name overwrites, matching §16's
108
+ register_builtin_commands() and §18's register_agent_commands()."""
109
+ commands.register(SlashCommand(
110
+ "skill", "activate a skill for this session", _cmd_skill,
111
+ "[name|off <name>|clear]"))