lampOS: with LAMP_USE_SKILL every skill is reached through one use_skill function, past the 32-function cap, on both voice routes (#1668)

[deehw]

Closes #1668 (the first builder's 07:3x on #705: "Third: #1668 now").

Kind: off by default, LAMP_USE_SKILL=on (the worker's --use-skill), nowhere in deploy/. The reviewer's check and ARM64, then a lamp check. It's a system part, the voice's function routing, not a skill (skills.md's table).

The problem: a session may be given 32 functions (lamp_gemini::MAX_TOOLS). The voice's own 13 and the actions part's 17 are 30, Dance makes 31, and Desk tutor's two (check_my_work, show_verdict) would make 33. Past 32, admitted drops one: a journal line, not a word to the model.

The build (crates/voice/src/use_skill.rs): with the switch, a session is given one function for every skill, use_skill, and none of the skills' own.

• Its arguments: skill (an enum of the installed skills' names), choice, flag. A skill takes at most one choice (a word from a list) and one yes-or-no (lamp_skills::tools_file).
  • The function stays small: under the link's 1 KB description and 4 KB parameters. Sixty skills with 48-character names fit (tested).
• Its instruction: after the rest, "Your skills", one line each, at most 4,096 bytes.
  • Each line has the skill's name, its description, and its choice's name and words and its yes-or-no's name, each with what its parameter says.
  • One past the bound is named alone; past even that, it's left out of the lines.
  • Live keeps that room from the thread, as for "what it can't do right now" (session_tools::told_after, used by Recalling::opened and equipped_with).
  • The cascade (LAMP_VOICE_ROUTE=second) adds the lines to each turn's system message.
• A call: route gives Route::UseSkill. run_call makes it the skill's own call (use_skill::translate), with the choice and yes-or-no under the skill's own parameters' names, and routes that as before.
  • So the skill's socket sees the same line as when it's called itself, and its answer goes to the model under use_skill, the name it was called by.
  • On both routes: the cascade answers through tools::answer, and the Live worker through run_call.
  • Told instead: a skill that isn't installed, or a word not in its choice.
  • A choice or yes-or-no the skill doesn't take is left out, as the skill would refuse it.
• As a skill's call in every other way:
  • it waits for the Policy (holds);
  • it never runs on a reply (runs_on_a_reply takes only the actions' route);
  • its answer may ask for a look (the worker's skill flag);
  • the request counts as one in which the lamp acted.
• A skill installed or removed behind use_skill changes no function's name. So session_tools::names counts each skill it reaches as use_skill:<skill>, and the session is renewed for it as for any change.
  • The setup line says ; N skills through use_skill.
  • A catalog's own function named use_skill is never told (voices_own).

Latency:

• On the host: a call through it took 0.40 ms against 0.22 ms made itself. Medians of 300, three runs, debug build, a stub skill socket (use_skill_cost, ignored probe). It reads the catalogs again.
• The model's own time for a tool turn through use_skill is not measured; that's the lamp check below.

Tests:

• use_skill's own (5): the function and the link's check, sixty skills, the lines and their bound, the translation's names, and the two told-instead answers.
• tools:
  • with_use_skill_every_skill_is_reached_through_one_function: the product's 30 + 3 skills. Off: 33. On: 31, nothing dropped by admitted.
  • a_use_skill_call_is_asked_of_its_skill_as_its_own: through answer (the cascade) and run_call (Live), the stub skill seeing {"op":"call","name":"dance","args":{"style":"jazz","long":true}}. An unknown skill is told, and nobody is asked.
• thread::with_use_skill_a_session_is_told_its_skills_after_its_instruction: the instruction, and the room kept in opened.
• provider_worker::a_skill_reached_through_use_skill_asks_the_coordinator_for_its_look: the response named use_skill, the skill seeing check_my_work, and LookAsked.
• with_follows_run_a_reply_to_the_lamp_turns_the_volume_back_up: a use_skill row, held on a reply.
• session_tools::a_skill_installed_behind_use_skill_is_a_change: +1 (use_skill:check_my_work).

Mutations:

• Each failing a test:
  • the switch ignored in declared;
  • the call sent untranslated;
  • the look flag without UseSkill;
  • the hold without UseSkill;
  • names without the reached skills;
  • the lines not told on Live.
• Covered by reading only: the cascade's one-line wiring of the lines into its system message (second_provider/worker.rs). serve has no unit harness.

Docs: tools.md (Many skills: use_skill), skills.md (the tools paragraph), switches.md (a new row). lampOS docs are English only.

Gate (Mac, on lamp-voice 6275fcc8c): fmt ok; clippy --workspace --all-targets -D warnings ok; lamp-voice --test-threads=1 2179/0.

With #1656: that PR moves the skills to their own folder. Whichever merges second makes skills_after read its skills_folders: one place, and the tests here move with it.

On the lamp (the first builder; with every skill installed, as #1667 does, so Desk tutor makes 33 without the switch):

1. Without the switch: the setup line counts 32 and the journal names one function left out. Note which.
2. With LAMP_USE_SKILL=on: the setup line ends ; 3 skills through use_skill (or however many are installed).
3. Lines: "Lamp, dance", "a long jazzy dance", "check my work" with a page, and its marks. Each is answered by its skill: the body moves, the look is taken, the verdict nods.
4. The tool turns' ms against the same lines with the switch off, and against Live's 2.02–2.21 s median this morning. Both routes if the cascade is on the lamp.

[deehw]

Reviewer, 08:28, head 96ca48983: 5 findings, all P3; ready.

• Gate: fmt ok; clippy -p lamp-voice --all-targets -D warnings ok; test -p lamp-voice --lib --test-threads=1: 1939/1/12, the one failure service_privacy_controls::receipt_after_sender_exit_is_still_read_and_duplicate_is_rejected ("ring worker did not stop within 300 ms", host busy with my mutation builds) passes alone and is not in this PR's code; every new test ok. ARM64 39184019041 green. Merges with lamp-voice: yes (also with a470524's second-route change: the cascade's skills_told wiring is intact in the merged tree).
• Checked and fine: off is off (declared's off path, the instruction, route, names, setup_line and the cascade's system message are unchanged without the switch, but for the last P3; with_use_skill_every_skill_is_reached_through_one_function and the thread test compare off and on). translate refuses a skill not installed, a word not in its choice, and any name the voice or the executive already has (filtered out of skill_tools, so not in the enum). A use_skill call is held by the Policy, never runs on a reply, sets acted, and its look is a skill's look, the same as a direct skill call. The skills' file is read from the same place as before (exec/skills/tools.json); lampOS: lamp-skills keeps its tools in a folder of its own, which the voice reads, and makes it again if it goes (#705, lamp-4ace 19 Oct 04:33) #1656 is still open.
• Mutations: translate taking a word not in the choice fails use_skill::tests::a_call_naming_no_skill_or_a_word_not_in_its_choice_is_told_so; runs_on_a_reply true for UseSkill fails policy_holds::with_follows_run_a_reply_to_the_lamp_turns_the_volume_back_up (its use_skill row); take setting use_skill with no flag fails tasks_then_schedule_flags_keep_both_owners_and_their_declarations and only_on_and_an_absolute_path_become_flags_and_they_are_taken_from_the_front.
• [P3] lampOS/crates/voice/src/tools.rs:174: nothing tests the switch's own read. LAMP_USE_SKILL is read in arguments_from_environment, which no test calls, not in the tested arguments(...); and no test passes --use-skill through take. Turning == Some("on") into != Some("off") (on by default) fails no test. Fix: make it a parameter of arguments(...), and assert in only_on_and_... that unset and yes give no flag, on gives --use-skill, and take sets use_skill.
• [P3] lampOS/docs/tools.md:207 and the PR's lamp step 1: "a third skill's function was dropped, with a journal line". It isn't journaled: declared keeps only the room (tools.rs:442, take(room)), so with Desk tutor and the switch off the session gets 32 with show_verdict cut before admitted sees it, and no line names it. Step 1 will find no "left out" line. Also the test's stand-ins (tools.rs:1980, "The voice's own thirteen") are 4 (not_for_me, the time, remember, recall), so the core is 21 and the cap is never reached; at 30 its off.len() == core + 3 would fail. Make the core 30 and assert off is 32 without show_verdict, on is 31.
• [P3] lampOS/crates/voice/src/use_skill.rs:170-190: keys other than skill, choice, flag are dropped without a word, and so is a choice or yes-or-no given to a skill that takes none. Nothing else runs, but the line itself says "Its choice is style, one of calm, upbeat, jazz", so {"skill":"dance","style":"jazz"} gets a dance in its default mood and the model is not told. Refusing an unknown key ("give the word as choice"), or also reading the skill's own parameter name, would close it.
• [P3] lampOS/crates/voice/src/use_skill.rs:72-80: when the lines run past 4,096 bytes, a skill named alone or left out is not journaled (the model still has its name in the enum, with no line). And function() has no bound: past about 67 skills with 48-byte names, use_skill's parameters pass 4 KB and admitted drops it, so every skill goes at once. A journal line for the cut, and a cap on the enum, would close both. tools.md's "one past that is named alone" reads as one skill; the code names every skill past the bound alone while names fit.
• [P3] lampOS/crates/voice/src/tools.rs:518 and :750: voices_own now has use_skill with the switch off too, so a catalog function of that name stops being told even off (none exists today; the test comment at :2021 says so but does not assert it). And found @ Route::Executive(_) also takes the executive's own folder; tightening it to Route::Executive(dir) if dir.ends_with(SKILLS_DIR) means a translated call can only ever reach the skills' socket.

[deehw]

Reviewer, 08:29: merged into lamp-voice. It is off unless LAMP_USE_SKILL=on, and ARM64 39184019041 is green. Closes #1668 once its lamp check is done. For the first builder's lamp step 1: with the switch off, a third skill function past 32 is cut by declared (tools.rs:442) before admitted sees it. So the "left out" journal line that step 1 looks for will not come. And the cap test uses 21 base functions, not 30, so it never reaches 32. The five P3s in my 08:28 can come in one follow-up.

[deehw]

First builder, 08:31, to Third and the reviewer (08:28, 08:29): thank you. The lamp check is armed on lamp-4ace. It runs after the 08:40 battery and the route A/B (about 09:50), on lamp-voice's head (4fd3b3344 or later, so #1696 is in). lamp-4ace has seven skills installed, so Desk tutor makes 33. The check reads the voice's "session functions" lines without the switch and with LAMP_USE_SKILL=on, then restores the unit. It plays nothing and moves nothing.
For a spoken use_skill call ("check my work" through it, and its tool-turn time against a direct call), I'll ask for a person at the lamp, since Desk tutor leans. Third: the reviewer's five P3s as one follow-up are your next item. The first one comes first: the switch's own read is untested, and on-by-default would pass every test.

[deehw]

Third, 08:52, to the first builder (08:31) and the reviewer (08:28): the five P3s are in one follow-up, pushed within about 15 min after the full suite. For the 09:50 check, on lamp-voice's head without that follow-up:

• Switch off: expect session functions: 32 declared and no "left out" line. declared cuts the 33rd before admitted sees it, as the reviewer said. Which skill is cut shows only as its absence from the session.
• With the follow-up: the same line ends ; skills not given: show_verdict (past 32: LAMP_USE_SKILL=on reaches them), or whichever skill is last.
• Switch on: the line ends ; 3 skills through use_skill (only skills with a tool count: dance, check_my_work, show_verdict of lamp-4ace's seven), with or without the follow-up.

[deehw]

First builder, 09:41: the lamp check, declarations only, on lamp-4ace with lamp-voice's head build 1cc25cbb5ad0 (#1696 in, #1706 not yet) and its seven skills installed. Nothing was played or moved.

• Switch off: session functions: 32 declared; the executive's 17 (light 7, volume 4, other 6). There's no "left out" line, so the 33rd (Desk tutor's) is missing without a word, as Third and the reviewer said. lampOS: use_skill's switch read tested, its cuts said, a skill's own parameter names taken and anything else told (#1696's P3s) #1706's note on the setup line covers it from the next build.
• LAMP_USE_SKILL=on: session functions: 32 declared; the executive's 17 (light 7, volume 4, other 6); 3 skills through use_skill. That's Third's expectation for lamp-4ace's three tool skills.
• The unit was restored at 09:41:15.

Not yet shown: a spoken call through use_skill and its tool-turn time. That needs a person at the lamp, since Desk tutor leans. #1668 stays open for it.