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-adminInstall
dsh plugin add @malipetek/dsh-adminNot on npm yet. The name is reserved for the first release, so this command will work once it is.
Package
Browse the source →- 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 READMEThe 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.sectionslot 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/attentioncount 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 opensptech-admin://ticket/12. A Harness without the bridge falls back toosascript. 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|offcommand. 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 sessionwhen 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.jsxis 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 andfocus(repo, ref)onglobalThis.__dshGitGraphNative, and the Client half adapts that global into thehost.gitGraphface. A fork-side review service addressed by repo/ref — or a way to mountchanges-reviewfor an arbitrary comparison — would remove the global.
ptech-admin:// links
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.
- This machine: the local node (
- 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), andadmin_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:
- Click Sign in with portal on Needs you, Inbox, or Settings.
- The app opens
ptechsolutions.net/portal/devicein the browser. Sign in with a portal admin account (magic link or six-digit code) and approve the app. - 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'sfetch. 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 throughremote.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
projectsentry in~/.config/malipetek-runner/config.jsonand leavesprojectsRootand everything else alone. Clearing a slug falls back to<projectsRoot>/<slug>.