Skip to content

Agent Zero AI framework

feat(pin-to-top): support the default No project pin

Alessandro6d0e1a50317d
diff --git a/plugins/_pin_to_top/AGENTS.md b/plugins/_pin_to_top/AGENTS.md
index 0333ee19a..553c4102e 100644
--- a/plugins/_pin_to_top/AGENTS.md
+++ b/plugins/_pin_to_top/AGENTS.md
@@ -14,7 +14,8 @@
## Local Contracts
- Pin state is separated into `chat`, `task`, and `project` groups and stored under the `plugin_pin_to_top` persistent KVP key; older state without `project` remains valid.
-- Project keys are validated project directory names. Adding a project pin requires its project header to exist; removing a stale pin remains possible.
+- Project keys are validated project directory names, with `""` reserved for the virtual **No project** folder. Adding a named project pin requires its project header to exist; removing a stale pin remains possible. Empty chat/task IDs and missing project IDs remain invalid.
+- **No project** is pinned by default with timestamp `1.0`, ahead of dated pins. Persist `no_project_pin_initialized` with pin changes so an explicit unpin survives reloads and changes to other pins; older pin state receives the default without losing existing pins.
- Folder view reads `pins.project`, calls `isProjectPinned(name)` / `toggleProjectPin(name)`, and can sort groups with `sortItems("project", items)` where each item has `id: name`.
- The plugin must register sidebar row-list callbacks; it must not patch chat/task stores or inject controls directly into rows.
- Pinned items sort before unpinned items, older pins remain first, and existing order is preserved within the unpinned group.
diff --git a/plugins/_pin_to_top/README.md b/plugins/_pin_to_top/README.md
index fd09f6f01..a193664cd 100644
--- a/plugins/_pin_to_top/README.md
+++ b/plugins/_pin_to_top/README.md
@@ -7,5 +7,6 @@ Built-in Agent Zero plugin for pinning chats, scheduled tasks, and project folde
- Separates pinned and unpinned items with the standard sidebar divider.
- Persists state in Agent Zero's user key-value storage.
- Folder view uses the same persisted project pins in Chats and Tasks; individual chat and task pins remain independent.
+- **No project** starts pinned and supports the same pin/unpin action as named projects. Unpinning it is remembered across reloads.
The plugin is always enabled and has no configuration screen.
diff --git a/plugins/_pin_to_top/api/toggle_pin.py b/plugins/_pin_to_top/api/toggle_pin.py
index 23589a0a3..fb534ba73 100644
--- a/plugins/_pin_to_top/api/toggle_pin.py
+++ b/plugins/_pin_to_top/api/toggle_pin.py
@@ -7,6 +7,8 @@ class TogglePin(ApiHandler):
async def process(self, input: Input, request: Request) -> Output:
try:
+ if input.get("item_id") is None:
+ raise ValueError("item_id is required")
pinned, timestamp = toggle_pin(
str(input.get("kind", "")),
str(input.get("item_id", "")),
diff --git a/plugins/_pin_to_top/helpers/pins.py b/plugins/_pin_to_top/helpers/pins.py
index 3750343bd..a546d0a4f 100644
--- a/plugins/_pin_to_top/helpers/pins.py
+++ b/plugins/_pin_to_top/helpers/pins.py
@@ -11,6 +11,7 @@ PinKind = Literal["chat", "task", "project"]
STORE_KEY = "plugin_pin_to_top"
KINDS: tuple[PinKind, ...] = ("chat", "task", "project")
+NO_PROJECT_PIN_TIMESTAMP = 1.0
_lock = threading.RLock()
@@ -23,8 +24,9 @@ def get_pins() -> dict[PinKind, dict[str, float]]:
def toggle_pin(kind: str, item_id: str) -> tuple[bool, float]:
"""Toggle a pin and return its new state and timestamp."""
normalized_kind = _require_kind(kind)
- normalized_id = _require_item_id(item_id)
- if normalized_kind == "project":
+ no_project = normalized_kind == "project" and item_id == ""
+ normalized_id = "" if no_project else _require_item_id(item_id)
+ if normalized_kind == "project" and not no_project:
normalized_id = projects.validate_project_name(normalized_id)
with _lock:
@@ -35,22 +37,22 @@ def toggle_pin(kind: str, item_id: str) -> tuple[bool, float]:
timestamp = 0.0
pinned = False
else:
- if normalized_kind == "project" and not os.path.isfile(
+ if normalized_kind == "project" and not no_project and not os.path.isfile(
projects.get_project_meta(normalized_id, projects.PROJECT_HEADER_FILE)
):
raise ValueError("Project not found")
- timestamp = time.time()
+ timestamp = NO_PROJECT_PIN_TIMESTAMP if no_project else time.time()
kind_pins[normalized_id] = timestamp
pinned = True
- kvp.set_persistent(STORE_KEY, pins)
+ kvp.set_persistent(STORE_KEY, {**pins, "no_project_pin_initialized": True})
return pinned, timestamp
def _normalize(value: object) -> dict[PinKind, dict[str, float]]:
normalized: dict[PinKind, dict[str, float]] = {kind: {} for kind in KINDS}
if not isinstance(value, dict):
- return normalized
+ value = {}
for kind in KINDS:
entries = value.get(kind)
@@ -62,9 +64,11 @@ def _normalize(value: object) -> dict[PinKind, dict[str, float]]:
except (TypeError, ValueError):
continue
clean_id = str(item_id).strip()
- if clean_id and clean_timestamp > 0:
+ if (clean_id or (kind == "project" and item_id == "")) and clean_timestamp > 0:
normalized[kind][clean_id] = clean_timestamp
+ if not value.get("no_project_pin_initialized"):
+ normalized["project"].setdefault("", NO_PROJECT_PIN_TIMESTAMP)
return normalized
diff --git a/plugins/_pin_to_top/tests/test_pins.py b/plugins/_pin_to_top/tests/test_pins.py
index 97f292cf6..b4123d753 100644
--- a/plugins/_pin_to_top/tests/test_pins.py
+++ b/plugins/_pin_to_top/tests/test_pins.py
@@ -35,7 +35,7 @@ def test_pins_are_persistent_and_separated_by_kind(monkeypatch, persistent_store
assert pins.get_pins() == {
"chat": {"chat-1": 100.0},
"task": {"task-1": 200.0},
- "project": {},
+ "project": {"": 1.0},
}
assert pins.toggle_pin("chat", "chat-1") == (False, 0.0)
@@ -51,9 +51,15 @@ def test_invalid_pin_input_is_rejected(kind, item_id, persistent_store):
pins.toggle_pin(kind, item_id)
-def test_toggle_api_returns_a_bad_request_for_invalid_input(persistent_store):
[email protected]("payload", [
+ {"kind": "unknown", "item_id": "item-1"},
+ {"kind": "project"},
+ {"kind": "project", "item_id": None},
+ {"kind": "project", "item_id": " "},
+])
+def test_toggle_api_returns_a_bad_request_for_invalid_input(payload, persistent_store):
response = asyncio.run(
- TogglePin(None, None).process({"kind": "unknown", "item_id": "item-1"}, None)
+ TogglePin(None, None).process(payload, None)
)
assert response.status_code == 400
@@ -69,7 +75,7 @@ def test_project_pins_validate_projects_and_preserve_legacy_pins(
header.parent.mkdir(parents=True)
header.write_text("{}")
- assert pins.get_pins()["project"] == {}
+ assert pins.get_pins()["project"] == {"": 1.0}
response = asyncio.run(
TogglePin(None, None).process({"kind": "project", "item_id": "my-project"}, None)
)
@@ -77,7 +83,7 @@ def test_project_pins_validate_projects_and_preserve_legacy_pins(
assert asyncio.run(GetPins(None, None).process({}, None))["pins"] == {
"chat": {"chat-1": 100.0},
"task": {"task-1": 200.0},
- "project": {"my-project": 300.0},
+ "project": {"my-project": 300.0, "": 1.0},
}
for name in ("../my-project", "missing-project"):
response = asyncio.run(
@@ -87,7 +93,27 @@ def test_project_pins_validate_projects_and_preserve_legacy_pins(
header.unlink()
assert pins.toggle_pin("project", "my-project") == (False, 0.0)
- assert pins.get_pins()["project"] == {}
+ assert pins.get_pins()["project"] == {"": 1.0}
+
+
[email protected]("legacy", [{}, {"project": {"existing-project": 200.0}}])
+def test_no_project_starts_pinned_and_remembers_unpinning(legacy, persistent_store):
+ persistent_store[pins.STORE_KEY] = legacy
+ assert pins.get_pins()["project"] == {**legacy.get("project", {}), "": 1.0}
+ handler = TogglePin(None, None)
+ payload = {"kind": "project", "item_id": ""}
+
+ assert asyncio.run(handler.process(payload, None)) == {
+ "ok": True, "pinned": False, "timestamp": 0.0,
+ }
+ assert pins.get_pins()["project"] == legacy.get("project", {})
+ pins.toggle_pin("chat", "another-chat")
+ assert pins.get_pins()["project"] == legacy.get("project", {})
+
+ assert asyncio.run(handler.process(payload, None)) == {
+ "ok": True, "pinned": True, "timestamp": 1.0,
+ }
+ assert pins.get_pins()["project"] == {**legacy.get("project", {}), "": 1.0}
@pytest.mark.skipif(not shutil.which("node"), reason="node is required")
@@ -100,9 +126,14 @@ const source = readFileSync(process.argv[1], 'utf8')
.replace(/^import .*;$/gm, '')
.replace('export const store = createStore("pinToTop", model);', 'globalThis.store = model;');
const calls = [];
+let noProjectPinned = false;
const context = {
callJsonApi: async (path, input) => {
calls.push([path, input]);
+ if (input.kind === 'project' && input.item_id === '') {
+ noProjectPinned = !noProjectPinned;
+ return { pinned: noProjectPinned, timestamp: noProjectPinned ? 1 : 0 };
+ }
return { pinned: calls.length === 1, timestamp: 300 };
},
toastFrontendError: message => { throw new Error(message); },
@@ -124,6 +155,18 @@ assert.equal(store.sortItems('project', rows).map(item => item.id).join(','), 'c
await store.toggleFromMenu('task:task-1', 'task');
assert.equal(calls[2][1].kind, 'task');
assert.equal(calls[2][1].item_id, 'task-1');
+store.pins.project.constructor = 200;
+await store.toggleProjectPin('');
+assert.equal(calls[3][1].item_id, '');
+assert.equal(store.isProjectPinned(''), true);
+assert.equal(store.sortItems('project', [...rows, { id: '' }])[0].id, '');
+await store.toggleProjectPin('');
+assert.equal(store.isProjectPinned(''), false);
+assert.equal(store.isProjectPinned('constructor'), true);
+const callCount = calls.length;
+await store.togglePin('chat', '');
+await store.toggleProjectPin(undefined);
+assert.equal(calls.length, callCount, 'only an explicit empty project ID represents No project');
"""
store = Path(__file__).resolve().parents[1] / "webui" / "pin-to-top-store.js"
subprocess.run(["node", "--input-type=module", "-e", script, str(store)], check=True)
diff --git a/plugins/_pin_to_top/webui/pin-to-top-store.js b/plugins/_pin_to_top/webui/pin-to-top-store.js
index b50302e91..b205d1ebf 100644
--- a/plugins/_pin_to_top/webui/pin-to-top-store.js
+++ b/plugins/_pin_to_top/webui/pin-to-top-store.js
@@ -50,7 +50,7 @@ const model = {
},
async togglePin(kind, itemId) {
- if (!itemId) return;
+ if (!itemId && !(kind === "project" && itemId === "")) return;
try {
const response = await callJsonApi(`/plugins/${PLUGIN_ID}/toggle_pin`, {