better-dsh 0.2.3-b → 0.2.3-d
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/50_test-reports/upstream-dsh-0.1.5-rc.2-local-test-report.md +79 -0
- package/docs/upstream-dsh-0.1.5-rc.2-report.md +156 -0
- package/eval-description.md +33 -0
- package/lib/client/index.js +59 -50
- package/lib/index.d.ts +4 -21
- package/lib/index.js +37 -77
- package/lib/py-sdk-Chvy92MB.js +178 -0
- package/lib/py-sdk.d.ts +19 -2
- package/lib/py-sdk.js +2 -2
- package/package.json +3 -3
- package/control-prompt.md +0 -37
- package/docs/50_test-reports/v0.1.8d_artifacts/README.md +0 -138
- package/docs/50_test-reports/v0.1.8d_artifacts/code-mode-repl-only.observation.md +0 -74
- package/docs/50_test-reports/v0.1.8d_artifacts/dsh-session-session-4a293388-9ae1-474b-87a0-9e17bb556d94.jsonl +0 -3890
- package/docs/50_test-reports/v0.1.8d_artifacts/dsh-session-session-4a293388-9ae1-474b-87a0-9e17bb556d94.w-sample-0435.jsonl +0 -544
- package/docs/50_test-reports/v0.1.8d_artifacts/functions.json +0 -592
- package/docs/50_test-reports/v0.1.8d_artifacts/skills-catalog.snapshot.md +0 -30
- package/docs/50_test-reports/v0.1.8d_artifacts/tools-sdk.output-schemas.json +0 -1236
- package/docs/50_test-reports/v0.1.8d_artifacts/tools-sdk.python.txt +0 -592
- package/docs/50_test-reports/v0.1.8d_artifacts/tools-sdk.typescript.txt +0 -516
- package/docs/50_test-reports/v0.1.8d_artifacts/wire-vs-transcription.diff.md +0 -54
- package/docs/50_test-reports/v0.2.0b_artifacts/f2probe/Cargo.lock +0 -7
- package/docs/50_test-reports/v0.2.0b_artifacts/f2probe/Cargo.toml +0 -6
- package/docs/50_test-reports/v0.2.0b_artifacts/f2probe/src/bin/messy.rs +0 -8
- package/docs/50_test-reports/v0.2.0b_artifacts/f2probe/src/main.rs +0 -4
- package/docs/50_test-reports/v0.2.0b_artifacts/hashline-probe.md +0 -5
- package/docs/50_test-reports/v0.2.0b_artifacts/slowprobe/Cargo.lock +0 -7
- package/docs/50_test-reports/v0.2.0b_artifacts/slowprobe/Cargo.toml +0 -7
- package/docs/50_test-reports/v0.2.0b_artifacts/slowprobe/build.rs +0 -4
- package/docs/50_test-reports/v0.2.0b_artifacts/slowprobe/src/main.rs +0 -13
- package/docs/60_exploration-and-research/01-cordis-runtime/bun-compile-cordis-runtime-bootstrap-research.md +0 -536
- package/docs/60_exploration-and-research/01-cordis-runtime/cordis-customization-and-override-mechanics.md +0 -418
- package/docs/60_exploration-and-research/01-cordis-runtime/cordis-engineering-feasibility.md +0 -155
- package/docs/60_exploration-and-research/01-cordis-runtime/cordis-research.md +0 -583
- package/docs/60_exploration-and-research/01-cordis-runtime/dsh-cordis-hotplug-mcp-patch-research.md +0 -265
- package/docs/60_exploration-and-research/01-cordis-runtime/js-ts-language-fundamentals.md +0 -628
- package/docs/60_exploration-and-research/02-dsh/dash-research.md +0 -592
- package/docs/60_exploration-and-research/02-dsh/dsh-web-profile-package-map.md +0 -186
- package/docs/60_exploration-and-research/02-dsh/dsh-web-ui-slot-system-research.md +0 -310
- package/docs/60_exploration-and-research/02-dsh/dsh-webui-backend-data-inventory.md +0 -633
- package/docs/60_exploration-and-research/02-dsh/dsh-webui-strip-boundary-research.md +0 -300
- package/docs/60_exploration-and-research/02-dsh/dsh-webui-wire-appendix.md +0 -3729
- package/docs/60_exploration-and-research/02-dsh/web-frontend-composability-research.md +0 -191
- package/docs/60_exploration-and-research/02-dsh/webui-wire-data/capture-live-turn.json +0 -1
- package/docs/60_exploration-and-research/02-dsh/webui-wire-data/observed-endpoints.json +0 -224
- package/docs/60_exploration-and-research/02-dsh/webui-wire-data/remote-inventory.json +0 -110954
- package/docs/60_exploration-and-research/02-dsh/webui-wire-data/served-index-sample.html +0 -47
- package/docs/60_exploration-and-research/02-dsh/webui-wire-data/session-events.json +0 -9411
- package/docs/60_exploration-and-research/02-dsh/webui-wire-data/ws-frame-examples.json +0 -20
- package/docs/60_exploration-and-research/02-dsh-webui/dsh-web-profile-package-map.md +0 -186
- package/docs/60_exploration-and-research/02-dsh-webui/dsh-web-ui-slot-system-research.md +0 -310
- package/docs/60_exploration-and-research/02-dsh-webui/dsh-webui-backend-data-inventory.md +0 -633
- package/docs/60_exploration-and-research/02-dsh-webui/dsh-webui-strip-boundary-research.md +0 -300
- package/docs/60_exploration-and-research/02-dsh-webui/dsh-webui-wire-appendix.md +0 -3729
- package/docs/60_exploration-and-research/02-dsh-webui/web-frontend-composability-research.md +0 -191
- package/docs/60_exploration-and-research/02-dsh-webui/webui-wire-data/capture-live-turn.json +0 -1
- package/docs/60_exploration-and-research/02-dsh-webui/webui-wire-data/observed-endpoints.json +0 -224
- package/docs/60_exploration-and-research/02-dsh-webui/webui-wire-data/remote-inventory.json +0 -110954
- package/docs/60_exploration-and-research/02-dsh-webui/webui-wire-data/served-index-sample.html +0 -47
- package/docs/60_exploration-and-research/02-dsh-webui/webui-wire-data/session-events.json +0 -9411
- package/docs/60_exploration-and-research/02-dsh-webui/webui-wire-data/ws-frame-examples.json +0 -20
- package/docs/60_exploration-and-research/03-mobile-ios/dsh-mobile-spa-ios-input-experience-research.md +0 -160
- package/docs/60_exploration-and-research/03-mobile-ios/ios-chat-app-bridge-research.md +0 -324
- package/docs/60_exploration-and-research/04-session-storage/alpha5-compaction-jsonl-mapping.md +0 -1532
- package/docs/60_exploration-and-research/04-session-storage/alpha5-compaction-sample/episode-failed.json +0 -46
- package/docs/60_exploration-and-research/04-session-storage/alpha5-compaction-sample/episode1.json +0 -1124
- package/docs/60_exploration-and-research/04-session-storage/alpha5-compaction-sample/episode2.json +0 -1240
- package/docs/60_exploration-and-research/05-dashr-dev/plugin-development.md +0 -148
- package/docs/60_exploration-and-research/05-dashr-dev/upstream-alignment.md +0 -102
- package/docs/60_exploration-and-research/README.md +0 -87
- package/docs/60_exploration-and-research/bun-compile-cordis-runtime-bootstrap-research.md +0 -348
- package/docs/60_exploration-and-research/cordis-research.md +0 -350
- package/docs/60_exploration-and-research/dsh-mobile-spa-ios-input-experience-research.md +0 -160
- package/docs/60_exploration-and-research/dsh-web-profile-package-map.md +0 -186
- package/docs/60_exploration-and-research/dsh-web-ui-slot-system-research.md +0 -310
- package/docs/60_exploration-and-research/dsh-webui-strip-boundary-research.md +0 -300
- package/docs/60_exploration-and-research/ios-chat-app-bridge-research.md +0 -324
- package/docs/60_exploration-and-research/web-frontend-composability-research.md +0 -191
- package/docs/superd/00-blueprint.md +0 -331
- package/docs/superd/01-component-boundaries.md +0 -261
- package/docs/superd/02-dsh-embed-modes.md +0 -151
- package/docs/superd/image.png +0 -0
- package/lib/py-sdk-BCaOGYz7.d.ts +0 -125
- package/lib/py-sdk-CbgYiX8O.js +0 -691
|
@@ -1,151 +0,0 @@
|
|
|
1
|
-
# DSH 运行时呈现层嵌入模式研究(iframe / 反代透传)
|
|
2
|
-
|
|
3
|
-
> 2026-09-08 · 起因:DSH runtime 的呈现层能否绕开"自有 composition",直接复用上游 Web UI?
|
|
4
|
-
> 两个候选:①iframe 直嵌 3080 页面;②DSH adapter 假装 browser 向 3080 发请求、把 traffic
|
|
5
|
-
> 透传给 3090 前端。方法:上游源码一手核验(checkout `dsh-v0.1.2-alpha.5`,
|
|
6
|
-
> `~/workspaces/dashr/upstream/deepseek-harness`)。
|
|
7
|
-
> 结论先行:**两者都可行**;②其实就是蓝图 v0.2 已裁决的"DSH adapter wire 透传"形态的自然延伸,
|
|
8
|
-
> 真正的新选择是"前端也用上游的"——最干净的落法是 **iframe(或 iframe-over-反代)作为一个
|
|
9
|
-
> lite composition**,与终态集成 composition 并存,不冲突。
|
|
10
|
-
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
## 1. 四个变体速览
|
|
14
|
-
|
|
15
|
-
| 变体 | 前端是什么 | 代理代码 | 远程 machine | HTTPS 混合内容 | 集成度 | 定位 |
|
|
16
|
-
|---|---|---|---|---|---|---|
|
|
17
|
-
| **A 直连 iframe** | 上游真 UI(iframe src=3080) | 零 | ✗(浏览器须直达 3080) | 有风险 | 零 | 本地 DSH 的零代码捷径 |
|
|
18
|
-
| **B 反代 + iframe** | 上游真 UI(iframe src=镜像) | HTTP+WS 透明反代 | ✓(经 superD-to-superD) | ✓(镜像走 HTTPS) | 低(画布级) | **推荐的 M1 lite 形态** |
|
|
19
|
-
| **B′ 反代全页(无 iframe)** | 上游真 UI(整页) | 同 B | ✓ | ✓ | 零(无壳共存) | ✗ 主线;仅"远程访问网关"产品形态 |
|
|
20
|
-
| **C 集成 composition** | 自有 UI(agent-ui-dsh) | RPC 透传(蓝图既有) | ✓ | ✓ | 高(统一壳) | 蓝图 v0.2 终态 |
|
|
21
|
-
|
|
22
|
-
判定:B′ 把代理代码和零集成两头的成本都占了却无收益——**整页 app 无法与我们的壳共挂**
|
|
23
|
-
(同一页面装两套 client 模块表 = 同 id 硬错,上游设计即禁止;DSH UI 是整页 root 槽应用,
|
|
24
|
-
没有"挂在 div 里"的形态),且页面内没有我们的 selector。B′ 唯一合理用途是"superD 作为
|
|
25
|
-
DSH 远程访问网关"(独立产品卖点),不是统一入口的主线。
|
|
26
|
-
|
|
27
|
-
---
|
|
28
|
-
|
|
29
|
-
## 2. 上游事实核查(六条,均已一手核验)
|
|
30
|
-
|
|
31
|
-
1. **无 frame-busting 头**:`packages/host/`、`packages/boot/` 全量 grep 无
|
|
32
|
-
`X-Frame-Options` / `Content-Security-Policy` / `frame-ancestors` → **DSH 页面可被 iframe**。
|
|
33
|
-
2. **token 只存在于 DSH 进程内存**:`client/connection/src/browser-auth.ts` —— launch token
|
|
34
|
-
为进程内随机数(`PROCESS_LAUNCH_TOKENS` WeakMap,L52–60),**无 env 覆盖、不落盘**;启动时
|
|
35
|
-
由 `authenticatedUrl()` 拼成 `/?token=…` 随 URL 打印(`bundle/web-app/src/index.ts:287` 调用)。
|
|
36
|
-
→ 获取路径只有一条:**读 DSH 进程的 stdout/journal/日志**。
|
|
37
|
-
3. **token → cookie 交换**:`GET /?token=…`(Host authority 必须在)→ `303` + 签名 cookie
|
|
38
|
-
`dsh-auth-<authority>`,**24h 有效**(`authorizeIndex`,L236+);token 本身**随 DSH 进程存活**,
|
|
39
|
-
cookie 过期可用同一 token 重铸。401 响应体带指纹
|
|
40
|
-
`dsh web authentication required; reopen the URL printed by dsh web.`(蓝图开放问题 #4 已记)。
|
|
41
|
-
4. **`/api` 信任栅栏按 Host 绑定,且"不是 auth 层"**(`api-request-trust.ts` 文件头注释):
|
|
42
|
-
loopback / 部署 LAN IP / 声明的 `trustedHosts` 过栅栏。→ 反代向上游发 `Host: 127.0.0.1:3080`
|
|
43
|
-
即过;iframe 内页面对 3080 的调用是 same-origin(Host=loopback)也过。
|
|
44
|
-
5. **客户端 API base = `window.location.origin`**(`client/connection/src/client/rpc.ts:109–110`,
|
|
45
|
-
缺省回退内部 base)→ **经反代时客户端自动打向代理 origin**,无需改上游客户端。
|
|
46
|
-
6. **资产/模块 URL 是 root-相对路径**(boot graph 里 `/plugins/??pkg/client.js&rev=…` 形态)→
|
|
47
|
-
反代**必须挂在 origin 根**(独立端口或子域);挂路径前缀(`3090/_dsh/`)会打断这些引用,
|
|
48
|
-
除非连 boot graph JSON 一起做路径重写(可行但增加脆弱面)。
|
|
49
|
-
|
|
50
|
-
---
|
|
51
|
-
|
|
52
|
-
## 3. 变体 A:直连 iframe(本地零代码)
|
|
53
|
-
|
|
54
|
-
机制:superD 壳的会话区渲染 `<iframe src="http://127.0.0.1:3080/?token=…">`。iframe 文档的
|
|
55
|
-
origin 就是 3080,其自身的一切 `/api`+WS 调用都是 same-origin、Host=loopback → 栅栏直过;
|
|
56
|
-
token URL 首开后 303 换 cookie,此后 iframe 内自持会话。
|
|
57
|
-
|
|
58
|
-
- **前提 1(✓ 已核验)**:上游不设 frame 头。
|
|
59
|
-
- **前提 2(✓ 已核验)**:栅栏按 Host,iframe 内 same-origin 调用天然合法。
|
|
60
|
-
- **前提 3(工程项)**:token 注入——adapter 从 DSH stdout/journal 抓 URL(本地机器可做)。
|
|
61
|
-
|
|
62
|
-
局限:远程 machine 的 3080 浏览器不可达(superD-to-superD 才可达);superD 壳若走 HTTPS
|
|
63
|
-
(Caddy),iframe 载入 plain HTTP 属混合内容,浏览器会拦;跨域 iframe 完全密封(壳不能
|
|
64
|
-
reach-in 折叠其自带 chrome)。
|
|
65
|
-
|
|
66
|
-
## 4. 变体 B:透明反代 + iframe(推荐 lite 形态)
|
|
67
|
-
|
|
68
|
-
"DSH adapter 假装成 browser"的准确工程含义:**adapter 以 browser 的口音说 HTTP/WS**(正确的
|
|
69
|
-
Host 头、持 cookie、做 WS upgrade),**不是**跑一个真的 headless browser(重且脆,不需要)。
|
|
70
|
-
实现就是标准反向代理:
|
|
71
|
-
|
|
72
|
-
```mermaid
|
|
73
|
-
flowchart LR
|
|
74
|
-
BR["用户浏览器:superD 壳(3090)"] -->|"会话区 iframe src = 镜像 origin"| IF["iframe:真 DSH UI"]
|
|
75
|
-
IF -->|"same-origin /api + WS<br/>(rpc.ts 按 location.origin 打)"| MIR["superD DSH 镜像<br/>(透明反代,origin 根挂载)"]
|
|
76
|
-
MIR -->|"Host: 127.0.0.1:3080<br/>+ 代理持有 dsh-auth cookie"| DSH["目标机 DSH(3080)"]
|
|
77
|
-
BR -->|"列表/设置/新建会话等 BFF RPC(method 级)"| BFF["superD BFF + DSH adapter"]
|
|
78
|
-
BFF -->|"同上,另一条腿"| DSH
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
实现要点:
|
|
82
|
-
|
|
83
|
-
- **origin 根挂载**(事实 6):镜像监听独立端口/子域(本地如 3091+ 自动分配;远程经 Caddy
|
|
84
|
-
路由到 remote superD 的镜像),纯透传、零重写。
|
|
85
|
-
- **认证归代理**:adapter 用抓到的 token 在镜像侧完成一次 `/?token=` 交换、持有并续期 cookie;
|
|
86
|
-
**浏览器全程不见 DSH token**——对下游只有 superD 自己的认证面(authChain)。
|
|
87
|
-
- **WS 1:1 桥**:每个下游 WS upgrade 对应一条独立上游 WS(不做扇出 hub,M1 单用户足够);
|
|
88
|
-
streaming 响应禁缓冲。
|
|
89
|
-
- **401 自愈**:镜像收到指纹 401 → 重读目标机 DSH 日志取新 token → 重交换(DSH 重启 token
|
|
90
|
-
轮换的自动恢复)。
|
|
91
|
-
- **可选 same-origin 增强**:若镜像与壳同 origin(路径前缀 + boot graph 路径重写),壳可
|
|
92
|
-
reach-in 折叠 iframe 内 DSH 自带 sidebar(双 chrome 问题);这是 nice-to-have,不作前提。
|
|
93
|
-
|
|
94
|
-
## 5. 与 v0.2 组合层架构的统一(关键:不二选一)
|
|
95
|
-
|
|
96
|
-
iframe **本身就是一种合法 composition**:`agent-ui-dsh-lite` 包往会话区槽 register 一个 iframe
|
|
97
|
-
组件(URL 由 adapter 供给:machine URL + token),selector 切换 = 换 composition——v0.2 的
|
|
98
|
-
机制原样适用,一行不用改。分工随之清晰:
|
|
99
|
-
|
|
100
|
-
- **会话画布**:lite 形态下 = 真 DSH UI(iframe);终态 = agent-ui-dsh(copy 版)。
|
|
101
|
-
- **会话列表 / workspace / settings / TG consumer**:永远走 superD BFF 的 method 级 RPC
|
|
102
|
-
(TG 本来就需要 method 级访问,adapter 的数据面两形态共用)——**统一入口不丢**:列表、
|
|
103
|
-
选择器、机器管理都是我们的,iframe 只接管画布。
|
|
104
|
-
- **双 chrome**(iframe 内 DSH 自带 sidebar 叠在我们的壳里):M1 接受;缓解路径 = 同源
|
|
105
|
-
reach-in 或移动断点折叠。
|
|
106
|
-
- **红利**:镜像是 wire 层的"参考实现 + 永远新鲜的对照"——集成 composition 的字段映射
|
|
107
|
-
可随时对着真实流量校准;上游 UI 更新零成本跟进(lite 形态下根本不维护 UI)。
|
|
108
|
-
|
|
109
|
-
## 6. token 获取与生命周期(两形态共用)
|
|
110
|
-
|
|
111
|
-
| 事实 | 值 | 出处 |
|
|
112
|
-
|---|---|---|
|
|
113
|
-
| token 存储 | 仅进程内存(WeakMap),无 env、无文件 | browser-auth.ts L52–60 |
|
|
114
|
-
| 发放面 | 启动时随 `authenticatedUrl` 打印到 stdout | web-app/src/index.ts:287 |
|
|
115
|
-
| token 寿命 | DSH 进程生命周期(重启即轮换) | WeakMap 语义 |
|
|
116
|
-
| cookie 寿命 | 24h,可用同一 token 无限重铸 | authorizeIndex + DAY_MILLISECONDS |
|
|
117
|
-
| 抓取实现 | 本地:journal/日志文件;远程:remote superD 读它本机的 | 蓝图本地发现三步可复用 |
|
|
118
|
-
|
|
119
|
-
长期项:向上游提 service-token / machine-token 配置需求(免除日志抓取);M1 不依赖。
|
|
120
|
-
|
|
121
|
-
---
|
|
122
|
-
|
|
123
|
-
## 7. 验证清单(M1 裁决 lite 形态前)
|
|
124
|
-
|
|
125
|
-
1. [ ] 直连 iframe 本地 3080 实测:`?token=` 注入 → 303 → cookie 建立 → UI 全功能。
|
|
126
|
-
2. [ ] HTTPS 壳(Caddy)iframe plain-HTTP 127.0.0.1 的混合内容行为(桌面 + 移动 Chrome)。
|
|
127
|
-
3. [ ] 镜像反代全通:静态资产 + boot graph + `/api` unary + WS upgrade + streaming。
|
|
128
|
-
4. [ ] WS 经代理的 connection generations 行为(断线重连、代理重启)。
|
|
129
|
-
5. [ ] DSH 重启 token 轮换 → 401 自愈链路。
|
|
130
|
-
6. [ ] 双 chrome 观感裁决(接受 / reach-in 折叠 / 移动断点)。
|
|
131
|
-
7. [ ] 同源变体的 boot graph 路径重写成本评估(仅当需要 reach-in 时)。
|
|
132
|
-
|
|
133
|
-
## 8. 建议
|
|
134
|
-
|
|
135
|
-
- **M1**:本地 DSH 用变体 A(零代码);远程 DSH 用变体 B(镜像反代)。`agent-ui-dsh-lite`
|
|
136
|
-
(iframe composition)先落地,`agent-ui-dsh`(集成 copy)延到 M2+。
|
|
137
|
-
- **终态**:蓝图 v0.2 的集成 composition 不变;lite 作为长尾保留("用最新原版 DSH UI"本身
|
|
138
|
-
可以是一个用户选项)。
|
|
139
|
-
- **不做**:B′ 全页镜像作主线;headless browser 方案。
|
|
140
|
-
|
|
141
|
-
---
|
|
142
|
-
|
|
143
|
-
## 来源
|
|
144
|
-
|
|
145
|
-
- 上游 checkout(`~/workspaces/dashr/upstream/deepseek-harness`,tag `dsh-v0.1.2-alpha.5`):
|
|
146
|
-
`packages/client/connection/src/{browser-auth,api-request-trust,rpc-host}.ts`、
|
|
147
|
-
`packages/client/connection/src/client/rpc.ts`、`packages/bundle/web-app/src/index.ts`;
|
|
148
|
-
`packages/host/`+`packages/boot/` frame 头 grep(空)。
|
|
149
|
-
- `00-blueprint.md` v0.2(§3 adapter 体系、§3.5 composition、开放问题 #4/#7);
|
|
150
|
-
`01-component-boundaries.md`(呈现层替换带)。
|
|
151
|
-
- 运维证据:`docs/60_exploration-and-research/`(boot graph 模块 URL 形态、token 轮换实践)。
|
package/docs/superd/image.png
DELETED
|
Binary file
|
package/lib/py-sdk-BCaOGYz7.d.ts
DELETED
|
@@ -1,125 +0,0 @@
|
|
|
1
|
-
//#region src/py-sdk.d.ts
|
|
2
|
-
/**
|
|
3
|
-
* DASHR kernel SDK codegen — Python flavor, cell edition.
|
|
4
|
-
*
|
|
5
|
-
* The pure projection from one calling scope's visible tool schemas to the
|
|
6
|
-
* Python SDK text the model programs against inside `eval` cells. The
|
|
7
|
-
* type-rendering machinery is ported from `@deepseek-ai/dsh-tools`
|
|
8
|
-
* `py-types.ts` (0.1.0-rc.6) per blueprint §7.4, deliberately slimmed to
|
|
9
|
-
* DASHR's single-language, stateful surface:
|
|
10
|
-
*
|
|
11
|
-
* - The usage instructions are OURS, not upstream's: upstream promises a
|
|
12
|
-
* one-shot program ("runs as the body of an async function", value-less
|
|
13
|
-
* between calls), while a DASHR cell runs on a PERSISTENT kernel whose
|
|
14
|
-
* variables, imports, and definitions survive across `eval` calls.
|
|
15
|
-
* The prose here must never state the throwaway contract.
|
|
16
|
-
* - No language table and no context-free renderer: DASHR renders Python
|
|
17
|
-
* only, and object shapes always render through the named-`TypedDict`
|
|
18
|
-
* path this module owns. (Upstream's exported `jsonSchemaToPy` degrades
|
|
19
|
-
* every object to `dict[str, Any]`; reusing it would lose the shape.)
|
|
20
|
-
* - The bare-identifier rule, `camelCase` derivation, class-name capping
|
|
21
|
-
* and collision suffixing, `typing` import emission, and the
|
|
22
|
-
* deterministic lexicographic member order are ported near-verbatim: the
|
|
23
|
-
* parseability invariants (NFKC stability, reserved words, unprintable
|
|
24
|
-
* escapes, bracket-nesting cap) exist because the emitted block is the
|
|
25
|
-
* model's ONLY declaration of the tools, and a syntax error in it poisons
|
|
26
|
-
* the whole mode.
|
|
27
|
-
* - renders one `tool.<name>(args) -> Output` member per tool — no `Tools`
|
|
28
|
-
* protocol and no `tools` singleton — matching the kernel's `tool`
|
|
29
|
-
* object holder. Which names may render as members is decided by
|
|
30
|
-
* {@link isFlatBindableName}, the one policy the renderer and the bridge
|
|
31
|
-
* share.
|
|
32
|
-
* @module dashr-repl/py-sdk
|
|
33
|
-
*/
|
|
34
|
-
/**
|
|
35
|
-
* One tool as the SDK renderer sees it: the model-facing schema
|
|
36
|
-
* (name/description/parameters) plus the tool's canonical output schema.
|
|
37
|
-
* The caller (the presentation plugin) excludes `eval` itself and reads
|
|
38
|
-
* both through the tool registry's public projection APIs.
|
|
39
|
-
*/
|
|
40
|
-
interface DASHRSdkSchema {
|
|
41
|
-
/** Tool name as registered (may be exotic; the renderer routes non-bindable names to not-callable comments). */
|
|
42
|
-
readonly name: string;
|
|
43
|
-
/** Tool description, rendered as the method docstring. */
|
|
44
|
-
readonly description: string;
|
|
45
|
-
/** Validated JSON-Schema node for the arguments object. */
|
|
46
|
-
readonly parameters: unknown;
|
|
47
|
-
/** Validated JSON-Schema node for the canonical output value. */
|
|
48
|
-
readonly output: unknown;
|
|
49
|
-
}
|
|
50
|
-
/**
|
|
51
|
-
* Whether a tool name can be emitted AND bound as a `tool` member — the ONE
|
|
52
|
-
* policy shared by this renderer and the bridge's binding
|
|
53
|
-
* loop (src/index.ts), so the catalog never promises a name the kernel does
|
|
54
|
-
* not bind. Strictly narrower than the runtime's validation: the
|
|
55
|
-
* language-portable identifier subset (`[A-Za-z_][A-Za-z0-9_]*`, ASCII — a
|
|
56
|
-
* non-ASCII XID name is legal CPython but not portable, so the runtime
|
|
57
|
-
* refuses it as a binding global and the catalog must not teach it), minus
|
|
58
|
-
* every portable reserved word (ECMAScript ∪ Python — `type` and `match`
|
|
59
|
-
* are legal Python but reserved on the seam), minus the seam's reserved
|
|
60
|
-
* binding globals (`console`, dunders), minus underscore-leading names
|
|
61
|
-
* (kernel-shim prefix plus the call-site hazards; not callable as taught
|
|
62
|
-
* flat globals). The runtime's `validateBindings` remains the authoritative
|
|
63
|
-
* backstop: everything this accepts, it accepts.
|
|
64
|
-
*/
|
|
65
|
-
declare function isFlatBindableName(name: string): boolean;
|
|
66
|
-
/**
|
|
67
|
-
* Render the `dashr:tool-catalog` prompt section body from the registry
|
|
68
|
-
* schemas: the cell-flavored usage instructions above, the
|
|
69
|
-
* `ToolCallError` declaration, one named `TypedDict` per tool argument or
|
|
70
|
-
* output object (and per nested object), and one
|
|
71
|
-
* `tool.<name>(args: XArgs) -> XOutput` member per visible tool — no `Tools`
|
|
72
|
-
* protocol, no `tools` singleton, every tool is a member of the `tool`
|
|
73
|
-
* object exactly as the kernel binds it — inside one fenced
|
|
74
|
-
* ```python block. The `typing` import line lists exactly the symbols the
|
|
75
|
-
* render used (and is omitted entirely when none are).
|
|
76
|
-
*
|
|
77
|
-
* Deterministic — tools are emitted in lexicographic name order and class
|
|
78
|
-
* declarations precede the function that references them in that same
|
|
79
|
-
* order (nested classes before the parent that references them), so an
|
|
80
|
-
* unchanged tool set produces byte-identical text across assemblies.
|
|
81
|
-
*
|
|
82
|
-
* Non-bindable names (reserved, exotic, or underscore-leading) render as
|
|
83
|
-
* comment lines: they are registered upstream but NOT callable from cells,
|
|
84
|
-
* and the comment keeps the signature and description visible instead of
|
|
85
|
-
* silently dropping the tool.
|
|
86
|
-
* @param schemas - the calling scope's visible tools (caller excludes
|
|
87
|
-
* `eval` and the masked delegation names).
|
|
88
|
-
* @returns the complete section body.
|
|
89
|
-
*/
|
|
90
|
-
declare function renderToolsSdkPy(schemas: readonly DASHRSdkSchema[]): string;
|
|
91
|
-
/**
|
|
92
|
-
* The `dashr:tool-catalog` section's presentation mode (design D4):
|
|
93
|
-
* `'signatures'` renders one compact declaration line per visible tool
|
|
94
|
-
* (the omp code-mode shape: `name(args: {…})` per line, argument and output
|
|
95
|
-
* sketches abbreviated to depth 2 — the default, chosen for low-tier model
|
|
96
|
-
* robustness); `'convention'` renders the one-sentence calling convention
|
|
97
|
-
* alone (zero repetition, the A/B deployment experiment's other arm).
|
|
98
|
-
* Both modes keep the output contract (each tool's canonical JSON output
|
|
99
|
-
* shape) and the non-flat-name exception; neither presents a REPL binding
|
|
100
|
-
* listing — the declaration lines themselves are the authoritative surface.
|
|
101
|
-
*/
|
|
102
|
-
type ReplBridgeCatalogMode = 'signatures' | 'convention';
|
|
103
|
-
/** The deployed presentation mode; flip to `'convention'` to ship arm A. */
|
|
104
|
-
declare const REPL_BRIDGE_CATALOG_MODE: ReplBridgeCatalogMode;
|
|
105
|
-
/**
|
|
106
|
-
* Render the `dashr:tool-catalog` prompt section body as the REPL bridge
|
|
107
|
-
* instructions (design D4/D5): the scripting-pad positioning and the
|
|
108
|
-
* calling convention above, then — in the default `'signatures'` mode —
|
|
109
|
-
* one compact declaration line per visible tool
|
|
110
|
-
* (`tool.<name>(args: {…}) -> <output shape>`, omp code-mode shape with
|
|
111
|
-
* the output contract kept), inside one fenced ```python block.
|
|
112
|
-
* Non-bindable names (reserved, exotic, underscore-leading) are omitted
|
|
113
|
-
* from the lines; the convention sentence above states that limit once.
|
|
114
|
-
*
|
|
115
|
-
* Deterministic — lines are emitted in lexicographic name order, so an
|
|
116
|
-
* unchanged tool set produces byte-identical text across assemblies.
|
|
117
|
-
* @param schemas - the calling scope's visible tools (the caller already
|
|
118
|
-
* excluded the transport and the wire-masked names).
|
|
119
|
-
* @param mode - override the deployed {@link REPL_BRIDGE_CATALOG_MODE}
|
|
120
|
-
* (the two render states; tests exercise both).
|
|
121
|
-
* @returns the complete section body.
|
|
122
|
-
*/
|
|
123
|
-
declare function renderReplBridgeInstructions(schemas: readonly DASHRSdkSchema[], mode?: ReplBridgeCatalogMode): string;
|
|
124
|
-
//#endregion
|
|
125
|
-
export { renderReplBridgeInstructions as a, isFlatBindableName as i, REPL_BRIDGE_CATALOG_MODE as n, renderToolsSdkPy as o, ReplBridgeCatalogMode as r, DASHRSdkSchema as t };
|