🛟 Updated.
75d424d parent: e0a76e0 modified
INSTALL.MACOS.md +1 -1 | @@ -6,7 +6,7 @@ VERSION=0.0.0 | ||
| 6 | 6 | curl -fsSLO "https://rickub.com/bots-garden/sidekick/releases/download/v${VERSION}/sidekick-${VERSION}-darwin-arm64" |
| 7 | 7 | chmod +x ./sidekick-${VERSION}-darwin-arm64 |
| 8 | 8 | xattr -cr ./sidekick-${VERSION}-darwin-arm64 |
| 9 | -sudo rm /usr/local/bin/sidekick | |
| 9 | +sudo rm -f /usr/local/bin/sidekick | |
| 10 | 10 | sudo cp ./sidekick-${VERSION}-darwin-arm64 /usr/local/bin/sidekick |
| 11 | 11 | ``` |
| 12 | 12 | |
| @@ -6,7 +6,7 @@ VERSION=0.0.0 | |||
| 6 | curl -fsSLO "https://rickub.com/bots-garden/sidekick/releases/download/v${VERSION}/sidekick-${VERSION}-darwin-arm64" | 6 | curl -fsSLO "https://rickub.com/bots-garden/sidekick/releases/download/v${VERSION}/sidekick-${VERSION}-darwin-arm64" |
| 7 | chmod +x ./sidekick-${VERSION}-darwin-arm64 | 7 | chmod +x ./sidekick-${VERSION}-darwin-arm64 |
| 8 | xattr -cr ./sidekick-${VERSION}-darwin-arm64 | 8 | xattr -cr ./sidekick-${VERSION}-darwin-arm64 |
| 9 | -sudo rm /usr/local/bin/sidekick | 9 | +sudo rm -f /usr/local/bin/sidekick |
| 10 | sudo cp ./sidekick-${VERSION}-darwin-arm64 /usr/local/bin/sidekick | 10 | sudo cp ./sidekick-${VERSION}-darwin-arm64 /usr/local/bin/sidekick |
| 11 | ``` | 11 | ``` |
| 12 | 12 | ||
added
demo/.mm/sessions/20260928-062527-2947e766.json +34 -0 | new file mode 100644 | ||
| @@ -0,0 +1,34 @@ | ||
| 1 | +{ | |
| 2 | + "id": "20260928-062527-2947e766", | |
| 3 | + "cwd": "/Users/k33g/kDrive/Rickub/bots-garden/sidekick/demo", | |
| 4 | + "provider": "dmr", | |
| 5 | + "model": "huggingface.co/unsloth/gemma-4-e4b-it-gguf:Q4_K_M", | |
| 6 | + "createdAt": "2026-09-28T06:25:27.511683604Z", | |
| 7 | + "updatedAt": "2026-09-28T06:25:27.512342062Z", | |
| 8 | + "messages": [ | |
| 9 | + { | |
| 10 | + "content": [ | |
| 11 | + { | |
| 12 | + "text": "Your name is Bob.\nYou are a coding agent working in a terminal.\nYou have a \"bash\" tool to run shell commands.\nUse it to explore files, run tests, inspect the repository, etc.\nChain several commands if needed, then answer clearly in English.\n\nA request often mixes things you answer from yourself (\"say hello\") with\nthings only a command can answer (\"list the files\"). Handle every part, in\nthe order asked, and run a command for each part that needs one.\nNever state the contents of a file, the output of a command, or the state of\nthe repository unless a command in THIS answer returned it. What you did not\nread, you do not know: run the command instead of recalling it.\n\nSKILLS\nYou have a second tool, `read_skill`. Its description lists the procedures\navailable for this project — one per kind of task.\n\nAny request to DO something to a Go project is a skill, not a shell command\nyou invent. Match the request against that list, call `read_skill` FIRST,\nbefore any bash command, and then follow what it says step by step.\n\nFILE EDITING\nYou have three tools for files: `read_file`, `edit_file` and `write_file`.\nThey are how a file gets read and changed here: each change is exact,\nchecked before it is written, and comes back as a diff with line numbers.\nbash is for running things — building, testing, listing, searching.\n\n- Read before you write: call `read_file` on the file (numbered=true when\n you need line numbers). You cannot target text you have not seen; never\n rely on what you think you remember about a file.\n- To change an existing file, call `edit_file` with one or more {old, new}\n pairs. `old` is copied from the file character for character — same\n spaces, same indentation, same line breaks — and appears exactly once:\n add the surrounding lines until it is unique. Several pairs are applied\n together, against the original file. An empty `new` deletes the text.\n- Call `write_file` only to create a file, or to rewrite one entirely and\n on purpose. On an existing file it replaces everything, including what\n you did not intend to touch.\n- Read the diff the tool returns: it says exactly what changed and on which\n line. If `edit_file` refuses — text not found, ambiguous, overlapping\n edits — read the file again and fix `old`. Do not fall back to\n `write_file` to force the change through.\n- After editing code, run the narrowest check with bash: the formatter, the\n compiler, or the test covering that file.\n\nRULES\n- Keep everything the file already does, unless the user asked to remove it.\n- Touch only the files the request is about. Do not add tests, files or\n features that were not asked for.\n- Never run a git command unless the user says git, commit or push.\n- Never move, rename or delete a file unless the user asked for it.\n- Then answer in English, in a few lines.\n- If you don't know how to use a \u003ccli\u003e, run `\u003ccli\u003e --help` (or `\u003ccli\u003e help`)\n to understand the options, then run the command.\n\nBACKGROUND JOBS\nNever let a command block the answer. Anything that serves, watches or runs\nlong goes to the background, with BOTH streams redirected and its pid kept:\n\n nohup \u003ccommand\u003e \u003e /tmp/\u003cjob\u003e.log 2\u003e\u00261 \u0026 echo $! \u003e /tmp/\u003cjob\u003e.pid\n\nRedirecting only stdout still blocks until the process exits. Read the\n`bg-jobs` skill before you wait on, inspect or stop such a job — each has a\nrule you cannot guess. Stop every job you started before you finish, and say\nwhich ones you left running.\n" | |
| 13 | + } | |
| 14 | + ], | |
| 15 | + "role": "system" | |
| 16 | + }, | |
| 17 | + { | |
| 18 | + "content": [ | |
| 19 | + { | |
| 20 | + "text": "hello" | |
| 21 | + } | |
| 22 | + ], | |
| 23 | + "role": "user" | |
| 24 | + }, | |
| 25 | + { | |
| 26 | + "content": [ | |
| 27 | + { | |
| 28 | + "text": "Hello! How can I help you today?" | |
| 29 | + } | |
| 30 | + ], | |
| 31 | + "role": "model" | |
| 32 | + } | |
| 33 | + ] | |
| 34 | +} | |
| \ No newline at end of file | ||
| new file mode 100644 | |||
| @@ -0,0 +1,34 @@ | |||
| 1 | +{ | ||
| 2 | + "id": "20260928-062527-2947e766", | ||
| 3 | + "cwd": "/Users/k33g/kDrive/Rickub/bots-garden/sidekick/demo", | ||
| 4 | + "provider": "dmr", | ||
| 5 | + "model": "huggingface.co/unsloth/gemma-4-e4b-it-gguf:Q4_K_M", | ||
| 6 | + "createdAt": "2026-09-28T06:25:27.511683604Z", | ||
| 7 | + "updatedAt": "2026-09-28T06:25:27.512342062Z", | ||
| 8 | + "messages": [ | ||
| 9 | + { | ||
| 10 | + "content": [ | ||
| 11 | + { | ||
| 12 | + "text": "Your name is Bob.\nYou are a coding agent working in a terminal.\nYou have a \"bash\" tool to run shell commands.\nUse it to explore files, run tests, inspect the repository, etc.\nChain several commands if needed, then answer clearly in English.\n\nA request often mixes things you answer from yourself (\"say hello\") with\nthings only a command can answer (\"list the files\"). Handle every part, in\nthe order asked, and run a command for each part that needs one.\nNever state the contents of a file, the output of a command, or the state of\nthe repository unless a command in THIS answer returned it. What you did not\nread, you do not know: run the command instead of recalling it.\n\nSKILLS\nYou have a second tool, `read_skill`. Its description lists the procedures\navailable for this project — one per kind of task.\n\nAny request to DO something to a Go project is a skill, not a shell command\nyou invent. Match the request against that list, call `read_skill` FIRST,\nbefore any bash command, and then follow what it says step by step.\n\nFILE EDITING\nYou have three tools for files: `read_file`, `edit_file` and `write_file`.\nThey are how a file gets read and changed here: each change is exact,\nchecked before it is written, and comes back as a diff with line numbers.\nbash is for running things — building, testing, listing, searching.\n\n- Read before you write: call `read_file` on the file (numbered=true when\n you need line numbers). You cannot target text you have not seen; never\n rely on what you think you remember about a file.\n- To change an existing file, call `edit_file` with one or more {old, new}\n pairs. `old` is copied from the file character for character — same\n spaces, same indentation, same line breaks — and appears exactly once:\n add the surrounding lines until it is unique. Several pairs are applied\n together, against the original file. An empty `new` deletes the text.\n- Call `write_file` only to create a file, or to rewrite one entirely and\n on purpose. On an existing file it replaces everything, including what\n you did not intend to touch.\n- Read the diff the tool returns: it says exactly what changed and on which\n line. If `edit_file` refuses — text not found, ambiguous, overlapping\n edits — read the file again and fix `old`. Do not fall back to\n `write_file` to force the change through.\n- After editing code, run the narrowest check with bash: the formatter, the\n compiler, or the test covering that file.\n\nRULES\n- Keep everything the file already does, unless the user asked to remove it.\n- Touch only the files the request is about. Do not add tests, files or\n features that were not asked for.\n- Never run a git command unless the user says git, commit or push.\n- Never move, rename or delete a file unless the user asked for it.\n- Then answer in English, in a few lines.\n- If you don't know how to use a \u003ccli\u003e, run `\u003ccli\u003e --help` (or `\u003ccli\u003e help`)\n to understand the options, then run the command.\n\nBACKGROUND JOBS\nNever let a command block the answer. Anything that serves, watches or runs\nlong goes to the background, with BOTH streams redirected and its pid kept:\n\n nohup \u003ccommand\u003e \u003e /tmp/\u003cjob\u003e.log 2\u003e\u00261 \u0026 echo $! \u003e /tmp/\u003cjob\u003e.pid\n\nRedirecting only stdout still blocks until the process exits. Read the\n`bg-jobs` skill before you wait on, inspect or stop such a job — each has a\nrule you cannot guess. Stop every job you started before you finish, and say\nwhich ones you left running.\n" | ||
| 13 | + } | ||
| 14 | + ], | ||
| 15 | + "role": "system" | ||
| 16 | + }, | ||
| 17 | + { | ||
| 18 | + "content": [ | ||
| 19 | + { | ||
| 20 | + "text": "hello" | ||
| 21 | + } | ||
| 22 | + ], | ||
| 23 | + "role": "user" | ||
| 24 | + }, | ||
| 25 | + { | ||
| 26 | + "content": [ | ||
| 27 | + { | ||
| 28 | + "text": "Hello! How can I help you today?" | ||
| 29 | + } | ||
| 30 | + ], | ||
| 31 | + "role": "model" | ||
| 32 | + } | ||
| 33 | + ] | ||
| 34 | +} | ||
| \ No newline at end of file | \ No newline at end of file | ||
added
demo/.mm/sessions/20260928-063109-bda98895.json +86 -0 | new file mode 100644 | ||
| @@ -0,0 +1,86 @@ | ||
| 1 | +{ | |
| 2 | + "id": "20260928-063109-bda98895", | |
| 3 | + "cwd": "/Users/k33g/kDrive/Rickub/bots-garden/sidekick/demo", | |
| 4 | + "provider": "dmr", | |
| 5 | + "model": "huggingface.co/unsloth/gemma-4-e4b-it-gguf:Q4_K_M", | |
| 6 | + "createdAt": "2026-09-28T06:31:09.737982258Z", | |
| 7 | + "updatedAt": "2026-09-28T06:31:09.738143091Z", | |
| 8 | + "messages": [ | |
| 9 | + { | |
| 10 | + "content": [ | |
| 11 | + { | |
| 12 | + "text": "Your name is Bob.\nYou are a coding agent working in a terminal.\nYou have a \"bash\" tool to run shell commands.\nUse it to explore files, run tests, inspect the repository, etc.\nChain several commands if needed, then answer clearly in English.\n\nA request often mixes things you answer from yourself (\"say hello\") with\nthings only a command can answer (\"list the files\"). Handle every part, in\nthe order asked, and run a command for each part that needs one.\nNever state the contents of a file, the output of a command, or the state of\nthe repository unless a command in THIS answer returned it. What you did not\nread, you do not know: run the command instead of recalling it.\n\nSKILLS\nYou have a second tool, `read_skill`. Its description lists the procedures\navailable for this project — one per kind of task.\n\nAny request to DO something to a Go project is a skill, not a shell command\nyou invent. Match the request against that list, call `read_skill` FIRST,\nbefore any bash command, and then follow what it says step by step.\n\nFILE EDITING\nYou have three tools for files: `read_file`, `edit_file` and `write_file`.\nThey are how a file gets read and changed here: each change is exact,\nchecked before it is written, and comes back as a diff with line numbers.\nbash is for running things — building, testing, listing, searching.\n\n- Read before you write: call `read_file` on the file (numbered=true when\n you need line numbers). You cannot target text you have not seen; never\n rely on what you think you remember about a file.\n- To change an existing file, call `edit_file` with one or more {old, new}\n pairs. `old` is copied from the file character for character — same\n spaces, same indentation, same line breaks — and appears exactly once:\n add the surrounding lines until it is unique. Several pairs are applied\n together, against the original file. An empty `new` deletes the text.\n- Call `write_file` only to create a file, or to rewrite one entirely and\n on purpose. On an existing file it replaces everything, including what\n you did not intend to touch.\n- Read the diff the tool returns: it says exactly what changed and on which\n line. If `edit_file` refuses — text not found, ambiguous, overlapping\n edits — read the file again and fix `old`. Do not fall back to\n `write_file` to force the change through.\n- After editing code, run the narrowest check with bash: the formatter, the\n compiler, or the test covering that file.\n\nRULES\n- Keep everything the file already does, unless the user asked to remove it.\n- Touch only the files the request is about. Do not add tests, files or\n features that were not asked for.\n- Never run a git command unless the user says git, commit or push.\n- Never move, rename or delete a file unless the user asked for it.\n- Then answer in English, in a few lines.\n- If you don't know how to use a \u003ccli\u003e, run `\u003ccli\u003e --help` (or `\u003ccli\u003e help`)\n to understand the options, then run the command.\n\nBACKGROUND JOBS\nNever let a command block the answer. Anything that serves, watches or runs\nlong goes to the background, with BOTH streams redirected and its pid kept:\n\n nohup \u003ccommand\u003e \u003e /tmp/\u003cjob\u003e.log 2\u003e\u00261 \u0026 echo $! \u003e /tmp/\u003cjob\u003e.pid\n\nRedirecting only stdout still blocks until the process exits. Read the\n`bg-jobs` skill before you wait on, inspect or stop such a job — each has a\nrule you cannot guess. Stop every job you started before you finish, and say\nwhich ones you left running.\n" | |
| 13 | + } | |
| 14 | + ], | |
| 15 | + "role": "system" | |
| 16 | + }, | |
| 17 | + { | |
| 18 | + "content": [ | |
| 19 | + { | |
| 20 | + "text": "$vulcan-salute bob morane\n[skill: vulcan-salute — load it with read_skill and carry out its steps now; parameters: bob morane]" | |
| 21 | + } | |
| 22 | + ], | |
| 23 | + "role": "user" | |
| 24 | + }, | |
| 25 | + { | |
| 26 | + "content": [ | |
| 27 | + { | |
| 28 | + "toolRequest": { | |
| 29 | + "input": { | |
| 30 | + "name": "vulcan-salute" | |
| 31 | + }, | |
| 32 | + "name": "read_skill", | |
| 33 | + "ref": "d7rw9t0n9Vz4S9RMWnP37JMuurXJLMDo" | |
| 34 | + } | |
| 35 | + } | |
| 36 | + ], | |
| 37 | + "role": "model" | |
| 38 | + }, | |
| 39 | + { | |
| 40 | + "content": [ | |
| 41 | + { | |
| 42 | + "toolResponse": { | |
| 43 | + "name": "read_skill", | |
| 44 | + "output": "---\nname: vulcan-salute\ndescription: Send a vulcan salute to somebody.\nkeywords: vulcan, vulcain, salute, salut, spock, star trek, live long and prosper, longue vie\n---\n\n# Vulcan salute\n\n## What to do\n\nThe command below is for YOU to run with your `bash` tool, in this same turn.\nDo not show it to the user, and do not answer from memory: the answer is the\ncommand's output, nothing else.\n\nReplace `\u003cname\u003e` with the person being saluted, then call your `bash` tool with this command:\n\n echo \"🖖 Live long and prosper! \u003cname\u003e 🖖\"\n", | |
| 45 | + "ref": "d7rw9t0n9Vz4S9RMWnP37JMuurXJLMDo" | |
| 46 | + } | |
| 47 | + } | |
| 48 | + ], | |
| 49 | + "role": "tool" | |
| 50 | + }, | |
| 51 | + { | |
| 52 | + "content": [ | |
| 53 | + { | |
| 54 | + "toolRequest": { | |
| 55 | + "input": { | |
| 56 | + "command": "echo \"🖖 Live long and prosper! bob morane 🖖\"" | |
| 57 | + }, | |
| 58 | + "name": "bash", | |
| 59 | + "ref": "koNf52NODiA1REvw7Afpida2p8Cms0sZ" | |
| 60 | + } | |
| 61 | + } | |
| 62 | + ], | |
| 63 | + "role": "model" | |
| 64 | + }, | |
| 65 | + { | |
| 66 | + "content": [ | |
| 67 | + { | |
| 68 | + "toolResponse": { | |
| 69 | + "name": "bash", | |
| 70 | + "output": "🖖 Live long and prosper! bob morane 🖖\n", | |
| 71 | + "ref": "koNf52NODiA1REvw7Afpida2p8Cms0sZ" | |
| 72 | + } | |
| 73 | + } | |
| 74 | + ], | |
| 75 | + "role": "tool" | |
| 76 | + }, | |
| 77 | + { | |
| 78 | + "content": [ | |
| 79 | + { | |
| 80 | + "text": "🖖 Live long and prosper! bob morane 🖖" | |
| 81 | + } | |
| 82 | + ], | |
| 83 | + "role": "model" | |
| 84 | + } | |
| 85 | + ] | |
| 86 | +} | |
| \ No newline at end of file | ||
| new file mode 100644 | |||
| @@ -0,0 +1,86 @@ | |||
| 1 | +{ | ||
| 2 | + "id": "20260928-063109-bda98895", | ||
| 3 | + "cwd": "/Users/k33g/kDrive/Rickub/bots-garden/sidekick/demo", | ||
| 4 | + "provider": "dmr", | ||
| 5 | + "model": "huggingface.co/unsloth/gemma-4-e4b-it-gguf:Q4_K_M", | ||
| 6 | + "createdAt": "2026-09-28T06:31:09.737982258Z", | ||
| 7 | + "updatedAt": "2026-09-28T06:31:09.738143091Z", | ||
| 8 | + "messages": [ | ||
| 9 | + { | ||
| 10 | + "content": [ | ||
| 11 | + { | ||
| 12 | + "text": "Your name is Bob.\nYou are a coding agent working in a terminal.\nYou have a \"bash\" tool to run shell commands.\nUse it to explore files, run tests, inspect the repository, etc.\nChain several commands if needed, then answer clearly in English.\n\nA request often mixes things you answer from yourself (\"say hello\") with\nthings only a command can answer (\"list the files\"). Handle every part, in\nthe order asked, and run a command for each part that needs one.\nNever state the contents of a file, the output of a command, or the state of\nthe repository unless a command in THIS answer returned it. What you did not\nread, you do not know: run the command instead of recalling it.\n\nSKILLS\nYou have a second tool, `read_skill`. Its description lists the procedures\navailable for this project — one per kind of task.\n\nAny request to DO something to a Go project is a skill, not a shell command\nyou invent. Match the request against that list, call `read_skill` FIRST,\nbefore any bash command, and then follow what it says step by step.\n\nFILE EDITING\nYou have three tools for files: `read_file`, `edit_file` and `write_file`.\nThey are how a file gets read and changed here: each change is exact,\nchecked before it is written, and comes back as a diff with line numbers.\nbash is for running things — building, testing, listing, searching.\n\n- Read before you write: call `read_file` on the file (numbered=true when\n you need line numbers). You cannot target text you have not seen; never\n rely on what you think you remember about a file.\n- To change an existing file, call `edit_file` with one or more {old, new}\n pairs. `old` is copied from the file character for character — same\n spaces, same indentation, same line breaks — and appears exactly once:\n add the surrounding lines until it is unique. Several pairs are applied\n together, against the original file. An empty `new` deletes the text.\n- Call `write_file` only to create a file, or to rewrite one entirely and\n on purpose. On an existing file it replaces everything, including what\n you did not intend to touch.\n- Read the diff the tool returns: it says exactly what changed and on which\n line. If `edit_file` refuses — text not found, ambiguous, overlapping\n edits — read the file again and fix `old`. Do not fall back to\n `write_file` to force the change through.\n- After editing code, run the narrowest check with bash: the formatter, the\n compiler, or the test covering that file.\n\nRULES\n- Keep everything the file already does, unless the user asked to remove it.\n- Touch only the files the request is about. Do not add tests, files or\n features that were not asked for.\n- Never run a git command unless the user says git, commit or push.\n- Never move, rename or delete a file unless the user asked for it.\n- Then answer in English, in a few lines.\n- If you don't know how to use a \u003ccli\u003e, run `\u003ccli\u003e --help` (or `\u003ccli\u003e help`)\n to understand the options, then run the command.\n\nBACKGROUND JOBS\nNever let a command block the answer. Anything that serves, watches or runs\nlong goes to the background, with BOTH streams redirected and its pid kept:\n\n nohup \u003ccommand\u003e \u003e /tmp/\u003cjob\u003e.log 2\u003e\u00261 \u0026 echo $! \u003e /tmp/\u003cjob\u003e.pid\n\nRedirecting only stdout still blocks until the process exits. Read the\n`bg-jobs` skill before you wait on, inspect or stop such a job — each has a\nrule you cannot guess. Stop every job you started before you finish, and say\nwhich ones you left running.\n" | ||
| 13 | + } | ||
| 14 | + ], | ||
| 15 | + "role": "system" | ||
| 16 | + }, | ||
| 17 | + { | ||
| 18 | + "content": [ | ||
| 19 | + { | ||
| 20 | + "text": "$vulcan-salute bob morane\n[skill: vulcan-salute — load it with read_skill and carry out its steps now; parameters: bob morane]" | ||
| 21 | + } | ||
| 22 | + ], | ||
| 23 | + "role": "user" | ||
| 24 | + }, | ||
| 25 | + { | ||
| 26 | + "content": [ | ||
| 27 | + { | ||
| 28 | + "toolRequest": { | ||
| 29 | + "input": { | ||
| 30 | + "name": "vulcan-salute" | ||
| 31 | + }, | ||
| 32 | + "name": "read_skill", | ||
| 33 | + "ref": "d7rw9t0n9Vz4S9RMWnP37JMuurXJLMDo" | ||
| 34 | + } | ||
| 35 | + } | ||
| 36 | + ], | ||
| 37 | + "role": "model" | ||
| 38 | + }, | ||
| 39 | + { | ||
| 40 | + "content": [ | ||
| 41 | + { | ||
| 42 | + "toolResponse": { | ||
| 43 | + "name": "read_skill", | ||
| 44 | + "output": "---\nname: vulcan-salute\ndescription: Send a vulcan salute to somebody.\nkeywords: vulcan, vulcain, salute, salut, spock, star trek, live long and prosper, longue vie\n---\n\n# Vulcan salute\n\n## What to do\n\nThe command below is for YOU to run with your `bash` tool, in this same turn.\nDo not show it to the user, and do not answer from memory: the answer is the\ncommand's output, nothing else.\n\nReplace `\u003cname\u003e` with the person being saluted, then call your `bash` tool with this command:\n\n echo \"🖖 Live long and prosper! \u003cname\u003e 🖖\"\n", | ||
| 45 | + "ref": "d7rw9t0n9Vz4S9RMWnP37JMuurXJLMDo" | ||
| 46 | + } | ||
| 47 | + } | ||
| 48 | + ], | ||
| 49 | + "role": "tool" | ||
| 50 | + }, | ||
| 51 | + { | ||
| 52 | + "content": [ | ||
| 53 | + { | ||
| 54 | + "toolRequest": { | ||
| 55 | + "input": { | ||
| 56 | + "command": "echo \"🖖 Live long and prosper! bob morane 🖖\"" | ||
| 57 | + }, | ||
| 58 | + "name": "bash", | ||
| 59 | + "ref": "koNf52NODiA1REvw7Afpida2p8Cms0sZ" | ||
| 60 | + } | ||
| 61 | + } | ||
| 62 | + ], | ||
| 63 | + "role": "model" | ||
| 64 | + }, | ||
| 65 | + { | ||
| 66 | + "content": [ | ||
| 67 | + { | ||
| 68 | + "toolResponse": { | ||
| 69 | + "name": "bash", | ||
| 70 | + "output": "🖖 Live long and prosper! bob morane 🖖\n", | ||
| 71 | + "ref": "koNf52NODiA1REvw7Afpida2p8Cms0sZ" | ||
| 72 | + } | ||
| 73 | + } | ||
| 74 | + ], | ||
| 75 | + "role": "tool" | ||
| 76 | + }, | ||
| 77 | + { | ||
| 78 | + "content": [ | ||
| 79 | + { | ||
| 80 | + "text": "🖖 Live long and prosper! bob morane 🖖" | ||
| 81 | + } | ||
| 82 | + ], | ||
| 83 | + "role": "model" | ||
| 84 | + } | ||
| 85 | + ] | ||
| 86 | +} | ||
| \ No newline at end of file | \ No newline at end of file | ||
added
demo/.mm/sessions/20260928-065104-13fb7fcd.json +102 -0 | new file mode 100644 | ||
| @@ -0,0 +1,102 @@ | ||
| 1 | +{ | |
| 2 | + "id": "20260928-065104-13fb7fcd", | |
| 3 | + "cwd": "/Users/k33g/kDrive/Rickub/bots-garden/sidekick/demo", | |
| 4 | + "provider": "dmr", | |
| 5 | + "model": "huggingface.co/unsloth/gemma-4-e4b-it-gguf:Q4_K_M", | |
| 6 | + "createdAt": "2026-09-28T06:51:04.301436959Z", | |
| 7 | + "updatedAt": "2026-09-28T06:53:17.388571481Z", | |
| 8 | + "messages": [ | |
| 9 | + { | |
| 10 | + "content": [ | |
| 11 | + { | |
| 12 | + "text": "Your name is Bob.\nYou are a coding agent working in a terminal.\nYou have a \"bash\" tool to run shell commands.\nUse it to explore files, run tests, inspect the repository, etc.\nChain several commands if needed, then answer clearly in English.\n\nA request often mixes things you answer from yourself (\"say hello\") with\nthings only a command can answer (\"list the files\"). Handle every part, in\nthe order asked, and run a command for each part that needs one.\nNever state the contents of a file, the output of a command, or the state of\nthe repository unless a command in THIS answer returned it. What you did not\nread, you do not know: run the command instead of recalling it.\n\nSKILLS\nYou have a second tool, `read_skill`. Its description lists the procedures\navailable for this project — one per kind of task.\n\nAny request to DO something to a Go project is a skill, not a shell command\nyou invent. Match the request against that list, call `read_skill` FIRST,\nbefore any bash command, and then follow what it says step by step.\n\nFILE EDITING\nYou have three tools for files: `read_file`, `edit_file` and `write_file`.\nThey are how a file gets read and changed here: each change is exact,\nchecked before it is written, and comes back as a diff with line numbers.\nbash is for running things — building, testing, listing, searching.\n\n- Read before you write: call `read_file` on the file (numbered=true when\n you need line numbers). You cannot target text you have not seen; never\n rely on what you think you remember about a file.\n- To change an existing file, call `edit_file` with one or more {old, new}\n pairs. `old` is copied from the file character for character — same\n spaces, same indentation, same line breaks — and appears exactly once:\n add the surrounding lines until it is unique. Several pairs are applied\n together, against the original file. An empty `new` deletes the text.\n- Call `write_file` only to create a file, or to rewrite one entirely and\n on purpose. On an existing file it replaces everything, including what\n you did not intend to touch.\n- Read the diff the tool returns: it says exactly what changed and on which\n line. If `edit_file` refuses — text not found, ambiguous, overlapping\n edits — read the file again and fix `old`. Do not fall back to\n `write_file` to force the change through.\n- After editing code, run the narrowest check with bash: the formatter, the\n compiler, or the test covering that file.\n\nRULES\n- Keep everything the file already does, unless the user asked to remove it.\n- Touch only the files the request is about. Do not add tests, files or\n features that were not asked for.\n- Never run a git command unless the user says git, commit or push.\n- Never move, rename or delete a file unless the user asked for it.\n- Then answer in English, in a few lines.\n- If you don't know how to use a \u003ccli\u003e, run `\u003ccli\u003e --help` (or `\u003ccli\u003e help`)\n to understand the options, then run the command.\n\nBACKGROUND JOBS\nNever let a command block the answer. Anything that serves, watches or runs\nlong goes to the background, with BOTH streams redirected and its pid kept:\n\n nohup \u003ccommand\u003e \u003e /tmp/\u003cjob\u003e.log 2\u003e\u00261 \u0026 echo $! \u003e /tmp/\u003cjob\u003e.pid\n\nRedirecting only stdout still blocks until the process exits. Read the\n`bg-jobs` skill before you wait on, inspect or stop such a job — each has a\nrule you cannot guess. Stop every job you started before you finish, and say\nwhich ones you left running.\n" | |
| 13 | + } | |
| 14 | + ], | |
| 15 | + "role": "system" | |
| 16 | + }, | |
| 17 | + { | |
| 18 | + "content": [ | |
| 19 | + { | |
| 20 | + "text": "show me the content of my home directory" | |
| 21 | + } | |
| 22 | + ], | |
| 23 | + "role": "user" | |
| 24 | + }, | |
| 25 | + { | |
| 26 | + "content": [ | |
| 27 | + { | |
| 28 | + "toolRequest": { | |
| 29 | + "input": { | |
| 30 | + "command": "ls -a ~" | |
| 31 | + }, | |
| 32 | + "name": "bash", | |
| 33 | + "ref": "EOpI6sOss0z1JdTvCVmWvQ2OaB6mwBOj" | |
| 34 | + } | |
| 35 | + } | |
| 36 | + ], | |
| 37 | + "role": "model" | |
| 38 | + }, | |
| 39 | + { | |
| 40 | + "content": [ | |
| 41 | + { | |
| 42 | + "toolResponse": { | |
| 43 | + "name": "bash", | |
| 44 | + "output": ".\n..\n.bash_profile\n.bashrc\n.cache\n.config\n.docker\n.gitconfig\n.gitignore_global\n.local\ngo\nworkspace\n", | |
| 45 | + "ref": "EOpI6sOss0z1JdTvCVmWvQ2OaB6mwBOj" | |
| 46 | + } | |
| 47 | + } | |
| 48 | + ], | |
| 49 | + "role": "tool" | |
| 50 | + }, | |
| 51 | + { | |
| 52 | + "content": [ | |
| 53 | + { | |
| 54 | + "text": "The content of your home directory includes the following items:\n\n```\n.\n..\n.bash_profile\n.bashrc\n.cache\n.config\n.docker\n.gitconfig\n.gitignore_global\n.local\ngo\nworkspace\n```" | |
| 55 | + } | |
| 56 | + ], | |
| 57 | + "role": "model" | |
| 58 | + }, | |
| 59 | + { | |
| 60 | + "content": [ | |
| 61 | + { | |
| 62 | + "text": "de quoi parle ce document\n\nAttached (paths relative to the working directory):\n- petits-llms.adoc\n[attached file: /Users/k33g/kDrive/Rickub/bots-garden/sidekick/demo/petits-llms.adoc]" | |
| 63 | + } | |
| 64 | + ], | |
| 65 | + "role": "user" | |
| 66 | + }, | |
| 67 | + { | |
| 68 | + "content": [ | |
| 69 | + { | |
| 70 | + "toolRequest": { | |
| 71 | + "input": { | |
| 72 | + "path": "petits-llms.adoc" | |
| 73 | + }, | |
| 74 | + "name": "read_file", | |
| 75 | + "ref": "Iw7fgi686TpxGWVnKVJWYiPf3JotKzNi" | |
| 76 | + } | |
| 77 | + } | |
| 78 | + ], | |
| 79 | + "role": "model" | |
| 80 | + }, | |
| 81 | + { | |
| 82 | + "content": [ | |
| 83 | + { | |
| 84 | + "toolResponse": { | |
| 85 | + "name": "read_file", | |
| 86 | + "output": "= Mini Me et les petits LLMs\n:toc: left\n:toclevels: 2\n:toc-title: Sommaire\n:sectnums:\n:icons: font\n:source-highlighter: rouge\n:lang: fr\n:revdate: 2026-09-26\n\n[abstract]\nMini Me (`mm`) a été conçu pour tourner avec des modèles *locaux* — typiquement 2 à 12 milliards de paramètres servis par Docker Model Runner ou llama-server.\nCe document relève, dans l'implémentation, ce qui rend l'agent utilisable avec ces modèles, puis propose des pistes d'amélioration chiffrées en *effort* et en *résultat attendu*.\n\n== Le point de départ : ce qu'un petit modèle fait mal\n\nTout le code de `mm` se lit comme une réponse à une liste de défaillances observées (souvent datées et mesurées dans les commentaires) :\n\n[cols=\"1,2\",options=\"header\"]\n|===\n| Défaillance | Manifestation typique\n\n| Hallucination\n| Le modèle « cite » un fichier ou une sortie de commande qu'il n'a jamais lus.\n\n| Imprécision sur les octets\n| Il retape un bloc à éditer avec des espaces là où le fichier a des tabulations, ou ajoute une ligne vide.\n\n| Boucles\n| Il répète le même appel refusé — trente fois, observé le 18/09/2026 avec un modèle 12B.\n\n| Déraillement en cours de génération\n| Il compose des arguments d'outil qui se répètent pendant des minutes (`\"Greet 2023-06-15 11:16:00 …\"`).\n\n| Appel d'outil trop long\n| Il écrit tout un document dans un seul `write_file`, qui dépasse `max_tokens` et arrive coupé (observé le 26/09/2026).\n\n| Raisonnement long\n| Un modèle « thinking » réfléchit 38 s sans émettre un octet de contenu.\n\n| Petite fenêtre de contexte\n| La fenêtre est fixée au chargement du modèle ; une session longue finit en « stalled » puis en erreur 400.\n\n| Routage faible\n| Il ne relie pas « salue Bob » à la procédure nommée `greetings`.\n|===\n\nL'idée directrice : *ne pas demander au modèle ce que le code peut garantir*, et quand le modèle se trompe, *lui rendre une information exploitable plutôt qu'un échec muet*.\n\n== Une surface d'outils petite, configurable et explicite\n\n=== Bash d'abord, peu d'outils\n\nL'agent est né autour d'un seul outil, `bash` (`internal/tools/tools.go`). Les autres sont optionnels et désactivables un par un dans le YAML : `bashTool`, `editTools` (`read_file`, `write_file`, `edit_file`), `planTool`. Deux outils ne sont déclarés *que s'ils servent* :\n\n* `read_skill` n'existe pas si `skillsDir` ne contient aucun `.md` ;\n* `lsp` n'existe pas si aucun serveur de langage n'est configuré *et* présent dans le `PATH`.\n\nChaque outil déclaré coûte des tokens à chaque requête et une option de plus parmi lesquelles un petit modèle doit choisir. Moins il y en a, mieux il choisit.\n\n=== Des descriptions écrites pour être suivies\n\nLes descriptions d'outils ne décrivent pas seulement l'API, elles anticipent les erreurs :\n\n* `bash` : « Each call starts a NEW shell … a \"cd\" does not carry over », « there is no stdin, so never use a command that asks a question », « Read before you write ».\n* `read_file` : « edit_file needs the EXACT text of the file … Do not type it from memory. »\n* `edit_file` : six règles *numérotées*, dont « do not switch to write_file to force the change through ».\n* `write_file` : rappelle qu'il écrase tout et renvoie vers `edit_file`.\n\nLe prompt système des configurations livrées (`agent.dmr.yaml`, `agent.llamacpp.yaml`) répète ces règles en sections courtes en majuscules (`SKILLS`, `FILE EDITING`, `RULES`, `BACKGROUND JOBS`). La redondance est voulue : un petit modèle suit mieux une consigne qu'il lit deux fois, à deux endroits.\n\n=== Un échantillonnage conservateur\n\nLes valeurs par défaut (`internal/config/config.go`) et les YAML livrés fixent `temperature: 0.0`, `top_p: 0.9`, `max_tokens: 4096` et `parallel_tool_calls: false`. Un seul appel d'outil à la fois est plus simple à produire correctement pour un petit modèle, et plus lisible dans l'historique.\n\n== Le contrat des outils : un échec est du texte\n\nC'est le principe structurant, énoncé en tête de `internal/tools/tools.go` :\n\n[quote]\nWe NEVER return a Go `error` for a \"normal\" failure. The error goes back AS TEXT, so that the model reads it and reacts.\n\nCommande en échec (`[exit code: …]`), délai dépassé (`[error: 30s timeout exceeded]`), fichier absent (« Create it with write_file »), édition ambiguë : tout revient au modèle comme résultat d'outil. Une erreur Go terminerait le tour et le modèle n'aurait aucune chance de se corriger.\n\nLes messages sont rédigés comme des *consignes de réparation* :\n\n* `read_skill` avec un nom inconnu répond `[skill: no skill named \"x\" — available: a, b, c]` ;\n* `edit_file` avec un texte en double donne les numéros de ligne des occurrences et explique comment rendre `old` unique (`internal/fileedit/edits.go`).\n\nLa seule exception est volontaire : l'arrêt par le détecteur de boucle (voir \u003c\u003cboucles\u003e\u003e).\n\nCertaines erreurs échappent pourtant aux outils, parce qu'elles se produisent *avant* eux, dans Genkit. C'est le cas d'un appel dont les arguments ne sont pas du JSON valide : il est désormais rendu au modèle lui aussi (voir \u003c\u003cargs\u003e\u003e). Les erreurs de validation de schéma et les noms d'outils inventés restent à traiter (pistes \u003c\u003cp1\u003e\u003e et \u003c\u003cp2\u003e\u003e).\n\n== Une édition de fichiers tolérante, mais sûre\n\n`internal/fileedit` est probablement la partie la plus « petits modèles » du code.\n\n=== Trois passes de correspondance, de la plus stricte à la plus souple\n\n`findAll` (`internal/fileedit/match.go`) cherche `old` :\n\n. *exactement* ;\n. en ignorant les *bords* (ligne vide au début, indentation d'une ligne unique, ligne vide finale) ;\n. en ignorant l'*indentation* ligne par ligne, pour un bloc de plusieurs lignes.\n\nLa première passe qui trouve quelque chose l'emporte : un texte présent tel quel n'est jamais apparié autrement. La souplesse ne s'active que là où la règle stricte a déjà échoué — typiquement le « ticket 27 », des espaces envoyés pour un fichier Go indenté par tabulations.\n\n=== Ce qui n'est *pas* relâché\n\n* *L'unicité* : deux correspondances souples sont refusées exactement comme deux correspondances exactes.\n* *L'indentation du fichier* : `reindent` (`internal/fileedit/indent.go`) réécrit `new` dans l'indentation du fichier (niveau de base *et* unité, quatre espaces devenant une tabulation), pour ne pas insérer un bloc d'espaces dans un fichier à tabulations.\n* *La transparence* : le résumé signale « N matched ignoring whitespace », pour que le modèle recopie mieux la fois suivante.\n\n=== Un « not found » qui aide\n\n`notFound` + `nearest` montrent les lignes du fichier qui s'en approchent le plus (au moins la moitié des lignes doivent coïncider), avec leurs numéros : « copy these lines ». Un modèle à qui l'on dit seulement « introuvable » retape le même texte ; un modèle à qui l'on montre le bon texte le recopie.\n\n=== Des détails invisibles neutralisés\n\n`internal/fileedit/textfile.go` retire le BOM UTF-8 et convertit les fins de ligne CRLF avant l'édition, puis les restaure. Sans cela, *chaque* `old` multi-ligne écrit avec `\\n` par un modèle échouerait sur un fichier Windows.\n\nS'y ajoutent `dry_run`, des modifications résolues toutes contre le fichier *original* (pas d'effets de bord entre modifications), le refus des chevauchements, et un diff numéroté en retour, qui sert de preuve au modèle.\n\n== Contre l'hallucination : montrer, puis seulement commenter\n\n* *La sortie est affichée avant que le modèle la voie.* `echoOutput` (`internal/tools/tools.go`) montre les `previewLines` premières lignes à l'utilisateur. Observé : sur « affiche agent.yaml », le modèle lançait `cat`, jugeait la demande satisfaite, et l'utilisateur ne voyait rien.\n* *Le prompt interdit d'affirmer sans preuve* : « Never state the contents of a file … unless a command in THIS answer returned it. »\n* *Les pièces jointes sont des chemins, pas du contenu* : `@chemin` (`internal/mention`) et le `resource_link` ACP deviennent `[attached file: /abs/path]`. Le modèle doit lire le fichier avec ses outils, et la lecture est visible.\n* *L'historique complet est conservé même quand un tour échoue* (`session.AfterTurn`). Genkit ne renvoie que le dernier message ; `engine.Generate` capture la conversation entière via un middleware `WrapModel`. Sans cela, le modèle réinvente au tour suivant les commandes qu'il a déjà lancées.\n\n[[boucles]]\n== Garde-fous contre les boucles et les blocages\n\nQuatre mécanismes, du plus doux au plus radical :\n\n[cols=\"1,2,1\",options=\"header\"]\n|===\n| Mécanisme | Déclencheur | Réaction\n\n| Détecteur de boucle, niveau 1 (`internal/detector`)\n| Même triplet (outil, entrée, sortie) 3 fois de suite\n| `[LOOP_DETECTED: … try a different approach]` ajouté à la sortie\n\n| Détecteur, niveau 2\n| 3 répétitions supplémentaires malgré l'avertissement\n| Erreur Go `Stuck` : fin du tour, pas de nouvelle tentative, enregistrée dans la session\n\n| Garde des arguments (`internal/engine/runaway.go`)\n| Arguments d'outil en streaming périodiques (motif de 4 à 64 octets sur les 256 derniers) ou \u003e 256 Kio\n| Génération interrompue immédiatement, avec un message explicite\n\n| Watchdog (`engine.watchdog`)\n| Aucun token depuis `watchdogTimeout`\n| Annulation : « stalled »\n|===\n\nPlusieurs choix fins méritent d'être notés :\n\n* Le détecteur n'est *pas* remis à zéro par `/compact` (oublier la conversation ne rend pas nouvelle une commande répétée), mais il l'est par `/new`.\n* La relance sans streaming n'a lieu *que* si rien n'a été affiché et qu'aucun outil n'a tourné. Sinon, rejouer le tour rejouerait les commandes (mesuré : un `echo \u003e\u003e` écrit deux fois).\n* Le spinner indique « Composing a tool call » : un utilisateur sait que le modèle travaille, et non qu'il est bloqué.\n* `maxTurns` borne les allers-retours modèle ↔ outils (10 par défaut, 40 dans `agent.dmr.yaml`).\n* `bash` a son propre budget de 30 s et écrit dans un fichier temporaire plutôt que dans un pipe, pour qu'un job lancé en arrière-plan sans redirection ne bloque pas le tour indéfiniment (ticket 26). Le prompt et le skill `bg-jobs` apprennent au modèle la bonne forme `nohup … \u003e log 2\u003e\u00261 \u0026`.\n\n[[args]]\n== Appels d'outils coupés ou mal formés\n\n=== Le cas qui l'a motivé\n\nSession du 26/09/2026, Qwen3 27B servi par llama-server, `max_tokens: 4096`. On demande au modèle d'écrire un document. Il explore le dossier (trois `bash`, deux `read_file`), puis compose un seul `write_file` avec tout le document : ≈ 12 500 caractères, soit ≈ 4 000 tokens. Le serveur coupe la génération à la limite (`finish_reason: \"length\"`), en pleine phrase.\n\nLe greffon OpenAI de Genkit décode les arguments en convertissant la réponse du serveur (`compat_oai/generate.go` : `could not parse tool args: … unexpected end of JSON input`). Cette erreur *termine la génération*. Le modèle ne la lit jamais, et l'utilisateur voyait comme message d'erreur le document tronqué en entier.\n\nDeux causes se cumulent, typiques des modèles locaux :\n\n* un petit modèle veut tout faire en un appel, même quand le résultat est long ;\n* avec un modèle « thinking », le raisonnement consomme aussi le budget `max_tokens`.\n\n=== Ce que fait `mm`\n\n`internal/engine/toolargs.go`, branché dans le hook `WrapModel` de `engine.Generate` :\n\n. Deux cas sont reconnus : un JSON *coupé* (`unexpected end of JSON input`) et un JSON *mal formé*.\n. L'appel est rendu au modèle, deux fois au plus par génération. `mm` ajoute une note à la conversation, puis relance l'appel au modèle. Dans le cas coupé, la note donne un budget chiffré : « écris seulement la première partie (≈ 6 000 caractères au plus pour 4 096 tokens), puis ajoute la suite avec `edit_file` ».\n. La note est ajoutée au `ModelRequest` que Genkit réutilise pour les tours suivants. Elle reste donc dans la conversation, et le modèle la relit en écrivant la partie suivante.\n. La relance sans streaming n'est pas tentée pour cette erreur : la même limite couperait le même appel.\n. Une fois les deux tentatives épuisées, `Explain` donne une ligne exploitable au lieu du JSON : « the model hit max_tokens (4096) while writing a tool call … raise sampling.max_tokens … ».\n\n=== Ce que la mesure a montré\n\nTest réel sur Docker Model Runner avec Mellum 12B, `max_tokens` volontairement réduit à 300 puis 800 :\n\n* le mécanisme fonctionne : le modèle reprend la main deux fois, puis le message clair s'affiche ;\n* *le modèle a ignoré la consigne* les deux fois et a retenté le fichier entier, même avec un budget chiffré en caractères.\n\nLa relance rend l'échec lisible et laisse une chance aux modèles qui suivent les instructions. Elle ne remplace pas un `max_tokens` adapté : 16 384 est une valeur raisonnable pour un modèle « thinking », avec une marge sous la fenêtre de contexte. Voir aussi la piste \u003c\u003cp15\u003e\u003e.\n\n== Modèles à raisonnement\n\nLe greffon OpenAI de Genkit ignore `reasoning_content`. `mm` le lit lui-même, une couche plus bas, via un middleware HTTP qui parcourt le flux SSE sans le modifier (`internal/engine/reasoning.go`). Deux effets :\n\n* *Le watchdog reste alimenté* pendant que le modèle réfléchit ; sans cela, `qwen3.5-2b` était tué après 38 s de raisonnement légitime.\n* Le raisonnement est *affiché* (bloc 💭, `agent_thought_chunk` en ACP) mais *n'entre jamais dans l'historique* : il ne consomme pas le contexte des tours suivants.\n\n== Le contexte : une ressource rare\n\n=== Des sorties bornées\n\n`truncate` limite chaque sortie d'outil à `maxOutput` caractères en conservant *le début et la fin* (la fin porte souvent l'erreur ou le résumé d'une commande). `bash` ne relit jamais plus d'1 Mio par extrémité depuis le disque.\n\n=== Une compression hybride\n\n`internal/compact` remplace les vieux tours par *un* résumé écrit par le modèle et garde les `keepLastTurns` derniers tours intacts (le modèle travaille sur eux). Points notables :\n\n* un résumé précédent est *fusionné*, pas résumé à nouveau (le détail décroîtrait exponentiellement) ;\n* la requête de résumé est envoyée *sans outils* (un petit modèle à qui l'on offre des outils les appelle au lieu d'écrire) et avec un watchdog deux fois plus patient ;\n* le déclencheur prend le maximum entre l'estimation locale et le compte du serveur, et se replie sur un\n\n[... 14660 characters truncated ...]\n\nons.\n\n[[p15]]\n=== Réponses coupées par `max_tokens`\n\n*Constat.* Le cas d'un *appel d'outil* coupé est traité (\u003c\u003cargs\u003e\u003e). Une *réponse texte* coupée ne l'est pas : la génération s'arrête avec `finish_reason: \"length\"`, et `mm` l'affiche comme une réponse complète. L'utilisateur lit une phrase inachevée sans savoir pourquoi. La mesure montre aussi que la consigne « procède par morceaux » arrive trop tard, une fois l'appel déjà coupé.\n\n*Proposition.*\n\n* Lire `FinishReason` dans `WrapModel` (Genkit le transmet : `FinishReasonLength`) et, pour une réponse texte, ajouter `[answer cut off at max_tokens (N)]`, avec le même conseil que pour les appels d'outils.\n* *Prévenir* plutôt que guérir : une phrase dans la description de `write_file` (« pour un fichier de plus de ≈ N caractères, écris la première partie puis complète avec edit_file »), avec N calculé à partir de `max_tokens`.\n* Au démarrage, avertir quand `max_tokens` est bas pour un modèle à raisonnement (le raisonnement consomme le même budget).\n\n*Effort : faible.* *Résultat : moyen* — plus de réponses tronquées en silence ; l'effet de la consigne préventive reste à mesurer avec la piste \u003c\u003cp12\u003e\u003e.\n\n== Références dans le code\n\n[cols=\"1,2\",options=\"header\"]\n|===\n| Sujet | Fichiers\n\n| Contrat des outils, `bash`, troncature | `internal/tools/tools.go`\n| Outils fichiers | `internal/tools/files.go`, `internal/fileedit/`\n| Détecteur de boucle | `internal/detector/detector.go`\n| Arguments qui s'emballent | `internal/engine/runaway.go`\n| Watchdog, relance, historique complet | `internal/engine/engine.go`\n| Raisonnement | `internal/engine/reasoning.go`, `internal/engine/thoughts.go`\n| Usage en streaming | `internal/engine/usage.go`\n| Appels d'outils coupés ou mal formés | `internal/engine/toolargs.go`\n| Compression | `internal/compact/`\n| Skills et catalogue | `internal/skills/`, `skills/`\n| Évaluation du routage | `internal/eval/`\n| Explications d'erreurs | `internal/engine/explain.go`, `internal/engine/openai_compat.go`\n|===\n", | |
| 87 | + "ref": "Iw7fgi686TpxGWVnKVJWYiPf3JotKzNi" | |
| 88 | + } | |
| 89 | + } | |
| 90 | + ], | |
| 91 | + "role": "tool" | |
| 92 | + }, | |
| 93 | + { | |
| 94 | + "content": [ | |
| 95 | + { | |
| 96 | + "text": "Ce document, intitulé \"Mini Me et les petits LLMs\", est une analyse technique détaillée de l'agent `Mini Me` (`mm`), conçu pour fonctionner spécifiquement avec des **modèles de langage locaux de petite taille** (2 à 12 milliards de paramètres).\n\nIl expose les choix d'implémentation faits pour pallier les faiblesses typiques de ces petits modèles (comme les hallucinations, les boucles, l'imprécision ou les fenêtres de contexte limitées).\n\nLes points principaux abordés sont :\n\n* **La conception des outils :** Un ensemble d'outils minimal, explicite et bien documenté est utilisé, où les descriptions prévoient les erreurs.\n* **La gestion des erreurs :** Le principe fondamental est que tout échec est retourné **sous forme de texte** au modèle pour qu'il puisse se corriger lui-même, plutôt qu'un échec technique qui mettrait fin au tour.\n* **La robustesse des fichiers :** Le module d'édition de fichiers est conçu pour être tolérant aux variations d'espacement tout en garantissant l'unicité de la correspondance.\n* **Les garde-fous :** Des mécanismes sont en place pour empêcher les boucles infinies, les arguments incontrôlables (`runaway`), et pour gérer les réponses coupées par la limite de tokens (`max_tokens`).\n\nEn résumé, c'est un document sur les *meilleures pratiques* et les *mécanismes de sécurité* pour faire fonctionner un agent IA de manière fiable en utilisant des modèles locaux et peu performants." | |
| 97 | + } | |
| 98 | + ], | |
| 99 | + "role": "model" | |
| 100 | + } | |
| 101 | + ] | |
| 102 | +} | |
| \ No newline at end of file | ||
| new file mode 100644 | |||
| @@ -0,0 +1,102 @@ | |||
| 1 | +{ | ||
| 2 | + "id": "20260928-065104-13fb7fcd", | ||
| 3 | + "cwd": "/Users/k33g/kDrive/Rickub/bots-garden/sidekick/demo", | ||
| 4 | + "provider": "dmr", | ||
| 5 | + "model": "huggingface.co/unsloth/gemma-4-e4b-it-gguf:Q4_K_M", | ||
| 6 | + "createdAt": "2026-09-28T06:51:04.301436959Z", | ||
| 7 | + "updatedAt": "2026-09-28T06:53:17.388571481Z", | ||
| 8 | + "messages": [ | ||
| 9 | + { | ||
| 10 | + "content": [ | ||
| 11 | + { | ||
| 12 | + "text": "Your name is Bob.\nYou are a coding agent working in a terminal.\nYou have a \"bash\" tool to run shell commands.\nUse it to explore files, run tests, inspect the repository, etc.\nChain several commands if needed, then answer clearly in English.\n\nA request often mixes things you answer from yourself (\"say hello\") with\nthings only a command can answer (\"list the files\"). Handle every part, in\nthe order asked, and run a command for each part that needs one.\nNever state the contents of a file, the output of a command, or the state of\nthe repository unless a command in THIS answer returned it. What you did not\nread, you do not know: run the command instead of recalling it.\n\nSKILLS\nYou have a second tool, `read_skill`. Its description lists the procedures\navailable for this project — one per kind of task.\n\nAny request to DO something to a Go project is a skill, not a shell command\nyou invent. Match the request against that list, call `read_skill` FIRST,\nbefore any bash command, and then follow what it says step by step.\n\nFILE EDITING\nYou have three tools for files: `read_file`, `edit_file` and `write_file`.\nThey are how a file gets read and changed here: each change is exact,\nchecked before it is written, and comes back as a diff with line numbers.\nbash is for running things — building, testing, listing, searching.\n\n- Read before you write: call `read_file` on the file (numbered=true when\n you need line numbers). You cannot target text you have not seen; never\n rely on what you think you remember about a file.\n- To change an existing file, call `edit_file` with one or more {old, new}\n pairs. `old` is copied from the file character for character — same\n spaces, same indentation, same line breaks — and appears exactly once:\n add the surrounding lines until it is unique. Several pairs are applied\n together, against the original file. An empty `new` deletes the text.\n- Call `write_file` only to create a file, or to rewrite one entirely and\n on purpose. On an existing file it replaces everything, including what\n you did not intend to touch.\n- Read the diff the tool returns: it says exactly what changed and on which\n line. If `edit_file` refuses — text not found, ambiguous, overlapping\n edits — read the file again and fix `old`. Do not fall back to\n `write_file` to force the change through.\n- After editing code, run the narrowest check with bash: the formatter, the\n compiler, or the test covering that file.\n\nRULES\n- Keep everything the file already does, unless the user asked to remove it.\n- Touch only the files the request is about. Do not add tests, files or\n features that were not asked for.\n- Never run a git command unless the user says git, commit or push.\n- Never move, rename or delete a file unless the user asked for it.\n- Then answer in English, in a few lines.\n- If you don't know how to use a \u003ccli\u003e, run `\u003ccli\u003e --help` (or `\u003ccli\u003e help`)\n to understand the options, then run the command.\n\nBACKGROUND JOBS\nNever let a command block the answer. Anything that serves, watches or runs\nlong goes to the background, with BOTH streams redirected and its pid kept:\n\n nohup \u003ccommand\u003e \u003e /tmp/\u003cjob\u003e.log 2\u003e\u00261 \u0026 echo $! \u003e /tmp/\u003cjob\u003e.pid\n\nRedirecting only stdout still blocks until the process exits. Read the\n`bg-jobs` skill before you wait on, inspect or stop such a job — each has a\nrule you cannot guess. Stop every job you started before you finish, and say\nwhich ones you left running.\n" | ||
| 13 | + } | ||
| 14 | + ], | ||
| 15 | + "role": "system" | ||
| 16 | + }, | ||
| 17 | + { | ||
| 18 | + "content": [ | ||
| 19 | + { | ||
| 20 | + "text": "show me the content of my home directory" | ||
| 21 | + } | ||
| 22 | + ], | ||
| 23 | + "role": "user" | ||
| 24 | + }, | ||
| 25 | + { | ||
| 26 | + "content": [ | ||
| 27 | + { | ||
| 28 | + "toolRequest": { | ||
| 29 | + "input": { | ||
| 30 | + "command": "ls -a ~" | ||
| 31 | + }, | ||
| 32 | + "name": "bash", | ||
| 33 | + "ref": "EOpI6sOss0z1JdTvCVmWvQ2OaB6mwBOj" | ||
| 34 | + } | ||
| 35 | + } | ||
| 36 | + ], | ||
| 37 | + "role": "model" | ||
| 38 | + }, | ||
| 39 | + { | ||
| 40 | + "content": [ | ||
| 41 | + { | ||
| 42 | + "toolResponse": { | ||
| 43 | + "name": "bash", | ||
| 44 | + "output": ".\n..\n.bash_profile\n.bashrc\n.cache\n.config\n.docker\n.gitconfig\n.gitignore_global\n.local\ngo\nworkspace\n", | ||
| 45 | + "ref": "EOpI6sOss0z1JdTvCVmWvQ2OaB6mwBOj" | ||
| 46 | + } | ||
| 47 | + } | ||
| 48 | + ], | ||
| 49 | + "role": "tool" | ||
| 50 | + }, | ||
| 51 | + { | ||
| 52 | + "content": [ | ||
| 53 | + { | ||
| 54 | + "text": "The content of your home directory includes the following items:\n\n```\n.\n..\n.bash_profile\n.bashrc\n.cache\n.config\n.docker\n.gitconfig\n.gitignore_global\n.local\ngo\nworkspace\n```" | ||
| 55 | + } | ||
| 56 | + ], | ||
| 57 | + "role": "model" | ||
| 58 | + }, | ||
| 59 | + { | ||
| 60 | + "content": [ | ||
| 61 | + { | ||
| 62 | + "text": "de quoi parle ce document\n\nAttached (paths relative to the working directory):\n- petits-llms.adoc\n[attached file: /Users/k33g/kDrive/Rickub/bots-garden/sidekick/demo/petits-llms.adoc]" | ||
| 63 | + } | ||
| 64 | + ], | ||
| 65 | + "role": "user" | ||
| 66 | + }, | ||
| 67 | + { | ||
| 68 | + "content": [ | ||
| 69 | + { | ||
| 70 | + "toolRequest": { | ||
| 71 | + "input": { | ||
| 72 | + "path": "petits-llms.adoc" | ||
| 73 | + }, | ||
| 74 | + "name": "read_file", | ||
| 75 | + "ref": "Iw7fgi686TpxGWVnKVJWYiPf3JotKzNi" | ||
| 76 | + } | ||
| 77 | + } | ||
| 78 | + ], | ||
| 79 | + "role": "model" | ||
| 80 | + }, | ||
| 81 | + { | ||
| 82 | + "content": [ | ||
| 83 | + { | ||
| 84 | + "toolResponse": { | ||
| 85 | + "name": "read_file", | ||
| 86 | + "output": "= Mini Me et les petits LLMs\n:toc: left\n:toclevels: 2\n:toc-title: Sommaire\n:sectnums:\n:icons: font\n:source-highlighter: rouge\n:lang: fr\n:revdate: 2026-09-26\n\n[abstract]\nMini Me (`mm`) a été conçu pour tourner avec des modèles *locaux* — typiquement 2 à 12 milliards de paramètres servis par Docker Model Runner ou llama-server.\nCe document relève, dans l'implémentation, ce qui rend l'agent utilisable avec ces modèles, puis propose des pistes d'amélioration chiffrées en *effort* et en *résultat attendu*.\n\n== Le point de départ : ce qu'un petit modèle fait mal\n\nTout le code de `mm` se lit comme une réponse à une liste de défaillances observées (souvent datées et mesurées dans les commentaires) :\n\n[cols=\"1,2\",options=\"header\"]\n|===\n| Défaillance | Manifestation typique\n\n| Hallucination\n| Le modèle « cite » un fichier ou une sortie de commande qu'il n'a jamais lus.\n\n| Imprécision sur les octets\n| Il retape un bloc à éditer avec des espaces là où le fichier a des tabulations, ou ajoute une ligne vide.\n\n| Boucles\n| Il répète le même appel refusé — trente fois, observé le 18/09/2026 avec un modèle 12B.\n\n| Déraillement en cours de génération\n| Il compose des arguments d'outil qui se répètent pendant des minutes (`\"Greet 2023-06-15 11:16:00 …\"`).\n\n| Appel d'outil trop long\n| Il écrit tout un document dans un seul `write_file`, qui dépasse `max_tokens` et arrive coupé (observé le 26/09/2026).\n\n| Raisonnement long\n| Un modèle « thinking » réfléchit 38 s sans émettre un octet de contenu.\n\n| Petite fenêtre de contexte\n| La fenêtre est fixée au chargement du modèle ; une session longue finit en « stalled » puis en erreur 400.\n\n| Routage faible\n| Il ne relie pas « salue Bob » à la procédure nommée `greetings`.\n|===\n\nL'idée directrice : *ne pas demander au modèle ce que le code peut garantir*, et quand le modèle se trompe, *lui rendre une information exploitable plutôt qu'un échec muet*.\n\n== Une surface d'outils petite, configurable et explicite\n\n=== Bash d'abord, peu d'outils\n\nL'agent est né autour d'un seul outil, `bash` (`internal/tools/tools.go`). Les autres sont optionnels et désactivables un par un dans le YAML : `bashTool`, `editTools` (`read_file`, `write_file`, `edit_file`), `planTool`. Deux outils ne sont déclarés *que s'ils servent* :\n\n* `read_skill` n'existe pas si `skillsDir` ne contient aucun `.md` ;\n* `lsp` n'existe pas si aucun serveur de langage n'est configuré *et* présent dans le `PATH`.\n\nChaque outil déclaré coûte des tokens à chaque requête et une option de plus parmi lesquelles un petit modèle doit choisir. Moins il y en a, mieux il choisit.\n\n=== Des descriptions écrites pour être suivies\n\nLes descriptions d'outils ne décrivent pas seulement l'API, elles anticipent les erreurs :\n\n* `bash` : « Each call starts a NEW shell … a \"cd\" does not carry over », « there is no stdin, so never use a command that asks a question », « Read before you write ».\n* `read_file` : « edit_file needs the EXACT text of the file … Do not type it from memory. »\n* `edit_file` : six règles *numérotées*, dont « do not switch to write_file to force the change through ».\n* `write_file` : rappelle qu'il écrase tout et renvoie vers `edit_file`.\n\nLe prompt système des configurations livrées (`agent.dmr.yaml`, `agent.llamacpp.yaml`) répète ces règles en sections courtes en majuscules (`SKILLS`, `FILE EDITING`, `RULES`, `BACKGROUND JOBS`). La redondance est voulue : un petit modèle suit mieux une consigne qu'il lit deux fois, à deux endroits.\n\n=== Un échantillonnage conservateur\n\nLes valeurs par défaut (`internal/config/config.go`) et les YAML livrés fixent `temperature: 0.0`, `top_p: 0.9`, `max_tokens: 4096` et `parallel_tool_calls: false`. Un seul appel d'outil à la fois est plus simple à produire correctement pour un petit modèle, et plus lisible dans l'historique.\n\n== Le contrat des outils : un échec est du texte\n\nC'est le principe structurant, énoncé en tête de `internal/tools/tools.go` :\n\n[quote]\nWe NEVER return a Go `error` for a \"normal\" failure. The error goes back AS TEXT, so that the model reads it and reacts.\n\nCommande en échec (`[exit code: …]`), délai dépassé (`[error: 30s timeout exceeded]`), fichier absent (« Create it with write_file »), édition ambiguë : tout revient au modèle comme résultat d'outil. Une erreur Go terminerait le tour et le modèle n'aurait aucune chance de se corriger.\n\nLes messages sont rédigés comme des *consignes de réparation* :\n\n* `read_skill` avec un nom inconnu répond `[skill: no skill named \"x\" — available: a, b, c]` ;\n* `edit_file` avec un texte en double donne les numéros de ligne des occurrences et explique comment rendre `old` unique (`internal/fileedit/edits.go`).\n\nLa seule exception est volontaire : l'arrêt par le détecteur de boucle (voir \u003c\u003cboucles\u003e\u003e).\n\nCertaines erreurs échappent pourtant aux outils, parce qu'elles se produisent *avant* eux, dans Genkit. C'est le cas d'un appel dont les arguments ne sont pas du JSON valide : il est désormais rendu au modèle lui aussi (voir \u003c\u003cargs\u003e\u003e). Les erreurs de validation de schéma et les noms d'outils inventés restent à traiter (pistes \u003c\u003cp1\u003e\u003e et \u003c\u003cp2\u003e\u003e).\n\n== Une édition de fichiers tolérante, mais sûre\n\n`internal/fileedit` est probablement la partie la plus « petits modèles » du code.\n\n=== Trois passes de correspondance, de la plus stricte à la plus souple\n\n`findAll` (`internal/fileedit/match.go`) cherche `old` :\n\n. *exactement* ;\n. en ignorant les *bords* (ligne vide au début, indentation d'une ligne unique, ligne vide finale) ;\n. en ignorant l'*indentation* ligne par ligne, pour un bloc de plusieurs lignes.\n\nLa première passe qui trouve quelque chose l'emporte : un texte présent tel quel n'est jamais apparié autrement. La souplesse ne s'active que là où la règle stricte a déjà échoué — typiquement le « ticket 27 », des espaces envoyés pour un fichier Go indenté par tabulations.\n\n=== Ce qui n'est *pas* relâché\n\n* *L'unicité* : deux correspondances souples sont refusées exactement comme deux correspondances exactes.\n* *L'indentation du fichier* : `reindent` (`internal/fileedit/indent.go`) réécrit `new` dans l'indentation du fichier (niveau de base *et* unité, quatre espaces devenant une tabulation), pour ne pas insérer un bloc d'espaces dans un fichier à tabulations.\n* *La transparence* : le résumé signale « N matched ignoring whitespace », pour que le modèle recopie mieux la fois suivante.\n\n=== Un « not found » qui aide\n\n`notFound` + `nearest` montrent les lignes du fichier qui s'en approchent le plus (au moins la moitié des lignes doivent coïncider), avec leurs numéros : « copy these lines ». Un modèle à qui l'on dit seulement « introuvable » retape le même texte ; un modèle à qui l'on montre le bon texte le recopie.\n\n=== Des détails invisibles neutralisés\n\n`internal/fileedit/textfile.go` retire le BOM UTF-8 et convertit les fins de ligne CRLF avant l'édition, puis les restaure. Sans cela, *chaque* `old` multi-ligne écrit avec `\\n` par un modèle échouerait sur un fichier Windows.\n\nS'y ajoutent `dry_run`, des modifications résolues toutes contre le fichier *original* (pas d'effets de bord entre modifications), le refus des chevauchements, et un diff numéroté en retour, qui sert de preuve au modèle.\n\n== Contre l'hallucination : montrer, puis seulement commenter\n\n* *La sortie est affichée avant que le modèle la voie.* `echoOutput` (`internal/tools/tools.go`) montre les `previewLines` premières lignes à l'utilisateur. Observé : sur « affiche agent.yaml », le modèle lançait `cat`, jugeait la demande satisfaite, et l'utilisateur ne voyait rien.\n* *Le prompt interdit d'affirmer sans preuve* : « Never state the contents of a file … unless a command in THIS answer returned it. »\n* *Les pièces jointes sont des chemins, pas du contenu* : `@chemin` (`internal/mention`) et le `resource_link` ACP deviennent `[attached file: /abs/path]`. Le modèle doit lire le fichier avec ses outils, et la lecture est visible.\n* *L'historique complet est conservé même quand un tour échoue* (`session.AfterTurn`). Genkit ne renvoie que le dernier message ; `engine.Generate` capture la conversation entière via un middleware `WrapModel`. Sans cela, le modèle réinvente au tour suivant les commandes qu'il a déjà lancées.\n\n[[boucles]]\n== Garde-fous contre les boucles et les blocages\n\nQuatre mécanismes, du plus doux au plus radical :\n\n[cols=\"1,2,1\",options=\"header\"]\n|===\n| Mécanisme | Déclencheur | Réaction\n\n| Détecteur de boucle, niveau 1 (`internal/detector`)\n| Même triplet (outil, entrée, sortie) 3 fois de suite\n| `[LOOP_DETECTED: … try a different approach]` ajouté à la sortie\n\n| Détecteur, niveau 2\n| 3 répétitions supplémentaires malgré l'avertissement\n| Erreur Go `Stuck` : fin du tour, pas de nouvelle tentative, enregistrée dans la session\n\n| Garde des arguments (`internal/engine/runaway.go`)\n| Arguments d'outil en streaming périodiques (motif de 4 à 64 octets sur les 256 derniers) ou \u003e 256 Kio\n| Génération interrompue immédiatement, avec un message explicite\n\n| Watchdog (`engine.watchdog`)\n| Aucun token depuis `watchdogTimeout`\n| Annulation : « stalled »\n|===\n\nPlusieurs choix fins méritent d'être notés :\n\n* Le détecteur n'est *pas* remis à zéro par `/compact` (oublier la conversation ne rend pas nouvelle une commande répétée), mais il l'est par `/new`.\n* La relance sans streaming n'a lieu *que* si rien n'a été affiché et qu'aucun outil n'a tourné. Sinon, rejouer le tour rejouerait les commandes (mesuré : un `echo \u003e\u003e` écrit deux fois).\n* Le spinner indique « Composing a tool call » : un utilisateur sait que le modèle travaille, et non qu'il est bloqué.\n* `maxTurns` borne les allers-retours modèle ↔ outils (10 par défaut, 40 dans `agent.dmr.yaml`).\n* `bash` a son propre budget de 30 s et écrit dans un fichier temporaire plutôt que dans un pipe, pour qu'un job lancé en arrière-plan sans redirection ne bloque pas le tour indéfiniment (ticket 26). Le prompt et le skill `bg-jobs` apprennent au modèle la bonne forme `nohup … \u003e log 2\u003e\u00261 \u0026`.\n\n[[args]]\n== Appels d'outils coupés ou mal formés\n\n=== Le cas qui l'a motivé\n\nSession du 26/09/2026, Qwen3 27B servi par llama-server, `max_tokens: 4096`. On demande au modèle d'écrire un document. Il explore le dossier (trois `bash`, deux `read_file`), puis compose un seul `write_file` avec tout le document : ≈ 12 500 caractères, soit ≈ 4 000 tokens. Le serveur coupe la génération à la limite (`finish_reason: \"length\"`), en pleine phrase.\n\nLe greffon OpenAI de Genkit décode les arguments en convertissant la réponse du serveur (`compat_oai/generate.go` : `could not parse tool args: … unexpected end of JSON input`). Cette erreur *termine la génération*. Le modèle ne la lit jamais, et l'utilisateur voyait comme message d'erreur le document tronqué en entier.\n\nDeux causes se cumulent, typiques des modèles locaux :\n\n* un petit modèle veut tout faire en un appel, même quand le résultat est long ;\n* avec un modèle « thinking », le raisonnement consomme aussi le budget `max_tokens`.\n\n=== Ce que fait `mm`\n\n`internal/engine/toolargs.go`, branché dans le hook `WrapModel` de `engine.Generate` :\n\n. Deux cas sont reconnus : un JSON *coupé* (`unexpected end of JSON input`) et un JSON *mal formé*.\n. L'appel est rendu au modèle, deux fois au plus par génération. `mm` ajoute une note à la conversation, puis relance l'appel au modèle. Dans le cas coupé, la note donne un budget chiffré : « écris seulement la première partie (≈ 6 000 caractères au plus pour 4 096 tokens), puis ajoute la suite avec `edit_file` ».\n. La note est ajoutée au `ModelRequest` que Genkit réutilise pour les tours suivants. Elle reste donc dans la conversation, et le modèle la relit en écrivant la partie suivante.\n. La relance sans streaming n'est pas tentée pour cette erreur : la même limite couperait le même appel.\n. Une fois les deux tentatives épuisées, `Explain` donne une ligne exploitable au lieu du JSON : « the model hit max_tokens (4096) while writing a tool call … raise sampling.max_tokens … ».\n\n=== Ce que la mesure a montré\n\nTest réel sur Docker Model Runner avec Mellum 12B, `max_tokens` volontairement réduit à 300 puis 800 :\n\n* le mécanisme fonctionne : le modèle reprend la main deux fois, puis le message clair s'affiche ;\n* *le modèle a ignoré la consigne* les deux fois et a retenté le fichier entier, même avec un budget chiffré en caractères.\n\nLa relance rend l'échec lisible et laisse une chance aux modèles qui suivent les instructions. Elle ne remplace pas un `max_tokens` adapté : 16 384 est une valeur raisonnable pour un modèle « thinking », avec une marge sous la fenêtre de contexte. Voir aussi la piste \u003c\u003cp15\u003e\u003e.\n\n== Modèles à raisonnement\n\nLe greffon OpenAI de Genkit ignore `reasoning_content`. `mm` le lit lui-même, une couche plus bas, via un middleware HTTP qui parcourt le flux SSE sans le modifier (`internal/engine/reasoning.go`). Deux effets :\n\n* *Le watchdog reste alimenté* pendant que le modèle réfléchit ; sans cela, `qwen3.5-2b` était tué après 38 s de raisonnement légitime.\n* Le raisonnement est *affiché* (bloc 💭, `agent_thought_chunk` en ACP) mais *n'entre jamais dans l'historique* : il ne consomme pas le contexte des tours suivants.\n\n== Le contexte : une ressource rare\n\n=== Des sorties bornées\n\n`truncate` limite chaque sortie d'outil à `maxOutput` caractères en conservant *le début et la fin* (la fin porte souvent l'erreur ou le résumé d'une commande). `bash` ne relit jamais plus d'1 Mio par extrémité depuis le disque.\n\n=== Une compression hybride\n\n`internal/compact` remplace les vieux tours par *un* résumé écrit par le modèle et garde les `keepLastTurns` derniers tours intacts (le modèle travaille sur eux). Points notables :\n\n* un résumé précédent est *fusionné*, pas résumé à nouveau (le détail décroîtrait exponentiellement) ;\n* la requête de résumé est envoyée *sans outils* (un petit modèle à qui l'on offre des outils les appelle au lieu d'écrire) et avec un watchdog deux fois plus patient ;\n* le déclencheur prend le maximum entre l'estimation locale et le compte du serveur, et se replie sur un\n\n[... 14660 characters truncated ...]\n\nons.\n\n[[p15]]\n=== Réponses coupées par `max_tokens`\n\n*Constat.* Le cas d'un *appel d'outil* coupé est traité (\u003c\u003cargs\u003e\u003e). Une *réponse texte* coupée ne l'est pas : la génération s'arrête avec `finish_reason: \"length\"`, et `mm` l'affiche comme une réponse complète. L'utilisateur lit une phrase inachevée sans savoir pourquoi. La mesure montre aussi que la consigne « procède par morceaux » arrive trop tard, une fois l'appel déjà coupé.\n\n*Proposition.*\n\n* Lire `FinishReason` dans `WrapModel` (Genkit le transmet : `FinishReasonLength`) et, pour une réponse texte, ajouter `[answer cut off at max_tokens (N)]`, avec le même conseil que pour les appels d'outils.\n* *Prévenir* plutôt que guérir : une phrase dans la description de `write_file` (« pour un fichier de plus de ≈ N caractères, écris la première partie puis complète avec edit_file »), avec N calculé à partir de `max_tokens`.\n* Au démarrage, avertir quand `max_tokens` est bas pour un modèle à raisonnement (le raisonnement consomme le même budget).\n\n*Effort : faible.* *Résultat : moyen* — plus de réponses tronquées en silence ; l'effet de la consigne préventive reste à mesurer avec la piste \u003c\u003cp12\u003e\u003e.\n\n== Références dans le code\n\n[cols=\"1,2\",options=\"header\"]\n|===\n| Sujet | Fichiers\n\n| Contrat des outils, `bash`, troncature | `internal/tools/tools.go`\n| Outils fichiers | `internal/tools/files.go`, `internal/fileedit/`\n| Détecteur de boucle | `internal/detector/detector.go`\n| Arguments qui s'emballent | `internal/engine/runaway.go`\n| Watchdog, relance, historique complet | `internal/engine/engine.go`\n| Raisonnement | `internal/engine/reasoning.go`, `internal/engine/thoughts.go`\n| Usage en streaming | `internal/engine/usage.go`\n| Appels d'outils coupés ou mal formés | `internal/engine/toolargs.go`\n| Compression | `internal/compact/`\n| Skills et catalogue | `internal/skills/`, `skills/`\n| Évaluation du routage | `internal/eval/`\n| Explications d'erreurs | `internal/engine/explain.go`, `internal/engine/openai_compat.go`\n|===\n", | ||
| 87 | + "ref": "Iw7fgi686TpxGWVnKVJWYiPf3JotKzNi" | ||
| 88 | + } | ||
| 89 | + } | ||
| 90 | + ], | ||
| 91 | + "role": "tool" | ||
| 92 | + }, | ||
| 93 | + { | ||
| 94 | + "content": [ | ||
| 95 | + { | ||
| 96 | + "text": "Ce document, intitulé \"Mini Me et les petits LLMs\", est une analyse technique détaillée de l'agent `Mini Me` (`mm`), conçu pour fonctionner spécifiquement avec des **modèles de langage locaux de petite taille** (2 à 12 milliards de paramètres).\n\nIl expose les choix d'implémentation faits pour pallier les faiblesses typiques de ces petits modèles (comme les hallucinations, les boucles, l'imprécision ou les fenêtres de contexte limitées).\n\nLes points principaux abordés sont :\n\n* **La conception des outils :** Un ensemble d'outils minimal, explicite et bien documenté est utilisé, où les descriptions prévoient les erreurs.\n* **La gestion des erreurs :** Le principe fondamental est que tout échec est retourné **sous forme de texte** au modèle pour qu'il puisse se corriger lui-même, plutôt qu'un échec technique qui mettrait fin au tour.\n* **La robustesse des fichiers :** Le module d'édition de fichiers est conçu pour être tolérant aux variations d'espacement tout en garantissant l'unicité de la correspondance.\n* **Les garde-fous :** Des mécanismes sont en place pour empêcher les boucles infinies, les arguments incontrôlables (`runaway`), et pour gérer les réponses coupées par la limite de tokens (`max_tokens`).\n\nEn résumé, c'est un document sur les *meilleures pratiques* et les *mécanismes de sécurité* pour faire fonctionner un agent IA de manière fiable en utilisant des modèles locaux et peu performants." | ||
| 97 | + } | ||
| 98 | + ], | ||
| 99 | + "role": "model" | ||
| 100 | + } | ||
| 101 | + ] | ||
| 102 | +} | ||
| \ No newline at end of file | \ No newline at end of file | ||
added
demo/.mm/sessions/20260928-065106-c5f208f4.json +18 -0 | new file mode 100644 | ||
| @@ -0,0 +1,18 @@ | ||
| 1 | +{ | |
| 2 | + "id": "20260928-065106-c5f208f4", | |
| 3 | + "cwd": "/Users/k33g/kDrive/Rickub/bots-garden/sidekick/demo", | |
| 4 | + "provider": "dmr", | |
| 5 | + "model": "huggingface.co/unsloth/gemma-4-e4b-it-gguf:Q4_K_M", | |
| 6 | + "createdAt": "2026-09-28T06:51:06.756781794Z", | |
| 7 | + "updatedAt": "2026-09-28T06:51:06.756865961Z", | |
| 8 | + "messages": [ | |
| 9 | + { | |
| 10 | + "content": [ | |
| 11 | + { | |
| 12 | + "text": "Your name is Bob.\nYou are a coding agent working in a terminal.\nYou have a \"bash\" tool to run shell commands.\nUse it to explore files, run tests, inspect the repository, etc.\nChain several commands if needed, then answer clearly in English.\n\nA request often mixes things you answer from yourself (\"say hello\") with\nthings only a command can answer (\"list the files\"). Handle every part, in\nthe order asked, and run a command for each part that needs one.\nNever state the contents of a file, the output of a command, or the state of\nthe repository unless a command in THIS answer returned it. What you did not\nread, you do not know: run the command instead of recalling it.\n\nSKILLS\nYou have a second tool, `read_skill`. Its description lists the procedures\navailable for this project — one per kind of task.\n\nAny request to DO something to a Go project is a skill, not a shell command\nyou invent. Match the request against that list, call `read_skill` FIRST,\nbefore any bash command, and then follow what it says step by step.\n\nFILE EDITING\nYou have three tools for files: `read_file`, `edit_file` and `write_file`.\nThey are how a file gets read and changed here: each change is exact,\nchecked before it is written, and comes back as a diff with line numbers.\nbash is for running things — building, testing, listing, searching.\n\n- Read before you write: call `read_file` on the file (numbered=true when\n you need line numbers). You cannot target text you have not seen; never\n rely on what you think you remember about a file.\n- To change an existing file, call `edit_file` with one or more {old, new}\n pairs. `old` is copied from the file character for character — same\n spaces, same indentation, same line breaks — and appears exactly once:\n add the surrounding lines until it is unique. Several pairs are applied\n together, against the original file. An empty `new` deletes the text.\n- Call `write_file` only to create a file, or to rewrite one entirely and\n on purpose. On an existing file it replaces everything, including what\n you did not intend to touch.\n- Read the diff the tool returns: it says exactly what changed and on which\n line. If `edit_file` refuses — text not found, ambiguous, overlapping\n edits — read the file again and fix `old`. Do not fall back to\n `write_file` to force the change through.\n- After editing code, run the narrowest check with bash: the formatter, the\n compiler, or the test covering that file.\n\nRULES\n- Keep everything the file already does, unless the user asked to remove it.\n- Touch only the files the request is about. Do not add tests, files or\n features that were not asked for.\n- Never run a git command unless the user says git, commit or push.\n- Never move, rename or delete a file unless the user asked for it.\n- Then answer in English, in a few lines.\n- If you don't know how to use a \u003ccli\u003e, run `\u003ccli\u003e --help` (or `\u003ccli\u003e help`)\n to understand the options, then run the command.\n\nBACKGROUND JOBS\nNever let a command block the answer. Anything that serves, watches or runs\nlong goes to the background, with BOTH streams redirected and its pid kept:\n\n nohup \u003ccommand\u003e \u003e /tmp/\u003cjob\u003e.log 2\u003e\u00261 \u0026 echo $! \u003e /tmp/\u003cjob\u003e.pid\n\nRedirecting only stdout still blocks until the process exits. Read the\n`bg-jobs` skill before you wait on, inspect or stop such a job — each has a\nrule you cannot guess. Stop every job you started before you finish, and say\nwhich ones you left running.\n" | |
| 13 | + } | |
| 14 | + ], | |
| 15 | + "role": "system" | |
| 16 | + } | |
| 17 | + ] | |
| 18 | +} | |
| \ No newline at end of file | ||
| new file mode 100644 | |||
| @@ -0,0 +1,18 @@ | |||
| 1 | +{ | ||
| 2 | + "id": "20260928-065106-c5f208f4", | ||
| 3 | + "cwd": "/Users/k33g/kDrive/Rickub/bots-garden/sidekick/demo", | ||
| 4 | + "provider": "dmr", | ||
| 5 | + "model": "huggingface.co/unsloth/gemma-4-e4b-it-gguf:Q4_K_M", | ||
| 6 | + "createdAt": "2026-09-28T06:51:06.756781794Z", | ||
| 7 | + "updatedAt": "2026-09-28T06:51:06.756865961Z", | ||
| 8 | + "messages": [ | ||
| 9 | + { | ||
| 10 | + "content": [ | ||
| 11 | + { | ||
| 12 | + "text": "Your name is Bob.\nYou are a coding agent working in a terminal.\nYou have a \"bash\" tool to run shell commands.\nUse it to explore files, run tests, inspect the repository, etc.\nChain several commands if needed, then answer clearly in English.\n\nA request often mixes things you answer from yourself (\"say hello\") with\nthings only a command can answer (\"list the files\"). Handle every part, in\nthe order asked, and run a command for each part that needs one.\nNever state the contents of a file, the output of a command, or the state of\nthe repository unless a command in THIS answer returned it. What you did not\nread, you do not know: run the command instead of recalling it.\n\nSKILLS\nYou have a second tool, `read_skill`. Its description lists the procedures\navailable for this project — one per kind of task.\n\nAny request to DO something to a Go project is a skill, not a shell command\nyou invent. Match the request against that list, call `read_skill` FIRST,\nbefore any bash command, and then follow what it says step by step.\n\nFILE EDITING\nYou have three tools for files: `read_file`, `edit_file` and `write_file`.\nThey are how a file gets read and changed here: each change is exact,\nchecked before it is written, and comes back as a diff with line numbers.\nbash is for running things — building, testing, listing, searching.\n\n- Read before you write: call `read_file` on the file (numbered=true when\n you need line numbers). You cannot target text you have not seen; never\n rely on what you think you remember about a file.\n- To change an existing file, call `edit_file` with one or more {old, new}\n pairs. `old` is copied from the file character for character — same\n spaces, same indentation, same line breaks — and appears exactly once:\n add the surrounding lines until it is unique. Several pairs are applied\n together, against the original file. An empty `new` deletes the text.\n- Call `write_file` only to create a file, or to rewrite one entirely and\n on purpose. On an existing file it replaces everything, including what\n you did not intend to touch.\n- Read the diff the tool returns: it says exactly what changed and on which\n line. If `edit_file` refuses — text not found, ambiguous, overlapping\n edits — read the file again and fix `old`. Do not fall back to\n `write_file` to force the change through.\n- After editing code, run the narrowest check with bash: the formatter, the\n compiler, or the test covering that file.\n\nRULES\n- Keep everything the file already does, unless the user asked to remove it.\n- Touch only the files the request is about. Do not add tests, files or\n features that were not asked for.\n- Never run a git command unless the user says git, commit or push.\n- Never move, rename or delete a file unless the user asked for it.\n- Then answer in English, in a few lines.\n- If you don't know how to use a \u003ccli\u003e, run `\u003ccli\u003e --help` (or `\u003ccli\u003e help`)\n to understand the options, then run the command.\n\nBACKGROUND JOBS\nNever let a command block the answer. Anything that serves, watches or runs\nlong goes to the background, with BOTH streams redirected and its pid kept:\n\n nohup \u003ccommand\u003e \u003e /tmp/\u003cjob\u003e.log 2\u003e\u00261 \u0026 echo $! \u003e /tmp/\u003cjob\u003e.pid\n\nRedirecting only stdout still blocks until the process exits. Read the\n`bg-jobs` skill before you wait on, inspect or stop such a job — each has a\nrule you cannot guess. Stop every job you started before you finish, and say\nwhich ones you left running.\n" | ||
| 13 | + } | ||
| 14 | + ], | ||
| 15 | + "role": "system" | ||
| 16 | + } | ||
| 17 | + ] | ||
| 18 | +} | ||
| \ No newline at end of file | \ No newline at end of file | ||
added
demo/mm-acp.sbx.sh +5 -0 | new file mode 100755 | ||
| @@ -0,0 +1,5 @@ | ||
| 1 | +#!/bin/sh | |
| 2 | +# Agent for sidekick: runs mm inside the mm-acp sandbox. | |
| 3 | +# sidekick calls its agent as `<agent> --acp [args...]`, so every argument | |
| 4 | +# (--acp included) is handed to mm, not to sbx. | |
| 5 | +exec sbx exec -i "${SBX_NAME:-mm-acp}" mm "$@" | |
| new file mode 100755 | |||
| @@ -0,0 +1,5 @@ | |||
| 1 | +#!/bin/sh | ||
| 2 | +# Agent for sidekick: runs mm inside the mm-acp sandbox. | ||
| 3 | +# sidekick calls its agent as `<agent> --acp [args...]`, so every argument | ||
| 4 | +# (--acp included) is handed to mm, not to sbx. | ||
| 5 | +exec sbx exec -i "${SBX_NAME:-mm-acp}" mm "$@" | ||
added
demo/start.sbx.sh +21 -0 | new file mode 100755 | ||
| @@ -0,0 +1,21 @@ | ||
| 1 | +#!/bin/bash | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | +sidekick -port 9000 sbx exec -i sidekick-acp mm -acp | |
| 6 | + | |
| 7 | + | |
| 8 | +sbx run k33g/sbx-kit-mm-tui:0.2.2 . ../mini-me-config:ro -- ../mini-me-config/sbx.agent.little.gemma.yaml | |
| 9 | + | |
| 10 | +# window mode sbx run k33g/sbx-kit-mm-tui:0.2.2 . -- agent.dmr.yaml | |
| 11 | +# editor (ACP) sbx create --name mm-acp k33g/sbx-kit-mm-acp:0.2.2 . --kit-arg config=agent.dmr.yaml | |
| 12 | +# then register sbx exec -i mm-acp mm -acp in the editor | |
| 13 | + | |
| 14 | +sbx create --name mm-acp k33g/sbx-kit-mm-acp:0.2.2 . ../mini-me-config:ro \ | |
| 15 | + --kit-arg config=../mini-me-config/sbx.agent.little.gemma.yaml | |
| 16 | + | |
| 17 | + | |
| 18 | +sidekick -port 9000 ./mm-acp.sbx.sh | |
| 19 | + | |
| 20 | +# Pour une autre sandbox, tu peux changer le nom : | |
| 21 | +# SBX_NAME=autre-sandbox sidekick -port 9000 ./mm-acp.sbx.sh. | |
| new file mode 100755 | |||
| @@ -0,0 +1,21 @@ | |||
| 1 | +#!/bin/bash | ||
| 2 | + | ||
| 3 | + | ||
| 4 | + | ||
| 5 | +sidekick -port 9000 sbx exec -i sidekick-acp mm -acp | ||
| 6 | + | ||
| 7 | + | ||
| 8 | +sbx run k33g/sbx-kit-mm-tui:0.2.2 . ../mini-me-config:ro -- ../mini-me-config/sbx.agent.little.gemma.yaml | ||
| 9 | + | ||
| 10 | +# window mode sbx run k33g/sbx-kit-mm-tui:0.2.2 . -- agent.dmr.yaml | ||
| 11 | +# editor (ACP) sbx create --name mm-acp k33g/sbx-kit-mm-acp:0.2.2 . --kit-arg config=agent.dmr.yaml | ||
| 12 | +# then register sbx exec -i mm-acp mm -acp in the editor | ||
| 13 | + | ||
| 14 | +sbx create --name mm-acp k33g/sbx-kit-mm-acp:0.2.2 . ../mini-me-config:ro \ | ||
| 15 | + --kit-arg config=../mini-me-config/sbx.agent.little.gemma.yaml | ||
| 16 | + | ||
| 17 | + | ||
| 18 | +sidekick -port 9000 ./mm-acp.sbx.sh | ||
| 19 | + | ||
| 20 | +# Pour une autre sandbox, tu peux changer le nom : | ||
| 21 | +# SBX_NAME=autre-sandbox sidekick -port 9000 ./mm-acp.sbx.sh. | ||
modified
mini-me-config/agent.little.gemma.yaml +1 -1 | @@ -1,6 +1,6 @@ | ||
| 1 | 1 | # Agent settings. |
| 2 | 2 | # |
| 3 | -#provider: dmr | |
| 3 | +provider: dmr | |
| 4 | 4 | |
| 5 | 5 | #model: huggingface.co/jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M |
| 6 | 6 | #model: huggingface.co/unsloth/gemma-4-26b-a4b-it-gguf:UD-Q4_K_M |
| @@ -1,6 +1,6 @@ | |||
| 1 | # Agent settings. | 1 | # Agent settings. |
| 2 | # | 2 | # |
| 3 | -#provider: dmr | 3 | +provider: dmr |
| 4 | 4 | ||
| 5 | #model: huggingface.co/jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M | 5 | #model: huggingface.co/jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M |
| 6 | #model: huggingface.co/unsloth/gemma-4-26b-a4b-it-gguf:UD-Q4_K_M | 6 | #model: huggingface.co/unsloth/gemma-4-26b-a4b-it-gguf:UD-Q4_K_M |
added
mini-me-config/sbx.agent.little.gemma.yaml +189 -0 | new file mode 100644 | ||
| @@ -0,0 +1,189 @@ | ||
| 1 | +# Agent settings. | |
| 2 | +# | |
| 3 | +provider: dmr | |
| 4 | + | |
| 5 | +#model: huggingface.co/jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M | |
| 6 | +#model: huggingface.co/unsloth/gemma-4-26b-a4b-it-gguf:UD-Q4_K_M | |
| 7 | +#model: huggingface.co/ornith-ai/ornith-1.5-35b-a3b-gguf:Q4_K_M | |
| 8 | +model: huggingface.co/unsloth/gemma-4-e4b-it-gguf:Q4_K_M | |
| 9 | + | |
| 10 | +baseUrl: http://localhost:12434/engines/v1 | |
| 11 | +fallback: http://host.docker.internal:12434/engines/v1 | |
| 12 | + | |
| 13 | +# llama serve -hf unsloth/gemma-4-E2B-it-GGUF:Q4_K_M | |
| 14 | + | |
| 15 | +#provider: llamacpp | |
| 16 | + | |
| 17 | +#model: unsloth/gemma-4-E2B-it-GGUF:Q4_K_M | |
| 18 | + | |
| 19 | +# llama-server's default is 127.0.0.1:8080; the OpenAI routes sit under /v1. | |
| 20 | +#baseUrl: http://127.0.0.1:8080/v1 | |
| 21 | +#baseUrl: http://host.docker.internal:8080/v1 | |
| 22 | + | |
| 23 | + | |
| 24 | +# How many tokens the server actually serves. | |
| 25 | +# 0 = ask the server | |
| 26 | +contextWindow: 0 | |
| 27 | + | |
| 28 | +# Max number of characters a tool returns to the model. | |
| 29 | +# Context safeguard: beyond that, the output is truncated (beginning + end kept). | |
| 30 | +maxOutput: 16000 | |
| 31 | + | |
| 32 | +# Max number of model <-> tools round trips for a single question. | |
| 33 | +# Raise it for tasks that need long chains of commands. | |
| 34 | +maxTurns: 40 | |
| 35 | + | |
| 36 | +# The `bash` tool. | |
| 37 | +# `false` removes it: the model can still read and edit files (editTools) and load skills, | |
| 38 | +# but never runs a command. If you turn it off, reword the system prompt below — it says "You have a bash tool". | |
| 39 | +bashTool: true | |
| 40 | + | |
| 41 | +# The built-in file tools: read_file, write_file, edit_file. | |
| 42 | +editTools: true | |
| 43 | + | |
| 44 | +# Language servers for the `lsp` tool (definition, references, hover, symbols, diagnostics, rename). | |
| 45 | +# The file extension picks the server. A server missing from the PATH is skipped with a warning. | |
| 46 | +# No server listed = no `lsp` tool. Examples (uncomment what you have installed): | |
| 47 | +lsp: | |
| 48 | + servers: | |
| 49 | + - name: gopls | |
| 50 | + command: gopls | |
| 51 | + extensions: [".go"] | |
| 52 | +# - name: typescript | |
| 53 | +# command: typescript-language-server | |
| 54 | +# args: ["--stdio"] | |
| 55 | +# extensions: [".ts", ".tsx", ".js", ".jsx"] | |
| 56 | +# - name: python | |
| 57 | +# command: pyright-langserver | |
| 58 | +# args: ["--stdio"] | |
| 59 | +# extensions: [".py"] | |
| 60 | +# - name: rust | |
| 61 | +# command: rust-analyzer | |
| 62 | +# extensions: [".rs"] | |
| 63 | + | |
| 64 | +# Where the `read_skill` tool looks for its markdown procedures. | |
| 65 | +# The path is relative to the CURRENT DIRECTORY, so run the agent from the directory that holds skills. | |
| 66 | +#skillsDir: skills | |
| 67 | +skillsDir: ../mini-me-config/skills | |
| 68 | + | |
| 69 | +# Persistent sessions, per project. | |
| 70 | +# When enabled, every conversation is saved as one JSON file under `dir` | |
| 71 | +sessions: | |
| 72 | + enabled: true | |
| 73 | + dir: .mm/sessions | |
| 74 | + | |
| 75 | +# How many lines of a command's output are echoed to the terminal. | |
| 76 | +# 0 disables it. | |
| 77 | +previewLines: 20 | |
| 78 | + | |
| 79 | +# The system prompt: what the agent is, and what it is allowed to do. | |
| 80 | +# This is the knob to play with — it is the shortest path to changing behaviour. | |
| 81 | +system: | | |
| 82 | + Your name is Bob. | |
| 83 | + You are a coding agent working in a terminal. | |
| 84 | + You have a "bash" tool to run shell commands. | |
| 85 | + Use it to explore files, run tests, inspect the repository, etc. | |
| 86 | + Chain several commands if needed, then answer clearly in English. | |
| 87 | + | |
| 88 | + A request often mixes things you answer from yourself ("say hello") with | |
| 89 | + things only a command can answer ("list the files"). Handle every part, in | |
| 90 | + the order asked, and run a command for each part that needs one. | |
| 91 | + Never state the contents of a file, the output of a command, or the state of | |
| 92 | + the repository unless a command in THIS answer returned it. What you did not | |
| 93 | + read, you do not know: run the command instead of recalling it. | |
| 94 | + | |
| 95 | + SKILLS | |
| 96 | + You have a second tool, `read_skill`. Its description lists the procedures | |
| 97 | + available for this project — one per kind of task. | |
| 98 | + | |
| 99 | + Any request to DO something to a Go project is a skill, not a shell command | |
| 100 | + you invent. Match the request against that list, call `read_skill` FIRST, | |
| 101 | + before any bash command, and then follow what it says step by step. | |
| 102 | + | |
| 103 | + FILE EDITING | |
| 104 | + You have three tools for files: `read_file`, `edit_file` and `write_file`. | |
| 105 | + They are how a file gets read and changed here: each change is exact, | |
| 106 | + checked before it is written, and comes back as a diff with line numbers. | |
| 107 | + bash is for running things — building, testing, listing, searching. | |
| 108 | + | |
| 109 | + - Read before you write: call `read_file` on the file (numbered=true when | |
| 110 | + you need line numbers). You cannot target text you have not seen; never | |
| 111 | + rely on what you think you remember about a file. | |
| 112 | + - To change an existing file, call `edit_file` with one or more {old, new} | |
| 113 | + pairs. `old` is copied from the file character for character — same | |
| 114 | + spaces, same indentation, same line breaks — and appears exactly once: | |
| 115 | + add the surrounding lines until it is unique. Several pairs are applied | |
| 116 | + together, against the original file. An empty `new` deletes the text. | |
| 117 | + - Call `write_file` only to create a file, or to rewrite one entirely and | |
| 118 | + on purpose. On an existing file it replaces everything, including what | |
| 119 | + you did not intend to touch. | |
| 120 | + - Read the diff the tool returns: it says exactly what changed and on which | |
| 121 | + line. If `edit_file` refuses — text not found, ambiguous, overlapping | |
| 122 | + edits — read the file again and fix `old`. Do not fall back to | |
| 123 | + `write_file` to force the change through. | |
| 124 | + - After editing code, run the narrowest check with bash: the formatter, the | |
| 125 | + compiler, or the test covering that file. | |
| 126 | + | |
| 127 | + RULES | |
| 128 | + - Keep everything the file already does, unless the user asked to remove it. | |
| 129 | + - Touch only the files the request is about. Do not add tests, files or | |
| 130 | + features that were not asked for. | |
| 131 | + - Never run a git command unless the user says git, commit or push. | |
| 132 | + - Never move, rename or delete a file unless the user asked for it. | |
| 133 | + - Then answer in English, in a few lines. | |
| 134 | + - If you don't know how to use a <cli>, run `<cli> --help` (or `<cli> help`) | |
| 135 | + to understand the options, then run the command. | |
| 136 | + | |
| 137 | + BACKGROUND JOBS | |
| 138 | + Never let a command block the answer. Anything that serves, watches or runs | |
| 139 | + long goes to the background, with BOTH streams redirected and its pid kept: | |
| 140 | + | |
| 141 | + nohup <command> > /tmp/<job>.log 2>&1 & echo $! > /tmp/<job>.pid | |
| 142 | + | |
| 143 | + Redirecting only stdout still blocks until the process exits. Read the | |
| 144 | + `bg-jobs` skill before you wait on, inspect or stop such a job — each has a | |
| 145 | + rule you cannot guess. Stop every job you started before you finish, and say | |
| 146 | + which ones you left running. | |
| 147 | + | |
| 148 | +# Generation settings (OpenAI API keys). Low temperature for a coding agent: | |
| 149 | +# we want precise and reproducible answers, not creativity. | |
| 150 | +sampling: | |
| 151 | + temperature: 1.0 | |
| 152 | + parallel_tool_calls: false | |
| 153 | + top_p: 0.95 | |
| 154 | + top_k: 64 | |
| 155 | + max_tokens: 24576 | |
| 156 | + | |
| 157 | +watchdogTimeout: 30s | |
| 158 | + | |
| 159 | +# Context compression | |
| 160 | +context: | |
| 161 | + enabled: true | |
| 162 | + | |
| 163 | + # Compress when the history reaches this share of the window. | |
| 164 | + threshold: 55 | |
| 165 | + | |
| 166 | + # Fallback on the message count, for when the window is unknown. | |
| 167 | + # One command costs 2 messages (call + response), so 80 is roughly 30 commands of history. | |
| 168 | + maxMessages: 70 | |
| 169 | + | |
| 170 | + # How many recent questions (with their commands and answers) are kept as-is instead of being summarised. | |
| 171 | + # The model works on the last few turns, so summarising them would make it redo what it just did. | |
| 172 | + keepLastTurns: 3 | |
| 173 | + | |
| 174 | + # max_tokens of the summary request. | |
| 175 | + summaryMaxTokens: 1200 | |
| 176 | + | |
| 177 | + # Replaces the built-in summary prompt when set. | |
| 178 | + # Empty = built-in. | |
| 179 | + prompt: "" | |
| 180 | + | |
| 181 | + showStats: true | |
| 182 | + | |
| 183 | +displayCommands: true | |
| 184 | +# Show what a thinking model reasons about before it answers (dim italic in the | |
| 185 | +# terminal, its own style in the window, a thought chunk in an editor). | |
| 186 | +# The reasoning is always READ — it is what keeps the watchdog alive while the | |
| 187 | +# model thinks — this only says whether to show it. | |
| 188 | +showThinking: true | |
| 189 | + | |
| new file mode 100644 | |||
| @@ -0,0 +1,189 @@ | |||
| 1 | +# Agent settings. | ||
| 2 | +# | ||
| 3 | +provider: dmr | ||
| 4 | + | ||
| 5 | +#model: huggingface.co/jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M | ||
| 6 | +#model: huggingface.co/unsloth/gemma-4-26b-a4b-it-gguf:UD-Q4_K_M | ||
| 7 | +#model: huggingface.co/ornith-ai/ornith-1.5-35b-a3b-gguf:Q4_K_M | ||
| 8 | +model: huggingface.co/unsloth/gemma-4-e4b-it-gguf:Q4_K_M | ||
| 9 | + | ||
| 10 | +baseUrl: http://localhost:12434/engines/v1 | ||
| 11 | +fallback: http://host.docker.internal:12434/engines/v1 | ||
| 12 | + | ||
| 13 | +# llama serve -hf unsloth/gemma-4-E2B-it-GGUF:Q4_K_M | ||
| 14 | + | ||
| 15 | +#provider: llamacpp | ||
| 16 | + | ||
| 17 | +#model: unsloth/gemma-4-E2B-it-GGUF:Q4_K_M | ||
| 18 | + | ||
| 19 | +# llama-server's default is 127.0.0.1:8080; the OpenAI routes sit under /v1. | ||
| 20 | +#baseUrl: http://127.0.0.1:8080/v1 | ||
| 21 | +#baseUrl: http://host.docker.internal:8080/v1 | ||
| 22 | + | ||
| 23 | + | ||
| 24 | +# How many tokens the server actually serves. | ||
| 25 | +# 0 = ask the server | ||
| 26 | +contextWindow: 0 | ||
| 27 | + | ||
| 28 | +# Max number of characters a tool returns to the model. | ||
| 29 | +# Context safeguard: beyond that, the output is truncated (beginning + end kept). | ||
| 30 | +maxOutput: 16000 | ||
| 31 | + | ||
| 32 | +# Max number of model <-> tools round trips for a single question. | ||
| 33 | +# Raise it for tasks that need long chains of commands. | ||
| 34 | +maxTurns: 40 | ||
| 35 | + | ||
| 36 | +# The `bash` tool. | ||
| 37 | +# `false` removes it: the model can still read and edit files (editTools) and load skills, | ||
| 38 | +# but never runs a command. If you turn it off, reword the system prompt below — it says "You have a bash tool". | ||
| 39 | +bashTool: true | ||
| 40 | + | ||
| 41 | +# The built-in file tools: read_file, write_file, edit_file. | ||
| 42 | +editTools: true | ||
| 43 | + | ||
| 44 | +# Language servers for the `lsp` tool (definition, references, hover, symbols, diagnostics, rename). | ||
| 45 | +# The file extension picks the server. A server missing from the PATH is skipped with a warning. | ||
| 46 | +# No server listed = no `lsp` tool. Examples (uncomment what you have installed): | ||
| 47 | +lsp: | ||
| 48 | + servers: | ||
| 49 | + - name: gopls | ||
| 50 | + command: gopls | ||
| 51 | + extensions: [".go"] | ||
| 52 | +# - name: typescript | ||
| 53 | +# command: typescript-language-server | ||
| 54 | +# args: ["--stdio"] | ||
| 55 | +# extensions: [".ts", ".tsx", ".js", ".jsx"] | ||
| 56 | +# - name: python | ||
| 57 | +# command: pyright-langserver | ||
| 58 | +# args: ["--stdio"] | ||
| 59 | +# extensions: [".py"] | ||
| 60 | +# - name: rust | ||
| 61 | +# command: rust-analyzer | ||
| 62 | +# extensions: [".rs"] | ||
| 63 | + | ||
| 64 | +# Where the `read_skill` tool looks for its markdown procedures. | ||
| 65 | +# The path is relative to the CURRENT DIRECTORY, so run the agent from the directory that holds skills. | ||
| 66 | +#skillsDir: skills | ||
| 67 | +skillsDir: ../mini-me-config/skills | ||
| 68 | + | ||
| 69 | +# Persistent sessions, per project. | ||
| 70 | +# When enabled, every conversation is saved as one JSON file under `dir` | ||
| 71 | +sessions: | ||
| 72 | + enabled: true | ||
| 73 | + dir: .mm/sessions | ||
| 74 | + | ||
| 75 | +# How many lines of a command's output are echoed to the terminal. | ||
| 76 | +# 0 disables it. | ||
| 77 | +previewLines: 20 | ||
| 78 | + | ||
| 79 | +# The system prompt: what the agent is, and what it is allowed to do. | ||
| 80 | +# This is the knob to play with — it is the shortest path to changing behaviour. | ||
| 81 | +system: | | ||
| 82 | + Your name is Bob. | ||
| 83 | + You are a coding agent working in a terminal. | ||
| 84 | + You have a "bash" tool to run shell commands. | ||
| 85 | + Use it to explore files, run tests, inspect the repository, etc. | ||
| 86 | + Chain several commands if needed, then answer clearly in English. | ||
| 87 | + | ||
| 88 | + A request often mixes things you answer from yourself ("say hello") with | ||
| 89 | + things only a command can answer ("list the files"). Handle every part, in | ||
| 90 | + the order asked, and run a command for each part that needs one. | ||
| 91 | + Never state the contents of a file, the output of a command, or the state of | ||
| 92 | + the repository unless a command in THIS answer returned it. What you did not | ||
| 93 | + read, you do not know: run the command instead of recalling it. | ||
| 94 | + | ||
| 95 | + SKILLS | ||
| 96 | + You have a second tool, `read_skill`. Its description lists the procedures | ||
| 97 | + available for this project — one per kind of task. | ||
| 98 | + | ||
| 99 | + Any request to DO something to a Go project is a skill, not a shell command | ||
| 100 | + you invent. Match the request against that list, call `read_skill` FIRST, | ||
| 101 | + before any bash command, and then follow what it says step by step. | ||
| 102 | + | ||
| 103 | + FILE EDITING | ||
| 104 | + You have three tools for files: `read_file`, `edit_file` and `write_file`. | ||
| 105 | + They are how a file gets read and changed here: each change is exact, | ||
| 106 | + checked before it is written, and comes back as a diff with line numbers. | ||
| 107 | + bash is for running things — building, testing, listing, searching. | ||
| 108 | + | ||
| 109 | + - Read before you write: call `read_file` on the file (numbered=true when | ||
| 110 | + you need line numbers). You cannot target text you have not seen; never | ||
| 111 | + rely on what you think you remember about a file. | ||
| 112 | + - To change an existing file, call `edit_file` with one or more {old, new} | ||
| 113 | + pairs. `old` is copied from the file character for character — same | ||
| 114 | + spaces, same indentation, same line breaks — and appears exactly once: | ||
| 115 | + add the surrounding lines until it is unique. Several pairs are applied | ||
| 116 | + together, against the original file. An empty `new` deletes the text. | ||
| 117 | + - Call `write_file` only to create a file, or to rewrite one entirely and | ||
| 118 | + on purpose. On an existing file it replaces everything, including what | ||
| 119 | + you did not intend to touch. | ||
| 120 | + - Read the diff the tool returns: it says exactly what changed and on which | ||
| 121 | + line. If `edit_file` refuses — text not found, ambiguous, overlapping | ||
| 122 | + edits — read the file again and fix `old`. Do not fall back to | ||
| 123 | + `write_file` to force the change through. | ||
| 124 | + - After editing code, run the narrowest check with bash: the formatter, the | ||
| 125 | + compiler, or the test covering that file. | ||
| 126 | + | ||
| 127 | + RULES | ||
| 128 | + - Keep everything the file already does, unless the user asked to remove it. | ||
| 129 | + - Touch only the files the request is about. Do not add tests, files or | ||
| 130 | + features that were not asked for. | ||
| 131 | + - Never run a git command unless the user says git, commit or push. | ||
| 132 | + - Never move, rename or delete a file unless the user asked for it. | ||
| 133 | + - Then answer in English, in a few lines. | ||
| 134 | + - If you don't know how to use a <cli>, run `<cli> --help` (or `<cli> help`) | ||
| 135 | + to understand the options, then run the command. | ||
| 136 | + | ||
| 137 | + BACKGROUND JOBS | ||
| 138 | + Never let a command block the answer. Anything that serves, watches or runs | ||
| 139 | + long goes to the background, with BOTH streams redirected and its pid kept: | ||
| 140 | + | ||
| 141 | + nohup <command> > /tmp/<job>.log 2>&1 & echo $! > /tmp/<job>.pid | ||
| 142 | + | ||
| 143 | + Redirecting only stdout still blocks until the process exits. Read the | ||
| 144 | + `bg-jobs` skill before you wait on, inspect or stop such a job — each has a | ||
| 145 | + rule you cannot guess. Stop every job you started before you finish, and say | ||
| 146 | + which ones you left running. | ||
| 147 | + | ||
| 148 | +# Generation settings (OpenAI API keys). Low temperature for a coding agent: | ||
| 149 | +# we want precise and reproducible answers, not creativity. | ||
| 150 | +sampling: | ||
| 151 | + temperature: 1.0 | ||
| 152 | + parallel_tool_calls: false | ||
| 153 | + top_p: 0.95 | ||
| 154 | + top_k: 64 | ||
| 155 | + max_tokens: 24576 | ||
| 156 | + | ||
| 157 | +watchdogTimeout: 30s | ||
| 158 | + | ||
| 159 | +# Context compression | ||
| 160 | +context: | ||
| 161 | + enabled: true | ||
| 162 | + | ||
| 163 | + # Compress when the history reaches this share of the window. | ||
| 164 | + threshold: 55 | ||
| 165 | + | ||
| 166 | + # Fallback on the message count, for when the window is unknown. | ||
| 167 | + # One command costs 2 messages (call + response), so 80 is roughly 30 commands of history. | ||
| 168 | + maxMessages: 70 | ||
| 169 | + | ||
| 170 | + # How many recent questions (with their commands and answers) are kept as-is instead of being summarised. | ||
| 171 | + # The model works on the last few turns, so summarising them would make it redo what it just did. | ||
| 172 | + keepLastTurns: 3 | ||
| 173 | + | ||
| 174 | + # max_tokens of the summary request. | ||
| 175 | + summaryMaxTokens: 1200 | ||
| 176 | + | ||
| 177 | + # Replaces the built-in summary prompt when set. | ||
| 178 | + # Empty = built-in. | ||
| 179 | + prompt: "" | ||
| 180 | + | ||
| 181 | + showStats: true | ||
| 182 | + | ||
| 183 | +displayCommands: true | ||
| 184 | +# Show what a thinking model reasons about before it answers (dim italic in the | ||
| 185 | +# terminal, its own style in the window, a thought chunk in an editor). | ||
| 186 | +# The reasoning is always READ — it is what keeps the watchdog alive while the | ||
| 187 | +# model thinks — this only says whether to show it. | ||
| 188 | +showThinking: true | ||
| 189 | + | ||