@onlyworlds/sdk 4.176.0 → 4.178.0
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/AGENTS.md +1 -1
- package/CHANGELOG.md +26 -0
- package/README.md +2 -2
- package/SCHEMA.md +1 -1
- package/dist/index.d.ts +44 -7
- package/dist/index.js +9 -7
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# For AI agents using @onlyworlds/sdk
|
|
2
2
|
|
|
3
|
-
**Current as of**: SDK **4.x** · schema-dist **v0.34.1-dist.
|
|
3
|
+
**Current as of**: SDK **4.x** · schema-dist **v0.34.1-dist.133** (canonical 00.34.01).
|
|
4
4
|
This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
|
|
5
5
|
re-read against it, the check fails rather than letting this document rot quietly.
|
|
6
6
|
|
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,32 @@ earlier history lives in git log only.
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [4.178.0] - 2026-11-17
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **`by_role` on every row of a draught's `work`**, which `GET /character/{id}/context` now serves: the ids of her Titles that the work item names, each once, in the item's order, and an empty list when none does. Work is for her by name (the item's `actor`) or by a role she holds (the item's `x_packet_for` names a Title whose `holders` name her), and a row that reached her only through a Title has `via` `['holders']`. Read as her (`mode: 'voice'`) a work item reaches her only through a field of its own that names her, so a caller asks with `mode: 'act'` for what is hers by role.
|
|
13
|
+
|
|
14
|
+
### Fixed
|
|
15
|
+
|
|
16
|
+
- **The message for a write the host refused says the whole way out.** The same command passes in a fenced code block whose first line names a language, or with no backtick, semicolon or pipe directly before it; the message named only the backtick.
|
|
17
|
+
|
|
18
|
+
## [4.177.0] - 2026-11-17
|
|
19
|
+
|
|
20
|
+
### Added
|
|
21
|
+
|
|
22
|
+
- **The charter and strand packets say each element's type** (schema-dist serial 133). `charterOf` answers `type: 'law'` on the Charter and `type: 'construct'` on the Guide and on each Domain; `strandOf` answers `type` on every filled slot (`narrative`, `event`, `location`, `character`, and `location` for `now`): the kind the slot holds, singular and lowercase, never the spelling stored. A packet is handed to a reader that may hold nothing else of the world, and an id is fetched by its type. `OwReadingAidsCharter`, `OwReadingAidsGuide`, `OwReadingAidsDomain` and `OwStrandSlot` declare the key, so `OwServedReadingAids` reads it as onlyworlds.com's `reading_aids` serves it. The schema pin moves to `v0.34.1-dist.133`; the charter fixture holds 47 cases and the strand fixture 29.
|
|
23
|
+
|
|
24
|
+
### Fixed
|
|
25
|
+
|
|
26
|
+
- **A Domain's hub is an element of the kind its field links to, in the reader's view.** An id of another kind in a hub field, or of an element the reader does not see, names no hub. Wherever the charter and strand readers compare an element's type to a kind, the type is trimmed and compared without regard to case, as the room profile defines it.
|
|
27
|
+
- **`getAccessKey`'s deprecation note names `ai('ask', ...)` and `ai('sort', ...)`**, where it sent a reader to `ask()` and `sort()`, themselves deprecated since 4.139.0. The example at the head of the ask module calls `ai('ask', ...)` too. The by-links-3d frame comment says every candidate is tested, and the README names the fixtures without a case count.
|
|
28
|
+
|
|
29
|
+
### Deprecated
|
|
30
|
+
|
|
31
|
+
- **The `version` key on `layoutByKind`'s and `layoutAround`'s answers** leaves in 5.0. It was always 1, and the layout profile's mark carries no version key: read `method`.
|
|
32
|
+
- **Five token types that serve only methods already deprecated** (`TokenConsumeParams`, `TokenConsumeResponse`, `AccessKeyResponse`, `RevokeSessionResponse`, `RevokeAllSessionsResponse`) are marked and leave in 5.0 with those methods.
|
|
33
|
+
|
|
8
34
|
## [4.176.0] - 2026-11-16
|
|
9
35
|
|
|
10
36
|
### Added
|
package/README.md
CHANGED
|
@@ -457,7 +457,7 @@ const heading = typeWord(world, 'character', { many: true }) ?? 'Characters';
|
|
|
457
457
|
const label = typeWord(world, el.type, { supertype: el.supertype }) ?? el.type;
|
|
458
458
|
```
|
|
459
459
|
|
|
460
|
-
The word is printed as written, never re-cased; folder names are never translated. The profile: [`profiles/names.md`](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/names.md) in the schema distribution, with its
|
|
460
|
+
The word is printed as written, never re-cased; folder names are never translated. The profile: [`profiles/names.md`](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/names.md) in the schema distribution, with its fixture, which is this function's test.
|
|
461
461
|
|
|
462
462
|
### Addresses
|
|
463
463
|
|
|
@@ -471,7 +471,7 @@ const r = parseOwLink(text); // { form, world, worldIsSlug, type, id, lens, mome
|
|
|
471
471
|
// a refusal throws OwAddressError: err.reason is the profile's name ('bad_id', 'uppercase', ...)
|
|
472
472
|
```
|
|
473
473
|
|
|
474
|
-
A field that holds an address is text: never fetch or resolve it on the server, and show one wording ("private or missing") for a world you cannot read and an element that is not there. `parseOwLink` reads one string whole; finding a link inside other text is yours. The profile: [`profiles/address.md`](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/address.md), with its
|
|
474
|
+
A field that holds an address is text: never fetch or resolve it on the server, and show one wording ("private or missing") for a world you cannot read and an element that is not there. `parseOwLink` reads one string whole; finding a link inside other text is yours. The profile: [`profiles/address.md`](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/address.md), with its fixture, which is these functions' test.
|
|
475
475
|
|
|
476
476
|
### Open with
|
|
477
477
|
|
package/SCHEMA.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# OnlyWorlds Schema Reference
|
|
2
2
|
|
|
3
|
-
**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.34.1-dist.
|
|
3
|
+
**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.34.1-dist.133** — canonical schema **00.34.01**, published 2026-11-16.
|
|
4
4
|
|
|
5
5
|
GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `python codegen/generate_types.py`).
|
|
6
6
|
Written for both humans and AI agents reading this package locally.
|
package/dist/index.d.ts
CHANGED
|
@@ -2352,6 +2352,8 @@ interface OwStrandWorld extends OwLensWorld {
|
|
|
2352
2352
|
/** A filled slot. */
|
|
2353
2353
|
interface OwStrandSlot {
|
|
2354
2354
|
id: string;
|
|
2355
|
+
/** The element's type: the slot's own (narrative, event, location, character; `now` a location). */
|
|
2356
|
+
type: 'narrative' | 'event' | 'location' | 'character';
|
|
2355
2357
|
name: string;
|
|
2356
2358
|
}
|
|
2357
2359
|
/** A world's strand as one reader sees it: five slots and whether then and now are one place. An empty slot is null. */
|
|
@@ -3198,6 +3200,8 @@ interface OwServedReadingAids extends OwReadingAids {
|
|
|
3198
3200
|
/** The Charter in `reading_aids`. */
|
|
3199
3201
|
interface OwReadingAidsCharter {
|
|
3200
3202
|
id: string;
|
|
3203
|
+
/** The Charter is a Law. */
|
|
3204
|
+
type: 'law';
|
|
3201
3205
|
name: string;
|
|
3202
3206
|
/** Its `x_checks_rules` (the checks profile) as stored; empty when it has none. */
|
|
3203
3207
|
rules: unknown[];
|
|
@@ -3207,11 +3211,15 @@ interface OwReadingAidsCharter {
|
|
|
3207
3211
|
/** The Guide in `reading_aids`. */
|
|
3208
3212
|
interface OwReadingAidsGuide {
|
|
3209
3213
|
id: string;
|
|
3214
|
+
/** The Guide is a Construct. */
|
|
3215
|
+
type: 'construct';
|
|
3210
3216
|
name: string;
|
|
3211
3217
|
}
|
|
3212
3218
|
/** One Domain in `reading_aids`. */
|
|
3213
3219
|
interface OwReadingAidsDomain {
|
|
3214
3220
|
id: string;
|
|
3221
|
+
/** A Domain is a Construct. */
|
|
3222
|
+
type: 'construct';
|
|
3215
3223
|
name: string;
|
|
3216
3224
|
/** Its description up to the first line break, trimmed; empty when it has none. */
|
|
3217
3225
|
sentence: string;
|
|
@@ -3610,9 +3618,17 @@ interface OwDraught {
|
|
|
3610
3618
|
element: OwElement;
|
|
3611
3619
|
} | null;
|
|
3612
3620
|
role?: OwDraughtItem[];
|
|
3613
|
-
/**
|
|
3621
|
+
/**
|
|
3622
|
+
* Her open work: Relations with supertype `Work item` and subtype `open` or `taken` that are for her, by name
|
|
3623
|
+
* (`actor` is her) or by a role she holds (`x_packet_for` names a Title whose `holders` name her). Each row adds
|
|
3624
|
+
* `packet`, the item's `x_packet_elements` (`[]` when it has none), and `by_role`, the ids of her Titles the item
|
|
3625
|
+
* names, each once, in the item's order (`[]` when none does). A row that reached her only through a Title has
|
|
3626
|
+
* `via` `['holders']`. Read as her (`mode: 'voice'`) a work item reaches her only through a field of its own
|
|
3627
|
+
* that names her: ask with `mode: 'act'` for what is hers by role.
|
|
3628
|
+
*/
|
|
3614
3629
|
work?: Array<OwDraughtItem & {
|
|
3615
3630
|
packet: Array<Record<string, unknown>>;
|
|
3631
|
+
by_role: string[];
|
|
3616
3632
|
}>;
|
|
3617
3633
|
style?: OwDraughtItem | null;
|
|
3618
3634
|
events?: OwDraughtItem[];
|
|
@@ -4270,7 +4286,7 @@ declare class OwApiError extends Error {
|
|
|
4270
4286
|
* page titled "Blocked", not the API's JSON envelope. Nothing was written. The host refuses text that holds a
|
|
4271
4287
|
* shell command such as `python -m`, `python -c`, `perl -e`, or `curl` or `wget` with an address right after
|
|
4272
4288
|
* a backtick, a semicolon or a pipe; such a command passes in a fenced code block whose first line names a
|
|
4273
|
-
* language, or
|
|
4289
|
+
* language, or with none of the three directly before it. `code` is null (it is no API code) and `detail` keeps the page.
|
|
4274
4290
|
*/
|
|
4275
4291
|
get isHostBlocked(): boolean;
|
|
4276
4292
|
/** 422s/400s name the offending param/field -- typos error loudly platform-wide. */
|
|
@@ -6760,7 +6776,10 @@ interface OwLayoutPoint {
|
|
|
6760
6776
|
/** What `layoutByKind` answers: one point per node, in the graph's node order, and the method that made them. */
|
|
6761
6777
|
interface OwLayoutByKind {
|
|
6762
6778
|
method: 'by-kind';
|
|
6763
|
-
/**
|
|
6779
|
+
/**
|
|
6780
|
+
* Always 1. A method's word is its version: a method that changes takes a new word, so read `method`, never this number.
|
|
6781
|
+
* @deprecated The layout profile's mark carries no version key. Leaves in 5.0.
|
|
6782
|
+
*/
|
|
6764
6783
|
version: 1;
|
|
6765
6784
|
points: OwLayoutPoint[];
|
|
6766
6785
|
}
|
|
@@ -6775,7 +6794,10 @@ interface OwLayoutAroundPoint {
|
|
|
6775
6794
|
/** What `layoutAround` answers: the focus and every element within the steps, in the graph's node order. */
|
|
6776
6795
|
interface OwLayoutAround {
|
|
6777
6796
|
method: 'around';
|
|
6778
|
-
/**
|
|
6797
|
+
/**
|
|
6798
|
+
* Always 1. A method's word is its version: a method that changes takes a new word, so read `method`, never this number.
|
|
6799
|
+
* @deprecated The layout profile's mark carries no version key. Leaves in 5.0.
|
|
6800
|
+
*/
|
|
6779
6801
|
version: 1;
|
|
6780
6802
|
points: OwLayoutAroundPoint[];
|
|
6781
6803
|
}
|
|
@@ -7544,7 +7566,7 @@ declare function renderElement<T extends OwLookupElement>(element: T, index: OwW
|
|
|
7544
7566
|
*
|
|
7545
7567
|
* const hits = lookupWorld(index, question).slice(0, 8); // what the screen lists
|
|
7546
7568
|
* const { context, kept, leftOut } = buildAskContext(hits, index);
|
|
7547
|
-
* const reply = await account.ask
|
|
7569
|
+
* const reply = await account.ai('ask', { world_id: worldId, question, context });
|
|
7548
7570
|
*
|
|
7549
7571
|
* It is a reader that hands a world on, so three published rules hold here, not only in
|
|
7550
7572
|
* the caller: an element marked proposed (the review profile, rules 1 and 4: an
|
|
@@ -8005,6 +8027,9 @@ interface TokenStatus {
|
|
|
8005
8027
|
}
|
|
8006
8028
|
/**
|
|
8007
8029
|
* Response from token consumption endpoint
|
|
8030
|
+
*
|
|
8031
|
+
* @deprecated Serves only a `TokenResource` method keel answers with 404 (production,
|
|
8032
|
+
* since 2026-10). Leaves in 5.0 with that method.
|
|
8008
8033
|
*/
|
|
8009
8034
|
interface TokenConsumeResponse {
|
|
8010
8035
|
/** Whether the consumption was successful */
|
|
@@ -8020,6 +8045,9 @@ interface TokenConsumeResponse {
|
|
|
8020
8045
|
}
|
|
8021
8046
|
/**
|
|
8022
8047
|
* Parameters for consuming tokens
|
|
8048
|
+
*
|
|
8049
|
+
* @deprecated Serves only a `TokenResource` method keel answers with 404 (production,
|
|
8050
|
+
* since 2026-10). Leaves in 5.0 with that method.
|
|
8023
8051
|
*/
|
|
8024
8052
|
interface TokenConsumeParams {
|
|
8025
8053
|
/** Number of tokens to consume (required) */
|
|
@@ -8033,6 +8061,9 @@ interface TokenConsumeParams {
|
|
|
8033
8061
|
}
|
|
8034
8062
|
/**
|
|
8035
8063
|
* Response from getting encrypted access key (advanced use case)
|
|
8064
|
+
*
|
|
8065
|
+
* @deprecated Serves only a `TokenResource` method keel answers with 404 (production,
|
|
8066
|
+
* since 2026-10). Leaves in 5.0 with that method.
|
|
8036
8067
|
*/
|
|
8037
8068
|
interface AccessKeyResponse {
|
|
8038
8069
|
/** Base64 encoded encrypted OpenAI key */
|
|
@@ -8067,6 +8098,9 @@ interface EncryptionInfo {
|
|
|
8067
8098
|
}
|
|
8068
8099
|
/**
|
|
8069
8100
|
* Response from session revocation
|
|
8101
|
+
*
|
|
8102
|
+
* @deprecated Serves only a `TokenResource` method keel answers with 404 (production,
|
|
8103
|
+
* since 2026-10). Leaves in 5.0 with that method.
|
|
8070
8104
|
*/
|
|
8071
8105
|
interface RevokeSessionResponse {
|
|
8072
8106
|
/** Whether revocation was successful */
|
|
@@ -8076,6 +8110,9 @@ interface RevokeSessionResponse {
|
|
|
8076
8110
|
}
|
|
8077
8111
|
/**
|
|
8078
8112
|
* Response from revoking all sessions
|
|
8113
|
+
*
|
|
8114
|
+
* @deprecated Serves only a `TokenResource` method keel answers with 404 (production,
|
|
8115
|
+
* since 2026-10). Leaves in 5.0 with that method.
|
|
8079
8116
|
*/
|
|
8080
8117
|
interface RevokeAllSessionsResponse {
|
|
8081
8118
|
/** Whether revocation was successful */
|
|
@@ -8207,8 +8244,8 @@ declare class TokenResource {
|
|
|
8207
8244
|
* Get encrypted OpenAI API key (advanced use case)
|
|
8208
8245
|
*
|
|
8209
8246
|
* @deprecated keel serves no access-key route (404 on production since
|
|
8210
|
-
* 2026-10). AI answers come from keel's own proxy: `OwV2Client.ask
|
|
8211
|
-
* `sort
|
|
8247
|
+
* 2026-10). AI answers come from keel's own proxy: `OwV2Client.ai('ask', ...)`
|
|
8248
|
+
* and `ai('sort', ...)`. Removed in 5.0.
|
|
8212
8249
|
*
|
|
8213
8250
|
* Requires minimum 100 tokens available. Creates a 1-hour session for tracking.
|
|
8214
8251
|
* Returns encrypted key that must be decrypted client-side using Fernet.
|
package/dist/index.js
CHANGED
|
@@ -129,7 +129,7 @@ var OwApiError = class extends Error {
|
|
|
129
129
|
* page titled "Blocked", not the API's JSON envelope. Nothing was written. The host refuses text that holds a
|
|
130
130
|
* shell command such as `python -m`, `python -c`, `perl -e`, or `curl` or `wget` with an address right after
|
|
131
131
|
* a backtick, a semicolon or a pipe; such a command passes in a fenced code block whose first line names a
|
|
132
|
-
* language, or
|
|
132
|
+
* language, or with none of the three directly before it. `code` is null (it is no API code) and `detail` keeps the page.
|
|
133
133
|
*/
|
|
134
134
|
get isHostBlocked() {
|
|
135
135
|
return isHostBlockedPage(this.status, this.detail);
|
|
@@ -530,7 +530,7 @@ var OwSignInError = class extends Error {
|
|
|
530
530
|
function isHostBlockedPage(status, body) {
|
|
531
531
|
return status === 403 && typeof body === "string" && /<title[^>]*>\s*Blocked\s*<\/title>/i.test(body);
|
|
532
532
|
}
|
|
533
|
-
var HOST_BLOCKED_MESSAGE = 'The host in front of onlyworlds.com refused this request before the API saw it (a 403 page titled "Blocked"), and nothing was written. It refuses text that holds a shell command such as python -m, python -c, perl -e, or curl or wget with an address, right after a backtick, a semicolon or a pipe. Put such a command in a fenced code block whose first line names a language, or write it
|
|
533
|
+
var HOST_BLOCKED_MESSAGE = 'The host in front of onlyworlds.com refused this request before the API saw it (a 403 page titled "Blocked"), and nothing was written. It refuses text that holds a shell command such as python -m, python -c, perl -e, or curl or wget with an address, right after a backtick, a semicolon or a pipe. Put such a command in a fenced code block whose first line names a language, or write it with none of the three directly before it.';
|
|
534
534
|
function parseErrorEnvelope(status, body, retryAfter = null) {
|
|
535
535
|
if (isHostBlockedPage(status, body)) return new OwApiError(status, null, HOST_BLOCKED_MESSAGE, null, body, null, null, retryAfter);
|
|
536
536
|
const env = body && typeof body === "object" ? body : {};
|
|
@@ -3734,7 +3734,7 @@ function hubsOf(id, r) {
|
|
|
3734
3734
|
const v = body[field];
|
|
3735
3735
|
const target = schema[field]?.target ?? "";
|
|
3736
3736
|
for (const t of many ? Array.isArray(v) ? v : [] : [v]) {
|
|
3737
|
-
if (typeof t !== "string" || t === "" || r.proposed.has(t) || seen.has(`${target}/${t}`)) continue;
|
|
3737
|
+
if (typeof t !== "string" || t === "" || r.proposed.has(t) || !r.view.has(t) || r.typeOf.get(t) !== target || seen.has(`${target}/${t}`)) continue;
|
|
3738
3738
|
seen.add(`${target}/${t}`);
|
|
3739
3739
|
out.push({ type: target, id: t });
|
|
3740
3740
|
}
|
|
@@ -3758,6 +3758,7 @@ function charterOf(world, reader) {
|
|
|
3758
3758
|
const skill = idsIn(el.description).filter((id) => r.view.has(id) && r.typeOf.get(id) === "object").slice(0, SKILL_MAX);
|
|
3759
3759
|
out.charter = {
|
|
3760
3760
|
id: law,
|
|
3761
|
+
type: "law",
|
|
3761
3762
|
name: typeof el.name === "string" ? el.name : "",
|
|
3762
3763
|
rules: Array.isArray(rules) ? JSON.parse(JSON.stringify(rules)) : [],
|
|
3763
3764
|
skill
|
|
@@ -3766,7 +3767,7 @@ function charterOf(world, reader) {
|
|
|
3766
3767
|
const guide = newest(seen("construct/guide"), r);
|
|
3767
3768
|
if (guide !== null) {
|
|
3768
3769
|
const el = r.byId.get(guide);
|
|
3769
|
-
out.guide = { id: guide, name: typeof el.name === "string" ? el.name : "" };
|
|
3770
|
+
out.guide = { id: guide, type: "construct", name: typeof el.name === "string" ? el.name : "" };
|
|
3770
3771
|
}
|
|
3771
3772
|
const domains = new Set(seen("construct/domain"));
|
|
3772
3773
|
const order = [];
|
|
@@ -3781,6 +3782,7 @@ function charterOf(world, reader) {
|
|
|
3781
3782
|
const rest = [...domains].filter((id) => !order.includes(id)).sort((a, b) => byCodePoint(fold(nameOf(a)), fold(nameOf(b))) || byCodePoint(a, b));
|
|
3782
3783
|
out.domains = [...order, ...rest].map((id) => ({
|
|
3783
3784
|
id,
|
|
3785
|
+
type: "construct",
|
|
3784
3786
|
name: nameOf(id),
|
|
3785
3787
|
sentence: firstLine(r.body(id).description),
|
|
3786
3788
|
hubs: hubsOf(id, r)
|
|
@@ -3820,7 +3822,7 @@ function strandOf(world, reader) {
|
|
|
3820
3822
|
const seen = (id, type) => typeof id === "string" && r.view.has(id) && r.typeOf.get(id) === type;
|
|
3821
3823
|
const slot = (id) => {
|
|
3822
3824
|
const name = r.body(id).name;
|
|
3823
|
-
return { id, name: typeof name === "string" ? name : "" };
|
|
3825
|
+
return { id, type: r.typeOf.get(id), name: typeof name === "string" ? name : "" };
|
|
3824
3826
|
};
|
|
3825
3827
|
const listed = (holder, field, id) => {
|
|
3826
3828
|
const v = r.body(holder)[field];
|
|
@@ -9325,8 +9327,8 @@ var TokenResource = class {
|
|
|
9325
9327
|
* Get encrypted OpenAI API key (advanced use case)
|
|
9326
9328
|
*
|
|
9327
9329
|
* @deprecated keel serves no access-key route (404 on production since
|
|
9328
|
-
* 2026-10). AI answers come from keel's own proxy: `OwV2Client.ask
|
|
9329
|
-
* `sort
|
|
9330
|
+
* 2026-10). AI answers come from keel's own proxy: `OwV2Client.ai('ask', ...)`
|
|
9331
|
+
* and `ai('sort', ...)`. Removed in 5.0.
|
|
9330
9332
|
*
|
|
9331
9333
|
* Requires minimum 100 tokens available. Creates a 1-hour session for tracking.
|
|
9332
9334
|
* Returns encrypted key that must be decrypted client-side using Fernet.
|