Deskmate

Chapter 1

What it is

deskmate is the agreement between you and the AI agent that shares your computer. It is one file with no dependencies, and it runs in Node and in this page.

The agent asks before it borrows anything: which app, which files, read or write, and for how many minutes. You lend it a lease or say no. Every action it tries is checked against what you lent and against your rules, and every step is written down. At the end you get the desk diary.

1

Chapter 2

Getting started

unzip deskmate-0.1.0.zip
cd deskmate
npm test                          # 13 tests
node bin/deskmate.js demo         # a careful human
node bin/deskmate.js ask          # you answer every request

In code: const desk = Deskmate.createDesk(), then desk.request(), desk.approve() or desk.deny(), and desk.act() before every step your agent takes.

3

Chapter 3

Leases

A lease lends one app and some folders, read or write, for a number of minutes. When you approve, you can shorten it or turn a write request into read only.

Leases run out on their own, and revoke() takes one back at once. A lease on ~/Documents/invoices/** does not reach ~/Pictures, and a read lease never lets the agent edit or delete.

7

Chapter 4

Verdicts

• done: inside a lease you gave.
• ask: it needs your yes first. Either nothing was lent, a lease ran out, it has read but needs write, the file is sensitive, or the action needs a yes every time.
• blocked: a rule says never (paying, by default).
• paused: you raised your hand and took over.

11

Chapter 5

Sensitive files

SSH keys, .pem and .key files, .env files, wallets, password and seed files, keychains and banking folders are never covered by a general lease, not even one for ~/**. Each needs its own explicit yes, and the diary lists every sensitive file the agent touched.

15

Chapter 6

Rules and policy

Rules match by action, app and path glob (** any depth, * one segment, ? one character), and decide allow, ask or never. The strictest match wins. By default, paying is never allowed, and sending or installing needs a yes every time.

{ "action": "delete", "path": "~/Photos/**",
  "decision": "never", "why": "never my photos" }

19

Chapter 7

Guarding your own agent

Call desk.act() inside every tool your agent has, before it touches anything. Turn "ask" into a question for the person, and never run a "blocked" step. examples/guard-an-agent.js shows the whole loop in forty lines.

runAsync() lets the answer come later, from a prompt, a chat message or a button like the ones in Period 1.

24

Chapter 8

Honest limits

• deskmate decides; it does not enforce. An agent that never calls act() is not stopped by it.
• Paths are matched as text. Your harness should resolve symlinks and .. first.
• The sensitive list covers common secrets, not every secret. Add your own patterns.

29