Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Add `simlock instructions`: the rules an agent must follow, printable and served over MCP

Aperta
  • Qualcosa non va?
#147 0 commenti 0 reazioni 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@V3RON ci sta già lavorando.

Dal 27/9/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

task:ready

Standalone task opened by the maintainer; no parent feature.

Scope

Simlock is advisory: it only works when every agent never calls simctl, adb, avdmanager, or emulator directly and only drives devices it leased. Today those rules live in the docs, and each team rewrites them into every agent's system prompt by hand.

After this PR an operator runs simlock instructions and gets one self-contained text block to paste into an agent's system prompt or AGENTS.md, and an MCP client can read the same text as a resource. The block tells an agent, in plain words:

  • Never call the platform tools directly; use simlock simctl / simlock adb, which inject the device set or adb port.
  • How to lease: set a stable SIMLOCK_AGENT_ID, run simlock catalog first, then simlock lease --platform … --device … in the background (or --detach plus simlock lease renew before ttlDeadline), read the one JSON line on stdout, and read progress from stderr.
  • One lease per agent, --all and nuke are operator commands, release with simlock release <lease-id> or by exiting the holder.
  • Never pass --allow-download unless told to.
  • What exit codes 10, 11, 13, and 14 mean and what to do on each.
  • How to reach a leased device: the environment block, simlock simctl/simlock adb, and that the refused verbs (simctl create/erase/delete, adb kill-server, emu kill) are refused on purpose.
  • Over MCP: the four tools and that lease_status is the thing to call after a context compaction.

Technical spec

Modules touched
  • src/instructions/index.ts (new): one exported AGENT_INSTRUCTIONS: string (Markdown) and renderInstructions(format: "text" | "json"). The only source of the text; nothing is duplicated in the CLI or MCP.
  • src/cli/index.ts: new instructions command. Prints the Markdown on stdout by default; --json prints {"instructions": "<markdown>"}. Any other flag is USAGE (exit 2). Never connects to, or auto-starts, the daemon. Listed in simlock --help.
  • src/mcp/server.ts: register a resource simlock://instructions (text/markdown) returning AGENT_INSTRUCTIONS; declare the resources capability. No new tools.
  • docs/CLI.md: a ## simlock instructions section, and add the command to the "human-oriented view … accept --json" exception list in the intro. README.md: one sentence under "Getting started" and one under "MCP integration".
Contract and event changes

None. No daemon operation, no event, no config key.

Rules in play
  • docs/internal/agent-rules/documentation.md rule 3: the printed text must name no file path in this repo. Point at the package's homepage URL if a pointer is needed.
  • docs/internal/agent-rules/testing.md: every test title below is a claim.
  • docs/internal/agent-rules/architecture.md rule 8: the text is static and frontend-owned; the daemon does not learn about it.
Tests
  • simlock instructions prints the agent instructions on stdout and exits 0 without starting a daemon (e2e, fast lane: assert no socket appears under SIMLOCK_HOME).
  • simlock instructions --json prints one JSON object whose instructions field equals the text output.
  • simlock instructions --bogus fails with USAGE and exit 2.
  • The agent instructions name no path inside this repository (unit: the text matches neither docs/ nor .md).
  • The agent instructions name every refused passthrough verb the drivers refuse (unit: derive the expected list from the drivers' refusal constants, not a copy).
  • The MCP server lists simlock://instructions and reading it returns the same text the CLI prints (e2e, MCP session flow).

Done when

  • simlock instructions and simlock instructions --json behave as specified above, verified by the e2e tests.
  • simlock --help lists the command.
  • An MCP client can read simlock://instructions.
  • docs/CLI.md and README.md describe the command; pnpm check is green.

Out of scope

  • Generating the text from the live catalog or config; it is static.
  • A prompt-typed MCP primitive; a resource is enough for v1.
  • Any new MCP tool.

Depends on

Approval

  • Approved for delivery

Written by an agent.

Lingua principale
TypeScript
Stelle
14
Fork
0
Merge medio
1g 3h
PR unite (30g)
49

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di callstackincubator/simlock

Tutte le issue di callstackincubator/simlock

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.