castle-web-cli 0.4.227 → 0.4.229

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.
Files changed (42) hide show
  1. package/dist/agent-prompts.d.ts +9 -3
  2. package/dist/agent-prompts.js +140 -48
  3. package/dist/agent.js +127 -14
  4. package/dist/api.d.ts +37 -0
  5. package/dist/api.js +29 -0
  6. package/dist/castle-host/host.d.ts +6 -0
  7. package/dist/castle-host/host.js +42 -3
  8. package/dist/castleJson.d.ts +15 -0
  9. package/dist/castleJson.js +136 -3
  10. package/dist/cloudGit.d.ts +27 -1
  11. package/dist/cloudGit.js +359 -24
  12. package/dist/cloudGitServe.js +9 -5
  13. package/dist/gitCollaborators.d.ts +16 -0
  14. package/dist/gitCollaborators.js +42 -0
  15. package/dist/gitIncoming.d.ts +17 -0
  16. package/dist/gitIncoming.js +113 -0
  17. package/dist/gitRemote.js +2 -2
  18. package/dist/imports.js +4 -2
  19. package/dist/index.js +5 -0
  20. package/dist/init.js +1 -1
  21. package/dist/native/playtest-browser.js +13 -1
  22. package/dist/platformDoc.js +1 -1
  23. package/dist/save-deck.js +3 -0
  24. package/dist/serve.js +17 -0
  25. package/dist/shell/assets/index-Cf61cNfT.css +1 -0
  26. package/dist/shell/assets/{index-D006JHww.js → index-D2tWM896.js} +71 -71
  27. package/dist/shell/index.html +2 -2
  28. package/dist/sourceLineage.d.ts +42 -0
  29. package/dist/sourceLineage.js +380 -0
  30. package/dist/webSourceSync.d.ts +9 -0
  31. package/dist/webSourceSync.js +24 -9
  32. package/kits/base/castle.json +1 -1
  33. package/kits/base/sdk/README.md +81 -0
  34. package/kits/base/sdk/castle.d.ts +1 -1
  35. package/kits/base/sdk/commands.d.ts +6 -0
  36. package/kits/base/sdk/multiplayer.d.ts +44 -6
  37. package/kits/base/sdk/multiplayer.js +62 -1
  38. package/kits/base/sdk/server/platformHandle.d.ts +9 -1
  39. package/kits/base/sdk/server/wrapper.d.ts +111 -4
  40. package/kits/base/sdk/server/wrapper.js +650 -24
  41. package/package.json +10 -2
  42. package/dist/shell/assets/index-BxDYy_-C.css +0 -1
@@ -1,8 +1,9 @@
1
- import type { MultiplayerDestinationAudience, MultiplayerSoloReason } from "./commands";
1
+ import type { MultiplayerDestinationAudience, MultiplayerJoinHint, MultiplayerSoloReason } from "./commands";
2
2
  import { CastleError } from "./errors";
3
3
  import type { Json } from "./types";
4
4
  import { type MultiplayerPlayer, type MultiplayerCharacterDisclosure, type MultiplayerCharacterTurnStatus } from "./multiplayerProtocol";
5
5
  import { type MultiplayerVoice } from "./multiplayerVoice";
6
+ export type { MultiplayerJoinHint } from "./commands";
6
7
  export type MultiplayerJoinOptions = {
7
8
  mode: "named";
8
9
  key: string;
@@ -78,7 +79,43 @@ export type MultiplayerWorldCharacterCommand = {
78
79
  type: "record_event";
79
80
  eventTypeId: string;
80
81
  data?: Json;
82
+ } | MultiplayerEvaluateBeatsCommand | MultiplayerCompleteScheduledBeatCommand;
83
+ export type MultiplayerStoryOpportunity = {
84
+ type: "approach" | "room_entry" | "world_action";
85
+ id: string;
81
86
  };
87
+ export interface MultiplayerEvaluateBeatsCommand {
88
+ type: "evaluate_beats";
89
+ opportunityId: string;
90
+ opportunity: MultiplayerStoryOpportunity;
91
+ presentCharacterIds: string[];
92
+ }
93
+ export interface MultiplayerCompleteScheduledBeatCommand {
94
+ type: "complete_scheduled_beat";
95
+ deliveryId: string;
96
+ outcomeId: string;
97
+ }
98
+ export interface MultiplayerScheduledBeatSelection {
99
+ deliveryId: string;
100
+ beatId: string;
101
+ characterId: string;
102
+ openingText: string;
103
+ }
104
+ export interface MultiplayerScheduledBeatReason {
105
+ beatId: string;
106
+ status: "selected" | "expired" | "eligible" | "blocked";
107
+ reasonCodes: string[];
108
+ }
109
+ export interface MultiplayerEvaluateBeatsResult {
110
+ selection: MultiplayerScheduledBeatSelection | null;
111
+ reasons?: MultiplayerScheduledBeatReason[];
112
+ }
113
+ export interface MultiplayerCompleteScheduledBeatResult {
114
+ deliveryId: string;
115
+ outcomeId: string;
116
+ completed: true;
117
+ }
118
+ export type MultiplayerWorldCharacterCommandResultValue<Command extends MultiplayerWorldCharacterCommand> = Command extends MultiplayerEvaluateBeatsCommand ? MultiplayerEvaluateBeatsResult : Command extends MultiplayerCompleteScheduledBeatCommand ? MultiplayerCompleteScheduledBeatResult : Json;
82
119
  export type MultiplayerWorldCharacterQuery = {
83
120
  type: "inspect";
84
121
  } | {
@@ -105,11 +142,11 @@ export interface MultiplayerWorldCharacterInspectResult<Gameplay = unknown, Shar
105
142
  }>;
106
143
  sources: Source[];
107
144
  }
108
- export interface MultiplayerWorldCharacterCommandResult {
145
+ export interface MultiplayerWorldCharacterCommandResult<Result = unknown> {
109
146
  operationId: string;
110
147
  status: "applied" | "ineligible";
111
148
  replayed: boolean;
112
- result: unknown;
149
+ result: Result;
113
150
  worldRevision: string;
114
151
  }
115
152
  export interface MultiplayerConnection {
@@ -128,11 +165,11 @@ export interface MultiplayerConnection {
128
165
  requestCharacterTurn(request: MultiplayerCharacterTurnRequest): Promise<MultiplayerCharacterTurnAdmission>;
129
166
  /** Recovers the durable status of a prior operation after reconnecting. */
130
167
  getCharacterTurnStatus(operationId: string): Promise<MultiplayerCharacterTurnStatusResult>;
131
- requestCharacterCommand(request: {
168
+ requestCharacterCommand<Command extends MultiplayerWorldCharacterCommand>(request: {
132
169
  requestId: string;
133
170
  operationId: string;
134
- command: MultiplayerWorldCharacterCommand;
135
- }): Promise<MultiplayerWorldCharacterCommandResult>;
171
+ command: Command;
172
+ }): Promise<MultiplayerWorldCharacterCommandResult<MultiplayerWorldCharacterCommandResultValue<Command>>>;
136
173
  readCharacters(request: {
137
174
  requestId: string;
138
175
  query: {
@@ -153,6 +190,7 @@ export interface MultiplayerConnection {
153
190
  }
154
191
  export interface CastleMultiplayerApi {
155
192
  join(options: MultiplayerJoinOptions): Promise<MultiplayerConnection>;
193
+ joinHint(): Promise<MultiplayerJoinHint | null>;
156
194
  joinDestination(options: MultiplayerDestinationOptions): Promise<MultiplayerDestinationJoinResult>;
157
195
  }
158
196
  export declare const Multiplayer: CastleMultiplayerApi;
@@ -18,7 +18,17 @@ let nextCharacterStatusRequestId = 1;
18
18
  let activeConnection = null;
19
19
  let latestJoinAttempt = 0;
20
20
  let pendingDestinationJoin = null;
21
- export const Multiplayer = { join, joinDestination };
21
+ export const Multiplayer = { join, joinHint, joinDestination };
22
+ async function joinHint() {
23
+ try {
24
+ return await hostRequest("multiplayer.getJoinHint", {});
25
+ }
26
+ catch (error) {
27
+ if (error instanceof CastleError && error.code === "UNKNOWN_COMMAND")
28
+ return null;
29
+ throw error;
30
+ }
31
+ }
22
32
  async function join(options) {
23
33
  const params = joinParams(options);
24
34
  latestJoinAttempt += 1;
@@ -771,6 +781,41 @@ function normalizeWorldCharacterCommandRequest(request) {
771
781
  },
772
782
  };
773
783
  }
784
+ if (command.type === "evaluate_beats") {
785
+ const opportunity = command.opportunity;
786
+ if (!opportunity || typeof opportunity !== "object") {
787
+ throw characterError("INVALID_ARGUMENT", "command.opportunity must be an opportunity object.");
788
+ }
789
+ if (opportunity.type !== "approach" &&
790
+ opportunity.type !== "room_entry" &&
791
+ opportunity.type !== "world_action") {
792
+ throw characterError("INVALID_ARGUMENT", "command.opportunity.type is invalid.");
793
+ }
794
+ return {
795
+ requestId,
796
+ operationId,
797
+ command: {
798
+ type: "evaluate_beats",
799
+ opportunityId: boundedCharacterSafeKey(command.opportunityId, "command.opportunityId"),
800
+ opportunity: {
801
+ type: opportunity.type,
802
+ id: boundedCharacterSafeKey(opportunity.id, "command.opportunity.id"),
803
+ },
804
+ presentCharacterIds: boundedCharacterSafeKeys(command.presentCharacterIds, 16, "command.presentCharacterIds"),
805
+ },
806
+ };
807
+ }
808
+ if (command.type === "complete_scheduled_beat") {
809
+ return {
810
+ requestId,
811
+ operationId,
812
+ command: {
813
+ type: "complete_scheduled_beat",
814
+ deliveryId: boundedCharacterSafeKey(command.deliveryId, "command.deliveryId"),
815
+ outcomeId: boundedCharacterSafeKey(command.outcomeId, "command.outcomeId"),
816
+ },
817
+ };
818
+ }
774
819
  throw characterError("INVALID_ARGUMENT", "Unknown shared character command type.");
775
820
  }
776
821
  function normalizeWorldCharacterReadRequest(request) {
@@ -821,6 +866,22 @@ function boundedCharacterIds(value, maxItems, field, maxCharacters = 128) {
821
866
  }
822
867
  return ids;
823
868
  }
869
+ function boundedCharacterSafeKeys(value, maxItems, field) {
870
+ if (!Array.isArray(value) || value.length > maxItems) {
871
+ throw characterError("INVALID_ARGUMENT", `${field} may contain at most ${maxItems} ids.`);
872
+ }
873
+ const ids = value.map((item) => boundedCharacterSafeKey(item, field));
874
+ if (new Set(ids).size !== ids.length) {
875
+ throw characterError("INVALID_ARGUMENT", `${field} may not contain duplicate ids.`);
876
+ }
877
+ return ids;
878
+ }
879
+ function boundedCharacterSafeKey(value, field) {
880
+ if (typeof value !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(value)) {
881
+ throw characterError("INVALID_ARGUMENT", `${field} must be a safe key of at most 64 characters.`);
882
+ }
883
+ return value;
884
+ }
824
885
  function boundedCharacterText(value, maxBytes, field, maxCharacters = maxBytes) {
825
886
  if (typeof value !== "string" ||
826
887
  value.length === 0 ||
@@ -1,4 +1,5 @@
1
1
  import type { Json } from "../types";
2
+ import type { MultiplayerWorldCharacterCommand } from "../multiplayer";
2
3
  export type MultiplayerSessionMode = "named" | "party" | "public";
3
4
  export interface PlayerIdentity {
4
5
  userId: string;
@@ -21,6 +22,11 @@ export interface PlatformWorldCheckpoint {
21
22
  export interface PlatformWorldSnapshot {
22
23
  revision: string;
23
24
  checkpoint: PlatformWorldCheckpoint | null;
25
+ /** Selected destination timing policy, stamped by hosts that support catch-up. */
26
+ worldTime?: PlatformWorldTimeConfig;
27
+ }
28
+ export interface PlatformWorldTimeConfig {
29
+ advance: "wallClock";
24
30
  }
25
31
  export interface PlatformHandle {
26
32
  send(connId: string, text: string): void;
@@ -43,6 +49,8 @@ export interface PlatformHandle {
43
49
  *
44
50
  * Optional because a published bundle may run on a host that predates storage.
45
51
  * Rejects with an Error whose `code` is the platform's error code.
52
+ * Persistent-world journal and participant operations share this broker; the
53
+ * host stamps their world binding and participant identity.
46
54
  */
47
55
  storage?(op: string, argsJson: string): Promise<string>;
48
56
  /** False when the host cannot broker storage, so a call can fail at once. */
@@ -65,7 +73,7 @@ export interface PlatformWorldCharacterCommand {
65
73
  speaker: PlayerIdentity & {
66
74
  playerId: string;
67
75
  };
68
- command: unknown;
76
+ command: MultiplayerWorldCharacterCommand;
69
77
  }
70
78
  export interface PlatformWorldCharacterRead {
71
79
  grantId: string;
@@ -1,10 +1,12 @@
1
1
  import type { MultiplayerSessionMode, PlatformHandle, PlayerIdentity } from "./platformHandle";
2
2
  import type { Json } from "../types";
3
+ import type { MultiplayerWorldCharacterCommand, MultiplayerWorldCharacterCommandResult, MultiplayerWorldCharacterCommandResultValue } from "../multiplayer";
3
4
  import { type ServerStorage } from "./storage";
4
- export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlatformWorldCheckpoint, PlatformWorldSnapshot, PlayerIdentity, } from "./platformHandle";
5
+ export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlatformWorldCheckpoint, PlatformWorldSnapshot, PlatformWorldTimeConfig, PlayerIdentity, } from "./platformHandle";
5
6
  export type { CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, } from "./storage";
6
7
  export interface MultiplayerServerPlayer extends PlayerIdentity {
7
8
  playerId: string;
9
+ readonly participantId: string;
8
10
  }
9
11
  export interface MultiplayerBroadcastOptions {
10
12
  except?: string;
@@ -52,8 +54,106 @@ export interface MultiplayerServerWorld {
52
54
  read(): Promise<MultiplayerWorldSnapshot>;
53
55
  /** Commits exactly against expectedRevision; conflicts never partially write. */
54
56
  commit(input: MultiplayerWorldCommitInput): Promise<MultiplayerWorldCommitReceipt>;
57
+ catchUp(options: MultiplayerWorldCatchUpOptions): Promise<MultiplayerWorldCatchUpResult>;
58
+ readonly journal: MultiplayerServerWorldJournal;
59
+ readonly participants: MultiplayerServerWorldParticipants;
60
+ readonly notifications: MultiplayerServerWorldNotifications;
55
61
  readonly characters: MultiplayerServerWorldCharacters;
56
62
  }
63
+ export interface MultiplayerWorldCatchUpOptions {
64
+ key?: string;
65
+ maxElapsedMs?: number;
66
+ apply(input: {
67
+ elapsedMs: number;
68
+ now: number;
69
+ checkpoint: MultiplayerWorldCheckpoint | null;
70
+ }): MultiplayerWorldCheckpoint | Promise<MultiplayerWorldCheckpoint>;
71
+ }
72
+ export interface MultiplayerWorldCatchUpResult {
73
+ applied: boolean;
74
+ elapsedMs: number;
75
+ revision: string;
76
+ }
77
+ export interface MultiplayerWorldJournalAppendInput {
78
+ operationId: string;
79
+ entries: readonly MultiplayerWorldJournalAppendEntry[];
80
+ }
81
+ export interface MultiplayerWorldJournalAppendEntry {
82
+ kind: string;
83
+ disclosure: "world" | "participants";
84
+ participantIds?: readonly string[];
85
+ data?: Json;
86
+ }
87
+ export interface MultiplayerWorldJournalAppendReceipt {
88
+ operationId: string;
89
+ replayed: boolean;
90
+ firstSeq: string;
91
+ lastSeq: string;
92
+ }
93
+ export interface MultiplayerWorldJournalReadOptions {
94
+ afterSeq?: string;
95
+ limit?: number;
96
+ participantId?: string;
97
+ }
98
+ export interface MultiplayerWorldJournalEntry {
99
+ seq: string;
100
+ kind: string;
101
+ disclosure: "world" | "participants";
102
+ participantIds: readonly string[];
103
+ data: Json;
104
+ createdAt: string;
105
+ }
106
+ export interface MultiplayerWorldJournalReadResult {
107
+ entries: readonly MultiplayerWorldJournalEntry[];
108
+ nextSeq: string;
109
+ oldestRetainedSeq: string | null;
110
+ }
111
+ export interface MultiplayerServerWorldJournal {
112
+ append(input: MultiplayerWorldJournalAppendInput): Promise<MultiplayerWorldJournalAppendReceipt>;
113
+ read(options?: MultiplayerWorldJournalReadOptions): Promise<MultiplayerWorldJournalReadResult>;
114
+ }
115
+ export interface MultiplayerWorldParticipantsReadOptions {
116
+ participantIds?: readonly string[];
117
+ limit?: number;
118
+ }
119
+ export interface MultiplayerWorldParticipant {
120
+ participantId: string;
121
+ firstSeenAt: string;
122
+ lastSeenAt: string;
123
+ lastLeftAt: string | null;
124
+ visitCount: number;
125
+ }
126
+ export interface MultiplayerWorldParticipantsReadResult {
127
+ participants: readonly MultiplayerWorldParticipant[];
128
+ }
129
+ export interface MultiplayerServerWorldParticipants {
130
+ read(options?: MultiplayerWorldParticipantsReadOptions): Promise<MultiplayerWorldParticipantsReadResult>;
131
+ }
132
+ export interface MultiplayerWorldNotificationNotifyInput {
133
+ key: string;
134
+ participantIds: readonly string[];
135
+ templateId: string;
136
+ slots?: Readonly<Record<string, string>>;
137
+ at?: string;
138
+ expiresAt?: string;
139
+ }
140
+ export interface MultiplayerWorldNotificationNotifyResult {
141
+ key: string;
142
+ accepted: number;
143
+ skipped: number;
144
+ limited: number;
145
+ }
146
+ export interface MultiplayerWorldNotificationCancelInput {
147
+ key: string;
148
+ participantIds?: readonly string[];
149
+ }
150
+ export interface MultiplayerWorldNotificationCancelResult {
151
+ cancelled: number;
152
+ }
153
+ export interface MultiplayerServerWorldNotifications {
154
+ notify(input: MultiplayerWorldNotificationNotifyInput): Promise<MultiplayerWorldNotificationNotifyResult>;
155
+ cancel(input: MultiplayerWorldNotificationCancelInput): Promise<MultiplayerWorldNotificationCancelResult>;
156
+ }
57
157
  export interface MultiplayerServerWorldCharacters {
58
158
  create(input: MultiplayerWorldRuntimeCharacterCreateInput): Promise<MultiplayerWorldRuntimeCharacterCreateReceipt>;
59
159
  list(): Promise<MultiplayerWorldCharacterList>;
@@ -97,14 +197,21 @@ export interface MultiplayerWorldRuntimeCharacterCreateReceipt {
97
197
  export interface MultiplayerWorldCharacterList {
98
198
  characters: readonly MultiplayerWorldCharacterSummary[];
99
199
  }
100
- export interface MultiplayerWorldCharacterCommandRequest {
200
+ interface MultiplayerWorldCharacterCommandRequestFor<Command extends MultiplayerWorldCharacterCommand> {
201
+ /** Command discriminator mirrored at the request level for TypeScript narrowing. */
202
+ readonly type: Command["type"];
101
203
  readonly requestId: string;
102
204
  readonly operationId: string;
103
205
  readonly speaker: MultiplayerServerPlayer;
104
- readonly command: Readonly<Record<string, unknown>>;
105
- apply(): Promise<unknown>;
206
+ readonly command: Readonly<Command>;
207
+ apply(): Promise<MultiplayerWorldCharacterCommandResult<MultiplayerWorldCharacterCommandResultValue<Command>>>;
106
208
  reject(code?: string): void;
107
209
  }
210
+ export type MultiplayerWorldCharacterCommandRequest = {
211
+ [Type in MultiplayerWorldCharacterCommand["type"]]: MultiplayerWorldCharacterCommandRequestFor<Extract<MultiplayerWorldCharacterCommand, {
212
+ type: Type;
213
+ }>>;
214
+ }[MultiplayerWorldCharacterCommand["type"]];
108
215
  export interface MultiplayerWorldCharacterReadRequest {
109
216
  readonly requestId: string;
110
217
  readonly speaker: MultiplayerServerPlayer;