@tivility/dsh-session-share 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# @tivility/dsh-session-share
+
+A link that opens one session.
+
+## The gap this fills
+
+The harness's GUI opens wherever it was left. There is no URL that means *this
+conversation* — the client carries **no routing at all** (search it for
+`pushState`, `location.hash`, or `searchParams` and you find nothing), and the
+selected session is restored from persisted state on load.
+
+So a session cannot be pointed at. Not in a message, not in a ticket, not by
+the agent describing its own work. "It's the third one down, from Tuesday" is
+the state of the art.
+
+This adds the one missing step:
+
+```
+http://127.0.0.1:3080/?session=<id>     ← opens that session
+http://127.0.0.1:3080/s/<id>            ← redirects to the same place
+```
+
+The agent is taught the format, so it can hand out a link to the conversation
+you are in, to a subagent it started, or to a session it forked.
+
+## What it does not do
+
+**It shares nothing and hides nothing.** The sidebar, the other sessions, and
+the composer are exactly as they would be. The link decides where a visitor
+lands, not what they can see.
+
+That is a deliberate limit rather than an oversight. Hiding the sidebar would
+*look* like isolation while `/api` went on answering every question about every
+other session — visual privacy, which is the kind that gets people in trouble.
+Restricting what a visitor can reach is
+[`@tivility/dsh-readonly-auth`](../readonly-auth)'s job, and it does it at the
+API rather than in the DOM.
+
+## How it works
+
+Two halves, which is what the harness's client-module system is for.
+
+**The browser half** reads `?session=`, waits for the session list, calls
+`sessions.open(id)`, then strips the parameter from the address bar.
+
+Two details carry their weight:
+
+- **The wait is on the list's phase, not a timeout.** `open()` fails loud on an
+  id the list does not carry, and the list arrives asynchronously — so `phase:
+  'ready'` is what separates "not loaded yet" from "no such session". A timeout
+  would be guessing.
+- **The parameter is consumed once.** The selection is persisted, so leaving it
+  in the URL would make every later reload jump back to the linked session,
+  fighting the user each time they navigate away and refresh. Consuming it
+  makes the link mean "start here", which is what a link means.
+
+**The node half** serves the `/s/<id>` redirect and registers the prompt
+section. The short form has to be a redirect rather than a page: the GUI is
+served only at the root — the harness's static fallback answers `/` and
+`/index.html` and 404s everything else, with no SPA rewrite — so `/s/<id>`
+would otherwise be a 404. The id is validated before it becomes a `Location`,
+because an unconstrained value in a response header is where header injection
+lives.
+
+## Building the browser bundle
+
+This is the only package here with a browser half, so it is the only one that
+needs a bundler:
+
+```sh
+pnpm --filter @tivility/dsh-session-share run bundle
+```
+
+after the usual `pnpm run build`. The bundle must exist before the harness
+loads the plugin; without it the client-module scanner reports a missing
+bundle at startup.
+
+`tsdown.config.ts` restates the harness's loader contract — CJS on a browser
+platform, the `__ModuleLoader__.load` handoff, externals limited to the
+loader's module table, source maps. The harness ships a preset for this, but it
+is repository-bound (it locates packages by globbing inside the harness
+checkout), so the four rules are written out instead. They are short, and they
+are the whole of what makes a bundle loadable.
+
+## Configuration
+
+```yaml
+- id: session-share
+  name: '@tivility/dsh-session-share'
+  config:
+    route: /s              # empty mounts no redirect, leaving the query form
+    prompt: true           # teach the model the link format
+    trustedHosts: []
+```
+
+The `?session=` parameter name is a constant, not configuration: the two halves
+cannot share a configured value — the browser bundle is fetched outside the
+loader's config tree — and a constant is the honest form of something that has
+to match in two places.
+
+## License
+
+MIT

package/lib/client/index.js

@@ -0,0 +1,81 @@
+/**
+ * The browser half: open the session a link names.
+ *
+ * The harness's GUI has no routing — the whole client is searched in vain for
+ * `pushState`, `location.hash`, or `searchParams`. The selected session lives
+ * in the sessions manager and is restored from persisted state on load, so a
+ * URL naming one has nowhere to be read. This adds that one step and nothing
+ * else: read the parameter, select the session, get out of the way.
+ *
+ * It deliberately hides nothing. The sidebar, the other sessions, and the
+ * composer are all exactly as they would be — the link decides where you land,
+ * not what you can see.
+ *
+ * ## Why the context is typed here
+ *
+ * The two halves of this package compile in one TypeScript program, and the
+ * node half pulls in the harness's HOST augmentations of `Context` — where
+ * `sessions` is a different service with the same name. Importing
+ * `ClientContext` would therefore resolve `ctx.sessions` to the host's shape.
+ * The harness avoids this with separate client and host programs; a two-file
+ * package states the three members it uses instead, which also leaves this
+ * half with no harness type dependency at all.
+ * @module @tivility/dsh-session-share/client
+ */
+import { SESSION_PARAM } from '../param.js';
+/** Client-side services this plugin drives. */
+export const inject = ['sessions'];
+/**
+ * Remove the parameter from the address bar once it has been acted on.
+ *
+ * The selection is persisted by the runtime, so leaving the parameter in place
+ * would make every later reload jump back to the linked session — fighting the
+ * user each time they navigate away and refresh. Consuming it once makes the
+ * link mean "start here", which is what a link means.
+ */
+function stripParam() {
+    const url = new URL(window.location.href);
+    if (!url.searchParams.has(SESSION_PARAM))
+        return;
+    url.searchParams.delete(SESSION_PARAM);
+    window.history.replaceState(window.history.state, '', `${url.pathname}${url.search}${url.hash}`);
+}
+/**
+ * Watch the session list until the named session can be opened.
+ * @param ctx - the client root context.
+ */
+export function apply(ctx) {
+    const requested = new URL(window.location.href).searchParams.get(SESSION_PARAM);
+    // No parameter is the overwhelmingly common case — every ordinary visit — so
+    // this plugin costs nothing at all when it has nothing to do.
+    if (requested === null || requested === '')
+        return;
+    ctx.effect(() => {
+        let done = false;
+        const attempt = () => {
+            if (done)
+                return;
+            const state = ctx.sessions.list.getSnapshot();
+            if (state.byId[requested] !== undefined) {
+                done = true;
+                ctx.sessions.open(requested);
+                stripParam();
+                return;
+            }
+            // The list arrives asynchronously, so an id that is absent right now may
+            // simply not have loaded. The phase is what separates "not yet" from "no
+            // such session" — a timeout would guess at it.
+            if (state.phase === 'ready') {
+                done = true;
+                stripParam();
+                ctx.logger?.warn?.(`session-share: no session ${requested} in this harness`);
+            }
+        };
+        const unsubscribe = ctx.sessions.list.subscribe(attempt);
+        // The list may already be ready before this plugin activates, in which case
+        // no change is ever published and the subscription alone would wait forever.
+        attempt();
+        return unsubscribe;
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AA8B3C,+CAA+C;AAC/C,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,UAAU,CAAC,CAAA;AAElC;;;;;;;GAOG;AACH,SAAS,UAAU;IACjB,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IACzC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,aAAa,CAAC;QAAE,OAAM;IAChD,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,aAAa,CAAC,CAAA;IACtC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,EAAE,GAAG,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,CAAA;AAClG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,GAAiB;IACrC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,aAAa,CAAC,CAAA;IAC/E,6EAA6E;IAC7E,8DAA8D;IAC9D,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,EAAE;QAAE,OAAM;IAElD,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE;QACd,IAAI,IAAI,GAAG,KAAK,CAAA;QAChB,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,IAAI,IAAI;gBAAE,OAAM;YAChB,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,CAAA;YAC7C,IAAI,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;gBACxC,IAAI,GAAG,IAAI,CAAA;gBACX,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;gBAC5B,UAAU,EAAE,CAAA;gBACZ,OAAM;YACR,CAAC;YACD,yEAAyE;YACzE,yEAAyE;YACzE,+CAA+C;YAC/C,IAAI,KAAK,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;gBAC5B,IAAI,GAAG,IAAI,CAAA;gBACX,UAAU,EAAE,CAAA;gBACZ,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,6BAA6B,SAAS,kBAAkB,CAAC,CAAA;YAC9E,CAAC;QACH,CAAC,CAAA;QACD,MAAM,WAAW,GAAG,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QACxD,4EAA4E;QAC5E,6EAA6E;QAC7E,OAAO,EAAE,CAAA;QACT,OAAO,WAAW,CAAA;IACpB,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/lib/client.js

@@ -0,0 +1,96 @@
+window.__ModuleLoader__.load({ id: "@tivility/dsh-session-share", factory: (require) => {
+var module = { exports: {} }; var exports = module.exports;
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region lib/param.js
+/**
+* The one fact both halves of this plugin have to agree on.
+*
+* The query parameter is a constant rather than configuration because the two
+* halves cannot share a configuration value: the browser bundle is fetched
+* outside the loader's config tree and receives only what its own `apply`
+* is handed, while the link the host writes into the system prompt is built
+* on the other side of the wire. A constant is the honest form of a value
+* that must match in two places.
+* @module @tivility/dsh-session-share/param
+*/
+/** Query parameter naming the session to open on load. */
+const SESSION_PARAM = "session";
+
+//#endregion
+//#region lib/client/index.js
+/**
+* The browser half: open the session a link names.
+*
+* The harness's GUI has no routing — the whole client is searched in vain for
+* `pushState`, `location.hash`, or `searchParams`. The selected session lives
+* in the sessions manager and is restored from persisted state on load, so a
+* URL naming one has nowhere to be read. This adds that one step and nothing
+* else: read the parameter, select the session, get out of the way.
+*
+* It deliberately hides nothing. The sidebar, the other sessions, and the
+* composer are all exactly as they would be — the link decides where you land,
+* not what you can see.
+*
+* ## Why the context is typed here
+*
+* The two halves of this package compile in one TypeScript program, and the
+* node half pulls in the harness's HOST augmentations of `Context` — where
+* `sessions` is a different service with the same name. Importing
+* `ClientContext` would therefore resolve `ctx.sessions` to the host's shape.
+* The harness avoids this with separate client and host programs; a two-file
+* package states the three members it uses instead, which also leaves this
+* half with no harness type dependency at all.
+* @module @tivility/dsh-session-share/client
+*/
+/** Client-side services this plugin drives. */
+const inject = ["sessions"];
+/**
+* Remove the parameter from the address bar once it has been acted on.
+*
+* The selection is persisted by the runtime, so leaving the parameter in place
+* would make every later reload jump back to the linked session — fighting the
+* user each time they navigate away and refresh. Consuming it once makes the
+* link mean "start here", which is what a link means.
+*/
+function stripParam() {
+	const url = new URL(window.location.href);
+	if (!url.searchParams.has(SESSION_PARAM)) return;
+	url.searchParams.delete(SESSION_PARAM);
+	window.history.replaceState(window.history.state, "", `${url.pathname}${url.search}${url.hash}`);
+}
+/**
+* Watch the session list until the named session can be opened.
+* @param ctx - the client root context.
+*/
+function apply(ctx) {
+	const requested = new URL(window.location.href).searchParams.get(SESSION_PARAM);
+	if (requested === null || requested === "") return;
+	ctx.effect(() => {
+		let done = false;
+		const attempt = () => {
+			if (done) return;
+			const state = ctx.sessions.list.getSnapshot();
+			if (state.byId[requested] !== void 0) {
+				done = true;
+				ctx.sessions.open(requested);
+				stripParam();
+				return;
+			}
+			if (state.phase === "ready") {
+				done = true;
+				stripParam();
+				ctx.logger?.warn?.(`session-share: no session ${requested} in this harness`);
+			}
+		};
+		const unsubscribe = ctx.sessions.list.subscribe(attempt);
+		attempt();
+		return unsubscribe;
+	});
+}
+
+//#endregion
+exports.apply = apply;
+exports.inject = inject;
+return module.exports; } });
+//# sourceMappingURL=client.js.map

package/lib/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["param.js","client/index.js"],"sourcesContent":["/**\n * The one fact both halves of this plugin have to agree on.\n *\n * The query parameter is a constant rather than configuration because the two\n * halves cannot share a configuration value: the browser bundle is fetched\n * outside the loader's config tree and receives only what its own `apply`\n * is handed, while the link the host writes into the system prompt is built\n * on the other side of the wire. A constant is the honest form of a value\n * that must match in two places.\n * @module @tivility/dsh-session-share/param\n */\n/** Query parameter naming the session to open on load. */\nexport const SESSION_PARAM = 'session';\n/**\n * Build the query a share link carries.\n * @param sessionId - the session to open.\n * @returns the query string, question mark included.\n */\nexport function shareQuery(sessionId) {\n    return `?${SESSION_PARAM}=${encodeURIComponent(sessionId)}`;\n}\n//# sourceMappingURL=param.js.map","/**\n * The browser half: open the session a link names.\n *\n * The harness's GUI has no routing — the whole client is searched in vain for\n * `pushState`, `location.hash`, or `searchParams`. The selected session lives\n * in the sessions manager and is restored from persisted state on load, so a\n * URL naming one has nowhere to be read. This adds that one step and nothing\n * else: read the parameter, select the session, get out of the way.\n *\n * It deliberately hides nothing. The sidebar, the other sessions, and the\n * composer are all exactly as they would be — the link decides where you land,\n * not what you can see.\n *\n * ## Why the context is typed here\n *\n * The two halves of this package compile in one TypeScript program, and the\n * node half pulls in the harness's HOST augmentations of `Context` — where\n * `sessions` is a different service with the same name. Importing\n * `ClientContext` would therefore resolve `ctx.sessions` to the host's shape.\n * The harness avoids this with separate client and host programs; a two-file\n * package states the three members it uses instead, which also leaves this\n * half with no harness type dependency at all.\n * @module @tivility/dsh-session-share/client\n */\nimport { SESSION_PARAM } from '../param.js';\n/** Client-side services this plugin drives. */\nexport const inject = ['sessions'];\n/**\n * Remove the parameter from the address bar once it has been acted on.\n *\n * The selection is persisted by the runtime, so leaving the parameter in place\n * would make every later reload jump back to the linked session — fighting the\n * user each time they navigate away and refresh. Consuming it once makes the\n * link mean \"start here\", which is what a link means.\n */\nfunction stripParam() {\n    const url = new URL(window.location.href);\n    if (!url.searchParams.has(SESSION_PARAM))\n        return;\n    url.searchParams.delete(SESSION_PARAM);\n    window.history.replaceState(window.history.state, '', `${url.pathname}${url.search}${url.hash}`);\n}\n/**\n * Watch the session list until the named session can be opened.\n * @param ctx - the client root context.\n */\nexport function apply(ctx) {\n    const requested = new URL(window.location.href).searchParams.get(SESSION_PARAM);\n    // No parameter is the overwhelmingly common case — every ordinary visit — so\n    // this plugin costs nothing at all when it has nothing to do.\n    if (requested === null || requested === '')\n        return;\n    ctx.effect(() => {\n        let done = false;\n        const attempt = () => {\n            if (done)\n                return;\n            const state = ctx.sessions.list.getSnapshot();\n            if (state.byId[requested] !== undefined) {\n                done = true;\n                ctx.sessions.open(requested);\n                stripParam();\n                return;\n            }\n            // The list arrives asynchronously, so an id that is absent right now may\n            // simply not have loaded. The phase is what separates \"not yet\" from \"no\n            // such session\" — a timeout would guess at it.\n            if (state.phase === 'ready') {\n                done = true;\n                stripParam();\n                ctx.logger?.warn?.(`session-share: no session ${requested} in this harness`);\n            }\n        };\n        const unsubscribe = ctx.sessions.list.subscribe(attempt);\n        // The list may already be ready before this plugin activates, in which case\n        // no change is ever published and the subscription alone would wait forever.\n        attempt();\n        return unsubscribe;\n    });\n}\n//# sourceMappingURL=index.js.map"],"mappings":";;;;;;;;;;;;;;;;;AAYA,MAAa,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACc7B,MAAa,SAAS,CAAC,WAAW;;;;;;;;;AASlC,SAAS,aAAa;CAClB,MAAM,MAAM,IAAI,IAAI,OAAO,SAAS,KAAK;AACzC,KAAI,CAAC,IAAI,aAAa,IAAI,cAAc,CACpC;AACJ,KAAI,aAAa,OAAO,cAAc;AACtC,QAAO,QAAQ,aAAa,OAAO,QAAQ,OAAO,IAAI,GAAG,IAAI,WAAW,IAAI,SAAS,IAAI,OAAO;;;;;;AAMpG,SAAgB,MAAM,KAAK;CACvB,MAAM,YAAY,IAAI,IAAI,OAAO,SAAS,KAAK,CAAC,aAAa,IAAI,cAAc;AAG/E,KAAI,cAAc,QAAQ,cAAc,GACpC;AACJ,KAAI,aAAa;EACb,IAAI,OAAO;EACX,MAAM,gBAAgB;AAClB,OAAI,KACA;GACJ,MAAM,QAAQ,IAAI,SAAS,KAAK,aAAa;AAC7C,OAAI,MAAM,KAAK,eAAe,QAAW;AACrC,WAAO;AACP,QAAI,SAAS,KAAK,UAAU;AAC5B,gBAAY;AACZ;;AAKJ,OAAI,MAAM,UAAU,SAAS;AACzB,WAAO;AACP,gBAAY;AACZ,QAAI,QAAQ,OAAO,6BAA6B,UAAU,kBAAkB;;;EAGpF,MAAM,cAAc,IAAI,SAAS,KAAK,UAAU,QAAQ;AAGxD,WAAS;AACT,SAAO;GACT"}

package/lib/index.js

@@ -0,0 +1,136 @@
+/**
+ * Link straight to one session.
+ *
+ * The harness's GUI opens wherever it was left. There is no URL that means
+ * "this conversation" — the whole client carries no routing at all, and the
+ * selected session is restored from persisted state. So a session cannot be
+ * pointed at: not in a message, not in a ticket, not by the agent describing
+ * its own work.
+ *
+ * This plugin adds the one missing step. The browser half reads a `?session=`
+ * parameter and selects that session; this half serves a short redirect route
+ * and teaches the model the link format so it can hand out links to the
+ * conversations it starts.
+ *
+ * **It shares nothing.** Every session stays visible and the GUI is otherwise
+ * untouched — the link decides where a visitor lands, not what they can see.
+ * Restricting that is what `@tivility/dsh-readonly-auth` is for, and this
+ * plugin deliberately does not pretend to do it: hiding the sidebar would look
+ * like isolation while `/api` still answered every question about every other
+ * session.
+ * @module @tivility/dsh-session-share
+ */
+import z from '@deepseek-ai/schemastery';
+import { absoluteUrl, isTrustedRequest, sendStatus } from '@tivility/dsh-web-kit';
+import { SESSION_PARAM, shareQuery } from './param.js';
+export { SESSION_PARAM, shareQuery } from './param.js';
+/** Stable Cordis plugin name. */
+export const name = 'session-share';
+/** The HTTP carrier this plugin mounts its redirect on. */
+export const inject = ['webServer'];
+export const Config = z.object({
+    route: z.string().default('/s'),
+    prompt: z.boolean().default(true),
+    trustedHosts: z.array(String).default([]),
+});
+/** A session id as it may appear in a URL: the harness mints uuids. */
+const SESSION_ID = /^[A-Za-z0-9_-]{1,128}$/;
+/**
+ * Build the redirect handler for the short link form.
+ *
+ * A redirect rather than a page, because the GUI is a single-page app served
+ * only at the root: the harness's static fallback serves `index.html` for `/`
+ * and `/index.html` and 404s everything else, with no SPA rewrite. `/s/<id>`
+ * would therefore be a 404, so the short form bounces to the query form the
+ * browser half reads.
+ * @param route - the configured prefix.
+ * @param trustedHosts - authorities the fence accepts.
+ * @returns the route handler.
+ */
+function createHandler(route, trustedHosts) {
+    return (req, res) => {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            sendStatus(res, 405, 'method not allowed', { allow: 'GET, HEAD' });
+            return;
+        }
+        if (!isTrustedRequest(req, trustedHosts)) {
+            sendStatus(res, 403, 'forbidden');
+            return;
+        }
+        /* v8 ignore next -- node:http always sets url on server requests */
+        const pathname = new URL(req.url ?? '/', 'http://x').pathname;
+        let id;
+        try {
+            id = decodeURIComponent(pathname.slice(route.length).replace(/^\//, ''));
+        }
+        catch {
+            sendStatus(res, 400, 'malformed session id');
+            return;
+        }
+        // Validated before it becomes a Location: the value lands in a header, and
+        // an unconstrained one is where header injection lives.
+        if (!SESSION_ID.test(id)) {
+            sendStatus(res, 400, 'malformed session id');
+            return;
+        }
+        res.writeHead(302, { location: `/${shareQuery(id)}` });
+        res.end();
+    };
+}
+/**
+ * The system prompt section teaching the model this link format.
+ * @param ctx - a context carrying the `webServer` service.
+ * @param route - the configured short-link prefix.
+ * @param sessionId - the session the calling agent belongs to.
+ * @returns the prompt text.
+ */
+function promptSection(ctx, route, sessionId) {
+    const base = absoluteUrl(ctx, '/');
+    const link = `${base}${shareQuery(sessionId)}`;
+    const shortForm = route === ''
+        ? ''
+        : ` The shorter ${absoluteUrl(ctx, route)}/${sessionId} redirects to the same place.`;
+    return [
+        `This conversation has a direct link: ${link}`,
+        `Opening it in a browser selects this session instead of whatever was last open.${shortForm}`,
+        'Give it to the user when they need to come back to this conversation, point someone at it,',
+        'or file it somewhere. Any session id works in the same shape — a subagent you started,',
+        'a session you forked — so a link can point at that one instead of this one.',
+        'The link decides which session opens, not who may read it: everyone who can reach the',
+        'harness sees the same thing they would see without it.',
+    ].join(' ');
+}
+/**
+ * Mount the redirect route and the prompt section.
+ * @param ctx - plugin context carrying the injected `webServer` service.
+ * @param config - plugin configuration.
+ */
+export function apply(ctx, config = {}) {
+    const route = config.route ?? '/s';
+    const trustedHosts = config.trustedHosts ?? [];
+    if (route !== '') {
+        if (!route.startsWith('/') || route.endsWith('/')) {
+            throw new Error(`session-share: route ${JSON.stringify(route)} must be an absolute path without a trailing slash`);
+        }
+        ctx.effect(() => ctx.webServer.register({
+            kind: 'prefix',
+            path: route,
+            handler: createHandler(route, trustedHosts),
+        }), `session-share: ${route} route`);
+    }
+    if (config.prompt === false)
+        return;
+    ctx.inject(['systemPrompt'], (scope) => {
+        scope.systemPrompt.section({
+            name: 'session-share',
+            order: 91,
+            text: (context) => {
+                // Resolved per assembly: the port is known only after the server binds,
+                // and the session id is whichever agent this prompt is being built for.
+                const sessionId = context.agent?.session.id;
+                return sessionId === undefined ? '' : promptSection(scope, route, String(sessionId));
+            },
+        });
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/param.js

@@ -0,0 +1,22 @@
+/**
+ * The one fact both halves of this plugin have to agree on.
+ *
+ * The query parameter is a constant rather than configuration because the two
+ * halves cannot share a configuration value: the browser bundle is fetched
+ * outside the loader's config tree and receives only what its own `apply`
+ * is handed, while the link the host writes into the system prompt is built
+ * on the other side of the wire. A constant is the honest form of a value
+ * that must match in two places.
+ * @module @tivility/dsh-session-share/param
+ */
+/** Query parameter naming the session to open on load. */
+export const SESSION_PARAM = 'session';
+/**
+ * Build the query a share link carries.
+ * @param sessionId - the session to open.
+ * @returns the query string, question mark included.
+ */
+export function shareQuery(sessionId) {
+    return `?${SESSION_PARAM}=${encodeURIComponent(sessionId)}`;
+}
+//# sourceMappingURL=param.js.map

package/lib/param.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"param.js","sourceRoot":"","sources":["../src/param.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,0DAA0D;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAA;AAEtC;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,SAAiB;IAC1C,OAAO,IAAI,aAAa,IAAI,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAA;AAC7D,CAAC"}

package/lib/types/client/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The browser half: open the session a link names.
+ *
+ * The harness's GUI has no routing — the whole client is searched in vain for
+ * `pushState`, `location.hash`, or `searchParams`. The selected session lives
+ * in the sessions manager and is restored from persisted state on load, so a
+ * URL naming one has nowhere to be read. This adds that one step and nothing
+ * else: read the parameter, select the session, get out of the way.
+ *
+ * It deliberately hides nothing. The sidebar, the other sessions, and the
+ * composer are all exactly as they would be — the link decides where you land,
+ * not what you can see.
+ *
+ * ## Why the context is typed here
+ *
+ * The two halves of this package compile in one TypeScript program, and the
+ * node half pulls in the harness's HOST augmentations of `Context` — where
+ * `sessions` is a different service with the same name. Importing
+ * `ClientContext` would therefore resolve `ctx.sessions` to the host's shape.
+ * The harness avoids this with separate client and host programs; a two-file
+ * package states the three members it uses instead, which also leaves this
+ * half with no harness type dependency at all.
+ * @module @tivility/dsh-session-share/client
+ */
+/** The session-list snapshot this plugin reads. */
+interface SessionListSnapshot {
+    /** Every listed session, keyed by id. */
+    readonly byId: Readonly<Record<string, unknown>>;
+    /** Whether the list has finished arriving. */
+    readonly phase: 'pending' | 'ready';
+}
+/** The part of the client sessions service this plugin drives. */
+interface SessionsFace {
+    readonly list: {
+        getSnapshot(): SessionListSnapshot;
+        subscribe(listener: () => void): () => void;
+    };
+    /**
+     * Select a session as current. Fails loud on an id the list does not carry,
+     * which is why the phase below is consulted first.
+     */
+    open(id: string): void;
+}
+/** The client context members this plugin uses. */
+interface ShareContext {
+    readonly sessions: SessionsFace;
+    effect(run: () => () => void): unknown;
+    readonly logger?: {
+        warn?(message: string): void;
+    };
+}
+/** Client-side services this plugin drives. */
+export declare const inject: string[];
+/**
+ * Watch the session list until the named session can be opened.
+ * @param ctx - the client root context.
+ */
+export declare function apply(ctx: ShareContext): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,mDAAmD;AACnD,UAAU,mBAAmB;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAChD,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAA;CACpC;AAED,kEAAkE;AAClE,UAAU,YAAY;IACpB,QAAQ,CAAC,IAAI,EAAE;QACb,WAAW,IAAI,mBAAmB,CAAA;QAClC,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;KAC5C,CAAA;IACD;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,mDAAmD;AACnD,UAAU,YAAY;IACpB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,MAAM,CAAC,GAAG,EAAE,MAAM,MAAM,IAAI,GAAG,OAAO,CAAA;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;CACnD;AAED,+CAA+C;AAC/C,eAAO,MAAM,MAAM,UAAe,CAAA;AAiBlC;;;GAGG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAgC7C"}

package/lib/types/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Link straight to one session.
+ *
+ * The harness's GUI opens wherever it was left. There is no URL that means
+ * "this conversation" — the whole client carries no routing at all, and the
+ * selected session is restored from persisted state. So a session cannot be
+ * pointed at: not in a message, not in a ticket, not by the agent describing
+ * its own work.
+ *
+ * This plugin adds the one missing step. The browser half reads a `?session=`
+ * parameter and selects that session; this half serves a short redirect route
+ * and teaches the model the link format so it can hand out links to the
+ * conversations it starts.
+ *
+ * **It shares nothing.** Every session stays visible and the GUI is otherwise
+ * untouched — the link decides where a visitor lands, not what they can see.
+ * Restricting that is what `@tivility/dsh-readonly-auth` is for, and this
+ * plugin deliberately does not pretend to do it: hiding the sidebar would look
+ * like isolation while `/api` still answered every question about every other
+ * session.
+ * @module @tivility/dsh-session-share
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { SESSION_PARAM, shareQuery } from './param.js';
+/** Stable Cordis plugin name. */
+export declare const name = "session-share";
+/** The HTTP carrier this plugin mounts its redirect on. */
+export declare const inject: string[];
+/** Plugin configuration. */
+export interface Config {
+    /**
+     * Prefix for the short link form, `<route>/<session-id>`. Empty mounts no
+     * route, leaving only the query form.
+     */
+    route?: string;
+    /** Teach the model the link format so it can hand out links to its own sessions. */
+    prompt?: boolean;
+    /** Non-loopback authorities this deployment serves, as `host` or `host:port`. */
+    trustedHosts?: string[];
+}
+export declare const Config: z<Config>;
+/**
+ * Mount the redirect route and the prompt section.
+ * @param ctx - plugin context carrying the injected `webServer` service.
+ * @param config - plugin configuration.
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAQxC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAEtD,iCAAiC;AACjC,eAAO,MAAM,IAAI,kBAAkB,CAAA;AAEnC,2DAA2D;AAC3D,eAAO,MAAM,MAAM,UAAgB,CAAA;AAEnC,4BAA4B;AAC5B,MAAM,WAAW,MAAM;IACrB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oFAAoF;IACpF,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CACxB;AAED,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAI3B,CAAA;AA0EF;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI,CA2B7D"}

package/lib/types/param.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The one fact both halves of this plugin have to agree on.
+ *
+ * The query parameter is a constant rather than configuration because the two
+ * halves cannot share a configuration value: the browser bundle is fetched
+ * outside the loader's config tree and receives only what its own `apply`
+ * is handed, while the link the host writes into the system prompt is built
+ * on the other side of the wire. A constant is the honest form of a value
+ * that must match in two places.
+ * @module @tivility/dsh-session-share/param
+ */
+/** Query parameter naming the session to open on load. */
+export declare const SESSION_PARAM = "session";
+/**
+ * Build the query a share link carries.
+ * @param sessionId - the session to open.
+ * @returns the query string, question mark included.
+ */
+export declare function shareQuery(sessionId: string): string;
+//# sourceMappingURL=param.d.ts.map

package/lib/types/param.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"param.d.ts","sourceRoot":"","sources":["../../src/param.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,aAAa,YAAY,CAAA;AAEtC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@tivility/dsh-session-share",
+  "version": "0.1.0",
+  "description": "Link straight to one DeepSeek Harness session: the GUI opens on it instead of wherever it was left.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "lib/**",
+    "src/**"
+  ],
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "session",
+    "deep-link"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tivility/dsh-plugins.git",
+    "directory": "packages/session-share"
+  },
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ]
+    }
+  },
+  "dependencies": {
+    "@tivility/dsh-web-kit": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "*",
+    "@deepseek-ai/dsh-agent": ">=0.1.1-rc.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-system-prompt": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-agent": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "*",
+    "tsdown": "^0.20.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "bundle": "tsdown"
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,110 @@
+/**
+ * The browser half: open the session a link names.
+ *
+ * The harness's GUI has no routing — the whole client is searched in vain for
+ * `pushState`, `location.hash`, or `searchParams`. The selected session lives
+ * in the sessions manager and is restored from persisted state on load, so a
+ * URL naming one has nowhere to be read. This adds that one step and nothing
+ * else: read the parameter, select the session, get out of the way.
+ *
+ * It deliberately hides nothing. The sidebar, the other sessions, and the
+ * composer are all exactly as they would be — the link decides where you land,
+ * not what you can see.
+ *
+ * ## Why the context is typed here
+ *
+ * The two halves of this package compile in one TypeScript program, and the
+ * node half pulls in the harness's HOST augmentations of `Context` — where
+ * `sessions` is a different service with the same name. Importing
+ * `ClientContext` would therefore resolve `ctx.sessions` to the host's shape.
+ * The harness avoids this with separate client and host programs; a two-file
+ * package states the three members it uses instead, which also leaves this
+ * half with no harness type dependency at all.
+ * @module @tivility/dsh-session-share/client
+ */
+
+import { SESSION_PARAM } from '../param.js'
+
+/** The session-list snapshot this plugin reads. */
+interface SessionListSnapshot {
+  /** Every listed session, keyed by id. */
+  readonly byId: Readonly<Record<string, unknown>>
+  /** Whether the list has finished arriving. */
+  readonly phase: 'pending' | 'ready'
+}
+
+/** The part of the client sessions service this plugin drives. */
+interface SessionsFace {
+  readonly list: {
+    getSnapshot(): SessionListSnapshot
+    subscribe(listener: () => void): () => void
+  }
+  /**
+   * Select a session as current. Fails loud on an id the list does not carry,
+   * which is why the phase below is consulted first.
+   */
+  open(id: string): void
+}
+
+/** The client context members this plugin uses. */
+interface ShareContext {
+  readonly sessions: SessionsFace
+  effect(run: () => () => void): unknown
+  readonly logger?: { warn?(message: string): void }
+}
+
+/** Client-side services this plugin drives. */
+export const inject = ['sessions']
+
+/**
+ * Remove the parameter from the address bar once it has been acted on.
+ *
+ * The selection is persisted by the runtime, so leaving the parameter in place
+ * would make every later reload jump back to the linked session — fighting the
+ * user each time they navigate away and refresh. Consuming it once makes the
+ * link mean "start here", which is what a link means.
+ */
+function stripParam(): void {
+  const url = new URL(window.location.href)
+  if (!url.searchParams.has(SESSION_PARAM)) return
+  url.searchParams.delete(SESSION_PARAM)
+  window.history.replaceState(window.history.state, '', `${url.pathname}${url.search}${url.hash}`)
+}
+
+/**
+ * Watch the session list until the named session can be opened.
+ * @param ctx - the client root context.
+ */
+export function apply(ctx: ShareContext): void {
+  const requested = new URL(window.location.href).searchParams.get(SESSION_PARAM)
+  // No parameter is the overwhelmingly common case — every ordinary visit — so
+  // this plugin costs nothing at all when it has nothing to do.
+  if (requested === null || requested === '') return
+
+  ctx.effect(() => {
+    let done = false
+    const attempt = (): void => {
+      if (done) return
+      const state = ctx.sessions.list.getSnapshot()
+      if (state.byId[requested] !== undefined) {
+        done = true
+        ctx.sessions.open(requested)
+        stripParam()
+        return
+      }
+      // The list arrives asynchronously, so an id that is absent right now may
+      // simply not have loaded. The phase is what separates "not yet" from "no
+      // such session" — a timeout would guess at it.
+      if (state.phase === 'ready') {
+        done = true
+        stripParam()
+        ctx.logger?.warn?.(`session-share: no session ${requested} in this harness`)
+      }
+    }
+    const unsubscribe = ctx.sessions.list.subscribe(attempt)
+    // The list may already be ready before this plugin activates, in which case
+    // no change is ever published and the subscription alone would wait forever.
+    attempt()
+    return unsubscribe
+  })
+}

package/src/index.ts

@@ -0,0 +1,165 @@
+/**
+ * Link straight to one session.
+ *
+ * The harness's GUI opens wherever it was left. There is no URL that means
+ * "this conversation" — the whole client carries no routing at all, and the
+ * selected session is restored from persisted state. So a session cannot be
+ * pointed at: not in a message, not in a ticket, not by the agent describing
+ * its own work.
+ *
+ * This plugin adds the one missing step. The browser half reads a `?session=`
+ * parameter and selects that session; this half serves a short redirect route
+ * and teaches the model the link format so it can hand out links to the
+ * conversations it starts.
+ *
+ * **It shares nothing.** Every session stays visible and the GUI is otherwise
+ * untouched — the link decides where a visitor lands, not what they can see.
+ * Restricting that is what `@tivility/dsh-readonly-auth` is for, and this
+ * plugin deliberately does not pretend to do it: hiding the sidebar would look
+ * like isolation while `/api` still answered every question about every other
+ * session.
+ * @module @tivility/dsh-session-share
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+// Type-only: contributes the `agent` field on the prompt assembly context.
+import type {} from '@deepseek-ai/dsh-agent'
+import { absoluteUrl, isTrustedRequest, sendStatus } from '@tivility/dsh-web-kit'
+import { SESSION_PARAM, shareQuery } from './param.js'
+
+export { SESSION_PARAM, shareQuery } from './param.js'
+
+/** Stable Cordis plugin name. */
+export const name = 'session-share'
+
+/** The HTTP carrier this plugin mounts its redirect on. */
+export const inject = ['webServer']
+
+/** Plugin configuration. */
+export interface Config {
+  /**
+   * Prefix for the short link form, `<route>/<session-id>`. Empty mounts no
+   * route, leaving only the query form.
+   */
+  route?: string
+  /** Teach the model the link format so it can hand out links to its own sessions. */
+  prompt?: boolean
+  /** Non-loopback authorities this deployment serves, as `host` or `host:port`. */
+  trustedHosts?: string[]
+}
+
+export const Config: z<Config> = z.object({
+  route: z.string().default('/s'),
+  prompt: z.boolean().default(true),
+  trustedHosts: z.array(String).default([]),
+})
+
+/** A session id as it may appear in a URL: the harness mints uuids. */
+const SESSION_ID = /^[A-Za-z0-9_-]{1,128}$/
+
+/**
+ * Build the redirect handler for the short link form.
+ *
+ * A redirect rather than a page, because the GUI is a single-page app served
+ * only at the root: the harness's static fallback serves `index.html` for `/`
+ * and `/index.html` and 404s everything else, with no SPA rewrite. `/s/<id>`
+ * would therefore be a 404, so the short form bounces to the query form the
+ * browser half reads.
+ * @param route - the configured prefix.
+ * @param trustedHosts - authorities the fence accepts.
+ * @returns the route handler.
+ */
+function createHandler(
+  route: string,
+  trustedHosts: readonly string[],
+): (req: IncomingMessage, res: ServerResponse) => void {
+  return (req, res) => {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      sendStatus(res, 405, 'method not allowed', { allow: 'GET, HEAD' })
+      return
+    }
+    if (!isTrustedRequest(req, trustedHosts)) {
+      sendStatus(res, 403, 'forbidden')
+      return
+    }
+    /* v8 ignore next -- node:http always sets url on server requests */
+    const pathname = new URL(req.url ?? '/', 'http://x').pathname
+    let id: string
+    try {
+      id = decodeURIComponent(pathname.slice(route.length).replace(/^\//, ''))
+    } catch {
+      sendStatus(res, 400, 'malformed session id')
+      return
+    }
+    // Validated before it becomes a Location: the value lands in a header, and
+    // an unconstrained one is where header injection lives.
+    if (!SESSION_ID.test(id)) {
+      sendStatus(res, 400, 'malformed session id')
+      return
+    }
+    res.writeHead(302, { location: `/${shareQuery(id)}` })
+    res.end()
+  }
+}
+
+/**
+ * The system prompt section teaching the model this link format.
+ * @param ctx - a context carrying the `webServer` service.
+ * @param route - the configured short-link prefix.
+ * @param sessionId - the session the calling agent belongs to.
+ * @returns the prompt text.
+ */
+function promptSection(ctx: Context, route: string, sessionId: string): string {
+  const base = absoluteUrl(ctx, '/')
+  const link = `${base}${shareQuery(sessionId)}`
+  const shortForm = route === ''
+    ? ''
+    : ` The shorter ${absoluteUrl(ctx, route)}/${sessionId} redirects to the same place.`
+  return [
+    `This conversation has a direct link: ${link}`,
+    `Opening it in a browser selects this session instead of whatever was last open.${shortForm}`,
+    'Give it to the user when they need to come back to this conversation, point someone at it,',
+    'or file it somewhere. Any session id works in the same shape — a subagent you started,',
+    'a session you forked — so a link can point at that one instead of this one.',
+    'The link decides which session opens, not who may read it: everyone who can reach the',
+    'harness sees the same thing they would see without it.',
+  ].join(' ')
+}
+
+/**
+ * Mount the redirect route and the prompt section.
+ * @param ctx - plugin context carrying the injected `webServer` service.
+ * @param config - plugin configuration.
+ */
+export function apply(ctx: Context, config: Config = {}): void {
+  const route = config.route ?? '/s'
+  const trustedHosts = config.trustedHosts ?? []
+  if (route !== '') {
+    if (!route.startsWith('/') || route.endsWith('/')) {
+      throw new Error(`session-share: route ${JSON.stringify(route)} must be an absolute path without a trailing slash`)
+    }
+    ctx.effect(() => ctx.webServer.register({
+      kind: 'prefix',
+      path: route,
+      handler: createHandler(route, trustedHosts),
+    }), `session-share: ${route} route`)
+  }
+
+  if (config.prompt === false) return
+  ctx.inject(['systemPrompt'], (scope) => {
+    scope.systemPrompt.section({
+      name: 'session-share',
+      order: 91,
+      text: (context) => {
+        // Resolved per assembly: the port is known only after the server binds,
+        // and the session id is whichever agent this prompt is being built for.
+        const sessionId = context.agent?.session.id
+        return sessionId === undefined ? '' : promptSection(scope, route, String(sessionId))
+      },
+    })
+  })
+}

package/src/param.ts

@@ -0,0 +1,23 @@
+/**
+ * The one fact both halves of this plugin have to agree on.
+ *
+ * The query parameter is a constant rather than configuration because the two
+ * halves cannot share a configuration value: the browser bundle is fetched
+ * outside the loader's config tree and receives only what its own `apply`
+ * is handed, while the link the host writes into the system prompt is built
+ * on the other side of the wire. A constant is the honest form of a value
+ * that must match in two places.
+ * @module @tivility/dsh-session-share/param
+ */
+
+/** Query parameter naming the session to open on load. */
+export const SESSION_PARAM = 'session'
+
+/**
+ * Build the query a share link carries.
+ * @param sessionId - the session to open.
+ * @returns the query string, question mark included.
+ */
+export function shareQuery(sessionId: string): string {
+  return `?${SESSION_PARAM}=${encodeURIComponent(sessionId)}`
+}