@sedge-hq/sedge 0.0.1 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +31 -5
- package/docs/architecture-dark.svg +114 -0
- package/docs/architecture-light.svg +114 -0
- package/docs/channels-and-signals.md +69 -0
- package/docs/commands.md +56 -0
- package/docs/configuration.md +63 -0
- package/docs/development.md +60 -0
- package/docs/getting-started.md +67 -0
- package/docs/how-it-works.md +76 -0
- package/docs/index.md +43 -0
- package/docs/kit.md +98 -0
- package/docs/mcp-and-skills.md +56 -0
- package/docs/memory.md +50 -0
- package/docs/meta.json +16 -0
- package/docs/security.md +56 -0
- package/package.json +6 -6
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Development
|
|
3
|
+
description: Working on sedge itself. The repository, running it from source, tests, and releases.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Setup
|
|
7
|
+
|
|
8
|
+
[Bun](https://bun.sh) only:
|
|
9
|
+
|
|
10
|
+
```sh
|
|
11
|
+
bun install
|
|
12
|
+
bun run sedge # the TUI from source, against ./.sedge-dev
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
`bun run sedge` keeps everything in `./.sedge-dev`, so it never touches your real `~/.sedge`.
|
|
16
|
+
|
|
17
|
+
## Before a change is done
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
bun run format
|
|
21
|
+
bun run lint
|
|
22
|
+
bun run typecheck
|
|
23
|
+
bun run test
|
|
24
|
+
bun run e2e:telegram # after changing channels, signals or the daemon
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
`e2e:telegram` starts a fake Telegram Bot API and a daemon in a throwaway home, then walks
|
|
28
|
+
install, connect, pairing, a reply, an approval and disconnect, with real model calls through
|
|
29
|
+
your logins. `SEDGE_BIN=dist/npm/sedge-<os>-<cpu>/bin/sedge` runs it against a compiled binary
|
|
30
|
+
(`bun scripts/build.ts` builds one for this machine).
|
|
31
|
+
|
|
32
|
+
## The repository
|
|
33
|
+
|
|
34
|
+
| Path | What |
|
|
35
|
+
| ------------------- | --------------------------------------------------------------------------- |
|
|
36
|
+
| `apps/cli` | The `sedge` command: dispatch, the TUI extension and its tools, the client. |
|
|
37
|
+
| `apps/site` | sedge.sh: the page and the `curl … \| sh` installer. |
|
|
38
|
+
| `packages/daemon` | The daemon: connections, runtime, dispatcher, host, server, updater. |
|
|
39
|
+
| `packages/agent` | The daemon's agent on pi-durable: tools, MCP, skills, recall. |
|
|
40
|
+
| `packages/db` | Inbox, timers, outbox, approvals (SQLite, Drizzle). |
|
|
41
|
+
| `packages/protocol` | The RPCs between the TUI and the daemon. |
|
|
42
|
+
| `packages/core` | Paths, config, version, logo. |
|
|
43
|
+
| `packages/kit` | [`@sedge-hq/kit`](./kit.md), published. |
|
|
44
|
+
| `packages/telegram` | `@sedge-hq/telegram`, published. |
|
|
45
|
+
| `docs` | These pages. |
|
|
46
|
+
| `scripts` | Build, release, and the generated pictures (`logo.ts`, `architecture.ts`). |
|
|
47
|
+
|
|
48
|
+
[`AGENTS.md`](../AGENTS.md) has the rules the code follows.
|
|
49
|
+
|
|
50
|
+
## Docs
|
|
51
|
+
|
|
52
|
+
A change people would notice updates these pages in the same change. `bun run test` fails when a
|
|
53
|
+
command, tool, setting or environment variable is missing from [Commands](./commands.md) or
|
|
54
|
+
[Configuration](./configuration.md).
|
|
55
|
+
|
|
56
|
+
## Releases
|
|
57
|
+
|
|
58
|
+
Every user-facing change has a changeset (`bun run changeset`). Merging to `main` opens or updates
|
|
59
|
+
a release PR; merging that publishes to npm, tags the version and creates a GitHub release whose
|
|
60
|
+
notes link each change's commit and PR.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Getting started
|
|
3
|
+
description: Install sedge, log in to a model, and reach it from your phone.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Install
|
|
7
|
+
|
|
8
|
+
```sh
|
|
9
|
+
curl -fsSL sedge.sh | sh
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
or with npm:
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
npm i -g @sedge-hq/sedge
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Both give you one `sedge` command. It updates itself (see [Configuration](./configuration.md) to
|
|
19
|
+
turn that off).
|
|
20
|
+
|
|
21
|
+
## First run
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
sedge
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
This opens the TUI and starts the daemon in the background if it isn't running. The first time,
|
|
28
|
+
log in to a model provider with `/login` (an API key, or a subscription such as Claude). The
|
|
29
|
+
daemon uses the same logins and the same default model, so you only do this once.
|
|
30
|
+
|
|
31
|
+
Ask it anything, as you would any coding agent. For one answer without the TUI:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
sedge -p "summarize the changes on this branch"
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Talk to it from your phone
|
|
38
|
+
|
|
39
|
+
In the TUI, say:
|
|
40
|
+
|
|
41
|
+
> set up telegram
|
|
42
|
+
|
|
43
|
+
sedge will:
|
|
44
|
+
|
|
45
|
+
1. install the Telegram package (you confirm first);
|
|
46
|
+
2. ask for your bot token in a hidden field (create a bot by writing `/newbot` to
|
|
47
|
+
[@BotFather](https://t.me/BotFather)); the token goes to your OS keychain, never into the chat;
|
|
48
|
+
3. give you an invite link. Open it on your phone: that pairs your Telegram account. The link
|
|
49
|
+
works once and expires in 30 minutes, and nobody else gets answers from your bot.
|
|
50
|
+
|
|
51
|
+
Now write to your bot. sedge answers there, shows "typing…" while it works, and asks before
|
|
52
|
+
anything risky with Approve / Deny buttons.
|
|
53
|
+
|
|
54
|
+
## Keep it running
|
|
55
|
+
|
|
56
|
+
The daemon runs until you stop it or log out. To start it at login:
|
|
57
|
+
|
|
58
|
+
```sh
|
|
59
|
+
sedge start --service
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
`sedge stop` stops it and removes the login service.
|
|
63
|
+
|
|
64
|
+
## Next
|
|
65
|
+
|
|
66
|
+
- Get woken when something happens: [Channels and signals](./channels-and-signals.md).
|
|
67
|
+
- See what it keeps between conversations: [Memory](./memory.md).
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: How it works
|
|
3
|
+
description: The daemon's loop. Events go into an inbox, a durable run handles them, and what it says leaves through an outbox.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<picture>
|
|
7
|
+
<source media="(prefers-color-scheme: dark)" srcset="./architecture-dark.svg">
|
|
8
|
+
<img src="./architecture-light.svg" alt="How sedge works: channels, signals, timers and the terminal put events into the inbox; a durable run works with memory, skills, MCP servers, tools and approvals; what it sends leaves through the outbox to you, and your reply comes back as an event." width="100%">
|
|
9
|
+
</picture>
|
|
10
|
+
|
|
11
|
+
An always-on agent is not running all the time. It sleeps until something happens, wakes for a
|
|
12
|
+
short run, and sleeps again. sedge follows the pattern in
|
|
13
|
+
[Building always-on agents](https://claude.com/resources/articles/building-always-on-agents),
|
|
14
|
+
with five parts.
|
|
15
|
+
|
|
16
|
+
## The event inbox
|
|
17
|
+
|
|
18
|
+
Everything that should wake the agent becomes an event in the inbox, a table in
|
|
19
|
+
`~/.sedge/sedge.db`:
|
|
20
|
+
|
|
21
|
+
- a message on a [channel](./channels-and-signals.md) (Telegram);
|
|
22
|
+
- a [signal](./channels-and-signals.md) firing (CI failed);
|
|
23
|
+
- a timer coming due;
|
|
24
|
+
- your answer to an approval;
|
|
25
|
+
- a task from the terminal (`/sedge bg <task>` in the TUI).
|
|
26
|
+
|
|
27
|
+
Each event has an id from its source, so one that arrives twice is stored once. One worker drains
|
|
28
|
+
the inbox, one conversation at a time. Events that arrive while it works are answered together
|
|
29
|
+
in the next run, so three quick messages get one reply, not three.
|
|
30
|
+
|
|
31
|
+
## The run
|
|
32
|
+
|
|
33
|
+
A run is the agent at work: [pi](https://github.com/earendil-works/pi)'s model, with tools to read
|
|
34
|
+
and edit files, run commands, search, and reach you. Runs live on
|
|
35
|
+
[pi-durable](https://github.com/earendil-works/pi/tree/main/packages/durable): each conversation
|
|
36
|
+
is kept in SQLite (`~/.sedge/agent/durable.sqlite`), so a run cut short by a crash, an update or a
|
|
37
|
+
restart resumes where it stopped. Every event is submitted with its inbox id, so even a repeat
|
|
38
|
+
after a restart is answered once.
|
|
39
|
+
|
|
40
|
+
Conversations are called threads:
|
|
41
|
+
|
|
42
|
+
- `main`: you and sedge, on every channel. Signals report here too.
|
|
43
|
+
- `cli:<folder>`: a task from the terminal, one per folder.
|
|
44
|
+
- `dream`: the nightly [memory](./memory.md) review.
|
|
45
|
+
|
|
46
|
+
## Timers
|
|
47
|
+
|
|
48
|
+
The agent sets its own: a follow-up (`in 2h`, `at 2026-12-01T09:00`) or a schedule (cron, in your
|
|
49
|
+
time zone). When one comes due it becomes an event. If the agent says it will check back, it has
|
|
50
|
+
set a timer.
|
|
51
|
+
|
|
52
|
+
## Memory
|
|
53
|
+
|
|
54
|
+
A folder of files the agent keeps. A short index is loaded into every run; the rest is read when
|
|
55
|
+
needed, and every night the agent reviews and tidies it. See [Memory](./memory.md).
|
|
56
|
+
|
|
57
|
+
## Permissions and approvals
|
|
58
|
+
|
|
59
|
+
In runs you're not watching, risky tool calls (shell commands, MCP tools) wait for your say-so.
|
|
60
|
+
The agent's call is held, you get the command with Approve / Deny buttons, and your answer comes
|
|
61
|
+
back as an event. See [Security](./security.md).
|
|
62
|
+
|
|
63
|
+
## The outbox
|
|
64
|
+
|
|
65
|
+
Nothing the agent writes reaches you unless it calls `send_message`. Messages go to the outbox
|
|
66
|
+
table first, and a dispatcher delivers them to the channel you last wrote from, retrying on
|
|
67
|
+
failure. Messages can carry buttons (your pick comes back as an event) and files.
|
|
68
|
+
|
|
69
|
+
## The two processes
|
|
70
|
+
|
|
71
|
+
- **The TUI** (`sedge`) is pi's interactive session with sedge's extension. Its own chat stays in
|
|
72
|
+
the TUI; it talks to the daemon only to show status, hand off background tasks and set things
|
|
73
|
+
up.
|
|
74
|
+
- **The daemon** (`sedge start`) runs everything above. The two talk over a Unix socket
|
|
75
|
+
(`~/.sedge/sedge.sock`). `sedge` never waits for the daemon: it starts it in the background and
|
|
76
|
+
connects when it's up.
|
package/docs/index.md
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: sedge
|
|
3
|
+
description: An always-on agent that lives on your machine. What it is, and where to read next.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
sedge is an agent that keeps working after you close the terminal. You talk to it in a TUI on
|
|
7
|
+
your computer, or from your phone on Telegram. It wakes when something happens (a message, a
|
|
8
|
+
timer, your CI failing), does the work, tells you what matters, and goes back to sleep.
|
|
9
|
+
|
|
10
|
+
<picture>
|
|
11
|
+
<source media="(prefers-color-scheme: dark)" srcset="./architecture-dark.svg">
|
|
12
|
+
<img src="./architecture-light.svg" alt="How sedge works: channels, signals, timers and the terminal put events into the inbox; a durable run works with memory, skills, MCP servers, tools and approvals; what it sends leaves through the outbox to you, and your reply comes back as an event." width="100%">
|
|
13
|
+
</picture>
|
|
14
|
+
|
|
15
|
+
It has two halves:
|
|
16
|
+
|
|
17
|
+
- **The TUI** (`sedge`): a coding agent in your terminal, built on
|
|
18
|
+
[pi](https://github.com/earendil-works/pi). Everything pi does works here, plus tools to set
|
|
19
|
+
sedge up.
|
|
20
|
+
- **The daemon** (`sedge start`): runs in the background. It holds an inbox of events, fires
|
|
21
|
+
timers, keeps memory, asks before risky actions, and sends you messages. Its conversations are
|
|
22
|
+
durable: a run cut short by a restart picks up where it stopped.
|
|
23
|
+
|
|
24
|
+
## Read next
|
|
25
|
+
|
|
26
|
+
| If you want to… | Read |
|
|
27
|
+
| --------------------------------------------- | ------------------------------------------------- |
|
|
28
|
+
| Install it and talk to it from your phone | [Getting started](./getting-started.md) |
|
|
29
|
+
| Understand what happens when an event arrives | [How it works](./how-it-works.md) |
|
|
30
|
+
| Connect Telegram, or get woken by your CI | [Channels and signals](./channels-and-signals.md) |
|
|
31
|
+
| Know what it remembers, and how | [Memory](./memory.md) |
|
|
32
|
+
| Give it your MCP servers and skills | [MCP and skills](./mcp-and-skills.md) |
|
|
33
|
+
| Know what it can and can't do without you | [Security](./security.md) |
|
|
34
|
+
| Change a setting | [Configuration](./configuration.md) |
|
|
35
|
+
| Look up a command or tool | [Commands](./commands.md) |
|
|
36
|
+
| Write a channel or signal of your own | [The kit](./kit.md) |
|
|
37
|
+
| Work on sedge itself | [Development](./development.md) |
|
|
38
|
+
|
|
39
|
+
## For agents
|
|
40
|
+
|
|
41
|
+
These pages are plain Markdown, one topic each, and every page starts with a one-line
|
|
42
|
+
description. The TUI's agent already knows sedge's basics and links here; the daemon's agent is
|
|
43
|
+
sedge.
|
package/docs/kit.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: The kit
|
|
3
|
+
description: Write a channel or signal for sedge with @sedge-hq/kit. The API, with examples.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
[`@sedge-hq/kit`](../packages/kit) is how channels and signals are written. It's
|
|
7
|
+
[Effect](https://effect.website): settings are an Effect `Schema`, a signal is a `Stream`, a
|
|
8
|
+
channel is a scoped `Effect`.
|
|
9
|
+
|
|
10
|
+
A module's default export is a kind: `defineSignal(...)` or `defineChannel(...)`. Ship it in a
|
|
11
|
+
package (list the module under `"sedge": { "plugins": ["./src/my-kind.ts"] }` in package.json),
|
|
12
|
+
or register a single file with `create_signal`. Modules are bundled with their dependencies
|
|
13
|
+
before sedge loads them.
|
|
14
|
+
|
|
15
|
+
## A signal
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import { defineSignal, secret } from '@sedge-hq/kit';
|
|
19
|
+
import { Effect, Redacted, Schedule, Schema, Stream } from 'effect';
|
|
20
|
+
|
|
21
|
+
export default defineSignal({
|
|
22
|
+
name: 'ci', // lowercase; what `connect` calls the kind
|
|
23
|
+
summary: 'GitHub Actions runs that fail on a branch',
|
|
24
|
+
settings: {
|
|
25
|
+
repo: Schema.String.annotate({ description: 'owner/name' }),
|
|
26
|
+
branch: Schema.optional(Schema.String).annotate({ description: 'Default: main' }),
|
|
27
|
+
token: secret('A GitHub token that can read Actions'),
|
|
28
|
+
},
|
|
29
|
+
watch: (settings, kit) =>
|
|
30
|
+
Stream.fromEffectSchedule(failedRuns(settings, kit), Schedule.spaced('1 minute')).pipe(
|
|
31
|
+
Stream.flatMap(Stream.fromIterable),
|
|
32
|
+
),
|
|
33
|
+
});
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`watch` returns a `Stream` of **happenings**:
|
|
37
|
+
|
|
38
|
+
| Field | What |
|
|
39
|
+
| --------- | ----------------------------------------------------------------------------- |
|
|
40
|
+
| `text` | What the agent reads. Short and plain: "CI failed on main: lint (run 812)". |
|
|
41
|
+
| `key` | Optional. An id for this happening; one with a key sedge has seen is dropped. |
|
|
42
|
+
| `details` | Optional. Anything else, as JSON, shown to the agent below the text. |
|
|
43
|
+
|
|
44
|
+
Report what changes after the signal starts, not the state of the world at start. Use
|
|
45
|
+
`kit.memo` to remember what you've already seen across restarts.
|
|
46
|
+
|
|
47
|
+
## A channel
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
import { defineChannel, secret } from '@sedge-hq/kit';
|
|
51
|
+
import { Effect, Stream } from 'effect';
|
|
52
|
+
|
|
53
|
+
export default defineChannel({
|
|
54
|
+
name: 'my-chat',
|
|
55
|
+
summary: 'my chat app: message sedge from anywhere',
|
|
56
|
+
settings: { token: secret('The bot token') },
|
|
57
|
+
connect: (settings, kit) =>
|
|
58
|
+
Effect.gen(function* () {
|
|
59
|
+
// Log in, restore paired accounts from kit.memo, …
|
|
60
|
+
return {
|
|
61
|
+
incoming: messages, // Stream of Message | Picked, only from paired accounts
|
|
62
|
+
deliver: (reply, to) => send(reply, to),
|
|
63
|
+
invite: (code) => `https://chat.example/bot?start=${code}`,
|
|
64
|
+
working: (to) => showTyping(to), // optional
|
|
65
|
+
};
|
|
66
|
+
}),
|
|
67
|
+
});
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`connect` runs in a scope: close what you open with `Effect.acquireRelease`, and it's released
|
|
71
|
+
when the channel stops. If it fails, sedge retries every 10 seconds and shows why in the status.
|
|
72
|
+
|
|
73
|
+
A channel must:
|
|
74
|
+
|
|
75
|
+
- **Pair through invites.** When someone sends a code from your `invite` link, call
|
|
76
|
+
`kit.claim(code, account)`. If it returns true, that account is the user's: remember it in
|
|
77
|
+
`kit.memo`. Ignore everyone else completely.
|
|
78
|
+
- **Deliver replies.** `reply.text` is Markdown (render what you can, fall back to plain text),
|
|
79
|
+
`reply.choices` are buttons (send a pick back as `{ _tag: 'Picked', from, value }`),
|
|
80
|
+
`reply.files` are local paths. `to` is the `from` of the message being answered, or undefined
|
|
81
|
+
for "the user's usual chat".
|
|
82
|
+
- **Give events a `key`** (the platform's message id), so a message redelivered after a crash is
|
|
83
|
+
answered once.
|
|
84
|
+
|
|
85
|
+
[`packages/telegram`](../packages/telegram/src/telegram.ts) is the reference channel.
|
|
86
|
+
|
|
87
|
+
## The kit
|
|
88
|
+
|
|
89
|
+
| Name | What |
|
|
90
|
+
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
91
|
+
| `secret(description)` | A secret setting: typed into a hidden field, kept in the keychain, given to you as a `Redacted` (`Redacted.value(token)`). |
|
|
92
|
+
| `kit.memo.get(key)` | A small value saved across restarts (`Option<string>`). |
|
|
93
|
+
| `kit.memo.set(key, v)` | Save one. |
|
|
94
|
+
| `kit.status(line)` | One line on how it's doing, shown in `channels` / `signals`. |
|
|
95
|
+
| `kit.claim(code, account)` | Channels: pair the account that sent this invite code. |
|
|
96
|
+
|
|
97
|
+
Settings descriptions (`.annotate({ description })`) are what the agent and the user see when
|
|
98
|
+
connecting, so write them for a person.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: MCP and skills
|
|
3
|
+
description: Using your MCP servers and skills in the daemon's runs, not only in the TUI.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## In the TUI
|
|
7
|
+
|
|
8
|
+
The TUI is pi, so MCP servers and skills work exactly as in pi: manage them with `/mcp`, or
|
|
9
|
+
`sedge pi mcp …` and `sedge pi config`.
|
|
10
|
+
|
|
11
|
+
## In the daemon's runs
|
|
12
|
+
|
|
13
|
+
Runs that happen without you (Telegram, signals, timers) get them too.
|
|
14
|
+
|
|
15
|
+
### MCP servers
|
|
16
|
+
|
|
17
|
+
The daemon reads the same global `mcp.json` as pi (`~/.pi/agent/mcp.json`), with the same format:
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{
|
|
21
|
+
"mcpServers": {
|
|
22
|
+
"github": {
|
|
23
|
+
"command": "npx",
|
|
24
|
+
"args": ["-y", "@modelcontextprotocol/server-github"],
|
|
25
|
+
"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
|
|
26
|
+
},
|
|
27
|
+
"docs": {
|
|
28
|
+
"url": "https://example.com/mcp",
|
|
29
|
+
"headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
- `${NAME}` and `$NAME` read the environment; a value starting with `!` is a shell command whose
|
|
36
|
+
output is used (`"!op read op://vault/github/token"`).
|
|
37
|
+
- `"enabled": false` skips a server. `exposure` / `toolExposure` set to `"hidden"` hide tools.
|
|
38
|
+
- Tools are found on demand: the agent searches with `tool_search` and only then sees a tool's
|
|
39
|
+
schema, so many servers cost nothing until used.
|
|
40
|
+
- In runs you're not watching, MCP calls ask for approval first, like shell commands (see
|
|
41
|
+
[Security](./security.md)).
|
|
42
|
+
- Servers start with the daemon. After changing `mcp.json`, restart it:
|
|
43
|
+
`sedge stop && sedge start`.
|
|
44
|
+
|
|
45
|
+
Not yet in the daemon:
|
|
46
|
+
|
|
47
|
+
- **Project files** (`.pi/mcp.json` in a repository) are ignored, so a repository can't add tools
|
|
48
|
+
to runs nobody watches.
|
|
49
|
+
- **Servers that sign in with OAuth**, and servers that use a `/login` provider (`"auth"`), only
|
|
50
|
+
work in the TUI for now. Give an HTTP server an `Authorization` header to use it in the daemon.
|
|
51
|
+
|
|
52
|
+
### Skills
|
|
53
|
+
|
|
54
|
+
The daemon lists your skills the way pi does (from `~/.pi/agent/skills` and the folders pi reads)
|
|
55
|
+
in its system prompt, and the agent reads one with its `read` tool when a task calls for it.
|
|
56
|
+
Skills marked `disable-model-invocation` are left out.
|
package/docs/memory.md
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Memory
|
|
3
|
+
description: What sedge keeps between conversations, how it decides, and the nightly dream that keeps it accurate.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
sedge's memory is a folder of files: `~/.sedge/memory`. It follows
|
|
7
|
+
[The components of agent memory](https://www.anthropic.com/research/components-of-agent-memory).
|
|
8
|
+
|
|
9
|
+
## What's loaded, and what isn't
|
|
10
|
+
|
|
11
|
+
- **`MEMORY.md`** is loaded into every run, only its first 200 lines (or 25 KB). It's an index:
|
|
12
|
+
what sedge knows and where to find it, plus anything it needs every time (your standing
|
|
13
|
+
instructions, current goals). Keeping it short keeps it cheap and keeps it followed.
|
|
14
|
+
- **Everything else** in the folder is organized by sedge itself and read when a task calls for
|
|
15
|
+
it.
|
|
16
|
+
|
|
17
|
+
## What it writes down
|
|
18
|
+
|
|
19
|
+
sedge is told what memory is for, not a fixed scheme for using it. It writes when you ask it to
|
|
20
|
+
remember something, or when something is clearly worth keeping: what it couldn't look up again,
|
|
21
|
+
rules it verified (and how it knows), your preferences, and traps it ran into. It doesn't copy
|
|
22
|
+
things it can read off the world anyway.
|
|
23
|
+
|
|
24
|
+
You can tell it directly: "remember that I deploy on Fridays", "forget the old staging URL".
|
|
25
|
+
|
|
26
|
+
## Recall
|
|
27
|
+
|
|
28
|
+
Every conversation is kept. The `recall` tool searches all of them, newest first: what you said,
|
|
29
|
+
what sedge answered, what tools returned. It's how sedge looks back without having written
|
|
30
|
+
everything down.
|
|
31
|
+
|
|
32
|
+
## Dreaming
|
|
33
|
+
|
|
34
|
+
Notes are written in the moment, and some turn out wrong or go stale. Every night at 03:30 (your
|
|
35
|
+
time) sedge **dreams**: in its own `dream` conversation, nobody waiting, it reads back over recent
|
|
36
|
+
conversations with `recall` and checks its memory against them. It:
|
|
37
|
+
|
|
38
|
+
- corrects notes that turned out wrong or out of date;
|
|
39
|
+
- merges duplicates and deletes what no longer matters;
|
|
40
|
+
- records what it learned and didn't write down;
|
|
41
|
+
- keeps `MEMORY.md` small, moving details into other files and leaving a link.
|
|
42
|
+
|
|
43
|
+
If little happened, it changes little. It doesn't message you.
|
|
44
|
+
|
|
45
|
+
To turn dreaming off, set `"dreaming": false` in `~/.sedge/config.json` and restart the daemon.
|
|
46
|
+
|
|
47
|
+
## Editing it yourself
|
|
48
|
+
|
|
49
|
+
It's your folder. Edit any file; sedge reads it fresh on the next run. In the TUI you can ask the
|
|
50
|
+
agent to change what the daemon remembers.
|
package/docs/meta.json
ADDED
package/docs/security.md
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Security
|
|
3
|
+
description: What sedge may do without you, where secrets live, who can talk to it, and what stays off limits.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
sedge runs with your rights on your machine. These are the limits it keeps.
|
|
7
|
+
|
|
8
|
+
## Runs you watch, and runs you don't
|
|
9
|
+
|
|
10
|
+
- **Watched**: anything you start from the terminal (the TUI, `sedge -p`, `/sedge bg`). Tools run
|
|
11
|
+
as in any coding agent.
|
|
12
|
+
- **Unwatched**: everything else (a Telegram message, a signal, a timer, a dream). Here the
|
|
13
|
+
permission policy applies.
|
|
14
|
+
|
|
15
|
+
## The permission policy
|
|
16
|
+
|
|
17
|
+
| Tool | Unwatched runs |
|
|
18
|
+
| ----------------------------------------------------------------------------- | -------------------------------------- |
|
|
19
|
+
| Reading and searching (`read`, `grep`, `find`, `ls`, `recall`, `tool_search`) | allowed |
|
|
20
|
+
| Writing files (`write`, `edit`) | `permissions.write`, default **allow** |
|
|
21
|
+
| Shell (`bash`) | `permissions.bash`, default **ask** |
|
|
22
|
+
| MCP tools and anything else | `permissions.mcp`, default **ask** |
|
|
23
|
+
| sedge's own (`send_message`, timers) | allowed |
|
|
24
|
+
|
|
25
|
+
`ask` holds the call and sends you the exact command with **Approve** / **Deny** buttons on your
|
|
26
|
+
channel. Approving lets that exact call (same tool, same input) through once; the agent makes it
|
|
27
|
+
again. Denying tells the agent to find another way. With no channel connected, an `ask` call is
|
|
28
|
+
refused. Set any of the three to `allow`, `ask` or `deny` in the [config](./configuration.md).
|
|
29
|
+
|
|
30
|
+
## Off limits, always
|
|
31
|
+
|
|
32
|
+
No run, watched or not, may read or change `~/.sedge/config.json` or the fallback secrets file.
|
|
33
|
+
|
|
34
|
+
## Secrets
|
|
35
|
+
|
|
36
|
+
Tokens and passwords for channels and signals are typed into a hidden field in the TUI. They go
|
|
37
|
+
straight to the daemon and into your OS keychain (one keychain entry per sedge home); they never
|
|
38
|
+
appear in the chat, the model's context, the config or the logs. `disconnect` deletes them. On a
|
|
39
|
+
machine without a keychain, they go to `~/.sedge/secrets.json`, readable only by you.
|
|
40
|
+
|
|
41
|
+
## Who can talk to sedge
|
|
42
|
+
|
|
43
|
+
A channel answers only accounts paired through a one-time invite link that sedge shows on your
|
|
44
|
+
screen. Anyone else gets silence: no error, no hint that a bot is there.
|
|
45
|
+
|
|
46
|
+
## Outside content
|
|
47
|
+
|
|
48
|
+
What a signal reports is framed as data from outside, so instructions inside it aren't followed.
|
|
49
|
+
Project MCP config (`.pi/mcp.json`) isn't read by the daemon, so a repository can't add tools to
|
|
50
|
+
unwatched runs.
|
|
51
|
+
|
|
52
|
+
## Code you add
|
|
53
|
+
|
|
54
|
+
Packages you install and signals you register run inside the daemon with your rights, outside any
|
|
55
|
+
sandbox. sedge asks before installing or registering, and shows you the file to review. What you
|
|
56
|
+
approve is copied, and that copy is what runs.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sedge-hq/sedge",
|
|
3
|
-
"version": "0.0
|
|
3
|
+
"version": "0.1.0",
|
|
4
4
|
"description": "An always-on agent that lives on your machine, built on pi.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -19,10 +19,10 @@
|
|
|
19
19
|
"node": ">=18"
|
|
20
20
|
},
|
|
21
21
|
"optionalDependencies": {
|
|
22
|
-
"@sedge-hq/sedge-darwin-arm64": "0.0
|
|
23
|
-
"@sedge-hq/sedge-darwin-x64": "0.0
|
|
24
|
-
"@sedge-hq/sedge-linux-x64": "0.0
|
|
25
|
-
"@sedge-hq/sedge-linux-arm64": "0.0
|
|
26
|
-
"@sedge-hq/sedge-windows-x64": "0.0
|
|
22
|
+
"@sedge-hq/sedge-darwin-arm64": "0.1.0",
|
|
23
|
+
"@sedge-hq/sedge-darwin-x64": "0.1.0",
|
|
24
|
+
"@sedge-hq/sedge-linux-x64": "0.1.0",
|
|
25
|
+
"@sedge-hq/sedge-linux-arm64": "0.1.0",
|
|
26
|
+
"@sedge-hq/sedge-windows-x64": "0.1.0"
|
|
27
27
|
}
|
|
28
28
|
}
|