malipetek/lab

← All plugins

Host + client · unpublished

Admin

The PTech client portal management panel (ptechsolutions.net): tickets, the work queue and its nodes, system tasks, clients and projects.

@malipetek/dsh-admin

Install

dsh plugin add @malipetek/dsh-admin

Not on npm yet. The name is reserved for the first release, so this command will work once it is.

Package
@malipetek/dsh-admin
Version
1.1.0 (unpublished)
Published
—
Installs / mo
—
Unpacked size
—
Surface
Host + client (web)
License
MIT
Keywords
dsh, dsh-plugin, deepseek-harness, cordis

Documentation

from the package README

The management panel for the PTech client portal (ptechsolutions.net), inside the Harness: the ticket queue with approve, reply and private notes; the work queue and the fleet of machines that run agents on it; Ali's own system tasks; and the clients and projects that decide who may file against what.

What it is

The admin surface is mostly native:

  • Needs you is the default main page. It answers one question — what wants a person now — with KPIs (to approve, to review, clients waiting, running) and the tickets behind them. A cold launch lands here once.
  • Inbox is its own page and sidebar row: every approval, review, client reply, stalled item and stuck queue entry, with filters, search and the same inline actions. Its badge is the actionable count.
  • A run's conversation is the ticket. There is no separate Ticket tab. Above the composer, a native menu-surface strip shows the status, client, project, the client's last message, the thread and the runs, with approve/decline, done/run again and no-reply-needed. The chat input stays the one place to type, and a small segmented mode switch changes where a draft goes: Chat (agent), Reply to client (emails them) or Private note (internal).
  • The full workbench (packages/admin-ui) is one click away for Fleet, SEO, Health, Marketing and settings, instead of being the front door.

Replies made in the conversation land on the ticket. While a run's session is on screen the Client half tells the Host (/admin follow <ticketId> <sessionId>) and the Host turns each new user message in that session log into a private note on the ticket — so the steering reaches the thread and the next run. It starts at the newest message already in the log, so history is never replayed, and it skips what the Harness writes as a user message itself (runtime context, turn clock, model changes, skill and instruction reminders, subagent messages).

The workbench is the shared packages/admin-ui app: the same React app that ptechsolutions.net/portal/admin serves. Like an editor, it has an activity bar, a project explorer, tabs, a status bar and a ⌘K palette. Like a task tracker, it has Needs you, a drag-and-drop Board, a sortable All work list, and ticket pages with the thread, the agent's runs, a composer for client replies or private notes (with Add note and run again), and a details pane. Here every portal call is an /admin api <METHOD> <path> [json] line run by the Host half, which holds the token. The panel sends those lines to a loopback HTTP bridge the Host opens (found once with /admin bridge), not as Harness commands: the Harness logs every command and its full result into the session, and the workbench polls, so one session grew to 10,000 commands and 430 MB. If the bridge is unreachable the panel falls back to commands; the Harness build adds This machine to Fleet and the token field to Settings.

Live in PTech Admin

The plugin is a first-class citizen of the PTech Admin fork, not a page inside it.

  • Clients is a sidebar section, not a blind poll. The fork's sidebar.workspaces.section slot renders Clients → projects → open tickets. Clients are avatar rows that open a client page; projects are folder rows that toggle on the whole row (the chevron also works); tickets are status-dot rows that open the ticket's conversation and carry a small ↗ as the open affordance. Counts sit on clients and projects, and Unsorted keeps a ticket with no client reachable. It reads the three lists once, then reloads only when something changed: the Host's 15-second /admin/attention count diff (four counts, one query), an event from the Host's own 60-second poll, window focus, or the ↻ button. A reload that returns the same data does not re-render, and a five-minute safety pass catches anything the cursors missed.
  • Notifications. When the Host's poll sees a new ticket, a ticket waiting for approval, a client reply, or a finished/failed run, it shows an in-app toast (shell.overlay, so it survives panel switches) and a native banner through the desktop bridge — title "PTech Admin", body like #12 Acme: new request, and clicking it opens ptech-admin://ticket/12. A Harness without the bridge falls back to osascript. The Host diffs the snapshot against the last state it accounted for, so an event is shown once; the seen state lives in $DSH_HOME/admin/notify-state.json (mode 600) and the first run after install marks everything existing as seen instead of flooding. The switch is Settings → Admin → Notify me about new work, which is the same /admin notify on|off command. Bursts are spaced out; more than three changes in one pass become one summary banner.
  • A ticket opens as a conversation when it has one. A ticket row opens the latest run's Harness session (ctx.uiWorkspace.openSession), importing the node's uploaded log through /admin session when this machine does not have it; only a ticket with no session at all falls back to the ticket page in the workbench. The conversation carries the ticket strip above its composer, so the chat and the ticket are one screen.
  • Review. packages/admin-ui/src/review.jsx is the one seam. In the Harness with the Git Graph plugin it opens the native view at the ticket's branch; without it (or on the web) the newest run's recorded comparison is shown; with neither, a link to the portal. The Git Graph plugin publishes its view and focus(repo, ref) on globalThis.__dshGitGraphNative, and the Client half adapts that global into the host.gitGraph face. A fork-side review service addressed by repo/ref — or a way to mount changes-review for an arbitrary comparison — would remove the global.

The plugin registers globalThis.__dshAdminOpenLink(url) and listens for a window event ptech-admin:open-link whose detail.url is the link, so the fork's URL scheme can hand links over without either side importing the other:

Link Opens
ptech-admin://ticket/12 ticket #12 in the Admin panel
ptech-admin://client/<id> that client's page
ptech-admin://seo the SEO desk
ptech-admin://health the health desk
globalThis.__dshAdminOpenLink('ptech-admin://ticket/12');
window.dispatchEvent(new CustomEvent('ptech-admin:open-link', { detail: { url: 'ptech-admin://seo' } }));

openAdminLink returns false for anything it does not know, so the caller can fall back to the browser.

client.js is generated: edit src/client.jsx or packages/admin-ui, then run node packages/dsh-admin/build.mjs.

The sections below describe the previous panel (kept in client.js.bak-workbench-2026-10-23).

Four tabs under a health strip that is always visible: every node with a green / orange / red dot, the queue with how many items are stuck, what is running, and how many tickets wait for approval or review. A node in the strip opens its details.

Anything that creates or edits more than one value opens a modal, and choices from a known set — capabilities, agents, priority, alert times — are chips and segmented buttons, never typed. Anything that emails a client or stops work asks first.

  • Tickets — search and filter, open one to read the thread, approve or decline, and reply or leave a private note from one composer. Routing (priority, needs, agent) shows on the ticket with an Edit routing modal.
  • Fleet — the control room.
    • This machine: the local node (fleet/node.mjs) as launchd sees it and as it reports itself, with Start / Stop / Restart (or Install) and its log.
    • Nodes: every machine the queue knows — online or since when offline, busy slots, executors, capabilities, projects — with Drain and Forget.
    • Queue: every approved item in claim order with the node that will take it, or the reason none can (no folder, node offline, missing capability). Below it, a form to file a system task: title, project, brief, priority, required capabilities, executor. Filing approves it.
    • Running runs with a Cancel button, and recent runs with node, executor, model, cost and duration. A row opens its ticket.
  • Ticket routing — on any ticket: priority, required capabilities, and the pinned executor (client tickets are always claude).
  • Clients & projects — every registered address with the projects linked to it, and a form to create a project. Each project row shows the folder its slug resolves to and a field to point it elsewhere; that mapping is written into the local runner config, the same one the runner reads when a ticket is claimed. A ticket is only workable once its project exists and the runner knows where it lives.
  • Tools — admin_tickets (list, get, reply, note, set_status), admin_directory (clients, projects, create_project, set_folder, link, unlink), admin_work (claim, report, fleet — for doing a ticket inside the Harness), and admin_fleet (queue, nodes, local, file_task, route, cancel, drain, undrain, node_control), so an agent can run the whole system without the panel.

Signing in

PTech Admin signs in through the portal with a deep-link PKCE handoff:

  1. Click Sign in with portal on Needs you, Inbox, or Settings.
  2. The app opens ptechsolutions.net/portal/device in the browser. Sign in with a portal admin account (magic link or six-digit code) and approve the app.
  3. The portal redirects to ptech-admin://auth?code=…; the app exchanges that one-time code with the verifier it kept on disk and stores the session.

The session is stored Host-side at $DSH_HOME/admin/config.json (~/.dsh-admin for PTech Admin, ~/.dsh for the official app; mode 600) and never reaches the browser page. Sessions last 30 days; when one expires the sign-in card returns. /admin signin and /admin login <token> remain available as a shell fallback.

Any address in the Worker's ADMIN_EMAILS signs in with the admin role, so a team can share the portal without sharing one password.

How it works

  • The Host half (index.js) holds the token and calls the Worker with Node's fetch. No CORS allow-list has to grow to include the Harness origin, and the token stays out of the page.
  • Reads go through $DSH_HOME/admin/state.json, a snapshot the Host refreshes every minute and on demand, which the Client reads over the session-scoped file Remote. Opening a ticket writes $DSH_HOME/admin/open-ticket.json, because a thread is only worth fetching when someone looks at it.
  • Writes travel as /admin … commands through remote.commands.execute, so a button press spends no model turn and never enters the conversation. The agent's tools call the same functions — there is no second implementation.
  • Sessions — a global panel gets no Session of its own, so the Client half borrows one for every Host call: the Session the main view retains first (the one you are looking at), then the rest of the list newest first, up to four. A candidate another process owns answers session/writer-held, which is a reason to ask the next one rather than to give up — the Harness's own ACP host keeps a blank Session in the list that way.

Command surface

/admin                              status and help
/admin refresh                      fetch tickets, clients and projects now
/admin open <id>                    load one ticket and its thread for the panel
/admin login <token>                store the portal session token
/admin endpoint <url>               point at another portal Worker
/admin logout                       forget the token
/admin status <id> <status>         set a ticket status
/admin approve <id>                 approve a ticket (emails the client)
/admin reply <id> <text>            reply to the client (emails them)
/admin note <id> <text>             internal note
/admin notify [on|off]              macOS and in-app notifications (no argument reads it)
/admin events [since]               the Client's event feed: changes after a sequence, for toasts
/admin follow <id> <sessionId>     mirror that conversation's replies onto the ticket
/admin unfollow                     stop mirroring
/admin attach <id> {"paths":["~/Desktop/spec.pdf"],"text":"…","internal":false}
                                    post local files (a private note unless internal is false)
/admin download /admin/tickets/<id>/files/<fileId>
                                    save an attachment to ~/Downloads (the panel's file chips use this)
/admin session <runId> <sessionId> <sessionDir>
                                    make a dsh run's Harness conversation openable here: found under
                                    ~/.dsh/sessions/*/<sessionId>/ (or $DSH_HOME), else the log its node
                                    uploaded is downloaded to $DSH_HOME/sessions/<sessionDir>/<sessionId>/
                                    (never over an existing file). Answers {"sessionId","path","imported"};
                                    the run card's "Open conversation" uses it, then opens the session
/admin project <name…> <slug>       create a project
/admin folder <slug> <path>         point a project at a local folder (`-` clears)
/admin link <clientId> <projectId>
/admin unlink <clientId> <projectId>
/admin task {"title","brief","slug",…}  file a system task (approved)
/admin route <id> {"priority"?,"requires"?,"executor"?}
/admin cancel <runId>               stop a run; its item goes to review
/admin drain <node> | undrain <node> | forget <node>
/admin node start|stop|restart|install   this machine's node (launchd)
/admin nodeset <node> {"slots"?,"capabilities"?,"executors"?,"alertOfflineMinutes"?}
/admin settings {"stallMinutes"?,"maxAttempts"?,"notifyRunFinished"?,"defaultPriority"?}
/admin local {"nodeId"?,"slots"?,"timeoutMinutes"?,"maxBudgetUsd"?,"claudeModel"?,…}
/admin projectlocal <slug> {"path"?,"verify"?,"baseRef"?}
/admin toolbox list                 the agent skills and MCP servers on this machine (fleet agents use them)
/admin toolbox add-mcp|remove-mcp|toggle-mcp {"target":"claude"|"opencode",…}
                                    edit them; each write keeps a timestamped .bak-ptech-<ts> (last three)

The three everyday moves also have their own command names, so they appear in the composer's / menu without knowing the subcommand grammar: /admin-approve <id>, /admin-reply <id> <text> and /admin-open <id>. They call the same handler as /admin approve, /admin reply and /admin open.

  • Settings — the queue settings every node shares (stuck-work alert, give-up count, run-finished email, default priority), this machine's node config (name, parallel runs, capabilities, agents, timeout, Claude budget and model, folders), and the portal connection. Per-project folder, verify command and base branch are in Directory → the project.

Endpoints it uses

The default API base is https://ptechsolutions.net/api; /admin endpoint <url> points it anywhere else. https://malipetek.dev/api is the same Worker under its legacy alias, so a config saved against it is read as the default.

Method Path Purpose
GET /admin/tickets the queue
GET /admin/tickets/:id one ticket with its thread
PATCH /admin/tickets/:id status
POST /admin/tickets/:id/messages reply or private note
GET /admin/runs running and recent runs
POST /admin/runs/:id/cancel stop a run
GET /admin/runs/:id/session a dsh run's uploaded session log (zstd), for /admin session
GET /admin/nodes every node, online state, running runs
PATCH / DELETE /admin/nodes/:id drain / forget a node
GET /admin/queue approved items with who takes them, or why nobody can
POST /admin/work file a system task
GET / PATCH /admin/settings queue settings, plus the capability and agent catalogs
GET /admin/clients clients and their project links
GET /admin/projects projects
POST /admin/projects create a project
PUT/DELETE /admin/clients/:userId/projects/:projectId link or unlink

Limits worth knowing

  • The Host polls the portal every 60 seconds; the sidebar is not a blind poller any more — it follows the cheap attention diff and the Host's event feed — but a change still takes up to that minute to reach the Host. A mutation made in the panel refreshes immediately.
  • Status changes and public replies email the client. That is the portal's behaviour, not the panel's.
  • The panel shows the Worker's own status labels, so it cannot drift from what the portal accepts.
  • Project folders belong to the local runner, not the portal: the panel edits the projects entry in ~/.config/malipetek-runner/config.json and leaves projectsRoot and everything else alone. Clearing a slug falls back to <projectsRoot>/<slug>.