Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở
  • Có gì không ổn?
#147 0 bình luận 0 reaction 1 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@V3RON đang làm issue này rồi.

Từ ngày 27/9/2026.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

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.

Ngôn ngữ chính
TypeScript
Star
14
Fork
0
Merge trung bình
1 ngày 3 giờ
Pull request đã merge (30 ngày)
49

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của callstackincubator/simlock

Tất cả issue của callstackincubator/simlock

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.